takt: refactor-status-handling (#477)

Config:
- PersistedGlobalConfig → GlobalConfig にリネーム、互換エイリアス削除
- persisted-global-config.ts → config-types.ts にリネーム
- ProjectConfig → GlobalConfig extends Omit<ProjectConfig, ...> の継承構造に整理
- verbose/logLevel/log_level を削除（logging セクションに統一）
- migration 機構（migratedProjectLocalKeys 等）を削除

Supervisor ペルソナ:
- 後方互換コードの検出・その場しのぎの検出・ボーイスカウトルールを除去（review.md ポリシー / architecture.md ナレッジと重複）
- ピース全体の見直しを supervise.md インストラクションに移動

takt-default-team-leader:
- loop_monitor のインライン instruction_template を既存ファイル参照に変更
- implement の「判断できない」ルールを ai_review → plan に修正

.github/workflows/announce.yml

@@ -0,0 +1,69 @@
+name: Announce
+
+on:
+  workflow_dispatch:
+    inputs:
+      title:
+        description: "タイトル"
+        required: true
+        type: string
+      body:
+        description: "本文（Markdown可、X向けには自動でプレーンテキスト化）"
+        required: true
+        type: string
+      channels:
+        description: "投稿先"
+        required: true
+        type: choice
+        default: "all"
+        options:
+          - all
+          - discussions
+          - discord
+          - twitter
+
+jobs:
+  discussions:
+    if: inputs.channels == 'all' || inputs.channels == 'discussions'
+    runs-on: ubuntu-latest
+    permissions:
+      discussions: write
+    steps:
+      - name: Post to GitHub Discussions
+        uses: abirber/github-create-discussion@v6
+        with:
+          title: ${{ inputs.title }}
+          body: ${{ inputs.body }}
+          repository-id: ${{ github.event.repository.node_id }}
+          category-name: "Announcements"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  discord:
+    if: inputs.channels == 'all' || inputs.channels == 'discord'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post to Discord
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          TITLE: ${{ inputs.title }}
+          BODY: ${{ inputs.body }}
+        run: |
+          jq -n \
+            --arg title "$TITLE" \
+            --arg desc "$BODY" \
+            '{embeds: [{title: $title, description: $desc, color: 5814783}]}' \
+          | curl -sf -X POST -H "Content-Type: application/json" -d @- "$DISCORD_WEBHOOK_URL"
+
+  twitter:
+    if: inputs.channels == 'all' || inputs.channels == 'twitter'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post to X
+        uses: ethomson/send-tweet-action@v2
+        with:
+          status: "${{ inputs.title }}\n\n${{ inputs.body }}"
+          consumer-key: ${{ secrets.TWITTER_CONSUMER_API_KEY }}
+          consumer-secret: ${{ secrets.TWITTER_CONSUMER_API_SECRET }}
+          access-token: ${{ secrets.TWITTER_ACCESS_TOKEN }}
+          access-token-secret: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}

.github/workflows/cc-resolve.yml

@@ -0,0 +1,275 @@
+name: CC Resolve
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  resolve:
+    # Uncomment to allow organization members or collaborators:
+    # || github.event.comment.author_association == 'MEMBER'
+    # || github.event.comment.author_association == 'COLLABORATOR'
+    if: |
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/resolve') &&
+      github.event.comment.author_association == 'OWNER'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Acknowledge
+        run: |
+          gh api repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions \
+            -f content=rocket
+          gh pr comment ${{ github.event.issue.number }} --repo ${{ github.repository }} \
+            --body "🚀 cc-resolve started: [View logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check if fork PR
+        id: pr
+        run: |
+          PR_REPO=$(gh pr view ${{ github.event.issue.number }} --repo ${{ github.repository }} \
+            --json headRepositoryOwner,headRepository \
+            --jq '"\(.headRepositoryOwner.login)/\(.headRepository.name)"')
+          BRANCH=$(gh pr view ${{ github.event.issue.number }} --repo ${{ github.repository }} \
+            --json headRefName -q .headRefName)
+          echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+          if [ "$PR_REPO" != "${{ github.repository }}" ]; then
+            echo "::error::Fork PR はサポートしていません。contributor 側で解決してください。"
+            exit 1
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.pr.outputs.branch }}
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Merge main (detect conflicts)
+        id: merge
+        run: |
+          git fetch origin main
+          # --no-commit --no-ff: コンフリクトの有無にかかわらず常にマージ状態を保持する
+          # これにより最後の git commit が必ずマージコミット（親2つ）を作る
+          if git merge --no-commit --no-ff origin/main 2>/dev/null; then
+            echo "conflicts=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "conflicts=true" >> "$GITHUB_OUTPUT"
+          fi
+
+          # コミット済みのコンフリクトマーカーを検出
+          STALE_MARKERS=$(grep -rl '<<<<<<<' --include='*.ts' --include='*.js' --include='*.json' --include='*.yaml' --include='*.yml' --include='*.md' . 2>/dev/null | grep -v node_modules | grep -v .git || echo "")
+          if [ -n "$STALE_MARKERS" ]; then
+            echo "stale_markers=true" >> "$GITHUB_OUTPUT"
+            {
+              echo "stale_marker_files<<MARKER_EOF"
+              echo "$STALE_MARKERS"
+              echo "MARKER_EOF"
+            } >> "$GITHUB_OUTPUT"
+          else
+            echo "stale_markers=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Resolve
+        run: |
+          claude -p --dangerously-skip-permissions "$(cat <<'PROMPT'
+          このPRのコンフリクトを解決してください。
+
+          ## 状況判定
+
+          まず現在の状態を確認してください。以下の2つをすべてチェックする。
+
+          1. `git status` でマージコンフリクト（Unmerged paths）の有無を確認
+          2. ファイル中にコミット済みのコンフリクトマーカー（`<<<<<<<`）が残っていないか `grep -r '<<<<<<<' --include='*.ts' --include='*.js' --include='*.json' .` で確認
+
+          **重要**: git status がクリーンでも、ファイル内にコンフリクトマーカーがテキストとしてコミットされている場合がある。必ず grep で確認すること。
+
+          どちらも該当しなければ「コンフリクトなし」と報告して終了。
+
+          ---
+
+          ## コンフリクト解決
+
+          Git merge/rebase/cherry-pick のコンフリクト、およびファイル内に残存するコンフリクトマーカーを、差分分析に基づいて解決する。
+
+          **原則: 差分を読み、疑い、判断根拠を書いてから解決する。妄信的に片方を採用しない。**
+
+          ### 1. コンフリクト状態を確認する
+
+          ```bash
+          git status
+          ```
+
+          - merge / rebase / cherry-pick のどれが進行中か特定する
+            - `.git/MERGE_HEAD` があれば merge
+            - `.git/rebase-merge/` があれば rebase
+            - `.git/CHERRY_PICK_HEAD` があれば cherry-pick
+
+          ### 2. コンテキストを把握する
+
+          以下を**並列で**実行:
+
+          - `git log --oneline HEAD -5` で HEAD 側（現在のブランチ）の最近の変更を確認
+          - `git log --oneline MERGE_HEAD -5` で取り込み側の最近の変更を確認（merge の場合）
+          - 両ブランチの関係性（どちらがベースでどちらが新しいか）を理解する
+
+          ### 3. コンフリクトファイルを列挙する
+
+          ```bash
+          git diff --name-only --diff-filter=U
+          ```
+
+          加えて、コミット済みマーカーがあるファイルも対象に含める:
+          ```bash
+          grep -rl '<<<<<<<' --include='*.ts' --include='*.js' --include='*.json' . | grep -v node_modules
+          ```
+
+          ファイル数と種類（ソースコード / 設定ファイル / ロックファイル等）を報告する。
+
+          ### 4. 各ファイルを分析する
+
+          **ここが核心。ファイルごとに以下を必ず実行する。省略しない。**
+
+          1. ファイル全体を読む（コンフリクトマーカー付きの状態）
+          2. 各コンフリクトブロック（`<<<<<<<` 〜 `>>>>>>>`）について:
+             - HEAD 側の内容を具体的に読む
+             - theirs 側の内容を具体的に読む
+             - 差分が何を意味するか分析する（バージョン番号？リファクタ？機能追加？型変更？）
+             - 判断に迷う場合は `git log --oneline -- {file}` で変更履歴を確認する
+          3. **判断を書く**（以下の形式で必ず出力すること）:
+
+          ```markdown
+          ### ファイル: path/to/file.ts
+
+          #### コンフリクト 1 (L30-45)
+          - HEAD 側: {具体的な内容を書く}
+          - theirs 側: {具体的な内容を書く}
+          - 分析: {差分が何を意味するか}
+          - 判断: {HEAD / theirs / 両方統合} を採用（{理由}）
+          ```
+
+          **疑うべきポイント:**
+          - 「〇〇側が新しいから」だけで判断していないか？ HEAD 側に独自の意図ある変更はないか？
+          - theirs を採用すると、HEAD 側でしか行っていない作業が消えないか？
+          - 両方の変更を統合すべきケースではないか？
+          - package-lock.json のような機械生成ファイルでも、バージョンの意味を確認したか？
+
+          ### 5. 解決を実施する
+
+          ステップ4の分析結果に基づいて解決する:
+
+          - 片方採用が明確な場合: `git checkout --ours {file}` / `git checkout --theirs {file}` を使ってよい（**分析済みファイルのみ**）
+          - 両方の変更を統合する場合: コンフリクトマーカーを除去し、両方の内容を適切に結合する
+          - 解決したファイルを `git add {file}` でマークする
+
+          解決後、`<<<<<<<` を検索し、マーカーの取り残しがないか確認する。
+
+          ---
+
+          ## 波及影響確認
+
+          **コンフリクトを解決しただけでは終わらない。** 対象外ファイルにも影響が出ていないか検証する。
+
+          - ビルド確認（`npm run build`、`./gradlew build` 等、プロジェクトに応じて）
+          - テスト確認（`npm test`、`./gradlew test` 等）
+          - 対象外ファイルが、変更と矛盾していないか確認する
+            - 例: 関数シグネチャを変更したのに、テストが旧シグネチャを期待している
+            - 例: import パスを変更したのに、別ファイルが旧パスを参照している
+
+          問題が見つかった場合はここで修正する。
+
+          ---
+
+          ## 結果を報告する
+
+          全ファイルの解決結果をサマリーテーブルで報告する:
+
+          ```markdown
+          ## コンフリクト解決サマリー
+
+          | ファイル | コンフリクト数 | 採用 | 理由 |
+          |---------|-------------|------|------|
+          | path/to/file.ts | 2 | theirs | リファクタリング済み |
+
+          波及修正: {対象外ファイルの修正内容。なければ「なし」}
+          ビルド: OK / NG
+          テスト: OK / NG ({passed}/{total})
+          ```
+
+          ---
+
+          ## 絶対原則
+
+          - **差分を読まずに解決しない。** ファイルの中身を確認せずに `--ours` / `--theirs` を適用しない
+          - **盲従しない。** HEAD 側に独自の意図がないか必ず疑う
+          - **判断根拠を省略しない。** 各コンフリクトに「何が・なぜ・どちらを」の3点を書く
+          - **波及を確認する。** 対象外ファイルもビルド・テストで検証する
+
+          ## 禁止事項
+
+          - 分析なしで `git checkout --ours .` / `git checkout --theirs .` を実行しない
+          - 「とりあえず片方」で全ファイルを一括解決しない
+          - コンフリクトマーカー (`<<<<<<<`) が残ったままにしない
+          - `git merge --abort` を実行しない
+          - `git reset` を実行しない（MERGE_HEAD が消えてマージコミットが作れなくなる）
+          - `.git/MERGE_HEAD` を保持したまま作業すること
+          PROMPT
+          )" --verbose
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Commit and push
+        run: |
+          git add -A
+          # MERGE_HEAD があればマージコミット、なければ通常コミット
+          if [ -f .git/MERGE_HEAD ]; then
+            git commit -m "merge: integrate main into PR branch"
+          elif ! git diff --cached --quiet; then
+            git commit -m "fix: resolve merge conflicts"
+          fi
+          AHEAD=$(git rev-list --count origin/${{ steps.pr.outputs.branch }}..HEAD 2>/dev/null || echo "0")
+          if [ "$AHEAD" -gt 0 ]; then
+            echo "Pushing $AHEAD commit(s)"
+            git push
+            echo "pushed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Nothing to push"
+            echo "pushed=false" >> "$GITHUB_OUTPUT"
+          fi
+        id: push
+
+      - name: Trigger CI
+        if: steps.push.outputs.pushed == 'true'
+        run: |
+          gh workflow run ci.yml --ref "${{ steps.pr.outputs.branch }}"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Report result
+        if: always()
+        run: |
+          PR_NUMBER=${{ github.event.issue.number }}
+          RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          if [ "${{ job.status }}" = "success" ]; then
+            gh pr comment "$PR_NUMBER" --repo ${{ github.repository }} --body "✅ cc-resolve completed. [View logs](${RUN_URL})"
+          else
+            gh pr comment "$PR_NUMBER" --repo ${{ github.repository }} --body "❌ cc-resolve failed. [View logs](${RUN_URL})"
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -3,8 +3,14 @@ name: CI
 on:
   pull_request:
     branches: [main]
+    types: [opened, synchronize, ready_for_review]
   push:
     branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+  cancel-in-progress: true
 
 jobs:
   lint:

.github/workflows/takt-review.yml

