spec-implement

spec-implement — 仕様駆動実装のオーケストレーター

ワーカーとなるスキル（spec-code、spec-review、spec-test）を調整し、仕様からプルリクエストまでの実装を進めます。このスキルはコードの作成やレビューを行いません。作業を委任します。

言語ルール

1. 入力言語を自動検出 → 同じ言語で出力
2. 日本語の入力 → 日本語で出力し、references/implement-guide.ja.mdを使用
3. 英語の入力 → 英語で出力し、references/implement-guide.mdを使用
4. 明示的な上書き指定が優先されます

オプション

オプション	説明
--resume	tasks.mdで最後に未完了のタスクから再開します
--issue {N}	コンテキストとして使用するGitHub Issue番号を指定します
--spec {path}	.specs/ディレクトリのパスを指定します（デフォルト：自動検出）
--dry-run	変更を加えずに実行計画を表示します
--roles {map}	kind別にタスクの担当者を割り当てます。形式：ui=claude,backend=codex,test=codex、またはroles.impl_{kind}キーで割り当てを指定するpipeline.ymlのパスを指定します。省略した場合 → すべてのタスクでspec-codeを使用し、すべてのレビューでspec-reviewを使用します（従来の動作で、agent-delegateは関与しません）。
--host-runtime {claude|codex}	このスキルを実行するランタイムです。--rolesと併用する場合は必須です。オーケストレーターは記録されたhost_runtimeを渡し、AIの役割と実行バックエンドを個別に解決します。
--review-fallback {block|native-independent}	--rolesのパスにおける、レビュー専用の機能ポリシーです。デフォルトのblockはスタンドアロン動作を維持します。native-independentでは、クロスAIレビュアーが利用できない場合、新しい読み取り専用のランタイムネイティブなレビュアーサブエージェントにフォールバックできます。spec-orchestrateはこの値を明示的に渡します。

役割：オーケストレーターのみ

🚨 BLOCKING — このルールは以下のすべてに優先します。

このスキルはオーケストレーターです。ワーカースキルを調整しますが、自ら作業を行いません。

• 自分で実装コードを書いてはいけません。 必ずspec-codeに委任してください。
• 自分でコードレビューを行ってはいけません。 必ずspec-reviewに委任してください。
• 自分でテストを書いてはいけません。 必ずspec-testに委任してください。

ワーカースキルがインストールされていない場合は、停止してインストールを提案してください。決して自分で作業を代行してはいけません。

重要な最初の手順

実装を始める前に、以下の確認を順番どおりに実行してください：

1. 環境を確認する：pwd、git status、gh auth status

2. ユーザー入力を解析する：--resume、--issue、--spec、--dry-run、 --roles、--host-runtime オプションを抽出する

3. cmux が利用可能か確認する：

   echo $CMUX_SOCKET_PATH
   

   設定されている場合 → 外部ペインの選択肢として cmux によるディスパッチが利用可能であることを記録します。

