agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
nrslib 2026-01-30 21:01:00 +09:00
parent 748f5afb29
commit 4e7c3d0afb
2 changed files with 295 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

204
CLAUDE.md
View File

@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## 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 ## 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 /watch` | | Watch `.takt/tasks/` and auto-execute tasks (resident process) |
| `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) | | `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 /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 /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 /refresh-builtin` | | Update builtin resources from `resources/` to `~/.takt/` |
| `takt /help` | | Show help message | | `takt /help` | | Show help message |
| `takt /config` | | Display current configuration | | `takt /config` | | Display current configuration |
GitHub issue references: `takt #6` fetches issue #6 and executes it as a task.
## Architecture ## Architecture
### Core Flow ### Core Flow
``` ```
CLI (cli.ts) CLI (cli.ts)
→ Slash commands (/run-tasks, /watch, /add-task, /list-tasks, /switch, /clear, /refresh-builtin, /help, /config) → Slash commands or executeTask()
→ or executeTask()
→ WorkflowEngine (workflow/engine.ts) → WorkflowEngine (workflow/engine.ts)
→ runAgent() (agents/runner.ts) → Per step: 3-phase execution
→ callClaude() (claude/client.ts) Phase 1: runAgent() → main work
→ executeClaudeCli() (claude/process.ts) Phase 2: runReportPhase() → report output (if step.report defined)
→ ClaudeProcess (claude-agent-sdk) 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 ### Key Components
**WorkflowEngine** (`src/workflow/engine.ts`) **WorkflowEngine** (`src/workflow/engine.ts`)
- State machine that orchestrates agent execution via EventEmitter - 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` - Emits events: `step:start`, `step:complete`, `step:blocked`, `step:loop_detected`, `workflow:complete`, `workflow:abort`, `iteration:limit`
- Supports loop detection (`LoopDetector`) and iteration limits - Supports loop detection (`LoopDetector`) and iteration limits
- Maintains agent sessions per step for conversation continuity - 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`) **Agent Runner** (`src/agents/runner.ts`)
- Resolves agent specs (name or path) to agent configurations - Resolves agent specs (name or path) to agent configurations
@ -63,17 +103,16 @@ CLI (cli.ts)
- `supervisor`: Read/Glob/Grep/Bash/WebSearch/WebFetch - `supervisor`: Read/Glob/Grep/Bash/WebSearch/WebFetch
- `planner`: Read/Glob/Grep/Bash/WebSearch/WebFetch - `planner`: Read/Glob/Grep/Bash/WebSearch/WebFetch
- Custom agents via `.takt/agents.yaml` or prompt files (.md) - Custom agents via `.takt/agents.yaml` or prompt files (.md)
- Supports Claude Code agents (`claudeAgent`) and skills (`claudeSkill`)
**Claude Integration** (`src/claude/`) **Claude Integration** (`src/claude/`)
- `client.ts` - High-level API: `callClaude()`, `callClaudeCustom()`, `callClaudeAgent()`, `callClaudeSkill()`, status detection via regex patterns - `client.ts` - High-level API: `callClaude()`, `callClaudeCustom()`, `callClaudeAgent()`, `callClaudeSkill()`
- `process.ts` - SDK wrapper with `ClaudeProcess` class, re-exports query management - `process.ts` - SDK wrapper with `ClaudeProcess` class
- `executor.ts` - Query execution using `@anthropic-ai/claude-agent-sdk` - `executor.ts` - Query execution using `@anthropic-ai/claude-agent-sdk`
- `query-manager.ts` - Concurrent query tracking with query IDs - `query-manager.ts` - Concurrent query tracking with query IDs
**Configuration** (`src/config/`) **Configuration** (`src/config/`)
- `loader.ts` - Custom agent loading from `.takt/agents.yaml` - `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 - `agentLoader.ts` - Agent prompt file loading
- `paths.ts` - Directory structure (`.takt/`, `~/.takt/`), session management - `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`) - `watcher.ts` - TaskWatcher class for polling and auto-executing tasks (used by `/watch`)
- `index.ts` - Task operations (getNextTask, completeTask, addTask) - `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 ### Data Flow
1. User provides task or slash command → CLI 1. User provides task (text or `#N` issue reference) or slash command → CLI
2. CLI loads workflow from `~/.takt/workflows/{name}.yaml` 2. CLI loads workflow: user `~/.takt/workflows/` → builtin `resources/global/{lang}/workflows/` fallback
3. WorkflowEngine starts at `initialStep` 3. WorkflowEngine starts at `initial_step`
4. Each step: `buildInstruction()` → `runStep()` → `runAgent()` → `callClaude()` → detect status → `determineNextStep()` 4. Each step: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()`
5. Status patterns (regex in `statusPatterns`) determine next step via `transitions` 5. Rule evaluation determines next step name
6. Special transitions: `COMPLETE` ends workflow successfully, `ABORT` ends with failure 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 ## Directory Structure
``` ```
~/.takt/ # Global user config (created on first run) ~/.takt/ # Global user config (created on first run)
config.yaml # Trusted dirs, default workflow, log level, language config.yaml # Trusted dirs, default workflow, log level, language
workflows/ # Workflow YAML files (required location) workflows/ # User workflow YAML files (override builtins)
agents/ # Agent prompt files (.md) agents/ # User agent prompt files (.md)
.takt/ # Project-level config .takt/ # Project-level config
agents.yaml # Custom agent definitions agents.yaml # Custom agent definitions
tasks/ # Task files for /run-tasks tasks/ # Task files for /run-tasks
reports/ # Execution reports (auto-generated) 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/ global/
en/ # English agents and workflows en/ # English agents and workflows
ja/ # Japanese 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 ## Workflow YAML Schema
```yaml ```yaml
name: workflow-name name: workflow-name
description: Optional description description: Optional description
max_iterations: 10 # snake_case in YAML max_iterations: 10
initial_step: plan # First step to execute
steps: steps:
# Normal step
- name: step-name - name: step-name
agent: ~/.takt/agents/default/coder.md # Path to agent prompt agent: ../agents/default/coder.md # Path to agent prompt
agent_name: coder # Display name (optional) agent_name: coder # Display name (optional)
provider: codex # claude|codex (optional) provider: codex # claude|codex (optional)
model: opus # Model name (optional) model: opus # Model name (optional)
edit: true # Whether step can edit files
permission_mode: acceptEdits # Tool permission mode (optional)
instruction_template: | instruction_template: |
{task} Custom instructions for this step.
{previous_response} {task}, {previous_response} are auto-injected if not present as placeholders.
pass_previous_response: true # Default: true pass_previous_response: true # Default: true
transitions: report:
- condition: done name: 01-plan.md # Report file name
next_step: next-step 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 - condition: blocked
next_step: ABORT next: ABORT
on_no_status: complete # complete|continue|stay
# 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 ### Template Variables
| Variable | Description | | Variable | Description |
|----------|-------------| |----------|-------------|
| `{task}` | Original user request | | `{task}` | Original user request (auto-injected if not in template) |
| `{iteration}` | Current iteration number | | `{iteration}` | Workflow-wide iteration count |
| `{max_iterations}` | Maximum iterations | | `{max_iterations}` | Maximum iterations allowed |
| `{previous_response}` | Previous step output (requires `pass_previous_response: true`) | | `{step_iteration}` | Per-step iteration count |
| `{user_inputs}` | Accumulated user inputs during workflow | | `{previous_response}` | Previous step output (auto-injected if not in template) |
| `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) | | `{user_inputs}` | Accumulated user inputs (auto-injected if not in template) |
| `{report_dir}` | Report directory name |
### Model Resolution ### Model Resolution
@ -166,24 +254,34 @@ provider: claude
model: opus # Default model for all steps (unless overridden) 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 ## TypeScript Notes
- ESM modules with `.js` extensions in imports - ESM modules with `.js` extensions in imports
- Strict TypeScript with `noUncheckedIndexedAccess` - 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 - Uses `@anthropic-ai/claude-agent-sdk` for Claude integration
## Design Principles ## 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. **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: **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`.
- `done` - Task completed (minor fixes, successful completion)
- `blocked` - Cannot proceed (needs plan rework) **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.
- `approved` - Review passed
- `rejected` - Review failed, needs major rework
- `improve` - Needs improvement (security concerns, quality issues)
- `always` - Unconditional transition
## Isolated Execution (Shared Clone) ## Isolated Execution (Shared Clone)

