takt 0.9.0 → 0.11.0

package/README.md

@@ -92,13 +92,25 @@ takt
 takt hello
 ```
 
-**Note:** Issue references (`#6`) and `--task` / `--issue` options skip interactive mode and execute the task directly. All other inputs (including text with spaces) enter interactive mode for requirement refinement.
+**Note:** `--task` option skips interactive mode and executes the task directly. Issue references (`#6`, `--issue`) are used as initial input in interactive mode.
 
 **Flow:**
 1. Select piece
-2. Refine task content through conversation with AI
-3. Finalize task instructions with `/go` (you can also add additional instructions like `/go additional instructions`), or use `/play <task>` to execute a task immediately
-4. Execute (create worktree, run piece, create PR)
+2. Select interactive mode (assistant / persona / quiet / passthrough)
+3. Refine task content through conversation with AI
+4. Finalize task instructions with `/go` (you can also add additional instructions like `/go additional instructions`), or use `/play <task>` to execute a task immediately
+5. Execute (create worktree, run piece, create PR)
+
+#### Interactive Mode Variants
+
+| Mode | Description |
+|------|-------------|
+| `assistant` | Default. AI asks clarifying questions before generating task instructions. |
+| `persona` | Conversation with the first movement's persona (uses its system prompt and tools). |
+| `quiet` | Generates task instructions without asking questions (best-effort). |
+| `passthrough` | Passes user input directly as task text without AI processing. |
+
+Pieces can set a default mode via the `interactive_mode` field in YAML.
 
 #### Execution Example
 
@@ -451,8 +463,11 @@ TAKT includes multiple builtin pieces:
 | `passthrough` | Thinnest wrapper. Pass task directly to coder as-is. No review. |
 | `compound-eye` | Multi-model review: sends the same instruction to Claude and Codex simultaneously, then synthesizes both responses. |
 | `review-only` | Read-only code review piece that makes no changes. |
+| `structural-reform` | Full project review and structural reform: iterative codebase restructuring with staged file splits. |
+| `unit-test` | Unit test focused piece: test analysis → test implementation → review → fix. |
+| `e2e-test` | E2E test focused piece: E2E analysis → E2E implementation → review → fix (Vitest-based E2E flow). |
 
-**Hybrid Codex variants** (`*-hybrid-codex`): Each major piece has a Codex variant where the coder agent runs on Codex while reviewers use Claude. Available for: default, minimal, expert, expert-cqrs, passthrough, review-fix-minimal, coding.
+**Per-persona provider overrides:** Use `persona_providers` in config to route specific personas to different providers (e.g., coder on Codex, reviewers on Claude) without duplicating pieces.
 
 Use `takt switch` to switch pieces.
 
@@ -475,6 +490,7 @@ Use `takt switch` to switch pieces.
 | **research-planner** | Research task planning and scope definition |
 | **research-digger** | Deep investigation and information gathering |
 | **research-supervisor** | Research quality validation and completeness assessment |
+| **test-planner** | Test strategy analysis and comprehensive test planning |
 | **pr-commenter** | Posts review findings as GitHub PR comments |
 
 ## Custom Personas
@@ -543,8 +559,15 @@ branch_name_strategy: romaji  # Branch name generation: 'romaji' (fast) or 'ai'
 prevent_sleep: false     # Prevent macOS idle sleep during execution (caffeinate)
 notification_sound: true # Enable/disable notification sounds
 concurrency: 1           # Parallel task count for takt run (1-10, default: 1 = sequential)
+task_poll_interval_ms: 500  # Polling interval for new tasks during takt run (100-5000, default: 500)
 interactive_preview_movements: 3  # Movement previews in interactive mode (0-10, default: 3)
 
+# Per-persona provider overrides (optional)
+# Route specific personas to different providers without duplicating pieces
+# persona_providers:
+#   coder: codex             # Run coder on Codex
+#   ai-antipattern-reviewer: claude  # Keep reviewers on Claude
+
 # API Key configuration (optional)
 # Can be overridden by environment variables TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY
 anthropic_api_key: sk-ant-...  # For Claude (Anthropic)

package/builtins/en/config.yaml

@@ -1,34 +1,85 @@
 # TAKT Global Configuration
-# This file contains default settings for takt.
+# Location: ~/.takt/config.yaml
 
