From 43c26d754752a0016ff46954f04583fb050f2101 Mon Sep 17 00:00:00 2001 From: nrslib <38722970+nrslib@users.noreply.github.com> Date: Mon, 23 Feb 2026 19:38:45 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=8F=A4=E3=81=84=E7=94=A8=E8=AA=9E?= =?UTF-8?q?=E3=83=BB=E6=A7=8B=E9=80=A0=E3=82=92=E3=82=B3=E3=83=BC=E3=83=89?= =?UTF-8?q?=E3=83=99=E3=83=BC=E3=82=B9=E3=81=AE=E5=AE=9F=E6=85=8B=E3=81=AB?= =?UTF-8?q?=E5=90=88=E3=82=8F=E3=81=9B=E3=81=A6=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 テスト記述を除去 --- CLAUDE.md | 176 ++++++++++++++++++++++++------------------- README.md | 10 ++- docs/README.ja.md | 10 ++- docs/agents.md | 65 +++++++++------- docs/pieces.md | 178 ++++++++++++++++++++++++++++---------------- docs/testing/e2e.md | 10 --- 6 files changed, 264 insertions(+), 185 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 56f9f2d..40e76fb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -67,31 +67,31 @@ TAKT (TAKT Agent Koordination Topology) is a multi-agent orchestration system fo CLI (cli.ts) → Slash commands or executeTask() → PieceEngine (piece/engine.ts) - → Per step: 3-phase execution + → Per movement: 3-phase execution 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) → 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 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 1 | Main work (coding, review, etc.) | Movement's allowed_tools (Write excluded if report defined) | Always | +| Phase 2 | Report output | Write only | When `output_contracts` is defined | +| 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. ### 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 3. **Phase 1 tag** - `[STEP:N]` tag from main execution output (fallback) 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`) - 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` - 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) **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 2: Report output (Write-only, optional) - Phase 3: Status judgment (no tools, optional) - Builds instructions via `InstructionBuilder`, detects matched rules via `RuleEvaluator` **ParallelRunner** (`src/core/piece/engine/ParallelRunner.ts`) -- Executes parallel sub-steps concurrently via `Promise.all()` -- Aggregates sub-step results for parent rule evaluation +- Executes parallel sub-movements concurrently via `Promise.all()` +- Aggregates sub-movement results for parent rule evaluation - Supports `all()` / `any()` aggregate conditions **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`) - 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: - `coder`: Read/Glob/Grep/Edit/Write/Bash/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/`) - `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/pieceCategories.ts` - Piece categorization and filtering - `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 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` -4. Each step: `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) +3. PieceEngine starts at `initial_movement` +4. Each movement: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()` +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 ## 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) config.yaml # Trusted dirs, default piece, log level, language pieces/ # User piece YAML files (override builtins) - personas/ # User persona prompt files (.md) - agents/ # Legacy persona prompts (backward compat) + facets/ # User facets + 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 + config.yaml # Project configuration agents.yaml # Custom agent definitions + facets/ # Project-level facets tasks/ # Task files for /run-tasks - reports/ # Execution reports (auto-generated) + runs/ # Execution reports, logs, context logs/ # Session logs in NDJSON format (gitignored) builtins/ # Bundled defaults (builtin, read from dist/ at runtime) - en/ # English personas, policies, instructions, and pieces - ja/ # Japanese personas, policies, instructions, and pieces + en/ # English + facets/ # Facets (personas, policies, knowledge, instructions, output-contracts) + pieces/ # Piece YAML files + ja/ # Japanese (same structure) project/ # Project-level template 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 description: Optional description max_movements: 10 -initial_step: plan # First step to execute +initial_movement: plan # First movement to execute -steps: - # Normal step - - name: step-name - persona: ../personas/coder.md # Path to persona prompt +# Section maps (key → file path relative to piece YAML directory) +personas: + coder: ../facets/personas/coder.md + 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) - 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) - edit: true # Whether step can edit files + edit: true # Whether movement can edit files required_permission_mode: edit # Required minimum permission mode (optional) instruction_template: | - Custom instructions for this step. + Custom instructions for this movement. {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: | # Output contract template - # Plan Report - ... + output_contracts: + report: + - name: 01-plan.md # Report file name + format: plan # References report_formats map rules: - condition: "Human-readable condition" - next: next-step-name + next: next-movement-name - condition: ai("AI evaluates this condition text") - next: other-step + next: other-movement - condition: blocked next: ABORT - # Parallel step (sub-steps execute concurrently) + # Parallel movement (sub-movements execute concurrently) - name: reviewers parallel: - name: arch-review - persona: ../personas/architecture-reviewer.md + persona: reviewer + policy: review + knowledge: architecture + edit: false rules: - - condition: approved # next is optional for sub-steps + - condition: approved # next is optional for sub-movements - condition: needs_fix - instruction_template: | - Review architecture... + instruction: review-arch - name: security-review - persona: ../personas/security-reviewer.md + persona: security-reviewer + edit: false rules: - condition: approved - condition: needs_fix - instruction_template: | - Review security... + instruction: review-security rules: # Parent rules use aggregate conditions - condition: all("approved") next: supervise @@ -271,11 +297,11 @@ steps: 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 +Key points about parallel movements: +- Sub-movement `rules` define possible outcomes but `next` is ignored (parent handles routing) +- Parent `rules` use `all("X")`/`any("X")` to aggregate sub-movement results +- `all("X")`: true if ALL sub-movements matched condition X +- `any("X")`: true if ANY sub-movements matched condition X ### Rule Condition Types @@ -283,7 +309,7 @@ Key points about parallel steps: |------|--------|------------| | 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 | +| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-movement matched conditions | ### Template Variables @@ -292,8 +318,8 @@ Key points about parallel steps: | `{task}` | Original user request (auto-injected if not in template) | | `{iteration}` | Piece-wide iteration count | | `{max_movements}` | Maximum movements allowed | -| `{step_iteration}` | Per-step iteration count | -| `{previous_response}` | Previous step output (auto-injected if not in template) | +| `{movement_iteration}` | Per-movement iteration count | +| `{previous_response}` | Previous movement output (auto-injected if not in template) | | `{user_inputs}` | Accumulated user inputs (auto-injected if not in template) | | `{report_dir}` | Report directory name | @@ -313,7 +339,7 @@ Example category config: ```yaml piece_categories: Development: - pieces: [default, simple] + pieces: [default, default-mini] children: Backend: pieces: [expert-cqrs] @@ -331,7 +357,7 @@ Implemented in `src/infra/config/loaders/pieceCategories.ts`. 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` 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) @@ -339,7 +365,7 @@ Model is resolved in the following priority order: Example `~/.takt/config.yaml`: ```yaml provider: claude -model: opus # Default model for all steps (unless overridden) +model: opus # Default model for all movements (unless overridden) ``` ## 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`. -**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. ``` -builtins/{lang}/ +builtins/{lang}/facets/ personas/ — WHO: identity, expertise, behavioral habits policies/ — HOW: judgment criteria, REJECT/APPROVE rules, prohibited patterns 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 | @@ -386,20 +412,20 @@ builtins/{lang}/ | Role definition, AI habit prevention | Persona | "置き換えたコードを残す → 禁止" | | Actionable REJECT/APPROVE criterion | Policy | "内部実装のパブリックAPIエクスポート → REJECT" | | 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` | 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 - 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 -- Piece YAML `instruction_template` is for step-specific details (which reports to read, step routing, output templates) +- Instructions are bound to a single piece movement. They reference procedures, not principles +- Piece YAML `instruction_template` is for movement-specific details (which reports to read, movement routing, output templates) **Separation of concerns in piece engine:** - `PieceEngine` - Orchestration, state management, event emission -- `StepExecutor` - Single step execution (3-phase model) -- `ParallelRunner` - Parallel step execution +- `StepExecutor` - Single movement execution (3-phase model) +- `ParallelRunner` - Parallel movement execution - `RuleEvaluator` - Rule matching and evaluation - `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 paths in piece YAML are resolved relative to the piece file's directory -- `../personas/coder.md` resolves from piece file location -- Built-in personas are loaded from `builtins/{lang}/personas/` -- User personas are loaded from `~/.takt/personas/` (legacy: `~/.takt/agents/`) +- `../facets/personas/coder.md` resolves from piece file location +- Built-in personas are loaded from `builtins/{lang}/facets/personas/` +- User personas are loaded from `~/.takt/facets/personas/` - If persona file doesn't exist, the persona string is used as inline system prompt **Report directory structure:** - 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 - 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 - **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 -- 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 - Interactive-only rules are skipped in pipeline mode (`rule.interactiveOnly === true`) **Provider-specific behavior:** -- Claude: Uses session files in `~/.claude/projects/`, supports skill/agent calls -- Codex: In-memory sessions, no skill/agent calls +- Claude: Uses session files in `~/.claude/projects/` +- Codex: In-memory sessions - Model names are passed directly to provider (no alias resolution in TAKT) - Claude supports aliases: `opus`, `sonnet`, `haiku` - Codex defaults to `codex` if model not specified diff --git a/README.md b/README.md index e768036..55e3b50 100644 --- a/README.md +++ b/README.md @@ -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: ```yaml -name: simple +name: plan-implement-review initial_movement: plan +max_movements: 10 personas: - planner: ../personas/planner.md - coder: ../personas/coder.md - reviewer: ../personas/architecture-reviewer.md + planner: ../facets/personas/planner.md + coder: ../facets/personas/coder.md + reviewer: ../facets/personas/architecture-reviewer.md movements: - name: plan @@ -107,6 +108,7 @@ movements: - name: implement persona: coder edit: true + required_permission_mode: edit rules: - condition: Implementation complete next: review diff --git a/docs/README.ja.md b/docs/README.ja.md index dcf8416..e647ef6 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -100,13 +100,14 @@ TAKT は音楽のメタファーを使っています。**piece** がワーク piece は movement の並びを定義します。各 movement では persona（誰が実行するか）、権限（何を許可するか）、ルール（次にどこへ進むか）を指定します。 ```yaml -name: simple +name: plan-implement-review initial_movement: plan +max_movements: 10 personas: - planner: ../personas/planner.md - coder: ../personas/coder.md - reviewer: ../personas/architecture-reviewer.md + planner: ../facets/personas/planner.md + coder: ../facets/personas/coder.md + reviewer: ../facets/personas/architecture-reviewer.md movements: - name: plan @@ -119,6 +120,7 @@ movements: - name: implement persona: coder edit: true + required_permission_mode: edit rules: - condition: Implementation complete next: review diff --git a/docs/agents.md b/docs/agents.md index e9babaa..bf32245 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -2,12 +2,12 @@ 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 | | **coder** | Implements features and fixes bugs | | **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 | | **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 -# Relative to piece file directory -agent: ../agents/default/coder.md +# Section map at top level (key → file path relative to piece YAML) +personas: + coder: ../facets/personas/coder.md + reviewer: ../facets/personas/architecture-reviewer.md -# Home directory -agent: ~/.takt/agents/default/coder.md - -# Absolute path -agent: /path/to/custom/agent.md +movements: + - name: implement + persona: coder # References the key in section map + - name: review + 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 # Security Reviewer @@ -52,7 +64,7 @@ You are a security-focused code reviewer. - 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 @@ -66,7 +78,7 @@ agents: - Read - Glob - Grep - provider: claude # Optional: claude or codex + provider: claude # Optional: claude, codex, or opencode model: opus # Optional: model alias or full name ``` @@ -74,13 +86,11 @@ agents: | Field | Description | |-------|-------------| -| `name` | Agent identifier (referenced in piece steps) | +| `name` | Agent identifier (referenced in piece movements) | | `prompt_file` | Path to Markdown prompt file | | `prompt` | Inline prompt text (alternative to `prompt_file`) | | `allowed_tools` | List of tools the agent can use | -| `claude_agent` | Claude Code agent name (for Claude Code native agents) | -| `claude_skill` | Claude Code skill name (for Claude Code native skills) | -| `provider` | Provider override: `claude` or `codex` | +| `provider` | Provider override: `claude`, `codex`, or `opencode` | | `model` | Model override (alias or full name) | ### Available Tools @@ -100,7 +110,7 @@ agents: 2. **Minimal tools** — Grant only necessary permissions 3. **Use `edit: false`** — Review agents should not modify files 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 @@ -114,9 +124,12 @@ agents: ```yaml # piece.yaml -steps: +personas: + coder: ../facets/personas/coder.md + +movements: - name: implement - agent: ../agents/default/coder.md + persona: coder edit: true rules: - condition: Implementation complete @@ -125,7 +138,7 @@ steps: next: ABORT - name: review - agent: performance-reviewer + persona: performance-reviewer # References agents.yaml by name edit: false rules: - condition: Approved diff --git a/docs/pieces.md b/docs/pieces.md index f5ce902..ff654cb 100644 --- a/docs/pieces.md +++ b/docs/pieces.md @@ -4,10 +4,10 @@ This guide explains how to create and customize TAKT pieces. ## Piece Basics -A piece is a YAML file that defines a sequence of steps executed by AI agents. Each step specifies: -- Which agent to use +A piece is a YAML file that defines a sequence of movements executed by AI agents. Each movement specifies: +- Which persona to use - What instructions to give -- Rules for routing to the next step +- Rules for routing to the next movement ## 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 -ピースの選択 UI をカテゴリ分けしたい場合は、`piece_categories` を設定します。 -詳細は `docs/piece-categories.md` を参照してください。 +To organize the piece selection UI into categories, configure `piece_categories`. +See `docs/piece-categories.md` for details. ## 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 description: Optional description max_movements: 10 -initial_step: first-step # Optional, defaults to first step +initial_movement: first-movement # Optional, defaults to first movement -steps: - - name: step-name - agent: ../agents/default/coder.md # Path to agent prompt file - agent_name: coder # Display name (optional) - edit: true # Whether the step can edit files - allowed_tools: # Optional tool allowlist +# Section maps (key → file path relative to piece YAML directory) +personas: + planner: ../facets/personas/planner.md + coder: ../facets/personas/coder.md + reviewer: ../facets/personas/architecture-reviewer.md +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 - Glob - Grep @@ -42,31 +62,37 @@ steps: - Bash rules: - condition: "Implementation complete" - next: next-step + next: next-movement - condition: "Cannot proceed" next: ABORT - instruction_template: | + instruction_template: | # Inline instructions (alternative to instruction key) 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 | Variable | Description | |----------|-------------| | `{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 | -| `{step_iteration}` | Per-step iteration count (how many times THIS step has run) | -| `{previous_response}` | Previous step's output (auto-injected if not in template) | +| `{movement_iteration}` | Per-movement iteration count (how many times THIS movement has run) | +| `{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) | | `{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. ## 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 rules: @@ -84,7 +110,7 @@ rules: |------|--------|-------------| | 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 | +| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-movement results | ### 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. -## Parallel Steps +## Parallel Movements -Steps can execute sub-steps concurrently with aggregate evaluation: +Movements can execute sub-movements concurrently with aggregate evaluation: ```yaml - name: reviewers parallel: - name: arch-review - agent: ../agents/default/architecture-reviewer.md + persona: architecture-reviewer + policy: review + knowledge: architecture edit: false rules: - condition: approved - condition: needs_fix - instruction_template: | - Review architecture and code quality. + instruction: review-arch - name: security-review - agent: ../agents/default/security-reviewer.md + persona: security-reviewer + policy: review edit: false rules: - condition: approved - condition: needs_fix - instruction_template: | - Review for security vulnerabilities. + instruction: review-security rules: - condition: all("approved") - next: supervise + next: COMPLETE - 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) +- `all("X")`: true if ALL sub-movements matched condition X +- `any("X")`: true if ANY sub-movement matched condition X +- 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 -# Single report file -report: 00-plan.md +# Single report with format specification (references report_formats map) +output_contracts: + report: + - name: 00-plan.md + format: plan -# Single report with format specification -report: - name: 00-plan.md - format: | - ```markdown - # Plan - ... - ``` +# Single report with inline format +output_contracts: + report: + - name: 00-plan.md + format: | + # Plan + ... -# Multiple report files -report: - - Scope: 01-scope.md - - Decisions: 02-decisions.md +# Multiple report files with labels +output_contracts: + report: + - Scope: 01-scope.md + - Decisions: 02-decisions.md ``` -## Step Options +## Movement 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}` | +| `persona` | - | Persona key (references section map) or file path | +| `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.) | -| `provider` | - | Override provider for this step (`claude` or `codex`) | -| `model` | - | Override model for this step | -| `required_permission_mode` | - | Required minimum permission mode: `readonly`, `edit`, or `full` (provider-independent) | -| `report` | - | Report file configuration (name, format) for auto-generated reports | +| `provider` | - | Override provider for this movement (`claude`, `codex`, or `opencode`) | +| `model` | - | Override model for this movement | +| `required_permission_mode` | - | Required minimum permission mode: `readonly`, `edit`, or `full` | +| `output_contracts` | - | Report file configuration (name, format) | +| `quality_gates` | - | Quality criteria for movement completion (AI instruction) | ## Examples @@ -172,9 +207,12 @@ report: name: simple-impl max_movements: 5 -steps: +personas: + coder: ../facets/personas/coder.md + +movements: - name: implement - agent: ../agents/default/coder.md + persona: coder edit: true required_permission_mode: edit allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch] @@ -193,9 +231,13 @@ steps: name: with-review max_movements: 10 -steps: +personas: + coder: ../facets/personas/coder.md + reviewer: ../facets/personas/architecture-reviewer.md + +movements: - name: implement - agent: ../agents/default/coder.md + persona: coder edit: true required_permission_mode: edit allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch] @@ -208,7 +250,7 @@ steps: Implement the requested changes. - name: review - agent: ../agents/default/architecture-reviewer.md + persona: reviewer edit: false allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch] rules: @@ -220,12 +262,16 @@ steps: Review the implementation for code quality and best practices. ``` -### Passing Data Between Steps +### Passing Data Between Movements ```yaml -steps: +personas: + planner: ../facets/personas/planner.md + coder: ../facets/personas/coder.md + +movements: - name: analyze - agent: ../agents/default/planner.md + persona: planner edit: false allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch] rules: @@ -235,7 +281,7 @@ steps: Analyze this request and create a plan. - name: implement - agent: ../agents/default/coder.md + persona: coder edit: true pass_previous_response: true required_permission_mode: edit @@ -251,7 +297,7 @@ steps: ## Best Practices 1. **Keep iterations reasonable** — 10-30 is typical for development pieces -2. **Use `edit: false` for review steps** — Prevent reviewers from modifying code -3. **Use descriptive step names** — Makes logs easier to read +2. **Use `edit: false` for review movements** — Prevent reviewers from modifying code +3. **Use descriptive movement names** — Makes logs easier to read 4. **Test pieces incrementally** — Start simple, add complexity 5. **Use `/eject` to customize** — Copy a builtin as starting point rather than writing from scratch diff --git a/docs/testing/e2e.md b/docs/testing/e2e.md index af12867..c7649e0 100644 --- a/docs/testing/e2e.md +++ b/docs/testing/e2e.md @@ -160,16 +160,6 @@ E2Eテストを追加・変更した場合は、このドキュメントも更 - 出力に `reset` と `backup:` を含むことを確認する。 - `$TAKT_CONFIG_DIR/config.yaml` がテンプレート内容（例: `branch_name_strategy: ai`, `concurrency: 2`）に置き換わっていることを確認する。 - `$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） 過去にドキュメント未反映だったシナリオを以下に追記する。