takt/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

TAKT (TAKT Agent Koordination Topology) is a multi-agent orchestration system for Claude Code. It enables YAML-based piece definitions that coordinate multiple AI agents through state machine transitions with rule-based routing.

## Development Commands

| Command | Description |
|---------|-------------|
| `npm run build` | TypeScript build (also copies prompt .md, i18n .yaml, and preset .sh files to dist/) |
| `npm run watch` | TypeScript build in watch mode |
| `npm run test` | Run all unit tests |
| `npm run test:watch` | Run tests in watch mode |
| `npm run lint` | ESLint |
| `npx vitest run src/__tests__/client.test.ts` | Run single test file |
| `npx vitest run -t "pattern"` | Run tests matching pattern |
| `npm run test:e2e` | Run E2E tests with mock provider (includes GitHub connectivity check) |
| `npm run test:e2e:mock` | Run E2E tests with mock provider (direct, no connectivity check) |
| `npm run test:e2e:provider:claude` | Run E2E tests against Claude provider |
| `npm run test:e2e:provider:codex` | Run E2E tests against Codex provider |
| `npm run test:e2e:provider:opencode` | Run E2E tests against OpenCode provider |
| `npm run check:release` | Full release check (build + lint + test + e2e) with macOS notification |
| `npm run prepublishOnly` | Lint, build, and test before publishing |

## CLI Subcommands

| Command | Description |
|---------|-------------|
| `takt {task}` | Execute task with current piece |
| `takt` | Interactive task input mode (chat with AI to refine requirements) |
| `takt run` | Execute all pending tasks from `.takt/tasks/` once |
| `takt watch` | Watch `.takt/tasks/` and auto-execute tasks (resident process) |
| `takt add [task]` | Add a new task via AI conversation |
| `takt list` | List task branches (merge, delete, retry) |
| `takt clear` | Clear agent conversation sessions (reset state) |
| `takt eject [type] [name]` | Copy builtin piece or facet for customization (`--global` for ~/.takt/) |
| `takt prompt [piece]` | Preview assembled prompts for each movement and phase |
| `takt catalog [type]` | List available facets (personas, policies, knowledge, etc.) |
| `takt export-cc` | Export takt pieces/agents as Claude Code Skill (~/.claude/) |
| `takt reset config` | Reset global config to builtin template |
| `takt reset categories` | Reset piece categories to builtin defaults |
| `takt metrics review` | Show review quality metrics |
| `takt purge` | Purge old analytics event files |
| `takt repertoire add <spec>` | Install a repertoire package from GitHub |
| `takt repertoire remove <scope>` | Remove an installed repertoire package |
| `takt repertoire list` | List installed repertoire packages |
| `takt config` | Configure settings (permission mode) |
| `takt --help` | Show help message |

**Interactive mode:** Running `takt` (without arguments) or `takt {initial message}` starts an interactive planning session. Supports 4 modes: `assistant` (default, AI asks clarifying questions), `passthrough` (passes input directly as task), `quiet` (generates instructions without questions), `persona` (uses first movement's persona for conversation). Type `/go` to execute the task with the selected piece, or `/cancel` to abort. Implemented in `src/features/interactive/`.

**Pipeline mode:** Specifying `--pipeline` enables non-interactive mode suitable for CI/CD. Automatically creates a branch, runs the piece, commits, and pushes. Use `--auto-pr` to also create a pull request. Use `--skip-git` to run piece only (no git operations). Implemented in `src/features/pipeline/`.

**GitHub issue references:** `takt #6` fetches issue #6 and executes it as a task.

### CLI Options

| Option | Description |
|--------|-------------|
| `--pipeline` | Enable pipeline (non-interactive) mode — required for CI/automation |
| `-t, --task <text>` | Task content (as alternative to GitHub issue) |
| `-i, --issue <N>` | GitHub issue number (equivalent to `#N` in interactive mode) |
| `--pr <number>` | PR number to fetch review comments and fix |
| `-w, --piece <name or path>` | Piece name or path to piece YAML file |
| `-b, --branch <name>` | Branch name (auto-generated if omitted) |
| `--auto-pr` | Create PR after execution (pipeline mode only) |
| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, piece-only) |
| `--repo <owner/repo>` | Repository for PR creation |
| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) |
| `--provider <name>` | Override agent provider (claude\|codex\|opencode\|mock) |
| `--model <name>` | Override agent model |
| `--config <path>` | Path to global config file (default: `~/.takt/config.yaml`) |

