takt 0.7.0 → 0.8.0-alpha.1

package/README.md

@@ -4,7 +4,7 @@
 
 **T**ask **A**gent **K**oordination **T**ool - Define how AI agents coordinate, where humans intervene, and what gets recorded — in YAML
 
-TAKT runs multiple AI agents (Claude Code, Codex) through YAML-defined workflows. Each step — who runs, what's allowed, what happens on failure — is declared in a piece file, not left to the agent.
+TAKT runs multiple AI agents (Claude Code, Codex) through YAML-defined workflows. Each step — who runs, what they see, what's allowed, what happens on failure — is declared in a piece file, not left to the agent.
 
 TAKT is built with TAKT itself (dogfooding).
 
@@ -24,6 +24,21 @@ You can read every term as standard workflow language (piece = workflow, movemen
 - Multi-agent coordination needs structure — pieces define who does what, in what order, with what permissions
 - CI/CD integration needs guardrails — pipeline mode runs agents non-interactively with full audit logs
 
+## What TAKT Controls and Manages
+
+TAKT **controls** agent execution and **manages** prompt components.
+
+| | Concern | Description |
+|---|---------|-------------|
+| Control | **Routing** | State transition rules (who runs when) |
+| Control | **Tools & Permissions** | Readonly, edit, full access (what's allowed) |
+| Control | **Recording** | Session logs, reports (what gets captured) |
+| Manage | **Personas** | Agent roles and expertise (who they act as) |
+| Manage | **Policies** | Coding standards, quality criteria, prohibitions (what to uphold) |
+| Manage | **Knowledge** | Domain knowledge, architecture info (what to reference) |
+
+Personas, policies, and knowledge are managed as independent files and freely combined across workflows ([Faceted Prompting](./docs/faceted-prompting.md)). Change a policy in one file and every workflow using it gets the update.
+
 ## What TAKT is NOT
 
 - **Not an autonomous engineer** — TAKT coordinates agents but doesn't decide what to build. You provide the task, TAKT governs the execution.
@@ -190,6 +205,12 @@ takt watch
 ```bash
 # List task branches (merge/delete)
 takt list
+
+# Non-interactive mode (for CI/scripts)
+takt list --non-interactive
+takt list --non-interactive --action diff --branch takt/my-branch
+takt list --non-interactive --action delete --branch takt/my-branch --yes
+takt list --non-interactive --format json
 ```
 
 ### Pipeline Mode (for CI/Automation)
@@ -229,17 +250,26 @@ In pipeline mode, PRs are not created unless `--auto-pr` is specified.
 # Interactively switch pieces
 takt switch
 
-# Copy builtin pieces/agents to ~/.takt/ for customization
+# Copy builtin pieces/personas to project .takt/ for customization
 takt eject
 
+# Copy to ~/.takt/ (global) instead
+takt eject --global
+
 # Clear agent conversation sessions
 takt clear
 
-# Deploy builtin pieces/agents as Claude Code Skill
+# Deploy builtin pieces/personas as Claude Code Skill
 takt export-cc
 
+# Preview assembled prompts for each movement and phase
+takt prompt [piece]
+
 # Configure permission mode
 takt config
+
+# Reset piece categories to builtin defaults
+takt reset categories
 ```
 
 ### Recommended Pieces
@@ -281,9 +311,21 @@ name: default
 max_iterations: 10
 initial_movement: plan
 
+# Section maps — key: file path (relative to this YAML)
+personas:
+  planner: ../personas/planner.md
+  coder: ../personas/coder.md
+  reviewer: ../personas/architecture-reviewer.md
+
+policies:
+  coding: ../policies/coding.md
+
+knowledge:
+  architecture: ../knowledge/architecture.md
+
 movements:
   - name: plan
-    agent: ../agents/default/planner.md
+    persona: planner
     model: opus
     edit: false
     rules:
@@ -293,7 +335,9 @@ movements:
       Analyze the request and create an implementation plan.
 
   - name: implement
-    agent: ../agents/default/coder.md
+    persona: coder
+    policy: coding
+    knowledge: architecture
     edit: true
     permission_mode: edit
     rules:
@@ -305,7 +349,8 @@ movements:
       Implement based on the plan.
 
   - name: review
-    agent: ../agents/default/architecture-reviewer.md
+    persona: reviewer
+    knowledge: architecture
     edit: false
     rules:
       - condition: Approved
@@ -316,13 +361,13 @@ movements:
       Review the implementation from architecture and code quality perspectives.
 ```
 
-### Agentless Movements
+### Persona-less Movements
 
-The `agent` field is optional. When omitted, the movement executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require agent behavior customization.
+The `persona` field is optional. When omitted, the movement executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require persona customization.
 
 ```yaml
   - name: summarize
-    # No agent specified — uses instruction_template only
+    # No persona specified — uses instruction_template only
     edit: false
     rules:
       - condition: Summary complete
@@ -331,11 +376,11 @@ The `agent` field is optional. When omitted, the movement executes using only th
       Read the report and provide a concise summary.
 ```
 
-You can also write an inline system prompt as the `agent` value (if the specified file doesn't exist):
+You can also write an inline system prompt as the `persona` value (if the specified file doesn't exist):
 
 ```yaml
   - name: review
-    agent: "You are a code reviewer. Focus on readability and maintainability."
+    persona: "You are a code reviewer. Focus on readability and maintainability."
     edit: false
     instruction_template: |
       Review code quality.
@@ -349,14 +394,14 @@ Execute sub-movements in parallel within a movement and evaluate with aggregate
   - name: reviewers
     parallel:
       - name: arch-review
-        agent: ../agents/default/architecture-reviewer.md
+        persona: reviewer
         rules:
           - condition: approved
           - condition: needs_fix
         instruction_template: |
           Review architecture and code quality.
       - name: security-review
-        agent: ../agents/default/security-reviewer.md
+        persona: security-reviewer
         rules:
           - condition: approved
           - condition: needs_fix
@@ -394,6 +439,7 @@ TAKT includes multiple builtin pieces:
 | `expert` | Full-stack development piece: architecture, frontend, security, QA reviews with fix loops. |
 | `expert-cqrs` | Full-stack development piece (CQRS+ES specialized): CQRS+ES, frontend, security, QA reviews with fix loops. |
 | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. |
+| `coding` | Lightweight development piece: architect-planner → implement → parallel review (AI antipattern + architecture) → fix. Fast feedback loop without supervisor. |
 | `passthrough` | Thinnest wrapper. Pass task directly to coder as-is. No review. |
 | `review-only` | Read-only code review piece that makes no changes. |
 
@@ -401,23 +447,26 @@ TAKT includes multiple builtin pieces:
 
 Use `takt switch` to switch pieces.
 
-## Builtin Agents
+## Builtin Personas
 
-| Agent | Description |
-|-------|-------------|
+| Persona | Description |
+|---------|-------------|
 | **planner** | Task analysis, spec investigation, implementation planning |
+| **architect-planner** | Task analysis and design planning: investigates code, resolves unknowns, creates implementation plans |
 | **coder** | Feature implementation, bug fixing |
 | **ai-antipattern-reviewer** | AI-specific antipattern review (non-existent APIs, incorrect assumptions, scope creep) |
 | **architecture-reviewer** | Architecture and code quality review, spec compliance verification |
+| **qa-reviewer** | Test coverage and quality assurance review |
 | **security-reviewer** | Security vulnerability assessment |
+| **conductor** | Phase 3 judgment specialist: reads reports/responses and outputs status tags |
 | **supervisor** | Final validation, approval |
 
-## Custom Agents
+## Custom Personas
 
-Create agent prompts in Markdown files:
+Create persona prompts in Markdown files:
 
 ```markdown
-# ~/.takt/agents/my-agents/reviewer.md
+# ~/.takt/personas/my-reviewer.md
 
 You are a code reviewer specialized in security.
 
@@ -444,10 +493,10 @@ The model string is passed to the Codex SDK. If unspecified, defaults to `codex`
 ```
 ~/.takt/                    # Global configuration directory
 ├── config.yaml             # Global config (provider, model, piece, etc.)
-├── pieces/              # User piece definitions (override builtins)
+├── pieces/                 # User piece definitions (override builtins)
 │   └── custom.yaml
-└── agents/                 # User agent prompt files (.md)
-    └── my-agent.md
+└── personas/               # User persona prompt files (.md)
+    └── my-persona.md
 
 .takt/                      # Project-level configuration
 ├── config.yaml             # Project config (current piece, etc.)
@@ -461,7 +510,7 @@ The model string is passed to the Codex SDK. If unspecified, defaults to `codex`
     └── {sessionId}.jsonl   # NDJSON session log per piece execution
 ```
 
-Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority.
+Builtin resources are embedded in the npm package (`builtins/`). User files in `~/.takt/` take priority.
 
 ### Global Configuration
 
@@ -596,9 +645,13 @@ description: Custom piece
 max_iterations: 5
 initial_movement: analyze
 
+personas:
+  analyzer: ~/.takt/personas/analyzer.md
+  coder: ../personas/coder.md
+
 movements:
   - name: analyze
-    agent: ~/.takt/agents/my-agents/analyzer.md
+    persona: analyzer
     edit: false
     rules:
       - condition: Analysis complete
@@ -607,7 +660,7 @@ movements:
       Thoroughly analyze this request.
 
   - name: implement
-    agent: ~/.takt/agents/default/coder.md
+    persona: coder
     edit: true
     permission_mode: edit
     pass_previous_response: true
@@ -620,19 +673,15 @@ movements:
 
 > **Note**: `{task}`, `{previous_response}`, `{user_inputs}` are automatically injected into instructions. Explicit placeholders are only needed if you want to control their position in the template.
 
-### Specifying Agents by Path
+### Specifying Personas by Path
 
-In piece definitions, specify agents using file paths:
+Map keys to file paths in section maps, then reference keys from movements:
 
 ```yaml
-# Relative path from piece file
-agent: ../agents/default/coder.md
-
-# Home directory
-agent: ~/.takt/agents/default/coder.md
-
-# Absolute path
-agent: /path/to/custom/agent.md
+# Section maps (relative to piece file)
+personas:
+  coder: ../personas/coder.md
+  reviewer: ~/.takt/personas/my-reviewer.md
 ```
 
 ### Piece Variables
@@ -654,11 +703,11 @@ Variables available in `instruction_template`:
 
 Elements needed for each piece movement:
 
-**1. Agent** - Markdown file containing system prompt:
+**1. Persona** - Referenced by section map key (used as system prompt):
 
 ```yaml
-agent: ../agents/default/coder.md    # Path to agent prompt file
-agent_name: coder                    # Display name (optional)
+persona: coder                       # Key from personas section map
+persona_name: coder                  # Display name (optional)
 ```
 
 **2. Rules** - Define routing from movement to next movement. The instruction builder auto-injects status output rules, so agents know which tags to output:
@@ -683,7 +732,8 @@ Special `next` values: `COMPLETE` (success), `ABORT` (failure)
 | `provider` | - | Override provider for this movement (`claude` or `codex`) |
 | `model` | - | Override model for this movement |
 | `permission_mode` | - | Permission mode: `readonly`, `edit`, `full` (provider-independent) |
-| `report` | - | Auto-generated report file settings (name, format) |
+| `output_contracts` | - | Output contract definitions for report files |
+| `quality_gates` | - | AI directives for movement completion requirements |
 
 ## API Usage Example
 
@@ -768,6 +818,7 @@ export TAKT_OPENAI_API_KEY=sk-...
 
 ## Documentation
 
+- [Faceted Prompting](./docs/faceted-prompting.md) - Separation of Concerns for AI prompts (Persona, Policy, Instruction, Knowledge, Output Contract)
 - [Piece Guide](./docs/pieces.md) - Creating and customizing pieces
 - [Agent Guide](./docs/agents.md) - Configuring custom agents
 - [Changelog](../CHANGELOG.md) - Version history

package/builtins/en/instructions/ai-fix.md

@@ -0,0 +1,40 @@
+**This is AI Review iteration #{movement_iteration}.**
+
+From the 2nd iteration onward, it means the previous fixes were not actually applied.
+**Your belief that they were "already fixed" is incorrect.**
+
+**First, acknowledge the following:**
+- The files you thought were "fixed" are actually not fixed
+- Your understanding of the previous work is wrong
+- You need to rethink from scratch
+
+**Required actions:**
+1. Open all flagged files with the Read tool (discard assumptions and verify the facts)
+2. Search for the problem areas with grep to confirm they exist
+3. Fix the confirmed issues with the Edit tool
+4. Run tests to verify
+5. Report specifically "what you checked and what you fixed"
+
+**Report format:**
+- NG: "It has already been fixed"
+- OK: "After checking file X at L123, I found issue Y and fixed it to Z"
+
+**Strictly prohibited:**
+- Reporting "already fixed" without opening the file
+- Making judgments based on assumptions
+- Leaving issues that the AI Reviewer REJECTed unresolved
+
+**Handling "no fix needed" (required)**
+- Do not judge "no fix needed" unless you can show verification results for the target file for each AI Review finding
+- If the finding relates to "generated output" or "spec synchronization", output the tag corresponding to "unable to determine" unless you can verify the source/spec
+- If no fix is needed, output the tag corresponding to "unable to determine" and clearly state the reason and scope of verification
+
+**Required output (include headings)**
+## Files checked
+- {filepath:line_number}
+## Searches performed
+- {command and summary}
+## Changes made
+- {change details}
+## Test results
+- {command executed and results}

package/builtins/en/instructions/ai-review.md

@@ -0,0 +1,10 @@
+**This is AI Review iteration #{movement_iteration}.**
+
+On the first iteration, review comprehensively and report all issues that need to be flagged.
+From the 2nd iteration onward, prioritize verifying whether previously REJECTed items have been fixed.
+
+Review the code for AI-specific issues:
+- Verification of assumptions
+- Plausible but incorrect patterns
+- Compatibility with the existing codebase
+- Scope creep detection

package/builtins/en/instructions/arbitrate.md

@@ -0,0 +1,14 @@
+The ai_review (reviewer) and ai_fix (coder) disagree.
+
+- ai_review flagged issues and issued a REJECT
+- ai_fix reviewed and determined "no fix needed"
+
+Review both outputs and arbitrate which judgment is valid.
+
+**Reports to reference:**
+- AI review results: {report:ai-review.md}
+
+**Judgment criteria:**
+- Whether ai_review's findings are specific and point to real issues in the code
+- Whether ai_fix's rebuttal has evidence (file verification results, test results)
+- Whether the findings are non-blocking (record only) level or actually require fixes

package/builtins/en/instructions/architect.md

@@ -0,0 +1,21 @@
+Read the plan report ({report:plan.md}) and design the architecture.
+
+**Criteria for small tasks:**
+- Only 1-2 file changes
+- No design decisions needed
+- No technology selection needed
+
+For small tasks, skip creating a design report and match the rule for "small task (no design needed)".
+
+**Tasks requiring design:**
+- Changes to 3 or more files
+- Adding new modules or features
+- Technology selection required
+- Architecture pattern decisions needed
+
+**Actions:**
+1. Assess the task scope
+2. Determine file structure
+3. Select technologies (if needed)
+4. Choose design patterns
+5. Create implementation guidelines for the Coder

package/builtins/en/instructions/fix-supervisor.md

@@ -0,0 +1,14 @@
+Fix the issues raised by the supervisor.
+
+The supervisor has flagged problems from an overall perspective.
+Address items in order of priority, starting with the highest.
+
+**Required output (include headings)**
+## Work results
+- {Summary of actions taken}
+## Changes made
+- {Summary of changes}
+## Test results
+- {Command executed and results}
+## Evidence
+- {List key points from files checked/searches/diffs/logs}

package/builtins/en/instructions/fix.md

@@ -0,0 +1,12 @@
+Address the reviewer's feedback.
+Review the session conversation history and fix the issues raised by the reviewer.
+
+**Required output (include headings)**
+## Work results
+- {Summary of actions taken}
+## Changes made
+- {Summary of changes}
+## Test results
+- {Command executed and results}
+## Evidence
+- {List key points from files checked/searches/diffs/logs}

package/builtins/en/instructions/implement.md

@@ -0,0 +1,46 @@
+Implement according to the plan.
+Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+
+**Important**: Add unit tests alongside the implementation.
+- Add unit tests for newly created classes and functions
+- Update relevant tests when modifying existing code
+- Test file placement: follow the project's conventions
+- Running tests is mandatory. After completing implementation, always run tests and verify results
+
+**Scope output contract (create at the start of implementation):**
+```markdown
+# Change Scope Declaration
+
+## Task
+{One-line task summary}
+
+## Planned changes
+| Type | File |
+|------|------|
+| Create | `src/example.ts` |
+| Modify | `src/routes.ts` |
+
+## Estimated size
+Small / Medium / Large
+
+## Impact area
+- {Affected modules or features}
+```
+
+**Decisions output contract (at implementation completion, only if decisions were made):**
+```markdown
+# Decision Log
+
+## 1. {Decision}
+- **Context**: {Why the decision was needed}
+- **Options considered**: {List of options}
+- **Rationale**: {Reason for the choice}
+```
+
+**Required output (include headings)**
+## Work results
+- {Summary of actions taken}
+## Changes made
+- {Summary of changes}
+## Test results
+- {Command executed and results}

package/builtins/en/instructions/plan-investigate.md

@@ -0,0 +1,13 @@
+Analyze the task and formulate an implementation plan.
+
+**Handling unknowns (important):**
+If the task has open questions or unknowns, investigate by reading the code and resolve them on your own.
+Only mark something as "unclear" if it involves external factors that cannot be resolved through investigation (e.g., the user's intent cannot be determined).
+If it can be understood by reading the code, it is not "unclear".
+
+**Actions:**
+1. Understand the task requirements
+2. Read the relevant code to grasp the current state
+3. Investigate any unknowns through code analysis
+4. Identify the impact area
+5. Decide on the implementation approach

package/builtins/en/instructions/plan.md

@@ -0,0 +1,9 @@
+Analyze the task and formulate an implementation plan.
+
+**Note:** If a Previous Response exists, this is a replan due to rejection.
+Revise the plan taking that feedback into account.
+
+**Actions:**
+1. Understand the task requirements
+2. Identify the impact area
+3. Decide on the implementation approach

package/builtins/en/instructions/review-ai.md

@@ -0,0 +1,5 @@
+Review the code for AI-specific issues:
+- Verification of assumptions
+- Plausible but incorrect patterns
+- Compatibility with the existing codebase
+- Scope creep detection

package/builtins/en/instructions/review-arch.md

@@ -0,0 +1,10 @@
+Focus on reviewing **architecture and design**.
+Do not review AI-specific issues (already covered by the ai_review movement).
+
+**Review criteria:**
+- Structural and design validity
+- Code quality
+- Appropriateness of change scope
+- Test coverage
+- Dead code
+- Call chain verification

package/builtins/en/instructions/review-cqrs-es.md

@@ -0,0 +1,12 @@
+Review the changes from the perspective of CQRS (Command Query Responsibility Segregation) and Event Sourcing.
+AI-specific issue review is not needed (already covered by the ai_review movement).
+
+**Review criteria:**
+- Aggregate design validity
+- Event design (granularity, naming, schema)
+- Command/Query separation
+- Projection design
+- Eventual consistency considerations
+
+**Note**: If this project does not use the CQRS+ES pattern,
+review from a general domain design perspective instead.

package/builtins/en/instructions/review-frontend.md

@@ -0,0 +1,12 @@
+Review the changes from a frontend development perspective.
+
+**Review criteria:**
+- Component design (separation of concerns, granularity)
+- State management (local vs. global decisions)
+- Performance (re-renders, memoization)
+- Accessibility (keyboard navigation, ARIA)
+- Data fetching patterns
+- TypeScript type safety
+
+**Note**: If this project does not include a frontend,
+proceed as no issues found.

package/builtins/en/instructions/review-qa.md

@@ -0,0 +1,8 @@
+Review the changes from a quality assurance perspective.
+
+**Review criteria:**
+- Test coverage and quality
+- Test strategy (unit/integration/E2E)
+- Error handling
+- Logging and monitoring
+- Maintainability

package/builtins/en/instructions/review-security.md

@@ -0,0 +1,5 @@
+Review the changes from a security perspective. Check for the following vulnerabilities:
+- Injection attacks (SQL, command, XSS)
+- Authentication and authorization flaws
+- Data exposure risks
+- Cryptographic weaknesses

package/builtins/en/instructions/supervise.md

@@ -0,0 +1,55 @@
+Run tests, verify the build, and perform final approval.
+
+**Overall piece verification:**
+1. Whether the plan and implementation results are consistent
+2. Whether findings from each review movement have been addressed
+3. Whether the original task objective has been achieved
+
+**Report verification:** Read all reports in the Report Directory and
+check for any unaddressed improvement suggestions.
+
+**Validation output contract:**
+```markdown
+# Final Verification Results
+
+## Result: APPROVE / REJECT
+
+## Verification Summary
+| Item | Status | Verification method |
+|------|--------|-------------------|
+| Requirements met | ✅ | Cross-checked with requirements list |
+| Tests | ✅ | `npm test` (N passed) |
+| Build | ✅ | `npm run build` succeeded |
+| Functional check | ✅ | Main flows verified |
+
+## Deliverables
+- Created: {Created files}
+- Modified: {Modified files}
+
+## Outstanding items (if REJECT)
+| # | Item | Reason |
+|---|------|--------|
+| 1 | {Item} | {Reason} |
+```
+
+**Summary output contract (only if APPROVE):**
+```markdown
+# Task Completion Summary
+
+## Task
+{Original request in 1-2 sentences}
+
+## Result
+Complete
+
+## Changes
+| Type | File | Summary |
+|------|------|---------|
+| Create | `src/file.ts` | Summary description |
+
+## Verification commands
+```bash
+npm test
+npm run build
+```
+```