-# Language setting (en or ja)
+# ── Basic ──
+
+# Language (en | ja)
 language: en
 
-# Default piece to use when no piece is specified
+# Default piece when no piece is specified
 default_piece: default
 
-# Log level: debug, info, warn, error
+# Log level (debug | info | warn | error)
 log_level: info
 
-# Provider runtime: claude or codex
-provider: claude
+# ── Provider & Model ──
 
-# Builtin pieces (resources/global/{lang}/pieces)
-# enable_builtin_pieces: true
+# Provider runtime (claude | codex)
+provider: claude
 
 # Default model (optional)
-# Claude: opus, sonnet, haiku, opusplan, default, or full model name
+# Claude: opus, sonnet, haiku
 # Codex: gpt-5.2-codex, gpt-5.1-codex, etc.
 # model: sonnet
 
-# Anthropic API key (optional, overridden by TAKT_ANTHROPIC_API_KEY env var)
-# anthropic_api_key: ""
+# Per-persona provider override (optional)
+# Override provider for specific personas. Others use the global provider.
+# persona_providers:
+#   coder: codex
+
+# ── API Keys ──
+# Optional. Environment variables take priority:
+#   TAKT_ANTHROPIC_API_KEY, TAKT_OPENAI_API_KEY
 
-# OpenAI API key (optional, overridden by TAKT_OPENAI_API_KEY env var)
+# anthropic_api_key: ""
 # openai_api_key: ""
 
-# Pipeline execution settings (optional)
-# Customize branch naming, commit messages, and PR body for pipeline mode (--task).
+# ── Execution ──
+
+# Worktree (shared clone) directory (default: ../{clone-name} relative to project)
+# worktree_dir: ~/takt-worktrees
+
+# Auto-create PR after worktree execution (default: prompt in interactive mode)
+# auto_pr: false
+
+# Prevent macOS idle sleep during execution using caffeinate (default: false)
+# prevent_sleep: false
+
+# ── Parallel Execution (takt run) ──
+
+# Number of tasks to run concurrently (1 = sequential, max: 10)
+# concurrency: 1
+
+# Polling interval in ms for picking up new tasks (100-5000, default: 500)
+# task_poll_interval_ms: 500
+
+# ── Interactive Mode ──
+
+# Number of movement previews shown in interactive mode (0 to disable, max: 10)
+# interactive_preview_movements: 3
+
+# Branch name generation strategy (romaji: fast default | ai: slow)
+# branch_name_strategy: romaji
+
+# ── Output ──
+
+# Notification sounds (default: true)
+# notification_sound: true
+
+# Minimal output for CI - suppress AI output (default: false)
+# minimal_output: false
+
+# ── Builtin Pieces ──
+
+# Enable builtin pieces (default: true)
+# enable_builtin_pieces: true
+
+# Exclude specific builtins from loading
+# disabled_builtins:
+#   - magi
+
+# ── Pipeline Mode (--pipeline) ──
+
 # pipeline:
 #   default_branch_prefix: "takt/"
 #   commit_message_template: "feat: {title} (#{issue})"
@@ -37,10 +88,14 @@ provider: claude
 #     {issue_body}
 #     Closes #{issue}
 
-# Notification sounds (true: enabled, false: disabled, default: true)
-# notification_sound: true
+# ── Preferences ──
+
+# Custom paths for preference files
+# bookmarks_file: ~/.takt/preferences/bookmarks.yaml
+# piece_categories_file: ~/.takt/preferences/piece-categories.yaml
+
+# ── Debug ──
 
-# Debug settings (optional)
 # debug:
 #   enabled: false
 #   log_file: ~/.takt/logs/debug.log

package/builtins/en/instructions/implement-e2e-test.md

@@ -0,0 +1,51 @@
+Implement E2E tests according to the test plan.
+Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+
+**Actions:**
+1. Review the test plan report
+2. Implement or update tests following existing E2E layout (e.g., `e2e/specs/`)
+3. Run E2E tests (minimum: `npm run test:e2e:mock`, and targeted spec runs when needed)
+4. If tests fail, analyze root cause, fix test or code, and rerun
+5. Confirm related existing tests are not broken
+
+**Constraints:**
+- Keep the current E2E framework (Vitest) unchanged
+- Keep one scenario per test and make assertions explicit
+- Reuse existing fixtures/helpers/mock strategy for external dependencies
+
+**Scope output contract (create at the start of implementation):**
+```markdown
+# Change Scope Declaration
+
+## Task
+{One-line task summary}
+
+## Planned changes
+| Type | File |
+|------|------|
+| Create | `e2e/specs/example.e2e.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/implement-test.md

