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

docs: 古い用語・構造をコードベースの実態に合わせて修正

Browse Source 
- step → movement, agent → persona に用語統一（CLAUDE.md, pieces.md, agents.md）
- Piece YAML Schema にセクションマップ（personas, policies, knowledge, instructions）を反映
- Directory Structure を facets/ 構造に更新
- README の YAML 例から架空の simple ピースを削除
- e2e.md から削除済み export-cc テスト記述を除去
This commit is contained in:
nrslib 2026-02-23 19:38:45 +09:00
parent dfc9263ef0
commit 43c26d7547
6 changed files with 264 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
CLAUDE.md
View File

@ -67,31 +67,31 @@ TAKT (TAKT Agent Koordination Topology) is a multi-agent orchestration system fo
CLI (cli.ts) CLI (cli.ts)
→ Slash commands or executeTask() → Slash commands or executeTask()
→ PieceEngine (piece/engine.ts) → PieceEngine (piece/engine.ts)
→ Per step: 3-phase execution → Per movement: 3-phase execution
Phase 1: runAgent() → main work Phase 1: runAgent() → main work
Phase 2: runReportPhase() → report output (if step.report defined) Phase 2: runReportPhase() → report output (if output_contracts defined)
Phase 3: runStatusJudgmentPhase() → status tag output (if tag-based rules) Phase 3: runStatusJudgmentPhase() → status tag output (if tag-based rules)
→ detectMatchedRule() → rule evaluation → determineNextStep() → detectMatchedRule() → rule evaluation → determineNextStep()
→ Parallel steps: Promise.all() for sub-steps, aggregate evaluation → Parallel movements: Promise.all() for sub-movements, aggregate evaluation
``` ```
### Three-Phase Step Execution ### Three-Phase Movement Execution
Each step executes in up to 3 phases (session is resumed across phases): Each movement executes in up to 3 phases (session is resumed across phases):
| Phase | Purpose | Tools | When | | Phase | Purpose | Tools | When |
|-------|---------|-------|------| |-------|---------|-------|------|
| Phase 1 | Main work (coding, review, etc.) | Step's allowed_tools (Write excluded if report defined) | Always | | Phase 1 | Main work (coding, review, etc.) | Movement's allowed_tools (Write excluded if report defined) | Always |
| Phase 2 | Report output | Write only | When `step.report` is defined | | Phase 2 | Report output | Write only | When `output_contracts` is defined |
| Phase 3 | Status judgment | None (judgment only) | When step has tag-based rules | | Phase 3 | Status judgment | None (judgment only) | When movement has tag-based rules |
Phase 2/3 are implemented in `src/core/piece/engine/phase-runner.ts`. The session is resumed so the agent retains context from Phase 1. Phase 2/3 are implemented in `src/core/piece/engine/phase-runner.ts`. The session is resumed so the agent retains context from Phase 1.
### Rule Evaluation (5-Stage Fallback) ### Rule Evaluation (5-Stage Fallback)
After step execution, rules are evaluated to determine the next step. Evaluation order (first match wins): After movement execution, rules are evaluated to determine the next movement. Evaluation order (first match wins):
1. **Aggregate** (`all()`/`any()`) - For parallel parent steps 1. **Aggregate** (`all()`/`any()`) - For parallel parent movements
2. **Phase 3 tag** - `[STEP:N]` tag from status judgment output 2. **Phase 3 tag** - `[STEP:N]` tag from status judgment output
3. **Phase 1 tag** - `[STEP:N]` tag from main execution output (fallback) 3. **Phase 1 tag** - `[STEP:N]` tag from main execution output (fallback)
4. **AI judge (ai() only)** - AI evaluates `ai("condition text")` rules 4. **AI judge (ai() only)** - AI evaluates `ai("condition text")` rules
@ -103,22 +103,22 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
**PieceEngine** (`src/core/piece/engine/PieceEngine.ts`) **PieceEngine** (`src/core/piece/engine/PieceEngine.ts`)
- State machine that orchestrates agent execution via EventEmitter - State machine that orchestrates agent execution via EventEmitter
- Manages step transitions based on rule evaluation results - Manages movement transitions based on rule evaluation results
- Emits events: `step:start`, `step:complete`, `step:blocked`, `step:loop_detected`, `piece:complete`, `piece:abort`, `iteration:limit` - Emits events: `step:start`, `step:complete`, `step:blocked`, `step:loop_detected`, `piece:complete`, `piece: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 movement for conversation continuity
- Delegates to `StepExecutor` (normal steps) and `ParallelRunner` (parallel steps) - Delegates to `StepExecutor` (normal steps) and `ParallelRunner` (parallel steps)
**StepExecutor** (`src/core/piece/engine/StepExecutor.ts`) **StepExecutor** (`src/core/piece/engine/StepExecutor.ts`)
- Executes a single piece step through the 3-phase model - Executes a single piece movement through the 3-phase model
- Phase 1: Main agent execution (with tools) - Phase 1: Main agent execution (with tools)
- Phase 2: Report output (Write-only, optional) - Phase 2: Report output (Write-only, optional)
- Phase 3: Status judgment (no tools, optional) - Phase 3: Status judgment (no tools, optional)
- Builds instructions via `InstructionBuilder`, detects matched rules via `RuleEvaluator` - Builds instructions via `InstructionBuilder`, detects matched rules via `RuleEvaluator`
**ParallelRunner** (`src/core/piece/engine/ParallelRunner.ts`) **ParallelRunner** (`src/core/piece/engine/ParallelRunner.ts`)
- Executes parallel sub-steps concurrently via `Promise.all()` - Executes parallel sub-movements concurrently via `Promise.all()`
- Aggregates sub-step results for parent rule evaluation - Aggregates sub-movement results for parent rule evaluation
- Supports `all()` / `any()` aggregate conditions - Supports `all()` / `any()` aggregate conditions
**RuleEvaluator** (`src/core/piece/evaluation/RuleEvaluator.ts`) **RuleEvaluator** (`src/core/piece/evaluation/RuleEvaluator.ts`)
@ -141,7 +141,7 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
**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
- **v0.3.8+:** Agent is optional — steps can execute with `instruction_template` only (no system prompt) - **v0.3.8+:** Agent is optional — movements can execute with `instruction_template` only (no system prompt)
- Built-in agents with default tools: - Built-in agents with default tools:
- `coder`: Read/Glob/Grep/Edit/Write/Bash/WebSearch/WebFetch - `coder`: Read/Glob/Grep/Edit/Write/Bash/WebSearch/WebFetch
- `architect`: Read/Glob/Grep/WebSearch/WebFetch - `architect`: Read/Glob/Grep/WebSearch/WebFetch
@ -161,7 +161,7 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
**Configuration** (`src/infra/config/`) **Configuration** (`src/infra/config/`)
- `loaders/loader.ts` - Custom agent loading from `.takt/agents.yaml` - `loaders/loader.ts` - Custom agent loading from `.takt/agents.yaml`
- `loaders/pieceParser.ts` - YAML parsing, step/rule normalization with Zod validation - `loaders/pieceParser.ts` - YAML parsing, movement/rule normalization with Zod validation
- `loaders/pieceResolver.ts` - **3-layer resolution with correct priority** (v0.3.8+: user → project → builtin) - `loaders/pieceResolver.ts` - **3-layer resolution with correct priority** (v0.3.8+: user → project → builtin)
- `loaders/pieceCategories.ts` - Piece categorization and filtering - `loaders/pieceCategories.ts` - Piece categorization and filtering
- `loaders/agentLoader.ts` - Agent prompt file loading - `loaders/agentLoader.ts` - Agent prompt file loading
@ -184,9 +184,9 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
1. User provides task (text or `#N` issue reference) or slash command → CLI 1. User provides task (text or `#N` issue reference) or slash command → CLI
2. CLI loads piece with **correct priority** (v0.3.8+): user `~/.takt/pieces/` → project `.takt/pieces/` → builtin `builtins/{lang}/pieces/` 2. CLI loads piece with **correct priority** (v0.3.8+): user `~/.takt/pieces/` → project `.takt/pieces/` → builtin `builtins/{lang}/pieces/`
3. PieceEngine starts at `initial_step` 3. PieceEngine starts at `initial_movement`
4. Each step: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()` 4. Each movement: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()`
5. Rule evaluation determines next step name (v0.3.8+: uses **last match** when multiple `[STEP:N]` tags appear) 5. Rule evaluation determines next movement name (v0.3.8+: uses **last match** when multiple `[STEP:N]` tags appear)
6. Special transitions: `COMPLETE` ends piece successfully, `ABORT` ends with failure 6. Special transitions: `COMPLETE` ends piece successfully, `ABORT` ends with failure
## Directory Structure ## Directory Structure
@ -195,18 +195,27 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
~/.takt/ # Global user config (created on first run) ~/.takt/ # Global user config (created on first run)
config.yaml # Trusted dirs, default piece, log level, language config.yaml # Trusted dirs, default piece, log level, language
pieces/ # User piece YAML files (override builtins) pieces/ # User piece YAML files (override builtins)
personas/ # User persona prompt files (.md) facets/ # User facets
agents/ # Legacy persona prompts (backward compat) personas/ # User persona prompt files (.md)
policies/ # User policy files
knowledge/ # User knowledge files
instructions/ # User instruction files
output-contracts/ # User output contract files
repertoire/ # Installed repertoire packages
.takt/ # Project-level config .takt/ # Project-level config
config.yaml # Project configuration
agents.yaml # Custom agent definitions agents.yaml # Custom agent definitions
facets/ # Project-level facets
tasks/ # Task files for /run-tasks tasks/ # Task files for /run-tasks
reports/ # Execution reports (auto-generated) runs/ # Execution reports, logs, context
logs/ # Session logs in NDJSON format (gitignored) logs/ # Session logs in NDJSON format (gitignored)
builtins/ # Bundled defaults (builtin, read from dist/ at runtime) builtins/ # Bundled defaults (builtin, read from dist/ at runtime)
en/ # English personas, policies, instructions, and pieces en/ # English
ja/ # Japanese personas, policies, instructions, and pieces facets/ # Facets (personas, policies, knowledge, instructions, output-contracts)
pieces/ # Piece YAML files
ja/ # Japanese (same structure)
project/ # Project-level template files project/ # Project-level template files
skill/ # Claude Code skill files skill/ # Claude Code skill files
``` ```
@ -219,51 +228,68 @@ Builtin resources are embedded in the npm package (`builtins/`). User files in `
name: piece-name name: piece-name
description: Optional description description: Optional description
max_movements: 10 max_movements: 10
initial_step: plan # First step to execute initial_movement: plan # First movement to execute
steps: # Section maps (key → file path relative to piece YAML directory)
# Normal step personas:
- name: step-name coder: ../facets/personas/coder.md
persona: ../personas/coder.md # Path to persona prompt reviewer: ../facets/personas/architecture-reviewer.md
policies:
coding: ../facets/policies/coding.md
knowledge:
architecture: ../facets/knowledge/architecture.md
instructions:
plan: ../facets/instructions/plan.md
report_formats:
plan: ../facets/output-contracts/plan.md
movements:
# Normal movement
- name: movement-name
persona: coder # Persona key (references section map)
persona_name: coder # Display name (optional) persona_name: coder # Display name (optional)
provider: codex # claude|codex (optional) policy: coding # Policy key (single or array)
knowledge: architecture # Knowledge key (single or array)
instruction: plan # Instruction key (references section map)
provider: codex # claude|codex|opencode (optional)
model: opus # Model name (optional) model: opus # Model name (optional)
edit: true # Whether step can edit files edit: true # Whether movement can edit files
required_permission_mode: edit # Required minimum permission mode (optional) required_permission_mode: edit # Required minimum permission mode (optional)
instruction_template: | instruction_template: |
Custom instructions for this step. Custom instructions for this movement.
{task}, {previous_response} are auto-injected if not present as placeholders. {task}, {previous_response} are auto-injected if not present as placeholders.
pass_previous_response: true # Default: true pass_previous_response: true # Default: true
report: output_contracts:
name: 01-plan.md # Report file name report:
format: | # Output contract template - name: 01-plan.md # Report file name
# Plan Report format: plan # References report_formats map
...
rules: rules:
- condition: "Human-readable condition" - condition: "Human-readable condition"
next: next-step-name next: next-movement-name
- condition: ai("AI evaluates this condition text") - condition: ai("AI evaluates this condition text")
next: other-step next: other-movement
- condition: blocked - condition: blocked
next: ABORT next: ABORT
# Parallel step (sub-steps execute concurrently) # Parallel movement (sub-movements execute concurrently)
- name: reviewers - name: reviewers
parallel: parallel:
- name: arch-review - name: arch-review
persona: ../personas/architecture-reviewer.md persona: reviewer
policy: review
knowledge: architecture
edit: false
rules: rules:
- condition: approved # next is optional for sub-steps - condition: approved # next is optional for sub-movements
- condition: needs_fix - condition: needs_fix
instruction_template: | instruction: review-arch
Review architecture...
- name: security-review - name: security-review
persona: ../personas/security-reviewer.md persona: security-reviewer
edit: false
rules: rules:
- condition: approved - condition: approved
- condition: needs_fix - condition: needs_fix
instruction_template: | instruction: review-security
Review security...
rules: # Parent rules use aggregate conditions rules: # Parent rules use aggregate conditions
- condition: all("approved") - condition: all("approved")
next: supervise next: supervise
@ -271,11 +297,11 @@ steps:
next: fix next: fix
``` ```
Key points about parallel steps: Key points about parallel movements:
- Sub-step `rules` define possible outcomes but `next` is ignored (parent handles routing) - Sub-movement `rules` define possible outcomes but `next` is ignored (parent handles routing)
- Parent `rules` use `all("X")`/`any("X")` to aggregate sub-step results - Parent `rules` use `all("X")`/`any("X")` to aggregate sub-movement results
- `all("X")`: true if ALL sub-steps matched condition X - `all("X")`: true if ALL sub-movements matched condition X
- `any("X")`: true if ANY sub-step matched condition X - `any("X")`: true if ANY sub-movements matched condition X
### Rule Condition Types ### Rule Condition Types
@ -283,7 +309,7 @@ Key points about parallel steps:
|------|--------|------------| |------|--------|------------|
| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index | | Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
| AI judge | `ai("condition text")` | AI evaluates condition against agent output | | AI judge | `ai("condition text")` | AI evaluates condition against agent output |
| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step matched conditions | | Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-movement matched conditions |
### Template Variables ### Template Variables
@ -292,8 +318,8 @@ Key points about parallel steps:
| `{task}` | Original user request (auto-injected if not in template) | | `{task}` | Original user request (auto-injected if not in template) |
| `{iteration}` | Piece-wide iteration count | | `{iteration}` | Piece-wide iteration count |
| `{max_movements}` | Maximum movements allowed | | `{max_movements}` | Maximum movements allowed |
| `{step_iteration}` | Per-step iteration count | | `{movement_iteration}` | Per-movement iteration count |
| `{previous_response}` | Previous step output (auto-injected if not in template) | | `{previous_response}` | Previous movement output (auto-injected if not in template) |
| `{user_inputs}` | Accumulated user inputs (auto-injected if not in template) | | `{user_inputs}` | Accumulated user inputs (auto-injected if not in template) |
| `{report_dir}` | Report directory name | | `{report_dir}` | Report directory name |
@ -313,7 +339,7 @@ Example category config:
```yaml ```yaml
piece_categories: piece_categories:
Development: Development:
pieces: [default, simple] pieces: [default, default-mini]
children: children:
Backend: Backend:
pieces: [expert-cqrs] pieces: [expert-cqrs]
@ -331,7 +357,7 @@ Implemented in `src/infra/config/loaders/pieceCategories.ts`.
Model is resolved in the following priority order: Model is resolved in the following priority order:
1. **Piece step `model`** - Highest priority (specified in step YAML) 1. **Piece movement `model`** - Highest priority (specified in movement YAML)
2. **Custom agent `model`** - Agent-level model in `.takt/agents.yaml` 2. **Custom agent `model`** - Agent-level model in `.takt/agents.yaml`
3. **Global config `model`** - Default model in `~/.takt/config.yaml` 3. **Global config `model`** - Default model in `~/.takt/config.yaml`
4. **Provider default** - Falls back to provider's default (Claude: sonnet, Codex: gpt-5.2-codex) 4. **Provider default** - Falls back to provider's default (Claude: sonnet, Codex: gpt-5.2-codex)
@ -339,7 +365,7 @@ Model is resolved in the following priority order:
Example `~/.takt/config.yaml`: Example `~/.takt/config.yaml`:
```yaml ```yaml
provider: claude provider: claude
model: opus # Default model for all steps (unless overridden) model: opus # Default model for all movements (unless overridden)
``` ```
## NDJSON Session Logging ## NDJSON Session Logging
@ -369,16 +395,16 @@ Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json
**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 `pieceParser.ts`. **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 `pieceParser.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. **Instruction auto-injection over explicit placeholders.** The instruction builder auto-injects `{task}`, `{previous_response}`, `{user_inputs}`, and status rules. Templates should contain only movement-specific instructions, not boilerplate.
**Faceted prompting: each facet has a dedicated file type.** TAKT assembles agent prompts from 4 facets. Each facet has a distinct role. When adding new rules or knowledge, place content in the correct facet. **Faceted prompting: each facet has a dedicated file type.** TAKT assembles agent prompts from 4 facets. Each facet has a distinct role. When adding new rules or knowledge, place content in the correct facet.
``` ```
builtins/{lang}/ builtins/{lang}/facets/
personas/ — WHO: identity, expertise, behavioral habits personas/ — WHO: identity, expertise, behavioral habits
policies/ — HOW: judgment criteria, REJECT/APPROVE rules, prohibited patterns policies/ — HOW: judgment criteria, REJECT/APPROVE rules, prohibited patterns
knowledge/ — WHAT TO KNOW: domain patterns, anti-patterns, detailed reasoning with examples knowledge/ — WHAT TO KNOW: domain patterns, anti-patterns, detailed reasoning with examples
instructions/ — WHAT TO DO NOW: step-specific procedures and checklists instructions/ — WHAT TO DO NOW: movement-specific procedures and checklists
``` ```
| Deciding where to place content | Facet | Example | | Deciding where to place content | Facet | Example |
@ -386,20 +412,20 @@ builtins/{lang}/
| Role definition, AI habit prevention | Persona | "置き換えたコードを残す → 禁止" | | Role definition, AI habit prevention | Persona | "置き換えたコードを残す → 禁止" |
| Actionable REJECT/APPROVE criterion | Policy | "内部実装のパブリックAPIエクスポート → REJECT" | | Actionable REJECT/APPROVE criterion | Policy | "内部実装のパブリックAPIエクスポート → REJECT" |
| Detailed reasoning, REJECT/OK table with examples | Knowledge | "パブリックAPIの公開範囲" section | | Detailed reasoning, REJECT/OK table with examples | Knowledge | "パブリックAPIの公開範囲" section |
| This-step-only procedure or checklist | Instruction | "レビュー観点: 構造・設計の妥当性..." | | This-movement-only procedure or checklist | Instruction | "レビュー観点: 構造・設計の妥当性..." |
| Workflow structure, facet assignment | Piece YAML | `persona: coder`, `policy: coding`, `knowledge: architecture` | | Workflow structure, facet assignment | Piece YAML | `persona: coder`, `policy: coding`, `knowledge: architecture` |
Key rules: Key rules:
- Persona files are reusable across pieces. Never include piece-specific procedures (report names, step references) - Persona files are reusable across pieces. Never include piece-specific procedures (report names, movement references)
- Policy REJECT lists are what reviewers enforce. If a criterion is not in the policy REJECT list, reviewers will not catch it — even if knowledge explains the reasoning - Policy REJECT lists are what reviewers enforce. If a criterion is not in the policy REJECT list, reviewers will not catch it — even if knowledge explains the reasoning
- Knowledge provides the WHY behind policy criteria. Knowledge alone does not trigger enforcement - Knowledge provides the WHY behind policy criteria. Knowledge alone does not trigger enforcement
- Instructions are bound to a single piece step. They reference procedures, not principles - Instructions are bound to a single piece movement. They reference procedures, not principles
- Piece YAML `instruction_template` is for step-specific details (which reports to read, step routing, output templates) - Piece YAML `instruction_template` is for movement-specific details (which reports to read, movement routing, output templates)
**Separation of concerns in piece engine:** **Separation of concerns in piece engine:**
- `PieceEngine` - Orchestration, state management, event emission - `PieceEngine` - Orchestration, state management, event emission
- `StepExecutor` - Single step execution (3-phase model) - `StepExecutor` - Single movement execution (3-phase model)
- `ParallelRunner` - Parallel step execution - `ParallelRunner` - Parallel movement execution
- `RuleEvaluator` - Rule matching and evaluation - `RuleEvaluator` - Rule matching and evaluation
- `InstructionBuilder` - Instruction template processing - `InstructionBuilder` - Instruction template processing
@ -460,14 +486,14 @@ Debug logs are written to `.takt/logs/debug.log` (ndjson format). Log levels: `d
**Persona prompt resolution:** **Persona prompt resolution:**
- Persona paths in piece YAML are resolved relative to the piece file's directory - Persona paths in piece YAML are resolved relative to the piece file's directory
- `../personas/coder.md` resolves from piece file location - `../facets/personas/coder.md` resolves from piece file location
- Built-in personas are loaded from `builtins/{lang}/personas/` - Built-in personas are loaded from `builtins/{lang}/facets/personas/`
- User personas are loaded from `~/.takt/personas/` (legacy: `~/.takt/agents/`) - User personas are loaded from `~/.takt/facets/personas/`
- If persona file doesn't exist, the persona string is used as inline system prompt - If persona file doesn't exist, the persona string is used as inline system prompt
**Report directory structure:** **Report directory structure:**
- Report dirs are created at `.takt/runs/{timestamp}-{slug}/reports/` - Report dirs are created at `.takt/runs/{timestamp}-{slug}/reports/`
- Report files specified in `step.report` are written relative to report dir - Report files specified in `output_contracts` are written relative to report dir
- Report dir path is available as `{report_dir}` variable in instruction templates - Report dir path is available as `{report_dir}` variable in instruction templates
- When `cwd !== projectCwd` (worktree execution), reports write to `cwd/.takt/runs/{slug}/reports/` (clone dir) to prevent agents from discovering the main repository path - When `cwd !== projectCwd` (worktree execution), reports write to `cwd/.takt/runs/{slug}/reports/` (clone dir) to prevent agents from discovering the main repository path
@ -489,13 +515,13 @@ Debug logs are written to `.takt/logs/debug.log` (ndjson format). Log levels: `d
- Tag-based rules match by array index (0-based), not by exact condition text - Tag-based rules match by array index (0-based), not by exact condition text
- **v0.3.8+:** When multiple `[STEP:N]` tags appear in output, **last match wins** (not first) - **v0.3.8+:** When multiple `[STEP:N]` tags appear in output, **last match wins** (not first)
- `ai()` conditions are evaluated by Claude/Codex, not by string matching - `ai()` conditions are evaluated by Claude/Codex, not by string matching
- Aggregate conditions (`all()`, `any()`) only work in parallel parent steps - Aggregate conditions (`all()`, `any()`) only work in parallel parent movements
- Fail-fast: if rules exist but no rule matches, piece aborts - Fail-fast: if rules exist but no rule matches, piece aborts
- Interactive-only rules are skipped in pipeline mode (`rule.interactiveOnly === true`) - Interactive-only rules are skipped in pipeline mode (`rule.interactiveOnly === true`)
**Provider-specific behavior:** **Provider-specific behavior:**
- Claude: Uses session files in `~/.claude/projects/`, supports skill/agent calls - Claude: Uses session files in `~/.claude/projects/`
- Codex: In-memory sessions, no skill/agent calls - Codex: In-memory sessions
- Model names are passed directly to provider (no alias resolution in TAKT) - Model names are passed directly to provider (no alias resolution in TAKT)
- Claude supports aliases: `opus`, `sonnet`, `haiku` - Claude supports aliases: `opus`, `sonnet`, `haiku`
- Codex defaults to `codex` if model not specified - Codex defaults to `codex` if model not specified

