ship-playbook について
ship-playbookは、計画から構築、検証までを1回で進めるソフトウェア開発向けエージェントスキルです。レビューや監査のゲートを選択でき、チェックポイントから再開できるため、修正の継続判断をユーザーに委ねるチームに適しています。
主な機能
- 01計画から検証までの単一ワークフロー
- 02ユーザーが選ぶレビュー・監査ゲート
- 03DAGタスク単位の構築とレビュー
- 04永続チェックポイントからの再開
- 05統合ツリーの最終検証
活用シーン
- 01単一の依頼から機能を開発
- 02未完了のビルドを再開
- 03検出事項を確認し修正ラウンドを判断
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ ulpi-io/ skills --skill ship-playbookインストール後、Claude Code で/ship-playbookを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
helpers/wf-status.mjsreferences/build-loop.mdharness-routing.mdplaybook-state.mdstatus-tracking.mdworkflow-template.js詳細
Inputs
$request:計画、構築、レビュー、リリースの対象となる機能プロンプトです。harness=codexやgolive=yesのようなオーバーライドを指定して、インテークに反映できます。修正ラウンドでは、前回の指摘をプロンプトとして渡します。 既存のレビュー済み DAG プランから 再開 するには、そのプランを指定します(例:resume .ulpi/plans/<name>.mdまたは--plan .ulpi/plans/<name>.json)。実行は計画とプランレビューをスキップして、ビルドから開始します。
Goal
1 つのプロンプトを、毎回同じ方法でリリース品質の成果物に仕上げます。デリバリープレイブックを、単一の実行可能なワークフローとして実行します。根拠に基づく DAG プラン、任意の創業者によるプランレビュー、DAG の各レイヤーにわたるタスクごとの実装(各タスクはユーザーが選んだ実行者が作成し、レビューします)、任意のプランと実装の照合レビュー、任意のリリース監査を行い、検証済みの指摘をフィードバックとして返します。実行は 1 回のみで、自動的にループすることはありません。指摘が残った場合、修正ラウンドを実行するかどうかはユーザーが決めます。
14 のステップはワークフローのフェーズに対応します。ステップ 3 → Plan · ステップ 4〜9 → Plan review(任意、回数制限付きループ) · ステップ 10〜11 → Build(タスクごとのレビューは任意) · ステップ 12 → Impl review(任意、プランと実装の照合) · ステップ 14 → Verify(重複排除 + 敵対的検証 → フィードバック) · ステップ 13 → Audit(goLive が有効で、ビルドと実装の検証に問題がない場合のみ)。スキルは最初にインテーク(依存関係の確認 + プロンプト + ゲート質問)を行います。各レビューゲートはユーザーが選んだ深さ(skip / native / codex / kiro)で実行され、自動的に再帰することはありません。ワークフローは指摘を返して終了します。
Phase 1 — Intake
Step 0 — MODE を決定する:新規実行か再開か(最初に行う)
スキルのモードは 2 つです。ほかのことをする前に、どちらかを判定します。
- NEW RUN(デフォルト — ユーザーが機能プロンプトを提示)。以下のインテーク全体(依存関係の確認 + ゲート質問 + スコープの根拠確認)を実施し、新しいステータスファイルを作成して、完全な
argsを指定して起動します。 - RESUME a previous run(ユーザーが「resume」「continue the build」と言う、
wf_…の runId を提示する、または既存の.ulpi/workflows/<id>.jsonを指定する)。インテークをやり直したり、ステータスファイルを上書きしたりしないでください。代わりに、リポジトリのルートからnode <skill-dir>/helpers/wf-status.mjs --resume [<runId>]を実行します。実行ステータスファイルを読み込み、再起動用の正確なWorkflow({ scriptPath, args })を出力します。そこには、すでにplanPath(再計画をスキップ)、checkpointResume:true(完了済みタスクをスキップ)、同じstatusFileが含まれています。その内容をそのまま起動してください。永続チェックポイントにより、セッションに依存せず再開できます(resumeFromRunIdは不要)。ビルドでは残りのタスクだけを再構築します。(--resumeがlaunchArgsの欠落を警告する場合は、v1.7.0 より前の実行です。不足しているvalidate/hardRulesを指定してください。ステータスファイルがまだない場合は、先に--writeを実行してください。)その後、フェーズ 3 の報告に進みます。
フェーズ 1 の残りは NEW-RUN の手順です。
Step 1 — 依存関係の確認とセットアップ(最初に行う)
ほかのことをする前に、このスキルの効果を最大限に高めるために必要なもの、すでにあるもの、不足しているものを、コピー&ペーストできるインストールコマンドとともにユーザーに伝えます。ship-playbook はほかのスキルを組み合わせ、専門エージェントに振り分けます。インストール済みのものが多いほど、よりよい結果が得られます。
検出方法 — 2 つではなく 3 つの状態。 スキルは Claude の起動時にのみ利用可能なスキル一覧に読み込まれ、エージェントは subagent_type の選択肢に読み込まれます。そのため、「ディスク上にインストール済み」でも「このセッションで使用可能」とは限りません。各項目を分類してください。
- 準備完了 — 読み込み済みの利用可能なスキルリスト/
subagent_typeオプションにあります。すぐに使用できます。リストには載せないでください。 - インストール済み、再起動が必要 — 読み込み済みのリストにはありませんが、ディスク上に存在します。ディスクの確認にはシンボリックリンクを考慮してください(スキルは共有ストアへのシンボリックリンクとして登録されています。例:
.claude/skills/map-project → ../../.agents/skills/map-project)。ls -laL .claude/skills/<name>またはtest -e .claude/skills/<name>(シンボリックリンクをたどります)を使用してください。find -type dは使用しないでください(シンボリックリンクを黙って見落とします)。 これらは「インストール済み — 読み込むには Claude を再起動」と報告し、インストールコマンドは表示しないでください(すでにインストール済みです)。 - 未インストール — 読み込み済みリストになく、ディスク上にもありません。完全なインストールコマンドを表示してください。
読み込み済みリストは、現在使用可能なものの唯一の判断基準です。シンボリックリンクを考慮したディスク確認は、「インストール済みだが未読み込み(再起動)」と「本当に未インストール」を区別するためだけに行います。そのため、インストール済みで未読み込みのスキルを、単に「未インストール」と誤って表示することはありません。妥当性チェック:明らかに存在するスキル(たった今使ったものなど)を未インストールと報告する場合、確認方法に問題があります。外部の kiro-cli バイナリに対するディスク/PATH の確認は別途行います(下記を参照)。
プロジェクトのスタックを検出し、検出したスタックに応じて、読み込み済みリストを照合し、以下の各項目の有無を確認してください。
- 複合スキル —
plan-to-task-list-with-dag、plan-founder-review、go-live-audit、map-project/map-project-monorepo。 - このスタック向けの専門エージェント — ビルドで割り当てるエンジニアとレビュアーのペア。レビュアー名はエンジニア名の完全な名前に
-reviewerを付けたものです(省略形ではありません)。例:nextjs-senior-engineer+nextjs-senior-engineer-reviewer、go-senior-engineer+go-senior-engineer-reviewer、laravel-senior-engineer+laravel-senior-engineer-reviewer。正確な登録名を使用してください。nextjs-reviewer/go-reviewerのように短縮しないでください。不足している場合はgeneral-purposeが使われ、品質が低下します。 - スタック用スキル — 検出したスタックに応じて、
/nextjs、/laravel、/rustなど。 - 任意のハーネスツール(ユーザーが codex/kiro を選ぶ可能性がある場合のみ):codex プラグイン
(
codex:codex-rescue)、kiro の場合は CLI と、レビュー用のkiro-reviewスキル、およびビルド用のhand-over-to-kiroスキル。kiro CLI の検出には、次の2点に注意してください。- バイナリ名は
kiroではなくkiro-cliです(kiroだけの場合、通常は CLI ではなく Kiro IDE のシンボリックリンクです)。kiro-cliを確認してください。 - 多くの場合、
~/.local/binにあり、サンドボックス化された Bash の PATH に含まれていないことがあります。そのため、インストール済みでもcommand -v kiro-cliの結果が空になる場合があります。場所に依存しない方法で確認してください。例:command -v kiro-cli || ls ~/.local/bin/kiro-cli ~/.kiro/bin/kiro-cli /usr/local/bin/kiro-cli 2>/dev/null。 また、実行できることを確認してください(kiro-cli --version)。ドキュメント:https://kiro.dev/docs/cli。
- バイナリ名は
表を2つ、スキル用とエージェント用に分けて提示し、「準備完了」以外の項目(「未インストール」または「インストール済み、再起動が必要」)だけを記載してください。「準備完了」の項目は一切記載しないでください(「存在/準備完了」のセクションも作成しません)。各行に項目、状態、対応を記載してください。
- 状態 = インストール済み、再起動が必要 → 対応:「読み込むには Claude を再起動」(ディスク上にすでにあるため、インストールコマンドは表示しません)。
- 状態 = 未インストール → 対応:コピーしてそのまま実行できる完全なインストールコマンド。
- スキル →
npx skills add https://github.com/ulpi-io/skills --skill <name>(複合スキル、スタックスキル、kiro の補助スキルkiro-review/hand-over-to-kiro)。kiro-cli自体は、そのドキュメントへのリンク https://kiro.dev/docs/cli を表示します。 - エージェント →
npx agentshq add ulpi-io/agents@<agent-name>。各行で正確な登録名を使用してください。例:…@nextjs-senior-engineerおよび…@nextjs-senior-engineer-reviewer(レビュアー名はエンジニア名の完全な名前に-reviewerを付けたものです。…@nextjs-reviewerのように短縮しないでください)。
- スキル →
表に「準備完了」以外の項目がない場合、その表は省略してください。その後、AskUserQuestion を使って2つの選択肢を提示してください。
- インストール済みのもので続行します(不足している専門エージェントは
general-purposeにフォールバックし、不足しているハーネスオプションは提示されません)。 - インストールしてから再起動します:ユーザーが一覧にある項目をインストールした後、Claude を再起動し(新しくインストールしたスキル/エージェントは起動時にのみ読み込まれます)、
/ship-playbookを再実行します。再起動後に戻って再度呼び出すよう伝えてください。
利用可能な項目を記録してください。これは availableAgents に反映され、提示するインテークオプションを制限します。
ステップ 2 — ワークフローのゲート質問(最初に尋ねる)
プロンプトは $request です。実行順に沿って、実行の流れのように読める形で、7 つのゲート質問を(AskUserQuestion を 2 回に分けて、各回最大 4 問)尋ねます。ただし、すでに $request で指定されている場合は尋ねません。
RESUME モード。 $request が既存のレビュー済みプラン(.ulpi/plans/<name> パス)を示している場合、またはユーザーが再開を求めている場合、実行は BUILD から始まります。ゲート質問 1(プランを誰が作成するか)と 2(誰がレビューするか)は、すでに完了しているため省略し、残り 5 問(コード作成者、コードレビュアー、実装レビュー、Go-Live、マップ)のみ尋ねます。続行する前に、プランの .json を読み込み、適切な形式であること(id / agent / writeScope / validate を含む tasks[] と layers[][])を確認します。形式が不正、または古い場合は、その旨を伝え、再開の代わりにプランを作成し直すことを提案します。
これらのゲート質問は、最初に尋ねます。 依存関係の確認(ステップ 1)の直後に尋ねてください。スコープや機能を明確にする質問(「プラットフォーム全体ですか、それとも API だけですか?」「どの SSO プロトコルですか?」など)を先に尋ねてはいけません。プロンプトがスコープを示しています。範囲が広い、または曖昧な場合は、ステップ 3(ゲート質問の後)で前提を確認するか、プランニング中にプランフェーズでスコープに異議を唱えさせます。ゲート質問より前に質問を重ねてはいけません。ユーザーはまずワークフローの設定を求めています。
各役割は、それぞれ独立して実行者を選びます(各作成と各レビューは別々です。codex で作成し、kiro でレビューしてもかまいません)。ステップ 1 でインストール済みと確認されたツールが使える役割に限り、codex / kiro を提示します。トークンコストを抑えるため、デフォルトは LIGHT です。ユーザーはそれぞれを最高水準の厳密さに引き上げたり、省略したりできます。
選択肢の順序ルール: 最初に native を提示し(Recommended / default と表示)、次に codex、その次に kiro を提示します。skip は最後の選択肢として提示してください(その場合、自動追加される「Other」の直前、つまり後ろから 2 番目に表示されます)。プラン作成とコード作成は省略できません(必ず実施します)。4 つの任意ゲート(プランレビュー、コードレビュー、実装レビュー、Go-Live 監査、マップ)には、それぞれ skip を含めます。
- プランを作成するのは誰か — DAG の分解:
native(プランから DAG 付きタスクリストを作成 — デフォルト)、codex、またはkiro。planHarnessとして渡します。(省略不可 — プランは作成する必要があります。) - プランをレビューするのは誰か — 創業者によるレビュー(スコープ、分解、実体のないパス):
native(デフォルト)、codex、kiro、またはskip。planReviewとして渡します。 - コードを作成するのは誰か — すべてのタスクとその修正:
native(プランに対応する専門エンジニアエージェント — デフォルト)、codex、またはkiro。buildHarnessとして渡します。(省略不可。) - コードをレビューするのは誰か — ビルドループで作成した各タスク:
native(対応する-reviewer— デフォルト)、codex、kiro、またはskip(タスクごとのレビュアーや修正ループなし — 最大のトークン節約)。taskReviewとして渡します。 - すべてのタスク完了後の実装レビュー — プランと実装の照合レビュー:
native(デフォルト)、codex、kiro、またはskip。implReviewとして渡します。 - Go-Live 監査を実行する —
run(Go-Live 監査。ビルドと実装レビューの両方が検証済みで問題なしの場合のみ実行)またはskip(デフォルト)。goLiveとして渡します(run → true)。 - 最後に map-project を実行する —
map-project、map-project-monorepo、またはskip(デフォルト)。リポジトリの構成を検出し、対応するバリアントを推奨します。mapRefreshとして保持します。これは Workflow の引数ではありません(argsオブジェクトに含まれません)。SKILL は、実行が中断されていない場合に限り、Workflow の終了後、フェーズ 3 で選択されたマップスキルを実行します。
デフォルト(安全性を保ちながら軽量化):planHarness native、planReview native、buildHarness native、taskReview native、implReview native、goLive skip、map skip。ユーザーはすべてを徹底する(すべてのレビューを有効にし、必要に応じて codex / kiro を使い、Go-Live も有効にする)、作成とレビューをハーネスに委任する(作成/レビューの任意の役割に codex|kiro を指定。作成者とレビュアーには異なるハーネスを指定可能)、またはレビューを省略して高速化できます。taskReview skip と implReview skip の両方が選択された場合は、警告してください(ブロックはしないでください)。その場合、ビルドを確認するものがないため、問題なしという判定が意味するのは、エンジニアによる検証が通過したことだけです。
ステップ 3 — スコープの把握、プロジェクト情報、Git の事前確認、エージェント一覧
ゲート質問の後で、スコープを把握します。 リポジトリを読み、何があるかを確認します。
$request が広範または曖昧な場合(例:「SSO 対応のセルフホスト可能な SaaS プラットフォーム」)は、ここで範囲を絞ります。リポジトリからスコープを推測することを優先し、実際に作業を進められない場合に限って、焦点を絞った質問をしてください。または広範なプロンプトをそのまま渡し、計画フェーズでスコープを再検討します。解決したスコープを、args で渡す prompt に含めてください。
ワークフローに必要な情報を集めます(ユーザーには尋ねず、リポジトリを確認してください)。root(リポジトリの絶対パス)、workingBranch(確認なしに保護ブランチ上でビルドしないこと)、validate(ワークスペースの型チェック+Lint+テストのコマンド)、hardRules(ルートの CLAUDE.md/仕様に記載された、必ず守るべき不変条件)です。
root が Git ワークツリーであることを確認します — git -C <root> rev-parse --is-inside-work-tree は true を出力し、workingBranch には少なくとも 1 つのコミットが存在する必要があります。ビルドではタスクブランチを作成してマージするため、Git 管理されていないフォルダー(またはコミットのないブランチ)ではビルドできません。root が Git リポジトリでない場合は、停止してユーザーに伝えてください。git init とベースラインコミットを行うか、パスを修正するよう提案し、起動しないでください。
availableAgents(ステップ 1 で確認した、ここに存在する専門エンジニアと -reviewer の名前)と、allowGeneralFallback(ユーザーが「不足があっても続行」を選んだ場合のみ true)を Workflow の args に渡してください。計画ではこのリストに含まれるエージェントのみが割り当てられます(インストールされていないエージェントは指定できません)。Workflow は、なお不足しているものがあれば missingAgents を返します。ステップ 1 で不足をユーザーに示すことなく、専門エージェントの代わりに general-purpose を黙って割り当てないでください。
既存の計画から再開する場合は、ここで計画も解決してください。.ulpi/plans/<name>.json を読みます(.md はここから生成されます)。DAG の構造(id/agent/writeScope/validate を含む tasks[]、および非循環の layers[][])を検証し、planPath(パス)または解析済みの plan オブジェクトを args に渡してください。再計画はしないでください。Workflow が読み込んで検証し、計画と計画レビューの両フェーズをスキップします。計画が見つからないか、形式が不正な場合は停止し、計画を作成(または再作成)することを提案してください。
references/playbook-state.md のフェーズを反映したマスター TodoWrite を作成します。
成功条件:依存関係の状態が表示され、ユーザーが続行または再起動を選択していること。planHarness、planReview、buildHarness、taskReview、implReview、goLive、mapRefresh、root(Git ワークツリーであることを確認済み)、workingBranch、validate、hardRules、availableAgents(不足がある場合は allowGeneralFallback も)がすべて解決されていること。
フェーズ 2 — プレイブックの Workflow を実行する(ステップ 3〜14)
goLive == yes の場合は、最初に go-live 監査を作成します。ステップ 13 で簡易的な確認ではなく、実証済みの監査を組み立てられるようにするためです。go-live-audit スキルを実行して、プロジェクトに合わせた監査ワークフローを生成し、Workflow ツールがそのために保存する scriptPath を取得します。そのパスを auditScriptPath として渡してください。(これを省略した場合、ステップ 13 ではインラインの検出処理にフォールバックします。)
最初に、実行中ステータスファイルを作成します(Workflow のサンドボックスにはファイルシステムへのアクセスがないため、SKILL が作成する必要があります)。workflowId を ship-<UTC timestamp>-<short-slug-of-the-prompt> の形式で選びます(例:Bash の date -u +%Y%m%dT%H%M%SZ を使用)。statusFile = <root>/.ulpi/workflows/<workflowId>.json(絶対パス)を設定し、実行開始と同時に監視側が検知できるよう、初期ドキュメントを書き込みます。
再開時 — 既存のステータスファイルを上書きしないでください。 ビルドは CHECKPOINT RESUME に対応しています。ステータスファイルを読み取り、すでに完了とマークされたタスク(passed/integrated/reviewing/fixing/blocked)をすべてスキップし、残りのタスクだけを再構築します。そのため、前回の実行から再開する場合は、既存の <root>/.ulpi/workflows/<id>.json を再利用し、同じ workflowId/statusFile を渡してください。新しい pending のみのドキュメントで上書きしてはいけません。チェックポイントが失われ、すべてが再構築されます。初期ドキュメントを書き込むのは、まったく新しい実行の場合だけです。
{ "schemaVersion": 1, "workflowId": "<id>", "skill": "ship-playbook", "status": "initializing",
"prompt": "<prompt>", "root": "<root>", "workingBranch": "<branch>", "createdAt": "<UTC now>",
"config": { "planHarness": "...", "planReview": "...", "buildHarness": "...", "taskReview": "...",
"implReview": "...", "goLive": false },
"plan": null,
"phases": { "plan": {"status":"pending"}, "plan_review": {"status":"pending"},
"build": {"status":"pending"}, "impl_review": {"status":"pending"},
"verify": {"status":"pending"}, "audit": {"status":"pending"} },
"tasks": {}, "openRegister": [], "result": null }
次に、intake を args として渡し、Workflow ツールで references/workflow-template.js を起動します。
Workflow({ scriptPath: ".../references/workflow-template.js",
args: { prompt, root, workingBranch, validate, hardRules, goLive,
planHarness, planReview, buildHarness, taskReview, implReview,
auditScriptPath, availableAgents, allowGeneralFallback, warmWorktree,
planPath, kiroModel,
workflowId, statusFile, trackStatus, checkpointResume } }) // planPath → RESUME at build;
// workflowId/statusFile → live .ulpi/workflows/<id>.json
// (trackStatus:false disables); checkpointResume:false →
// force a full rebuild (default true: skip done tasks);
// warmWorktree:false → plain per-worktree install
// (default true: CoW-seed node_modules/vendor/Pods; Rust uses kache or CoW-seeds target/)
起動後、run id と起動引数全体を記録します。 Workflow ツールは runId(wf_…)をすぐに返します(バックグラウンドで実行されます)。Bash+jq を使って、runId、status:"running"、そして重要な点として、launchArgs(直前に渡した args オブジェクトそのもの。prompt、root、workingBranch、validate、hardRules、すべての harnesses、goLive などを含みます)をステータスファイルに書き込みます。
jq --argjson la '<the args object>' '. + {runId:"<runId>", status:"running", launchArgs:$la}'
これにより、ステータスファイルは自己記述型の決定論的な再開元になります。wf-status.mjs --resume は launchArgs をそのまま読み戻すため、同一の設定で再起動できます(手動で組み立てる必要も、設定がずれることもありません)。
前回の実行を再開しますか?wf-status.mjs --resume を使い、引数を手動で組み立てないでください。 リポジトリのルートから、次を実行します。
node <skill-dir>/helpers/wf-status.mjs --resume [<runId>] は実行のステータスファイルを読み取り、再起動用の正確な Workflow({ scriptPath, args }) を出力します。これには、再計画を省略する planPath、完了済みタスクをスキップする checkpointResume:true、および同じ statusFile がすでに含まれています。そのまま起動してください。永続的なステータスファイルのチェックポイントにより、再開はセッションに依存しません。resumeFromRunId は必要ありません。(実行が v1.7.0 より前のもの、または launchArgs がない場合、--resume は警告を表示します。その場合は、不足している validate/hardRules を指定してください。まず --write [<runId>] を実行すると、ジャーナルからステータスファイルを補完できます。)
mapRefresh は意図的に args に含めていません。Workflow が実行しない intake の回答はこれだけです。マップの更新では、完了したコードから CLAUDE.md を再生成するため、Workflow の戻り後、Phase 3 でスキル自身が実行します(Q7 を参照)。その他のゲートの回答はすべて、上記の args に含めます。
args は JSON 文字列ではなく、実際の JSON オブジェクトとして渡してください。 文字列化されたデータはスクリプトに単一の文字列として渡され、typeof args === 'object' のチェックに失敗します。その結果、すべての入力が FILL: プレースホルダーに黙って置き換わります。スクリプトは偽の converged:true を返さず、そこでエラーをスローするため、文字列化した引数で起動すると明確にエラーになります。その場合は、再開ではなく、args をオブジェクトとして新規実行してください。(各ロールの引数は無効な場合、安全なデフォルト値に変換されるため、タイプミスがあっても正常に処理されます。)
その後、Workflow はプレイブックを一度に実行し、ユーザーが選択したレベルで各ゲートを実行します。
- 計画(ステップ 3) — プランナー(
planHarnessに応じて native/codex/kiro)が、計画を DAG 付きのタスクリストにする手法に従って無人で実行します(モードは自動選択)。すべてのパスを実際のリポジトリに基づいて確定し、各タスクに専門エンジニア+-reviewer+スタックのスキルを割り当て、.ulpi/plans/<name>.md+.jsonを書き込み、{tasks, layers}を返します。再開:planPath/planが指定されている場合、このフェーズでは代わりにレビュー済みの計画を読み込みます(エージェントが読み取り、検証し、正規化します。再計画は行いません)。計画レビューはスキップされ、ビルドから再開します。 - 計画レビュー(ステップ 4~9) —
planReview(skip/native/codex/kiro)に応じたレビュー担当者が実行します。1 回の上限付きループで計画を修正し(JSON を優先し、MD を再生成。修正は常に native)、再レビューします。BLOCK/CONCERN がなくなった場合(OBSERVATION はブロックしません)、または収束しない場合に終了し、上限はMAX_REVIEW(2)です。 - ビルド(ステップ 10~11) — DAG の各レイヤーを順に処理します。タスクごとに、エンジニア(worktree、タスクブランチ)→ ワークフロー内の統合エージェント(
git mergeで作業ブランチにマージし、マージした worktree を順次削除)→ レビュー担当者(taskReview skipでない場合)と進み、合格するまで上限付きの修正ループを実行します。各レイヤーの間にはバリアがあります。新しい worktree はそれぞれ高速にプロビジョニングされます(warmWorktree、デフォルトで有効)。計画と並行して一度だけウォームアップを行い、キャッシュを準備します。その後、ロックファイルに変更がなければ、エンジニアはプライマリチェックアウトからnode_modules/vendor/Podsを CoW クローンします(Rust ではkacheを使ってクレートのコンパイルを共有します。kacheはパスに依存しないハードリンクベースの rustc-wrapper キャッシュで、.cargo/config.tomlで設定されており、worktree でtarget/をクローンする代わりにコンパイル済みクレートを復元します。kacheがない場合は、ウォーム済みのtarget/を CoW でシードします)。これができない場合は、通常の凍結インストールにフォールバックします。warmWorktree:falseの場合は、worktree ごとに通常のインストールを行います。エンジニアのルートはbuildHarnessに応じ、レビュー担当者のルートはtaskReviewに応じます。両者は独立しています(codex で作成し、kiro でレビューしても問題ありません)。ビルドと検証の並列処理には同時実行数の上限を設けているため、DAG レイヤーのタスク数が多い場合や指摘事項のリストが長い場合でも、Claude の API レート制限に達するのを防げます。同時に実行される worktree エンジニアは最大MAX_BUILD_PARALLEL(4)、レビュー担当者/検証担当者は最大MAX_PARALLEL(6)です。エージェントの総数は変わらず、同時実行数だけが制限されます。429 エラーが発生する場合はreferences/workflow-template.jsのこの 2 つの定数を小さくし、上限の高いアカウントの場合は大きくしてください。1~2 には設定しないでください。上限を設定してもエージェントがレート制限を受ける場合(空の結果を返す、または処理の途中で打ち切られる)、ブロックとして記録する前に指数バックオフで再試行されます(RETRY_DELAYS、最大 4 回)。これにより、レート制限の連続発生が誤った「ブロックされたタスク」のノイズになることはなくなります。 - 実装レビュー(ステップ 12) —
implReview(skip/native/codex/kiro)に応じたレビュー担当者が実行します。ビルドしたすべての内容について、計画と実装を照合してレビューします。 - 検証(ステップ 14) — ビルドと実装レビューの指摘事項を重複排除し、敵対的な観点から検証します。これらはフィードバックとして返される
openRegisterになります。自動で再計画/再ビルドは行わず、ワークフローは結果を返して停止します。 - 監査(ステップ 13) —
goLiveが有効で、ビルドと実装レビューの両方が検証済みかつ問題なしの場合にのみ実行します。実証済みのgo-live-auditワークフローをworkflow()フック(auditScriptPath)経由でインラインに実行します。ゲート → 検出 → 重複排除 → 2 つの観点からの検証 → 批評を実行し、∥ 第 2 のハーネスによる監査レーンも実行します。その指摘事項がopenRegisterになります。 進捗は3つの方法で確認できます。/workflowsパネル(ライブのエージェントツリー)、ステータスファイル (cat <root>/.ulpi/workflows/<id>.json— 全体、フェーズごと、タスクごとのステータス)、または同梱のリーダーnode <skill-dir>/helpers/wf-status.mjs(実行のジャーナルからタスクごとのステータスを直接再構築します — 実行中でも、ステータス追跡がオフでも機能します)。references/status-tracking.mdを参照してください。スクリプトを反復実行するには、ツールが返した保存済みのscriptPathを編集して、{scriptPath}を指定して再実行します(キャッシュ済みのエージェント結果を再利用するにはresumeFromRunIdも指定します)。resumeFromRunIdを渡す場合は、毎回同じargsオブジェクトも渡してください。キャッシュ済みの エージェント 結果は再利用されますが、スクリプトは先頭から再実行されるため、argsを省略するとCFGが空になり、FILL:ガードでスクリプトが強制終了します。最初に起動したときのargsオブジェクト全体(workflowId/statusFileを含む)を必ず渡してください。スクリプトを反復実行するのではなく、以前の実行を再開する場合は、代わりにwf-status.mjs --resumeを使用してください — 下記の resume 動詞を参照してください。必要なargs全体が引き継がれます。
成功条件:ワークフローが最後まで実行され、次の値を返すこと。
{ converged, ranReal, plan, planSupplied, build, openRegister, missingAgents, reviewConfig, noReviewGate, planReviewRan, implReviewRan, taskReviewDowngraded, auditRan, workspaceValidatePassed, endStateUngated, blockedTaskCount, workflowId, statusFile }
フェーズ 3 — 報告とエスカレーション
ワークフローの結果を読み取ります。
- まず、実際に実行されたことを確認してください。偽のクリーン判定ではありません。 結果が
ranReal: false(またはabortedメッセージ)の場合、入力はスクリプトに渡されていないか(または 事前チェックに失敗しています)。その失敗を報告し、argsを実際の JSON オブジェクトとして指定して再実行(新規実行)してください。convergedを意味のある結果として扱わないでください。 missingAgentsが空でない場合、割り当てられた専門エージェントがここにインストールされていないため、一部のタスクはgeneral-purposeで実行されました。ユーザーがインストールして品質向上のために再実行するかどうかを判断できるよう、 該当するエージェントとインストール方法を提示してください。noReviewGate: trueの場合(ユーザーがタスクごとのレビューと実装レビューの両方をスキップした場合)、クリーン判定には必ず 注意書きを添えてください。これはエンジニアの検証に合格したことだけを意味し、ビルドは何もレビューされていません。 どのゲートが実行されたかユーザーが確認できるよう、reviewConfigを報告してください。- ゲートの誠実性 — 設定されたゲートが実際には実行されなかった場合、決して「クリーン」としてはいけません。 Workflow はゲートが失敗したときに
openRegisterを空でない状態に保つため、convergedは false になりますが、原因を報告して理由をユーザーに伝えてください。planReviewRan === false/implReviewRan === false→ 設定されたプラン/実装レビュアーを実行できませんでした (例:kiro CLI がありません)。taskReviewDowngradedが null 以外 → 要求されたタスクごとのレビュアー (例:codex)をここで実行できず、native にダウングレードされました({requested, ranAs}が表示されます)。タスクは (native で)レビュー済みですが、要求されたレビュアーが実行されなかったことを伝えてください。auditRan === false→ go-live 監査が失敗しました (起動は未確認です)。workspaceValidatePassed === false→ 統合済みツリーに対する最終的なvalidateが RED です (型チェック/lint/テストは行いません — 最も重大なブロッカーです)。endStateUngated === true(実装レビューをスキップ) → ツリーがコンパイルできても、コードベース全体の意味的な最終状態がゲートで検証されていないことに注意書きを添えてください。 blockedTaskCount > 0→ その数のタスクが合格しませんでした(エンジニアの失敗、レビューによるブロック、または上流の依存関係が統合されなかったためのdep_blocked—blocked on dependency <X>という理由は ROOT を指しています)。これらはopenRegisterに含まれています。 理由とともに提示してください。- 既存の失敗の帰属。
build[]のエントリにはpreexistingNoteが含まれることがあります。そのスライスは正しく統合されていますが、検証が RED だったのは、 担当範囲外の既存の失敗のみが原因です(ビルドはこのような正しい作業を破棄しなくなりました。エンジニアは新規の失敗と既存の失敗を ベースと照合して自己分類します)。また、workspaceValidatePassed === falseの場合、workspace-validateマーカーは、この実行で 発生した失敗(実際のブロッカー)と、ベースに既存の失敗(別の担当タスクが必要で、この実行が原因ではないもの)を区別し、 ステップごとの[steps: typecheck=pass, lint=FAIL, …]内訳を示すようになりました。この区分を提示し、ユーザーが適切な問題を修正できるようにしてください。 また、ツリーが引き継いだ不具合によって RED になった、スライスは正常なビルドを正しく読み取れるようにしてください (作業は保持され、実際の原因が示されるため、「ビルドが壊した」と誤解されません)。 planSupplied: trueの場合、実行はレビュー済みプランから再開されました。設計上、プランニングとプランレビューはスキップされています。 クリーン判定が「プランがレビューされなかった」と誤解されないよう、そのことを伝えてください。converged: true(実際の実行で、openRegisterが空)→ 完了です。タスクごとのビルド結果、 (reviewConfigに基づく)レビュー/監査の判定、およびプランの最終結果を報告してください。openRegisterが空でない → フィードバックを提示し、次の対応をユーザーに判断してもらってください。検証済みの BLOCK/CONCERN の指摘事項(ファイル:行、問題、推奨される修正、検出したゲート)を一覧にしてください。その後、次の手段を提示してください。 修正ラウンドを実行する(指摘事項をプロンプトとして指定し、同じインテークでワークフローを再呼び出しする)、 手動で修正する、またはリスクを受け入れる。ワークフローは自動ではループしません。未解決の指摘事項をクリーンとして示してはいけません。 ワークフローは最終状態をすでに<root>/.ulpi/workflows/<id>.jsonに書き込みました(status=done/needs_fix/aborted、タスクごとの結果、openRegister)。これを読み込んでレポートを補足し、保存場所をユーザーに伝えてください。これは今回の実行を記録した永続的な記録です。実行が途中で終了した場合(最終書き込みがない場合)は、レポートする前にnode <skill-dir>/helpers/wf-status.mjs --writeでジャーナルからファイルを更新してください。
ライブステータス、停止、再開 — 3つの操作はいずれもステータスファイルと実行ジャーナルに基づいています。
- status →
cat <root>/.ulpi/workflows/<id>.json(またはnode <skill-dir>/helpers/wf-status.mjs)— 全体のステータス、現在のフェーズ、各タスクの状態(pending → in_progress → dev_done → integrated → passed/blocked)をひと目で確認できます。 - stop → 実行に
TaskStopを行うか、/workflowsパネルを使います。何も失われません。ジャーナルには完了したすべてのエージェントがキャッシュされています。 - resume → リポジトリのルートから
node <skill-dir>/helpers/wf-status.mjs --resume [<runId>]を実行し、表示されたWorkflow({ scriptPath, args })をそのまま起動します。保存済みのlaunchArgsをplanPath(再計画をスキップ)、checkpointResume:true(完了済みの作業をスキップ)、同じstatusFileとともに再実行します。これは、完全なargsを引き継ぐ、セッションに依存しない新しい実行です。これが正式な再開方法です。resumeFromRunIdだけで再開しないでください。キャッシュ済みのエージェント結果は再利用しますが、スクリプトは先頭から再実行され、新しいセッションではargsが引き継がれず、CFGが空になり、FILL:ガードでスクリプトがハードエラーになります(旧バージョンでは何もしないフェイククリーンパスが実行されていました)。キャッシュを再利用するためにスクリプトを反復作業するときに限りresumeFromRunIdを使い、その場合も同じ完全なargsオブジェクトを必ず渡してください。
v1.5.0 より前に起動した実行(ステータスファイルなし)の場合、ジャーナルからファイルを補完します。
node <skill-dir>/helpers/wf-status.mjs --write [<runId>] — 計画、ブランチ、タスクリストとステータス、競合を復元します。ジャーナルには起動時の引数がないため、resume の手順を完成させるには --args '{…gate config + validate…}'(起動したセッションだけが把握しています)を追加してください。references/status-tracking.md を参照してください。
次に、ユーザーが受付時にプロジェクトマップの更新を選択し、かつ実行が実際に行われた(ranReal が真で、中止されていない)場合は、最後に更新します — 選択されたスキル(map-project または map-project-monorepo)を実行し、ビルドで反映されたコードを CLAUDE.md のコンテキストマップに反映してください。中止された実行、または実際にはクリーンではなかった実行では、マップを更新しないでください(新たにマップする内容はありません)。レポートの後に行う最後の手順です。
成功条件:有効にしたゲートが実際にクリーンである(reviewConfig/noReviewGate による注記を付す)か、残っている阻害要因と次の対応を正直にユーザーへ提示していること、永続的なステータスファイルに最終状態が反映されていること、そして要求されている場合はプロジェクトマップが更新されていること。
ガードレール
- 積極的に実行しないでください。これは明示的なユーザー操作があった場合のみ実行します(ラウンドごとに多数のエージェントを起動するためです)。
- ワークフローは1回だけ実行し、自動で繰り返すことはありません。修正ラウンドはユーザーが意図的に選択します(指摘事項をプロンプトとして再実行します)。レビューのゲートは実行ごとにユーザーが選択します。ユーザーの
planReview/taskReview/implReviewの選択に従い、タスク単位レビューと実装レビューの両方がスキップされる場合は、ブロックせず警告してください。ワークフローが担当するのはステップ3~14です。スキルが担当するのは、インテーク(依存関係の確認と質問)およびフェーズ3のレポートです。 - プランを手作業で作成しないでください。ワークフローのプランフェーズは、plan-to-task-list-with-dag の手法に従い、各タスクに専門エージェントを割り当てます。
- ビルドでは、各タスクに対して利用可能な専門エージェントのうち最適なものを割り当てます。専門エージェントが不足していることをユーザーに通知し、同意を得た場合に限り、
general-purposeを代わりに使用します(黙って代用しないでください)。スタックのスキルがインストールされている場合、エンジニアは必ずそれを使用してください(/nextjs、/laravel、/rustなど)。 - クリーンな判定を捏造しないでください。未解決の BLOCK/CONCERN 指摘は隠さず、フィードバックとして返してください。
- ワークフローは1回だけ実行し、自動で繰り返すことはありません。修正ラウンドはユーザーが意図的に選択します(指摘事項をプロンプトとして再実行します)。自律的な再帰処理を再導入しないでください。
- エージェントへのブリーフにシークレットやトークンを渡さないでください。値は伏せ、保存場所を参照してください。
workingBranchの明示的な確認を得ずに、保護されたブランチ上でビルドしないでください。- Git 管理されていないフォルダーや空のリポジトリではビルドを起動しないでください。ビルドではタスクブランチを作成してマージするため、コミット済みの
workingBranchを持つ Git ワークツリーが必要です。 - ビルド用ワークツリーがゲートに悪影響を及ぼさないようにしてください。ワークフローはビルドのチェックアウト先である
.claude/worktrees/を、プリフライト時、各統合後、および終了時に削除します。また、統合時の検証で.claude/worktrees/**や兄弟のエージェントディレクトリをスキャンしてはいけません。実行中にタスクの範囲外のファイルが原因でゲートが失敗した場合は、コードを疑う前に、残存するワークツリーを疑ってください。 - DAG に従い、依存関係が統合される前にタスクをビルドしないでください。ビルドはバリアを設けてレイヤーごとに統合するため、正確性はプランでタスクが正しく順序付けられているかに左右されます。各タスクの
dependsOnがすべて完了しており、layersがトポロジカル順序になっている必要があります(各タスクは、依存するすべてのタスクより後に配置します)。プランフェーズでdependsOnを設定し、プランレビューでは不完全または順序が誤ったグラフを BLOCK します。ビルドのvalidatePlanは、レイヤーがdependsOnに違反するプランを ABORT し、壊れたベース上でのビルドを防ぎます。他のタスクの出力(カタログ/レジストリの行、マイグレーション、ルート、エクスポートされたシンボル、別のタスクが拡張するテストなど)を必要とするタスクが先に実行される場合、それは PLAN の不備です。順序を修正し、実行時の再試行で取り繕わないでください。2つの要素がそれぞれ独立して検証できない場合は、1つのタスクにまとめてください。各タスクのvalidateはスライス単位の範囲に限定してください(そのスライスと依存関係が統合された時点で成功できるようにし、最終状態でしか通らないスイート全体の e2e にしないでください)。 - タスク単位レビューはスライス単位であり、最終状態のゲートではありません。タスク単位の BLOCK が有効なのは、そのタスクの writeScope 内に不備がある場合に限られます。後続タスクが担当するコードベース全体の不変条件が未達の場合(まだ削除されていないレガシーパス、まだ作成されていないルート/リンク/コンシューマーなど)、それはそのタスクに帰属する OBSERVATION であり、現在のスライスに対するブロッカーにしてはいけません。また、修正ループにも含めないでください。最終状態は、実装レビュー(ステップ12)と統合ワークスペースでの検証によって担保されます。「ブロックされたタスク」の件数が多い場合は、スライスが壊れていると判断する前に、ブロックが他のタスクの担当する最終状態の未達によるものかを確認してください。
- ステータスの追跡は、失敗しても致命的にならない可観測性のためのものです。.ulpi/workflows/.json の書き込みに失敗した場合はログに記録して無視し、ビルドをブロックしてはいけません。ステータスファイルへの書き込みをデリバリーのゲートにせず、ステータスファイルが古いことだけを理由に実行を失敗と報告しないでください。代わりにジャーナル(
wf-status.mjs)から状態を再構築してください。
リファレンスを読み込むタイミング
references/workflow-template.jsプレイブックを1回の処理で実行するワークフローです(計画 → 範囲を限定した計画レビュー → ワークフロー内の git 統合を伴う DAG レイヤー全体での専門家によるビルド → 実装レビュー → 検証 → 本番公開監査)。検証済みの調査結果を返します。受付時のargsを指定して、Workflow ツールから起動します。編集して再実行することで反復できます。references/build-loop.mdビルドフェーズが実装するビルドの CONTRACT です。専門家のペアリングを必ず選択すること、スタックごとの スキルを適用すること、DAG レイヤリングと git 統合、タスク終了時のゲートについて説明します。references/harness-routing.mdclaude/codex/kiro/noneが、計画レビュー、コードレビュー、本番公開監査のための具体的な呼び出し (codex:codex-rescueプラグイン、kiro、ネイティブ)にどう対応するかを説明します。references/playbook-state.md1回処理の状態機械、マスター TodoWrite の形式、調査結果のスキーマと重複排除、検証フェーズ、 クリーン状態とフィードバックの判定について説明します(修正ラウンドはユーザー主導であり、自動ではありません)。references/status-tracking.mdライブステータスファイル(.ulpi/workflows/<id>.json)のスキーマとライフサイクル、書き込み担当者とタイミング、 3つの動詞(status / stop / resume)、helpers/wf-status.mjsのジャーナルリーダーについて説明します。 起動・レポートのステータス書き込みを設定するとき、または実行の進捗をデバッグするときに読み込みます。
出力仕様
次の内容を報告してください。
- 受付 — 使用したレビュー設定(
reviewConfig:ハーネスと、実行した各ゲートおよびその深度)、本番公開の選択、 解決済みの作業ブランチ - 計画名とタスクごとのビルド結果(passed / fixes / blocked)
- 計画レビューと実装レビュー — 有効な各ゲートによる調査結果(確認済み/却下)、または「skipped」
- 本番公開監査 — 判定とブロッカー(または「skipped」)
- 最終状態 — クリーン(
noReviewGateの場合は条件付き)、または正直な未解決調査結果の一覧と次の手順