## Architecture

### Core Flow

```
CLI (cli.ts → routing.ts)
  → Interactive mode / Pipeline mode / Direct task execution
    → PieceEngine (piece/engine/PieceEngine.ts)
      → Per movement, delegates to one of 4 runners:
        MovementExecutor  — Normal movements (3-phase execution)
        ParallelRunner    — Parallel sub-movements via Promise.allSettled()
        ArpeggioRunner    — Data-driven batch processing (CSV → template → LLM)
        TeamLeaderRunner  — Dynamic task decomposition into sub-parts
      → detectMatchedRule() → rule evaluation → determineNextMovementByRules()
```

### Three-Phase Movement Execution

Each normal movement executes in up to 3 phases (session is resumed across phases):

| Phase | Purpose | Tools | When |
|-------|---------|-------|------|
| 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/phase-runner.ts`. The session is resumed so the agent retains context from Phase 1.

### Rule Evaluation (5-Stage Fallback)

After movement execution, rules are evaluated to determine the next movement. Evaluation order (first match wins):

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
5. **AI judge fallback** - AI evaluates ALL conditions as final resort

Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method is tracked as `RuleMatchMethod` type (`aggregate`, `auto_select`, `structured_output`, `phase3_tag`, `phase1_tag`, `ai_judge`, `ai_judge_fallback`).

### Key Components

**PieceEngine** (`src/core/piece/engine/PieceEngine.ts`)
- State machine that orchestrates agent execution via EventEmitter
- Manages movement transitions based on rule evaluation results
- Emits events: `movement:start`, `movement:complete`, `movement:blocked`, `movement:report`, `movement:user_input`, `movement:loop_detected`, `movement:cycle_detected`, `phase:start`, `phase:complete`, `piece:complete`, `piece:abort`, `iteration:limit`
- Supports loop detection (`LoopDetector`), cycle detection (`CycleDetector`), and iteration limits
- Maintains agent sessions per movement for conversation continuity
- Delegates to `MovementExecutor` (normal), `ParallelRunner` (parallel), `ArpeggioRunner` (data-driven batch), and `TeamLeaderRunner` (task decomposition)

**MovementExecutor** (`src/core/piece/engine/MovementExecutor.ts`)
- 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`
- Writes facet snapshots (knowledge/policy) per movement iteration

**ArpeggioRunner** (`src/core/piece/engine/ArpeggioRunner.ts`)
- Data-driven batch processing: reads data from a source (e.g., CSV), expands templates per batch, calls LLM for each batch with concurrency control
- Supports retry logic with configurable `maxRetries` and `retryDelayMs`
- Merge strategies: `concat` (default, join with separator) or `custom` (inline JS or file-based)
- Optional output file writing via `outputPath`

**TeamLeaderRunner** (`src/core/piece/engine/TeamLeaderRunner.ts`)
- Decomposes a task into sub-parts via AI (`decomposeTask()`), then executes each part as a sub-agent
- Uses `PartDefinition` schema (id, title, instruction, optional timeoutMs) for decomposed tasks
- Configured via `TeamLeaderConfig` (maxParts ≤3, separate persona/tools/permissions for parts)
- Aggregates sub-part results and evaluates parent rules

**ParallelRunner** (`src/core/piece/engine/ParallelRunner.ts`)
- Executes parallel sub-movements concurrently via `Promise.allSettled()`
- Uses `ParallelLogger` to prefix sub-movement output for readable interleaved display
- Aggregates sub-movement results for parent rule evaluation with `all()` / `any()` conditions

**RuleEvaluator** (`src/core/piece/evaluation/RuleEvaluator.ts`)
- 5-stage fallback evaluation: aggregate → Phase 3 tag → Phase 1 tag → ai() judge → all-conditions AI judge
- Returns `RuleMatch` with index and detection method
- Fail-fast: throws if rules exist but no rule matched
- Tag detection uses **last match** when multiple `[STEP:N]` tags appear in output

**Instruction Builder** (`src/core/piece/instruction/InstructionBuilder.ts`)
- Auto-injects standard sections into every instruction (no need for `{task}` or `{previous_response}` placeholders in templates):
  1. Execution context (working dir, edit permission rules)
  2. Piece context (iteration counts, report dir)
  3. User request (`{task}` — auto-injected unless placeholder present)
  4. Previous response (auto-injected if `pass_previous_response: true`)
  5. User inputs (auto-injected unless `{user_inputs}` placeholder present)
  6. `instruction_template` content
  7. Status output rules (auto-injected for tag-based rules)
