implement-from-plan reference

GitHub Issue を作らず、local plan から実装、検証、review、PR 作成まで進める入口である。

対象読者と使いどころ

fix-github-issue と違い、claim gate や Issue 更新は行わない。dummy Issue や hidden Issue も作らない。

まず何が起きるか

1. Issue を作らずに local plan を作り、要求と repository の一次情報から受け入れ条件を整理する。
2. plan validation と plan readiness で、受け入れ条件、変更範囲、検証方法を確認する。
3. 実装し、通常検証、PR 前 simplify、必要な pre-review E2E を行って pre-review commit を作る。
4. working tree が clean であることを確認し、review、push、PR 作成の前に fix-code-comments skill を実行する。対応言語の変更が無い branch でも省略せず、review 指摘の対応で HEAD が変わった場合は push 前に再実行して run record を最新 HEAD に揃える。
5. local review が有効な場合は current HEAD を review する。
6. finding があれば修正、再検証、再commitを行い、指定した review gate の収束後に push する。
7. pr=create|draft なら PR を作り、PR review と CI を確認する。pr=none なら PR を作らず完了確認へ進む。
8. final E2E が必要な場合は review 後に実行し、最新結果を PR と完了報告へ反映する。

受け入れ条件や公開 API、設定形式、画面上の挙動に複数の完了形がある場合は、plan を確定する前に利用者へ確認する。

plan validation

plan validation が通っても、plan readiness が変更範囲や検証方法の不足を返した場合は実装を始めない。

調査から始める

research-packet=auto の候補が複数、古い、または読み取れない場合は自動採用しない。packet に未解決の重要判断が残る場合は、質問への回答か grill=skip の明示が必要になる。

shared implementation options

PR と review

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 を広げる。

実装 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 で文書だけを変更し、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 へまとめて保存する。現在の Codex thread ID または Claude Code session ID を取得できる場合は、plan ID と role=implementation の session binding も保存する。再開時は保存済みの条件を使い、不足項目の補完、既存値との不一致、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> も指定する。

完了報告前には、canonical completion-check が state から解決する artifact を plan implementation-evidence --kind <kind> --state-evidence <artifact.json> で登録する。

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 を空にしない。

Stop hook は明示 workflow identity または current session binding と role=implementation を branch 推定より優先する。保存済み selector と canonical artifact ref を CompletionCheckOptions へ変換し、完了報告と同じ canonical evaluator の結果を canonical_completion に記録する。非 implementation role と durable state が無い branch-only inference は no-op にする。 required mode では完了報告と同じ canonical 判定を effective exit に使う。旧判定は legacy_decision に残し、shadow_decision と divergence に比較結果を記録する。

完了確認の 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 を使う。

停止条件と再開

次の場合は 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

詳細 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.md
• claude/skills/implement-from-plan/references/*.md