10
README.md
View File

@ -88,13 +88,14 @@ TAKT uses a music metaphor: **piece** = workflow, **movement** = step.
A piece defines a sequence of movements. Each movement specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example: A piece defines a sequence of movements. Each movement specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:
```yaml ```yaml
name: simple name: plan-implement-review
initial_movement: plan initial_movement: plan
max_movements: 10
personas: personas:
planner: ../personas/planner.md planner: ../facets/personas/planner.md
coder: ../personas/coder.md coder: ../facets/personas/coder.md
reviewer: ../personas/architecture-reviewer.md reviewer: ../facets/personas/architecture-reviewer.md
movements: movements:
- name: plan - name: plan
@ -107,6 +108,7 @@ movements:
- name: implement - name: implement
persona: coder persona: coder
edit: true edit: true
required_permission_mode: edit
rules: rules:
- condition: Implementation complete - condition: Implementation complete
next: review next: review

10
docs/README.ja.md
View File

@ -100,13 +100,14 @@ TAKT は音楽のメタファーを使っています。**piece** がワーク
piece は movement の並びを定義します。各 movement では persona（誰が実行するか）、権限（何を許可するか）、ルール（次にどこへ進むか）を指定します。 piece は movement の並びを定義します。各 movement では persona（誰が実行するか）、権限（何を許可するか）、ルール（次にどこへ進むか）を指定します。
```yaml ```yaml
name: simple name: plan-implement-review
initial_movement: plan initial_movement: plan
max_movements: 10
personas: personas:
planner: ../personas/planner.md planner: ../facets/personas/planner.md
coder: ../personas/coder.md coder: ../facets/personas/coder.md
reviewer: ../personas/architecture-reviewer.md reviewer: ../facets/personas/architecture-reviewer.md
movements: movements:
- name: plan - name: plan
@ -119,6 +120,7 @@ movements:
- name: implement - name: implement
persona: coder persona: coder
edit: true edit: true
required_permission_mode: edit
rules: rules:
- condition: Implementation complete - condition: Implementation complete
next: review next: review