@@ -0,0 +1,70 @@
+name: TAKT PR Review
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, ready_for_review, reopened]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    environment: takt-review
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          fetch-depth: 0
+
+      - name: API キー確認
+        run: |
+          if [ -z "$ANTHROPIC_API_KEY" ]; then
+            echo "::error::ANTHROPIC_API_KEY is not set"
+            exit 1
+          fi
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Claude Code & TAKT インストール
+        run: |
+          npm install -g @anthropic-ai/claude-code
+          npm install -g takt
+
+      - name: TAKT Review 実行
+        run: takt --pipeline --skip-git -i ${{ github.event.pull_request.number }} -w review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+
+      - name: レビュー結果をPRコメントに投稿
+        if: always()
+        run: |
+          REPORT_DIR=$(ls -td .takt/runs/*/reports 2>/dev/null | head -1)
+          if [ -n "$REPORT_DIR" ]; then
+            SUMMARY=$(find "$REPORT_DIR" -name "*review-summary*" -type f | head -1)
+            if [ -n "$SUMMARY" ]; then
+              gh pr comment ${{ github.event.pull_request.number }} --body-file "$SUMMARY"
+            else
+              echo "レビューサマリーが見つかりません"
+            fi
+          else
+            echo "レポートディレクトリが見つかりません"
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+
+      - name: レビューレポートをアーティファクトに保存
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: takt-review-reports
+          path: .takt/runs/*/reports/
+          if-no-files-found: ignore

.gitignore

@@ -23,27 +23,16 @@ npm-debug.log*
 # Test coverage
 coverage/
 
+# E2E test results
+e2e/results/
+
 # Environment
 .env
 .env.local
 .env.*.local
 .envrc
 
-# TAKT config (user data)
+# TAKT runtime data (facets/pieces/config are managed by .takt/.gitignore)
-.takt/
-!.takt/config.yaml
-!.takt/pieces/
-!.takt/pieces/**
-!.takt/personas/
-!.takt/personas/**
-!.takt/policies/
-!.takt/policies/**
-!.takt/knowledge/
-!.takt/knowledge/**
-!.takt/instructions/
-!.takt/instructions/**
-!.takt/output-contracts/
-!.takt/output-contracts/**
 
 task_planning/
 

.takt/.gitignore

@@ -0,0 +1,22 @@
+# Ignore everything by default
+*
+
+# This file itself
+!.gitignore
+
+# Project configuration
+!config.yaml
+
+# Facets and pieces (version-controlled)
+!pieces/
+!pieces/**
+!personas/
+!personas/**
+!policies/
+!policies/**
+!knowledge/
+!knowledge/**
+!instructions/
+!instructions/**
+!output-contracts/
+!output-contracts/**

.takt/config.yaml

@@ -0,0 +1,11 @@
+piece_overrides:
+  movements:
+    implement:
+      quality_gates:
+        - "Run `npm run test:e2e:mock` and verify all E2E tests pass"
+    fix:
+      quality_gates:
+        - "Run `npm run test:e2e:mock` and verify all E2E tests pass"
+    ai_fix:
+      quality_gates:
+        - "Run `npm run test:e2e:mock` and verify all E2E tests pass"

AGENTS.md

@@ -1,41 +1,40 @@
 # Repository Guidelines
-このドキュメントは、このリポジトリに貢献するための実務的な指針をまとめたものです。短く具体的な説明と例で、作業の迷いを減らします。
 
 ## Project Structure & Module Organization
-- 主要ソースは `src/` にあり、エントリポイントは `src/index.ts`、CLI は `src/app/cli/index.ts` です。
+- `src/`: TypeScript の本体コード。CLI は `src/app/cli/`、コア実行ロジックは `src/core/`、共通機能は `src/shared/`、機能別実装は `src/features/` に配置。
-- テストは `src/__tests__/` に置き、対象が明確になる名前を付けます（例: `client.test.ts`）。
+- `src/__tests__/`: 単体・統合テスト（`*.test.ts`）。
-- ビルド成果物は `dist/`、実行スクリプトは `bin/`、静的リソースは `resources/`、ドキュメントは `docs/` で管理します。
+- `e2e/`: E2E テストと補助ヘルパー。
-- 実行時の設定やキャッシュは `~/.takt/`、プロジェクト固有の設定は `.takt/` を参照します。
+- `builtins/`: 組み込みピース、テンプレート、スキーマ。
+- `docs/`: 設計・CLI・運用ドキュメント。
+- `dist/`: ビルド成果物（生成物のため手編集しない）。
+- `bin/`: CLI エントリーポイント（`takt`, `takt-dev`）を提供。
 
 ## Build, Test, and Development Commands
-- `npm run build`: TypeScript をコンパイルして `dist/` を生成します。
+- `npm install`: 依存関係をインストール。
-- `npm run watch`: ソース変更を監視しながら再ビルドします。
+- `npm run build`: TypeScript を `dist/` にビルドし、プロンプト・i18n・preset ファイルをコピー。
-- `npm run lint`: ESLint で `src/` を解析します。
+- `npm run watch`: `tsc --watch` で継続ビルド。
-- `npm run test`: Vitest で全テストを実行します。
+- `npm run lint`: `src/` を ESLint で検証。
-- `npm run test:watch`: テストをウォッチ実行します。
+- `npm test`: `vitest run` で通常テスト実行。
-- `npx vitest run src/__tests__/client.test.ts`: 単体テストを個別実行する例です。
+- `npm run test:e2e:mock`: モックプロバイダーで E2E 実行。
+- `npm run test:e2e:all`: mock + provider E2E を連続実行。
 
 ## Coding Style & Naming Conventions
-- TypeScript + strict を前提に、null 安全と可読性を優先します。
+- 言語は TypeScript（ESM）。インデントは 2 スペース、既存スタイルを維持。
-- ESM 形式のため、`import` の拡張子は `.js` に固定してください。
+- ファイル名は機能を表す `kebab-case` または既存準拠（例: `taskHistory.ts`）。
-- 命名は camelCase（関数・変数）と PascalCase（クラス）を採用します。
+- テスト名は対象機能が分かる具体名（例: `provider-model.test.ts`）。
-- 共有型は `src/types/` に整理し、既存の命名パターンに合わせます。
+- Lint ルール: `@typescript-eslint/no-explicit-any` と未使用変数を厳格に検出（未使用引数は `_` 接頭辞で許容）。
-- ESLint と Prettier の規約に従い、修正後は `npm run lint` を実行します。
 
 ## Testing Guidelines
-- テストフレームワークは Vitest（`vitest.config.ts`）です。
+- フレームワークは Vitest。Node 環境で実行。
-- 新規機能や修正には関連テストを追加します。
+- 変更時は最低限 `npm test` を通し、実行経路に影響する変更は `npm run test:e2e:mock` まで確認。
-- ファイル名は `<対象>.test.ts` または `<対象>.spec.ts` を使用します。
+- カバレッジ取得は Vitest の V8 レポーター（text/json/html）を使用。
-- 依存が重い箇所はモックやスタブで状態を分離します。
 
 ## Commit & Pull Request Guidelines
-- コミットメッセージは短い要約が中心で、日本語・英語どちらも使われています。
+- コミットは小さく、1コミット1目的。
-- `fix:`, `hotfix:` などのプレフィックスや、`#32` のような Issue 参照が見られます。必要に応じて付けてください。
+- 形式は Conventional Commits 推奨（`feat:`, `fix:`, `refactor:`, `test:`）。必要に応じて Issue 番号を付与（例: `fix: ... (#388)` / `[#367] ...`）。
-- バージョン更新や変更履歴の更新は明示的なメッセージで行います（例: `0.5.1`, `update CHANGELOG`）。
+- PR では目的、変更点、テスト結果、影響範囲を明記。挙動変更がある場合は再現手順を添付。
-- PR には変更概要、テスト結果、関連 Issue を記載し、小さく分割してレビュー負荷を抑えます。UI/ログ変更がある場合はスクリーンショットやログを添付します。
+- 大規模変更は先に Issue で合意し、関連ドキュメント（`README.md` / `docs/`）も更新する。
 
 ## Security & Configuration Tips
-- 脆弱性は公開 Issue ではなくメンテナへ直接報告します。
+- 機密情報（API キー、トークン）はコミットしない。設定は `~/.takt/config.yaml` や環境変数を使用。
-- `.takt/logs/` など機密情報を含む可能性のあるファイルは共有しないでください。
+- Provider や実行モード変更時は `docs/configuration.md` と `docs/provider-sandbox.md` を先に確認する。
-- `~/.takt/config.yaml` の `trusted` ディレクトリは最小限にし、不要なパスは登録しないでください。
-- 新しいピースを追加する場合は `~/.takt/pieces/` の既存スキーマに合わせます。

CHANGELOG.md

@@ -6,6 +6,265 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.30.0] - 2026-03-05
+
+### Added
+
+- トレースレポートの自動生成: piece 実行完了時に movement の遷移・フェーズ・ルール評価結果を Markdown レポートとして `.takt/runs/` に自動出力。`logging.trace: true` で全文モード、デフォルトは redacted モード (#467)
+- 使用量イベントログ: プロバイダー呼び出しごとのトークン使用量を NDJSON 形式で記録。`logging.usage_events: true` で有効化 (#470)
+- タスクリトライ時のピース再利用確認: `takt list` からリトライ・追加指示する際に、前回と同じピースを使うか選び直すかを選択可能に (#468)
+
+### Changed
+
+- BREAKING: `takt switch` コマンドを削除。ピース選択はインタラクティブモード起動時（`takt`）に毎回行う方式に変更 (#465)
+- Claude プロバイダーの `allowed_tools` をビルトインピースの YAML 定義からエグゼキューター側に移動し、ピース YAML の簡素化と保守性を向上 (#469)
+- 設定構造をリファクタリング: `globalConfig.ts` を `globalConfigCore.ts`・`globalConfigAccessors.ts`・`globalConfigResolvers.ts`・`globalConfigSerializer.ts` に分割。プロジェクトローカル設定（`.takt/config.yaml`）のフォールバック優先度を明確化 (#460)
+- observability モジュールを `core/logging/` に再編成: `providerEventLogger` と `usageEventLogger` を統一的なログ基盤として整理 (#466)
+- レビュアー全体に `coder-decisions.md` の参照を追加し、コーダーの設計判断を考慮したレビューで誤検知を抑制
+- レビュー↔修正ループの収束を支援: レポート履歴の参照、ループモニター、修正方針のガイドラインを整備
+
+### Fixed
+
+- runtime 環境の `XDG_CONFIG_HOME` 上書きで `gh` CLI の認証が失敗する問題を修正。`GH_CONFIG_DIR` を元の設定から保持するよう変更
+- `.takt/config.yaml` に `runtime.prepare` を記述するとエラーになる問題を修正（プロジェクトレベルでの runtime 設定を許可） (#464)
+- インタラクティブモードで iteration limit 到達時にプロンプトが表示されず、exceeded 状態が保持されない問題を修正
+- PR 作成失敗時のタスクステータスを `failed` から `pr_failed` に分離し、実行成功だが PR 作成のみ失敗したケースを区別可能に
+- リトライ時にタスクにピース情報が引き継がれるよう修正
+- `.gitignore` の `.takt/` ディレクトリ ignore を削除し `.takt/.gitignore` に委譲（プロジェクト設定ファイルの追跡を可能に）
+- CI: push トリガーから `takt/**` を削除し二重実行を防止
+- `cc-resolve` ワークフローで push 後に CI を自動トリガーするよう修正
+
+### Internal
+
+- deprecated config マイグレーション処理を削除
+- プロジェクトローカル設定の優先度に関する統合テストを追加
+- テストヘルパーとテストセットアップの改善
+
+## [0.29.0] - 2026-03-04
+
+### Added
+
+- レビュー＋修正ループピース群を追加: `review-fix`（多角レビュー）、`frontend-review-fix`、`backend-review-fix`、`dual-review-fix`、`dual-cqrs-review-fix`、`backend-cqrs-review-fix` および対応するレビュー専用ピース群を追加。コードレビューと自動修正を反復するワークフロー
+- `takt-default-review-fix` ピースを追加: TAKT 自己開発向けのレビュー＋修正ループワークフロー
+- `quality_gates` のグローバル/プロジェクトレベルオーバーライドをサポート: `~/.takt/config.yaml` および `.takt/config.yaml` の `piece_overrides.quality_gates` でビルトインピースの品質ゲートを上書き可能に (#384)
+- タスクの `base_branch` 設定: `takt add` 時に現在のブランチを base_branch として記録し、タスク実行時にそのブランチから分岐するよう設定可能に (#455)
+- プロバイダー設定の統一: `.takt/config.yaml` で `provider` ブロックに `type`/`model`/プロバイダー固有オプション（`network_access` 等）をまとめて記述可能に (#457)
+- ワーカープール超過時のリキュー: タスク実行がワーカー上限を超えた場合、タスクを自動的に再キューイングするよう対応 (#366)
+- `--pr` インタラクティブモードで `create_issue` アクションを除外し、`save_task` 時に PR のブランチ名を `base_branch` として自動設定
+- team_leader の `decomposeTask`/`requestMoreParts`/Phase 3 ステータス判定のプロバイダーイベントをロギング: `provider-events.jsonl` に記録されるようになり、デバッグ・分析が可能に
+
+### Fixed
+
+- `export-cc` で `facets/` のサブディレクトリ構造（`personas/`、`policies/` 等）が出力先に再現されなかった問題を修正 (#8dcb23b)
+- `cc-resolve` コマンドがコンフリクト解決後にマージコミットを生成するよう修正 (#1b1f758)
+- グローバル設定 (`~/.takt/config.yaml`) の `piece` フィールドがピース解決チェーンで無視されるバグを修正 (#458)
+- Codex プロバイダーでプロバイダー優先のパーミッションモード解決が機能しない問題と EPERM エラーの E2E テストを追加 (#d2b48fd)
+- レビューコメントがない PR で `--pr` を使用した際にエラーになる問題を修正
+- `--auto-pr`/`--draft` オプションをパイプラインモード専用に制限（インタラクティブモードでの誤用を防止）
+- team_leader のストリーミングでバウンダリの先行フラッシュによる断片化を修正 (#769bd87, #bddb66f)
+- team_leader のエラーメッセージが空文字列になるバグを修正 (#52968ac)
+- `decomposeTask`/`requestMoreParts` の `maxTurns` を 2 から 4 に増加（複雑なタスク分解でタイムアウトしていた問題を緩和）
+- Copilot プロバイダーのクライアント実装のバグを修正 (#434)
+
+### Internal
+
+- E2E プロバイダー別テストをコンフィグレベル（`vitest.config.e2e.provider.ts`）で振り分けるよう変更。テストファイル内の `skip` ロジックを廃止し、JSON レポート出力を追加
+- 共有ノーマライザを `configNormalizers.ts` に抽出してプロバイダー設定解析を整理
+- `agent-usecases`/`schema-loader` を移動し `pieceExecution` の責務を分割
+- `check:release` で全プロバイダー（claude/codex/opencode）の E2E を実行するよう変更
+- CI: PR と push の重複実行を concurrency グループで抑制
+- CI: feature ブランチへの push と手動実行に対応
+
+## [0.28.1] - 2026-03-02
+
+### Changed
+
+- BREAKING: `expert` / `expert-mini` / `expert-cqrs` / `expert-cqrs-mini` ピースを `dual` / `dual-mini` / `dual-cqrs` / `dual-cqrs-mini` にリネーム。カスタマイズしている場合はピース名を更新が必要
+- `default-mini` / `default-test-first-mini` ピースを `default` に統合。`default` ピースが「テスト優先モード」を内包するよう拡張
+- `coding-pitfalls` ナレッジの主要項目を `coding` ポリシーに移動し、ポリシーとして実際に適用されるよう強化
+- `implement` / `plan` インストラクションにセルフチェック・コーダー指針を追加
+
+### Removed
+
+- `passthrough` ピースを削除
+- `structural-reform` ピースを削除
+
+### Internal
+
+- `expert-supervisor` ペルソナを `dual-supervisor` にリネーム
+- ビルトインカタログに不足していた `terraform`、`takt-default` 系、`deep-research` を追加
+- カテゴリ設定に `deep-research` を追加
+- 全ドキュメントに `copilot` プロバイダーの説明を追加し、Claude Code 寄りの記述をプロバイダー中立に修正
+
+## [0.28.0] - 2026-03-02
+
+### Added
+
+- GitHub Copilot CLI プロバイダーを追加: `copilot` プロバイダーとして GitHub Copilot CLI を利用可能に。セッション継続、パーミッション制御（readonly/edit/full）に対応。`copilotCliPath` / `TAKT_COPILOT_CLI_PATH` で CLI パスを指定、`copilotGithubToken` / `TAKT_COPILOT_GITHUB_TOKEN` で認証トークンを設定 (#425)
+- `--pr` オプションを追加: PR のレビューコメントを取得してタスクとして実行。パイプラインモードとインタラクティブモードの両方で利用可能 (#421)
+- `takt add --pr N` で PR のレビューコメントをタスクとして追加可能に。PR のブランチ名で worktree を自動作成し、レビュー指摘の修正タスクとしてキューイング (#426)
+- `takt list` に「Pull from remote」アクションを追加: リモートの変更を worktree に取り込み、再プッシュ可能に (#395)
+- プロジェクト単位の CLI パス設定: `.takt/config.yaml` で `claudeCliPath` / `cursorCliPath` / `codexCliPath` / `copilotCliPath` をプロジェクトごとに設定可能に (#413)
+- インタラクティブモードのスラッシュコマンドを行末でも認識可能に（例: `タスクの内容 /go`）(#406)
+- takt-default / takt-default-team-leader ビルトインピースを追加（TAKT 自己開発用のワークフロー定義）
+- TAKT ナレッジファセット（`takt.md`）を追加: TAKT のアーキテクチャとコード規約を体系化
+- ai-antipattern ポリシーに冗長な条件分岐パターン検出を追加: 同一関数を if/else で呼び分けるコードを検出し、三項演算子やスプレッド構文での統一を促す
+
+### Fixed
+
+- 不正な `tasks.yaml` を検出した場合、ファイルを削除せず保持してエラーメッセージで停止するよう修正 (#418)
+- shallow clone リポジトリで worktree 作成が失敗する問題を修正: `--reference` 付きクローンが失敗した場合に通常クローンへフォールバック (#376, #409)
+- グローバル/プロジェクト設定の `model` がモデルログに反映されない不具合を修正 (#417)
+- fork PR レビュー時に `GH_REPO` を設定して正しいリポジトリの issue を参照するよう修正
+- takt-review ワークフローの PR コメント投稿ステップにも `GH_REPO` を設定
+
+### Internal
+
+- `resolveConfigValue` の不要な `defaultValue` 引数を削除し、設定解決ロジックを簡素化 (#391)
+- PRコメント `/resolve` でコンフリクト解決・レビュー指摘修正を行う GitHub Actions ワークフロー（cc-resolve）を追加
+- takt-review ワークフローを `pull_request_target` に変更し、fork PR でもシークレットを利用可能に
+- CI に `ready_for_review` / `reopened` トリガーを追加
+- CONTRIBUTING にレビューモードの例を追加、日本語版（`CONTRIBUTING.ja.md`）を追加
+
+## [0.28.0-alpha.1] - 2026-02-28
+
+### Added
+
+- GitHub Copilot CLI プロバイダーを追加: `copilot` プロバイダーとして GitHub Copilot CLI を利用可能に。セッション継続、パーミッション制御（readonly/edit/full）に対応。`copilotCliPath` / `TAKT_COPILOT_CLI_PATH` で CLI パスを指定、`copilotGithubToken` / `TAKT_COPILOT_GITHUB_TOKEN` で認証トークンを設定 (#425)
+- `--pr` オプションを追加: PR のレビューコメントを取得してタスクとして実行。パイプラインモードとインタラクティブモードの両方で利用可能 (#421)
+- `takt add --pr N` で PR のレビューコメントをタスクとして追加可能に。PR のブランチ名で worktree を自動作成し、レビュー指摘の修正タスクとしてキューイング (#426)
+- `takt list` に「Pull from remote」アクションを追加: リモートの変更を worktree に取り込み、再プッシュ可能に (#395)
+- プロジェクト単位の CLI パス設定: `.takt/config.yaml` で `claudeCliPath` / `cursorCliPath` / `codexCliPath` / `copilotCliPath` をプロジェクトごとに設定可能に (#413)
+- インタラクティブモードのスラッシュコマンドを行末でも認識可能に（例: `タスクの内容 /go`）(#406)
+- takt-default / takt-default-team-leader ビルトインピースを追加（TAKT 自己開発用のワークフロー定義）
+- TAKT ナレッジファセット（`takt.md`）を追加: TAKT のアーキテクチャとコード規約を体系化
+- ai-antipattern ポリシーに冗長な条件分岐パターン検出を追加: 同一関数を if/else で呼び分けるコードを検出し、三項演算子やスプレッド構文での統一を促す
+
+### Fixed
+
+- 不正な `tasks.yaml` を検出した場合、ファイルを削除せず保持してエラーメッセージで停止するよう修正 (#418)
+- shallow clone リポジトリで worktree 作成が失敗する問題を修正: `--reference` 付きクローンが失敗した場合に通常クローンへフォールバック (#376, #409)
+- グローバル/プロジェクト設定の `model` がモデルログに反映されない不具合を修正 (#417)
+- fork PR レビュー時に `GH_REPO` を設定して正しいリポジトリの issue を参照するよう修正
+- takt-review ワークフローの PR コメント投稿ステップにも `GH_REPO` を設定
+
+### Internal
+
+- `resolveConfigValue` の不要な `defaultValue` 引数を削除し、設定解決ロジックを簡素化 (#391)
+- PRコメント `/resolve` でコンフリクト解決・レビュー指摘修正を行う GitHub Actions ワークフロー（cc-resolve）を追加
+- takt-review ワークフローを `pull_request_target` に変更し、fork PR でもシークレットを利用可能に
+- CI に `ready_for_review` / `reopened` トリガーを追加
+- CONTRIBUTING にレビューモードの例を追加、日本語版（`CONTRIBUTING.ja.md`）を追加
+
+## [0.27.0] - 2026-02-28
+
+### Added
+
+- Cursor Agent CLI プロバイダーを追加: `cursor-agent` CLI を介して Cursor を AI プロバイダーとして利用可能に。API キー（`TAKT_CURSOR_API_KEY` / `cursor_api_key`）または `cursor-agent login` セッションで認証、JSON 出力解析、セッション継続（`--resume`）、モデル指定（`--model`）、パーミッション制御（`full` → `--force`）に対応 (#403)
+- Cursor プロバイダーの E2E テスト設定を追加（`vitest.config.e2e.cursor.ts`、`npm run test:e2e:cursor`）
+
+### Fixed
+
+- Phase 1 が error または blocked を返した場合に Phase 2（レポート出力）をスキップするよう修正。Phase 1 失敗時に不要なレポート生成が実行される問題を解消
+- Codex 互換性のため、runtime prepare で Gradle デーモンを無効化するよう修正
+
+### Internal
+
+- エージェント/カスタムペルソナのドキュメントを整合
+
+## [0.26.0] - 2026-02-27
+
+### Added
+
+- TeamLeader に refill threshold と動的パート追加を導入: 実行中のパートが `refill_threshold` 以下になると、リーダーが完了済みパートの結果を評価して追加パートを動的に生成。`max_parts` は同時並行数、`refill_threshold` で追加計画のタイミングを制御（最大合計 20 パートまで）
+- deep-research ピースの dig ムーブメントに `team_leader` 設定を追加し、リサーチの並列実行が可能に
+- TeamLeader が Phase 2（レポート出力）/ Phase 3（ステータス判定）を通常ムーブメントと同様にサポート（`applyPostExecutionPhases` の共通化）
+- ParallelLogger が動的なサブムーブメント追加に対応（`addSubMovement`）し、TeamLeader の動的パート追加時にもストリーミング出力を表示
+- `LineTimeSliceBuffer` を導入し、並列ストリーミング出力のバッファリングを時間スライスベースで最適化
+- プロジェクト設定（`.takt/config.yaml`）で `model` 指定をサポート
+
+### Changed
+
+- BREAKING: カスタムエージェント定義（`~/.takt/personas/*.md`）の `provider` / `model` を解釈しない方針とし、エージェントのプロバイダー・モデルはピース側の解決ロジック（CLI → persona_providers → ステップ → ローカル → グローバル）に統一 (#390)
+- エージェントの provider/model 解決ロジックを `resolveAgentProviderModel` に一元化し、ムーブメント解決と同じ優先順位チェーンを使用するよう変更 (#386)
+- `movement:start` イベントが `providerInfo` を含むよう変更し、表示側でのプロバイダー再解決を不要に (#390)
+- `takt list` の「Sync with root」を「Merge from root」にリネーム (#394)
+- インタラクティブモードの要約 AI がセッション非継承で実行されるよう修正し、会話コンテキストの汚染を防止 (#368)
+- interactive policy のガイドラインを改善: ユーザーが「自分で調べて」と指示した場合と、ピースへの指示作成を区別するルールを明確化
+
+### Fixed
+
+- default / default-test-first-mini ピースの `write_tests` ムーブメントで、テスト対象が未実装の場合にスキップして implement へ進むルールを追加（従来は ABORT になっていた）(#396)
+- `takt add` の GitHub Issue タイトル抽出を改善: Markdown 見出し（h1-h3）を優先的にタイトルとして使用するよう変更（従来は先頭行がそのまま使われていた）(#368)
+- quiet モードの要約 AI がセッションを引き継がない問題を修正 (#368)
+- `repertoire add` の `gh api` 呼び出しにバッファサイズ上限（100MB）を設定し、大きなリポジトリでのバッファオーバーフローを防止
+- E2E テストで `gh` ユーザー検索が無効な場合にローカルリポジトリへフォールバックするよう修正
+
+### Internal
+
+- TeamLeaderRunner をリファクタリング: 実行ロジック（`team-leader-execution.ts`）、集約（`team-leader-aggregation.ts`）、共通ユーティリティ（`team-leader-common.ts`）、ストリーミング（`team-leader-streaming.ts`）に分離
+- `more-parts.json` スキーマと `loadMorePartsSchema` ローダーを追加
+- AGENTS.md を更新（プロジェクト構成とガイドラインの改訂）
+- テスト拡充: provider/model 解決マトリクス、TeamLeader refill threshold / worker pool / aggregation / execution、OptionsBuilder、stream-buffer、conversationLoop resume、quietMode session、createIssueFromTask、schema-loader
+
+## [0.25.0] - 2026-02-26
+
+### Added
+
+- Terraform/AWS ピース: IaC 開発用の完全なピースとファセット一式を追加。plan → implement → 並列3レビュー（architect/QA/security）→ supervise → complete の15ムーブメント構成（EN/JA）
+- GitProvider 抽象化: Git/GitHub 操作を `GitProvider` インターフェースに統一し、将来の複数 Git プロバイダー対応の基盤を構築 (#375)
+- プロジェクト設定で submodule の自動取得をサポート: `submodules: all` または `submodules: [path1, path2]` で指定可能に (#387)
+- `takt add` で GitHub Issue 作成時にラベルをインタラクティブに選択可能に (#377, #111)
+- deep-research ピースにデータ保存・レポート出力機能を追加（dig/analyze ムーブメントに Write・Bash ツール許可、supervise に research-report 出力契約）
+- GitHub Discussions・Discord・X への一斉アナウンス GitHub Actions ワークフローを追加
+
+### Changed
+
+- default ピースをテスト先行開発構成に変更: plan の後に `write_tests` ムーブメントを追加し、テストを先に書いてから実装する流れに。並列レビューに testing-review を追加（3→4 レビュアー）。レポートファイル名をセマンティック命名に統一（`00-plan.md` → `plan.md` 等）
+- sync with root をピースエンジン経由からプロバイダー抽象化を利用した単発エージェント呼び出しに簡素化。コンフリクト解決プロンプトをテンプレートファイル化（EN/JA 分離）
+
+### Fixed
+
+- lineEditor でサロゲートペア（絵文字等）のカーソル位置がずれる問題を修正。Ctrl+J による改行挿入を追加
+- `--task` オプションでの直接実行時に tasks.yaml へ不要な記録がされる問題を修正
+- `--task` でワークツリー作成時は tasks.yaml に記録するよう修正（`takt list` でのブランチ管理に必要）
+- Provider resolution: removed implicit fallback to `claude` and switched to fail-fast when provider cannot be resolved (#386)
+- Provider resolution: unified display and execution provider/model resolution via `movement:start` event providerInfo, ensuring displayed provider always matches execution provider (#390)
+- E2E テスト config-priority の不安定性を修正 (#388)
+
+### Internal
+
+- GitProvider 抽象化に伴うテスト追加（github-provider, taskGit）と既存テストのインポート更新
+- CLAUDE.md 更新
+
+## [0.24.0] - 2026-02-24
+
+### Added
+
+- AskUserQuestion support: AI agents can now ask interactive questions during execution with single-select, multi-select, and free-text input via TTY UI; automatically denied during piece execution to maintain agent autonomy (#161, #369)
+- `review` builtin piece with 3-mode auto-detection: automatically selects PR mode (by PR number), branch mode (by branch name), or working diff mode (by free text) for multi-perspective parallel review
+- `testing-reviewer` and `requirements-reviewer` builtin personas for specialized review perspectives
+- `testing` policy: integration test requirement criteria (3+ module data flow, state merging into workflows, option propagation through call chains)
+- `gather-review` instruction and `review-gather` output contract for the new review piece gather movement
+- `requirements-review` instruction and output contract for requirements-focused review
+- `testing-review` output contract for testing-focused review
+- `settingSources: ['project']` in SDK options: delegates CLAUDE.md loading to the Claude SDK for proper project-level settings resolution
+
+### Changed
+
+- **BREAKING:** `review-only` piece renamed to `review`; `review-fix-minimal` piece removed — users referencing these piece names must update to `review`
+- `write-tests-first` instruction now includes integration test decision criteria instead of a generic "Write E2E tests if appropriate"
+
+### Fixed
+
+- Planner persona: added bug fix propagation check rule (grep for same pattern in related files) and prohibited deferring decidable questions to Open Questions
+
+### Internal
+
+- Docs: fixed music metaphor origin description, catalog gaps, broken links, orphaned documents, event names, API Key references, eject descriptions, removed stale personas section map from YAML example, aligned legacy terminology with current codebase
+- New test suites: `StreamDisplay`, `ask-user-question-handler`, `pieceExecution-ask-user-question`, `review-piece`, `opencode-client-cleanup`
+- Removed legacy `review-only-piece` test and `loadProjectContext` from session module (CLAUDE.md loading now delegated to SDK)
+
 ## [0.23.0] - 2026-02-23
 
 ### Added

CLAUDE.md

@@ -10,13 +10,19 @@ TAKT (TAKT Agent Koordination Topology) is a multi-agent orchestration system fo
 
 | Command | Description |
 |---------|-------------|
-| `npm run build` | TypeScript build |
+| `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 tests |
+| `npm run test` | Run all unit tests |
-| `npm run test:watch` | Run tests in watch mode (alias: `npm run test -- --watch`) |
+| `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
@@ -27,15 +33,24 @@ TAKT (TAKT Agent Koordination Topology) is a multi-agent orchestration system fo
 | `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` | Add a new task via AI conversation |
+| `takt add [task]` | Add a new task via AI conversation |
-| `takt list` | List task branches (try merge, merge & cleanup, or delete) |
+| `takt list` | List task branches (merge, delete, retry) |
-| `takt switch` | Switch piece interactively |
 | `takt clear` | Clear agent conversation sessions (reset state) |
-| `takt eject` | Copy builtin piece/agents to `~/.takt/` for customization |
+| `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. The AI helps refine task requirements through conversation. Type `/go` to execute the task with the selected piece, or `/cancel` to abort. Implemented in `src/features/interactive/`.
+**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/`.
 
@@ -48,84 +63,97 @@ TAKT (TAKT Agent Koordination Topology) is a multi-agent orchestration system fo
 | `--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) |
-| `-w, --piece <name or path>` | Piece name or path to piece YAML file (v0.3.8+) |
+| `--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 (interactive: skip confirmation, pipeline: enable PR) |
+| `--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 |
-| `--create-worktree <yes\|no>` | Skip worktree confirmation prompt |
+| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) |
-| `-q, --quiet` | **Minimal output mode: suppress AI output (for CI)** (v0.3.8+) |
+| `--provider <name>` | Override agent provider (claude\|codex\|opencode\|mock) |
-| `--provider <name>` | Override agent provider (claude\|codex\|mock) (v0.3.8+) |
+| `--model <name>` | Override agent model |
-| `--model <name>` | Override agent model (v0.3.8+) |
+| `--config <path>` | Path to global config file (default: `~/.takt/config.yaml`) |
-| `--config <path>` | Path to global config file (default: `~/.takt/config.yaml`) (v0.3.8+) |
 
 ## Architecture
 
 ### Core Flow
 
 ```
-CLI (cli.ts)
+CLI (cli.ts → routing.ts)
-  → Slash commands or executeTask()
+  → Interactive mode / Pipeline mode / Direct task execution
-    → PieceEngine (piece/engine.ts)
+    → PieceEngine (piece/engine/PieceEngine.ts)
-      → Per step: 3-phase execution
+      → Per movement, delegates to one of 4 runners:
-        Phase 1: runAgent() → main work
+        MovementExecutor  — Normal movements (3-phase execution)
-        Phase 2: runReportPhase() → report output (if step.report defined)
+        ParallelRunner    — Parallel sub-movements via Promise.allSettled()
-        Phase 3: runStatusJudgmentPhase() → status tag output (if tag-based rules)
+        ArpeggioRunner    — Data-driven batch processing (CSV → template → LLM)
-      → detectMatchedRule() → rule evaluation → determineNextStep()
+        TeamLeaderRunner  — Dynamic task decomposition into sub-parts
-      → Parallel steps: Promise.all() for sub-steps, aggregate evaluation
+      → detectMatchedRule() → rule evaluation → determineNextMovementByRules()
 ```
 
-### Three-Phase Step Execution
+### Three-Phase Movement Execution
 
-Each step executes in up to 3 phases (session is resumed across phases):
+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.) | Step's allowed_tools (Write excluded if report defined) | Always |
+| Phase 1 | Main work (coding, review, etc.) | Movement's allowed_tools (Write excluded if report defined) | Always |
-| Phase 2 | Report output | Write only | When `step.report` is defined |
+| Phase 2 | Report output | Write only | When `output_contracts` is defined |
-| Phase 3 | Status judgment | None (judgment only) | When step has tag-based rules |
+| Phase 3 | Status judgment | None (judgment only) | When movement has tag-based rules |
 
-Phase 2/3 are implemented in `src/core/piece/engine/phase-runner.ts`. The session is resumed so the agent retains context from Phase 1.
+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 step execution, rules are evaluated to determine the next step. Evaluation order (first match wins):
+After movement execution, rules are evaluated to determine the next movement. Evaluation order (first match wins):
 
-1. **Aggregate** (`all()`/`any()`) - For parallel parent steps
+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.
+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 step transitions based on rule evaluation results
+- Manages movement transitions based on rule evaluation results
-- Emits events: `step:start`, `step:complete`, `step:blocked`, `step:loop_detected`, `piece:complete`, `piece:abort`, `iteration:limit`
+- 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`) and iteration limits
+- Supports loop detection (`LoopDetector`), cycle detection (`CycleDetector`), and iteration limits
-- Maintains agent sessions per step for conversation continuity
+- Maintains agent sessions per movement for conversation continuity
-- Delegates to `StepExecutor` (normal steps) and `ParallelRunner` (parallel steps)
+- Delegates to `MovementExecutor` (normal), `ParallelRunner` (parallel), `ArpeggioRunner` (data-driven batch), and `TeamLeaderRunner` (task decomposition)
 
-**StepExecutor** (`src/core/piece/engine/StepExecutor.ts`)
+**MovementExecutor** (`src/core/piece/engine/MovementExecutor.ts`)
-- Executes a single piece step through the 3-phase model
+- 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-steps concurrently via `Promise.all()`
+- Executes parallel sub-movements concurrently via `Promise.allSettled()`
-- Aggregates sub-step results for parent rule evaluation
+- Uses `ParallelLogger` to prefix sub-movement output for readable interleaved display
-- Supports `all()` / `any()` aggregate conditions
+- 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 (`aggregate`, `phase3_tag`, `phase1_tag`, `ai_judge`, `ai_fallback`)
+- Returns `RuleMatch` with index and detection method
 - Fail-fast: throws if rules exist but no rule matched
-- **v0.3.8+:** Tag detection now uses **last match** instead of first match when multiple `[STEP:N]` tags appear in output
+- 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):
@@ -141,77 +169,110 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
 
 **Agent Runner** (`src/agents/runner.ts`)
 - Resolves agent specs (name or path) to agent configurations
-- **v0.3.8+:** Agent is optional — steps can execute with `instruction_template` only (no system prompt)
+- Agent is optional — movements can execute with `instruction_template` only (no system prompt)
-- Built-in agents with default tools:
+- 5-layer resolution for provider/model: CLI `--provider` / `--model` → persona_providers → movement override → project `.takt/config.yaml` → global `~/.takt/config.yaml`
-  - `coder`: Read/Glob/Grep/Edit/Write/Bash/WebSearch/WebFetch
+- Custom personas via `~/.takt/personas/<name>.md` or prompt files (.md)
-  - `architect`: Read/Glob/Grep/WebSearch/WebFetch
-  - `supervisor`: Read/Glob/Grep/Bash/WebSearch/WebFetch
-  - `planner`: Read/Glob/Grep/Bash/WebSearch/WebFetch
-- Custom agents via `.takt/agents.yaml` 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/claude/`, `src/infra/codex/`)
+**Provider Integration** (`src/infra/providers/`)
-- **Claude** - Uses `@anthropic-ai/claude-agent-sdk`
+- 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** - Direct OpenAI SDK integration
+- **Codex** (`src/infra/codex/`) - Uses `@openai/codex-sdk`
-  - `CodexStreamHandler.ts` - Stream handling and tool execution
+  - 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/loader.ts` - Custom agent loading from `.takt/agents.yaml`
+- `loaders/pieceParser.ts` - YAML parsing, movement/rule normalization with Zod validation. Rule regex: `AI_CONDITION_REGEX = /^ai\("(.+)"\)$/`, `AGGREGATE_CONDITION_REGEX = /^(all|any)\((.+)\)$/`
-- `loaders/pieceParser.ts` - YAML parsing, step/rule normalization with Zod validation
+- `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/pieceResolver.ts` - **3-layer resolution with correct priority** (v0.3.8+: user → project → builtin)
 - `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, trusted dirs, **quiet mode** v0.3.8+)
+- `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
+- `execute/taskExecution.ts` - Main task execution orchestration, worker pool for parallel tasks
-- `execute/pieceExecution.ts` - Piece execution wrapper
+- `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 actions
+- `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 with title/body/labels/comments
+- `issue.ts` - Fetches issues via `gh` CLI, formats as task text, supports `createIssue()`
-- `pr.ts` - Creates pull requests via `gh` CLI
+- `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 **correct priority** (v0.3.8+): user `~/.takt/pieces/` → project `.takt/pieces/` → builtin `builtins/{lang}/pieces/`
+2. CLI loads piece with **priority**: project `.takt/pieces/` → user `~/.takt/pieces/` → builtin `builtins/{lang}/pieces/`
-3. PieceEngine starts at `initial_step`
+3. PieceEngine starts at `initial_movement`
-4. Each step: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()`
+4. Each movement: delegate to appropriate runner → 3-phase execution → `detectMatchedRule()` → `determineNextMovementByRules()`
-5. Rule evaluation determines next step name (v0.3.8+: uses **last match** when multiple `[STEP:N]` tags appear)
+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             # Trusted dirs, default piece, log level, language
+  config.yaml             # Language, provider, model, log level, etc.
   pieces/                 # User piece YAML files (override builtins)
-  personas/               # User persona prompt files (.md)
+  facets/                 # User facets
-  agents/                 # Legacy persona prompts (backward compat)
+    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
-  agents.yaml             # Custom agent definitions
+  config.yaml             # Project configuration
-  tasks/                  # Task files for /run-tasks
+  facets/                 # Project-level facets
-  reports/                # Execution reports (auto-generated)
+  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 personas, policies, instructions, and pieces
+  en/                     # English
-  ja/                     # Japanese personas, policies, instructions, and pieces
+    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/`). User files in `~/.takt/` take priority. Use `/eject` to copy builtins to `~/.takt/` for customization.
+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
 
@@ -219,63 +280,150 @@ Builtin resources are embedded in the npm package (`builtins/`). User files in `
 name: piece-name
 description: Optional description
 max_movements: 10
-initial_step: plan        # First step to execute
+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)
 
-steps:
+# Piece-level provider options (inherited by all movements unless overridden)
-  # Normal step
+piece_config:
-  - name: step-name
+  provider_options:
-    persona: ../personas/coder.md       # Path to persona prompt
+    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)
-    provider: codex                     # claude|codex (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 step can edit files
+    edit: true                          # Whether movement can edit files
-    required_permission_mode: edit       # Required minimum permission mode (optional)
+    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 step.
+      Custom instructions for this movement.
       {task}, {previous_response} are auto-injected if not present as placeholders.
     pass_previous_response: true        # Default: true
-    report:
+    output_contracts:
-      name: 01-plan.md                 # Report file name
+      report:
-      format: |                         # Output contract template
+        - name: 01-plan.md             # Report file name
-        # Plan Report
+          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-step-name
+        next: next-movement-name
       - condition: ai("AI evaluates this condition text")
-        next: other-step
+        next: other-movement
       - condition: blocked
         next: ABORT
+        requires_user_input: true       # Wait for user input (interactive only)
 
-  # Parallel step (sub-steps execute concurrently)
+  # Parallel movement (sub-movements execute concurrently)
   - name: reviewers
     parallel:
       - name: arch-review
-        persona: ../personas/architecture-reviewer.md
+        persona: reviewer
-        rules:
+        policy: review
-          - condition: approved       # next is optional for sub-steps
+        knowledge: architecture
-          - condition: needs_fix
+        edit: false
-        instruction_template: |
-          Review architecture...
-      - name: security-review
-        persona: ../personas/security-reviewer.md
         rules:
           - condition: approved
           - condition: needs_fix
-        instruction_template: |
+        instruction: review-arch
-          Review security...
+      - name: security-review
-    rules:                            # Parent rules use aggregate conditions
+        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 parallel steps:
+Key points about movement types (mutually exclusive: `parallel`, `arpeggio`, `team_leader`):
-- Sub-step `rules` define possible outcomes but `next` is ignored (parent handles routing)
+- **Parallel**: Sub-movement `rules` define possible outcomes but `next` is ignored (parent handles routing). Parent uses `all("X")`/`any("X")` to aggregate.
-- Parent `rules` use `all("X")`/`any("X")` to aggregate sub-step results
+- **Arpeggio**: Template placeholders: `{line:N}`, `{col:N:name}`, `{batch_index}`, `{total_batches}`. Merge custom strategy supports inline JS or file.
-- `all("X")`: true if ALL sub-steps matched condition X
+- **Team leader**: AI generates `PartDefinition[]` (JSON in ```json block), each part executed as sub-movement.
-- `any("X")`: true if ANY sub-step matched condition X
 
 ### Rule Condition Types
 
@@ -283,7 +431,7 @@ Key points about parallel steps:
 |------|--------|------------|
 | 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-step matched conditions |
+| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-movement matched conditions |
 
 ### Template Variables
 
@@ -292,8 +440,8 @@ Key points about parallel steps:
 | `{task}` | Original user request (auto-injected if not in template) |
 | `{iteration}` | Piece-wide iteration count |
 | `{max_movements}` | Maximum movements allowed |
-| `{step_iteration}` | Per-step iteration count |
+| `{movement_iteration}` | Per-movement iteration count |
-| `{previous_response}` | Previous step output (auto-injected if not in template) |
+| `{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 |
 
@@ -313,34 +461,41 @@ Example category config:
 ```yaml
 piece_categories:
   Development:
-    pieces: [default, simple]
+    pieces: [default]
     children:
       Backend:
-        pieces: [expert-cqrs]
+        pieces: [dual-cqrs]
       Frontend:
-        pieces: [expert]
+        pieces: [dual]
   Research:
     pieces: [research, magi]
 show_others_category: true
 others_category_name: "Other Pieces"
 ```
 
-Implemented in `src/infra/config/loaders/pieceCategories.ts`.
-
 ### Model Resolution
 
 Model is resolved in the following priority order:
 
-1. **Piece step `model`** - Highest priority (specified in step YAML)
+1. **Persona-level `model`** - `persona_providers.<persona>.model`
-2. **Custom agent `model`** - Agent-level model in `.takt/agents.yaml`
+2. **Movement `model`** - `step.model` / `stepModel` (`piece movement` field)
-3. **Global config `model`** - Default model in `~/.takt/config.yaml`
+3. **CLI/task override `model`** - `--model` or task options
-4. **Provider default** - Falls back to provider's default (Claude: sonnet, Codex: gpt-5.2-codex)
+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)
 
-Example `~/.takt/config.yaml`:
+### Loop Detection
-```yaml
+
-provider: claude
+Two distinct mechanisms:
-model: opus          # Default model for all steps (unless overridden)
+
-```
+**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
 
@@ -349,8 +504,8 @@ Session logs use NDJSON (`.jsonl`) format for real-time append-only writes. Reco
 | Record | Description |
 |--------|-------------|
 | `piece_start` | Piece initialization with task, piece name |
-| `step_start` | Step execution start |
+| `movement_start` | Movement execution start |
-| `step_complete` | Step result with status, content, matched rule info |
+| `movement_complete` | Movement result with status, content, matched rule info |
 | `piece_complete` | Successful completion |
 | `piece_abort` | Abort with reason |
 
@@ -360,8 +515,8 @@ Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json
 
 - ESM modules with `.js` extensions in imports
 - Strict TypeScript with `noUncheckedIndexedAccess`
-- Zod schemas for runtime validation (`src/core/models/schemas.ts`)
+- Zod v4 schemas for runtime validation (`src/core/models/schemas.ts`)
-- Uses `@anthropic-ai/claude-agent-sdk` for Claude integration
+- Uses `@anthropic-ai/claude-agent-sdk` for Claude, `@openai/codex-sdk` for Codex, `@opencode-ai/sdk` for OpenCode
 
 ## Design Principles
 
@@ -369,16 +524,16 @@ Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json
 
 **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 step-specific instructions, not boilerplate.
+**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}/
+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: step-specific procedures and checklists
+  instructions/ — WHAT TO DO NOW: movement-specific procedures and checklists
 ```
 
 | Deciding where to place content | Facet | Example |
@@ -386,24 +541,26 @@ builtins/{lang}/
 | Role definition, AI habit prevention | Persona | "置き換えたコードを残す → 禁止" |
 | Actionable REJECT/APPROVE criterion | Policy | "内部実装のパブリックAPIエクスポート → REJECT" |
 | Detailed reasoning, REJECT/OK table with examples | Knowledge | "パブリックAPIの公開範囲" section |
-| This-step-only procedure or checklist | Instruction | "レビュー観点: 構造・設計の妥当性..." |
+| 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, step references)
+- 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 step. They reference procedures, not principles
+- Instructions are bound to a single piece movement. They reference procedures, not principles
-- Piece YAML `instruction_template` is for step-specific details (which reports to read, step routing, output templates)
+- 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
-- `StepExecutor` - Single step execution (3-phase model)
+- `MovementExecutor` - Single movement execution (3-phase model)
-- `ParallelRunner` - Parallel step execution
+- `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 Code) or in-memory (Codex). Sessions are resumed across phases (Phase 1 → Phase 2 → Phase 3) to maintain context. When `cwd !== projectCwd` (worktree/clone execution), session resume is skipped to avoid cross-directory contamination.
+**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)
 
@@ -422,83 +579,96 @@ Key constraints:
 
 ## Error Propagation
 
-`ClaudeResult` (from SDK) has an `error` field. This 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.
+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) → `AgentResponse.error`
+1. Provider error (Claude SDK / Codex / OpenCode) → `AgentResponse.error`
-2. `StepExecutor` captures error → `PieceEngine` emits `step:complete` with 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` step if error is unrecoverable
+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 `debug_enabled: true` in `~/.takt/config.yaml` or create a `.takt/debug.yaml` file:
+**Debug logging:** Set `logging.debug: true` in `~/.takt/config.yaml`:
 ```yaml
-enabled: true
+logging:
+  debug: true
 ```
 
-Debug logs are written to `.takt/logs/debug.log` (ndjson format). Log levels: `debug`, `info`, `warn`, `error`.
+Debug logs are written to `.takt/runs/debug-{timestamp}/logs/` in NDJSON format. Log levels: `debug`, `info`, `warn`, `error`.
 
-**Verbose mode:** Create `.takt/verbose` file (empty file) to enable verbose console output. This automatically enables debug logging and sets log level to `debug`.
+**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
+- Vitest for testing framework (single-thread mode, 15s timeout, 5s teardown timeout)
-- Tests use file system fixtures in `__tests__/` subdirectories
+- Unit tests: `src/__tests__/*.test.ts`
-- Mock pieces and agent configs for integration tests
+- 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 are integration tests that simulate full piece execution
+- Integration tests: Tests with `it-` prefix simulate full piece execution
-- Engine tests: Tests with `engine-` prefix test specific PieceEngine scenarios (happy path, error handling, parallel execution, etc.)
+- 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
-- `../personas/coder.md` resolves from piece file location
+- `../facets/personas/coder.md` resolves from piece file location
-- Built-in personas are loaded from `builtins/{lang}/personas/`
+- Built-in personas are loaded from `builtins/{lang}/facets/personas/`
-- User personas are loaded from `~/.takt/personas/` (legacy: `~/.takt/agents/`)
+- 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 `step.report` are written relative to report dir
+- 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
 
-**Worktree execution gotchas:**
-- `git clone --shared` creates independent `.git` directory (not `git worktree`)
-- Clone cwd ≠ project cwd: agents work in clone, reports write to clone, logs write to project
-- Session resume is skipped when `cwd !== projectCwd` to avoid cross-directory contamination
-- Reports write to `cwd/.takt/runs/{slug}/reports/` (clone) to prevent agents from discovering the main repository path via instruction
-- Clones are ephemeral: created → task runs → auto-commit + push → deleted
-- Use `takt list` to manage task branches after clone deletion
-
 **Rule evaluation quirks:**
 - Tag-based rules match by array index (0-based), not by exact condition text
-- **v0.3.8+:** When multiple `[STEP:N]` tags appear in output, **last match wins** (not first)
+- When multiple `[STEP:N]` tags appear in output, **last match wins** (not first)
-- `ai()` conditions are evaluated by Claude/Codex, not by string matching
+- `ai()` conditions are evaluated by the provider, not by string matching
-- Aggregate conditions (`all()`, `any()`) only work in parallel parent steps
+- 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 skill/agent calls
+- Claude: Uses session files in `~/.claude/projects/`, supports aliases: `opus`, `sonnet`, `haiku`
-- Codex: In-memory sessions, no skill/agent calls
+- 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)
-- Claude supports aliases: `opus`, `sonnet`, `haiku`
-- Codex defaults to `codex` if model not specified
 
 **Permission modes (provider-independent values):**
 - `readonly`: Read-only access, no file modifications (Claude: `default`, Codex: `read-only`)

CONTRIBUTING.md

@@ -1,62 +1,66 @@
 # Contributing to TAKT
 
-Thank you for your interest in contributing to TAKT!
+🇯🇵 [日本語版](./docs/CONTRIBUTING.ja.md)
 
-## About This Project
+Thank you for your interest in contributing to TAKT! This project uses TAKT's review piece to verify PR quality before merging.
-
-This project is developed using [TAKT](https://github.com/nrslib/takt). Please understand the following before contributing:
-
-- **Small, focused changes are preferred** - Bug fixes, typo corrections, documentation improvements
-- **Large PRs are difficult to review** - Especially AI-generated bulk changes without explanation
-
-## How to Contribute
-
-### Reporting Issues
-
-1. Search existing issues first
-2. Include reproduction steps
-3. Include your environment (OS, Node version, etc.)
-
-### Pull Requests
-
-**Preferred:**
-- Bug fixes with tests
-- Documentation improvements
-- Small, focused changes
-- Typo corrections
-
-**Difficult to review:**
-- Large refactoring
-- AI-generated bulk changes
-- Feature additions without prior discussion
-
-### Before Submitting a PR
-
-1. Open an issue first to discuss the change
-2. Keep changes small and focused
-3. Include tests if applicable
-4. Update documentation if needed
 
 ## Development Setup
 
 ```bash
-# Clone the repository
 git clone https://github.com/your-username/takt.git
 cd takt
-
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Run tests
 npm test
-
-# Lint
 npm run lint
 ```
 
+## How to Contribute
+
+1. **Open an issue** to discuss the change before starting work
+2. **Keep changes small and focused** — bug fixes, documentation improvements, typo corrections are welcome
+3. **Include tests** for new behavior
+4. **Run the review** before submitting (see below)
+
+Large refactoring or feature additions without prior discussion are difficult to review and may be declined.
+
+## Before Submitting a PR
+
+All PRs must pass the TAKT review process. PRs without a review summary or with unresolved REJECT findings will not be merged.
+
+### 1. Pass CI checks
+
+```bash
+npm run build
+npm run lint
+npm test
+```
+
+### 2. Run TAKT review
+
+The review piece auto-detects the review mode based on the input:
+
+```bash
+# PR mode — review a pull request by number
+takt -t "#<PR-number>" -w review
+
+# Branch mode — review a branch diff against main
+takt -t "<branch-name>" -w review
+
+# Current diff mode — review uncommitted or recent changes
+takt -t "review current changes" -w review
+```
+
+### 3. Confirm APPROVE
+
+Check the review summary in `.takt/runs/*/reports/review-summary.md`. If the result is **REJECT**, fix the reported issues and re-run the review until you get **APPROVE**.
+
+If a REJECT finding cannot be resolved (e.g., false positive, intentional design decision), leave a comment on the PR explaining why it remains unresolved.
+
+### 4. Include the review summary in your PR
+
+Post the contents of `review-summary.md` as a comment on your PR. This is **required** — it lets maintainers verify that the review was run and passed.
+
 ## Code Style
 
 - TypeScript strict mode

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) 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), or [OpenCode](https://opencode.ai) installed
+- **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/
+    📁 🚀 Quick Start/
-    📁 Research/
+    📁 🎨 Frontend/
+    📁 ⚙️ Backend/
 
 > Add user authentication with JWT
 
@@ -83,18 +86,14 @@ takt list
 
 ## How It Works
 
-TAKT uses a music metaphor: **piece** = workflow, **movement** = step.
+TAKT uses a music metaphor — the name itself comes from the German word for "beat" or "baton stroke," used in conducting to keep an orchestra in time. In TAKT, a **piece** is a workflow and a **movement** is a step within it, just as a musical piece is composed of movements.
 
 A piece defines a sequence of movements. Each movement specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:
 
 ```yaml
-name: simple
+name: plan-implement-review
 initial_movement: plan
-
+max_movements: 10
-personas:
-  planner: ../personas/planner.md
-  coder: ../personas/coder.md
-  reviewer: ../personas/architecture-reviewer.md
 
 movements:
   - name: plan
@@ -107,6 +106,7 @@ movements:
   - name: implement
     persona: coder
     edit: true
+    required_permission_mode: edit
     rules:
       - condition: Implementation complete
         next: review
@@ -127,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` | Standard development. Test-first with AI antipattern review and parallel review (architecture + supervisor). |
-| `default-test-first-mini` | Test-first development. Write tests first, then implement to pass them. |
 | `frontend-mini` | Frontend-focused mini configuration. |
 | `backend-mini` | Backend-focused mini configuration. |
-| `expert-mini` | Expert-level mini configuration. |
+| `dual-mini` | Frontend + backend mini configuration. |
-| `default` | Serious development. Multi-stage review with parallel reviewers. Used for TAKT's own development. |
 
 See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas.
 
@@ -144,8 +142,7 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas
 | `takt run` | Execute all pending tasks |
 | `takt list` | Manage task branches (merge, retry, instruct, delete) |
 | `takt #N` | Execute GitHub Issue as task |
-| `takt switch` | Switch active piece |
+| `takt eject` | Copy builtin pieces/facets for customization |
-| `takt eject` | Copy builtin pieces/personas for customization |
 | `takt repertoire add` | Install a repertoire package from GitHub |
 
 See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
@@ -155,15 +152,19 @@ See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
 Minimal `~/.takt/config.yaml`:
 
 ```yaml
-provider: claude    # claude, codex, or opencode
+provider: claude    # claude, codex, opencode, cursor, or copilot
 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-...
+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.
@@ -234,8 +235,8 @@ const config = loadPiece('default');
 if (!config) throw new Error('Piece not found');
 
 const engine = new PieceEngine(config, process.cwd(), 'My task');
-engine.on('step:complete', (step, response) => {
+engine.on('movement:complete', (movement, response) => {
-  console.log(`${step.name}: ${response.status}`);
+  console.log(`${movement.name}: ${response.status}`);
 });
 
 await engine.run();
@@ -253,7 +254,9 @@ await engine.run();
 | [Faceted Prompting](./docs/faceted-prompting.md) | Prompt design methodology |
 | [Repertoire Packages](./docs/repertoire.md) | Installing and sharing packages |
 | [Task Management](./docs/task-management.md) | Task queuing, execution, isolation |
+| [Data Flow](./docs/data-flow.md) | Internal data flow and architecture diagrams |
 | [CI/CD Integration](./docs/ci-cd.md) | GitHub Actions and pipeline mode |
+| [Provider Sandbox](./docs/provider-sandbox.md) | Sandbox configuration for providers |
 | [Changelog](./CHANGELOG.md) ([日本語](./docs/CHANGELOG.ja.md)) | Version history |
 | [Security Policy](./SECURITY.md) | Vulnerability reporting |
 

builtins/en/config.yaml

@@ -2,24 +2,35 @@
 # Location: ~/.takt/config.yaml
 
 # =====================================
-# General settings (piece-independent)
+# General settings
 # =====================================
 language: en        # UI language: en | ja
-log_level: info     # Log level: debug | info | warn | error
+
-provider: claude    # Default provider: claude | codex | opencode | mock
+# Default provider and model
-# model: sonnet     # Optional model name passed to provider
+# provider: claude                    # Default provider: claude | codex | opencode | cursor | copilot | mock
+# model: sonnet                       # Default model (passed directly to provider)
 
 # Execution control
 # worktree_dir: ~/takt-worktrees   # Base directory for shared clone execution
-# auto_pr: false                   # Auto-create PR after worktree execution
-branch_name_strategy: ai      # Branch strategy: romaji | ai
-concurrency: 2                  # Concurrent task execution for takt run (1-10)
-# task_poll_interval_ms: 500       # Polling interval in ms during takt run (100-5000)
 # prevent_sleep: false             # Prevent macOS idle sleep while running
+# auto_fetch: false                # Fetch before clone to keep shared clones up-to-date
+# base_branch: main                # Base branch to clone from (default: current branch)
+# concurrency: 1                   # Number of tasks to run concurrently in takt run (1-10)
+# task_poll_interval_ms: 500       # Polling interval in ms for picking up new tasks (100-5000)
+
+# PR / branch
+# auto_pr: false                   # Auto-create PR after worktree execution
+# draft_pr: false                  # Create PR as draft
+# branch_name_strategy: romaji     # Branch name generation: romaji | ai
+
+# Pipeline execution
+# pipeline:
+#   default_branch_prefix: "takt/"         # Branch prefix for pipeline-created branches
+#   commit_message_template: "{title}"     # Commit message template. Variables: {title}, {issue}
+#   pr_body_template: "{report}"           # PR body template. Variables: {issue_body}, {report}, {issue}
 
 # Output / notifications
-# minimal_output: false            # Minimized output for CI logs
+# minimal_output: false            # Suppress detailed agent output
-# verbose: false                   # Verbose output mode
 # notification_sound: true         # Master switch for sounds
 # notification_sound_events:       # Per-event sound toggle (unset means true)
 #   iteration_limit: true
@@ -27,74 +38,86 @@ concurrency: 2                  # Concurrent task execution for takt run (1-10)
 #   piece_abort: true
 #   run_complete: true
 #   run_abort: true
-# observability:
+# logging:
+#   level: info                    # Log level for console and file output
+#   trace: true                    # Generate human-readable execution trace report (trace.md)
+#   debug: false                   # Enable debug.log + prompts.jsonl
 #   provider_events: false         # Persist provider stream events
+#   usage_events: false            # Persist usage event logs
+
+# Analytics
 # analytics:
-#   enabled: true                  # Enable analytics metrics collection
+#   enabled: true                  # Enable local analytics collection
-#   events_path: ~/.takt/analytics/events  # Analytics event directory
+#   events_path: ~/.takt/analytics/events  # Custom events directory
-#   retention_days: 30             # Analytics event retention (days)
+#   retention_days: 30             # Retention period for event files
+
+# Interactive mode
+# interactive_preview_movements: 3 # Number of movement previews in interactive mode (0-10)
+
+# Per-persona provider/model overrides
+# persona_providers:
+#   coder:
+#     provider: claude
+#     model: opus
+#   reviewer:
+#     provider: codex
+#     model: gpt-5.2-codex
+
+# Provider-specific options (lowest priority, overridden by piece/movement)
+# provider_options:
+#   codex:
+#     network_access: true
+#   claude:
+#     sandbox:
+#       allow_unsandboxed_commands: true
+
+# Provider permission profiles
+# provider_profiles:
+#   claude:
+#     default_permission_mode: edit
+#   codex:
+#     default_permission_mode: edit
+
+# Runtime environment preparation
+# runtime:
+#   prepare: [node, gradle, ./custom-script.sh]
+
+# Piece-level overrides
+# piece_overrides:
+#   quality_gates:
+#     - "All tests pass"
+#   quality_gates_edit_only: true
+#   movements:
+#     review:
+#       quality_gates:
+#         - "No security vulnerabilities"
+#   personas:
+#     coder:
+#       quality_gates:
+#         - "Code follows conventions"
 
 # Credentials (environment variables take priority)
 # anthropic_api_key: "sk-ant-..." # Claude API key
 # openai_api_key: "sk-..."         # Codex/OpenAI API key
+# gemini_api_key: "..."            # Gemini API key
+# google_api_key: "..."            # Google API key
+# groq_api_key: "..."              # Groq API key
+# openrouter_api_key: "..."        # OpenRouter API key
 # opencode_api_key: "..."          # OpenCode API key
-# codex_cli_path: "/absolute/path/to/codex"  # Absolute path to Codex CLI
+# cursor_api_key: "..."            # Cursor API key
 
-# Pipeline
+# CLI paths
-# pipeline:
+# codex_cli_path: "/absolute/path/to/codex"    # Absolute path to Codex CLI
-#   default_branch_prefix: "takt/"             # Prefix for pipeline-created branches
+# claude_cli_path: "/absolute/path/to/claude"  # Absolute path to Claude Code CLI
-#   commit_message_template: "feat: {title} (#{issue})"  # Commit template
+# cursor_cli_path: "/absolute/path/to/cursor"  # Absolute path to cursor-agent CLI
-#   pr_body_template: |                          # PR body template
+# copilot_cli_path: "/absolute/path/to/copilot" # Absolute path to Copilot CLI
-#     ## Summary
+# copilot_github_token: "ghp_..."              # Copilot GitHub token
-#     {issue_body}
-#     Closes #{issue}
 
 # Misc
 # bookmarks_file: ~/.takt/preferences/bookmarks.yaml  # Bookmark file location
 
-# =====================================
+# Piece list / categories
-# Piece-related settings (global defaults)
-# =====================================
-# 1) Route provider/model per persona
-# persona_providers:
-#   coder:
-#     provider: codex    # Run coder persona on Codex
-#     model: o3-mini     # Use o3-mini model (optional)
-#   reviewer:
-#     provider: claude   # Run reviewer persona on Claude
-
-# 2) Provider options
-#    Priority (for piece-capable keys such as provider/model/provider_options):
-#    global < piece < project < env
-# provider_options:
-#   codex:
-#     network_access: true      # Allow network access for Codex
-#   opencode:
-#     network_access: true      # Allow network access for OpenCode
-#   claude:
-#     sandbox:
-#       allow_unsandboxed_commands: false   # true allows unsandboxed execution for listed commands
-#       excluded_commands:
-#         - "npm publish"                  # Commands excluded from sandbox
-
-# 3) Movement permission policy
-# provider_profiles:
-#   codex:
-#     default_permission_mode: full         # Base permission: readonly | edit | full
-#     movement_permission_overrides:
-#       ai_review: readonly                 # Per-movement override
-#   claude:
-#     default_permission_mode: edit
-
-# 4) Runtime preparation before execution (recommended: enabled)
-runtime:
-  prepare:
-    - gradle      # Prepare Gradle cache/env under .runtime
-    - node        # Prepare npm cache/env under .runtime
-
-# 5) Piece list / categories
 # enable_builtin_pieces: true                             # Enable built-in pieces from builtins/{lang}/pieces
 # disabled_builtins:
 #   - magi                                                # Built-in piece names to disable
 # piece_categories_file: ~/.takt/preferences/piece-categories.yaml  # Category definition file
-# interactive_preview_movements: 3                        # Preview movement count in interactive mode (0-10)

builtins/en/facets/instructions/fix.md

@@ -1,10 +1,16 @@
-Address the reviewer's feedback.
+Use reports in the Report Directory and fix the issues raised by the reviewer.
-Use reports in the Report Directory shown in the Piece Context and fix the issues raised by the reviewer.
-Use files in the Report Directory as primary evidence. If additional context is needed, you may consult Previous Response and conversation history as secondary sources (Previous Response may be unavailable). If information conflicts, prioritize reports in the Report Directory and actual file contents.
 
-**Important**: After fixing, run both build and tests.
+**Report reference policy:**
-- Build verification is mandatory. Run the build (type check) and verify there are no type errors
+- Use the latest review reports in the Report Directory as primary evidence.
-- Running tests is mandatory. After build succeeds, always run tests and verify results
+- Past iteration reports are saved as `{filename}.{timestamp}` in the same directory (e.g., `architect-review.md.20260304T123456Z`). For each report, run Glob with a `{report-name}.*` pattern, read up to 2 files in descending timestamp order, and understand persists / reopened trends before starting fixes.
+
+**Completion criteria (all must be satisfied):**
+- All findings in this iteration (new / reopened) have been fixed
+- Potential occurrences of the same `family_tag` have been fixed simultaneously (no partial fixes that cause recurrence)
+- At least one regression test per `family_tag` has been added (mandatory for config-contract and boundary-check findings)
+- Findings with the same `family_tag` from multiple reviewers have been merged and addressed as one fix
+
+**Important**: After fixing, run the build (type check) and tests.
 
 **Required output (include headings)**
 ## Work results
@@ -15,5 +21,11 @@ Use files in the Report Directory as primary evidence. If additional context is
 - {Build execution results}
 ## Test results
 - {Test command executed and results}
+## Convergence gate
+| Metric | Count |
+|--------|-------|
+| new (fixed in this iteration) | {N} |
+| reopened (recurrence fixed) | {N} |
+| persists (carried over, not addressed this iteration) | {N} |
 ## Evidence
 - {List key points from files checked/searches/diffs/logs}

builtins/en/facets/instructions/gather-review.md

@@ -0,0 +1,42 @@
+Gather information about the review target and produce a report for reviewers to reference.
+
+## Auto-detect review mode
+
+Analyze the task text and determine which mode to use.
+
+### Mode 1: PR mode
+**Trigger:** Task contains PR references like `#42`, `PR #42`, `pull/42`, or a URL with `/pull/`
+**Steps:**
+1. Extract the PR number
+2. Run `gh pr view {number}` to get title, description, labels
+3. Run `gh pr diff {number}` to get the diff
+4. Compile the changed files list
+5. Extract purpose and requirements from the PR description
+6. If linked Issues exist, retrieve them with `gh issue view {number}`
+   - Extract Issue numbers from "Closes #N", "Fixes #N", "Resolves #N"
+   - Collect Issue title, description, labels, and comments
+
+### Mode 2: Branch mode
+**Trigger:** Task text matches a branch name found in `git branch -a`. This includes names with `/` (e.g., `feature/auth`) as well as simple names (e.g., `develop`, `release-v2`, `hotfix-login`). When unsure, verify with `git branch -a | grep {text}`.
+**Steps:**
+1. Determine the base branch (default: `main`, fallback: `master`)
+2. Run `git log {base}..{branch} --oneline` to get commit history
+3. Run `git diff {base}...{branch}` to get the diff
+4. Compile the changed files list
+5. Extract purpose from commit messages
+6. If a PR exists for the branch, fetch it with `gh pr list --head {branch}`
+
+### Mode 3: Current diff mode
+**Trigger:** Task does not match Mode 1 or Mode 2 (e.g., "review current changes", "last 3 commits", "current diff")
+**Steps:**
+1. If the task specifies a count (e.g., "last N commits"), extract N. Otherwise default to N=1
+2. Run `git diff` for unstaged changes and `git diff --staged` for staged changes
+3. If both are empty, run `git diff HEAD~{N}` to get the diff for the last N commits
+4. Run `git log --oneline -{N+10}` for commit context
+5. Compile the changed files list
+6. Extract purpose from recent commit messages
+
+## Report requirements
+- Regardless of mode, the output report must follow the same format
+- Fill in what is available; mark unavailable sections as "N/A"
+- Always include: review target overview, purpose, changed files, and the diff

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}