@@ -0,0 +1,52 @@
+Implement unit tests according to the test plan.
+Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+
+**Important: Do NOT modify production code. Only test files may be edited.**
+
+**Actions:**
+1. Review the test plan report
+2. Implement the planned test cases
+3. Run tests and verify all pass
+4. Confirm existing tests are not broken
+
+**Test implementation constraints:**
+- Follow the project's existing test patterns (naming conventions, directory structure, helpers)
+- Write tests in Given-When-Then structure
+- One concept per test. Do not mix multiple concerns in a single test
+
+**Scope output contract (create at the start of implementation):**
+```markdown
+# Change Scope Declaration
+
+## Task
+{One-line task summary}
+
+## Planned changes
+| Type | File |
+|------|------|
+| Create | `src/__tests__/example.test.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-e2e-test.md

@@ -0,0 +1,11 @@
+Analyze the target code and identify missing E2E tests.
+
+**Note:** If a Previous Response exists, this is a replan due to rejection.
+Revise the test plan taking that feedback into account.
+
+**Actions:**
+1. Read target features, implementation, and existing E2E specs (`e2e/specs/**/*.e2e.ts`) to understand behavior
+2. Summarize current E2E coverage (happy path, failure path, regression points)
+3. Identify missing E2E scenarios with expected outcomes and observability points
+4. Specify execution commands (`npm run test:e2e:mock` and, when needed, `npx vitest run e2e/specs/<target>.e2e.ts`)
+5. Provide concrete guidance for failure analysis → fix → rerun workflow

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

@@ -0,0 +1,11 @@
+Analyze the target code and identify missing unit tests.
+
+**Note:** If a Previous Response exists, this is a replan due to rejection.
+Revise the test plan taking that feedback into account.
+
+**Actions:**
+1. Read the target module source code and understand its behavior, branches, and state transitions
+2. Read existing tests and identify what is already covered
+3. Identify missing test cases (happy path, error cases, boundary values, edge cases)
+4. Determine test strategy (mock approach, existing test helper usage, fixture design)
+5. Provide concrete guidelines for the test implementer

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

@@ -9,8 +9,14 @@ Do not review AI-specific issues (already covered by the ai_review movement).
 - Dead code
 - Call chain verification
 
+**Previous finding tracking (required):**
+- First, extract open findings from "Previous Response"
+- Assign `finding_id` to each finding and classify current status as `new / persists / resolved`
+- If status is `persists`, provide concrete unresolved evidence (file/line)
+
 ## Judgment Procedure
 
-1. Review the change diff and detect issues based on the architecture and design criteria above
-2. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-3. If there is even one blocking issue, judge as REJECT
+1. First, extract previous open findings and preliminarily classify as `new / persists / resolved`
+2. Review the change diff and detect issues based on the architecture and design criteria above
+3. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
+4. If there is even one blocking issue (`new` or `persists`), judge as REJECT

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

@@ -7,8 +7,14 @@ Review the changes from a quality assurance perspective.
 - Logging and monitoring
 - Maintainability
 
+**Previous finding tracking (required):**
+- First, extract open findings from "Previous Response"
+- Assign `finding_id` to each finding and classify current status as `new / persists / resolved`
+- If status is `persists`, provide concrete unresolved evidence (file/line)
+
 ## Judgment Procedure
 
-1. Review the change diff and detect issues based on the quality assurance criteria above
-2. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-3. If there is even one blocking issue, judge as REJECT
+1. First, extract previous open findings and preliminarily classify as `new / persists / resolved`
+2. Review the change diff and detect issues based on the quality assurance criteria above
+3. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
+4. If there is even one blocking issue (`new` or `persists`), judge as REJECT

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