- Localized for `en` and `ja`
- Related: `ReportInstructionBuilder` (Phase 2), `StatusJudgmentBuilder` (Phase 3)

**Agent Runner** (`src/agents/runner.ts`)
- Resolves agent specs (name or path) to agent configurations
- Agent is optional — movements can execute with `instruction_template` only (no system prompt)
- 5-layer resolution for provider/model: CLI `--provider` / `--model` → persona_providers → movement override → project `.takt/config.yaml` → global `~/.takt/config.yaml`
- Custom personas via `~/.takt/personas/<name>.md` or prompt files (.md)
- Inline system prompts: If agent file doesn't exist, the agent string is used as inline system prompt

**Provider Integration** (`src/infra/providers/`)
- Unified `Provider` interface: `setup(AgentSetup) → ProviderAgent`, `ProviderAgent.call(prompt, options) → AgentResponse`
- **Claude** (`src/infra/claude/`) - Uses `@anthropic-ai/claude-agent-sdk`
  - `client.ts` - High-level API: `callClaude()`, `callClaudeCustom()`, `callClaudeAgent()`, `callClaudeSkill()`
  - `process.ts` - SDK wrapper with `ClaudeProcess` class
  - `executor.ts` - Query execution
  - `query-manager.ts` - Concurrent query tracking with query IDs
- **Codex** (`src/infra/codex/`) - Uses `@openai/codex-sdk`
  - Retry logic with exponential backoff (3 attempts, 250ms base)
  - Stream handling with idle timeout (10 minutes)
- **OpenCode** (`src/infra/opencode/`) - Uses `@opencode-ai/sdk/v2`
  - Shared server pooling with `acquireClient()` / `releaseClient()`
  - Client-side permission auto-reply
  - Requires explicit `model` specification (no default)
- **Mock** (`src/infra/mock/`) - Deterministic responses for testing

**Configuration** (`src/infra/config/`)
- `loaders/pieceParser.ts` - YAML parsing, movement/rule normalization with Zod validation. Rule regex: `AI_CONDITION_REGEX = /^ai\("(.+)"\)$/`, `AGGREGATE_CONDITION_REGEX = /^(all|any)\((.+)\)$/`
- `loaders/pieceResolver.ts` - **3-layer resolution**: project `.takt/pieces/` → user `~/.takt/pieces/` → builtin `builtins/{lang}/pieces/`. Also supports repertoire packages `@{owner}/{repo}/{piece-name}`
- `loaders/pieceCategories.ts` - Piece categorization and filtering
- `loaders/agentLoader.ts` - Agent prompt file loading
- `paths.ts` - Directory structure (`.takt/`, `~/.takt/`), session management
- `global/globalConfig.ts` - Global configuration (provider, model, language, quiet mode)
- `project/projectConfig.ts` - Project-level configuration

**Task Management** (`src/features/tasks/`)
- `execute/taskExecution.ts` - Main task execution orchestration, worker pool for parallel tasks
- `execute/pieceExecution.ts` - Piece execution wrapper, analytics integration, NDJSON logging
- `add/index.ts` - Interactive task addition via AI conversation
- `list/index.ts` - List task branches with merge/delete/retry actions
- `watch/index.ts` - Watch for task files and auto-execute

**Repertoire** (`src/features/repertoire/`)
- Package management for external facet/piece collections
- Install from GitHub: `github:{owner}/{repo}@{ref}`
- Config validation via `takt-repertoire.yaml` (path constraints, min_version semver check)
- Lock file for resolved dependencies
- Packages installed to `~/.takt/repertoire/@{owner}/{repo}/`

**Analytics** (`src/features/analytics/`)
- Event types: `MovementResultEvent`, `ReviewFindingEvent`, `FixActionEvent`, `RebuttalEvent`
- NDJSON storage at `.takt/events/`
- Integrated into piece execution: movement results, review findings, fix actions

**Catalog** (`src/features/catalog/`)
- Scans 3 layers (builtin → user → project) for available facets
- Shows override detection and source provenance

**Faceted Prompting** (`src/faceted-prompting/`)
- Independent module (no TAKT dependencies) for composing prompts from facets
- `compose(facets, options)` → `ComposedPrompt` (systemPrompt + userMessage)
- Supports template rendering, context truncation, facet path resolution, scope references