65
docs/agents.md
View File

@ -2,12 +2,12 @@
This guide explains how to configure and create custom agents in TAKT. This guide explains how to configure and create custom agents in TAKT.
## Built-in Agents ## Built-in Personas
TAKT includes six built-in agents (located in `resources/global/{lang}/agents/default/`): TAKT includes built-in personas (located in `builtins/{lang}/facets/personas/`):
| Agent | Description | | Persona | Description |
|-------|-------------| |---------|-------------|
| **planner** | Task analysis, spec investigation, and implementation planning | | **planner** | Task analysis, spec investigation, and implementation planning |
| **coder** | Implements features and fixes bugs | | **coder** | Implements features and fixes bugs |
| **ai-antipattern-reviewer** | Reviews for AI-specific anti-patterns (hallucinated APIs, incorrect assumptions, scope creep) | | **ai-antipattern-reviewer** | Reviews for AI-specific anti-patterns (hallucinated APIs, incorrect assumptions, scope creep) |
@ -15,26 +15,38 @@ TAKT includes six built-in agents (located in `resources/global/{lang}/agents/de
| **security-reviewer** | Security vulnerability assessment | | **security-reviewer** | Security vulnerability assessment |
| **supervisor** | Final verification, validation, and approval | | **supervisor** | Final verification, validation, and approval |
## Specifying Agents ## Specifying Personas
In piece YAML, agents are specified by file path: In piece YAML, personas are specified via section maps:
```yaml ```yaml
# Relative to piece file directory # Section map at top level (key → file path relative to piece YAML)
agent: ../agents/default/coder.md personas:
coder: ../facets/personas/coder.md
reviewer: ../facets/personas/architecture-reviewer.md
# Home directory movements:
agent: ~/.takt/agents/default/coder.md - name: implement
persona: coder # References the key in section map
# Absolute path - name: review
agent: /path/to/custom/agent.md persona: reviewer # References the key in section map
``` ```
## Creating Custom Agents Alternatively, use file paths directly:
### Agent Prompt File ```yaml
movements:
- name: implement
persona: ../facets/personas/coder.md # Relative to piece file
- name: review
persona: ~/.takt/facets/personas/my-reviewer.md # User custom
```
Create a Markdown file with your agent's instructions: ## Creating Custom Personas
### Persona Prompt File
Create a Markdown file with your persona's instructions:
```markdown ```markdown
# Security Reviewer # Security Reviewer
@ -52,7 +64,7 @@ You are a security-focused code reviewer.
- Verify proper error handling - Verify proper error handling
``` ```
> **Note**: Agents do NOT need to output status markers manually. The piece engine auto-injects status output rules into agent instructions based on the step's `rules` configuration. Agents output `[STEP:N]` tags (where N is the 0-based rule index) which the engine uses for routing. > **Note**: Personas do NOT need to output status markers manually. The piece engine auto-injects status output rules into agent instructions based on the movement's `rules` configuration. Agents output `[STEP:N]` tags (where N is the 0-based rule index) which the engine uses for routing.
### Using agents.yaml ### Using agents.yaml
@ -66,7 +78,7 @@ agents:
- Read - Read
- Glob - Glob
- Grep - Grep
provider: claude # Optional: claude or codex provider: claude # Optional: claude, codex, or opencode
model: opus # Optional: model alias or full name model: opus # Optional: model alias or full name
``` ```
@ -74,13 +86,11 @@ agents:
| Field | Description | | Field | Description |
|-------|-------------| |-------|-------------|
| `name` | Agent identifier (referenced in piece steps) | | `name` | Agent identifier (referenced in piece movements) |
| `prompt_file` | Path to Markdown prompt file | | `prompt_file` | Path to Markdown prompt file |
| `prompt` | Inline prompt text (alternative to `prompt_file`) | | `prompt` | Inline prompt text (alternative to `prompt_file`) |
| `allowed_tools` | List of tools the agent can use | | `allowed_tools` | List of tools the agent can use |
| `claude_agent` | Claude Code agent name (for Claude Code native agents) | | `provider` | Provider override: `claude`, `codex`, or `opencode` |
| `claude_skill` | Claude Code skill name (for Claude Code native skills) |
| `provider` | Provider override: `claude` or `codex` |
| `model` | Model override (alias or full name) | | `model` | Model override (alias or full name) |
### Available Tools ### Available Tools
@ -100,7 +110,7 @@ agents:
2. **Minimal tools** — Grant only necessary permissions 2. **Minimal tools** — Grant only necessary permissions
3. **Use `edit: false`** — Review agents should not modify files 3. **Use `edit: false`** — Review agents should not modify files
4. **Focused scope** — One agent, one responsibility 4. **Focused scope** — One agent, one responsibility
5. **Customize via `/eject`** — Copy builtin agents to `~/.takt/` for modification rather than writing from scratch 5. **Customize via `/eject`** — Copy builtin personas to `~/.takt/` for modification rather than writing from scratch
## Example: Multi-Reviewer Setup ## Example: Multi-Reviewer Setup
@ -114,9 +124,12 @@ agents:
```yaml ```yaml
# piece.yaml # piece.yaml
steps: personas:
coder: ../facets/personas/coder.md
movements:
- name: implement - name: implement
agent: ../agents/default/coder.md persona: coder
edit: true edit: true
rules: rules:
- condition: Implementation complete - condition: Implementation complete
@ -125,7 +138,7 @@ steps:
next: ABORT next: ABORT
- name: review - name: review
agent: performance-reviewer persona: performance-reviewer # References agents.yaml by name
edit: false edit: false
rules: rules:
- condition: Approved - condition: Approved

178
docs/pieces.md
View File

@ -4,10 +4,10 @@ This guide explains how to create and customize TAKT pieces.
## Piece Basics ## Piece Basics
A piece is a YAML file that defines a sequence of steps executed by AI agents. Each step specifies: A piece is a YAML file that defines a sequence of movements executed by AI agents. Each movement specifies:
- Which agent to use - Which persona to use
- What instructions to give - What instructions to give
- Rules for routing to the next step - Rules for routing to the next movement
## File Locations ## File Locations
@ -17,8 +17,8 @@ A piece is a YAML file that defines a sequence of steps executed by AI agents. E
## Piece Categories ## Piece Categories
ピースの選択 UI をカテゴリ分けしたい場合は、`piece_categories` を設定します。 To organize the piece selection UI into categories, configure `piece_categories`.
詳細は `docs/piece-categories.md` を参照してください。 See `docs/piece-categories.md` for details.
## Piece Schema ## Piece Schema
@ -26,14 +26,34 @@ A piece is a YAML file that defines a sequence of steps executed by AI agents. E
name: my-piece name: my-piece
description: Optional description description: Optional description
max_movements: 10 max_movements: 10
initial_step: first-step # Optional, defaults to first step initial_movement: first-movement # Optional, defaults to first movement
steps: # Section maps (key → file path relative to piece YAML directory)
- name: step-name personas:
agent: ../agents/default/coder.md # Path to agent prompt file planner: ../facets/personas/planner.md
agent_name: coder # Display name (optional) coder: ../facets/personas/coder.md
edit: true # Whether the step can edit files reviewer: ../facets/personas/architecture-reviewer.md
allowed_tools: # Optional tool allowlist policies:
coding: ../facets/policies/coding.md
review: ../facets/policies/review.md
knowledge:
architecture: ../facets/knowledge/architecture.md
instructions:
plan: ../facets/instructions/plan.md
implement: ../facets/instructions/implement.md
report_formats:
plan: ../facets/output-contracts/plan.md
movements:
- name: movement-name
persona: coder # Persona key (references personas map)
persona_name: coder # Display name (optional)
policy: coding # Policy key (single or array)
knowledge: architecture # Knowledge key (single or array)
instruction: implement # Instruction key (references instructions map)
edit: true # Whether the movement can edit files
required_permission_mode: edit # Minimum permission: readonly, edit, or full
allowed_tools: # Optional tool allowlist
- Read - Read
- Glob - Glob
- Grep - Grep
@ -42,31 +62,37 @@ steps:
- Bash - Bash
rules: rules:
- condition: "Implementation complete" - condition: "Implementation complete"
next: next-step next: next-movement
- condition: "Cannot proceed" - condition: "Cannot proceed"
next: ABORT next: ABORT
instruction_template: | instruction_template: | # Inline instructions (alternative to instruction key)
Your instructions here with {variables} Your instructions here with {variables}
output_contracts: # Report file configuration
report:
- name: 00-plan.md
format: plan # References report_formats map
``` ```
Movements reference section maps by key name (e.g., `persona: coder`), not by file path. Paths in section maps are resolved relative to the piece YAML file's directory.
## Available Variables ## Available Variables
| Variable | Description | | Variable | Description |
|----------|-------------| |----------|-------------|
| `{task}` | Original user request (auto-injected if not in template) | | `{task}` | Original user request (auto-injected if not in template) |
| `{iteration}` | Piece-wide turn count (total steps executed) | | `{iteration}` | Piece-wide turn count (total movements executed) |
| `{max_movements}` | Maximum movements allowed | | `{max_movements}` | Maximum movements allowed |
| `{step_iteration}` | Per-step iteration count (how many times THIS step has run) | | `{movement_iteration}` | Per-movement iteration count (how many times THIS movement has run) |
| `{previous_response}` | Previous step's output (auto-injected if not in template) | | `{previous_response}` | Previous movement's output (auto-injected if not in template) |
| `{user_inputs}` | Additional user inputs during piece (auto-injected if not in template) | | `{user_inputs}` | Additional user inputs during piece (auto-injected if not in template) |
| `{report_dir}` | Report directory path (e.g., `.takt/runs/20250126-143052-task-summary/reports`) | | `{report_dir}` | Report directory path (e.g., `.takt/runs/20250126-143052-task-summary/reports`) |
| `{report:filename}` | Resolves to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) | | `{report:filename}` | Inline the content of `{report_dir}/filename` |
> **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. > **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.
## Rules ## Rules
Rules define how each step routes to the next step. The instruction builder auto-injects status output rules so agents know what tags to output. Rules define how each movement routes to the next movement. The instruction builder auto-injects status output rules so agents know what tags to output.
```yaml ```yaml
rules: rules:
@ -84,7 +110,7 @@ rules:
|------|--------|-------------| |------|--------|-------------|
| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index | | Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
| AI judge | `ai("condition text")` | AI evaluates the condition against agent output | | AI judge | `ai("condition text")` | AI evaluates the condition against agent output |
| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step results | | Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-movement results |
### Special `next` Values ### Special `next` Values
@ -95,74 +121,83 @@ rules:
The optional `appendix` field provides a template for additional AI output when that rule is matched. Useful for structured error reporting or requesting specific information. The optional `appendix` field provides a template for additional AI output when that rule is matched. Useful for structured error reporting or requesting specific information.
## Parallel Steps ## Parallel Movements
Steps can execute sub-steps concurrently with aggregate evaluation: Movements can execute sub-movements concurrently with aggregate evaluation:
```yaml ```yaml
- name: reviewers - name: reviewers
parallel: parallel:
- name: arch-review - name: arch-review
agent: ../agents/default/architecture-reviewer.md persona: architecture-reviewer
policy: review
knowledge: architecture
edit: false edit: false
rules: rules:
- condition: approved - condition: approved
- condition: needs_fix - condition: needs_fix
instruction_template: | instruction: review-arch
Review architecture and code quality.
- name: security-review - name: security-review
agent: ../agents/default/security-reviewer.md persona: security-reviewer
policy: review
edit: false edit: false
rules: rules:
- condition: approved - condition: approved
- condition: needs_fix - condition: needs_fix
instruction_template: | instruction: review-security
Review for security vulnerabilities.
rules: rules:
- condition: all("approved") - condition: all("approved")
next: supervise next: COMPLETE
- condition: any("needs_fix") - condition: any("needs_fix")
next: fix next: fix
``` ```
- `all("X")`: true if ALL sub-steps matched condition X - `all("X")`: true if ALL sub-movements matched condition X
- `any("X")`: true if ANY sub-step matched condition X - `any("X")`: true if ANY sub-movement matched condition X
- Sub-step `rules` define possible outcomes; `next` is optional (parent handles routing) - Sub-movement `rules` define possible outcomes; `next` is optional (parent handles routing)
## Report Files ## Output Contracts (Report Files)
Steps can generate report files in the report directory: Movements can generate report files in the report directory:
```yaml ```yaml
# Single report file # Single report with format specification (references report_formats map)
report: 00-plan.md output_contracts:
report:
- name: 00-plan.md
format: plan
# Single report with format specification # Single report with inline format
report: output_contracts:
name: 00-plan.md report:
format: | - name: 00-plan.md
```markdown format: |
# Plan # Plan
... ...
```
# Multiple report files # Multiple report files with labels
report: output_contracts:
- Scope: 01-scope.md report:
- Decisions: 02-decisions.md - Scope: 01-scope.md
- Decisions: 02-decisions.md
``` ```
## Step Options ## Movement Options
| Option | Default | Description | | Option | Default | Description |
|--------|---------|-------------| |--------|---------|-------------|
| `edit` | - | Whether the step can edit project files (`true`/`false`) | | `persona` | - | Persona key (references section map) or file path |
| `pass_previous_response` | `true` | Pass previous step's output to `{previous_response}` | | `policy` | - | Policy key or array of keys |
| `knowledge` | - | Knowledge key or array of keys |
| `instruction` | - | Instruction key (references section map) |
| `edit` | - | Whether the movement can edit project files (`true`/`false`) |
| `pass_previous_response` | `true` | Pass previous movement's output to `{previous_response}` |
| `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 movement (`claude`, `codex`, or `opencode`) |
| `model` | - | Override model for this step | | `model` | - | Override model for this movement |
| `required_permission_mode` | - | Required minimum permission mode: `readonly`, `edit`, or `full` (provider-independent) | | `required_permission_mode` | - | Required minimum permission mode: `readonly`, `edit`, or `full` |
| `report` | - | Report file configuration (name, format) for auto-generated reports | | `output_contracts` | - | Report file configuration (name, format) |
| `quality_gates` | - | Quality criteria for movement completion (AI instruction) |
## Examples ## Examples
@ -172,9 +207,12 @@ report:
name: simple-impl name: simple-impl
max_movements: 5 max_movements: 5
steps: personas:
coder: ../facets/personas/coder.md
movements:
- name: implement - name: implement
agent: ../agents/default/coder.md persona: coder
edit: true edit: true
required_permission_mode: edit required_permission_mode: edit
allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch] allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
@ -193,9 +231,13 @@ steps:
name: with-review name: with-review
max_movements: 10 max_movements: 10
steps: personas:
coder: ../facets/personas/coder.md
reviewer: ../facets/personas/architecture-reviewer.md
movements:
- name: implement - name: implement
agent: ../agents/default/coder.md persona: coder
edit: true edit: true
required_permission_mode: edit required_permission_mode: edit
allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch] allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
@ -208,7 +250,7 @@ steps:
Implement the requested changes. Implement the requested changes.
- name: review - name: review
agent: ../agents/default/architecture-reviewer.md persona: reviewer
edit: false edit: false
allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch] allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
rules: rules:
@ -220,12 +262,16 @@ steps:
Review the implementation for code quality and best practices. Review the implementation for code quality and best practices.
``` ```
### Passing Data Between Steps ### Passing Data Between Movements
```yaml ```yaml
steps: personas:
planner: ../facets/personas/planner.md
coder: ../facets/personas/coder.md
movements:
- name: analyze - name: analyze
agent: ../agents/default/planner.md persona: planner
edit: false edit: false
allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch] allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
rules: rules:
@ -235,7 +281,7 @@ steps:
Analyze this request and create a plan. Analyze this request and create a plan.
- name: implement - name: implement
agent: ../agents/default/coder.md persona: coder
edit: true edit: true
pass_previous_response: true pass_previous_response: true
required_permission_mode: edit required_permission_mode: edit
@ -251,7 +297,7 @@ steps:
## Best Practices ## Best Practices
1. **Keep iterations reasonable** — 10-30 is typical for development pieces 1. **Keep iterations reasonable** — 10-30 is typical for development pieces
2. **Use `edit: false` for review steps** — Prevent reviewers from modifying code 2. **Use `edit: false` for review movements** — Prevent reviewers from modifying code
3. **Use descriptive step names** — Makes logs easier to read 3. **Use descriptive movement names** — Makes logs easier to read
4. **Test pieces incrementally** — Start simple, add complexity 4. **Test pieces incrementally** — Start simple, add complexity
5. **Use `/eject` to customize** — Copy a builtin as starting point rather than writing from scratch 5. **Use `/eject` to customize** — Copy a builtin as starting point rather than writing from scratch

