implement-from-plan reference
GitHub Issue を作らず、local plan から実装、検証、review、PR 作成まで進める入口である。
対象読者と使いどころ
| 項目 | 内容 |
|---|---|
| 対象読者 | Issue 化が不要な bounded task を、受け入れ条件を残して実装したい人 |
| 目的 | Issue を作らず、local plan を起点に実装から PR まで進める |
| 代表的な入口 | /implement-from-plan pr=draft |
| 入力 | 要求から作る local plan、または既存の research packet |
| 結果 | 検証済みの変更、指定した review、commit、push、必要な PR |
fix-github-issue と違い、claim gate や Issue 更新は行わない。dummy Issue や hidden Issue も作らない。
まず何が起きるか
- Issue を作らずに local plan を作り、要求と repository の一次情報から受け入れ条件を整理する。
- plan validation と
plan readinessで、受け入れ条件、変更範囲、検証方法を確認する。 - 実装し、通常検証、PR 前 simplify、必要な pre-review E2E を行って pre-review commit を作る。
- local review が有効な場合は current HEAD を review する。
- finding があれば修正、再検証、再commitを行い、指定した review gate の収束後に push する。
pr=create|draftなら PR を作り、PR review と CI を確認する。pr=noneなら PR を作らず完了確認へ進む。- final E2E が必要な場合は review 後に実行し、最新結果を PR と完了報告へ反映する。
受け入れ条件や公開 API、設定形式、画面上の挙動に複数の完了形がある場合は、plan を確定する前に利用者へ確認する。
作業途中の仕様訂正
plan 確定後に条件を削除・置換したり対象を狭めたりした場合は、Agent が新旧の要求と影響箇所を既存の plan と作業記録へ反映します。今回触った実装、migration、テスト、コメント、PR説明を照合し、反映済み、未反映、対象外を区別します。実装が新条件でも、テストの期待値や説明に旧条件が残っていれば修正対象です。
新要求の期待結果で検証し、無関係な仕様や廃案専用のテストへ変更を広げません。外部文面の更新が未許可なら差分案と残件を報告し、許可済みの作業は続けます。local plan の正本、PR本文の人手追記保護、変更後の検証更新規則を維持し、既存の plan validation、readiness、checkpoint の手順へ戻ります。
詳細は共有手順を参照してください。新しい Issue や履歴管理機構は作りません。
plan validation
| 指定 | 動作 |
|---|---|
agent=auto |
plan validation に使う Agent を自動選択する |
agent=codex / agent=claude / agent=copilot |
plan validation Agentを固定する |
config=<path> |
validation Agent の設定を渡す |
claude-mcp=off / claude-mcp=on |
Claude validation で MCP を使うか指定する |
skip-validation |
別 Agent の validation だけを省略する。readiness と通常検証は省略しない |
questions=off |
plan 作成前の最小確認を止め、decision-doc を起動しない。高影響な判断を Agent が補った場合は plan 作成後に停止する |
plan 作成前に high-impact 未確定が 1 件でも残る場合は、AskUserQuestion の個別質問を連続で出さず、推奨案を最初に置いた判断候補から packet を作り /decision-doc research-packet=<path> で確認する。各判断には、回答で plan のどこが変わるかを影響範囲として表示する。
レビュー完了後は、packet-out.json の chosen_by: "user" decision を evidence 付きで plan の decisions[] へ転記する。decision-doc が success / proceed を返すまで、plan draft と plan validation へ進まない。
RHW 未導入で decision-doc が停止した場合は、質問一覧を報告して plan draft 前に停止する。
対話手段のない worker は decision-doc を起動せず、needs_user_decision と構造化した質問一覧を親へ返して停止する。
decision-doc 完了後の task-research validate --packet と plan readiness --research-packet には、入力 packet ではなく packet-out.json を渡す。
plan validation が通っても、plan readiness が変更範囲や検証方法の不足を返した場合は実装を始めない。
調査から始める
| 指定 | 動作 |
|---|---|
research=auto / research=light / research=standard / research=deep / research=spike |
plan 作成前に read-only 調査を追加する |
research=off |
追加の調査 packet を作らない |
research-packet=<path> |
検証済みの packet を plan の根拠に使う |
research-packet=auto |
要求に一致する単一の current packet がある場合だけ採用する |
grill=skip |
research artifact が要求する深掘り interview を明示的に省略する |
research-packet=auto の候補が複数、古い、または読み取れない場合は自動採用しない。packet に未解決の重要判断が残る場合は、質問への回答か grill=skip の明示が必要になる。
discovery 結果は、最初に status を確認する。status=success の場合だけ candidate_state と candidate_status を解釈する。
shared implementation options
PR と review
| 指定 | 動作 |
|---|---|
pr=draft / pr=create / pr=none |
Draft PR、通常 PR、PR なしのいずれかを選ぶ |
review=auto |
plan と変更規模から review の強さを決める |
review=simplify |
PR 前 simplify だけを行う |
review=off |
review=simplify の alias として扱う |
review=once |
simplify 後に選択した Agent の one-shot review を行う |
review=on |
local review と、PR 作成後の review を収束させる |
agents=codex / agents=claude / agents=copilot / agents=none |
local reviewer を指定する。複数指定もできる |
reviewers=copilot / reviewers=codex / reviewers=codex,copilot / reviewers=copilot,codex / reviewers=none |
GitHub reviewer または trigger を指定する |
max-local-review-loops=auto / max-local-review-loops=<positive-integer> / max-local-review-loops=unlimited |
local reviewer loop の上限を指定する |
max-github-review-loops=auto / max-github-review-loops=<positive-integer> / max-github-review-loops=unlimited |
GitHub reviewer / trigger loop の上限を指定する |
ask-user |
review finding の採否を利用者に確認する |
pr= が未指定の場合は、通常 PR、Draft PR、PR なしのどれに進むかを推測せず、利用者へ確認する。
agents= は local reviewer、reviewers= は GitHub reviewer の指定である。reviewers=codex,copilot と reviewers=copilot,codex は同じ指定として扱う。
review=once では agents= に 1 つの runtime が必要で、agents=none や複数指定は開始前に停止する。
review=auto は変更規模から profile を選び、risk が高いほど coverage を広げる。
| profile | review mode | 既定 local reviewer | review loop の自動上限 |
|---|---|---|---|
minimal |
review=simplify |
なし | なし |
standard |
review=once |
実装 runtime の反対側 | なし |
high |
review=on |
実装 runtime の反対側 | 5 |
full |
review=on |
codex,claude |
10 |
実装 runtime が Claude Code なら Codex、Codex なら Claude、それ以外は Codex を反対側の既定値とする。判定できない場合は standard を選ぶ。review=、agents=、reviewers=、loop 上限の明示値は自動結果より優先し、unlimited は明示指定時だけ使う。
review=on で代表 profile の選択または明示 override が必要な場合は、利用者に確認してから実行する。
pr=none review=on agents=none のように実行可能な review 経路がない組み合わせは開始前に停止する。
単独の local plan はこの Skill で進める。親 Issue の sub-issue 群を queue 実行する場合は agent-team-run を使う。
E2E と作業場所
| 指定 | 動作 |
|---|---|
e2e=auto |
変更内容から E2E の要否と実行時点を決める。既定 |
e2e=off |
E2E を実行しない |
e2e=pre-review |
local review の前に E2E を行う |
e2e=final |
review とコード変更が収束した後に E2E を行う |
e2e=both |
pre-review と final の両方で行う |
worktree=on / worktree=off |
専用 worktree を使うか、現在の作業場所で実装するかを選ぶ。既定は on |
stack=<PR number|PR URL|auto> / stack=true |
stacked PR の親を PR または一意な source Issue の依存から解決する |
stack-base=<branch> |
stacked PR の親 branch を明示し、作業起点と review / PR の base をそろえる |
e2e=auto で文書だけを変更し、local apply、browser UI、command behavior、workflow runtime に影響しない場合は E2E を実行しない。e2e=pre-review|final|both を明示した場合は省略しない。
E2E の実行方法に利用者判断が必要な場合は、実行も skip も推測せず確認へ戻る。
stacked PR の親
stack=<PR number|PR URL> は同じ repository の open PR を親として指定します。stack=auto または stack=true は、research packet、handoff、plan から source Issue を一意に特定できる場合だけ Issue 依存から親 PR を解決します。自由文 plan などで source Issue を特定できない場合は停止します。
解決した親 PR、base branch、base OID は worktree、review、PR 作成へ引き継ぎ、PR 作成直前に再検査します。stack と stack-base は同時に指定できません。
stack=auto が logical_dependency_pr と effective_tail_candidate を返しても、legacy parent_pr_not_top は実装開始許可に読み替えません。chain_root_status、stack_members、publication_order_snapshot は後続 coordinator 用の観測 evidence として保持します。
source Issue を一意に特定できる auto stack は、fix-github-issue と同じ publication intent registry と standalone coordinator を使います。commit 後に current branch と HEAD を ready にし、先行 intent がある場合は status と heartbeat を続けます。順番が来たら prepare から再開し、restack 後の HEAD で validation、simplify、review、E2E をそろえ直します。
明示 stack=auto の publication gate と closing Issue gate は required です。required worker は implementation を commit までに限定し、publication-finalization が保存済み intent を使って prepare、current-HEAD gate、PR 作成を担当します。
false stop、unsafe pass、duplicate publication、順序違反、closing Issue の誤停止または見逃しがあれば、両 gate を report-only に rollback します。残存 publication intent は計測 artifact に記録して abort し、required registry へ持ち越しません。
generic resolver の legacy 既定値は変更しません。
branch を直接指定する互換経路
stack-base=<branch> を指定すると、先に対象 branch を fetch し、origin/<stack-base> を worktree または branch の起点にします。同じ branch を review-profile-plan、local review、create-pr にも渡します。
既存 linked worktree は、clean で origin/<stack-base> が HEAD の祖先になっている場合だけ再利用します。条件を満たさない場合は、自動 rebase や追加 worktree の作成を行わず、必要な操作を案内して停止します。
未指定時は stack-base による上書きを行わず、作業起点、review base、PR base の各既存手順を維持します。
実装開始時には、確定した PR、review、local reviewer、E2E、smoke の実行条件を durable state へまとめて保存する。再開時は保存済みの条件を使い、不足項目の補完、既存値との不一致、live binding の保存失敗が解消するまで完了扱いにしない。
plan.json の decisions[].category には、ux_visible_behavior、data_format、public_api、config_format、scope、other のいずれかを指定する。
readiness checkpoint の acceptance_evidence は省略できる。記載する場合は plan の全 acceptance に対応する entry を置き、各 entry を status: "satisfied" かつ空でない evidence[] にする。
durable state を作る plan task-ledger には、--state-workflow-id PLAN_ID と次の selector snapshot を渡す。
CLI では --state-pr-mode <pr_mode>、--state-review-mode <review_mode>、--state-agents <agents>、--state-e2e-mode <e2e_mode>、--state-smoke-mode <smoke_mode> と指定する。stack resolver を使った場合は --state-stack-selector <selector> と --state-stack-resolution <artifact path> も指定する。
| flag | 値 |
|---|---|
--state-pr-mode |
正規化済みの PR mode |
--state-review-mode |
解決済みの review mode |
--state-agents |
解決済みの local reviewer selector |
--state-e2e-mode |
解決済みの E2E mode |
--state-smoke-mode |
解決済みの smoke mode |
--state-stack-selector |
正規化前の stack selector |
--state-stack-resolution |
stack-resolution.v1 artifact path |
完了報告前には、canonical completion-check が state から解決する artifact を plan implementation-evidence --kind <kind> --state-evidence <artifact.json> で登録する。
| kind | 登録する条件 |
|---|---|
commit、validation、pre-pr-simplify |
常時 |
review |
review_mode が once または on |
ci |
pr_mode!=none |
pre-review-e2e |
e2e_mode が pre-review または both |
final-e2e |
e2e_mode が final または both |
validation kind には run-validation が出力した validation-transcript.v1 を登録する。集約用の validation-evidence.v1 は登録しない。
publication は CI artifact から PR 番号を解決できない場合だけ使う optional fallback であり、必須 evidence ではない。mode が要求しない kind も登録しない。
完了確認へ渡す --simplify-result は、次のいずれかを受理する。
{"status":"success"}{"status":"skipped_trivial_change"}{"status":"skipped_covered_by_multi_review","covered_by":{"evidence_path":"<multi-review evidence>"}}
skipped_covered_by_multi_review を使う場合は、covered_by.evidence_path を空にしない。
完了確認の completion-check は実行のたびに fix-code-comments の run record を照合し、comment-check-observation.v1 を state root の repository 単位 path へ保存して、stdout に summary を additive に含める。この観測は report_only で、required_action を追加せず完了判定と exit code を変えない。base は optional な --base-ref で明示でき、省略時は origin/main との merge-base を使う。
PR 前 simplify commit 後、review / push / PR 作成の前に、各 implementation agent が非 test・非 generated Go の追加 hunk を確認する。理由、制約、外部契約をコードだけで残せない hunk にはコメントを書く。コメントを書いた場合は通常検証を再実行して commit し、commit 後の diff で行範囲を更新した comment-intent-input.v1 を review-orchestrator issue comment-intent record で記録する。修正で HEAD が変わった場合は再判定して再記録する。
completion-check は comment_intent_check summary を追加する。record で --repo-remote を指定した場合は、completion-check にも同じ値を渡す。record の欠落、HEAD 不一致、missing、stale、読み取りエラーは report_only であり、完了判定と exit code を変えない。
subagent への委譲
任意の委譲は、独立していて並列化できる大きな作業に限ります。数回の tool 呼び出しで終わる作業は直接処理し、探索ディレクトリ数だけでは委譲しません。基準の編集元は claude/CLAUDE.md の「Subagent 委譲」節です。
調査だけを任せる子と編集する子の責務を分け、同じファイルを競合して編集しないようにします。親は応答待ちの間も独立した許可済み作業を進め、子と同じ調査を繰り返しません。
ユーザーの明示並列実行 / Agent 指定と、skill が要求する独立 review / validation は維持します。利用不能時の停止条件や外部 AI 許可も変わりません。具体的な引き継ぎは共通手順に従います。
停止条件と再開
次の場合は commit、push、PR 作成、完了報告へ進まない。
- plan validation、readiness、review、CI、E2E に未解決の required action がある。
- plan と実際の変更ファイル、検証方法、受け入れ条件に差が出た。
- reviewer を起動できない、または finding の修正を検証できていない。
- host profile への反映に companion PR が必要だが、元の handoff や PR 状態を確認できない。
停止時は、不足項目と再開に使う command を報告する。利用者が回答した場合は plan を更新し、readiness と変更差分の確認から再開する。
完了は会話の要約だけで決めない。指定した validation、review、CI、E2E と PR mode の結果が current HEAD に対してそろった場合だけ完了として報告する。
実行例
/implement-from-plan pr=draft
/implement-from-plan research=standard pr=create agents=claude reviewers=none
/implement-from-plan research-packet=tmp/task-research/abc/research-packet.json pr=draft
/implement-from-plan pr=none review=once agents=claude e2e=off
/implement-from-plan pr=create review=on agents=codex,claude reviewers=copilot e2e=final
モデルを今回だけ変更する
既定設定は自動で読み込まれる。codex-model=gpt-6-astra でモデルを、codex-effort=high で推論量を指定できる。設定ファイルの追加は不要で、指定値は子Agentと再実行にも引き継ぐ。Claude／Copilotの指定方法はモデル選択を参照。
詳細 contract
- no-Issue implementation flow contract
- implementation readiness contract
- E2E workflow gate
- task-research reference
- fix-github-issue reference
- Issue workflow skill guide
claude/skills/implement-from-plan/SKILL.mdclaude/skills/implement-from-plan/references/*.md