@@ -0,0 +1,14 @@
+Review the changes from a test quality perspective.
+
+**Review criteria:**
+- Whether all test plan items are covered
+- Test quality (Given-When-Then structure, independence, reproducibility)
+- Test naming conventions
+- Completeness (unnecessary tests, missing cases)
+- Appropriateness of mocks and fixtures
+
+## Judgment Procedure
+
+1. Cross-reference the test plan report ({report:00-test-plan.md}) with the implemented tests
+2. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
+3. If there is even one blocking issue, judge as REJECT

package/builtins/en/output-contracts/architecture-review.md

@@ -14,10 +14,15 @@
 - [x] Dead code
 - [x] Call chain verification
 
+## Previous Open Findings
+| finding_id | Previous Status | Current Status (new/persists/resolved) | Evidence |
+|------------|-----------------|-----------------------------------------|----------|
+| ARCH-EXAMPLE-src-file-L42 | open | persists | `src/file.ts:42` |
+
 ## Issues (if REJECT)
-| # | Scope | Location | Issue | Fix Suggestion |
-|---|-------|----------|-------|----------------|
-| 1 | In-scope | `src/file.ts:42` | Issue description | Fix approach |
+| # | finding_id | Status (new/persists) | Scope | Location | Issue | Fix Suggestion |
+|---|------------|-----------------------|-------|----------|-------|----------------|
+| 1 | ARCH-EXAMPLE-src-file-L42 | new | In-scope | `src/file.ts:42` | Issue description | Fix approach |
 
 Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
 

package/builtins/en/output-contracts/qa-review.md

@@ -15,8 +15,13 @@
 | Documentation | ✅ | - |
 | Maintainability | ✅ | - |
 
+## Previous Open Findings
+| finding_id | Previous Status | Current Status (new/persists/resolved) | Evidence |
+|------------|-----------------|-----------------------------------------|----------|
+| QA-EXAMPLE-src-file-L42 | open | persists | `src/file.ts:42` |
+
 ## Issues (if REJECT)