10
docs/testing/e2e.md
View File

@ -160,16 +160,6 @@ E2Eテストを追加・変更した場合は、このドキュメントも更
- 出力に `reset` と `backup:` を含むことを確認する。 - 出力に `reset` と `backup:` を含むことを確認する。
- `$TAKT_CONFIG_DIR/config.yaml` がテンプレート内容（例: `branch_name_strategy: ai`, `concurrency: 2`）に置き換わっていることを確認する。 - `$TAKT_CONFIG_DIR/config.yaml` がテンプレート内容（例: `branch_name_strategy: ai`, `concurrency: 2`）に置き換わっていることを確認する。
- `$TAKT_CONFIG_DIR/` 直下に `config.yaml.YYYYMMDD-HHmmss.old` 形式のバックアップファイルが1件作成されることを確認する。 - `$TAKT_CONFIG_DIR/` 直下に `config.yaml.YYYYMMDD-HHmmss.old` 形式のバックアップファイルが1件作成されることを確認する。
- Export Claude Code Skill（`e2e/specs/cli-export-cc.e2e.ts`）
- 目的: `takt export-cc` でClaude Code Skillのデプロイを確認。
- LLM: 呼び出さない（LLM不使用の操作のみ）
- 手順（ユーザー行動/コマンド）:
- `HOME` を一時ディレクトリに設定する。
- `takt export-cc` を実行する。
- 出力に `ファイルをデプロイしました` を含むことを確認する。
- `$HOME/.claude/skills/takt/SKILL.md` が存在することを確認する。
- `$HOME/.claude/skills/takt/pieces/` および `$HOME/.claude/skills/takt/personas/` ディレクトリが存在し、それぞれ少なくとも1ファイルを含むことを確認する。
## 追記シナリオ（2026-02-19） ## 追記シナリオ（2026-02-19）
過去にドキュメント未反映だったシナリオを以下に追記する。 過去にドキュメント未反映だったシナリオを以下に追記する。