takt/docs/pieces.md

Piece Guide

This guide explains how to create and customize TAKT pieces.

Piece Basics

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 movement

File Locations

• Builtin pieces are embedded in the npm package (dist/resources/)
• ~/.takt/pieces/ — User pieces (override builtins with the same name)
• Use takt eject <piece> to copy a builtin to ~/.takt/pieces/ for customization

Piece Categories

To organize the piece selection UI into categories, configure piece_categories. See docs/piece-categories.md for details.

Piece Schema

name: my-piece
description: Optional description
max_movements: 10
initial_movement: first-movement  # Optional, defaults to first movement

# 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
      - Edit
      - Write
      - Bash
    rules:
      - condition: "Implementation complete"
        next: next-movement
      - condition: "Cannot proceed"
        next: ABORT
    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 movements executed)
{max_movements}	Maximum movements allowed
{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}	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 movement routes to the next movement. The instruction builder auto-injects status output rules so agents know what tags to output.

rules:
  - condition: "Implementation complete"
    next: review
  - condition: "Cannot proceed"
    next: ABORT
    appendix: |
      Explain what is blocking progress.

Rule Condition Types

Type	Syntax	Description
Tag-based	"condition text"	Agent outputs [STEP:N] tag, matched by index
AI judge	ai("condition text")	AI evaluates the condition against agent output
Aggregate	all("X") / any("X")	Aggregates parallel sub-movement results

Special next Values

• COMPLETE — End piece successfully
• ABORT — End piece with failure

Rule Field: appendix

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 Movements

Movements can execute sub-movements concurrently with aggregate evaluation:

  - name: reviewers
    parallel:
      - name: arch-review
        persona: architecture-reviewer
        policy: review
        knowledge: architecture
        edit: false
        rules:
          - condition: approved
          - condition: needs_fix
        instruction: review-arch
      - name: security-review
        persona: security-reviewer
        policy: review
        edit: false
        rules:
          - condition: approved
          - condition: needs_fix
        instruction: review-security
    rules:
      - condition: all("approved")
        next: COMPLETE
      - condition: any("needs_fix")
        next: fix

• 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)

Output Contracts (Report Files)

Movements can generate report files in the report directory:

# Single report with format specification (references report_formats map)
output_contracts:
  report:
    - name: 00-plan.md
      format: plan

# Single report with inline format
output_contracts:
  report:
    - name: 00-plan.md
      format: |
        # Plan
        ...

# Multiple report files with labels
output_contracts:
  report:
    - Scope: 01-scope.md
    - Decisions: 02-decisions.md

Movement Options

Option	Default	Description
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 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

Simple Implementation Piece

name: simple-impl
max_movements: 5

personas:
  coder: ../facets/personas/coder.md

movements:
  - name: implement
    persona: coder
    edit: true
    required_permission_mode: edit
    allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
    rules:
      - condition: Implementation complete
        next: COMPLETE
      - condition: Cannot proceed
        next: ABORT
    instruction_template: |
      Implement the requested changes.

Implementation with Review

name: with-review
max_movements: 10

personas:
  coder: ../facets/personas/coder.md
  reviewer: ../facets/personas/architecture-reviewer.md

movements:
  - name: implement
    persona: coder
    edit: true
    required_permission_mode: edit
    allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
    rules:
      - condition: Implementation complete
        next: review
      - condition: Cannot proceed
        next: ABORT
    instruction_template: |
      Implement the requested changes.

  - name: review
    persona: reviewer
    edit: false
    allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
    rules:
      - condition: Approved
        next: COMPLETE
      - condition: Needs fix
        next: implement
    instruction_template: |
      Review the implementation for code quality and best practices.

Passing Data Between Movements

personas:
  planner: ../facets/personas/planner.md
  coder: ../facets/personas/coder.md

movements:
  - name: analyze
    persona: planner
    edit: false
    allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
    rules:
      - condition: Analysis complete
        next: implement
    instruction_template: |
      Analyze this request and create a plan.

  - name: implement
    persona: coder
    edit: true
    pass_previous_response: true
    required_permission_mode: edit
    allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
    rules:
      - condition: Implementation complete
        next: COMPLETE
    instruction_template: |
      Implement based on this analysis:
      {previous_response}

Best Practices

1. Keep iterations reasonable — 10-30 is typical for development pieces
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