-| # | Category | Issue | Fix Suggestion |
-|---|----------|-------|----------------|
-| 1 | Testing | Issue description | Fix approach |
+| # | finding_id | Status (new/persists) | Category | Issue | Fix Suggestion |
+|---|------------|-----------------------|----------|-------|----------------|
+| 1 | QA-EXAMPLE-src-file-L42 | new | Testing | Issue description | Fix approach |
 ```

package/builtins/en/output-contracts/test-plan.md

@@ -0,0 +1,24 @@
+```markdown
+# Test Plan
+
+## Target Modules
+{List of modules to analyze}
+
+## Existing Test Analysis
+| Module | Existing Tests | Coverage Status |
+|--------|---------------|-----------------|
+| `src/xxx.ts` | `xxx.test.ts` | {Coverage status} |
+
+## Missing Test Cases
+| # | Target | Test Case | Priority | Reason |
+|---|--------|-----------|----------|--------|
+| 1 | `src/xxx.ts` | {Test case summary} | High/Medium/Low | {Reason} |
+
+## Test Strategy
+- {Mock approach}
+- {Fixture design}
+- {Test helper usage}
+
+## Implementation Guidelines
+- {Concrete instructions for the test implementer}
+```

package/builtins/en/personas/test-planner.md

@@ -0,0 +1,25 @@
+# Test Planner
+
+You are a **test analysis and planning specialist**. You understand the behavior of target code, analyze existing test coverage, and systematically identify missing test cases.
+
+## Role Boundaries
+
+**Do:**
+- Analyze target code behavior, branches, and state transitions
+- Analyze existing test coverage
+- Identify missing test cases (happy path, error cases, boundary values, edge cases)
+- Determine test strategy (mock approach, fixture design, test helper usage)
+- Provide concrete guidelines for test implementers
+
+**Don't:**
+- Plan production code changes (Planner's job)
+- Implement test code (Coder's job)
+- Review code (Reviewer's job)
+
+## Behavioral Principles
+
+- Read the code before planning. Don't list test cases based on guesses
+- Always check existing tests. Don't duplicate already-covered scenarios
+- Prioritize tests: business logic and state transitions > edge cases > simple CRUD
+- Provide instructions at a granularity that prevents test implementers from hesitating
+- Follow the project's existing test patterns. Don't propose novel conventions

package/builtins/en/piece-categories.yaml

@@ -10,6 +10,10 @@ piece_categories:
     pieces:
       - review-fix-minimal
       - review-only
+  🧪 Testing:
+    pieces:
+      - unit-test
+      - e2e-test
   🎨 Frontend: {}
   ⚙️ Backend: {}
   🔧 Expert:
@@ -17,20 +21,9 @@ piece_categories:
       pieces:
         - expert
         - expert-cqrs
-  🔀 Hybrid (Codex Coding):
-    🚀 Quick Start:
-      pieces:
-        - coding-hybrid-codex
-        - default-hybrid-codex
-        - minimal-hybrid-codex
-        - passthrough-hybrid-codex
-    🔧 Expert:
-      pieces:
-        - expert-cqrs-hybrid-codex
-        - expert-hybrid-codex
-    🔍 Review & Fix:
+    Refactoring:
       pieces:
-        - review-fix-minimal-hybrid-codex
+        - structural-reform
   Others:
     pieces:
       - research

package/builtins/en/pieces/coding.yaml

@@ -1,24 +1,6 @@
 name: coding
 description: Lightweight development piece with planning and parallel reviews (plan -> implement -> parallel review -> complete)
 max_iterations: 20
-policies:
-  coding: ../policies/coding.md
-  review: ../policies/review.md
-  testing: ../policies/testing.md
-  ai-antipattern: ../policies/ai-antipattern.md
-knowledge:
-  architecture: ../knowledge/architecture.md
-personas:
-  planner: ../personas/planner.md
-  coder: ../personas/coder.md
-  ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
-  architecture-reviewer: ../personas/architecture-reviewer.md
-instructions:
-  plan: ../instructions/plan.md
-  implement: ../instructions/implement.md
-  ai-review: ../instructions/ai-review.md
-  review-arch: ../instructions/review-arch.md
-  fix: ../instructions/fix.md
 initial_movement: plan
 movements:
   - name: plan
@@ -150,7 +132,3 @@ movements:
       - condition: Cannot determine, insufficient information
         next: ABORT
     instruction: fix
-report_formats:
-  plan: ../output-contracts/plan.md
-  ai-review: ../output-contracts/ai-review.md
-  architecture-review: ../output-contracts/architecture-review.md

package/builtins/en/pieces/compound-eye.yaml

@@ -1,11 +1,6 @@
 name: compound-eye
 description: Multi-model review - send the same instruction to Claude and Codex simultaneously, synthesize both responses
 max_iterations: 10
-knowledge:
-  architecture: ../knowledge/architecture.md
-personas:
-  coder: ../personas/coder.md
-  supervisor: ../personas/supervisor.md
 initial_movement: evaluate
 movements:
   - name: evaluate

package/builtins/en/pieces/default.yaml

@@ -1,32 +1,6 @@
 name: default
 description: Standard development piece with planning and specialized reviews
 max_iterations: 30
-policies:
-  coding: ../policies/coding.md
-  review: ../policies/review.md
-  testing: ../policies/testing.md
-  ai-antipattern: ../policies/ai-antipattern.md
-  qa: ../policies/qa.md
-knowledge:
-  backend: ../knowledge/backend.md
-  architecture: ../knowledge/architecture.md
-personas:
-  planner: ../personas/planner.md
-  coder: ../personas/coder.md
-  ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
-  architecture-reviewer: ../personas/architecture-reviewer.md
-  qa-reviewer: ../personas/qa-reviewer.md
-  supervisor: ../personas/supervisor.md
-instructions:
-  plan: ../instructions/plan.md
-  implement: ../instructions/implement.md
-  ai-review: ../instructions/ai-review.md
-  ai-fix: ../instructions/ai-fix.md
-  arbitrate: ../instructions/arbitrate.md
-  review-arch: ../instructions/review-arch.md
-  review-qa: ../instructions/review-qa.md
-  fix: ../instructions/fix.md
-  supervise: ../instructions/supervise.md
 initial_movement: plan
 loop_monitors:
   - cycle:
@@ -282,10 +256,3 @@ movements:
       report:
         - Validation: 07-supervisor-validation.md
         - Summary: summary.md
-report_formats:
-  plan: ../output-contracts/plan.md
-  ai-review: ../output-contracts/ai-review.md
-  architecture-review: ../output-contracts/architecture-review.md
-  qa-review: ../output-contracts/qa-review.md
-  validation: ../output-contracts/validation.md
-  summary: ../output-contracts/summary.md