update README
This commit is contained in:
nrslib
parent
748f5afb29
commit
4e7c3d0afb
204
CLAUDE.md
204
CLAUDE.md
@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Project Overview
|
||||
|
||||
TAKT (Task Agent Koordination Tool) is a multi-agent orchestration system for Claude Code. It enables YAML-based workflow definitions that coordinate multiple AI agents through state machine transitions.
|
||||
TAKT (Task Agent Koordination Tool) is a multi-agent orchestration system for Claude Code. It enables YAML-based workflow definitions that coordinate multiple AI agents through state machine transitions with rule-based routing.
|
||||
|
||||
## Development Commands
|
||||
|
||||
@ -25,35 +25,75 @@ TAKT (Task Agent Koordination Tool) is a multi-agent orchestration system for Cl
|
||||
| `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (resident process) |
|
||||
| `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) |
|
||||
| `takt /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) |
|
||||
| `takt /switch` | | Switch workflow interactively |
|
||||
| `takt /switch` | `/sw` | Switch workflow interactively |
|
||||
| `takt /clear` | | Clear agent conversation sessions (reset state) |
|
||||
| `takt /eject` | | Copy builtin workflow/agents to `~/.takt/` for customization |
|
||||
| `takt /refresh-builtin` | | Update builtin resources from `resources/` to `~/.takt/` |
|
||||
| `takt /help` | | Show help message |
|
||||
| `takt /config` | | Display current configuration |
|
||||
|
||||
GitHub issue references: `takt #6` fetches issue #6 and executes it as a task.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Flow
|
||||
|
||||
```
|
||||
CLI (cli.ts)
|
||||
→ Slash commands (/run-tasks, /watch, /add-task, /list-tasks, /switch, /clear, /refresh-builtin, /help, /config)
|
||||
→ or executeTask()
|
||||
→ Slash commands or executeTask()
|
||||
→ WorkflowEngine (workflow/engine.ts)
|
||||
→ runAgent() (agents/runner.ts)
|
||||
→ callClaude() (claude/client.ts)
|
||||
→ executeClaudeCli() (claude/process.ts)
|
||||
→ ClaudeProcess (claude-agent-sdk)
|
||||
→ Per step: 3-phase execution
|
||||
Phase 1: runAgent() → main work
|
||||
Phase 2: runReportPhase() → report output (if step.report defined)
|
||||
Phase 3: runStatusJudgmentPhase() → status tag output (if tag-based rules)
|
||||
→ detectMatchedRule() → rule evaluation → determineNextStep()
|
||||
→ Parallel steps: Promise.all() for sub-steps, aggregate evaluation
|
||||
```
|
||||
|
||||
### Three-Phase Step Execution
|
||||
|
||||
Each step executes in up to 3 phases (session is resumed across phases):
|
||||
|
||||
| Phase | Purpose | Tools | When |
|
||||
|-------|---------|-------|------|
|
||||
| Phase 1 | Main work (coding, review, etc.) | Step's allowed_tools (Write excluded if report defined) | Always |
|
||||
| Phase 2 | Report output | Write only | When `step.report` is defined |
|
||||
| Phase 3 | Status judgment | None (judgment only) | When step has tag-based rules |
|
||||
|
||||
Phase 2/3 are implemented in `src/workflow/phase-runner.ts`. The session is resumed so the agent retains context from Phase 1.
|
||||
|
||||
### Rule Evaluation (5-Stage Fallback)
|
||||
|
||||
After step execution, rules are evaluated to determine the next step. Evaluation order (first match wins):
|
||||
|
||||
1. **Aggregate** (`all()`/`any()`) - For parallel parent steps
|
||||
2. **Phase 3 tag** - `[STEP:N]` tag from status judgment output
|
||||
3. **Phase 1 tag** - `[STEP:N]` tag from main execution output (fallback)
|
||||
4. **AI judge (ai() only)** - AI evaluates `ai("condition text")` rules
|
||||
5. **AI judge fallback** - AI evaluates ALL conditions as final resort
|
||||
|
||||
Implemented in `src/workflow/rule-evaluator.ts`. The matched method is tracked as `RuleMatchMethod` type.
|
||||
|
||||
### Key Components
|
||||
|
||||
**WorkflowEngine** (`src/workflow/engine.ts`)
|
||||
- State machine that orchestrates agent execution via EventEmitter
|
||||
- Manages step transitions based on agent response status
|
||||
- Manages step transitions based on rule evaluation results
|
||||
- Emits events: `step:start`, `step:complete`, `step:blocked`, `step:loop_detected`, `workflow:complete`, `workflow:abort`, `iteration:limit`
|
||||
- Supports loop detection (`LoopDetector`) and iteration limits
|
||||
- Maintains agent sessions per step for conversation continuity
|
||||
- Parallel step execution via `runParallelStep()` with `Promise.all()`
|
||||
|
||||
**Instruction Builder** (`src/workflow/instruction-builder.ts`)
|
||||
- Auto-injects standard sections into every instruction (no need for `{task}` or `{previous_response}` placeholders in templates):
|
||||
1. Execution context (working dir, edit permission rules)
|
||||
2. Workflow context (iteration counts, report dir)
|
||||
3. User request (`{task}` — auto-injected unless placeholder present)
|
||||
4. Previous response (auto-injected if `pass_previous_response: true`)
|
||||
5. User inputs (auto-injected unless `{user_inputs}` placeholder present)
|
||||
6. `instruction_template` content
|
||||
7. Status output rules (auto-injected for tag-based rules)
|
||||
- Localized for `en` and `ja`
|
||||
|
||||
**Agent Runner** (`src/agents/runner.ts`)
|
||||
- Resolves agent specs (name or path) to agent configurations
|
||||
@ -63,17 +103,16 @@ CLI (cli.ts)
|
||||
- `supervisor`: Read/Glob/Grep/Bash/WebSearch/WebFetch
|
||||
- `planner`: Read/Glob/Grep/Bash/WebSearch/WebFetch
|
||||
- Custom agents via `.takt/agents.yaml` or prompt files (.md)
|
||||
- Supports Claude Code agents (`claudeAgent`) and skills (`claudeSkill`)
|
||||
|
||||
**Claude Integration** (`src/claude/`)
|
||||
- `client.ts` - High-level API: `callClaude()`, `callClaudeCustom()`, `callClaudeAgent()`, `callClaudeSkill()`, status detection via regex patterns
|
||||
- `process.ts` - SDK wrapper with `ClaudeProcess` class, re-exports query management
|
||||
- `client.ts` - High-level API: `callClaude()`, `callClaudeCustom()`, `callClaudeAgent()`, `callClaudeSkill()`
|
||||
- `process.ts` - SDK wrapper with `ClaudeProcess` class
|
||||
- `executor.ts` - Query execution using `@anthropic-ai/claude-agent-sdk`
|
||||
- `query-manager.ts` - Concurrent query tracking with query IDs
|
||||
|
||||
**Configuration** (`src/config/`)
|
||||
- `loader.ts` - Custom agent loading from `.takt/agents.yaml`
|
||||
- `workflowLoader.ts` - YAML workflow parsing with Zod validation (loads from `~/.takt/workflows/` only)
|
||||
- `workflowLoader.ts` - YAML workflow parsing with Zod validation; resolves user workflows (`~/.takt/workflows/`) with builtin fallback (`resources/global/{lang}/workflows/`)
|
||||
- `agentLoader.ts` - Agent prompt file loading
|
||||
- `paths.ts` - Directory structure (`.takt/`, `~/.takt/`), session management
|
||||
|
||||
@ -82,74 +121,123 @@ CLI (cli.ts)
|
||||
- `watcher.ts` - TaskWatcher class for polling and auto-executing tasks (used by `/watch`)
|
||||
- `index.ts` - Task operations (getNextTask, completeTask, addTask)
|
||||
|
||||
**GitHub Integration** (`src/github/issue.ts`)
|
||||
- Fetches issues via `gh` CLI, formats as task text with title/body/labels/comments
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. User provides task or slash command → CLI
|
||||
2. CLI loads workflow from `~/.takt/workflows/{name}.yaml`
|
||||
3. WorkflowEngine starts at `initialStep`
|
||||
4. Each step: `buildInstruction()` → `runStep()` → `runAgent()` → `callClaude()` → detect status → `determineNextStep()`
|
||||
5. Status patterns (regex in `statusPatterns`) determine next step via `transitions`
|
||||
1. User provides task (text or `#N` issue reference) or slash command → CLI
|
||||
2. CLI loads workflow: user `~/.takt/workflows/` → builtin `resources/global/{lang}/workflows/` fallback
|
||||
3. WorkflowEngine starts at `initial_step`
|
||||
4. Each step: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()`
|
||||
5. Rule evaluation determines next step name
|
||||
6. Special transitions: `COMPLETE` ends workflow successfully, `ABORT` ends with failure
|
||||
|
||||
### Status Detection
|
||||
|
||||
Agents output status markers (e.g., `[CODER:DONE]`) that are matched against `GENERIC_STATUS_PATTERNS` in `src/models/schemas.ts`. Common statuses: `done`, `blocked`, `approved`, `rejected`, `improve`, `in_progress`, `interrupted`.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
~/.takt/ # Global user config (created on first run)
|
||||
config.yaml # Trusted dirs, default workflow, log level, language
|
||||
workflows/ # Workflow YAML files (required location)
|
||||
agents/ # Agent prompt files (.md)
|
||||
workflows/ # User workflow YAML files (override builtins)
|
||||
agents/ # User agent prompt files (.md)
|
||||
|
||||
.takt/ # Project-level config
|
||||
agents.yaml # Custom agent definitions
|
||||
tasks/ # Task files for /run-tasks
|
||||
reports/ # Execution reports (auto-generated)
|
||||
logs/ # Session logs (gitignored)
|
||||
logs/ # Session logs in NDJSON format (gitignored)
|
||||
|
||||
resources/ # Bundled defaults (copied to ~/.takt on init)
|
||||
resources/ # Bundled defaults (builtin, read from dist/ at runtime)
|
||||
global/
|
||||
en/ # English agents and workflows
|
||||
ja/ # Japanese agents and workflows
|
||||
```
|
||||
|
||||
Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority. Use `/eject` to copy builtins to `~/.takt/` for customization.
|
||||
|
||||
## Workflow YAML Schema
|
||||
|
||||
```yaml
|
||||
name: workflow-name
|
||||
description: Optional description
|
||||
max_iterations: 10 # snake_case in YAML
|
||||
max_iterations: 10
|
||||
initial_step: plan # First step to execute
|
||||
|
||||
steps:
|
||||
# Normal step
|
||||
- name: step-name
|
||||
agent: ~/.takt/agents/default/coder.md # Path to agent prompt
|
||||
agent_name: coder # Display name (optional)
|
||||
provider: codex # claude|codex (optional)
|
||||
model: opus # Model name (optional)
|
||||
agent: ../agents/default/coder.md # Path to agent prompt
|
||||
agent_name: coder # Display name (optional)
|
||||
provider: codex # claude|codex (optional)
|
||||
model: opus # Model name (optional)
|
||||
edit: true # Whether step can edit files
|
||||
permission_mode: acceptEdits # Tool permission mode (optional)
|
||||
instruction_template: |
|
||||
{task}
|
||||
{previous_response}
|
||||
pass_previous_response: true # Default: true
|
||||
transitions:
|
||||
- condition: done
|
||||
next_step: next-step
|
||||
Custom instructions for this step.
|
||||
{task}, {previous_response} are auto-injected if not present as placeholders.
|
||||
pass_previous_response: true # Default: true
|
||||
report:
|
||||
name: 01-plan.md # Report file name
|
||||
format: | # Report format template
|
||||
# Plan Report
|
||||
...
|
||||
rules:
|
||||
- condition: "Human-readable condition"
|
||||
next: next-step-name
|
||||
- condition: ai("AI evaluates this condition text")
|
||||
next: other-step
|
||||
- condition: blocked
|
||||
next_step: ABORT
|
||||
on_no_status: complete # complete|continue|stay
|
||||
next: ABORT
|
||||
|
||||
# Parallel step (sub-steps execute concurrently)
|
||||
- name: reviewers
|
||||
parallel:
|
||||
- name: arch-review
|
||||
agent: ../agents/default/architecture-reviewer.md
|
||||
rules:
|
||||
- condition: approved # next is optional for sub-steps
|
||||
- condition: needs_fix
|
||||
instruction_template: |
|
||||
Review architecture...
|
||||
- name: security-review
|
||||
agent: ../agents/default/security-reviewer.md
|
||||
rules:
|
||||
- condition: approved
|
||||
- condition: needs_fix
|
||||
instruction_template: |
|
||||
Review security...
|
||||
rules: # Parent rules use aggregate conditions
|
||||
- condition: all("approved")
|
||||
next: supervise
|
||||
- condition: any("needs_fix")
|
||||
next: fix
|
||||
```
|
||||
|
||||
Key points about parallel steps:
|
||||
- Sub-step `rules` define possible outcomes but `next` is ignored (parent handles routing)
|
||||
- Parent `rules` use `all("X")`/`any("X")` to aggregate sub-step results
|
||||
- `all("X")`: true if ALL sub-steps matched condition X
|
||||
- `any("X")`: true if ANY sub-step matched condition X
|
||||
|
||||
### Rule Condition Types
|
||||
|
||||
| Type | Syntax | Evaluation |
|
||||
|------|--------|------------|
|
||||
| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
|
||||
| AI judge | `ai("condition text")` | AI evaluates condition against agent output |
|
||||
| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step matched conditions |
|
||||
|
||||
### Template Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `{task}` | Original user request |
|
||||
| `{iteration}` | Current iteration number |
|
||||
| `{max_iterations}` | Maximum iterations |
|
||||
| `{previous_response}` | Previous step output (requires `pass_previous_response: true`) |
|
||||
| `{user_inputs}` | Accumulated user inputs during workflow |
|
||||
| `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) |
|
||||
| `{task}` | Original user request (auto-injected if not in template) |
|
||||
| `{iteration}` | Workflow-wide iteration count |
|
||||
| `{max_iterations}` | Maximum iterations allowed |
|
||||
| `{step_iteration}` | Per-step iteration count |
|
||||
| `{previous_response}` | Previous step output (auto-injected if not in template) |
|
||||
| `{user_inputs}` | Accumulated user inputs (auto-injected if not in template) |
|
||||
| `{report_dir}` | Report directory name |
|
||||
|
||||
### Model Resolution
|
||||
|
||||
@ -166,24 +254,34 @@ provider: claude
|
||||
model: opus # Default model for all steps (unless overridden)
|
||||
```
|
||||
|
||||
## NDJSON Session Logging
|
||||
|
||||
Session logs use NDJSON (`.jsonl`) format for real-time append-only writes. Record types:
|
||||
|
||||
| Record | Description |
|
||||
|--------|-------------|
|
||||
| `workflow_start` | Workflow initialization with task, workflow name |
|
||||
| `step_start` | Step execution start |
|
||||
| `step_complete` | Step result with status, content, matched rule info |
|
||||
| `workflow_complete` | Successful completion |
|
||||
| `workflow_abort` | Abort with reason |
|
||||
|
||||
Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json` format is still readable via `loadSessionLog()`.
|
||||
|
||||
## TypeScript Notes
|
||||
|
||||
- ESM modules with `.js` extensions in imports
|
||||
- Strict TypeScript with `noUncheckedIndexedAccess`
|
||||
- Zod schemas (v4 syntax) for runtime validation (`src/models/schemas.ts`)
|
||||
- Zod schemas for runtime validation (`src/models/schemas.ts`)
|
||||
- Uses `@anthropic-ai/claude-agent-sdk` for Claude integration
|
||||
|
||||
## Design Principles
|
||||
|
||||
**Keep commands minimal.** One command per concept. Use arguments/modes instead of multiple similar commands. Before adding a new command, consider if existing commands can be extended.
|
||||
|
||||
**Do NOT expand schemas carelessly.** The `TransitionConditionSchema` defines allowed condition values for workflow transitions. Do NOT add new values without strong justification. Use existing values creatively:
|
||||
- `done` - Task completed (minor fixes, successful completion)
|
||||
- `blocked` - Cannot proceed (needs plan rework)
|
||||
- `approved` - Review passed
|
||||
- `rejected` - Review failed, needs major rework
|
||||
- `improve` - Needs improvement (security concerns, quality issues)
|
||||
- `always` - Unconditional transition
|
||||
**Do NOT expand schemas carelessly.** Rule conditions are free-form text (not enum-restricted). However, the engine's behavior depends on specific patterns (`ai()`, `all()`, `any()`). Do not add new special syntax without updating the loader's regex parsing in `workflowLoader.ts`.
|
||||
|
||||
**Instruction auto-injection over explicit placeholders.** The instruction builder auto-injects `{task}`, `{previous_response}`, `{user_inputs}`, and status rules. Templates should contain only step-specific instructions, not boilerplate.
|
||||
|
||||
## Isolated Execution (Shared Clone)
|
||||
|
||||
|
||||
248
README.md
248
README.md
@ -26,6 +26,9 @@ npm install -g takt
|
||||
# Run a task (will prompt for workflow selection and optional isolated clone)
|
||||
takt "Add a login feature"
|
||||
|
||||
# Run a GitHub issue as a task
|
||||
takt "#6"
|
||||
|
||||
# Add a task to the queue
|
||||
takt /add-task "Fix the login bug"
|
||||
|
||||
@ -75,7 +78,7 @@ Choose `y` to run in a `git clone --shared` isolated environment, keeping your w
|
||||
|
||||
| Workflow | Best for |
|
||||
|----------|----------|
|
||||
| `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with fix loops. |
|
||||
| `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with parallel architect + security review. |
|
||||
| `simple` | Lightweight tasks like README updates or small fixes. Reviews without fix loops. |
|
||||
| `expert-review` / `expert-cqrs` | Web development projects. Multi-expert review (CQRS, Frontend, Security, QA). |
|
||||
| `research` | Research and investigation. Autonomous research without asking questions. |
|
||||
@ -86,67 +89,111 @@ Choose `y` to run in a `git clone --shared` isolated environment, keeping your w
|
||||
| Command | Alias | Description |
|
||||
|---------|-------|-------------|
|
||||
| `takt "task"` | | Execute task with current workflow (session auto-continued) |
|
||||
| `takt "#N"` | | Execute GitHub issue #N as a task |
|
||||
| `takt /run-tasks` | `/run` | Run all pending tasks from `.takt/tasks/` |
|
||||
| `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (stays resident) |
|
||||
| `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) |
|
||||
| `takt /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) |
|
||||
| `takt /switch` | `/sw` | Switch workflow interactively |
|
||||
| `takt /clear` | | Clear agent conversation sessions |
|
||||
| `takt /eject` | | Copy builtin workflow/agents to `~/.takt/` for customization |
|
||||
| `takt /refresh-builtin` | | Update builtin agents/workflows to latest version |
|
||||
| `takt /config` | | Configure permission mode |
|
||||
| `takt /help` | | Show help |
|
||||
|
||||
## Workflows
|
||||
|
||||
TAKT uses YAML-based workflow definitions. Place them in:
|
||||
- `~/.takt/workflows/*.yaml`
|
||||
TAKT uses YAML-based workflow definitions with rule-based routing. Builtin workflows are embedded in the package; user workflows in `~/.takt/workflows/` take priority. Use `/eject` to copy a builtin to `~/.takt/` for customization.
|
||||
|
||||
### Example Workflow
|
||||
|
||||
```yaml
|
||||
name: default
|
||||
max_iterations: 10
|
||||
initial_step: plan
|
||||
|
||||
steps:
|
||||
- name: plan
|
||||
agent: planner
|
||||
provider: claude # Optional: claude or codex
|
||||
model: opus # Claude: opus/sonnet/haiku, Codex: gpt-5.2-codex/gpt-5.1-codex
|
||||
agent: ../agents/default/planner.md
|
||||
model: opus
|
||||
edit: false
|
||||
rules:
|
||||
- condition: Plan complete
|
||||
next: implement
|
||||
instruction_template: |
|
||||
{task}
|
||||
transitions:
|
||||
- condition: done
|
||||
next_step: implement
|
||||
Analyze the request and create an implementation plan.
|
||||
|
||||
- name: implement
|
||||
agent: coder
|
||||
provider: codex
|
||||
model: gpt-5.2-codex # Codex model example
|
||||
agent: ../agents/default/coder.md
|
||||
edit: true
|
||||
permission_mode: acceptEdits
|
||||
rules:
|
||||
- condition: Implementation complete
|
||||
next: review
|
||||
- condition: Cannot proceed
|
||||
next: ABORT
|
||||
instruction_template: |
|
||||
{task}
|
||||
transitions:
|
||||
- condition: done
|
||||
next_step: review
|
||||
- condition: blocked
|
||||
next_step: ABORT
|
||||
Implement based on the plan.
|
||||
|
||||
- name: review
|
||||
agent: architect
|
||||
model: sonnet # Model alias (no provider = uses global default)
|
||||
transitions:
|
||||
- condition: approved
|
||||
next_step: COMPLETE
|
||||
- condition: rejected
|
||||
next_step: implement
|
||||
agent: ../agents/default/architecture-reviewer.md
|
||||
edit: false
|
||||
rules:
|
||||
- condition: Approved
|
||||
next: COMPLETE
|
||||
- condition: Needs fix
|
||||
next: implement
|
||||
instruction_template: |
|
||||
Review the implementation for architecture and code quality.
|
||||
```
|
||||
|
||||
### Parallel Steps
|
||||
|
||||
Steps can execute sub-steps concurrently with aggregate evaluation:
|
||||
|
||||
```yaml
|
||||
- name: reviewers
|
||||
parallel:
|
||||
- name: arch-review
|
||||
agent: ../agents/default/architecture-reviewer.md
|
||||
rules:
|
||||
- condition: approved
|
||||
- condition: needs_fix
|
||||
instruction_template: |
|
||||
Review architecture and code quality.
|
||||
- name: security-review
|
||||
agent: ../agents/default/security-reviewer.md
|
||||
rules:
|
||||
- condition: approved
|
||||
- condition: needs_fix
|
||||
instruction_template: |
|
||||
Review for security vulnerabilities.
|
||||
rules:
|
||||
- condition: all("approved")
|
||||
next: supervise
|
||||
- condition: any("needs_fix")
|
||||
next: fix
|
||||
```
|
||||
|
||||
- `all("X")`: true if ALL sub-steps matched condition X
|
||||
- `any("X")`: true if ANY sub-step matched condition X
|
||||
- Sub-step `rules` define possible outcomes; `next` is optional (parent handles routing)
|
||||
|
||||
### Rule Condition Types
|
||||
|
||||
| Type | Syntax | Description |
|
||||
|------|--------|-------------|
|
||||
| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
|
||||
| AI judge | `ai("condition text")` | AI evaluates the condition against agent output |
|
||||
| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step results |
|
||||
|
||||
## Built-in Workflows
|
||||
|
||||
TAKT ships with several built-in workflows:
|
||||
|
||||
| Workflow | Description |
|
||||
|----------|-------------|
|
||||
| `default` | Full development workflow: plan → implement → architect review → AI review → security review → supervisor approval. Includes fix loops for each review stage. |
|
||||
| `default` | Full development workflow: plan → implement → AI review → parallel reviewers (architect + security) → supervisor approval. Includes fix loops for each review stage. |
|
||||
| `simple` | Simplified version of default: plan → implement → architect review → AI review → supervisor. No intermediate fix steps. |
|
||||
| `research` | Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions. |
|
||||
| `expert-review` | Comprehensive review with domain experts: CQRS+ES, Frontend, AI, Security, QA reviews with fix loops. |
|
||||
@ -158,9 +205,9 @@ Switch between workflows with `takt /switch`.
|
||||
## Built-in Agents
|
||||
|
||||
- **coder** - Implements features and fixes bugs
|
||||
- **architect** - Reviews code and provides feedback
|
||||
- **supervisor** - Final verification and approval
|
||||
- **planner** - Task analysis and implementation planning
|
||||
- **architect** - Reviews architecture and code quality, verifies spec compliance
|
||||
- **supervisor** - Final verification, validation, and approval
|
||||
- **planner** - Task analysis, spec investigation, and implementation planning
|
||||
- **ai-reviewer** - AI-generated code quality review
|
||||
- **security** - Security vulnerability assessment
|
||||
|
||||
@ -175,14 +222,19 @@ agents:
|
||||
allowed_tools: [Read, Glob, Grep]
|
||||
provider: claude # Optional: claude or codex
|
||||
model: opus # Claude: opus/sonnet/haiku or full name (claude-opus-4-5-20251101)
|
||||
status_patterns:
|
||||
approved: "\\[APPROVE\\]"
|
||||
rejected: "\\[REJECT\\]"
|
||||
```
|
||||
|
||||
- name: my-codex-agent
|
||||
prompt_file: .takt/prompts/analyzer.md
|
||||
provider: codex
|
||||
model: gpt-5.2-codex # Codex: gpt-5.2-codex, gpt-5.1-codex, etc.
|
||||
Or create agent prompt files as Markdown:
|
||||
|
||||
```markdown
|
||||
# ~/.takt/agents/my-agents/reviewer.md
|
||||
|
||||
You are a code reviewer focused on security.
|
||||
|
||||
## Your Role
|
||||
- Check for security vulnerabilities
|
||||
- Verify input validation
|
||||
- Review authentication logic
|
||||
```
|
||||
|
||||
## Model Selection
|
||||
@ -217,22 +269,22 @@ Available Codex models:
|
||||
```
|
||||
~/.takt/
|
||||
├── config.yaml # Global config (provider, model, workflows, etc.)
|
||||
├── workflows/ # Workflow definitions
|
||||
└── agents/ # Agent prompt files
|
||||
├── workflows/ # User workflow definitions (override builtins)
|
||||
└── agents/ # User agent prompt files
|
||||
|
||||
.takt/ # Project-level config
|
||||
├── agents.yaml # Custom agent definitions
|
||||
├── tasks/ # Pending task files (.yaml, .md)
|
||||
├── completed/ # Completed tasks with reports
|
||||
├── worktree-meta/ # Metadata for task branches
|
||||
├── worktree-sessions/ # Per-clone agent session storage
|
||||
├── reports/ # Execution reports (auto-generated)
|
||||
└── logs/ # Session logs (incremental)
|
||||
└── logs/ # Session logs in NDJSON format
|
||||
├── latest.json # Pointer to current/latest session
|
||||
├── previous.json # Pointer to previous session
|
||||
└── {sessionId}.json # Full session log per workflow run
|
||||
└── {sessionId}.jsonl # NDJSON session log per workflow run
|
||||
```
|
||||
|
||||
Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority.
|
||||
|
||||
### Global Configuration
|
||||
|
||||
Configure default provider and model in `~/.takt/config.yaml`:
|
||||
@ -268,67 +320,59 @@ This interactive flow ensures each task runs with the right workflow and isolati
|
||||
|
||||
### Adding Custom Workflows
|
||||
|
||||
Create your own workflow by adding YAML files to `~/.takt/workflows/`:
|
||||
Create your own workflow by adding YAML files to `~/.takt/workflows/`, or use `/eject` to customize a builtin:
|
||||
|
||||
```bash
|
||||
# Copy the default workflow to ~/.takt/workflows/ for editing
|
||||
takt /eject default
|
||||
```
|
||||
|
||||
```yaml
|
||||
# ~/.takt/workflows/my-workflow.yaml
|
||||
name: my-workflow
|
||||
description: My custom workflow
|
||||
|
||||
max_iterations: 5
|
||||
initial_step: analyze
|
||||
|
||||
steps:
|
||||
- name: analyze
|
||||
agent: ~/.takt/agents/my-agents/analyzer.md
|
||||
edit: false
|
||||
rules:
|
||||
- condition: Analysis complete
|
||||
next: implement
|
||||
instruction_template: |
|
||||
Analyze this request: {task}
|
||||
transitions:
|
||||
- condition: done
|
||||
next_step: implement
|
||||
Analyze this request thoroughly.
|
||||
|
||||
- name: implement
|
||||
agent: ~/.takt/agents/default/coder.md
|
||||
instruction_template: |
|
||||
Implement based on the analysis: {previous_response}
|
||||
edit: true
|
||||
permission_mode: acceptEdits
|
||||
pass_previous_response: true
|
||||
transitions:
|
||||
- condition: done
|
||||
next_step: COMPLETE
|
||||
rules:
|
||||
- condition: Done
|
||||
next: COMPLETE
|
||||
instruction_template: |
|
||||
Implement based on the analysis.
|
||||
```
|
||||
|
||||
> **Note**: `{task}`, `{previous_response}`, and `{user_inputs}` are auto-injected into instructions. You only need explicit placeholders if you want to control their position in the template.
|
||||
|
||||
### Specifying Agents by Path
|
||||
|
||||
Agents are specified using file paths in workflow definitions:
|
||||
|
||||
```yaml
|
||||
# Use built-in agents
|
||||
# Relative to workflow file directory
|
||||
agent: ../agents/default/coder.md
|
||||
|
||||
# Home directory
|
||||
agent: ~/.takt/agents/default/coder.md
|
||||
agent: ~/.takt/agents/magi/melchior.md
|
||||
|
||||
# Use project-local agents
|
||||
agent: ./.takt/agents/my-reviewer.md
|
||||
|
||||
# Use absolute paths
|
||||
# Absolute paths
|
||||
agent: /path/to/custom/agent.md
|
||||
```
|
||||
|
||||
Create custom agent prompts as Markdown files:
|
||||
|
||||
```markdown
|
||||
# ~/.takt/agents/my-agents/reviewer.md
|
||||
|
||||
You are a code reviewer focused on security.
|
||||
|
||||
## Your Role
|
||||
- Check for security vulnerabilities
|
||||
- Verify input validation
|
||||
- Review authentication logic
|
||||
|
||||
## Output Format
|
||||
- [REVIEWER:APPROVE] if code is secure
|
||||
- [REVIEWER:REJECT] if issues found (list them)
|
||||
```
|
||||
|
||||
### Task Management
|
||||
|
||||
TAKT supports batch task processing through task files in `.takt/tasks/`. Both `.yaml`/`.yml` and `.md` file formats are supported.
|
||||
@ -339,6 +383,9 @@ TAKT supports batch task processing through task files in `.takt/tasks/`. Both `
|
||||
# Quick add (no isolation)
|
||||
takt /add-task "Add authentication feature"
|
||||
|
||||
# Add a GitHub issue as a task
|
||||
takt /add-task "#6"
|
||||
|
||||
# Interactive mode (prompts for isolation, branch, workflow options)
|
||||
takt /add-task
|
||||
```
|
||||
@ -416,11 +463,13 @@ Lists all `takt/`-prefixed branches with file change counts. For each branch you
|
||||
|
||||
### Session Logs
|
||||
|
||||
TAKT writes session logs incrementally to `.takt/logs/`. Logs are saved at workflow start, after each step, and at workflow end — so even if the process crashes mid-execution, partial logs are preserved.
|
||||
TAKT writes session logs in NDJSON (`.jsonl`) format to `.takt/logs/`. Each record is appended atomically, so even if the process crashes mid-execution, partial logs are preserved and logs can be tailed in real-time with `tail -f`.
|
||||
|
||||
- `.takt/logs/latest.json` - Pointer to the current (or most recent) session
|
||||
- `.takt/logs/previous.json` - Pointer to the previous session
|
||||
- `.takt/logs/{sessionId}.json` - Full session log with step history
|
||||
- `.takt/logs/{sessionId}.jsonl` - NDJSON session log with step history
|
||||
|
||||
Record types: `workflow_start`, `step_start`, `step_complete`, `workflow_complete`, `workflow_abort`.
|
||||
|
||||
Agents can read `previous.json` to pick up context from a prior run. Session continuity is automatic — simply run `takt "task"` to continue where the previous session left off.
|
||||
|
||||
@ -430,57 +479,48 @@ Available variables in `instruction_template`:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `{task}` | Original user request |
|
||||
| `{task}` | Original user request (auto-injected if not in template) |
|
||||
| `{iteration}` | Workflow-wide turn count (total steps executed) |
|
||||
| `{max_iterations}` | Maximum iterations allowed |
|
||||
| `{step_iteration}` | Per-step iteration count (how many times THIS step has run) |
|
||||
| `{previous_response}` | Previous step's output (requires `pass_previous_response: true`) |
|
||||
| `{user_inputs}` | Additional user inputs during workflow |
|
||||
| `{previous_response}` | Previous step's output (auto-injected if not in template) |
|
||||
| `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
|
||||
| `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) |
|
||||
|
||||
### Designing Workflows
|
||||
|
||||
Each workflow step requires three key elements:
|
||||
Each workflow step requires:
|
||||
|
||||
**1. Agent** - A Markdown file containing the system prompt:
|
||||
|
||||
```yaml
|
||||
agent: ~/.takt/agents/default/coder.md # Path to agent prompt file
|
||||
agent_name: coder # Display name (optional)
|
||||
agent: ../agents/default/coder.md # Path to agent prompt file
|
||||
agent_name: coder # Display name (optional)
|
||||
```
|
||||
|
||||
**2. Status Rules** - Define how the agent signals completion. Agents output status markers like `[CODER:DONE]` or `[ARCHITECT:REJECT]` that TAKT detects to drive transitions:
|
||||
**2. Rules** - Define how the step routes to the next step. The instruction builder auto-injects status output rules so agents know what tags to output:
|
||||
|
||||
```yaml
|
||||
status_rules_prompt: |
|
||||
Your final output MUST include a status tag:
|
||||
- `[CODER:DONE]` if implementation is complete
|
||||
- `[CODER:BLOCKED]` if you cannot proceed
|
||||
rules:
|
||||
- condition: "Implementation complete"
|
||||
next: review
|
||||
- condition: "Cannot proceed"
|
||||
next: ABORT
|
||||
```
|
||||
|
||||
**3. Transitions** - Route to the next step based on status:
|
||||
Special `next` values: `COMPLETE` (success), `ABORT` (failure).
|
||||
|
||||
```yaml
|
||||
transitions:
|
||||
- condition: done # Maps to status tag DONE
|
||||
next_step: review # Go to review step
|
||||
- condition: blocked # Maps to status tag BLOCKED
|
||||
next_step: ABORT # End workflow with failure
|
||||
```
|
||||
|
||||
Available transition conditions: `done`, `blocked`, `approved`, `rejected`, `improve`, `answer`, `always`.
|
||||
Special next_step values: `COMPLETE` (success), `ABORT` (failure).
|
||||
|
||||
**Step options:**
|
||||
**3. Step options:**
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `edit` | - | Whether the step can edit project files (`true`/`false`) |
|
||||
| `pass_previous_response` | `true` | Pass previous step's output to `{previous_response}` |
|
||||
| `on_no_status` | - | Behavior when no status is detected: `complete`, `continue`, `stay` |
|
||||
| `allowed_tools` | - | List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) |
|
||||
| `provider` | - | Override provider for this step (`claude` or `codex`) |
|
||||
| `model` | - | Override model for this step |
|
||||
| `permission_mode` | `default` | Permission mode: `default`, `acceptEdits`, or `bypassPermissions` |
|
||||
| `report` | - | Report file configuration (name, format) for auto-generated reports |
|
||||
|
||||
## API Usage
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user