**GitHub Integration** (`src/infra/github/`)
- `issue.ts` - Fetches issues via `gh` CLI, formats as task text, supports `createIssue()`
- `pr.ts` - Creates pull requests via `gh` CLI, supports draft PRs and custom templates

### Data Flow

1. User provides task (text or `#N` issue reference) or slash command → CLI
2. CLI loads piece with **priority**: project `.takt/pieces/` → user `~/.takt/pieces/` → builtin `builtins/{lang}/pieces/`
3. PieceEngine starts at `initial_movement`
4. Each movement: delegate to appropriate runner → 3-phase execution → `detectMatchedRule()` → `determineNextMovementByRules()`
5. Rule evaluation determines next movement name (uses **last match** when multiple `[STEP:N]` tags appear)
6. Special transitions: `COMPLETE` ends piece successfully, `ABORT` ends with failure

## Directory Structure

```
~/.takt/                  # Global user config (created on first run)
  config.yaml             # Language, provider, model, log level, etc.
  pieces/                 # User piece YAML files (override builtins)
  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
    @{owner}/{repo}/      # Per-package directory

.takt/                    # Project-level config
  config.yaml             # Project configuration
  facets/                 # Project-level facets
  tasks/                  # Task files for takt run
  runs/                   # Execution reports (runs/{slug}/reports/)
  logs/                   # Session logs in NDJSON format (gitignored)
  events/                 # Analytics event files (NDJSON)

builtins/                 # Bundled defaults (builtin, read from dist/ at runtime)
  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
```

Builtin resources are embedded in the npm package (`builtins/`). Project files in `.takt/` take highest priority, then user files in `~/.takt/`, then builtins. Use `takt eject` to copy builtins for customization.

## Piece YAML Schema

```yaml
name: piece-name
description: Optional description
max_movements: 10
initial_movement: plan    # First movement to execute
interactive_mode: assistant  # Default interactive mode (assistant|passthrough|quiet|persona)
answer_agent: agent-name  # Route AskUserQuestion to this agent (optional)

# Piece-level provider options (inherited by all movements unless overridden)
piece_config:
  provider_options:
    codex: { network_access: true }
    opencode: { network_access: true }
    claude: { sandbox: { allow_unsandboxed_commands: true } }
  runtime:
    prepare: [node, gradle, ./custom-script.sh]  # Runtime environment preparation

# Loop monitors (cycle detection between movements)
loop_monitors:
  - cycle: [review, fix]        # Movement names forming the cycle
    threshold: 3                # Cycles before triggering judge
    judge:
      persona: supervisor
      instruction_template: "Evaluate if the fix loop is making progress..."
      rules:
        - condition: "Progress is being made"
          next: fix
        - condition: "No progress"
          next: ABORT

# 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)
    session: continue                   # Session continuity: continue (default) | refresh
    policy: coding                      # Policy key (single or array)
    knowledge: architecture             # Knowledge key (single or array)
    instruction: plan                   # Instruction key (references section map)
    provider: claude                    # claude|codex|opencode|mock (optional)
    model: opus                         # Model name (optional)
    edit: true                          # Whether movement can edit files
    required_permission_mode: edit      # Required minimum permission mode (optional)
    quality_gates:                      # AI directives for completion (optional)
      - "All tests pass"
      - "No lint errors"
    provider_options:                   # Per-provider options (optional)
      codex: { network_access: true }
      claude: { sandbox: { excluded_commands: [rm] } }
    mcp_servers:                        # MCP server configuration (optional)
      my-server:
        command: npx
        args: [-y, my-mcp-server]
    instruction_template: |
      Custom instructions for this movement.
      {task}, {previous_response} are auto-injected if not present as placeholders.
    pass_previous_response: true        # Default: true
    output_contracts:
      report:
        - name: 01-plan.md             # Report file name
          format: plan                  # References report_formats map
          order: "Write the plan to {report_dir}/01-plan.md"  # Instruction prepend
    rules:
      - condition: "Human-readable condition"
        next: next-movement-name
      - condition: ai("AI evaluates this condition text")
        next: other-movement
      - condition: blocked
        next: ABORT
        requires_user_input: true       # Wait for user input (interactive only)

  # Parallel movement (sub-movements execute concurrently)
  - name: reviewers
    parallel:
      - name: arch-review
        persona: reviewer
        policy: review
        knowledge: architecture
        edit: false
        rules:
          - condition: approved
          - condition: needs_fix
        instruction: review-arch
      - name: security-review
        persona: security-reviewer
        edit: false
        rules:
          - condition: approved
          - condition: needs_fix
        instruction: review-security
    rules:
      - condition: all("approved")
        next: supervise
      - condition: any("needs_fix")
        next: fix

  # Arpeggio movement (data-driven batch processing)
  - name: batch-process
    persona: coder
    arpeggio:
      source: csv
      source_path: ./data/items.csv     # Relative to piece YAML
      batch_size: 5                     # Rows per batch (default: 1)
      concurrency: 3                    # Concurrent LLM calls (default: 1)
      template: ./templates/process.txt # Prompt template file
      max_retries: 2                    # Retry attempts per batch (default: 2)
      retry_delay_ms: 1000             # Delay between retries (default: 1000)
      merge:
        strategy: concat                # concat (default) | custom
        separator: "\n---\n"           # For concat strategy
      output_path: ./output/result.txt  # Write merged results (optional)
    rules:
      - condition: "Processing complete"
        next: COMPLETE

  # Team leader movement (dynamic task decomposition)
  - name: implement
    team_leader:
      max_parts: 3                      # Max parallel parts (1-3, default: 3)
      timeout_ms: 600000               # Per-part timeout (default: 600s)
      part_persona: coder              # Persona for part agents
      part_edit: true                  # Edit permission for parts
      part_permission_mode: edit       # Permission mode for parts
      part_allowed_tools: [Read, Glob, Grep, Edit, Write, Bash]
    instruction_template: |
      Decompose this task into independent subtasks.
    rules:
      - condition: "All parts completed"
        next: review
```