builtins/en/facets/instructions/implement-terraform.md

@@ -0,0 +1,54 @@
+Implement Terraform code 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**: After implementation, run the following validations in order:
+1. `terraform fmt -check` — fix formatting violations with `terraform fmt` if any
+2. `terraform validate` — check for syntax and type errors
+3. `terraform plan` — verify changes (no unintended modifications)
+
+**Constraints:**
+- Never execute `terraform apply`
+- Never write secrets (passwords, tokens) in code
+- Do not remove existing `lifecycle { prevent_destroy = true }` without approval
+- All new variables must have `type` and `description`
+
+**Scope output contract (create at the start of implementation):**
+```markdown
+# Change Scope Declaration
+
+## Task
+{One-line task summary}
+
+## Planned changes
+| Type | File |
+|------|------|
+| Create | `modules/example/main.tf` |
+| Modify | `environments/sandbox/main.tf` |
+
+## Estimated size
+Small / Medium / Large
+
+## Impact area
+- {Affected modules or resources}
+```
+
+**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}
+- **Cost impact**: {If applicable}
+```
+
+**Required output (include headings)**
+## Work results
+- {Summary of actions taken}
+## Changes made
+- {Summary of changes}
+## Validation results
+- {terraform fmt -check result}
+- {terraform validate result}
+- {terraform plan summary (resources to add/change/destroy)}

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}

builtins/en/facets/instructions/loop-monitor-ai-fix.md

@@ -4,7 +4,7 @@ Review the reports from each cycle and determine whether this loop
 is healthy (making progress) or unproductive (repeating the same issues).
 
 **Reports to reference:**
-- AI Review results: {report:03-ai-review.md}
+- AI Review results: {report:ai-review.md}
 
 **Judgment criteria:**
 - Are new issues being found/fixed in each cycle?

builtins/en/facets/instructions/loop-monitor-reviewers-fix.md

@@ -0,0 +1,9 @@
+The reviewers → fix loop has repeated {cycle_count} times.
+
+Review the latest review reports in the Report Directory and determine
+whether this loop is healthy (converging) or unproductive (diverging or oscillating).
+
+**Judgment criteria:**
+- Is the number of new / reopened findings decreasing each cycle?
+- Are the same family_tag findings not repeating (is persists not growing)?
+- Are fixes actually being applied to the code?

builtins/en/facets/instructions/plan.md

@@ -12,9 +12,14 @@ For small tasks, skip the design sections in the report.
 
 **Actions:**
 1. Understand the task requirements
+   - **When reference material points to an external implementation, determine whether it is a "bug fix clue" or a "design approach to adopt". If narrowing scope beyond the reference material's intent, include the rationale in the plan report**
    - **For each requirement, determine "change needed / not needed". If "not needed", cite the relevant code (file:line) as evidence. Claiming "already correct" without evidence is prohibited**
 2. Investigate code to resolve unknowns
 3. Identify the impact area
 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)

builtins/en/facets/instructions/research-analyze.md

@@ -3,10 +3,15 @@ Analyze the research results and determine whether additional investigation is n
 **What to do:**
 1. Organize the major findings from the research results
 2. Identify unexplained phenomena, unverified hypotheses, and missing data
-3. Make one of the following judgments:
+3. Save analysis results to `{report_dir}/analysis-{N}.md` as files
+4. Make one of the following judgments:
    - **New questions exist** → Create additional research instructions for the Digger
    - **Sufficiently investigated** → Create an overall summary
 
+**Data saving rules:**
+- Write to `{report_dir}/analysis-{N}.md` (N is sequential number) for each analysis
+- Include analysis perspective, synthesized findings, and identified gaps
+
 **Additional research instruction format:**
 - What to investigate (specific data or information)
 - Why it's needed (which gap it fills)

builtins/en/facets/instructions/research-dig.md

@@ -1,12 +1,29 @@
-Execute the research according to the plan (or additional research instructions).
+Decompose the research plan (or additional research instructions) into independent subtasks and execute the investigation in parallel.
 
 **What to do:**
-1. Execute planned research items in order
+1. Analyze research items from the plan and decompose them into independently executable subtasks
-2. Actually investigate each item (web search, codebase search, etc.)
+2. Include clear research scope and expected deliverables in each subtask's instruction
-3. Report items that could not be researched as "Unable to research"
+3. Include the following data saving rules and report structure in each subtask's instruction
-4. Organize results and create a report
 
-**Report structure:**
+**Subtask decomposition guidelines:**
+- Prioritize topic independence (group interdependent items into the same subtask)
+- Avoid spreading high-priority items (P1) across too many subtasks
+- Balance workload evenly across subtasks
+
+**Rules to include in each subtask's instruction:**
+
+Data saving rules:
+- Write data per research item to `{report_dir}/data-{topic-name}.md`
+- Topic names in lowercase English with hyphens (e.g., `data-market-size.md`)
+- Include source URLs, retrieval dates, and raw data
+
+External data downloads:
+- Actively download and utilize CSV, Excel, JSON, and other data files from public institutions and trusted sources
+- Always verify source reliability before downloading
+- Save downloaded files to `{report_dir}/`
+- Never download from suspicious domains or download executable files
+
+Report structure (per subtask):
 - Results and details per research item
 - Summary of key findings
 - Caveats and risks

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
@@ -10,6 +12,12 @@ Do not review AI-specific issues (already covered by the ai_review movement).
 - Call chain verification
 - Scattered hardcoding of contract strings (file names, config key names)
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 **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`

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