248
README.md
View File

@ -26,6 +26,9 @@ npm install -g takt
# Run a task (will prompt for workflow selection and optional isolated clone) # Run a task (will prompt for workflow selection and optional isolated clone)
takt "Add a login feature" takt "Add a login feature"
# Run a GitHub issue as a task
takt "#6"
# Add a task to the queue # Add a task to the queue
takt /add-task "Fix the login bug" 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 | | 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. | | `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). | | `expert-review` / `expert-cqrs` | Web development projects. Multi-expert review (CQRS, Frontend, Security, QA). |
| `research` | Research and investigation. Autonomous research without asking questions. | | `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 | | Command | Alias | Description |
|---------|-------|-------------| |---------|-------|-------------|
| `takt "task"` | | Execute task with current workflow (session auto-continued) | | `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 /run-tasks` | `/run` | Run all pending tasks from `.takt/tasks/` |
| `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (stays resident) | | `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 /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 /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) |
| `takt /switch` | `/sw` | Switch workflow interactively | | `takt /switch` | `/sw` | Switch workflow interactively |
| `takt /clear` | | Clear agent conversation sessions | | `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 /refresh-builtin` | | Update builtin agents/workflows to latest version |
| `takt /config` | | Configure permission mode | | `takt /config` | | Configure permission mode |
| `takt /help` | | Show help | | `takt /help` | | Show help |
## Workflows ## Workflows
TAKT uses YAML-based workflow definitions. Place them in: 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.
- `~/.takt/workflows/*.yaml`
### Example Workflow ### Example Workflow
```yaml ```yaml
name: default name: default
max_iterations: 10 max_iterations: 10
initial_step: plan
steps: steps:
- name: plan - name: plan
agent: planner agent: ../agents/default/planner.md
provider: claude # Optional: claude or codex model: opus
model: opus # Claude: opus/sonnet/haiku, Codex: gpt-5.2-codex/gpt-5.1-codex edit: false
rules:
- condition: Plan complete
next: implement
instruction_template: | instruction_template: |
{task} Analyze the request and create an implementation plan.
transitions:
- condition: done
next_step: implement
- name: implement - name: implement
agent: coder agent: ../agents/default/coder.md
provider: codex edit: true
model: gpt-5.2-codex # Codex model example permission_mode: acceptEdits
rules:
- condition: Implementation complete
next: review
- condition: Cannot proceed
next: ABORT
instruction_template: | instruction_template: |
{task} Implement based on the plan.
transitions:
- condition: done
next_step: review
- condition: blocked
next_step: ABORT
- name: review - name: review
agent: architect agent: ../agents/default/architecture-reviewer.md
model: sonnet # Model alias (no provider = uses global default) edit: false
transitions: rules:
- condition: approved - condition: Approved
next_step: COMPLETE next: COMPLETE
- condition: rejected - condition: Needs fix
next_step: implement 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 ## Built-in Workflows
TAKT ships with several built-in workflows: TAKT ships with several built-in workflows:
| Workflow | Description | | 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. | | `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. | | `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. | | `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 ## Built-in Agents
- **coder** - Implements features and fixes bugs - **coder** - Implements features and fixes bugs
- **architect** - Reviews code and provides feedback - **architect** - Reviews architecture and code quality, verifies spec compliance
- **supervisor** - Final verification and approval - **supervisor** - Final verification, validation, and approval
- **planner** - Task analysis and implementation planning - **planner** - Task analysis, spec investigation, and implementation planning
- **ai-reviewer** - AI-generated code quality review - **ai-reviewer** - AI-generated code quality review
- **security** - Security vulnerability assessment - **security** - Security vulnerability assessment
@ -175,14 +222,19 @@ agents:
allowed_tools: [Read, Glob, Grep] allowed_tools: [Read, Glob, Grep]
provider: claude # Optional: claude or codex provider: claude # Optional: claude or codex
model: opus # Claude: opus/sonnet/haiku or full name (claude-opus-4-5-20251101) model: opus # Claude: opus/sonnet/haiku or full name (claude-opus-4-5-20251101)
status_patterns: ```
approved: "\\[APPROVE\\]"
rejected: "\\[REJECT\\]"
- name: my-codex-agent Or create agent prompt files as Markdown:
prompt_file: .takt/prompts/analyzer.md
provider: codex ```markdown
model: gpt-5.2-codex # Codex: gpt-5.2-codex, gpt-5.1-codex, etc. # ~/.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 ## Model Selection
@ -217,22 +269,22 @@ Available Codex models:
``` ```
~/.takt/ ~/.takt/
├── config.yaml # Global config (provider, model, workflows, etc.) ├── config.yaml # Global config (provider, model, workflows, etc.)
├── workflows/ # Workflow definitions ├── workflows/ # User workflow definitions (override builtins)
└── agents/ # Agent prompt files └── agents/ # User agent prompt files
.takt/ # Project-level config .takt/ # Project-level config
├── agents.yaml # Custom agent definitions ├── agents.yaml # Custom agent definitions
├── tasks/ # Pending task files (.yaml, .md) ├── tasks/ # Pending task files (.yaml, .md)
├── completed/ # Completed tasks with reports ├── completed/ # Completed tasks with reports
├── worktree-meta/ # Metadata for task branches
├── worktree-sessions/ # Per-clone agent session storage
├── reports/ # Execution reports (auto-generated) ├── reports/ # Execution reports (auto-generated)
└── logs/ # Session logs (incremental) └── logs/ # Session logs in NDJSON format
├── latest.json # Pointer to current/latest session ├── latest.json # Pointer to current/latest session
├── previous.json # Pointer to previous 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 ### Global Configuration
Configure default provider and model in `~/.takt/config.yaml`: 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 ### 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 ```yaml
# ~/.takt/workflows/my-workflow.yaml # ~/.takt/workflows/my-workflow.yaml
name: my-workflow name: my-workflow
description: My custom workflow description: My custom workflow
max_iterations: 5 max_iterations: 5
initial_step: analyze
steps: steps:
- name: analyze - name: analyze
agent: ~/.takt/agents/my-agents/analyzer.md agent: ~/.takt/agents/my-agents/analyzer.md
edit: false
rules:
- condition: Analysis complete
next: implement
instruction_template: | instruction_template: |
Analyze this request: {task} Analyze this request thoroughly.
transitions:
- condition: done
next_step: implement
- name: implement - name: implement
agent: ~/.takt/agents/default/coder.md agent: ~/.takt/agents/default/coder.md
instruction_template: | edit: true
Implement based on the analysis: {previous_response} permission_mode: acceptEdits
pass_previous_response: true pass_previous_response: true
transitions: rules:
- condition: done - condition: Done
next_step: COMPLETE 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 ### Specifying Agents by Path
Agents are specified using file paths in workflow definitions: Agents are specified using file paths in workflow definitions:
```yaml ```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/default/coder.md
agent: ~/.takt/agents/magi/melchior.md
# Use project-local agents # Absolute paths
agent: ./.takt/agents/my-reviewer.md
# Use absolute paths
agent: /path/to/custom/agent.md 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 ### Task Management
TAKT supports batch task processing through task files in `.takt/tasks/`. Both `.yaml`/`.yml` and `.md` file formats are supported. 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) # Quick add (no isolation)
takt /add-task "Add authentication feature" 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) # Interactive mode (prompts for isolation, branch, workflow options)
takt /add-task takt /add-task
``` ```
@ -416,11 +463,13 @@ Lists all `takt/`-prefixed branches with file change counts. For each branch you
### Session Logs ### 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/latest.json` - Pointer to the current (or most recent) session
- `.takt/logs/previous.json` - Pointer to the previous 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. 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 | | Variable | Description |
|----------|-------------| |----------|-------------|
| `{task}` | Original user request | | `{task}` | Original user request (auto-injected if not in template) |
| `{iteration}` | Workflow-wide turn count (total steps executed) | | `{iteration}` | Workflow-wide turn count (total steps executed) |
| `{max_iterations}` | Maximum iterations allowed | | `{max_iterations}` | Maximum iterations allowed |
| `{step_iteration}` | Per-step iteration count (how many times THIS step has run) | | `{step_iteration}` | Per-step iteration count (how many times THIS step has run) |
| `{previous_response}` | Previous step's output (requires `pass_previous_response: true`) | | `{previous_response}` | Previous step's output (auto-injected if not in template) |
| `{user_inputs}` | Additional user inputs during workflow | | `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
| `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) | | `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) |
### Designing Workflows ### Designing Workflows
Each workflow step requires three key elements: Each workflow step requires:
**1. Agent** - A Markdown file containing the system prompt: **1. Agent** - A Markdown file containing the system prompt:
```yaml ```yaml
agent: ~/.takt/agents/default/coder.md # Path to agent prompt file agent: ../agents/default/coder.md # Path to agent prompt file
agent_name: coder # Display name (optional) 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 ```yaml
status_rules_prompt: | rules:
Your final output MUST include a status tag: - condition: "Implementation complete"
- `[CODER:DONE]` if implementation is complete next: review
- `[CODER:BLOCKED]` if you cannot proceed - condition: "Cannot proceed"
next: ABORT
``` ```
**3. Transitions** - Route to the next step based on status: Special `next` values: `COMPLETE` (success), `ABORT` (failure).
```yaml **3. Step options:**
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:**
| Option | Default | Description | | 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}` | | `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.) | | `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`) | | `provider` | - | Override provider for this step (`claude` or `codex`) |
| `model` | - | Override model for this step | | `model` | - | Override model for this step |
| `permission_mode` | `default` | Permission mode: `default`, `acceptEdits`, or `bypassPermissions` | | `permission_mode` | `default` | Permission mode: `default`, `acceptEdits`, or `bypassPermissions` |
| `report` | - | Report file configuration (name, format) for auto-generated reports |
## API Usage ## API Usage