takt/resources/global/ja/pieces/default-hybrid-codex.yaml

# Default TAKT Piece
# Plan -> Architect -> Implement -> AI Review -> Reviewers (parallel: Architect + QA) -> Supervisor Approval
#
# Template Variables (auto-injected by buildInstruction):
#   {iteration}      - Piece-wide turn count (total movements executed across all agents)
#   {max_iterations} - Maximum iterations allowed for the piece
#   {movement_iteration} - Per-movement iteration count (how many times THIS movement has been executed)
#   {task}           - Original user request
#   {previous_response} - Output from the previous movement
#   {user_inputs}    - Accumulated user inputs during piece
#   {report_dir}     - Report directory name (e.g., "20250126-143052-task-summary")

name: default-hybrid-codex
description: Standard development piece with planning and specialized reviews

max_iterations: 30

initial_movement: plan

loop_monitors:
  - cycle: [ai_review, ai_fix]
    threshold: 3
    judge:
      agent: ../agents/default/supervisor.md
      instruction_template: |
        ai_review と ai_fix のループが {cycle_count} 回繰り返されました。

        各サイクルのレポートを確認し、このループが健全（進捗がある）か、
        非生産的（同じ問題を繰り返している）かを判断してください。

        **参照するレポート:**
        - AIレビュー結果: {report:04-ai-review.md}

        **判断基準:**
        - 各サイクルで新しい問題が発見・修正されているか
        - 同じ指摘が繰り返されていないか
        - 修正が実際に反映されているか
      rules:
        - condition: 健全（進捗あり）
          next: ai_review
        - condition: 非生産的（改善なし）
          next: reviewers