4. ランタイムネイティブのエージェントが利用可能か確認する：

   ls .codex/agents/workflow-*.toml 2>/dev/null
   ls .claude/agents/workflow-*.md 2>/dev/null
   

   Codex で実行中で、.codex/agents/workflow-*.toml が存在する場合 → ワークフローの役割には cmux よりもランタイムネイティブの Codex サブエージェントを優先します。Codex は .codex/agents/*.toml からカスタムエージェントを検出します。[agents.<name>] config_file エントリーは必須ではありません。 Claude Code で実行中で、.claude/agents/workflow-*.md が存在する場合 → CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が設定されている場合に限り、ワークフローの役割には cmux よりも Claude Code エージェントチームを優先します。設定されていない場合は、通常の Claude Code サブエージェントを使用するか、単一エージェントで順次実行します。

5. 仕様書ディレクトリを特定する 🚨 ブロッキング：

   • --spec が指定されている場合 → パスの存在を確認し、それを使用します
   • Issue の本文にパスが含まれているかどうかにかかわらず、常に .specs/ を検索します：

     find .specs -maxdepth 2 -name "tasks.md" 2>/dev/null
     

   • 該当する仕様書ディレクトリが見つかった場合 → それを使用して続行します
   • .specs/ が見つからない場合 → AskUserQuestion を使ってユーザーに確認します：

     question: "仕様書ディレクトリが見つかりません。仕様書の場所を教えてください。" /
               "仕様書ディレクトリが見つかりません。仕様書の場所を教えてください。"
     options:
       - "パスを手動で指定する" / "パスを手動で指定する"
       - "spec-generator で仕様書を生成する" / "spec-generator で仕様書を生成する"
     

     • ユーザーがパスを指定した場合 → 存在を確認して使用します
     • ユーザーが spec-generator を選択した場合 → 停止し、次のように指示します：まず /spec-generator を実行してから、/spec-implement を再実行してください
   • 有効な仕様書ディレクトリが確認されるまで、Phase 5（ブランチ作成）に進まないでください。

6. プロジェクトファイルを特定して読み込む：

   • ワークフロー：docs/development/issue-to-pr-workflow.md → docs/ → 検索 → フォールバック
   • コーディング規則：docs/development/coding-rules.md → docs/ → 検索 → フォールバック
   • レビュー規則：docs/development/review_rules.md → docs/ → 検索 → 任意
   • プロジェクトの指示：CLAUDE.md、AGENTS.md
   • 仕様書ファイル：requirement.md、design.md、tasks.md

実行フロー

Phase 1-3：コンテキストの読み込み

ワークフロー、コーディング規則、プロジェクトの指示を読み込みます。検索とフォールバックのロジックは以前と同じです。詳細は references/implement-guide.md を参照してください。

ワークフローから以下を抽出します：

• ベースブランチ（デフォルト：main）
• ブランチの命名規則
• コミットメッセージの形式
• テスト／lint／ビルドのコマンド
• ディスパッチ戦略とエージェント定義（存在する場合）

Phase 4：Issue の分析

--issue {N} が指定されている場合：

gh issue view {N} --json title,body,labels,assignees

Phase 5：ブランチの作成

🚨 ブロッキング — フィーチャーブランチは必須です

git checkout {base_branch} && git pull origin {base_branch}
git checkout -b feature/issue-{N}-{brief-description}

作成後に検証し、main、master、develop 上にいないことを確認してください。

フェーズ 6：タスクループ（オーケストレーション）

tasks.md を読み、ロールタグに従ってフェーズを処理します。

フェーズにロールタグがない場合（[code]／[orchestrator] のない旧形式の仕様）、デフォルトで [code] として扱います。これにより、v3 より前に生成された仕様との後方互換性が確保されます。

レビューゲートのフェーズ：-R サフィックスが付いたフェーズ（例：Phase 2-R: Review Gate [orchestrator]）はレビューゲートです。これらを処理する際は、直前の [code] フェーズにある各タスクに対して spec-review と spec-test を実行します。

for each phase in tasks.md:
  if phase has [orchestrator] tag AND phase name contains "Review Gate":
    // This is a review gate — run spec-review + spec-test for preceding [code] tasks
    for each task in the preceding [code] phase:
      invoke spec-review --task {task-id} --spec {path}
      read review result → if FAIL, run fix loop (spec-code --feedback → re-review, max 3)
      invoke spec-test --task {task-id} --spec {path}
      read test result → if FAIL, run fix loop (spec-code --feedback → re-test)
      if review PASS AND test PASS: mark review gate task checkbox

  elif phase has [orchestrator] tag:
    execute tasks directly (run commands, check results — do NOT modify files)

  elif phase has [code] tag (or NO tag — legacy fallback):
    for each unchecked task in phase:
      // Implement only — review/test happens in the Review Gate phase
      invoke spec-code --issue {N} --task {task-id} --spec {path}
      mark task checkbox: - [ ] → - [x]
      commit progress

ディスパッチモード：

ワーカーのスキルを呼び出す方法は、実行モードによって異なります。

モード	呼び出し方法
シングルエージェント	現在のセッションでスキルを直接呼び出します
Codex サブエージェント	Agent 列の値（例：workflow-implementer）でワークフローのカスタムエージェントを起動し、割り当てられたタスクに対して /spec-code、/spec-review、または /spec-test を実行するよう指示します
Claude Code エージェントチーム	Claude Code に、Agent 列の値（例：workflow-implementer）に基づくチームメイトでエージェントチームを作成し、それらのチームメイトに /spec-code、/spec-review、または /spec-test のタスクを割り当てるよう依頼します
cmux ディスパッチ	外部ペインが明示的に選択されている場合、またはランタイムネイティブのエージェントが利用できない場合は、cmux-delegate --agent {ai} --task "/spec-code --issue {N} --task {id} --spec {path}" を使用します

モードの優先順位：

1. Codex で実行中で、.codex/agents/workflow-*.toml が存在する場合 → デフォルトで Codex サブエージェントを使用します
2. Claude Code で実行中で、.claude/agents/workflow-*.md が存在し、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が設定されている場合 → デフォルトで Claude Code エージェントチームを使用します
3. cmux が利用可能で、ワークフローまたはユーザーが cmux を明示的に選択している場合 → cmux ディスパッチを使用します
4. それ以外の場合は、シングルエージェントで順次実行します

この優先順位は、--roles を使わない旧来のパスに適用されます。--roles が有効な場合は、フェーズ 6b のホスト対応能力フォールバックが優先されます。利用できないネイティブワーカーについて呼び出し元に報告し、cmux やシングルエージェント実行に暗黙的に切り替えないでください。

Codex サブエージェントの場合：

1. ワークフローで参照されている .codex/agents/workflow-implementer.toml、.codex/agents/workflow-reviewer.toml、および .codex/agents/workflow-tester.toml が存在することを確認します
2. Agent 列の値をカスタムエージェントのタイプとして使用します
3. TOML の内容をプロンプトにインラインで含めないでください。Codex がカスタムエージェントファイルから developer_instructions を読み込みます
4. タスク固有のコンテキスト（issue、仕様のパス、タスク ID、関連ファイル、期待される成果物／結果）のみを渡します

Claude Code エージェントチームの場合：

1. ワークフローで参照されている .claude/agents/workflow-implementer.md、.claude/agents/workflow-reviewer.md、および .claude/agents/workflow-tester.md が存在することを確認します
2. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が設定されていることを確認します
3. 予測可能なチームメイト名を使用してエージェントチームを作成し、Agent 列の値に基づいてワークフローのエージェント定義を使用するよう Claude Code に依頼します
4. Claude Code がそのエージェントを直接選択できる場合、Markdown のエージェント定義をプロンプトにインラインで含めないでください
5. タスク固有のコンテキスト（issue、仕様のパス、タスク ID、関連ファイル、依存関係、期待される成果物／結果、および競合を避けるためのファイル所有権）を渡します

cmux ディスパッチの場合：

1. ワークフローのディスパッチ戦略とエージェント定義ファイルのパスを読み込みます
2. ロールをエージェントに割り当てます（implementer／tester → cmux-delegate、reviewer → cmux-second-opinion）
3. スキルコマンドを渡します。ワーカーのスキルが独自にコンテキストを読み込みます

フェーズ 6b：種別ベースのタスク振り分け（--roles）

このレイヤーはフェーズ 6 のループの上に位置し、--roles が指定された場合にのみ有効になります（オーケストレーションモード）。--roles が指定されていない場合、すべてのタスクで spec-code を使用し、すべてのレビューで spec-review を使用します。これは従来の動作と同じで、agent-delegate は関与しません。ループの制御フロー（フェーズごとの反復、3 回を上限とする修正ループ、ゲート評価、チェックボックスのマーク付け、spec-test）は変更されません。各ステップの実行担当のみをタスクごとに解決します。

担当者の解決（タスクごと）：

1. tasks.md の詳細ブロックから、タスクの kind: フィールド（ui | backend | test）を読み取ります。
2. kind が既知で、マップに存在する場合は owner = roles[kind]、それ以外の場合は claude（デフォルト）とします。
3. owner は実装を担当する AI ロールとして扱い、バックエンドとして扱わないでください。
4. --host-runtime から実行担当を解決します。
   • owner == host_runtime → spec-code をランタイムネイティブのサブエージェントで実行します。 agent-delegate は起動しません。
   • owner != host_runtime → --mode delegate --target <owner> --detach を指定して agent-delegate スクリプトを実行します。想定される run id を保持し、コントラクトに従って、レポートを優先する 15～30 秒の状態待機を使用します。30 分間隔で再評価し、2 時間後にコントラクトに従って制御された停止を適用します。

**レビュアーの反転（レビューゲート）：**タスクの実装担当とは反対の AI ロールを優先レビュアーとして選択し、同じホスト対応マトリックスを通じてそのレビュアーを解決します。

実装担当の AI ロール	レビュアーの AI ロール
codex	claude
claude	codex

レビュアーとホストが一致する場合は、ランタイムネイティブの spec-review サブエージェントを使用します。ロールが異なる場合は、agent-delegate に --mode review --target <reviewer> を指定して使用します（同期実行は、具体的な根拠により 5 分以内で完了すると見込まれる場合に限り、それ以外はデタッチします）。修正は実装担当の AI ロールに振り分け、同じマトリックスを通じて再度解決します。agent-delegate のレビュー用ファイルは spec-review と互換性があるため（重要度別のセクションと Gate: PASS|FAIL を含む）、既存の修正ループでそのまま使用できます。

他の AI によるレビュアーが利用できない場合、デフォルトの --review-fallback block ではブロッカーを報告します。native-independent のみ、ホスト AI ロールで続行できます。その場合は新しいランタイムネイティブのレビュアーサブエージェントを起動する必要があります。このサブエージェントは実装担当のインスタンスとは別のものであり、実装時の会話を再開したり受け取ったりせず、書き込みツールを持たず、ワークスペースを変更しないものとします。この独立したネイティブレビュアーを作成できない場合は、ブロックします。使用するたびに、その記録をオーケストレーターの状態と PR の本文に残します。他の AI によるレビューであるかのように偽装してはいけません。状態の所有権を維持するため、spec-implement は使用ごとに構造化されたフォールバックレコードを 1 件、呼び出し元に返します。spec-orchestrate はこれらのレコードを状態と PR に追加します。パイプライン状態を書き込まないスタンドアロンの呼び出し元は、完了サマリーにそれらを表示します。

agent-delegate は公開コントラクト上の依存関係です。agent-delegate/references/contract.md に従ってスクリプトを呼び出し、必ず --target を明示的に指定してください（コントラクトのネストされたチェーンに関する注意事項により、プログラムからの呼び出しでは自己検出が禁止されています）。呼び出しの詳細、想定 run のポーリング、サンドボックスの各段階、再開、利用できないピアへのフォールバックについては、references/implement-guide.md → 「種別ベースのタスク振り分け」を参照してください。

フェーズ 7：最終品質ゲート

すべてのタスクが完了したら：

1. ワークフローのテストコマンド（または言語のデフォルト）を実行します
2. lint／型チェックコマンド（指定されている場合）を実行します
3. tasks.md のすべてのタスクにチェックが付いていることを確認します
4. いずれかのチェックが失敗した場合 → spec-code --feedback で修正し、再確認します

フェーズ 8：PR の作成

PR の本文は、監査ログ、仕様書、実装日誌ではなく、レビュー用のインデックスとして扱います。本文を作成する前に、リポジトリのプルリクエストテンプレートと PR 作成ルールを確認します。プロジェクトのテンプレートがある場合は、その見出し、順序、必須項目、チェックボックスを維持します。

削除すると、正確性、リスク、スコープ、検証、またはマージの可否に関するレビュアーの判断が変わる事実だけを選びます。変更された動作、設計上の理由、影響範囲、既知の制約、検証内容、レビュー時の注目点を要約します。レビューラウンド全体、すべての指摘、受け入れ基準の表、エビデンス一覧、タスクの進捗、調停の履歴は、永続化されるローカルの記録に保持し、PR の本文にそのままコピーしないでください。

プロジェクトのテンプレートがない場合は、次の役割を果たす見出しを使用します：概要、背景または理由、変更内容、検証、既知の制約、レビュー時の注目点。

gh pr create \
  --title "{type}: {description} (closes #{N})" \
  --body "{PR body following workflow template}" \
  --base {base_branch}

安全ガード：

• テストが失敗している場合は PR を作成しないでください
• force push を行ったり、main/master に push したりしないでください
• ベースブランチがワークフローに一致していることを確認してください

保留中の指摘：fix_before: trial / required_check / follow_up が付いたレビュー指摘ごとに、フォローアップ Issue を作成してください（gh issue create — 指摘内容、重大度、fix_before の段階、ファイル／セクション、PR へのリンクを記載します。同じ種類の指摘は 1 つの Issue にまとめてもかまいません）。Issue には指摘の全文を記載します。PR の本文には Issue のリンク、変更された動作への影響、フォローアップ前に現在の PR をマージできる理由のみを記載します。Issue の作成に失敗した場合、または gh が利用できない場合は、警告を添えて指摘の全文を PR の本文に記載してください。保留中の指摘を実行記録にしか残さない状態にしてはいけません。

レビューの代替対応によってレビューの確実性が低下した場合に限り、その内容を PR に要約します。優先されるレビュアーの役割と実際のレビュアーの役割、代替対応が発生した理由、マージ判断への影響を記載し、構造化された代替対応の記録をすべて貼り付けないでください。

エラー処理

状況	対応
git リポジトリではない	エラー：git リポジトリ内で実行する必要があります
gh CLI が利用できない	エラー：インストール／認証の手順をユーザーに案内します
.specs/ が見つからない	🚨 ブロック：ユーザーにパスを尋ねるか、spec-generator を提案します
requirement.md が見つからない	警告：要件として Issue の本文を使用します
tasks.md が見つからない	警告：Issue から簡単なチェックリストを生成します
保護されたブランチ上にいる	🚨 ブロック：処理を停止し、フィーチャーブランチを必須とします
ワーカースキルがインストールされていない	エラー：npx skills add anyoneanderson/agent-skills --skill {name} を提案します
有効な --host-runtime を指定せずに --roles が指定された	オーケストレーターに設定上のブロッカーを報告します。単独で実行している場合は、ユーザーに claude または codex を尋ね、推測しないでください
担当タスクにランタイムネイティブのサブエージェントを利用できない	オーケストレーターにブロッカーを報告し、手動／自動の役割フォールバックを適用してもらいます。単独で実行している場合は、AI の役割を再割り当てする前に確認してください
AI 間の実装で agent-delegate を利用できない（スクリプトがない／終了コード 2／tool_unavailable）	オーケストレーターにブロッカーを報告し、手動／自動の担当者フォールバックを適用してもらいます。単独で実行している場合は、ホスト AI に再割り当てする前に確認してください
AI 間のレビューで agent-delegate を利用できない	デフォルトの --review-fallback block では、ブロッカーとして報告します。明示的に native-independent が指定されている場合は、読み取り専用のホストネイティブな新規レビュアーサブエージェントを使用して、レビューの品質低下を記録します。そのサブエージェントも利用できない場合は、ブロックします
3 回の反復後もレビューが FAIL	ユーザーに判断を求めます
修正を試みてもテストが FAIL	ユーザーに判断を求めます

完了後のアクション

AskUserQuestion:
  question: "PR created. What's next?" / "PRを作成しました。次は？"
  options:
    - "Monitor CI status" / "CIステータスを監視"
    - "Done" / "完了"