takt 0.28.0 → 0.29.0

package/README.md

@@ -4,7 +4,7 @@
 
 **T**AKT **A**gent **K**oordination **T**opology — Give your AI coding agents structured review loops, managed prompts, and guardrails — so they deliver quality code, not just code.
 
-TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, Copilot) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative piece files.
+TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, GitHub Copilot CLI) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative piece files.
 
 TAKT is built with TAKT itself (dogfooding).
 
@@ -22,13 +22,15 @@ TAKT is built with TAKT itself (dogfooding).
 
 Choose one:
 
-- **Provider CLIs**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Cursor Agent](https://docs.cursor.com/), or [GitHub Copilot](https://github.com/features/copilot) installed
-- **Direct API**: Anthropic / OpenAI / OpenCode / Cursor API Key (no CLI required)
+- **Provider CLIs**: [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Cursor Agent](https://docs.cursor.com/), or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed
+- **Direct API**: Anthropic / OpenAI / OpenCode API Key (no CLI required)
 
 Optional:
 
 - [GitHub CLI](https://cli.github.com/) (`gh`) — for `takt #N` (GitHub Issue tasks)
 
+> **OAuth and API key usage:** Whether OAuth or API key access is permitted varies by provider and use case. Check each provider's terms of service before using TAKT.
+
 ## Quick Start
 
 ### Install
@@ -44,8 +46,9 @@ $ takt
 
 Select piece:
   ❯ 🎼 default (current)
-    📁 Development/
-    📁 Research/
+    📁 🚀 Quick Start/
+    📁 🎨 Frontend/
+    📁 ⚙️ Backend/
 
 > Add user authentication with JWT
 
@@ -124,12 +127,10 @@ Rules determine the next movement. `COMPLETE` ends the piece successfully, `ABOR
 
 | Piece | Use Case |
 |-------|----------|
-| `default-mini` | Quick fixes. Lightweight plan → implement → parallel review → fix loop. |
-| `default-test-first-mini` | Test-first development. Write tests first, then implement to pass them. |
+| `default` | Standard development. Test-first with AI antipattern review and parallel review (architecture + supervisor). |
 | `frontend-mini` | Frontend-focused mini configuration. |
 | `backend-mini` | Backend-focused mini configuration. |
-| `expert-mini` | Expert-level mini configuration. |
-| `default` | Serious development. Multi-stage review with parallel reviewers. Used for TAKT's own development. |
+| `dual-mini` | Frontend + backend mini configuration. |
 
 See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas.
 
@@ -157,13 +158,14 @@ model: sonnet       # passed directly to provider
 language: en        # en or ja
 ```
 
-Or use API keys directly (no CLI installation required):
+Or use API keys directly (no CLI installation required for Claude, Codex, OpenCode):
 
 ```bash
 export TAKT_ANTHROPIC_API_KEY=sk-ant-...   # Anthropic (Claude)
 export TAKT_OPENAI_API_KEY=sk-...          # OpenAI (Codex)
 export TAKT_OPENCODE_API_KEY=...           # OpenCode
 export TAKT_CURSOR_API_KEY=...             # Cursor Agent (optional if logged in)
+export TAKT_COPILOT_GITHUB_TOKEN=ghp_...   # GitHub Copilot CLI
 ```
 
 See the [Configuration Guide](./docs/configuration.md) for all options, provider profiles, and model resolution.

package/builtins/en/facets/instructions/implement-after-tests.md

@@ -41,6 +41,15 @@ Small / Medium / Large
 - **Rationale**: {Reason for the choice}
 ```
 
+**Pre-completion self-check (required):**
+Before running build and tests, verify the following:
+- If new parameters/fields were added, grep to confirm they are actually passed from call sites
+- For any `??`, `||`, `= defaultValue` usage, confirm fallback is truly necessary
+- Verify no replaced code/exports remain after refactoring
+- Verify no features outside the task specification were added
+- Verify no if/else blocks call the same function with only argument differences
+- Verify new code matches existing implementation patterns (API call style, type definition style, etc.)
+
 **Required output (include headings)**
 ## Work results
 - {Summary of actions taken}

package/builtins/en/facets/instructions/implement.md

@@ -40,6 +40,15 @@ Small / Medium / Large
 - **Rationale**: {Reason for the choice}
 ```
 
+**Pre-completion self-check (required):**
+Before running build and tests, verify the following:
+- If new parameters/fields were added, grep to confirm they are actually passed from call sites
+- For any `??`, `||`, `= defaultValue` usage, confirm fallback is truly necessary
+- Verify no replaced code/exports remain after refactoring
+- Verify no features outside the task specification were added
+- Verify no if/else blocks call the same function with only argument differences
+- Verify new code matches existing implementation patterns (API call style, type definition style, etc.)
+
 **Required output (include headings)**
 ## Work results
 - {Summary of actions taken}

package/builtins/en/facets/instructions/plan.md

@@ -19,3 +19,7 @@ For small tasks, skip the design sections in the report.
 4. Determine file structure and design patterns (if needed)
 5. Decide on the implementation approach
    - Verify the implementation approach does not violate knowledge/policy constraints
+6. Include the following in coder implementation guidelines:
+   - Existing implementation patterns to reference (file:line). Always cite when similar processing already exists
+   - Impact area of changes. Especially when adding new parameters, enumerate all call sites that need wiring
+   - Anti-patterns to watch for in this specific task (if applicable)

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

@@ -3,6 +3,8 @@ Do not review AI-specific issues (already covered by the ai_review movement).
 
 **Review criteria:**
 - Structural and design validity
+- Modularization (high cohesion, low coupling, no circular dependencies)
+- Functionalization (single responsibility per function, operation discoverability, consistent abstraction level)
 - Code quality
 - Appropriateness of change scope
 - Test coverage

package/builtins/en/facets/policies/coding.md

@@ -321,3 +321,6 @@ function formatPercentage(value: number): string { ... }
 - **Replaced code surviving after refactoring** - Remove replaced code and exports. Do not keep unless explicitly told to
 - **Workarounds that bypass safety mechanisms** - If the root fix is correct, no additional bypass is needed
 - **Direct tool execution bypassing project scripts** - `npx tool` and similar bypass the lockfile, causing version mismatches. Look for project-defined scripts (npm scripts, Makefile, etc.) first. Only consider direct execution when no script exists
+- **Missing wiring** - When adding new parameters or fields, grep the entire call chain to verify. If callers do not pass the value, `options.xxx ?? fallback` always uses the fallback
+- **Redundant conditionals** - When if/else calls the same function with only argument differences, unify using ternary operators or spread syntax
+- **Copy-paste patterns** - Before writing new code, grep for existing implementations of the same kind and follow the existing pattern. Do not introduce your own style

package/builtins/en/piece-categories.yaml

@@ -1,20 +1,17 @@
 piece_categories:
   🚀 Quick Start:
     pieces:
-      - default-mini
+      - default
       - frontend-mini
       - backend-mini
-      - default
       - compound-eye
   ⚡ Mini:
     pieces:
-      - default-mini
-      - default-test-first-mini
       - frontend-mini
       - backend-mini
       - backend-cqrs-mini
-      - expert-mini
-      - expert-cqrs-mini
+      - dual-mini
+      - dual-cqrs-mini
   🎨 Frontend:
     pieces:
       - frontend
@@ -25,35 +22,42 @@ piece_categories:
       - backend-mini
       - backend-cqrs
       - backend-cqrs-mini
-  🔧 Expert:
+  🔧 Dual:
     pieces:
-      - expert
-      - expert-mini
-      - expert-cqrs
-      - expert-cqrs-mini
+      - dual
+      - dual-mini
+      - dual-cqrs
+      - dual-cqrs-mini
   🏗️ Infrastructure:
     pieces:
       - terraform
-  🛠️ Refactoring:
-    pieces:
-      - structural-reform
   🔍 Review:
     pieces:
       - review
+      - review-fix
+      - frontend-review
+      - frontend-review-fix
+      - backend-review
+      - backend-review-fix
+      - dual-review
+      - dual-review-fix
+      - dual-cqrs-review
+      - dual-cqrs-review-fix
+      - backend-cqrs-review
+      - backend-cqrs-review-fix
   🧪 Testing:
     pieces:
       - unit-test
       - e2e-test
-  ✅ Test First:
-    pieces:
-      - default-test-first-mini
   🎵 TAKT Development:
     pieces:
       - takt-default
       - takt-default-team-leader
+      - takt-default-review-fix
   Others:
     pieces:
       - research
+      - deep-research
       - magi
 show_others_category: true
 others_category_name: Others

package/builtins/en/pieces/backend-cqrs-review-fix.yaml

@@ -0,0 +1,220 @@
+name: backend-cqrs-review-fix
+description: CQRS+ES focused review + fix loop (structure, modularization, domain model, security, QA)
+piece_config:
+  provider_options:
+    codex:
+      network_access: true
+    opencode:
+      network_access: true
+max_movements: 30
+initial_movement: gather
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-ai-fix
+      rules:
+        - condition: Healthy (progress being made)
+          next: reviewers
+        - condition: Unproductive (repeated findings, fixes not applied)
+          next: supervise
+
+movements:
+  - name: gather
+    edit: false
+    persona: planner
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Bash
+      - WebSearch
+      - WebFetch
+    instruction: gather-review
+    output_contracts:
+      report:
+        - name: review-target.md
+          format: review-gather
+    rules:
+      - condition: Review target information gathered
+        next: reviewers
+      - condition: Unable to identify review target, insufficient information
+        next: ABORT
+
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        edit: false
+        persona: architecture-reviewer
+        policy: review
+        knowledge:
+          - architecture
+          - backend
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-arch
+        output_contracts:
+          report:
+            - name: architect-review.md
+              format: architecture-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: cqrs-es-review
+        edit: false
+        persona: cqrs-es-reviewer
+        policy: review
+        knowledge:
+          - cqrs-es
+          - backend
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-cqrs-es
+        output_contracts:
+          report:
+            - name: cqrs-es-review.md
+              format: cqrs-es-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-security
+        output_contracts:
+          report:
+            - name: security-review.md
+              format: security-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: qa-review
+        edit: false
+        persona: qa-reviewer
+        policy:
+          - review
+          - qa
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-qa
+        output_contracts:
+          report:
+            - name: qa-review.md
+              format: qa-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+    rules:
+      - condition: all("approved")
+        next: supervise
+      - condition: any("needs_fix")
+        next: fix
+
+  - name: fix
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - backend
+      - cqrs-es
+      - security
+      - architecture
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Edit
+      - Write
+      - Bash
+      - WebSearch
+      - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    instruction: fix
+    rules:
+      - condition: Fixes complete
+        next: reviewers
+      - condition: Unable to proceed with fixes
+        next: supervise
+
+  - name: supervise
+    edit: false
+    persona: dual-supervisor
+    policy: review
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - WebSearch
+      - WebFetch
+    instruction: supervise
+    pass_previous_response: false
+    rules:
+      - condition: All validations complete, ready to merge
+        next: COMPLETE
+      - condition: Issues detected
+        next: fix_supervisor
+    output_contracts:
+      report:
+        - name: supervisor-validation.md
+          format: supervisor-validation
+        - name: summary.md
+          format: summary
+          use_judge: false
+
+  - name: fix_supervisor
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - backend
+      - cqrs-es
+      - security
+      - architecture
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Edit
+      - Write
+      - Bash
+      - WebSearch
+      - WebFetch
+    instruction: fix-supervisor
+    pass_previous_response: false
+    rules:
+      - condition: Fixes for supervisor findings complete
+        next: supervise
+      - condition: Unable to proceed with fixes
+        next: supervise

package/builtins/en/pieces/backend-cqrs-review.yaml

@@ -0,0 +1,148 @@
+name: backend-cqrs-review
+description: CQRS+ES focused review (structure, modularization, domain model, security, QA)
+piece_config:
+  provider_options:
+    codex:
+      network_access: true
+    opencode:
+      network_access: true
+max_movements: 10
+initial_movement: gather
+
+movements:
+  - name: gather
+    edit: false
+    persona: planner
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Bash
+      - WebSearch
+      - WebFetch
+    instruction: gather-review
+    output_contracts:
+      report:
+        - name: review-target.md
+          format: review-gather
+    rules:
+      - condition: Review target information gathered
+        next: reviewers
+      - condition: Unable to identify review target, insufficient information
+        next: ABORT
+
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        edit: false
+        persona: architecture-reviewer
+        policy: review
+        knowledge:
+          - architecture
+          - backend
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-arch
+        output_contracts:
+          report:
+            - name: architect-review.md
+              format: architecture-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: cqrs-es-review
+        edit: false
+        persona: cqrs-es-reviewer
+        policy: review
+        knowledge:
+          - cqrs-es
+          - backend
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-cqrs-es
+        output_contracts:
+          report:
+            - name: cqrs-es-review.md
+              format: cqrs-es-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-security
+        output_contracts:
+          report:
+            - name: security-review.md
+              format: security-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: qa-review
+        edit: false
+        persona: qa-reviewer
+        policy:
+          - review
+          - qa
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-qa
+        output_contracts:
+          report:
+            - name: qa-review.md
+              format: qa-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+    rules:
+      - condition: all("approved")
+        next: supervise
+      - condition: any("needs_fix")
+        next: supervise
+
+  - name: supervise
+    edit: false
+    persona: supervisor
+    policy: review
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - WebSearch
+      - WebFetch
+    pass_previous_response: false
+    instruction: supervise
+    output_contracts:
+      report:
+        - name: supervisor-validation.md
+          format: supervisor-validation
+        - name: summary.md
+          format: summary
+          use_judge: false
+    rules:
+      - condition: Review integration complete
+        next: COMPLETE

package/builtins/en/pieces/backend-cqrs.yaml

@@ -235,7 +235,7 @@ movements:
     instruction: fix
   - name: supervise
     edit: false
-    persona: expert-supervisor
+    persona: dual-supervisor
     policy: review
     allowed_tools:
       - Read