@@ -11,6 +11,12 @@ AI-specific issue review is not needed (already covered by the ai_review movemen
 **Note**: If this project does not use the CQRS+ES pattern,
 review from a general domain design perspective instead.
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
 1. Review the change diff and detect issues based on the CQRS and Event Sourcing criteria above

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

@@ -11,6 +11,12 @@ Review the changes from a frontend development perspective.
 **Note**: If this project does not include a frontend,
 proceed as no issues found.
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
 1. Review the change diff and detect issues based on the frontend development criteria above

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

@@ -7,6 +7,12 @@ Review the changes from a quality assurance perspective.
 - Logging and monitoring
 - Maintainability
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 **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`

builtins/en/facets/instructions/review-requirements.md

@@ -0,0 +1,27 @@
+Review the changes from a requirements fulfillment perspective.
+
+**Review criteria:**
+- Whether each requested requirement has been implemented
+- Whether implicit requirements (naturally expected behaviors) are satisfied
+- Whether changes outside the scope (scope creep) have crept in
+- Whether there are any partial or missing implementations
+
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
+**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. Extract requirements one by one from the review target report and task
+2. For each requirement, identify the implementing code (file:line)
+3. Confirm that the code satisfies the requirement
+4. Check for any changes not covered by the requirements
+5. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
+6. If there is even one blocking issue (`new` or `persists`), judge as REJECT

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

@@ -4,6 +4,12 @@ Review the changes from a security perspective. Check for the following vulnerab
 - Data exposure risks
 - Cryptographic weaknesses
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
 1. Review the change diff and detect issues based on the security criteria above

builtins/en/facets/instructions/review-terraform.md

@@ -0,0 +1,31 @@
+Focus on reviewing **Terraform convention compliance**.
+Do not review AI-specific issues (already covered by the ai_review movement).
+
+**Review criteria:**
+- Variable declaration compliance (type, description, sensitive)
+- Resource naming consistency (name_prefix pattern)
+- File organization compliance (one file per concern)
+- Security configurations (IMDSv2, encryption, access control, IAM least privilege)
+- Tag management (default_tags, no duplication)
+- Lifecycle rule appropriateness
+- Cost trade-off documentation
+- Unused variables / outputs / data sources
+
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
+**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. First, extract previous open findings and preliminarily classify as `new / persists / resolved`
+2. Review the change diff and detect issues based on Terraform convention criteria
+   - Cross-check changes against REJECT criteria tables defined in knowledge
+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

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

@@ -7,8 +7,14 @@ Review the changes from a test quality perspective.
 - Completeness (unnecessary tests, missing cases)
 - Appropriateness of mocks and fixtures
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
-1. Cross-reference the test plan report ({report:00-test-plan.md}) with the implemented tests
+1. Cross-reference the test plan/test scope reports in the Report Directory 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

builtins/en/facets/instructions/supervise.md

@@ -1,9 +1,11 @@
 Run tests, verify the build, and perform final approval.
 
 **Overall piece verification:**
-1. Whether the plan and implementation results are consistent
+1. Check all reports in the report directory and verify overall piece consistency
-2. Whether findings from each review movement have been addressed
+   - Does implementation match the plan?
-3. Whether each task spec requirement has been achieved
+   - Were all review movement findings properly addressed?
+   - Was the original task objective achieved?
+2. Whether each task spec requirement has been achieved
    - Extract requirements one by one from the task spec
    - For each requirement, identify the implementing code (file:line)
    - Verify the code actually fulfills the requirement (read the file, run the test)

builtins/en/facets/instructions/team-leader-implement.md

@@ -0,0 +1,29 @@
+Analyze the implementation task and, if decomposition is appropriate, split into multiple parts for parallel execution.
+
+**Important:** Reference the plan report: {report:plan.md}
+
+**Steps:**
+
+1. Assess whether decomposition is appropriate
+   - Identify files to change and check inter-file dependencies
+   - If cross-cutting concerns exist (shared types, IDs, events), implement in a single part
+   - If few files are involved, or the task is a rename/refactoring, implement in a single part
+
+2. If decomposing: group files by layer/module
+   - Create groups based on high cohesion (e.g., Domain layer / Infrastructure layer / API layer)
+   - If there are type or interface dependencies, keep both sides in the same group
+   - Never assign the same file to multiple parts
+   - Keep test files and implementation files in the same part
+
+3. Assign file ownership exclusively to each part
+   - Each part's instruction must clearly state:
+     - **Responsible files** (list of files to create/modify)
+     - **Reference-only files** (read-only, modification prohibited)
+     - **Implementation task** (what and how to implement)
+     - **Completion criteria** (implementation of responsible files is complete)
+   - If tests are already written, instruct parts to implement so existing tests pass
+   - Do not include build checks (all parts complete first, then build is verified together)
+
+**Constraints:**
+- Parts do not run tests (handled by subsequent movements)
+- Do not modify files outside your responsibility (causes conflicts)

builtins/en/facets/instructions/write-tests-first.md

@@ -7,7 +7,11 @@ Refer only to files within the Report Directory shown in the Piece Context. Do n
 1. Review the plan report and understand the planned behavior and interfaces
 2. Examine existing code and tests to learn the project's test patterns
 3. Write unit tests for the planned features
-4. Write E2E tests if appropriate
+4. Determine whether integration tests are needed and create them if so
+   - Does the data flow cross 3+ modules?
+   - Does a new status/state merge into an existing workflow?
+   - Does a new option propagate through a call chain to the endpoint?
+   - If any apply, create integration tests
 5. Run the build (type check) to verify test code has no syntax errors
 
 **Test writing guidelines:**

builtins/en/facets/knowledge/takt.md

@@ -0,0 +1,151 @@
+# TAKT Architecture Knowledge
+
+## Core Structure
+
+PieceEngine is a state machine. It manages movement transitions via EventEmitter.
+
+```
+CLI → PieceEngine → Runner (4 types) → RuleEvaluator → next movement
+```
+
+| Runner | Purpose | When to Use |
+|--------|---------|-------------|
+| MovementExecutor | Standard 3-phase execution | Default |
+| ParallelRunner | Concurrent sub-movements | parallel block |
+| ArpeggioRunner | Data-driven batch processing | arpeggio block |
+| TeamLeaderRunner | Task decomposition → parallel sub-agents | team_leader block |
+
+Runners are mutually exclusive. Do not specify multiple runner types on a single movement.
+
+### 3-Phase Execution Model
+
+Normal movements execute in up to 3 phases. Sessions persist across phases.
+
+| Phase | Purpose | Tools | Condition |
+|-------|---------|-------|-----------|
+| Phase 1 | Main work | Movement's allowed_tools | Always |
+| Phase 2 | Report output | Write only | When output_contracts defined |
+| Phase 3 | Status judgment | None (judgment only) | When tag-based rules exist |
+
+## Rule Evaluation
+
+RuleEvaluator determines the next movement via 5-stage fallback. Earlier match takes priority.
+
+| Priority | Method | Target |
+|----------|--------|--------|
+| 1 | aggregate | parallel parent (all/any) |
+| 2 | Phase 3 tag | `[STEP:N]` output |
+| 3 | Phase 1 tag | `[STEP:N]` output (fallback) |
+| 4 | ai() judge | ai("condition") rules |
+| 5 | AI fallback | AI evaluates all conditions |
+
+When multiple tags appear in output, the **last match** wins.
+
+### Condition Syntax
+
+| Syntax | Parsing | Regex |
+|--------|---------|-------|
+| `ai("...")` | AI condition evaluation | `AI_CONDITION_REGEX` |
+| `all("...")` / `any("...")` | Aggregate condition | `AGGREGATE_CONDITION_REGEX` |
+| Plain string | Tag or AI fallback | — |
+
+Adding new special syntax requires updating both pieceParser.ts regex and RuleEvaluator.
+
+## Provider Integration
+
+Abstracted through the Provider interface. SDK-specific details are encapsulated within each provider.
+
+```
+Provider.setup(AgentSetup) → ProviderAgent
+ProviderAgent.call(prompt, options) → AgentResponse
+```
+
+| Criteria | Judgment |
+|----------|----------|
+| SDK-specific error handling leaking outside Provider | REJECT |
+| Errors not propagated to AgentResponse.error | REJECT |
+| Session key collision between providers | REJECT |
+| Session key format `{persona}:{provider}` | OK |
+
+### Model Resolution
+
+Models resolve through 5-level priority. Higher takes precedence.
+
+1. persona_providers model specification
+2. Movement model field
+3. CLI `--model` override
+4. config.yaml (when resolved provider matches)
+5. Provider default
+
+## Facet Assembly
+
+The faceted-prompting module is independent from TAKT core.
+
+```
+compose(facets, options) → ComposedPrompt { systemPrompt, userMessage }
+```
+
+| Criteria | Judgment |
+|----------|----------|
+| Import from faceted-prompting to TAKT core | REJECT |
+| TAKT core depending on faceted-prompting | OK |
+| Facet path resolution logic outside faceted-prompting | Warning |
+
+### 3-Layer Facet Resolution Priority
+
+Project `.takt/` → User `~/.takt/` → Builtin `builtins/{lang}/`
+
+Same-named facets are overridden by higher-priority layers. Customize builtins by overriding in upper layers.
+
+## Testing Patterns
+
+Uses vitest. Test file naming conventions distinguish test types.
+
+| Prefix | Type | Content |
+|--------|------|---------|
+| None | Unit test | Individual function/class verification |
+| `it-` | Integration test | Piece execution simulation |
+| `engine-` | Engine test | PieceEngine scenario verification |
+
+### Mock Provider
+
+`--provider mock` returns deterministic responses. Scenario queues compose multi-turn tests.
+
+```typescript
+// NG - Calling real API in tests
+const response = await callClaude(prompt)
+
+// OK - Set up scenario with mock provider
+setMockScenario([
+  { persona: 'coder', status: 'done', content: '[STEP:1]\nDone.' },
+  { persona: 'reviewer', status: 'done', content: '[STEP:1]\napproved' },
+])
+```
+
+### Test Isolation
+
+| Criteria | Judgment |
+|----------|----------|
+| Tests sharing global state | REJECT |
+| Environment variables not cleared in test setup | Warning |
+| E2E tests assuming real API | Isolate via `provider` config |
+
+## Error Propagation
+
+Provider errors propagate through: `AgentResponse.error` → session log → console output.
+
+| Criteria | Judgment |
+|----------|----------|
+| SDK error results in empty `blocked` status | REJECT |
+| Error details not recorded in session log | REJECT |
+| No ABORT transition defined for error cases | Warning |
+
+## Session Management
+
+Agent sessions are stored per-cwd. Session resume is skipped during worktree/clone execution.
+
+| Criteria | Judgment |
+|----------|----------|
+| Session resuming when `cwd !== projectCwd` | REJECT (cross-project contamination) |
+| Session key missing provider identifier | REJECT (cross-provider contamination) |
+| Session broken between phases | REJECT (context loss) |

builtins/en/facets/knowledge/task-decomposition.md

@@ -0,0 +1,66 @@
+# Task Decomposition Knowledge
+
+## Decomposition Feasibility
+
+Before splitting a task into multiple parts, assess whether decomposition is appropriate. When decomposition is unsuitable, implementing in a single part is more efficient.
+
+| Criteria | Judgment |
+|----------|----------|
+| Changed files clearly separate into layers | Decompose |
+| Shared types/IDs span multiple parts | Single part |
+| Broad rename/refactoring | Single part |
+| Fewer than 5 files to change | Single part |
+| Same file needs editing by multiple parts | Single part |
+
+### Detecting Cross-Cutting Concerns
+
+When any of the following apply, independent parts cannot maintain consistency. Consolidate into a single part.
+
+- A new ID, key, or type is generated in one module and consumed in another
+- Both the event emitter and event receiver need changes
+- An existing interface signature changes, requiring updates to all call sites
+
+## File Exclusivity Principle
+
+When decomposing into multiple parts, each part's file ownership must be completely exclusive.
+
+| Criteria | Judgment |
+|----------|----------|
+| Same file edited by multiple parts | REJECT (causes conflicts) |
+| Type definition and consumer in different parts | Consolidate into the type definition part |
+| Test file and implementation file in different parts | Consolidate into the same part |
+
+### Grouping Priority
+
+1. **By dependency direction** — keep dependency source and target in the same part
+2. **By layer** — domain layer / infrastructure layer / API layer
+3. **By feature** — independent functional units
+
+## Failure Patterns
+
+### Part Overlap
+
+When two parts own the same file or feature, sub-agents overwrite each other's changes, causing repeated REJECT in reviews.
+
+```
+// NG: part-2 and part-3 own the same file
+part-2: taskInstructionActions.ts — instruct confirmation dialog
+part-3: taskInstructionActions.ts — requeue confirmation dialog
+
+// OK: consolidate into one part
+part-1: taskInstructionActions.ts — both instruct/requeue confirmation dialogs
+```
+
+### Shared Contract Mismatch
+
+When part A generates an ID that part B consumes, both parts implement independently, leading to mismatches in ID name, type, or passing mechanism.
+
+```
+// NG: shared contract across independent parts
+part-1: generates phaseExecutionId
+part-2: consumes phaseExecutionId
+→ part-1 uses string, part-2 expects number → integration error
+
+// OK: single part for consistent implementation
+part-1: implements phaseExecutionId from generation to consumption
+```

builtins/en/facets/knowledge/terraform-aws.md

@@ -0,0 +1,241 @@
+# Terraform AWS Knowledge
+
+## Module Design
+
+Split modules by domain (network, database, application layer). Do not create generic utility modules.
+
+| Criteria | Judgment |
+|----------|----------|
+| Domain-based module splitting | OK |
+| Generic "utils" module | REJECT |
+| Unrelated resources mixed in one module | REJECT |
+| Implicit inter-module dependencies | REJECT (connect explicitly via outputs→inputs) |
+
+### Inter-Module Dependencies
+
+Pass dependencies explicitly via outputs→inputs. Avoid implicit references (using `data` sources to look up other module resources).
+
+```hcl
+# OK - Explicit dependency
+module "database" {
+  source     = "../../modules/database"
+  vpc_id     = module.network.vpc_id
+  subnet_ids = module.network.private_subnet_ids
+}
+
+# NG - Implicit dependency
+module "database" {
+  source = "../../modules/database"
+  # vpc_id not passed; module uses data "aws_vpc" internally
+}
+```
+
+### Identification Variable Passthrough
+
+Pass identification variables (environment, service name) explicitly from root to child modules. Do not rely on globals or hardcoding.
+
+```hcl
+# OK - Explicit passthrough
+module "database" {
+  environment      = var.environment
+  service          = var.service
+  application_name = var.application_name
+}
+```
+
+## Resource Naming Convention
+
+Compute `name_prefix` in `locals` and apply consistently to all resources. Append resource-specific suffixes.
+
+| Criteria | Judgment |
+|----------|----------|
+| Unified naming with `name_prefix` pattern | OK |
+| Inconsistent naming across resources | REJECT |
+| Name exceeds AWS character limits | REJECT |
+| Tag names not in PascalCase | Warning |
+
+```hcl
+# OK - Unified with name_prefix
+locals {
+  name_prefix = "${var.environment}-${var.service}-${var.application_name}"
+}
+
+resource "aws_ecs_cluster" "main" {
+  name = "${local.name_prefix}-cluster"
+}
+
+# NG - Inconsistent naming
+resource "aws_ecs_cluster" "main" {
+  name = "${var.environment}-app-cluster"
+}
+```
+
+### Character Limit Handling
+
+AWS services have name character limits. Use shortened forms when approaching limits.
+
+| Service | Limit | Example |
+|---------|-------|---------|
+| Target Group | 32 chars | `${var.environment}-${var.service}-backend-tg` |
+| Lambda Function | 64 chars | Full prefix OK |
+| S3 Bucket | 63 chars | Full prefix OK |
+
+## Tagging Strategy
+
+Use provider `default_tags` for common tags. No duplicate tagging on individual resources.
+
+| Criteria | Judgment |
+|----------|----------|
+| Centralized via provider `default_tags` | OK |
+| Duplicate tags matching `default_tags` on individual resources | Warning |
+| Only `Name` tag added on individual resources | OK |
+
+```hcl
+# OK - Centralized, individual gets Name only
+provider "aws" {
+  default_tags {
+    tags = {
+      Environment = var.environment
+      ManagedBy   = "Terraform"
+    }
+  }
+}
+
+resource "aws_instance" "main" {
+  tags = {
+    Name = "${local.name_prefix}-instance"
+  }
+}
+
+# NG - Duplicates default_tags
+resource "aws_instance" "main" {
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "Terraform"
+    Name        = "${local.name_prefix}-instance"
+  }
+}
+```
+
+## File Organization Patterns
+
+### Environment Directory Structure
+
+Separate environments into directories, each with independent state management.
+
+```
+environments/
+├── production/
+│   ├── terraform.tf       # Version constraints
+│   ├── providers.tf       # Provider config (default_tags)
+│   ├── backend.tf         # S3 backend
+│   ├── variables.tf       # Environment variables
+│   ├── main.tf            # Module invocations
+│   └── outputs.tf         # Outputs
+└── staging/
+    └── ...
+```
+
+### Module File Structure
+
+| File | Contents |
+|------|----------|
+| `main.tf` | `locals` and `data` sources only |
+| `variables.tf` | Input variable definitions only (no resources) |
+| `outputs.tf` | Output definitions only (no resources) |
+| `{resource_type}.tf` | One file per resource category |
+| `templates/` | user_data scripts and other templates |
+
+## Security Best Practices
+
+### EC2 Instance Security
+
+| Setting | Recommended | Reason |
+|---------|-------------|--------|
+| `http_tokens` | `"required"` | Enforce IMDSv2 (SSRF prevention) |
+| `http_put_response_hop_limit` | `1` | Prevent container escapes |
+| `root_block_device.encrypted` | `true` | Data-at-rest encryption |
+
+### S3 Bucket Security
+
+Block all public access with all four settings. Use OAC (Origin Access Control) for CloudFront distributions.
+
+```hcl
+# OK - Complete block
+resource "aws_s3_bucket_public_access_block" "this" {
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+```
+
+### IAM Design
+
+| Pattern | Recommendation |
+|---------|---------------|
+| Per-service role separation | Separate execution role (for ECS Agent) and task role (for app) |
+| CI/CD authentication | OIDC federation (avoid long-lived credentials) |
+| Policy scope | Specify resource ARNs explicitly (avoid `"*"`) |
+
+### Secret Management
+
+| Method | Recommendation |
+|--------|---------------|
+| SSM Parameter Store (SecureString) | Recommended |
+| Secrets Manager | Recommended (when rotation needed) |
+| Direct in `.tfvars` | Conditional OK (gitignore required) |
+| Hardcoded in `.tf` files | REJECT |
+
+Set SSM Parameter initial values to placeholders and use `lifecycle { ignore_changes = [value] }` to manage outside Terraform.
+
+## Cost Optimization Patterns
+
+Document trade-offs with inline comments for cost-impacting choices.
+
+| Choice | Cost Effect | Trade-off |
+|--------|------------|-----------|
+| NAT Instance vs NAT Gateway | Instance ~$3-4/mo vs Gateway ~$32/mo | Lower availability and throughput |
+| Public subnet placement | No VPC Endpoints needed | Weaker network isolation |
+| EC2 + EBS vs RDS | EC2 ~$15-20/mo vs RDS ~$50+/mo | Higher operational burden |
+
+```hcl
+# OK - Trade-off documented
+# Using t3.nano instead of NAT Gateway (~$3-4/mo vs ~$32/mo)
+# Trade-off: single-AZ availability, throughput limits
+resource "aws_instance" "nat" {
+  instance_type = "t3.nano"
+}
+```
+
+## Lifecycle Rule Usage
+
+| Rule | Purpose | Target |
+|------|---------|--------|
+| `prevent_destroy` | Prevent accidental deletion | Databases, EBS volumes |
+| `ignore_changes` | Allow external changes | `desired_count` (Auto Scaling), SSM `value` |
+| `create_before_destroy` | Prevent downtime | Load balancers, security groups |
+
+```hcl
+# OK - Prevent accidental database deletion
+resource "aws_instance" "database" {
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+
+# OK - Let Auto Scaling manage desired_count
+resource "aws_ecs_service" "main" {
+  lifecycle {
+    ignore_changes = [desired_count]
+  }
+}
+```
+
+## Version Management
+
+| Setting | Recommendation |
+|---------|---------------|
+| `required_version` | `">= 1.5.0"` or higher (`default_tags` support) |
+| Provider version | Pin minor version with `~>` (e.g., `~> 5.80`) |
+| State locking | `use_lockfile = true` required |

builtins/en/facets/output-contracts/ai-review.md

@@ -15,22 +15,27 @@
 | Scope | ✅ | - |
 
 ## Current Iteration Findings (new)
-| # | finding_id | Category | Location | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
-|---|------------|----------|----------|-------|----------------|
+|---|------------|------------|----------|----------|-------|----------------|
-| 1 | AI-NEW-src-file-L23 | Hallucinated API | `src/file.ts:23` | Non-existent method | Replace with existing API |
+| 1 | AI-NEW-src-file-L23 | hallucination | Hallucinated API | `src/file.ts:23` | Non-existent method | Replace with existing API |
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
+|---|------------|------------|-------------------|------------------|-------|----------------|
-| 1 | AI-PERSIST-src-file-L42 | `src/file.ts:42` | `src/file.ts:42` | Still unresolved | Apply prior fix plan |
+| 1 | AI-PERSIST-src-file-L42 | hallucination | `src/file.ts:42` | `src/file.ts:42` | Still unresolved | Apply prior fix plan |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | AI-RESOLVED-src-file-L10 | `src/file.ts:10` no longer contains the issue |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | AI-REOPENED-src-file-L55 | hallucination | `Previously fixed at src/file.ts:10` | `Recurred at src/file.ts:55` | Issue description | Fix approach |
+
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 

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

@@ -15,24 +15,29 @@
 - [x] Call chain verification
 
 ## Current Iteration Findings (new)
-| # | finding_id | Scope | Location | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Scope | Location | Issue | Fix Suggestion |
-|---|------------|-------|----------|-------|----------------|
+|---|------------|------------|-------|----------|-------|----------------|
-| 1 | ARCH-NEW-src-file-L42 | In-scope | `src/file.ts:42` | Issue description | Fix approach |
+| 1 | ARCH-NEW-src-file-L42 | design-violation | In-scope | `src/file.ts:42` | Issue description | Fix approach |
 
 Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
+|---|------------|------------|-------------------|------------------|-------|----------------|
-| 1 | ARCH-PERSIST-src-file-L77 | `src/file.ts:77` | `src/file.ts:77` | Still unresolved | Apply prior fix plan |
+| 1 | ARCH-PERSIST-src-file-L77 | design-violation | `src/file.ts:77` | `src/file.ts:77` | Still unresolved | Apply prior fix plan |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | ARCH-RESOLVED-src-file-L10 | `src/file.ts:10` now satisfies the rule |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | ARCH-REOPENED-src-file-L55 | design-violation | `Previously fixed at src/file.ts:10` | `Recurred at src/file.ts:55` | Issue description | Fix approach |
+
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 

builtins/en/facets/output-contracts/cqrs-es-review.md

@@ -15,13 +15,33 @@
 | Projections | ✅ | - |
 | Eventual consistency | ✅ | - |
 
-## Issues (if REJECT)
+## Current Iteration Findings (new)
-| # | Scope | Location | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Scope | Location | Issue | Fix Suggestion |
-|---|-------|----------|-------|----------------|
+|---|------------|------------|-------|----------|-------|----------------|
-| 1 | In-scope | `src/file.ts:42` | Issue description | Fix approach |
+| 1 | CQRS-NEW-src-file-L42 | cqrs-violation | In-scope | `src/file.ts:42` | Issue description | Fix approach |
 
 Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
 
-## Existing Issues (reference, non-blocking)
+## Carry-over Findings (persists)
-- {Record of existing issues unrelated to the current change}
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | CQRS-PERSIST-src-file-L77 | cqrs-violation | `src/file.ts:77` | `src/file.ts:77` | Still unresolved | Apply prior fix plan |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| CQRS-RESOLVED-src-file-L10 | `src/file.ts:10` now satisfies the rule |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | CQRS-REOPENED-src-file-L55 | cqrs-violation | `Previously fixed at src/file.ts:10` | `Recurred at src/file.ts:55` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
 ```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

builtins/en/facets/output-contracts/frontend-review.md

@@ -15,8 +15,31 @@
 | Accessibility | ✅ | - |
 | Type safety | ✅ | - |
 
-## Issues (if REJECT)
+## Current Iteration Findings (new)
-| # | Location | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Location | Issue | Fix Suggestion |
-|---|----------|-------|----------------|
+|---|------------|------------|----------|-------|----------------|
-| 1 | `src/file.tsx:42` | Issue description | Fix approach |
+| 1 | FE-NEW-src-file-L42 | component-design | `src/file.tsx:42` | Issue description | Fix approach |
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | FE-PERSIST-src-file-L77 | component-design | `src/file.tsx:77` | `src/file.tsx:77` | Still unresolved | Apply prior fix plan |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| FE-RESOLVED-src-file-L10 | `src/file.tsx:10` now satisfies the rule |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | FE-REOPENED-src-file-L55 | component-design | `Previously fixed at src/file.tsx:10` | `Recurred at src/file.tsx:55` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
 ```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

builtins/en/facets/output-contracts/plan.md

@@ -9,18 +9,15 @@
 ### Objective
 {What needs to be achieved}
 
+### Reference Material Findings (when reference material exists)
+{Overview of reference implementation's approach and key differences from current implementation}
+
 ### Scope
 {Impact area}
 
-### Design Decisions (only when design is needed)
+### Approaches Considered (when design decisions exist)
-
+| Approach | Adopted? | Rationale |
-#### File Structure
+|----------|----------|-----------|
-| File | Role |
-|------|------|
-| `src/example.ts` | Overview |
-
-#### Design Patterns
-- {Adopted patterns and where they apply}
 
 ### Implementation Approach
 {How to proceed}
@@ -28,6 +25,10 @@
 ## Implementation Guidelines (only when design is needed)
 - {Guidelines the Coder should follow during implementation}
 
+## Out of Scope (only when items exist)
+| Item | Reason for exclusion |
+|------|---------------------|
+
 ## Open Questions (if any)
 - {Unclear points or items that need confirmation}
 ```

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

@@ -16,21 +16,26 @@
 | Maintainability | ✅ | - |
 
 ## Current Iteration Findings (new)
-| # | finding_id | Category | Location | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
-|---|------------|----------|----------|-------|----------------|
+|---|------------|------------|----------|----------|-------|----------------|
-| 1 | QA-NEW-src-test-L42 | Testing | `src/test.ts:42` | Missing negative test | Add failure-path test |
+| 1 | QA-NEW-src-test-L42 | test-coverage | Testing | `src/test.ts:42` | Missing negative test | Add failure-path test |
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
+|---|------------|------------|-------------------|------------------|-------|----------------|
-| 1 | QA-PERSIST-src-test-L77 | `src/test.ts:77` | `src/test.ts:77` | Still flaky | Stabilize assertion & setup |
+| 1 | QA-PERSIST-src-test-L77 | test-coverage | `src/test.ts:77` | `src/test.ts:77` | Still flaky | Stabilize assertion & setup |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | QA-RESOLVED-src-test-L10 | `src/test.ts:10` now covers error path |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | QA-REOPENED-src-test-L55 | test-coverage | `Previously fixed at src/test.ts:10` | `Recurred at src/test.ts:55` | Issue description | Fix approach |
+
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```

builtins/en/facets/output-contracts/requirements-review.md

@@ -0,0 +1,49 @@
+```markdown
+# Requirements Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the result in 1-2 sentences}
+
+## Requirements Cross-Reference
+| # | Requirement (from task) | Satisfied | Evidence (file:line) |
+|---|----------------------|-----------|----------------------|
+| 1 | {requirement 1} | ✅/❌ | `src/file.ts:42` |
+
+- If even one ❌ exists, REJECT is mandatory
+- A ✅ without evidence is invalid (must be verified in actual code)
+
+## Scope Check
+| # | Out-of-scope Change | File | Justification |
+|---|---------------------|------|---------------|
+| 1 | {change not in requirements} | `src/file.ts` | Justified/Unnecessary |
+
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|----------------|
+| 1 | REQ-NEW-src-file-L42 | req-gap | Unimplemented | `src/file.ts:42` | Issue description | Fix suggestion |
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | REQ-PERSIST-src-file-L77 | req-gap | `file:line` | `file:line` | Unresolved | Fix suggestion |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| REQ-RESOLVED-src-file-L10 | `file:line` now satisfies the requirement |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | REQ-REOPENED-src-file-L55 | req-gap | `Previously fixed at file:line` | `Recurred at file:line` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
+```
+
+**Cognitive load reduction rules:**
+- APPROVE: Summary only (5 lines or fewer)
+- REJECT: Only relevant findings in tables (30 lines or fewer)

builtins/en/facets/output-contracts/research-report.md

@@ -0,0 +1,28 @@
+```markdown
+# Research Report
+
+## Research Overview
+{Summarize the original request in 1-2 sentences}
+
+## Key Findings
+{Major insights discovered during research, as bullet points}
+
+## Research Results
+
+### {Topic 1}
+{Data and analysis results}
+
+### {Topic 2}
+{Data and analysis results}
+
+## Data Sources
+| # | Source | Type | Reliability |
+|---|--------|------|-------------|
+| 1 | {Source name/URL} | {Web/Codebase/Literature} | {High/Medium/Low} |
+
+## Conclusions and Recommendations
+{Conclusions and recommendations based on research results}
+
+## Remaining Gaps (if any)
+- {Items that could not be researched or unverified hypotheses}
+```

builtins/en/facets/output-contracts/review-gather.md

@@ -0,0 +1,37 @@
+```markdown
+# Review Target
+
+## Overview
+| Field | Details |
+|-------|---------|
+| Mode | PR / Branch / Current Diff |
+| Source | PR #{number} / Branch `{name}` / Working tree |
+| Title | {title or summary from commits} |
+| Labels | {label list, or N/A} |
+
+## Purpose & Requirements
+{Purpose and requirements extracted from PR description, commit messages, or task text}
+
+## Linked Issues
+{State "N/A" if not applicable}
+
+### Issue #{number}: {Issue title}
+- Labels: {label list}
+- Description: {Summary of Issue body}
+- Key comments: {Summary of relevant comments}
+
+## Commit History
+{Include for Branch/Current Diff modes. State "N/A" for PR mode}
+
+| Hash | Message |
+|------|---------|
+| `{short hash}` | {commit message} |
+
+## Changed Files
+| File | Type | Lines Changed |
+|------|------|---------------|
+| `{file path}` | Added/Modified/Deleted | +{added} -{removed} |
+
+## Diff
+{diff output}
+```

builtins/en/facets/output-contracts/security-review.md

@@ -14,25 +14,30 @@
 | Dependencies | ✅ | - |
 
 ## Current Iteration Findings (new)
-| # | finding_id | Severity | Type | Location | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Severity | Type | Location | Issue | Fix Suggestion |
-|---|------------|----------|------|----------|-------|----------------|
+|---|------------|------------|----------|------|----------|-------|----------------|
-| 1 | SEC-NEW-src-db-L42 | High | SQLi | `src/db.ts:42` | Raw query string | Use parameterized queries |
+| 1 | SEC-NEW-src-db-L42 | injection-risk | High | SQLi | `src/db.ts:42` | Raw query string | Use parameterized queries |
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
+|---|------------|------------|-------------------|------------------|-------|----------------|
-| 1 | SEC-PERSIST-src-auth-L18 | `src/auth.ts:18` | `src/auth.ts:18` | Weak validation persists | Harden validation |
+| 1 | SEC-PERSIST-src-auth-L18 | injection-risk | `src/auth.ts:18` | `src/auth.ts:18` | Weak validation persists | Harden validation |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | SEC-RESOLVED-src-db-L10 | `src/db.ts:10` now uses bound parameters |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | SEC-REOPENED-src-auth-L55 | injection-risk | `Previously fixed at src/auth.ts:20` | `Recurred at src/auth.ts:55` | Issue description | Fix approach |
+
 ## Warnings (non-blocking)
 - {Security recommendations}
 
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 

builtins/en/facets/output-contracts/terraform-review.md

@@ -0,0 +1,47 @@
+```markdown
+# Terraform Convention Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the result in 1-2 sentences}
+
+## Reviewed Aspects
+- [x] Variable declarations (type, description, sensitive)
+- [x] Resource naming (name_prefix pattern)
+- [x] File structure (one concern per file)
+- [x] Security settings
+- [x] Tag management
+- [x] lifecycle rules
+- [x] Cost trade-off documentation
+
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Scope | Location | Issue | Fix Suggestion |
+|---|------------|------------|-------|----------|-------|----------------|
+| 1 | TF-NEW-file-L42 | tf-convention | In-scope | `modules/example/main.tf:42` | Issue description | Fix approach |
+
+Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | TF-PERSIST-file-L77 | tf-convention | `file.tf:77` | `file.tf:77` | Still unresolved | Apply prior fix plan |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| TF-RESOLVED-file-L10 | `file.tf:10` now satisfies the convention |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | TF-REOPENED-file-L55 | tf-convention | `Previously fixed at file.tf:10` | `Recurred at file.tf:55` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
+```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

builtins/en/facets/output-contracts/testing-review.md

@@ -0,0 +1,46 @@
+```markdown
+# Testing Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the result in 1-2 sentences}
+
+## Reviewed Aspects
+| Aspect | Result | Notes |
+|--------|--------|-------|
+| Test coverage | ✅ | - |
+| Test structure (Given-When-Then) | ✅ | - |
+| Test naming | ✅ | - |
+| Test independence & reproducibility | ✅ | - |
+| Mocks & fixtures | ✅ | - |
+| Test strategy (unit/integration/E2E) | ✅ | - |
+
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|----------------|
+| 1 | TEST-NEW-src-test-L42 | test-structure | Coverage | `src/test.ts:42` | Issue description | Fix suggestion |
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | TEST-PERSIST-src-test-L77 | test-structure | `src/test.ts:77` | `src/test.ts:77` | Unresolved | Fix suggestion |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| TEST-RESOLVED-src-test-L10 | `src/test.ts:10` now has sufficient coverage |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | TEST-REOPENED-src-test-L55 | test-structure | `Previously fixed at src/test.ts:10` | `Recurred at src/test.ts:55` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
+```
+
+**Cognitive load reduction rules:**
+- APPROVE: Summary only (5 lines or fewer)
+- REJECT: Only relevant findings in tables (30 lines or fewer)

builtins/en/facets/personas/planner.md

@@ -97,6 +97,16 @@ Only plan work that is explicitly stated in the task order. Do not include impli
 "Change statuses to 5 values" means "rewrite enum values," NOT "delete flows that seem unnecessary."
 Do not over-interpret the task order. Plan only what is written.
 
+**Reference material intent:**
+- When the task order specifies external implementations as reference material, determine WHY that reference was specified
+- "Fix/improve by referencing X" includes evaluating whether to adopt the reference's design approach
+- When narrowing scope beyond the reference material's implied intent, explicitly document the rationale in the plan report
+
+**Bug fix propagation check:**
+- After identifying the root cause pattern, grep for the same pattern in related files
+- If the same bug exists in other files, include them in scope
+- This is not scope expansion — it is bug fix completeness
+
 ## Design Principles
 
 **Backward Compatibility:**
@@ -106,6 +116,7 @@ Do not over-interpret the task order. Plan only what is written.
 **Don't Generate Unnecessary Code:**
 - Don't plan "just in case" code, future fields, or unused methods
 - Don't plan to leave TODO comments. Either do it now, or don't
+- Don't put deferrable decisions in Open Questions. If you can resolve it by reading code, investigate and decide. Only include items that genuinely require user input
 
 **Important:**
 **Investigate before planning.** Don't plan without reading existing code.

builtins/en/facets/personas/requirements-reviewer.md

@@ -0,0 +1,26 @@
+# Requirements Reviewer
+
+You are a requirements fulfillment verifier. You verify that changes satisfy the original requirements and specifications, and flag any gaps or excess.
+
+## Role Boundaries
+
+**Do:**
+- Cross-reference requirements against implementation (whether each requirement is realized in actual code)
+- Detect implicit requirements (whether naturally expected behaviors are satisfied)
+- Detect scope creep (whether changes unrelated to requirements have crept in)
+- Identify unimplemented or partially implemented items
+- Flag ambiguity in specifications
+
+**Don't:**
+- Review code quality (Architecture Reviewer's job)
+- Review test coverage (Testing Reviewer's job)
+- Review security concerns (Security Reviewer's job)
+- Write code yourself
+
+## Behavioral Principles
+
+- Verify requirements one by one. Never say "broadly satisfied" in aggregate
+- Verify in actual code. Do not take "implemented" claims at face value
+- Guard the scope. Question any change not covered by the requirements
+- Do not tolerate ambiguity. Flag unclear or underspecified requirements
+- Pay attention to deletions. Confirm that file or code removals are justified by the requirements

builtins/en/facets/personas/supervisor.md

@@ -81,15 +81,7 @@ You are the **human proxy** in the automated piece. Before approval, verify the
 | Production ready | No mock/stub/TODO remaining? |
 | Operation | Actually works as expected? |
 
-### 6. Backward Compatibility Code Detection
+### 6. Spec Compliance Final Check
-
-**Backward compatibility code is unnecessary unless explicitly instructed.** REJECT if found:
-
-- Unused re-exports, `_var` renames, `// removed` comments
-- Fallbacks, old API maintenance, migration code
-- Legacy support kept "just in case"
-
-### 7. Spec Compliance Final Check
 
 **Final verification that changes comply with the project's documented specifications.**
 
@@ -115,66 +107,6 @@ Additions can be reverted, but restoring deleted flows is difficult.
 - A "UI fix" task includes structural changes to backend domain models
 - A "display change" task rewrites business logic flows
 
-### 8. Piece Overall Review
-
-**Check all reports in the report directory and verify overall piece consistency.**
-
-Check:
-- Does implementation match the plan (00-plan.md)?
-- Were all review step issues properly addressed?
-- Was the original task objective achieved?
-
-**Piece-wide issues:**
-| Issue | Action |
-|-------|--------|
-| Plan-implementation gap | REJECT - Request plan revision or implementation fix |
-| Unaddressed review feedback | REJECT - Point out specific unaddressed items |
-| Deviation from original purpose | REJECT - Request return to objective |
-| Scope creep | REJECT - Deletions outside task order must be reverted |
-
-### 9. Improvement Suggestion Check
-
-**Check review reports for unaddressed improvement suggestions.**
-
-Check:
-- "Improvement Suggestions" section in Architect report
-- Warnings and suggestions in AI Reviewer report
-- Recommendations in Security report
-
-**If there are unaddressed improvement suggestions:**
-- Judge if the improvement should be addressed in this task
-- If it should be addressed, **REJECT** and request fix
-- If it should be addressed in next task, record as "technical debt" in report
-
-**Judgment criteria:**
-| Type of suggestion | Decision |
-|--------------------|----------|
-| Minor fix in same file | Address now (REJECT) |
-| Fixable in seconds to minutes | Address now (REJECT) |
-| Redundant code / unnecessary expression removal | Address now (REJECT) |
-| Affects other features | Address in next task (record only) |
-| External impact (API changes, etc.) | Address in next task (record only) |
-| Requires significant refactoring (large scope) | Address in next task (record only) |
-
-### Boy Scout Rule
-
-**"Functionally harmless" is not a free pass.** Classifying a near-zero-cost fix as "non-blocking" or "next task" is a compromise. There is no guarantee it will be addressed in a future task, and it accumulates as technical debt.
-
-**Principle:** If a reviewer found it and it can be fixed in minutes, make the coder fix it now. Do not settle for recording it as a "non-blocking improvement suggestion."
-
-## Workaround Detection
-
-**REJECT** if any of the following remain:
-
-| Pattern | Example |
-|---------|---------|
-| TODO/FIXME | `// TODO: implement later` |
-| Commented out | Code that should be deleted remains |
-| Hardcoded | Values that should be config are hardcoded |
-| Mock data | Dummy data unusable in production |
-| console.log | Forgotten debug output |
-| Skipped tests | `@Disabled`, `.skip()` |
-
 ## Important
 
 - **Actually run**: Don't just look at files, execute and verify

builtins/en/facets/personas/terraform-coder.md

@@ -0,0 +1,30 @@
+# Terraform Coder
+
+You are a Terraform/AWS infrastructure implementation specialist. You write safe, maintainable infrastructure code following IaC principles.
+
+## Role Boundaries
+
+**Do:**
+- Create and modify Terraform code (.tf files)
+- Design modules and define variables
+- Implement security configurations (IAM, security groups, encryption)
+- Make cost optimization decisions and document trade-offs
+
+**Don't:**
+- Implement application code (implementation agent's responsibility)
+- Make final infrastructure design decisions (planning/design agent's responsibility)
+- Apply changes to production (`terraform apply` is never executed)
+
+## Behavioral Principles
+
+- Safety over speed. Infrastructure misconfigurations have greater impact than application bugs
+- Don't guess configurations; verify with official documentation
+- Never write secrets (passwords, tokens) in code
+- Document trade-offs with inline comments for cost-impacting choices
+- Security is strict by default. Only relax explicitly with justification
+
+**Be aware of AI's bad habits:**
+- Writing nonexistent resource attributes or provider arguments → Prohibited (verify with official docs)
+- Casually opening security groups to `0.0.0.0/0` → Prohibited
+- Writing unused variables or outputs "just in case" → Prohibited
+- Adding `depends_on` where implicit dependencies suffice → Prohibited

builtins/en/facets/personas/terraform-reviewer.md

@@ -0,0 +1,25 @@
+# Terraform Reviewer
+
+You are an IaC (Infrastructure as Code) convention specialist reviewer. You verify that Terraform code complies with project conventions and security standards.
+
+## Role Boundaries
+
+**Do:**
+- Verify Terraform convention compliance (naming, file organization, variable declarations)
+- Validate security configurations (IAM least privilege, encryption, access control)
+- Detect cost impacts and verify trade-off documentation
+- Validate `lifecycle` rule appropriateness
+
+**Don't:**
+- Write code yourself (only provide findings and fix suggestions)
+- Review AI-specific issues (separate review agent's responsibility)
+- Review application code (design review agent's responsibility)
+- Execute `terraform plan` (validation agent's responsibility)
+
+## Behavioral Principles
+
+- No compromises on security issues. Missing encryption or public access exposure is an immediate REJECT
+- Enforce naming consistency. Even one off-convention name gets flagged
+- Flag cost-impacting choices that lack trade-off documentation
+- No "conditional approvals". If there are issues, reject
+- Never miss unused variables/outputs/data sources

builtins/en/facets/personas/testing-reviewer.md

@@ -0,0 +1,27 @@
+# Testing Reviewer
+
+You are a test code quality specialist. You evaluate test structure, naming, coverage, independence, and verify the reliability of the test suite.
+
+## Role Boundaries
+
+**Do:**
+- Evaluate test structure (Given-When-Then / Arrange-Act-Assert)
+- Verify test naming conventions
+- Assess test coverage (whether new behaviors and bug fixes have tests)
+- Verify test independence and reproducibility
+- Check appropriateness of mocks and fixtures
+- Evaluate test strategy (unit/integration/E2E selection)
+
+**Don't:**
+- Review error handling or logging (QA Reviewer's job)
+- Review security concerns (Security Reviewer's job)
+- Review architecture decisions (Architecture Reviewer's job)
+- Write code yourself
+
+## Behavioral Principles
+
+- Untested code is not trustworthy. New behaviors must have tests
+- Structure matters. Demand improvements for tests that lack clear Given-When-Then
+- Ensure independence. Flag tests that depend on execution order or external state
+- Names convey intent. Verify that test names clearly describe the behavior under test
+- Balance coverage. Suggest both removing unnecessary tests and adding missing cases

builtins/en/facets/policies/ai-antipattern.md

@@ -47,6 +47,34 @@ AI often repeats the same patterns, including mistakes.
 | Inconsistent implementation | Same logic implemented differently across files |
 | Boilerplate explosion | Unnecessary repetition that could be abstracted |
 
+## Redundant Conditional Branch Detection
+
+AI tends to generate if/else blocks that call the same function with only argument differences.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Branch differs only in argument presence | `if (x) f(a, b, c) else f(a, b)` | REJECT |
+| Branch differs only in options | `if (x) f(a, {opt: x}) else f(a)` | REJECT |
+| Redundant else without using return value | `if (x) { f(a, x); return; } f(a);` | REJECT |
+
+```typescript
+// REJECT - both branches call the same function, differing only in the 3rd argument
+if (options.format !== undefined) {
+  await processFile(input, output, { format: options.format });
+} else {
+  await processFile(input, output);
+}
+
+// OK - extract the conditional into a variable, then make a single call
+const formatOpt = options.format !== undefined ? { format: options.format } : undefined;
+await processFile(input, output, formatOpt);
+```
+
+Verification approach:
+1. Find if/else blocks calling the same function
+2. If the only difference is optional argument presence, unify with ternary or spread syntax
+3. If branches have different preprocessing, store results in a variable and make a single call
+
 ## Context Fitness Assessment
 
 Does the code fit this specific project?
@@ -102,18 +130,18 @@ Logical dead code detection:
 AI tends to add "just in case" defensive code, but when considering caller constraints, it may be unreachable. Code that is syntactically reachable but logically unreachable due to call chain preconditions should be removed.
 
 ```typescript
-// REJECT - callers are only from interactive menus that require TTY
+// REJECT - callers always require interactive input
-// This function is never called from non-TTY environments
+// This function is never called from non-interactive environments
-function showFullDiff(cwd: string, branch: string): void {
+function displayResult(data: ResultData): void {
-  const usePager = process.stdin.isTTY === true;
+  const isInteractive = process.stdin.isTTY === true;
-  // usePager is always true (callers assume TTY)
+  // isInteractive is always true (callers assume TTY)
-  const pager = usePager ? 'less -R' : 'cat';  // else branch is unreachable
+  const output = isInteractive ? formatRich(data) : formatPlain(data);  // else branch is unreachable
 }
 
 // OK - understands caller constraints and removes unnecessary branching
-function showFullDiff(cwd: string, branch: string): void {
+function displayResult(data: ResultData): void {
   // Only called from interactive menus, so TTY is always present
-  spawnSync('git', ['diff', ...], { env: { GIT_PAGER: 'less -R' } });
+  console.log(formatRich(data));
 }
 ```
 

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

builtins/en/facets/policies/terraform.md

@@ -0,0 +1,88 @@
+# Terraform Policy
+
+Prioritize safety and maintainability. Write infrastructure code following consistent conventions.
+
+## Principles
+
+| Principle | Criteria |
+|-----------|----------|
+| Security by Default | Security is strict by default. Relaxation requires explicit justification |
+| Fail Fast | No defaults for required values. Missing values must error immediately |
+| Naming Consistency | Unified resource naming via `name_prefix` pattern |
+| Least Privilege | IAM scoped to minimum necessary actions and resources |
+| Cost Awareness | Document trade-offs with inline comments |
+| DRY | Compute common values in `locals`. Eliminate duplication |
+| One File One Concern | Split files by resource category |
+
+## Variable Declarations
+
+| Criteria | Judgment |
+|----------|----------|
+| Missing `type` | REJECT |
+| Missing `description` | REJECT |
+| Sensitive value without `sensitive = true` | REJECT |
+| Default on environment-dependent value | REJECT |
+| Default on constant value (port numbers, etc.) | OK |
+
+```hcl
+# REJECT - no type/description
+variable "region" {}
+
+# REJECT - sensitive value without sensitive flag
+variable "db_password" {
+  type = string
+}
+
+# OK - constant value with default
+variable "container_port" {
+  type        = number
+  description = "Container port for the application"
+  default     = 8080
+}
+```
+
+## Security
+
+| Criteria | Judgment |
+|----------|----------|
+| EC2 without IMDSv2 (`http_tokens != "required"`) | REJECT |
+| Unencrypted EBS/RDS | REJECT |
+| S3 without public access block | REJECT |
+| Security group with unnecessary `0.0.0.0/0` | REJECT |
+| IAM policy with `*` resource (no valid reason) | REJECT |
+| Direct SSH access (when SSM is viable) | REJECT |
+| Hardcoded secrets | REJECT |
+| Missing `lifecycle { prevent_destroy = true }` on critical data | Warning |
+
+## Naming Convention
+
+| Criteria | Judgment |
+|----------|----------|
+| `name_prefix` pattern not used | REJECT |
+| Resource name missing environment identifier | REJECT |
+| Tag names not in PascalCase | Warning |
+| Name exceeds AWS character limits | REJECT |
+
+## File Organization
+
+| Criteria | Judgment |
+|----------|----------|
+| Resource definitions mixed in `main.tf` | REJECT |
+| Resources defined in `variables.tf` | REJECT |
+| Multiple resource categories in one file | Warning |
+| Unused variable / output / data source | REJECT |
+
+## Tag Management
+
+| Criteria | Judgment |
+|----------|----------|
+| Provider `default_tags` not configured | REJECT |
+| Tags duplicated between `default_tags` and individual resources | Warning |
+| Missing `ManagedBy = "Terraform"` tag | Warning |
+
+## Cost Management
+
+| Criteria | Judgment |
+|----------|----------|
+| Cost-impacting choice without documentation | Warning |
+| High-cost resource without alternative consideration | Warning |

builtins/en/facets/policies/testing.md

@@ -70,6 +70,17 @@ Test names describe expected behavior. Use the `should {expected behavior} when
 - Do not overuse E2E tests for what unit tests can cover
 - If new logic only has E2E tests, propose adding unit tests
 
+### When Integration Tests Are Required
+
+Verify data flow coupling that unit tests alone cannot cover.
+
+| Condition | Verdict |
+|-----------|---------|
+| Data flow crossing 3+ modules | Integration test required |
+| New status/state merging into an existing workflow | Integration test for the full transition flow required |
+| New option propagating through a call chain to the endpoint | End-to-end chain coupling test required |
+| All module-level unit tests pass | Unit tests alone are sufficient (when none of the above apply) |
+
 ## Test Environment Isolation
 
 Tie test infrastructure configuration to test scenario parameters. Hardcoded assumptions break under different scenarios.

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
+      - dual-mini
-      - expert-cqrs-mini
+      - dual-cqrs-mini
   🎨 Frontend:
     pieces:
       - frontend
@@ -25,29 +22,42 @@ piece_categories:
       - backend-mini
       - backend-cqrs
       - backend-cqrs-mini
-  🔧 Expert:
+  🔧 Dual:
     pieces:
-      - expert
+      - dual
-      - expert-mini
+      - dual-mini
-      - expert-cqrs
+      - dual-cqrs
-      - expert-cqrs-mini
+      - dual-cqrs-mini
-  🛠️ Refactoring:
+  🏗️ Infrastructure:
     pieces:
-      - structural-reform
+      - terraform
   🔍 Review:
     pieces:
-      - review-fix-minimal
+      - review
-      - review-only
+      - 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:
+  🎵 TAKT Development:
     pieces:
-      - default-test-first-mini
+      - takt-default
+      - takt-default-team-leader
+      - takt-default-review-fix
   Others:
     pieces:
       - research
+      - deep-research
       - magi
 show_others_category: true
 others_category_name: Others

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

@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 20
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix_both
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: fix_both
+        - condition: unproductive (same findings repeating)
+          next: supervise_fix
 movements:
   - name: plan
     edit: false
@@ -17,13 +30,15 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Requirements are clear and implementation is possible
         next: implement
@@ -34,7 +49,7 @@ movements:
     instruction: plan
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -47,15 +62,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     instruction: implement
     rules:
@@ -81,19 +98,21 @@ movements:
         policy:
           - review
           - ai-antipattern
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         instruction: review-ai
         rules:
           - condition: No AI-specific issues
           - condition: AI-specific issues found
         output_contracts:
           report:
-            - name: 03-ai-review.md
+            - name: ai-review.md
               format: ai-review
       - name: supervise
         edit: false
@@ -104,13 +123,15 @@ movements:
           - cqrs-es
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Bash
+              - Glob
-          - WebSearch
+              - Grep
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         instruction: supervise
         rules:
           - condition: All checks passed
@@ -144,14 +165,16 @@ movements:
           - cqrs-es
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: AI Reviewer's issues fixed
@@ -169,14 +192,16 @@ movements:
           - cqrs-es
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: Supervisor's issues fixed
@@ -198,15 +223,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -228,15 +255,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:

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

@@ -0,0 +1,236 @@
+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-reviewers-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
+    provider_options:
+      claude:
+        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
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+    provider_options:
+      claude:
+        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
+    provider_options:
+      claude:
+        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
+    provider_options:
+      claude:
+        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

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

@@ -0,0 +1,160 @@
+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
+    provider_options:
+      claude:
+        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
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+    provider_options:
+      claude:
+        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

builtins/en/pieces/backend-cqrs.yaml

@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 30
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: unproductive (same findings repeating)
+          next: supervise
 movements:
   - name: plan
     edit: false
@@ -16,13 +29,15 @@ movements:
       - backend
       - cqrs-es
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: plan
     rules:
       - condition: Task analysis and planning is complete
@@ -31,7 +46,7 @@ movements:
         next: ABORT
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -45,15 +60,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: implement
     rules:
       - condition: Implementation is complete
@@ -78,12 +95,14 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: ai-review
     rules:
       - condition: No AI-specific issues found
@@ -92,7 +111,7 @@ movements:
         next: ai_fix
     output_contracts:
       report:
-        - name: 03-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -106,15 +125,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: ai-fix
     pass_previous_response: false
     rules:
@@ -128,10 +149,12 @@ movements:
     edit: false
     persona: architecture-reviewer
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
@@ -147,38 +170,42 @@ movements:
         knowledge:
           - cqrs-es
           - backend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-cqrs-es
         output_contracts:
           report:
-            - name: 04-cqrs-es-review.md
+            - name: cqrs-es-review.md
               format: cqrs-es-review
       - name: security-review
         edit: false
         persona: security-reviewer
         policy: review
         knowledge: security
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-security
         output_contracts:
           report:
-            - name: 05-security-review.md
+            - name: security-review.md
               format: security-review
       - name: qa-review
         edit: false
@@ -186,19 +213,21 @@ movements:
         policy:
           - review
           - qa
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-qa
         output_contracts:
           report:
-            - name: 06-qa-review.md
+            - name: qa-review.md
               format: qa-review
     rules:
       - condition: all("approved")
@@ -216,15 +245,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -235,14 +266,16 @@ movements:
     instruction: fix
   - name: supervise
     edit: false
-    persona: expert-supervisor
+    persona: dual-supervisor
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: supervise
     pass_previous_response: false
     rules:
@@ -268,15 +301,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: fix-supervisor
     pass_previous_response: false
     rules:

builtins/en/pieces/backend-mini.yaml

@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 20
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix_both
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: fix_both
+        - condition: unproductive (same findings repeating)
+          next: supervise_fix
 movements:
   - name: plan
     edit: false
@@ -16,13 +29,15 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Requirements are clear and implementation is possible
         next: implement
@@ -33,7 +48,7 @@ movements:
     instruction: plan
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -45,15 +60,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     instruction: implement
     rules:
@@ -79,19 +96,21 @@ movements:
         policy:
           - review
           - ai-antipattern
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         instruction: review-ai
         rules:
           - condition: No AI-specific issues
           - condition: AI-specific issues found
         output_contracts:
           report:
-            - name: 03-ai-review.md
+            - name: ai-review.md
               format: ai-review
       - name: supervise
         edit: false
@@ -101,13 +120,15 @@ movements:
           - backend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Bash
+              - Glob
-          - WebSearch
+              - Grep
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         instruction: supervise
         rules:
           - condition: All checks passed
@@ -140,14 +161,16 @@ movements:
           - backend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: AI Reviewer's issues fixed
@@ -164,14 +187,16 @@ movements:
           - backend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: Supervisor's issues fixed
@@ -192,15 +217,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -221,15 +248,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:

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

@@ -0,0 +1,210 @@
+name: backend-review-fix
+description: Backend-focused review + fix loop (structure, modularization, hexagonal architecture, 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-reviewers-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
+    provider_options:
+      claude:
+        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
+        provider_options:
+          claude:
+            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: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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
+    provider_options:
+      claude:
+        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
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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

builtins/en/pieces/backend-review.yaml

@@ -0,0 +1,136 @@
+name: backend-review
+description: Backend-focused review (structure, modularization, hexagonal architecture, 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
+    provider_options:
+      claude:
+        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
+        provider_options:
+          claude:
+            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: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+    provider_options:
+      claude:
+        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

builtins/en/pieces/backend.yaml

@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 30
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: unproductive (same findings repeating)
+          next: supervise
 movements:
   - name: plan
     edit: false
@@ -15,13 +28,15 @@ movements:
     knowledge:
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: plan
     rules:
       - condition: Task analysis and planning is complete
@@ -30,7 +45,7 @@ movements:
         next: ABORT
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -43,15 +58,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: implement
     rules:
       - condition: Implementation is complete
@@ -76,12 +93,14 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: ai-review
     rules:
       - condition: No AI-specific issues found
@@ -90,7 +109,7 @@ movements:
         next: ai_fix
     output_contracts:
       report:
-        - name: 03-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -103,15 +122,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: ai-fix
     pass_previous_response: false
     rules:
@@ -125,10 +146,12 @@ movements:
     edit: false
     persona: architecture-reviewer
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
@@ -144,38 +167,42 @@ movements:
         knowledge:
           - architecture
           - backend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-arch
         output_contracts:
           report:
-            - name: 04-architect-review.md
+            - name: architect-review.md
               format: architecture-review
       - name: security-review
         edit: false
         persona: security-reviewer
         policy: review
         knowledge: security
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-security
         output_contracts:
           report:
-            - name: 05-security-review.md
+            - name: security-review.md
               format: security-review
       - name: qa-review
         edit: false
@@ -183,19 +210,21 @@ movements:
         policy:
           - review
           - qa
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-qa
         output_contracts:
           report:
-            - name: 06-qa-review.md
+            - name: qa-review.md
               format: qa-review
     rules:
       - condition: all("approved")
@@ -212,15 +241,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -231,14 +262,16 @@ movements:
     instruction: fix
   - name: supervise
     edit: false
-    persona: expert-supervisor
+    persona: dual-supervisor
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: supervise
     pass_previous_response: false
     rules:
@@ -263,15 +296,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: fix-supervisor
     pass_previous_response: false
     rules:

builtins/en/pieces/compound-eye.yaml

@@ -17,13 +17,15 @@ movements:
         provider: claude
         session: refresh
         knowledge: architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Bash
+              - Glob
-          - WebSearch
+              - Grep
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         rules:
           - condition: done
           - condition: failed
@@ -56,13 +58,15 @@ movements:
         provider: codex
         session: refresh
         knowledge: architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Bash
+              - Glob
-          - WebSearch
+              - Grep
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         rules:
           - condition: done
           - condition: failed
@@ -95,10 +99,12 @@ movements:
   - name: synthesize
     edit: false
     persona: supervisor
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: synthesis complete
         next: COMPLETE

builtins/en/pieces/deep-research.yaml

@@ -14,12 +14,14 @@ movements:
     policy: research
     knowledge: research
     instruction: research-plan
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Planning is complete
         next: dig
@@ -30,12 +32,29 @@ movements:
     policy: research
     knowledge: research
     instruction: research-dig
-    allowed_tools:
+    edit: true
-      - Read
+    team_leader:
-      - Glob
+      max_parts: 3
-      - Grep
+      part_persona: research-digger
-      - WebSearch
+      part_edit: true
-      - WebFetch
+      part_allowed_tools:
+        - Read
+        - Write
+        - Bash
+        - Glob
+        - Grep
+        - WebSearch
+        - WebFetch
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Write
+          - Bash
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Research is complete
         next: analyze
@@ -46,12 +65,16 @@ movements:
     policy: research
     knowledge: research
     instruction: research-analyze
-    allowed_tools:
+    edit: true
-      - Read
+    provider_options:
-      - Glob
+      claude:
-      - Grep
+        allowed_tools:
-      - WebSearch
+          - Read
-      - WebFetch
+          - Write
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
     rules:
       - condition: New questions exist and additional research is needed
         next: dig
@@ -62,12 +85,18 @@ movements:
     policy: research
     knowledge: research
     instruction: research-supervise
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
+    output_contracts:
+      report:
+        - name: research-report.md
+          format: research-report
     rules:
       - condition: Research results adequately answer the original request
         next: COMPLETE

builtins/en/pieces/default-mini.yaml

@@ -1,219 +0,0 @@
-name: default-mini
-description: Mini development piece (plan -> implement -> parallel review -> fix if needed -> complete)
-piece_config:
-  provider_options:
-    codex:
-      network_access: true
-    opencode:
-      network_access: true
-max_movements: 20
-initial_movement: plan
-movements:
-  - name: plan
-    edit: false
-    persona: planner
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Bash
-      - WebSearch
-      - WebFetch
-    rules:
-      - condition: Requirements are clear and implementation is possible
-        next: implement
-      - condition: User is asking a question (not an implementation task)
-        next: COMPLETE
-      - condition: Requirements are unclear, insufficient information
-        next: ABORT
-    instruction: plan
-    output_contracts:
-      report:
-        - name: 00-plan.md
-          format: plan
-  - name: implement
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    instruction: implement
-    rules:
-      - condition: Implementation complete
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: ABORT
-      - condition: User input required because there are items to confirm with the user
-        next: implement
-        requires_user_input: true
-        interactive_only: true
-    output_contracts:
-      report:
-        - name: coder-scope.md
-          format: coder-scope
-        - name: coder-decisions.md
-          format: coder-decisions
-  - name: reviewers
-    parallel:
-      - name: ai_review
-        edit: false
-        persona: ai-antipattern-reviewer
-        policy:
-          - review
-          - ai-antipattern
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - WebSearch
-          - WebFetch
-        instruction: review-ai
-        rules:
-          - condition: No AI-specific issues
-          - condition: AI-specific issues found
-        output_contracts:
-          report:
-            - name: 03-ai-review.md
-              format: ai-review
-      - name: supervise
-        edit: false
-        persona: supervisor
-        policy: review
-        knowledge: architecture
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Bash
-          - WebSearch
-          - WebFetch
-        instruction: supervise
-        rules:
-          - condition: All checks passed
-          - condition: Requirements unmet, tests failing
-        output_contracts:
-          report:
-            - name: supervisor-validation.md
-              format: supervisor-validation
-            - name: summary.md
-              format: summary
-              use_judge: false
-    rules:
-      - condition: all("No AI-specific issues", "All checks passed")
-        next: COMPLETE
-      - condition: all("AI-specific issues found", "Requirements unmet, tests failing")
-        next: fix_both
-      - condition: any("AI-specific issues found")
-        next: ai_fix
-      - condition: any("Requirements unmet, tests failing")
-        next: supervise_fix
-  - name: fix_both
-    parallel:
-      - name: ai_fix_parallel
-        edit: true
-        persona: coder
-        policy:
-          - coding
-          - testing
-        knowledge: architecture
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Edit
-          - Bash
-          - WebSearch
-          - WebFetch
-        required_permission_mode: edit
-        rules:
-          - condition: AI Reviewer's issues fixed
-          - condition: No fix needed (verified target files/spec)
-          - condition: Cannot proceed, insufficient info
-        instruction: ai-fix
-      - name: supervise_fix_parallel
-        edit: true
-        persona: coder
-        policy:
-          - coding
-          - testing
-        knowledge: architecture
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Edit
-          - Bash
-          - WebSearch
-          - WebFetch
-        required_permission_mode: edit
-        rules:
-          - condition: Supervisor's issues fixed
-          - condition: Cannot proceed, insufficient info
-        instruction: fix-supervisor
-    rules:
-      - condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
-        next: reviewers
-      - condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
-        next: implement
-  - name: ai_fix
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    pass_previous_response: false
-    rules:
-      - condition: AI Reviewer's issues fixed
-        next: reviewers
-      - condition: No fix needed (verified target files/spec)
-        next: implement
-      - condition: Cannot proceed, insufficient info
-        next: implement
-    instruction: ai-fix
-  - name: supervise_fix
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    pass_previous_response: false
-    rules:
-      - condition: Supervisor's issues fixed
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: implement
-    instruction: fix-supervisor

builtins/en/pieces/default-test-first-mini.yaml

@@ -1,252 +0,0 @@
-name: default-test-first-mini
-description: Test-first development piece (plan -> write tests -> implement -> parallel review -> fix if needed -> complete)
-piece_config:
-  provider_options:
-    codex:
-      network_access: true
-    opencode:
-      network_access: true
-max_movements: 25
-initial_movement: plan
-movements:
-  - name: plan
-    edit: false
-    persona: planner
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Bash
-      - WebSearch
-      - WebFetch
-    rules:
-      - condition: Requirements are clear and implementation is possible
-        next: write_tests
-      - condition: User is asking a question (not an implementation task)
-        next: COMPLETE
-      - condition: Requirements are unclear, insufficient information
-        next: ABORT
-    instruction: plan
-    output_contracts:
-      report:
-        - name: 00-plan.md
-          format: plan
-  - name: write_tests
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    instruction: write-tests-first
-    rules:
-      - condition: Tests written successfully
-        next: implement
-      - condition: Cannot proceed with test creation
-        next: ABORT
-      - condition: User input required because there are items to confirm with the user
-        next: write_tests
-        requires_user_input: true
-        interactive_only: true
-    output_contracts:
-      report:
-        - name: 01-test-scope.md
-          format: coder-scope
-        - name: 01-test-decisions.md
-          format: coder-decisions
-  - name: implement
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    instruction: implement-after-tests
-    rules:
-      - condition: Implementation complete
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: ABORT
-      - condition: User input required because there are items to confirm with the user
-        next: implement
-        requires_user_input: true
-        interactive_only: true
-    output_contracts:
-      report:
-        - name: coder-scope.md
-          format: coder-scope
-        - name: coder-decisions.md
-          format: coder-decisions
-  - name: reviewers
-    parallel:
-      - name: ai_review
-        edit: false
-        persona: ai-antipattern-reviewer
-        policy:
-          - review
-          - ai-antipattern
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - WebSearch
-          - WebFetch
-        instruction: review-ai
-        rules:
-          - condition: No AI-specific issues
-          - condition: AI-specific issues found
-        output_contracts:
-          report:
-            - name: 03-ai-review.md
-              format: ai-review
-      - name: supervise
-        edit: false
-        persona: supervisor
-        policy: review
-        knowledge: architecture
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Bash
-          - WebSearch
-          - WebFetch
-        instruction: supervise
-        rules:
-          - condition: All checks passed
-          - condition: Requirements unmet, tests failing
-        output_contracts:
-          report:
-            - name: supervisor-validation.md
-              format: supervisor-validation
-            - name: summary.md
-              format: summary
-              use_judge: false
-    rules:
-      - condition: all("No AI-specific issues", "All checks passed")
-        next: COMPLETE
-      - condition: all("AI-specific issues found", "Requirements unmet, tests failing")
-        next: fix_both
-      - condition: any("AI-specific issues found")
-        next: ai_fix
-      - condition: any("Requirements unmet, tests failing")
-        next: supervise_fix
-  - name: fix_both
-    parallel:
-      - name: ai_fix_parallel
-        edit: true
-        persona: coder
-        policy:
-          - coding
-          - testing
-        knowledge: architecture
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Edit
-          - Bash
-          - WebSearch
-          - WebFetch
-        required_permission_mode: edit
-        rules:
-          - condition: AI Reviewer's issues fixed
-          - condition: No fix needed (verified target files/spec)
-          - condition: Cannot proceed, insufficient info
-        instruction: ai-fix
-      - name: supervise_fix_parallel
-        edit: true
-        persona: coder
-        policy:
-          - coding
-          - testing
-        knowledge: architecture
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Edit
-          - Bash
-          - WebSearch
-          - WebFetch
-        required_permission_mode: edit
-        rules:
-          - condition: Supervisor's issues fixed
-          - condition: Cannot proceed, insufficient info
-        instruction: fix-supervisor
-    rules:
-      - condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
-        next: reviewers
-      - condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
-        next: implement
-  - name: ai_fix
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    pass_previous_response: false
-    rules:
-      - condition: AI Reviewer's issues fixed
-        next: reviewers
-      - condition: No fix needed (verified target files/spec)
-        next: implement
-      - condition: Cannot proceed, insufficient info
-        next: implement
-    instruction: ai-fix
-  - name: supervise_fix
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    pass_previous_response: false
-    rules:
-      - condition: Supervisor's issues fixed
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: implement
-    instruction: fix-supervisor

builtins/en/pieces/default.yaml

@@ -1,5 +1,5 @@
 name: default
-description: Standard development piece with planning and specialized reviews
+description: Test-first development piece (plan → write tests → implement → AI antipattern review → parallel review → complete)
 piece_config:
   provider_options:
     codex:
@@ -22,7 +22,7 @@ loop_monitors:
         is healthy (making progress) or unproductive (repeating the same issues).
 
         **Reports to reference:**
-        - AI Review results: {report:04-ai-review.md}
+        - AI Review results: {report:ai-review.md}
 
         **Judgment criteria:**
         - Are new issues being found/fixed in each cycle?
@@ -33,21 +33,35 @@ loop_monitors:
           next: ai_review
         - condition: Unproductive (no improvement)
           next: reviewers
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: unproductive (same findings repeating)
+          next: ABORT
 movements:
   - name: plan
     edit: false
     persona: planner
     knowledge: architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Requirements are clear and implementable
-        next: implement
+        next: write_tests
       - condition: User is asking a question (not an implementation task)
         next: COMPLETE
       - condition: Requirements unclear, insufficient info
@@ -59,8 +73,46 @@ movements:
     instruction: plan
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
+  - name: write_tests
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    instruction: write-tests-first
+    rules:
+      - condition: Tests written successfully
+        next: implement
+      - condition: Cannot proceed because the test target is not implemented yet, so skip test writing
+        next: implement
+      - condition: Cannot proceed with test writing
+        next: ABORT
+      - condition: User input needed for clarification
+        next: write_tests
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: test-scope.md
+          format: coder-scope
+        - name: test-decisions.md
+          format: coder-decisions
   - name: implement
     edit: true
     persona: coder
@@ -69,18 +121,20 @@ movements:
       - testing
     session: refresh
     knowledge:
-      - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
+    instruction: implement-after-tests
     rules:
       - condition: Implementation complete
         next: ai_review
@@ -92,7 +146,6 @@ movements:
         next: implement
         requires_user_input: true
         interactive_only: true
-    instruction: implement
     output_contracts:
       report:
         - name: coder-scope.md
@@ -105,21 +158,23 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
+    instruction: ai-review
     rules:
       - condition: No AI-specific issues
         next: reviewers
       - condition: AI-specific issues found
         next: ai_fix
-    instruction: ai-review
     output_contracts:
       report:
-        - name: 04-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -129,88 +184,79 @@ movements:
       - testing
     session: refresh
     knowledge:
-      - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
+    instruction: ai-fix
     pass_previous_response: false
     rules:
       - condition: AI issues fixed
         next: ai_review
       - condition: No fix needed (verified target files/spec)
-        next: ai_no_fix
-      - condition: Cannot proceed, insufficient info
-        next: ai_no_fix
-    instruction: ai-fix
-  - name: ai_no_fix
-    edit: false
-    persona: architecture-reviewer
-    policy: review
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-    rules:
-      - condition: ai_review's findings are valid (fix required)
-        next: ai_fix
-      - condition: ai_fix's judgment is valid (no fix needed)
         next: reviewers
-    instruction: arbitrate
+      - condition: Cannot proceed with fixes
+        next: reviewers
   - name: reviewers
     parallel:
       - name: arch-review
         edit: false
         persona: architecture-reviewer
         policy: review
-        knowledge:
+        knowledge: architecture
-          - architecture
+        provider_options:
-          - backend
+          claude:
-        allowed_tools:
+            allowed_tools:
-          - Read
+              - Read
-          - Glob
+              - Glob
-          - Grep
+              - Grep
-          - WebSearch
+              - WebSearch
-          - WebFetch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-arch
         output_contracts:
           report:
-            - name: 05-architect-review.md
+            - name: architect-review.md
               format: architecture-review
-      - name: qa-review
+      - name: supervise
         edit: false
-        persona: qa-reviewer
+        persona: supervisor
-        policy:
+        policy: review
-          - review
+        provider_options:
-          - qa
+          claude:
-        allowed_tools:
+            allowed_tools:
-          - Read
+              - Read
-          - Glob
+              - Glob
-          - Grep
+              - Grep
-          - WebSearch
+              - Bash
-          - WebFetch
+              - WebSearch
+              - WebFetch
+        instruction: supervise
         rules:
-          - condition: approved
+          - condition: All checks passed
-          - condition: needs_fix
+          - condition: Requirements unmet, tests failing, build errors
-        instruction: review-qa
         output_contracts:
           report:
-            - name: 06-qa-review.md
+            - name: supervisor-validation.md
-              format: qa-review
+              format: supervisor-validation
+            - name: summary.md
+              format: summary
+              use_judge: false
     rules:
-      - condition: all("approved")
+      - condition: all("approved", "All checks passed")
-        next: supervise
+        next: COMPLETE
-      - condition: any("needs_fix")
+      - condition: any("needs_fix", "Requirements unmet, tests failing, build errors")
         next: fix
   - name: fix
     edit: true
@@ -219,47 +265,23 @@ movements:
       - coding
       - testing
     knowledge:
-      - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
+    instruction: fix
     pass_previous_response: false
     rules:
       - condition: Fix complete
         next: reviewers
       - condition: Cannot proceed, insufficient info
         next: plan
-    instruction: fix
-  - name: supervise
-    edit: false
-    persona: supervisor
-    policy: review
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Bash
-      - WebSearch
-      - WebFetch
-    pass_previous_response: false
-    rules:
-      - condition: All checks passed
-        next: COMPLETE
-      - condition: Requirements unmet, tests failing, build errors
-        next: plan
-    instruction: supervise
-    output_contracts:
-      report:
-        - name: supervisor-validation.md
-          format: supervisor-validation
-        - name: summary.md
-          format: summary
-          use_judge: false

builtins/en/pieces/dual-cqrs-mini.yaml

@@ -1,5 +1,5 @@
-name: expert-cqrs-mini
+name: dual-cqrs-mini
-description: CQRS+ES Expert-focused mini development piece (plan -> implement -> parallel review -> fix if needed -> complete)
+description: CQRS+ES frontend + backend mini development piece (plan -> implement -> parallel review -> fix if needed -> complete) with CQRS+ES knowledge injection
 piece_config:
   provider_options:
     codex:
@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 20
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix_both
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: fix_both
+        - condition: unproductive (same findings repeating)
+          next: supervise_fix
 movements:
   - name: plan
     edit: false
@@ -18,13 +31,15 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Requirements are clear and implementation is possible
         next: implement
@@ -35,7 +50,7 @@ movements:
     instruction: plan
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -49,15 +64,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     instruction: implement
     rules:
@@ -83,23 +100,25 @@ movements:
         policy:
           - review
           - ai-antipattern
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         instruction: review-ai
         rules:
           - condition: No AI-specific issues
           - condition: AI-specific issues found
         output_contracts:
           report:
-            - name: 03-ai-review.md
+            - name: ai-review.md
               format: ai-review
       - name: supervise
         edit: false
-        persona: expert-supervisor
+        persona: dual-supervisor
         policy: review
         knowledge:
           - frontend
@@ -107,13 +126,15 @@ movements:
           - cqrs-es
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Bash
+              - Glob
-          - WebSearch
+              - Grep
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         instruction: supervise
         rules:
           - condition: All checks passed
@@ -148,14 +169,16 @@ movements:
           - cqrs-es
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: AI Reviewer's issues fixed
@@ -174,14 +197,16 @@ movements:
           - cqrs-es
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: Supervisor's issues fixed
@@ -204,15 +229,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -235,15 +262,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:

builtins/en/pieces/dual-cqrs-review-fix.yaml

@@ -0,0 +1,261 @@
+name: dual-cqrs-review-fix
+description: Frontend + CQRS+ES focused review + fix loop (structure, modularization, domain model, component design, 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-reviewers-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
+    provider_options:
+      claude:
+        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
+          - frontend
+          - backend
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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: frontend-review
+        edit: false
+        persona: frontend-reviewer
+        policy: review
+        knowledge: frontend
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        instruction: review-frontend
+        output_contracts:
+          report:
+            - name: frontend-review.md
+              format: frontend-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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:
+      - frontend
+      - backend
+      - cqrs-es
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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
+    provider_options:
+      claude:
+        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:
+      - frontend
+      - backend
+      - cqrs-es
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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

builtins/en/pieces/dual-cqrs-review.yaml

@@ -0,0 +1,183 @@
+name: dual-cqrs-review
+description: Frontend + CQRS+ES focused review (structure, modularization, domain model, component design, 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
+    provider_options:
+      claude:
+        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
+          - frontend
+          - backend
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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: frontend-review
+        edit: false
+        persona: frontend-reviewer
+        policy: review
+        knowledge: frontend
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        instruction: review-frontend
+        output_contracts:
+          report:
+            - name: frontend-review.md
+              format: frontend-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+    provider_options:
+      claude:
+        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

builtins/en/pieces/dual-cqrs.yaml

@@ -1,5 +1,5 @@
-name: expert-cqrs
+name: dual-cqrs
-description: CQRS+ES, Frontend, Security, QA Expert Review
+description: Frontend + backend development piece (CQRS+ES specialized) with CQRS+ES, frontend, security, and QA reviews with fix loops
 piece_config:
   provider_options:
     codex:
@@ -21,6 +21,18 @@ loop_monitors:
           next: ai_review
         - condition: Unproductive (same findings repeated or fixes not reflected)
           next: ai_no_fix
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: Healthy (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: Unproductive (same findings repeating)
+          next: supervise
 movements:
   - name: plan
     edit: false
@@ -30,13 +42,15 @@ movements:
       - backend
       - cqrs-es
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: plan
     rules:
       - condition: Task analysis and planning is complete
@@ -45,7 +59,7 @@ movements:
         next: ABORT
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -60,15 +74,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: implement
     rules:
       - condition: Implementation is complete
@@ -93,12 +109,14 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: ai-review
     rules:
       - condition: No AI-specific issues found
@@ -107,7 +125,7 @@ movements:
         next: ai_fix
     output_contracts:
       report:
-        - name: 03-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -122,15 +140,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: ai-fix
     pass_previous_response: false
     rules:
@@ -144,10 +164,12 @@ movements:
     edit: false
     persona: architecture-reviewer
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
@@ -163,57 +185,63 @@ movements:
         knowledge:
           - cqrs-es
           - backend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-cqrs-es
         output_contracts:
           report:
-            - name: 04-cqrs-es-review.md
+            - name: cqrs-es-review.md
               format: cqrs-es-review
       - name: frontend-review
         edit: false
         persona: frontend-reviewer
         policy: review
         knowledge: frontend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-frontend
         output_contracts:
           report:
-            - name: 05-frontend-review.md
+            - name: frontend-review.md
               format: frontend-review
       - name: security-review
         edit: false
         persona: security-reviewer
         policy: review
         knowledge: security
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-security
         output_contracts:
           report:
-            - name: 06-security-review.md
+            - name: security-review.md
               format: security-review
       - name: qa-review
         edit: false
@@ -221,19 +249,21 @@ movements:
         policy:
           - review
           - qa
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-qa
         output_contracts:
           report:
-            - name: 07-qa-review.md
+            - name: qa-review.md
               format: qa-review
     rules:
       - condition: all("approved")
@@ -252,15 +282,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -271,14 +303,16 @@ movements:
     instruction: fix
   - name: supervise
     edit: false
-    persona: expert-supervisor
+    persona: dual-supervisor
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: supervise
     pass_previous_response: false
     rules:
@@ -305,15 +339,17 @@ movements:
       - cqrs-es
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: fix-supervisor
     pass_previous_response: false
     rules:

builtins/en/pieces/dual-mini.yaml

@@ -1,5 +1,5 @@
-name: expert-mini
+name: dual-mini
-description: Expert-focused mini development piece (plan -> implement -> parallel review -> fix if needed -> complete)
+description: Frontend + backend mini development piece (plan -> implement -> parallel review -> fix if needed -> complete) with frontend + backend knowledge injection
 piece_config:
   provider_options:
     codex:
@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 20
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix_both
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: fix_both
+        - condition: unproductive (same findings repeating)
+          next: supervise_fix
 movements:
   - name: plan
     edit: false
@@ -17,13 +30,15 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Requirements are clear and implementation is possible
         next: implement
@@ -34,7 +49,7 @@ movements:
     instruction: plan
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -47,15 +62,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     instruction: implement
     rules:
@@ -81,36 +98,40 @@ movements:
         policy:
           - review
           - ai-antipattern
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         instruction: review-ai
         rules:
           - condition: No AI-specific issues
           - condition: AI-specific issues found
         output_contracts:
           report:
-            - name: 03-ai-review.md
+            - name: ai-review.md
               format: ai-review
       - name: supervise
         edit: false
-        persona: expert-supervisor
+        persona: dual-supervisor
         policy: review
         knowledge:
           - frontend
           - backend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Bash
+              - Glob
-          - WebSearch
+              - Grep
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         instruction: supervise
         rules:
           - condition: All checks passed
@@ -144,14 +165,16 @@ movements:
           - backend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: AI Reviewer's issues fixed
@@ -169,14 +192,16 @@ movements:
           - backend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: Supervisor's issues fixed
@@ -198,15 +223,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -228,15 +255,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:

builtins/en/pieces/dual-review-fix.yaml

@@ -0,0 +1,235 @@
+name: dual-review-fix
+description: Frontend + backend focused review + fix loop (structure, modularization, component design, 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-reviewers-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
+    provider_options:
+      claude:
+        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
+          - frontend
+          - backend
+        provider_options:
+          claude:
+            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: frontend-review
+        edit: false
+        persona: frontend-reviewer
+        policy: review
+        knowledge: frontend
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        instruction: review-frontend
+        output_contracts:
+          report:
+            - name: frontend-review.md
+              format: frontend-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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:
+      - frontend
+      - backend
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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
+    provider_options:
+      claude:
+        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:
+      - frontend
+      - backend
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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

builtins/en/pieces/dual-review.yaml

@@ -0,0 +1,159 @@
+name: dual-review
+description: Frontend + backend focused review (structure, modularization, component design, 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
+    provider_options:
+      claude:
+        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
+          - frontend
+          - backend
+        provider_options:
+          claude:
+            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: frontend-review
+        edit: false
+        persona: frontend-reviewer
+        policy: review
+        knowledge: frontend
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        instruction: review-frontend
+        output_contracts:
+          report:
+            - name: frontend-review.md
+              format: frontend-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+    provider_options:
+      claude:
+        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

builtins/en/pieces/dual.yaml

@@ -1,5 +1,5 @@
-name: expert
+name: dual
-description: Architecture, Frontend, Security, QA Expert Review
+description: Frontend + backend development piece with architecture, frontend, security, and QA reviews with fix loops
 piece_config:
   provider_options:
     codex:
@@ -21,6 +21,18 @@ loop_monitors:
           next: ai_review
         - condition: Unproductive (same findings repeated or fixes not reflected)
           next: ai_no_fix
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: unproductive (same findings repeating)
+          next: supervise
 movements:
   - name: plan
     edit: false
@@ -29,13 +41,15 @@ movements:
       - frontend
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: plan
     rules:
       - condition: Task analysis and planning is complete
@@ -44,7 +58,7 @@ movements:
         next: ABORT
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -58,15 +72,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: implement
     rules:
       - condition: Implementation is complete
@@ -91,12 +107,14 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: ai-review
     rules:
       - condition: No AI-specific issues found
@@ -105,7 +123,7 @@ movements:
         next: ai_fix
     output_contracts:
       report:
-        - name: 03-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -119,15 +137,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: ai-fix
     pass_previous_response: false
     rules:
@@ -141,10 +161,12 @@ movements:
     edit: false
     persona: architecture-reviewer
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
@@ -160,57 +182,63 @@ movements:
         knowledge:
           - architecture
           - backend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-arch
         output_contracts:
           report:
-            - name: 04-architect-review.md
+            - name: architect-review.md
               format: architecture-review
       - name: frontend-review
         edit: false
         persona: frontend-reviewer
         policy: review
         knowledge: frontend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-frontend
         output_contracts:
           report:
-            - name: 05-frontend-review.md
+            - name: frontend-review.md
               format: frontend-review
       - name: security-review
         edit: false
         persona: security-reviewer
         policy: review
         knowledge: security
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-security
         output_contracts:
           report:
-            - name: 06-security-review.md
+            - name: security-review.md
               format: security-review
       - name: qa-review
         edit: false
@@ -218,19 +246,21 @@ movements:
         policy:
           - review
           - qa
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-qa
         output_contracts:
           report:
-            - name: 07-qa-review.md
+            - name: qa-review.md
               format: qa-review
     rules:
       - condition: all("approved")
@@ -248,15 +278,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -267,14 +299,16 @@ movements:
     instruction: fix
   - name: supervise
     edit: false
-    persona: expert-supervisor
+    persona: dual-supervisor
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: supervise
     pass_previous_response: false
     rules:
@@ -300,15 +334,17 @@ movements:
       - backend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: fix-supervisor
     pass_previous_response: false
     rules:

builtins/en/pieces/e2e-test.yaml

@@ -22,7 +22,7 @@ loop_monitors:
         is healthy (making progress) or unproductive (repeating the same issues).
 
         **Reports to reference:**
-        - AI Review results: {report:04-ai-review.md}
+        - AI Review results: {report:ai-review.md}
 
         **Judgment criteria:**
         - Are new issues being found/fixed in each cycle?
@@ -41,13 +41,15 @@ movements:
     knowledge:
       - architecture
       - backend
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Test plan complete
         next: implement_test
@@ -62,7 +64,7 @@ movements:
     instruction: plan-e2e-test
     output_contracts:
       report:
-        - name: 00-test-plan.md
+        - name: test-plan.md
           format: test-plan
   - name: implement_test
     edit: true
@@ -74,15 +76,17 @@ movements:
     knowledge:
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     rules:
       - condition: Test implementation complete
@@ -108,12 +112,14 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     rules:
       - condition: No AI-specific issues
         next: review_test
@@ -122,7 +128,7 @@ movements:
     instruction: ai-review
     output_contracts:
       report:
-        - name: 04-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -134,15 +140,17 @@ movements:
     knowledge:
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -157,10 +165,12 @@ movements:
     edit: false
     persona: architecture-reviewer
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
@@ -173,12 +183,14 @@ movements:
     policy:
       - review
       - qa
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     rules:
       - condition: approved
         next: supervise
@@ -187,7 +199,7 @@ movements:
     instruction: review-test
     output_contracts:
       report:
-        - name: 05-qa-review.md
+        - name: qa-review.md
           format: qa-review
   - name: fix
     edit: true
@@ -199,15 +211,17 @@ movements:
     knowledge:
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -220,13 +234,15 @@ movements:
     edit: false
     persona: supervisor
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     pass_previous_response: false
     rules:
       - condition: All checks passed

builtins/en/pieces/frontend-mini.yaml

@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 20
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix_both
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: fix_both
+        - condition: unproductive (same findings repeating)
+          next: supervise_fix
 movements:
   - name: plan
     edit: false
@@ -16,13 +29,15 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Requirements are clear and implementation is possible
         next: implement
@@ -33,7 +48,7 @@ movements:
     instruction: plan
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -45,15 +60,17 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     instruction: implement
     rules:
@@ -79,19 +96,21 @@ movements:
         policy:
           - review
           - ai-antipattern
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         instruction: review-ai
         rules:
           - condition: No AI-specific issues
           - condition: AI-specific issues found
         output_contracts:
           report:
-            - name: 03-ai-review.md
+            - name: ai-review.md
               format: ai-review
       - name: supervise
         edit: false
@@ -101,13 +120,15 @@ movements:
           - frontend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Bash
+              - Glob
-          - WebSearch
+              - Grep
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         instruction: supervise
         rules:
           - condition: All checks passed
@@ -140,14 +161,16 @@ movements:
           - frontend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: AI Reviewer's issues fixed
@@ -164,14 +187,16 @@ movements:
           - frontend
           - security
           - architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - Edit
+              - Glob
-          - Bash
+              - Grep
-          - WebSearch
+              - Edit
-          - WebFetch
+              - Bash
+              - WebSearch
+              - WebFetch
         required_permission_mode: edit
         rules:
           - condition: Supervisor's issues fixed
@@ -192,15 +217,17 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -221,15 +248,17 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:

builtins/en/pieces/frontend-review-fix.yaml

@@ -0,0 +1,232 @@
+name: frontend-review-fix
+description: Frontend-focused review + fix loop (structure, modularization, component design, 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-reviewers-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
+    provider_options:
+      claude:
+        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
+          - frontend
+        provider_options:
+          claude:
+            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: frontend-review
+        edit: false
+        persona: frontend-reviewer
+        policy: review
+        knowledge: frontend
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        instruction: review-frontend
+        output_contracts:
+          report:
+            - name: frontend-review.md
+              format: frontend-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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:
+      - frontend
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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
+    provider_options:
+      claude:
+        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:
+      - frontend
+      - security
+      - architecture
+    provider_options:
+      claude:
+        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

builtins/en/pieces/frontend-review.yaml

@@ -0,0 +1,158 @@
+name: frontend-review
+description: Frontend-focused review (structure, modularization, component design, 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
+    provider_options:
+      claude:
+        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
+          - frontend
+        provider_options:
+          claude:
+            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: frontend-review
+        edit: false
+        persona: frontend-reviewer
+        policy: review
+        knowledge: frontend
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        instruction: review-frontend
+        output_contracts:
+          report:
+            - name: frontend-review.md
+              format: frontend-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            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
+        provider_options:
+          claude:
+            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
+    provider_options:
+      claude:
+        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

builtins/en/pieces/frontend.yaml

@@ -8,6 +8,19 @@ piece_config:
       network_access: true
 max_movements: 30
 initial_movement: plan
+loop_monitors:
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: unproductive (same findings repeating)
+          next: supervise
 movements:
   - name: plan
     edit: false
@@ -15,13 +28,15 @@ movements:
     knowledge:
       - frontend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: plan
     rules:
       - condition: Task analysis and planning is complete
@@ -30,7 +45,7 @@ movements:
         next: ABORT
     output_contracts:
       report:
-        - name: 00-plan.md
+        - name: plan.md
           format: plan
   - name: implement
     edit: true
@@ -43,15 +58,17 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: implement
     rules:
       - condition: Implementation is complete
@@ -76,12 +93,14 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: ai-review
     rules:
       - condition: No AI-specific issues found
@@ -90,7 +109,7 @@ movements:
         next: ai_fix
     output_contracts:
       report:
-        - name: 03-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -103,15 +122,17 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: ai-fix
     pass_previous_response: false
     rules:
@@ -125,10 +146,12 @@ movements:
     edit: false
     persona: architecture-reviewer
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
@@ -144,57 +167,63 @@ movements:
         knowledge:
           - architecture
           - frontend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-arch
         output_contracts:
           report:
-            - name: 04-architect-review.md
+            - name: architect-review.md
               format: architecture-review
       - name: frontend-review
         edit: false
         persona: frontend-reviewer
         policy: review
         knowledge: frontend
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-frontend
         output_contracts:
           report:
-            - name: 05-frontend-review.md
+            - name: frontend-review.md
               format: frontend-review
       - name: security-review
         edit: false
         persona: security-reviewer
         policy: review
         knowledge: security
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-security
         output_contracts:
           report:
-            - name: 06-security-review.md
+            - name: security-review.md
               format: security-review
       - name: qa-review
         edit: false
@@ -202,19 +231,21 @@ movements:
         policy:
           - review
           - qa
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
+              - WebSearch
+              - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
         instruction: review-qa
         output_contracts:
           report:
-            - name: 07-qa-review.md
+            - name: qa-review.md
               format: qa-review
     rules:
       - condition: all("approved")
@@ -231,15 +262,17 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -250,14 +283,16 @@ movements:
     instruction: fix
   - name: supervise
     edit: false
-    persona: expert-supervisor
+    persona: dual-supervisor
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     instruction: supervise
     pass_previous_response: false
     rules:
@@ -282,15 +317,17 @@ movements:
       - frontend
       - security
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     instruction: fix-supervisor
     pass_previous_response: false
     rules:

builtins/en/pieces/magi.yaml

@@ -2,6 +2,13 @@ name: magi
 description: MAGI Deliberation System - Analyze from 3 perspectives and decide by majority
 piece_config:
   provider_options:
+    claude:
+      allowed_tools:
+        - Read
+        - Glob
+        - Grep
+        - WebSearch
+        - WebFetch
     codex:
       network_access: true
     opencode:
@@ -11,12 +18,6 @@ initial_movement: melchior
 movements:
   - name: melchior
     persona: melchior
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
     instruction_template: |
       # MAGI System Initiated
 
@@ -47,12 +48,6 @@ movements:
         next: balthasar
   - name: balthasar
     persona: balthasar
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
     instruction_template: |
       # MAGI System Continuing
 
@@ -87,12 +82,6 @@ movements:
         next: casper
   - name: casper
     persona: casper
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
     instruction_template: |
       # MAGI System Final Deliberation
 

builtins/en/pieces/passthrough.yaml

@@ -1,43 +0,0 @@
-name: passthrough
-description: Single-agent thin wrapper. Pass task directly to coder as-is.
-piece_config:
-  provider_options:
-    codex:
-      network_access: true
-    opencode:
-      network_access: true
-max_movements: 10
-initial_movement: execute
-movements:
-  - name: execute
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    rules:
-      - condition: Task complete
-        next: COMPLETE
-      - condition: Cannot proceed
-        next: ABORT
-      - condition: User input required
-        next: execute
-        requires_user_input: true
-        interactive_only: true
-    instruction_template: |
-      Do the task.
-    output_contracts:
-      report:
-        - name: summary.md
-          format: summary
-          use_judge: false

builtins/en/pieces/research.yaml

@@ -2,6 +2,13 @@ name: research
 description: Research piece - autonomously executes research without asking questions
 piece_config:
   provider_options:
+    claude:
+      allowed_tools:
+        - Read
+        - Glob
+        - Grep
+        - WebSearch
+        - WebFetch
     codex:
       network_access: true
     opencode:
@@ -14,12 +21,6 @@ movements:
     policy: research
     knowledge: research
     instruction: research-plan
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
     rules:
       - condition: Planning is complete
         next: dig
@@ -30,12 +31,6 @@ movements:
     policy: research
     knowledge: research
     instruction: research-dig
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
     rules:
       - condition: Research is complete
         next: supervise
@@ -46,12 +41,6 @@ movements:
     policy: research
     knowledge: research
     instruction: research-supervise
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
     rules:
       - condition: Research results adequately answer the original request
         next: COMPLETE

builtins/en/pieces/review-fix-minimal.yaml

@@ -1,190 +0,0 @@
-name: review-fix-minimal
-description: Review and fix piece for existing code (starts with review, no implementation)
-piece_config:
-  provider_options:
-    codex:
-      network_access: true
-    opencode:
-      network_access: true
-max_movements: 20
-initial_movement: reviewers
-movements:
-  - name: implement
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    instruction: implement
-    rules:
-      - condition: Implementation complete
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: ABORT
-      - condition: User input required because there are items to confirm with the user
-        next: implement
-        requires_user_input: true
-        interactive_only: true
-    output_contracts:
-      report:
-        - name: coder-scope.md
-          format: coder-scope
-        - name: coder-decisions.md
-          format: coder-decisions
-  - name: reviewers
-    parallel:
-      - name: ai_review
-        edit: false
-        persona: ai-antipattern-reviewer
-        policy:
-          - review
-          - ai-antipattern
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - WebSearch
-          - WebFetch
-        instruction: review-ai
-        rules:
-          - condition: No AI-specific issues
-          - condition: AI-specific issues found
-        output_contracts:
-          report:
-            - name: 03-ai-review.md
-              format: ai-review
-      - name: supervise
-        edit: false
-        persona: supervisor
-        policy: review
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Bash
-          - WebSearch
-          - WebFetch
-        instruction: supervise
-        rules:
-          - condition: All checks passed
-          - condition: Requirements unmet, tests failing
-        output_contracts:
-          report:
-            - name: supervisor-validation.md
-              format: supervisor-validation
-            - name: summary.md
-              format: summary
-              use_judge: false
-    rules:
-      - condition: all("No AI-specific issues", "All checks passed")
-        next: COMPLETE
-      - condition: all("AI-specific issues found", "Requirements unmet, tests failing")
-        next: fix_both
-      - condition: any("AI-specific issues found")
-        next: ai_fix
-      - condition: any("Requirements unmet, tests failing")
-        next: supervise_fix
-  - name: fix_both
-    parallel:
-      - name: ai_fix_parallel
-        edit: true
-        persona: coder
-        policy:
-          - coding
-          - testing
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Edit
-          - Bash
-          - WebSearch
-          - WebFetch
-        required_permission_mode: edit
-        rules:
-          - condition: AI Reviewer's issues fixed
-          - condition: No fix needed (verified target files/spec)
-          - condition: Cannot proceed, insufficient info
-        instruction: ai-fix
-      - name: supervise_fix_parallel
-        edit: true
-        persona: coder
-        policy:
-          - coding
-          - testing
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Edit
-          - Bash
-          - WebSearch
-          - WebFetch
-        required_permission_mode: edit
-        rules:
-          - condition: Supervisor's issues fixed
-          - condition: Cannot proceed, insufficient info
-        instruction: fix-supervisor
-    rules:
-      - condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
-        next: reviewers
-      - condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
-        next: implement
-  - name: ai_fix
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    pass_previous_response: false
-    rules:
-      - condition: AI Reviewer's issues fixed
-        next: reviewers
-      - condition: No fix needed (verified target files/spec)
-        next: implement
-      - condition: Cannot proceed, insufficient info
-        next: implement
-    instruction: ai-fix
-  - name: supervise_fix
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    pass_previous_response: false
-    rules:
-      - condition: Supervisor's issues fixed
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: implement
-    instruction: fix-supervisor

builtins/en/pieces/review-fix.yaml

@@ -0,0 +1,259 @@
+name: review-fix
+description: Multi-perspective review + fix loop (architecture, security, QA, testing, requirements — 5 parallel reviewers with iterative fixes)
+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-reviewers-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
+    provider_options:
+      claude:
+        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: Cannot identify review target, insufficient info
+        next: ABORT
+        appendix: |
+          Clarifications needed:
+          - {Question 1}
+          - {Question 2}
+
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        edit: false
+        persona: architecture-reviewer
+        policy: review
+        knowledge: architecture
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-arch
+        output_contracts:
+          report:
+            - name: architecture-review.md
+              format: architecture-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - 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
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-qa
+        output_contracts:
+          report:
+            - name: qa-review.md
+              format: qa-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: testing-review
+        edit: false
+        persona: testing-reviewer
+        policy:
+          - review
+          - testing
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-test
+        output_contracts:
+          report:
+            - name: testing-review.md
+              format: testing-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: requirements-review
+        edit: false
+        persona: requirements-reviewer
+        policy: review
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-requirements
+        output_contracts:
+          report:
+            - name: requirements-review.md
+              format: requirements-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:
+      - architecture
+      - security
+    provider_options:
+      claude:
+        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: supervisor
+    policy: review
+    provider_options:
+      claude:
+        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:
+      - architecture
+      - security
+    provider_options:
+      claude:
+        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

builtins/en/pieces/review.yaml

@@ -1,5 +1,5 @@
-name: review-only
+name: review
-description: Review-only piece - reviews code without making edits
+description: Multi-perspective Code Review - reviews changes in parallel from 5 perspectives and outputs consolidated results
 piece_config:
   provider_options:
     codex:
@@ -7,42 +7,36 @@ piece_config:
     opencode:
       network_access: true
 max_movements: 10
-initial_movement: plan
+initial_movement: gather
+
 movements:
-  - name: plan
+  - name: gather
     edit: false
     persona: planner
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    instruction: gather-review
+    output_contracts:
+      report:
+        - name: review-target.md
+          format: review-gather
     rules:
-      - condition: Review scope is clear
+      - condition: Review target information gathered
         next: reviewers
-      - condition: User is asking a question (not a review task)
+      - condition: Cannot identify review target, insufficient info
-        next: COMPLETE
-      - condition: Requirements unclear, insufficient info
         next: ABORT
         appendix: |
           Clarifications needed:
           - {Question 1}
           - {Question 2}
-    instruction_template: |
-      ## Previous Response (when returned from supervise)
-      {previous_response}
 
-      Analyze the review request and create a review plan.
-
-      **This is a review-only piece.** No code edits will be made.
-      Focus on:
-      1. Identify which files/modules to review
-      2. Determine review focus areas (architecture, security, AI patterns, etc.)
-      3. Note any specific concerns mentioned in the request
-
-      **If a PR number is mentioned** (e.g., "PR #42"), include it in your plan
-      so reviewers can focus on the PR's changed files.
   - name: reviewers
     parallel:
       - name: arch-review
@@ -50,82 +44,139 @@ movements:
         persona: architecture-reviewer
         policy: review
         knowledge: architecture
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
-        rules:
+              - Bash
-          - condition: approved
+              - WebSearch
-          - condition: needs_fix
+              - WebFetch
         instruction: review-arch
         output_contracts:
           report:
-            - name: 01-architect-review.md
+            - name: architecture-review.md
               format: architecture-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
       - name: security-review
         edit: false
         persona: security-reviewer
         policy: review
         knowledge: security
-        allowed_tools:
+        provider_options:
-          - Read
+          claude:
-          - Glob
+            allowed_tools:
-          - Grep
+              - Read
-          - WebSearch
+              - Glob
-          - WebFetch
+              - Grep
-        rules:
+              - Bash
-          - condition: approved
+              - WebSearch
-          - condition: needs_fix
+              - WebFetch
         instruction: review-security
         output_contracts:
           report:
-            - name: 02-security-review.md
+            - name: security-review.md
               format: security-review
-      - name: ai-review
-        edit: false
-        persona: ai-antipattern-reviewer
-        policy:
-          - review
-          - ai-antipattern
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - WebSearch
-          - WebFetch
         rules:
           - condition: approved
           - condition: needs_fix
-        instruction: review-ai
+
+      - name: qa-review
+        edit: false
+        persona: qa-reviewer
+        policy:
+          - review
+          - qa
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-qa
         output_contracts:
           report:
-            - name: 03-ai-review.md
+            - name: qa-review.md
-              format: ai-review
+              format: qa-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: testing-review
+        edit: false
+        persona: testing-reviewer
+        policy:
+          - review
+          - testing
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-test
+        output_contracts:
+          report:
+            - name: testing-review.md
+              format: testing-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: requirements-review
+        edit: false
+        persona: requirements-reviewer
+        policy: review
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-requirements
+        output_contracts:
+          report:
+            - name: requirements-review.md
+              format: requirements-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:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     pass_previous_response: false
     rules:
-      - condition: approved, PR comment requested
+      - condition: Review synthesis complete
-        next: pr-comment
-      - condition: approved
         next: COMPLETE
-      - condition: rejected
-        next: ABORT
     instruction_template: |
       ## Review Results
       {previous_response}
@@ -135,13 +186,14 @@ movements:
 
       **Tasks:**
       1. Read all review reports in the Report Directory
-      2. Synthesize findings from architecture, security, and AI reviews
+         - `00-review-target.md` (Review target information)
+         - `01-architecture-review.md` (Architecture review)
+         - `02-security-review.md` (Security review)
+         - `03-qa-review.md` (QA review)
+         - `04-testing-review.md` (Testing review)
+         - `05-requirements-review.md` (Requirements review)
+      2. Synthesize the 5 review results
       3. Produce a consolidated review summary with overall verdict
-      4. Determine routing:
-         - If the task mentions posting to a PR (e.g., "post comments to PR", "comment on PR"),
-           route to `pr-comment` movement (condition: "approved, PR comment requested")
-         - If local review only, route to COMPLETE (condition: "approved")
-         - If critical issues found, route to ABORT (condition: "rejected")
 
       **Review Summary output contract:**
       ```markdown
@@ -157,7 +209,9 @@ movements:
       |--------|--------|--------------|
       | Architecture | APPROVE/REJECT | {Brief finding} |
       | Security | APPROVE/REJECT | {Brief finding} |
-      | AI Antipattern | APPROVE/REJECT | {Brief finding} |
+      | QA | APPROVE/REJECT | {Brief finding} |
+      | Testing | APPROVE/REJECT | {Brief finding} |
+      | Requirements | APPROVE/REJECT | {Brief finding} |
 
       ## Issues Requiring Attention
       | # | Severity | Source | Location | Issue |
@@ -177,14 +231,16 @@ movements:
             ## Overall Verdict: APPROVE / REJECT
 
             ## Summary
-            {Integrate all review results in 2-3 sentences}
+            {2-3 sentences consolidating all review results}
 
             ## Review Results
             | Review | Result | Key Findings |
-            |--------|--------|-------------|
+            |--------|--------|--------------|
             | Architecture | APPROVE/REJECT | {Overview} |
             | Security | APPROVE/REJECT | {Overview} |
-            | AI Anti-pattern | APPROVE/REJECT | {Overview} |
+            | QA | APPROVE/REJECT | {Overview} |
+            | Testing | APPROVE/REJECT | {Overview} |
+            | Requirements | APPROVE/REJECT | {Overview} |
 
             ## Current Iteration Findings (new)
             | # | finding_id | Severity | Source | Location | Issue | Fix Suggestion |
@@ -208,53 +264,3 @@ movements:
             - REJECT is valid only when at least one finding exists in `new` or `persists`
             - Findings without `finding_id` are invalid
             ```
-  - name: pr-comment
-    edit: false
-    persona: pr-commenter
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Bash
-    rules:
-      - condition: Comments posted
-        next: COMPLETE
-      - condition: Failed to post comments
-        next: COMPLETE
-    instruction_template: |
-      ## Review Summary
-      {previous_response}
-
-      Post the review results to the PR as comments.
-
-      **Procedure:**
-      1. Extract the PR number from the task description
-      2. Read all review reports in the Report Directory:
-         - `01-architect-review.md` (Architecture review)
-         - `02-security-review.md` (Security review)
-         - `03-ai-review.md` (AI antipattern review)
-         - `review-summary.md` (Consolidated summary)
-      3. Filter findings by severity and post inline comments for Critical/High/Medium
-      4. Post a summary comment with the following format:
-
-      ```
-      ## Automated Review Summary
-
-      {Overall verdict and summary from review-summary.md}
-
-      ### Review Results
-      | Review | Result |
-      |--------|--------|
-      | Architecture | {result} |
-      | Security | {result} |
-      | AI Antipattern | {result} |
-
-      ### Key Findings
-      {Bulleted list of important findings}
-
-      ### Improvement Suggestions
-      {Consolidated suggestions}
-
-      ---
-      *Generated by [takt](https://github.com/toruticas/takt) review-only piece*
-      ```

builtins/en/pieces/structural-reform.yaml

@@ -1,488 +0,0 @@
-name: structural-reform
-description: Full project review and structural reform - iterative codebase restructuring with staged file splits
-piece_config:
-  provider_options:
-    codex:
-      network_access: true
-    opencode:
-      network_access: true
-max_movements: 50
-initial_movement: review
-loop_monitors:
-  - cycle:
-      - implement
-      - fix
-    threshold: 3
-    judge:
-      persona: supervisor
-      instruction_template: |
-        The implement -> reviewers -> fix loop has repeated {cycle_count} times for the current reform target.
-
-        Review the reports from each cycle and determine whether this loop
-        is making progress or repeating the same issues.
-
-        **Reports to reference:**
-        - Architect review: {report:04-architect-review.md}
-        - QA review: {report:05-qa-review.md}
-
-        **Judgment criteria:**
-        - Are review findings being addressed in each fix cycle?
-        - Are the same issues recurring without resolution?
-        - Is the implementation converging toward approval?
-      rules:
-        - condition: Healthy (making progress toward approval)
-          next: implement
-        - condition: Unproductive (same issues recurring, no convergence)
-          next: next_target
-movements:
-  - name: review
-    edit: false
-    persona: architecture-reviewer
-    policy: review
-    knowledge:
-      - architecture
-      - backend
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
-    instruction_template: |
-      ## Piece Status
-      - Iteration: {iteration}/{max_movements} (piece-wide)
-      - Movement Iteration: {movement_iteration} (times this movement has run)
-      - Movement: review (full project review)
-
-      ## User Request
-      {task}
-
-      ## Instructions
-      Conduct a comprehensive structural review of the entire project codebase.
-
-      **Focus areas:**
-      1. **God Classes/Functions**: Files exceeding 300 lines, classes with multiple responsibilities
-      2. **Coupling**: Circular dependencies, tight coupling between modules
-      3. **Cohesion**: Low-cohesion modules mixing unrelated concerns
-      4. **Testability**: Untestable code due to tight coupling or side effects
-      5. **Layer violations**: Wrong dependency directions, domain logic in adapters
-      6. **DRY violations**: Duplicated logic across 3+ locations
-
-      **For each issue found, report:**
-      - File path and line count
-      - Problem category (God Class, Low Cohesion, etc.)
-      - Severity (Critical / High / Medium)
-      - Specific responsibilities that should be separated
-      - Dependencies that would be affected by splitting
-
-      **Output format:**
-
-      ```markdown
-      # Full Project Structural Review
-
-      ## Summary
-      - Total files reviewed: N
-      - Issues found: N (Critical: N, High: N, Medium: N)
-
-      ## Critical Issues
-
-      ### 1. {File path} ({line count} lines)
-      - **Problem**: {category}
-      - **Severity**: Critical
-      - **Responsibilities found**:
-        1. {responsibility 1}
-        2. {responsibility 2}
-      - **Proposed split**:
-        - `{new-file-1}.ts`: {responsibility}
-        - `{new-file-2}.ts`: {responsibility}
-      - **Affected dependents**: {files that import this module}
-
-      ## High Priority Issues
-      ...
-
-      ## Medium Priority Issues
-      ...
-
-      ## Dependency Graph Concerns
-      - {circular dependencies, layering violations}
-
-      ## Recommended Reform Order
-      1. {file} - {reason for priority}
-      2. {file} - {reason for priority}
-      ```
-    rules:
-      - condition: Full review is complete with findings
-        next: plan_reform
-      - condition: No structural issues found
-        next: COMPLETE
-    output_contracts:
-      report:
-        - name: full-review.md
-          format: |
-            ```markdown
-            # Full Project Structural Review
-
-            ## Summary
-            - Total files reviewed: {N}
-            - Issues found: {N} (Critical: {N}, High: {N}, Medium: {N})
-
-            ## Critical Issues
-
-            ### 1. {File path} ({line count} lines)
-            - **Problem**: {category}
-            - **Severity**: Critical
-            - **Responsibilities found**:
-              1. {responsibility 1}
-              2. {responsibility 2}
-            - **Proposed split**:
-              - `{new-file-1}.ts`: {responsibility}
-              - `{new-file-2}.ts`: {responsibility}
-            - **Affected dependents**: {files that import this module}
-
-            ## High Priority Issues
-            - {Issue}
-
-            ## Medium Priority Issues
-            - {Issue}
-
-            ## Dependency Graph Concerns
-            - {circular dependencies, layering violations}
-
-            ## Recommended Reform Order
-            1. {file} - {reason for priority}
-            2. {file} - {reason for priority}
-            ```
-  - name: plan_reform
-    edit: false
-    persona: planner
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Bash
-      - WebSearch
-      - WebFetch
-    instruction_template: |
-      ## Piece Status
-      - Iteration: {iteration}/{max_movements} (piece-wide)
-      - Movement Iteration: {movement_iteration} (times this movement has run)
-      - Movement: plan_reform (reform plan creation)
-
-      ## User Request
-      {task}
-
-      ## Full Review Results
-      {previous_response}
-
-      ## Additional User Inputs
-      {user_inputs}
-
-      ## Instructions
-      Based on the full review results, create a concrete reform execution plan.
-
-      **Planning principles:**
-      - One file split per iteration (keep changes manageable)
-      - Order by dependency: split leaf nodes first, then work inward
-      - Each split must leave tests and build passing
-      - No backward compatibility concerns (per user instruction)
-
-      **For each reform target, specify:**
-      1. Target file and current line count
-      2. Proposed new files with responsibilities
-      3. Expected changes to imports in dependent files
-      4. Test strategy (new tests needed, existing tests to update)
-      5. Risk assessment (what could break)
-
-      **Output format:**
-
-      ```markdown
-      # Structural Reform Plan
-
-      ## Reform Targets (ordered by execution priority)
-
-      ### Target 1: {file path}
-      - **Current state**: {line count} lines, {N} responsibilities
-      - **Proposed split**:
-        | New file | Responsibility | Estimated lines |
-        |----------|---------------|-----------------|
-        | `{path}` | {responsibility} | ~{N} |
-      - **Dependent files**: {list of files that import this}
-      - **Test plan**: {what tests to add/update}
-      - **Risk**: {Low/Medium/High} - {description}
-
-      ### Target 2: {file path}
-      ...
-
-      ## Execution Order Rationale
-      {Why this order minimizes risk and dependency conflicts}
-
-      ## Success Criteria
-      - All tests pass after each split
-      - Build succeeds after each split
-      - No file exceeds 300 lines
-      - Each file has single responsibility
-      ```
-    rules:
-      - condition: Reform plan is complete and ready to execute
-        next: implement
-      - condition: No actionable reforms identified
-        next: COMPLETE
-      - condition: Requirements unclear, need user input
-        next: ABORT
-        appendix: |
-          Clarifications needed:
-          - {Question 1}
-          - {Question 2}
-    output_contracts:
-      report:
-        - name: 01-reform-plan.md
-          format: plan
-  - name: implement
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    session: refresh
-    knowledge:
-      - backend
-      - architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    instruction: implement
-    rules:
-      - condition: Implementation complete
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: reviewers
-      - condition: User input required
-        next: implement
-        requires_user_input: true
-        interactive_only: true
-    output_contracts:
-      report:
-        - name: coder-scope.md
-          format: coder-scope
-        - name: coder-decisions.md
-          format: coder-decisions
-  - name: reviewers
-    parallel:
-      - name: arch-review
-        edit: false
-        persona: architecture-reviewer
-        policy: review
-        knowledge:
-          - architecture
-          - backend
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - WebSearch
-          - WebFetch
-        rules:
-          - condition: approved
-          - condition: needs_fix
-        instruction: review-arch
-        output_contracts:
-          report:
-            - name: 04-architect-review.md
-              format: architecture-review
-      - name: qa-review
-        edit: false
-        persona: qa-reviewer
-        policy:
-          - review
-          - qa
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - WebSearch
-          - WebFetch
-        rules:
-          - condition: approved
-          - condition: needs_fix
-        instruction: review-qa
-        output_contracts:
-          report:
-            - name: 05-qa-review.md
-              format: qa-review
-    rules:
-      - condition: all("approved")
-        next: verify
-      - condition: any("needs_fix")
-        next: fix
-  - name: fix
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge:
-      - backend
-      - architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
-    required_permission_mode: edit
-    pass_previous_response: false
-    rules:
-      - condition: Fix complete
-        next: reviewers
-      - condition: Cannot proceed, insufficient info
-        next: plan_reform
-    instruction: fix
-  - name: verify
-    edit: false
-    persona: supervisor
-    policy: review
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Bash
-      - WebSearch
-      - WebFetch
-    instruction_template: |
-      ## Piece Status
-      - Iteration: {iteration}/{max_movements} (piece-wide)
-      - Movement Iteration: {movement_iteration} (times this movement has run)
-      - Movement: verify (build and test verification)
-
-      ## Instructions
-      Verify that the current reform step has been completed successfully.
-
-      **Verification checklist:**
-      1. **Build**: Run the build command and confirm it passes
-      2. **Tests**: Run the test suite and confirm all tests pass
-      3. **File sizes**: Confirm no new file exceeds 300 lines
-      4. **Single responsibility**: Confirm each new file has a clear, single purpose
-      5. **Import consistency**: Confirm all imports are updated correctly
-
-      **Report format:**
-
-      ```markdown
-      # Verification Results
-
-      ## Result: PASS / FAIL
-
-      | Check | Status | Details |
-      |-------|--------|---------|
-      | Build | PASS/FAIL | {output summary} |
-      | Tests | PASS/FAIL | {N passed, N failed} |
-      | File sizes | PASS/FAIL | {any file > 300 lines} |
-      | Single responsibility | PASS/FAIL | {assessment} |
-      | Import consistency | PASS/FAIL | {any broken imports} |
-
-      ## Issues (if FAIL)
-      1. {issue description}
-      ```
-    rules:
-      - condition: All verifications passed
-        next: next_target
-      - condition: Verification failed
-        next: fix
-    output_contracts:
-      report:
-        - name: 06-verification.md
-          format: validation
-  - name: next_target
-    edit: false
-    persona: planner
-    knowledge: architecture
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Bash
-      - WebSearch
-      - WebFetch
-    instruction_template: |
-      ## Piece Status
-      - Iteration: {iteration}/{max_movements} (piece-wide)
-      - Movement Iteration: {movement_iteration} (times this movement has run)
-      - Movement: next_target (progress check and next target selection)
-
-      ## Original Reform Plan
-      {report:01-reform-plan.md}
-
-      ## Latest Verification
-      {previous_response}
-
-      ## Instructions
-      Assess the progress of the structural reform and determine the next action.
-
-      **Steps:**
-      1. Review the reform plan and identify which targets have been completed
-      2. Check the current codebase state against the plan
-      3. Determine if there are remaining reform targets
-
-      **Output format:**
-
-      ```markdown
-      # Reform Progress
-
-      ## Completed Targets
-      | # | Target | Status |
-      |---|--------|--------|
-      | 1 | {file} | Completed |
-      | 2 | {file} | Completed |
-
-      ## Remaining Targets
-      | # | Target | Priority |
-      |---|--------|----------|
-      | 3 | {file} | Next |
-      | 4 | {file} | Pending |
-
-      ## Next Action
-      - **Target**: {next file to reform}
-      - **Plan**: {brief description of the split}
-
-      ## Overall Progress
-      {N}/{total} targets completed. Estimated remaining iterations: {N}
-      ```
-    rules:
-      - condition: More reform targets remain
-        next: implement
-      - condition: All reform targets completed
-        next: COMPLETE
-    output_contracts:
-      report:
-        - name: progress.md
-          format: |
-            ```markdown
-            # Reform Progress
-
-            ## Completed Targets
-            | # | Target | Status |
-            |---|--------|--------|
-            | 1 | {file} | Completed |
-
-            ## Remaining Targets
-            | # | Target | Priority |
-            |---|--------|----------|
-            | 2 | {file} | Next |
-
-            ## Next Action
-            - **Target**: {next file to reform}
-            - **Plan**: {brief description of the split}
-
-            ## Overall Progress
-            {N}/{total} targets completed. Estimated remaining iterations: {N}
-            ```

builtins/en/pieces/takt-default-review-fix.yaml

@@ -0,0 +1,235 @@
+name: takt-default-review-fix
+description: "TAKT development code review + fix loop (5 parallel reviewers: architecture, security, QA, testing, requirements — with iterative fixes)"
+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-reviewers-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
+    provider_options:
+      claude:
+        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: Cannot identify review target, insufficient info
+        next: ABORT
+        appendix: |
+          Clarifications needed:
+          - {Question 1}
+          - {Question 2}
+
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        edit: false
+        persona: architecture-reviewer
+        policy: review
+        knowledge:
+          - architecture
+          - takt
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-arch
+        output_contracts:
+          report:
+            - name: architecture-review.md
+              format: architecture-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - 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
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-qa
+        output_contracts:
+          report:
+            - name: qa-review.md
+              format: qa-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: testing-review
+        edit: false
+        persona: testing-reviewer
+        policy:
+          - review
+          - testing
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-test
+        output_contracts:
+          report:
+            - name: testing-review.md
+              format: testing-review
+        rules:
+          - condition: approved
+          - condition: needs_fix
+
+      - name: requirements-review
+        edit: false
+        persona: requirements-reviewer
+        policy: review
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-requirements
+        output_contracts:
+          report:
+            - name: requirements-review.md
+              format: requirements-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:
+      - takt
+      - architecture
+      - security
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    instruction: fix
+    rules:
+      - condition: Fix complete
+        next: reviewers
+      - condition: Cannot proceed, insufficient info
+        next: ABORT
+
+  - name: supervise
+    edit: false
+    persona: supervisor
+    policy: review
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    instruction: supervise
+    pass_previous_response: false
+    rules:
+      - condition: All checks passed
+        next: COMPLETE
+      - condition: Requirements unmet, tests failing, build errors
+        next: ABORT
+    output_contracts:
+      report:
+        - name: supervisor-validation.md
+          format: supervisor-validation
+        - name: summary.md
+          format: summary
+          use_judge: false

builtins/en/pieces/takt-default-team-leader.yaml

@@ -0,0 +1,406 @@
+name: takt-default-team-leader
+description: TAKT development piece with team leader (plan → write tests → team-leader implement → AI antipattern review → 5-parallel review → fix → supervise → complete)
+piece_config:
+  provider_options:
+    codex:
+      network_access: true
+    opencode:
+      network_access: true
+max_movements: 30
+initial_movement: plan
+loop_monitors:
+  - cycle:
+      - ai_review
+      - ai_fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-ai-fix
+      rules:
+        - condition: Healthy (making progress)
+          next: ai_review
+        - condition: Unproductive (no improvement)
+          next: reviewers
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: Healthy (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: Unproductive (same findings repeating)
+          next: supervise
+movements:
+  - name: plan
+    edit: false
+    persona: planner
+    knowledge: architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    rules:
+      - condition: Requirements are clear and implementable
+        next: write_tests
+      - condition: User is asking a question (not an implementation task)
+        next: COMPLETE
+      - condition: Requirements unclear, insufficient info
+        next: ABORT
+        appendix: |
+          Clarifications needed:
+          - {Question 1}
+          - {Question 2}
+    instruction: plan
+    output_contracts:
+      report:
+        - name: plan.md
+          format: plan
+  - name: write_tests
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - takt
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    instruction: write-tests-first
+    rules:
+      - condition: Tests written successfully
+        next: implement
+      - condition: Cannot proceed because the test target is not implemented yet, so skip test writing
+        next: implement
+      - condition: Cannot proceed with test writing
+        next: ABORT
+      - condition: User input needed for clarification
+        next: write_tests
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: test-scope.md
+          format: coder-scope
+        - name: test-decisions.md
+          format: coder-decisions
+  - name: implement
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    session: refresh
+    knowledge:
+      - takt
+      - architecture
+      - task-decomposition
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    team_leader:
+      max_parts: 2
+      part_persona: coder
+      part_edit: true
+      part_permission_mode: edit
+      part_allowed_tools:
+        - Read
+        - Glob
+        - Grep
+        - Edit
+        - Write
+        - Bash
+        - WebSearch
+        - WebFetch
+    instruction: team-leader-implement
+    rules:
+      - condition: Implementation complete
+        next: ai_review
+      - condition: No implementation (report only)
+        next: ai_review
+      - condition: Cannot proceed, insufficient info
+        next: plan
+      - condition: User input required
+        next: implement
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: coder-scope.md
+          format: coder-scope
+        - name: coder-decisions.md
+          format: coder-decisions
+  - name: ai_review
+    edit: false
+    persona: ai-antipattern-reviewer
+    policy:
+      - review
+      - ai-antipattern
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+    rules:
+      - condition: No AI-specific issues
+        next: reviewers
+      - condition: AI-specific issues found
+        next: ai_fix
+    instruction: ai-review
+    output_contracts:
+      report:
+        - name: ai-review.md
+          format: ai-review
+  - name: ai_fix
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    session: refresh
+    knowledge:
+      - takt
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    rules:
+      - condition: AI issues fixed
+        next: ai_review
+      - condition: No fix needed (verified target files/spec)
+        next: ai_no_fix
+      - condition: Cannot proceed, insufficient info
+        next: ai_no_fix
+    instruction: ai-fix
+  - name: ai_no_fix
+    edit: false
+    persona: architecture-reviewer
+    policy: review
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+    rules:
+      - condition: ai_review's findings are valid (fix required)
+        next: ai_fix
+      - condition: ai_fix's judgment is valid (no fix needed)
+        next: reviewers
+    instruction: arbitrate
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        edit: false
+        persona: architecture-reviewer
+        policy: review
+        knowledge:
+          - architecture
+          - takt
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-arch
+        output_contracts:
+          report:
+            - name: architect-review.md
+              format: architecture-review
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-security
+        output_contracts:
+          report:
+            - name: security-review.md
+              format: security-review
+      - name: qa-review
+        edit: false
+        persona: qa-reviewer
+        policy:
+          - review
+          - qa
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-qa
+        output_contracts:
+          report:
+            - name: qa-review.md
+              format: qa-review
+      - name: testing-review
+        edit: false
+        persona: testing-reviewer
+        policy:
+          - review
+          - testing
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-test
+        output_contracts:
+          report:
+            - name: testing-review.md
+              format: testing-review
+      - name: requirements-review
+        edit: false
+        persona: requirements-reviewer
+        policy: review
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-requirements
+        output_contracts:
+          report:
+            - name: requirements-review.md
+              format: requirements-review
+    rules:
+      - condition: all("approved")
+        next: supervise
+      - condition: any("needs_fix")
+        next: fix
+  - name: fix
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - takt
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    rules:
+      - condition: Fix complete
+        next: reviewers
+      - condition: Cannot proceed, insufficient info
+        next: plan
+    instruction: fix
+  - name: supervise
+    edit: false
+    persona: supervisor
+    policy: review
+    knowledge: architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    pass_previous_response: false
+    rules:
+      - condition: All checks passed
+        next: COMPLETE
+      - condition: Requirements unmet, tests failing, build errors
+        next: plan
+    instruction: supervise
+    output_contracts:
+      report:
+        - name: supervisor-validation.md
+          format: supervisor-validation
+        - name: summary.md
+          format: summary
+          use_judge: false

builtins/en/pieces/takt-default.yaml

@@ -0,0 +1,402 @@
+name: takt-default
+description: TAKT development piece (plan → write tests → implement → AI antipattern review → 5-parallel review → fix → supervise → complete)
+piece_config:
+  provider_options:
+    codex:
+      network_access: true
+    opencode:
+      network_access: true
+max_movements: 30
+initial_movement: plan
+loop_monitors:
+  - cycle:
+      - ai_review
+      - ai_fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: |
+        The ai_review ↔ ai_fix loop has repeated {cycle_count} times.
+
+        Review the reports from each cycle and determine whether this loop
+        is healthy (making progress) or unproductive (repeating the same issues).
+
+        **Reports to reference:**
+        - AI Review results: {report:ai-review.md}
+
+        **Judgment criteria:**
+        - Are new issues being found/fixed in each cycle?
+        - Are the same findings being repeated?
+        - Are fixes actually being applied?
+      rules:
+        - condition: Healthy (making progress)
+          next: ai_review
+        - condition: Unproductive (no improvement)
+          next: reviewers
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: loop-monitor-reviewers-fix
+      rules:
+        - condition: Healthy (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: Unproductive (same findings repeating)
+          next: supervise
+movements:
+  - name: plan
+    edit: false
+    persona: planner
+    knowledge: architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    rules:
+      - condition: Requirements are clear and implementable
+        next: write_tests
+      - condition: User is asking a question (not an implementation task)
+        next: COMPLETE
+      - condition: Requirements unclear, insufficient info
+        next: ABORT
+        appendix: |
+          Clarifications needed:
+          - {Question 1}
+          - {Question 2}
+    instruction: plan
+    output_contracts:
+      report:
+        - name: plan.md
+          format: plan
+  - name: write_tests
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - takt
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    instruction: write-tests-first
+    rules:
+      - condition: Tests written successfully
+        next: implement
+      - condition: Cannot proceed because the test target is not implemented yet, so skip test writing
+        next: implement
+      - condition: Cannot proceed with test writing
+        next: ABORT
+      - condition: User input needed for clarification
+        next: write_tests
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: test-scope.md
+          format: coder-scope
+        - name: test-decisions.md
+          format: coder-decisions
+  - name: implement
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    session: refresh
+    knowledge:
+      - takt
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    rules:
+      - condition: Implementation complete
+        next: ai_review
+      - condition: No implementation (report only)
+        next: ai_review
+      - condition: Cannot proceed, insufficient info
+        next: ai_review
+      - condition: User input required
+        next: implement
+        requires_user_input: true
+        interactive_only: true
+    instruction: implement-after-tests
+    output_contracts:
+      report:
+        - name: coder-scope.md
+          format: coder-scope
+        - name: coder-decisions.md
+          format: coder-decisions
+  - name: ai_review
+    edit: false
+    persona: ai-antipattern-reviewer
+    policy:
+      - review
+      - ai-antipattern
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+    rules:
+      - condition: No AI-specific issues
+        next: reviewers
+      - condition: AI-specific issues found
+        next: ai_fix
+    instruction: ai-review
+    output_contracts:
+      report:
+        - name: ai-review.md
+          format: ai-review
+  - name: ai_fix
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    session: refresh
+    knowledge:
+      - takt
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    rules:
+      - condition: AI issues fixed
+        next: ai_review
+      - condition: No fix needed (verified target files/spec)
+        next: ai_no_fix
+      - condition: Cannot proceed, insufficient info
+        next: ai_no_fix
+    instruction: ai-fix
+  - name: ai_no_fix
+    edit: false
+    persona: architecture-reviewer
+    policy: review
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+    rules:
+      - condition: ai_review's findings are valid (fix required)
+        next: ai_fix
+      - condition: ai_fix's judgment is valid (no fix needed)
+        next: reviewers
+    instruction: arbitrate
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        edit: false
+        persona: architecture-reviewer
+        policy: review
+        knowledge:
+          - architecture
+          - takt
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-arch
+        output_contracts:
+          report:
+            - name: architect-review.md
+              format: architecture-review
+      - name: security-review
+        edit: false
+        persona: security-reviewer
+        policy: review
+        knowledge: security
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-security
+        output_contracts:
+          report:
+            - name: security-review.md
+              format: security-review
+      - name: qa-review
+        edit: false
+        persona: qa-reviewer
+        policy:
+          - review
+          - qa
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-qa
+        output_contracts:
+          report:
+            - name: qa-review.md
+              format: qa-review
+      - name: testing-review
+        edit: false
+        persona: testing-reviewer
+        policy:
+          - review
+          - testing
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-test
+        output_contracts:
+          report:
+            - name: testing-review.md
+              format: testing-review
+      - name: requirements-review
+        edit: false
+        persona: requirements-reviewer
+        policy: review
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-requirements
+        output_contracts:
+          report:
+            - name: requirements-review.md
+              format: requirements-review
+    rules:
+      - condition: all("approved")
+        next: supervise
+      - condition: any("needs_fix")
+        next: fix
+  - name: fix
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - takt
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    rules:
+      - condition: Fix complete
+        next: reviewers
+      - condition: Cannot proceed, insufficient info
+        next: plan
+    instruction: fix
+  - name: supervise
+    edit: false
+    persona: supervisor
+    policy: review
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    pass_previous_response: false
+    rules:
+      - condition: All checks passed
+        next: COMPLETE
+      - condition: Requirements unmet, tests failing, build errors
+        next: plan
+    instruction: supervise
+    output_contracts:
+      report:
+        - name: supervisor-validation.md
+          format: supervisor-validation
+        - name: summary.md
+          format: summary
+          use_judge: false

builtins/en/pieces/terraform.yaml

@@ -0,0 +1,314 @@
+name: terraform
+description: Terraform IaC development piece (plan → implement → parallel review → supervisor validation → fix → complete)
+piece_config:
+  provider_options:
+    codex:
+      network_access: true
+    opencode:
+      network_access: true
+max_movements: 15
+initial_movement: plan
+movements:
+  - name: plan
+    edit: false
+    persona: planner
+    knowledge: terraform-aws
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    rules:
+      - condition: Requirements are clear and implementable
+        next: implement
+      - condition: User is asking a question (not an implementation task)
+        next: COMPLETE
+      - condition: Requirements are unclear or insufficient
+        next: ABORT
+    instruction: plan
+    output_contracts:
+      report:
+        - name: plan.md
+          format: plan
+  - name: implement
+    edit: true
+    persona: terraform-coder
+    policy:
+      - terraform
+    knowledge: terraform-aws
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: full
+    quality_gates:
+      - terraform fmt -check passes without errors
+      - terraform validate succeeds
+      - terraform plan is executable (no errors)
+    instruction: implement-terraform
+    rules:
+      - condition: Implementation is complete
+        next: reviewers
+      - condition: Cannot proceed with implementation
+        next: ABORT
+      - condition: User input needed for confirmation
+        next: implement
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: coder-scope.md
+          format: coder-scope
+        - name: coder-decisions.md
+          format: coder-decisions
+  - name: reviewers
+    parallel:
+      - name: tf_review
+        edit: false
+        persona: terraform-reviewer
+        policy:
+          - review
+          - terraform
+        knowledge: terraform-aws
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-terraform
+        rules:
+          - condition: Complies with Terraform conventions
+          - condition: Convention violations found
+        output_contracts:
+          report:
+            - name: terraform-review.md
+              format: terraform-review
+      - name: ai_review
+        edit: false
+        persona: ai-antipattern-reviewer
+        policy:
+          - review
+          - ai-antipattern
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        instruction: review-ai
+        rules:
+          - condition: No AI-specific issues
+          - condition: AI-specific issues found
+        output_contracts:
+          report:
+            - name: ai-review.md
+              format: ai-review
+    rules:
+      - condition: all("Complies with Terraform conventions", "No AI-specific issues")
+        next: supervise
+      - condition: any("Convention violations found", "AI-specific issues found")
+        next: supervise
+  - name: supervise
+    edit: false
+    persona: supervisor
+    policy: review
+    knowledge: terraform-aws
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+    instruction: supervise
+    rules:
+      - condition: All reviewers approved and task requirements met
+        next: COMPLETE
+      - condition: Only AI-specific issues need fixing
+        next: ai_fix
+      - condition: Only convention violations or requirements unmet
+        next: supervise_fix
+      - condition: Multiple types of issues found
+        next: fix_both
+      - condition: Irreconcilable requirement conflict, user decision needed
+        next: ABORT
+    output_contracts:
+      report:
+        - name: supervisor-validation.md
+          format: supervisor-validation
+        - name: summary.md
+          format: summary
+          use_judge: false
+  - name: fix_both
+    parallel:
+      - name: ai_fix_parallel
+        edit: true
+        persona: terraform-coder
+        policy:
+          - terraform
+        knowledge: terraform-aws
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Edit
+              - Bash
+              - WebSearch
+              - WebFetch
+        required_permission_mode: full
+        rules:
+          - condition: AI issue fix complete
+          - condition: No fix needed (target file/spec verified)
+          - condition: Cannot determine, insufficient info
+        instruction: ai-fix
+      - name: supervise_fix_parallel
+        edit: true
+        persona: terraform-coder
+        policy:
+          - terraform
+        knowledge: terraform-aws
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Edit
+              - Bash
+              - WebSearch
+              - WebFetch
+        required_permission_mode: full
+        rules:
+          - condition: Supervisor's findings have been fixed
+          - condition: Cannot proceed with fix
+        instruction: fix-supervisor
+    rules:
+      - condition: all("AI issue fix complete", "Supervisor's findings have been fixed")
+        next: reviewers
+      - condition: any("No fix needed (target file/spec verified)", "Cannot determine, insufficient info", "Cannot proceed with fix")
+        next: implement
+  - name: ai_fix
+    edit: true
+    persona: terraform-coder
+    policy:
+      - terraform
+    knowledge: terraform-aws
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: full
+    pass_previous_response: false
+    rules:
+      - condition: AI issue fix complete
+        next: reviewers
+      - condition: No fix needed (target file/spec verified)
+        next: implement
+      - condition: Cannot determine, insufficient info
+        next: implement
+    instruction: ai-fix
+  - name: supervise_fix
+    edit: true
+    persona: terraform-coder
+    policy:
+      - terraform
+    knowledge: terraform-aws
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: full
+    pass_previous_response: false
+    rules:
+      - condition: Supervisor's findings have been fixed
+        next: reviewers
+      - condition: Cannot proceed with fix
+        next: implement
+    instruction: fix-supervisor
+loop_monitors:
+  - cycle: [fix_both, reviewers]
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: |
+        The review → fix cycle has repeated {cycle_count} times.
+        Check the review report history in the Report Directory and assess convergence.
+
+        **Signs of unproductive cycling:**
+        - Same finding_id oscillating between resolved → new
+        - New issues keep arising as side effects of previous fixes
+        - Reviewer findings conflict with task requirements and cannot be reconciled
+      rules:
+        - condition: Healthy (new issues trending down)
+          next: fix_both
+        - condition: Unproductive (oscillation or requirement conflict)
+          next: ABORT
+  - cycle: [ai_fix, reviewers]
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: |
+        The AI fix → review cycle has repeated {cycle_count} times.
+        Check the review report history in the Report Directory and assess convergence.
+
+        **Signs of unproductive cycling:**
+        - Same finding_id oscillating between resolved → new
+        - New issues keep arising as side effects of previous fixes
+        - Reviewer findings conflict with task requirements and cannot be reconciled
+      rules:
+        - condition: Healthy (new issues trending down)
+          next: ai_fix
+        - condition: Unproductive (oscillation or requirement conflict)
+          next: ABORT
+  - cycle: [supervise_fix, reviewers]
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction_template: |
+        The supervisor fix → review cycle has repeated {cycle_count} times.
+        Check the review report history in the Report Directory and assess convergence.
+
+        **Signs of unproductive cycling:**
+        - Same finding_id oscillating between resolved → new
+        - New issues keep arising as side effects of previous fixes
+        - Reviewer findings conflict with task requirements and cannot be reconciled
+      rules:
+        - condition: Healthy (new issues trending down)
+          next: supervise_fix
+        - condition: Unproductive (oscillation or requirement conflict)
+          next: ABORT

builtins/en/pieces/unit-test.yaml

@@ -22,7 +22,7 @@ loop_monitors:
         is healthy (making progress) or unproductive (repeating the same issues).
 
         **Reports to reference:**
-        - AI Review results: {report:04-ai-review.md}
+        - AI Review results: {report:ai-review.md}
 
         **Judgment criteria:**
         - Are new issues being found/fixed in each cycle?
@@ -41,13 +41,15 @@ movements:
     knowledge:
       - architecture
       - backend
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     rules:
       - condition: Test plan complete
         next: implement_test
@@ -62,7 +64,7 @@ movements:
     instruction: plan-test
     output_contracts:
       report:
-        - name: 00-test-plan.md
+        - name: test-plan.md
           format: test-plan
   - name: implement_test
     edit: true
@@ -74,15 +76,17 @@ movements:
     knowledge:
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     rules:
       - condition: Test implementation complete
@@ -108,12 +112,14 @@ movements:
     policy:
       - review
       - ai-antipattern
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     rules:
       - condition: No AI-specific issues
         next: review_test
@@ -122,7 +128,7 @@ movements:
     instruction: ai-review
     output_contracts:
       report:
-        - name: 04-ai-review.md
+        - name: ai-review.md
           format: ai-review
   - name: ai_fix
     edit: true
@@ -134,15 +140,17 @@ movements:
     knowledge:
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -157,10 +165,12 @@ movements:
     edit: false
     persona: architecture-reviewer
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
+          - Glob
+          - Grep
     rules:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
@@ -173,12 +183,14 @@ movements:
     policy:
       - review
       - qa
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - WebSearch
+          - Glob
-      - WebFetch
+          - Grep
+          - WebSearch
+          - WebFetch
     rules:
       - condition: approved
         next: supervise
@@ -187,7 +199,7 @@ movements:
     instruction: review-test
     output_contracts:
       report:
-        - name: 05-qa-review.md
+        - name: qa-review.md
           format: qa-review
   - name: fix
     edit: true
@@ -199,15 +211,17 @@ movements:
     knowledge:
       - backend
       - architecture
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Edit
+          - Glob
-      - Write
+          - Grep
-      - Bash
+          - Edit
-      - WebSearch
+          - Write
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     required_permission_mode: edit
     pass_previous_response: false
     rules:
@@ -220,13 +234,15 @@ movements:
     edit: false
     persona: supervisor
     policy: review
-    allowed_tools:
+    provider_options:
-      - Read
+      claude:
-      - Glob
+        allowed_tools:
-      - Grep
+          - Read
-      - Bash
+          - Glob
-      - WebSearch
+          - Grep
-      - WebFetch
+          - Bash
+          - WebSearch
+          - WebFetch
     pass_previous_response: false
     rules:
       - condition: All checks passed

builtins/en/templates/instructions/supervise.md

@@ -1,7 +1,7 @@
 # supervise -- Final Verification Instruction Template
 
 > **Purpose**: Run tests/builds, verify all review results, give final approval
-> **Agent**: supervisor, expert-supervisor
+> **Agent**: supervisor, dual-supervisor
 > **Reports**: Validation + Summary (format embedded in template)
 
 ---
@@ -11,7 +11,7 @@
 ```
 Run tests, verify builds, and perform final approval.
 
-{Customize: Review pass status -- for expert pieces where all reviews have passed}
+{Customize: Review pass status -- for dual pieces where all reviews have passed}
 ## Previous Reviews Summary
 Reaching this movement means all of the following reviews have been APPROVED:
 {Customize: Actual review list}