Key points about movement types (mutually exclusive: `parallel`, `arpeggio`, `team_leader`):
- **Parallel**: Sub-movement `rules` define possible outcomes but `next` is ignored (parent handles routing). Parent uses `all("X")`/`any("X")` to aggregate.
- **Arpeggio**: Template placeholders: `{line:N}`, `{col:N:name}`, `{batch_index}`, `{total_batches}`. Merge custom strategy supports inline JS or file.
- **Team leader**: AI generates `PartDefinition[]` (JSON in ```json block), each part executed as sub-movement.

### Rule Condition Types

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

### Template Variables

| Variable | Description |
|----------|-------------|
| `{task}` | Original user request (auto-injected if not in template) |
| `{iteration}` | Piece-wide iteration count |
| `{max_movements}` | Maximum movements allowed |
| `{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 |

### Piece Categories

Pieces can be organized into categories for better UI presentation. Categories are configured in:
- `builtins/{lang}/piece-categories.yaml` - Default builtin categories
- `~/.takt/config.yaml` - User-defined categories (via `piece_categories` field)

Category configuration supports:
- Nested categories (unlimited depth)
- Per-category piece lists
- "Others" category for uncategorized pieces (can be disabled via `show_others_category: false`)
- Builtin piece filtering (disable via `builtin_pieces_enabled: false`, or selectively via `disabled_builtins: [name1, name2]`)

Example category config:
```yaml
piece_categories:
  Development:
    pieces: [default]
    children:
      Backend:
        pieces: [dual-cqrs]
      Frontend:
        pieces: [dual]
  Research:
    pieces: [research, magi]
show_others_category: true
others_category_name: "Other Pieces"
```

### Model Resolution

Model is resolved in the following priority order:

1. **Persona-level `model`** - `persona_providers.<persona>.model`
2. **Movement `model`** - `step.model` / `stepModel` (`piece movement` field)
3. **CLI/task override `model`** - `--model` or task options
4. **Local/Global config `model`** - `.takt/config.yaml` and `~/.takt/config.yaml` when the resolved provider matches
5. **Provider default** - Falls back to provider's default (for example, Claude: sonnet, Codex: gpt-5.2-codex)

### Loop Detection

Two distinct mechanisms:

**LoopDetector** (`src/core/piece/engine/loop-detector.ts`):
- Detects consecutive same-movement executions (simple counter)
- Configurable: `maxConsecutiveSameStep` (default: 10), `action` (`warn` | `abort` | `ignore`)

**CycleDetector** (`src/core/piece/engine/cycle-detector.ts`):
- Detects cyclic patterns between movements (e.g., review → fix → review → fix)
- Configured via `loop_monitors` in piece config (cycle pattern + threshold + judge)
- When threshold reached, triggers a synthetic judge movement for decision-making
- Resets after judge intervention to prevent immediate re-triggering

## NDJSON Session Logging

Session logs use NDJSON (`.jsonl`) format for real-time append-only writes. Record types:

| Record | Description |
|--------|-------------|
| `piece_start` | Piece initialization with task, piece name |
| `movement_start` | Movement execution start |
| `movement_complete` | Movement result with status, content, matched rule info |
| `piece_complete` | Successful completion |
| `piece_abort` | Abort with reason |

Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json` format is still readable via `loadSessionLog()`.

## TypeScript Notes

- ESM modules with `.js` extensions in imports
- Strict TypeScript with `noUncheckedIndexedAccess`
- Zod v4 schemas for runtime validation (`src/core/models/schemas.ts`)
- Uses `@anthropic-ai/claude-agent-sdk` for Claude, `@openai/codex-sdk` for Codex, `@opencode-ai/sdk` for OpenCode

## Design Principles

**Keep commands minimal.** One command per concept. Use arguments/modes instead of multiple similar commands. Before adding a new command, consider if existing commands can be extended.

**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 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}/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: movement-specific procedures and checklists
```

| Deciding where to place content | Facet | Example |
|--------------------------------|-------|---------|
| Role definition, AI habit prevention | Persona | "置き換えたコードを残す → 禁止" |
| Actionable REJECT/APPROVE criterion | Policy | "内部実装のパブリックAPIエクスポート → REJECT" |
| Detailed reasoning, REJECT/OK table with examples | Knowledge | "パブリックAPIの公開範囲" section |
| 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, 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 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
- `MovementExecutor` - Single movement execution (3-phase model)
- `ParallelRunner` - Parallel movement execution
- `ArpeggioRunner` - Data-driven batch processing
- `TeamLeaderRunner` - Dynamic task decomposition
- `RuleEvaluator` - Rule matching and evaluation
- `InstructionBuilder` - Instruction template processing

**Session management:** Agent sessions are stored per-cwd in `~/.claude/projects/{encoded-path}/` (Claude) or in-memory (Codex/OpenCode). Sessions are resumed across phases (Phase 1 → Phase 2 → Phase 3) to maintain context. Session key format: `{persona}:{provider}` to prevent cross-provider contamination. When `cwd !== projectCwd` (worktree/clone execution), session resume is skipped.

## Isolated Execution (Shared Clone)

When tasks specify `worktree: true` or `worktree: "path"`, code runs in a `git clone --shared` (lightweight clone with independent `.git` directory). Clones are ephemeral: created before task execution, auto-committed + pushed after success, then deleted.

> **Why `worktree` in YAML but `git clone --shared` internally?** The YAML field name `worktree` is retained for backward compatibility. The original implementation used `git worktree`, but git worktrees have a `.git` file containing `gitdir: /path/to/main/.git/worktrees/...`. Claude Code follows this path and recognizes the main repository as the project root, causing agents to work on main instead of the worktree. `git clone --shared` creates an independent `.git` directory that prevents this traversal.

Key constraints:

- **Independent `.git`**: Shared clones have their own `.git` directory, preventing Claude Code from traversing `gitdir:` back to the main repository.
- **Ephemeral lifecycle**: Clone is created → task runs → auto-commit + push → clone is deleted. Branches are the single source of truth.
- **Session isolation**: Claude Code sessions are stored per-cwd in `~/.claude/projects/{encoded-path}/`. Sessions from the main project cannot be resumed in a clone. The engine skips session resume when `cwd !== projectCwd`.
- **No node_modules**: Clones only contain tracked files. `node_modules/` is absent.
- **Dual cwd**: `cwd` = clone path (where agents run), `projectCwd` = project root. Reports write to `cwd/.takt/runs/{slug}/reports/` (clone) to prevent agents from discovering the main repository. Logs and session data write to `projectCwd`.
- **List**: Use `takt list` to list branches. Instruct action creates a temporary clone for the branch, executes, pushes, then removes the clone.

## Error Propagation

Provider errors must be propagated through `AgentResponse.error` → session log history → console output. Without this, SDK failures (exit code 1, rate limits, auth errors) appear as empty `blocked` status with no diagnostic info.

**Error handling flow:**
1. Provider error (Claude SDK / Codex / OpenCode) → `AgentResponse.error`
2. `MovementExecutor` captures error → `PieceEngine` emits `phase:complete` with error
3. Error logged to session log (`.takt/logs/{sessionId}.jsonl`)
4. Console output shows error details
5. Piece transitions to `ABORT` movement if error is unrecoverable

## Runtime Environment

Piece-level runtime preparation via `runtime.prepare` in piece config or `~/.takt/config.yaml`:

- **Presets**: `gradle` (sets `GRADLE_USER_HOME`, `JAVA_TOOL_OPTIONS`), `node` (sets `npm_config_cache`)
- **Custom scripts**: Arbitrary shell scripts, resolved relative to cwd or as absolute paths
- Environment injected: `TMPDIR`, `XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `CI=true`
- Creates `.takt/.runtime/` directory structure with `env.sh` for sourcing

Implemented in `src/core/runtime/runtime-environment.ts`.

## Debugging

**Debug logging:** Set `logging.debug: true` in `~/.takt/config.yaml`:
```yaml
logging:
  debug: true
```

Debug logs are written to `.takt/runs/debug-{timestamp}/logs/` in NDJSON format. Log levels: `debug`, `info`, `warn`, `error`.

**Verbose mode:** Set `verbose: true` in `~/.takt/config.yaml` or `TAKT_VERBOSE=true` to enable verbose console output. This enables `logging.debug`, `logging.trace`, and sets `logging.level` to `debug`.

**Session logs:** All piece executions are logged to `.takt/logs/{sessionId}.jsonl`. Use `tail -f .takt/logs/{sessionId}.jsonl` to monitor in real-time.

**Environment variables:**

- `TAKT_LOGGING_LEVEL=info`
- `TAKT_LOGGING_PROVIDER_EVENTS=true`
- `TAKT_VERBOSE=true`

**Testing with mocks:** Use `--provider mock` to test pieces without calling real AI APIs. Mock responses are deterministic and configurable via test fixtures.

## Testing Notes

- Vitest for testing framework (single-thread mode, 15s timeout, 5s teardown timeout)
- Unit tests: `src/__tests__/*.test.ts`
- E2E mock tests: configured via `vitest.config.e2e.mock.ts` (240s timeout, forceExit)
- E2E provider tests: configured via `vitest.config.e2e.provider.ts`
- Test single files: `npx vitest run src/__tests__/filename.test.ts`
- Pattern matching: `npx vitest run -t "test pattern"`
- Integration tests: Tests with `it-` prefix simulate full piece execution
- Engine tests: Tests with `engine-` prefix test PieceEngine scenarios (happy path, error handling, parallel, arpeggio, team-leader, etc.)
- Environment variables cleared in test setup: `TAKT_CONFIG_DIR`, `TAKT_NOTIFY_WEBHOOK`

## Important Implementation Notes

**Persona prompt resolution:**
- Persona paths in piece YAML are resolved relative to the piece file's directory
- `../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 `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

**Session continuity across phases:**
- Agent sessions persist across Phase 1 → Phase 2 → Phase 3 for context continuity
- Session ID is passed via `resumeFrom` in `RunAgentOptions`
- Session key: `{persona}:{provider}` prevents cross-provider session contamination
- Sessions are stored per-cwd, so worktree executions create new sessions
- Use `takt clear` to reset all agent sessions

**Rule evaluation quirks:**
- Tag-based rules match by array index (0-based), not by exact condition text
- When multiple `[STEP:N]` tags appear in output, **last match wins** (not first)
- `ai()` conditions are evaluated by the provider, not by string matching
- 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 aliases: `opus`, `sonnet`, `haiku`
- Codex: In-memory sessions, retry with exponential backoff (3 attempts)
- OpenCode: Shared server pooling, requires explicit `model`, client-side permission auto-reply
- Mock: Deterministic responses, scenario queue support
- Model names are passed directly to provider (no alias resolution in TAKT)

**Permission modes (provider-independent values):**
- `readonly`: Read-only access, no file modifications (Claude: `default`, Codex: `read-only`)
- `edit`: Allow file edits with confirmation (Claude: `acceptEdits`, Codex: `workspace-write`)
- `full`: Bypass all permission checks (Claude: `bypassPermissions`, Codex: `danger-full-access`)
- Resolved via `provider_profiles` (global/project config) with `required_permission_mode` as minimum floor
- Movement-level `required_permission_mode` sets the minimum; `provider_profiles` defaults/overrides can raise it