movements:
  - name: plan
    edit: false
    agent: ../agents/default/planner.md
    report:
      name: 00-plan.md
      format: |
        ```markdown
        # タスク計画

        ## 元の要求
        {ユーザーの要求をそのまま記載}

        ## 分析結果

        ### 目的
        {達成すべきこと}

        ### スコープ
        {影響範囲}

        ### 実装アプローチ
        {どう進めるか}

        ## 確認事項（あれば）
        - {不明点や確認が必要な点}
        ```
    allowed_tools:
      - Read
      - Glob
      - Grep
      - Bash
      - WebSearch
      - WebFetch
    rules:
      - condition: 要件が明確で実装可能
        next: architect
      - condition: ユーザーが質問をしている（実装タスクではない）
        next: COMPLETE
      - condition: 要件が不明確、情報不足
        next: ABORT
        appendix: |
          確認事項:
          - {質問1}
          - {質問2}
    instruction_template: |
      タスクを分析し、実装方針を立ててください。

      **注意:** Previous Responseがある場合は差し戻しのため、
      その内容を踏まえて計画を見直してください（replan）。

      **やること（実装タスクの場合）:**
      1. タスクの要件を理解する
      2. 影響範囲を特定する
      3. 実装アプローチを決める

  - name: architect
    edit: false
    agent: ../agents/default/architect.md
    report:
      name: 01-architecture.md
      format: |
        ```markdown
        # アーキテクチャ設計

        ## タスク規模
        Small / Medium / Large

        ## 設計判断

        ### ファイル構成
        | ファイル | 役割 |
        |---------|------|
        | `src/example.ts` | 概要 |

        ### 技術選定
        - {選定した技術・ライブラリとその理由}

        ### 設計パターン
        - {採用するパターンと適用箇所}

        ## 実装ガイドライン
        - {Coderが実装時に従うべき指針}
        ```
    allowed_tools:
      - Read
      - Glob
      - Grep
      - WebSearch
      - WebFetch
    rules:
      - condition: 小規模タスク（設計不要）
        next: implement
      - condition: 設計完了
        next: implement
      - condition: 情報不足、判断できない
        next: ABORT
    instruction_template: |
      計画レポート（{report:00-plan.md}）を読み、アーキテクチャ設計を行ってください。

      **小規模タスクの判断基準:**
      - 1-2ファイルの変更のみ
      - 設計判断が不要
      - 技術選定が不要

      小規模タスクの場合は設計レポートを作成せず、「小規模タスク（設計不要）」のルールに対応してください。

      **設計が必要なタスク:**
      - 3ファイル以上の変更
      - 新しいモジュール・機能の追加
      - 技術選定が必要
      - アーキテクチャパターンの決定が必要

      **やること:**
      1. タスクの規模を評価
      2. ファイル構成を決定
      3. 技術選定（必要な場合）
      4. 設計パターンの選択
      5. Coderへの実装ガイドライン作成

  - name: implement
    edit: true
    agent: ../agents/default/coder.md
    provider: codex
    session: refresh
    report:
      - Scope: 02-coder-scope.md
      - Decisions: 03-coder-decisions.md
    allowed_tools:
      - Read
      - Glob
      - Grep
      - Edit
      - Write
      - Bash
      - WebSearch
      - WebFetch
    permission_mode: edit
    rules:
      - condition: 実装完了
        next: ai_review
      - condition: 実装未着手（レポートのみ）
        next: ai_review
      - condition: 判断できない、情報不足
        next: ai_review
      - condition: ユーザー入力が必要
        next: implement
        requires_user_input: true
        interactive_only: true
    instruction_template: |
      planムーブメントで立てた計画と、architectムーブメントで決定した設計に従って実装してください。

      **参照するレポート:**
      - 計画: {report:00-plan.md}
      - 設計: {report:01-architecture.md}（存在する場合）

      Piece Contextに示されたReport Directory内のファイルのみ参照してください。他のレポートディレクトリは検索/参照しないでください。

      **重要:** 設計判断はせず、architectムーブメントで決定された設計に従ってください。
      不明点や設計の変更が必要な場合は報告してください。

      **重要**: 実装と同時に単体テストを追加してください。
      - 新規作成したクラス・関数には単体テストを追加
      - 既存コードを変更した場合は該当するテストを更新
      - テストファイルの配置: プロジェクトの規約に従う（例: `__tests__/`, `*.test.ts`）

      **Scopeレポートフォーマット（実装開始時に作成）:**
      ```markdown
      # 変更スコープ宣言

      ## タスク
      {タスクの1行要約}

      ## 変更予定
      | 種別 | ファイル |
      |------|---------|
      | 作成 | `src/example.ts` |
      | 変更 | `src/routes.ts` |

      ## 推定規模
      Small / Medium / Large

      ## 影響範囲
      - {影響するモジュールや機能}
      ```

      **Decisionsレポートフォーマット（実装完了時、決定がある場合のみ）:**
      ```markdown
      # 決定ログ

      ## 1. {決定内容}
      - **背景**: {なぜ決定が必要だったか}
      - **検討した選択肢**: {選択肢リスト}
      - **理由**: {選んだ理由}
      ```

      **必須出力（見出しを含める）**
      ## 作業結果
      - {実施内容の要約}
      ## 変更内容
      - {変更内容の要約}
      ## テスト結果
      - {実行コマンドと結果}


  - name: ai_review
    edit: false
    agent: ../agents/default/ai-antipattern-reviewer.md
    report:
      name: 04-ai-review.md
      format: |
        ```markdown
        # AI生成コードレビュー

        ## 結果: APPROVE / REJECT

        ## サマリー
        {1文で結果を要約}

        ## 検証した項目
        | 観点 | 結果 | 備考 |
        |------|------|------|
        | 仮定の妥当性 | ✅ | - |
        | API/ライブラリの実在 | ✅ | - |
        | コンテキスト適合 | ✅ | - |
        | スコープ | ✅ | - |

        ## 問題点（REJECTの場合）
        | # | カテゴリ | 場所 | 問題 |
        |---|---------|------|------|
        | 1 | 幻覚API | `src/file.ts:23` | 存在しないメソッド |
        ```

        **認知負荷軽減ルール:**
        - 問題なし → サマリー1文 + チェック表のみ（10行以内）
        - 問題あり → + 問題を表形式で（25行以内）
    allowed_tools:
      - Read
      - Glob
      - Grep
      - WebSearch
      - WebFetch
    rules:
      - condition: AI特有の問題なし
        next: reviewers
      - condition: AI特有の問題あり
        next: ai_fix
    instruction_template: |
      **これは {movement_iteration} 回目のAI Reviewです。**

      初回は網羅的にレビューし、指摘すべき問題をすべて出し切ってください。
      2回目以降は、前回REJECTした項目が修正されたかの確認を優先してください。

      AI特有の問題についてコードをレビューしてください:
      - 仮定の検証
      - もっともらしいが間違っているパターン
      - 既存コードベースとの適合性
      - スコープクリープの検出

  - name: ai_fix
    edit: true
    agent: ../agents/default/coder.md
    provider: codex
    session: refresh
    allowed_tools:
      - Read
      - Glob
      - Grep
      - Edit
      - Write
      - Bash
      - WebSearch
      - WebFetch
    permission_mode: edit
    rules:
      - condition: AI問題の修正完了
        next: ai_review
      - condition: 修正不要（指摘対象ファイル/仕様の確認済み）
        next: ai_no_fix
      - condition: 判断できない、情報不足
        next: ai_no_fix
    instruction_template: |
      **これは {movement_iteration} 回目の AI Review です。**

      2回目以降は、前回の修正が実際には行われていなかったということです。
      **あなたの「修正済み」という認識が間違っています。**

      **まず認めること:**
      - 「修正済み」と思っていたファイルは実際には修正されていない
      - 前回の作業内容の認識が間違っている
      - ゼロベースで考え直す必要がある

      **必須アクション:**
      1. 指摘された全ファイルを Read tool で開く（思い込みを捨てて事実確認）
      2. 問題箇所を grep で検索して実在を確認する
      3. 確認した問題を Edit tool で修正する
      4. テストを実行して検証する（`./gradlew :backend:test` 等）
      5. 「何を確認して、何を修正したか」を具体的に報告する

      **報告フォーマット:**
      - ❌ 「既に修正されています」
      - ✅ 「ファイルXのL123を確認した結果、問題Yが存在したため、Zに修正しました」

      **絶対に禁止:**
      - ファイルを開かずに「修正済み」と報告

      **修正不要の扱い（必須）**
      - AI Reviewの指摘ごとに「対象ファイルの確認結果」を示せない場合は修正不要と判断しない
      - 指摘が「生成物」「仕様同期」に関係する場合は、生成元/仕様の確認ができなければ「判断できない、情報不足」に対応するタグを出力する
      - 修正不要の場合は「判断できない、情報不足」に対応するタグを出力し、理由と確認範囲を明記する

      **必須出力（見出しを含める）**
      ## 確認したファイル
      - {ファイルパス:行番号}
      ## 実行した検索
      - {コマンドと要約}
      ## 修正内容
      - {変更内容}
      ## テスト結果
      - {実行コマンドと結果}
      - 思い込みで判断
      - AI Reviewer が REJECT した問題の放置

  - name: ai_no_fix
    edit: false
    agent: ../agents/default/architecture-reviewer.md
    allowed_tools:
      - Read
      - Glob
      - Grep
    rules:
      - condition: ai_reviewの指摘が妥当（修正すべき）
        next: ai_fix
      - condition: ai_fixの判断が妥当（修正不要）
        next: reviewers
    instruction_template: |
      ai_review（レビュアー）と ai_fix（コーダー）の意見が食い違っています。

      - ai_review は問題を指摘し REJECT しました
      - ai_fix は確認の上「修正不要」と判断しました

      両者の出力を確認し、どちらの判断が妥当か裁定してください。

      **参照するレポート:**
      - AIレビュー結果: {report:04-ai-review.md}

      **判断基準:**
      - ai_review の指摘が具体的で、コード上の実在する問題を指しているか
      - ai_fix の反論に根拠（ファイル確認結果、テスト結果）があるか
      - 指摘が非ブロッキング（記録のみ）レベルか、実際に修正が必要か

  - name: reviewers
    parallel:
      - name: arch-review
        edit: false
        agent: ../agents/default/architecture-reviewer.md
        report:
          name: 05-architect-review.md
          format: |
            ```markdown
            # アーキテクチャレビュー

            ## 結果: APPROVE / REJECT

            ## サマリー
            {1-2文で結果を要約}

            ## 確認した観点
            - [x] 構造・設計
            - [x] コード品質
            - [x] 変更スコープ
            - [x] テストカバレッジ
            - [x] デッドコード
            - [x] 呼び出しチェーン検証

            ## 問題点（REJECTの場合）
            | # | スコープ | 場所 | 問題 | 修正案 |
            |---|---------|------|------|--------|
            | 1 | スコープ内 | `src/file.ts:42` | 問題の説明 | 修正方法 |

            スコープ: 「スコープ内」（今回修正可能）/ 「スコープ外」（既存問題・非ブロッキング）

            ## 既存問題（参考・非ブロッキング）
            - {既存問題の記録。今回の変更と無関係な問題}
            ```

            **認知負荷軽減ルール:**
            - APPROVE → サマリーのみ（5行以内）
            - REJECT → 問題点を表形式で（30行以内）
        allowed_tools:
          - Read
          - Glob
          - Grep
          - WebSearch
          - WebFetch
        rules:
          - condition: approved
          - condition: needs_fix
        instruction_template: |
          **実装がarchitectムーブメントの設計に従っているか**を確認してください。
          AI特有の問題はレビューしないでください（ai_reviewムーブメントで行います）。

          **参照するレポート:**
          - 設計: {report:01-architecture.md}（存在する場合）
          - 実装スコープ: {report:02-coder-scope.md}

          **レビュー観点:**
          - 設計との整合性（architectが定めたファイル構成・パターンに従っているか）
          - コード品質
          - 変更スコープの適切性
          - テストカバレッジ
          - デッドコード
          - 呼び出しチェーン検証

          **注意:** architectムーブメントをスキップした小規模タスクの場合は、従来通り設計の妥当性も確認してください。

      - name: qa-review
        edit: false
        agent: ../agents/default/qa-reviewer.md
        report:
          name: 06-qa-review.md
          format: |
            ```markdown
            # QAレビュー

            ## 結果: APPROVE / REJECT

            ## サマリー
            {1-2文で結果を要約}

            ## レビュー観点
            | 観点 | 結果 | 備考 |
            |------|------|------|
            | テストカバレッジ | ✅ | - |
            | テスト品質 | ✅ | - |
            | エラーハンドリング | ✅ | - |
            | ドキュメント | ✅ | - |
            | 保守性 | ✅ | - |

            ## 問題点（REJECTの場合）
            | # | カテゴリ | 問題 | 修正案 |
            |---|---------|------|--------|
            | 1 | テスト | 問題の説明 | 修正方法 |
            ```
        allowed_tools:
          - Read
          - Glob
          - Grep
          - WebSearch
          - WebFetch
        rules:
          - condition: approved
          - condition: needs_fix
        instruction_template: |
          品質保証の観点から変更をレビューしてください。

          **レビュー観点:**
          - テストカバレッジと品質
          - テスト戦略（unit/integration/E2E）
          - エラーハンドリング
          - ログとモニタリング
          - 保守性
    rules:
      - condition: all("approved")
        next: supervise
      - condition: any("needs_fix")
        next: fix

  - name: fix
    edit: true
    agent: ../agents/default/coder.md
    provider: codex
    allowed_tools:
      - Read
      - Glob
      - Grep
      - Edit
      - Write
      - Bash
      - WebSearch
      - WebFetch
    permission_mode: edit
    rules:
      - condition: 修正完了
        next: reviewers
      - condition: 判断できない、情報不足
        next: plan
    instruction_template: |
      レビュアーのフィードバックに対応してください。
      セッションの会話履歴を確認し、レビュアーの指摘事項を修正してください。


      **必須出力（見出しを含める）**
      ## 作業結果
      - {実施内容の要約}
      ## 変更内容
      - {変更内容の要約}
      ## テスト結果
      - {実行コマンドと結果}
      ## 証拠
      - {確認したファイル/検索/差分/ログの要点を列挙}

  - name: supervise
    edit: false
    agent: ../agents/default/supervisor.md
    report:
      - Validation: 07-supervisor-validation.md
      - Summary: summary.md
    allowed_tools:
      - Read
      - Glob
      - Grep
      - Bash
      - WebSearch
      - WebFetch
    rules:
      - condition: すべて問題なし
        next: COMPLETE
      - condition: 要求未達成、テスト失敗、ビルドエラー
        next: plan
    instruction_template: |
      テスト実行、ビルド確認、最終承認を行ってください。

      **ピース全体の確認:**
      1. 計画（{report:00-plan.md}）と設計（{report:01-architecture.md}、存在する場合）に従った実装か
      2. 各レビュームーブメントの指摘が対応されているか
      3. 元のタスク目的が達成されているか

      **レポートの確認:** Report Directory内の全レポートを読み、
      未対応の改善提案がないか確認してください。

      **Validationレポートフォーマット:**
      ```markdown
      # 最終検証結果

      ## 結果: APPROVE / REJECT

      ## 検証サマリー
      | 項目 | 状態 | 確認方法 |
      |------|------|---------|
      | 要求充足 | ✅ | 要求リストと照合 |
      | テスト | ✅ | `npm test` (N passed) |
      | ビルド | ✅ | `npm run build` 成功 |
      | 動作確認 | ✅ | 主要フロー確認 |

      ## 成果物
      - 作成: {作成したファイル}
      - 変更: {変更したファイル}

      ## 未完了項目（REJECTの場合）
      | # | 項目 | 理由 |
      |---|------|------|
      | 1 | {項目} | {理由} |
      ```

      **Summaryレポートフォーマット（APPROVEの場合のみ）:**
      ```markdown
      # タスク完了サマリー

      ## タスク
      {元の要求を1-2文で}

      ## 結果
      ✅ 完了

      ## 変更内容
      | 種別 | ファイル | 概要 |
      |------|---------|------|
      | 作成 | `src/file.ts` | 概要説明 |

      ## レビュー結果
      | レビュー | 結果 |
      |---------|------|
      | Architecture Design | ✅ 完了 |
      | AI Review | ✅ APPROVE |
      | Architect Review | ✅ APPROVE |
      | QA | ✅ APPROVE |
      | Supervisor | ✅ APPROVE |

      ## 確認コマンド
      ```bash
      npm test
      npm run build
      ```
      ```