executing-plans

計画の実行

このセッションで、タスクごとに自分で計画を実行します。タスクごとの実装サブエージェントは使わず、タスクごとのレビュアーも使いません。最後に、ブランチ全体を新しいコンテキストで一度レビューします。

インラインで実行する理由： サブエージェント駆動の開発では、タスクごとに新しい実装者と新しいレビュアーを用意し、それぞれがコードベースを最初から読み直すコストがかかります。インライン実行では、自分のコンテキスト一つと、最後のレビュアー一人で済みます。その代わり、タスクごとの新しいコンテキストと、タスクごとのもう一組の目を手放します。このスキルでは、別の方法でその二つがもたらす利点を補います。ブリーフは仕様、台帳は記憶、TDD は各タスクのゲート、最後のレビュアーはもう一組の目の役割を果たします。

基本原則： 計画を立てる段階で、考えるべきことはすでに考えられています。各ステップをそのとおりに実行し、自分が失敗を見届けてから成功するテストで証明し、自分が忘れても残る記録を作成します。

ナレーション： ツール呼び出しの合間に記述するのは、短い一行までにします。記録は台帳とツールの結果に任せます。

継続的な実行： タスクの合間に、人間のパートナーへ確認のために作業を中断しないでください。インライン実行を選んだのは、コストを抑えるためであり、タスクごとに「続けてよいですか？」と尋ねるためではありません。計画のすべてのタスクを中断せずに実行します。

行き詰まらず、判断する。 矛盾、曖昧さ、計画の不備がある場合は、自分で判断します。拘束力を持つのは仕様であり、計画はその根拠です。どちらも答えを示さない場合は、自分の判断で決着をつけます。判断はすべて、台帳に Ruling: <what you decided> — <why> — <what it costs if wrong> の形式で記録し、作業を続けます。台帳に記録せずに計画から逸脱することは、判断を隠して行うことです。

作業を止めてよいのは、次の四つの場合だけです。取り消せない操作または破壊的な操作、セキュリティ上機微な操作、まず確認を求めるのが通例となっている作業ツリー外への副作用（マージ、共有ブランチへのプッシュ、公開など）、そして、どの進め方を選んでも推測に頼らざるを得ないほど破綻した計画です。これらの場合は、作業を止めて確認を求めてください。

使用する場面

• superpowers:writing-plans で作成した計画があり、引き継ぎ時に人間のパートナーがインライン実行を選んでいる場合。
• ハーネスにサブエージェント用のツールがない場合（プラットフォームごとの参照資料は ../using-superpowers/references/ を参照）。ディスパッチを捏造せず、ここで計画を実行してください。
• タスクの大部分が独立している場合。これは superpowers:subagent-driven-development と同じ前提条件です。

十分に詳細な計画があれば、インライン実行は指示の転記とテストの組み合わせになります。中程度のセッションモデルでもうまく実行でき、最も高性能なモデルのコストに見合うのは、最終レビューという一箇所だけです。このスキルでは、その最終レビューを別途ディスパッチします。人間のパートナーがインライン実行を選んだときは、そのことを伝えてください。

人間のパートナーが各タスクにレビュープロセスを設けたい場合や、計画が長く、後半のタスクに取りかかる頃にはコンテキストが圧縮されてしまう場合は、superpowers:subagent-driven-development を優先してください。長い計画をインラインで実行することもできます。台帳があれば後から状況を再現できますが、最後のタスクほど、あなたが使えるコンテキストは少なくなります。

プロセス

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "task-start: brief + BASE; read the brief" [shape=box];
        "Work the steps in order: TDD, run every verification, read every output" [shape=box];
        "Step output matches plan's Expected?" [shape=diamond];
        "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" [shape=box];
        "Commit as the plan's commit steps say" [shape=box];
        "Completion contract met?" [shape=diamond];
        "task-done: run tests, ledger the result; mark todo complete" [shape=box];
    }

    "Setup: worktree, workspace + ledger, read plan + spec, pre-flight scan" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Final whole-branch review (fresh reviewer if you have one)" [shape=box];
    "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger" [shape=box];
    "Final review clean: delete this plan's workspace" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Setup: worktree, workspace + ledger, read plan + spec, pre-flight scan" -> "task-start: brief + BASE; read the brief";
    "task-start: brief + BASE; read the brief" -> "Work the steps in order: TDD, run every verification, read every output";
    "Work the steps in order: TDD, run every verification, read every output" -> "Step output matches plan's Expected?";
    "Step output matches plan's Expected?" -> "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" [label="no"];
    "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" -> "Work the steps in order: TDD, run every verification, read every output";
    "Step output matches plan's Expected?" -> "Commit as the plan's commit steps say" [label="yes, last step"];
    "Commit as the plan's commit steps say" -> "Completion contract met?";
    "Completion contract met?" -> "Work the steps in order: TDD, run every verification, read every output" [label="no - finish the task"];
    "Completion contract met?" -> "task-done: run tests, ledger the result; mark todo complete" [label="yes"];
    "task-done: run tests, ledger the result; mark todo complete" -> "More tasks remain?";
    "More tasks remain?" -> "task-start: brief + BASE; read the brief" [label="yes"];
    "More tasks remain?" -> "Final whole-branch review (fresh reviewer if you have one)" [label="no"];
    "Final whole-branch review (fresh reviewer if you have one)" -> "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger";
    "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger" -> "Final review clean: delete this plan's workspace";
    "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
}

セットアップ

作業が隔離されたワークスペースで行われるようにしてください。superpowers:using-git-worktrees を使って作成するか、既存のものを確認してください。 人間のパートナーから明示的な承諾を得ずに、main/master ブランチで実装を始めてはいけません。

会話の記憶はコンパクション後には残りません。作業箇所を見失ったインライン実行者は、すでにコミット済みのタスクを再実装してしまいます。これは、コントローラーがタスクを再ディスパッチするのと同じ失敗であり、自分のコンテキストを無駄に消費します。進捗は TODO だけでなく、台帳ファイルにも記録してください。ハーネスの TODO は現在の状態を示すビューであり、台帳は記録です。

ワークスペースと台帳は superpowers:subagent-driven-development と共有されます。同じディレクトリ、同じ形式です。そのため、計画の途中で実行者が交代しても、新しい実行者は同じ台帳から再開できます。

• 各計画には専用のワークスペースがあります。スキルの開始時に ../subagent-driven-development/scripts/sdd-workspace PLAN_FILE を実行してください。計画の Git 無視対象ディレクトリ （<repo-root>/.superpowers/sdd/<plan-basename>/）が表示されます。このディレクトリには、この計画のすべての成果物（台帳、ブリーフ、レビュー用パッケージ）が置かれます。別の計画のディレクトリを読み書きしてはいけません。
• この計画の台帳が <workspace>/progress.md にあるか確認してください。最初の行にこの計画ファイルが記載されている場合、Task <N>: complete の行があるタスクは完了済みです。やり直さず、まだその行がない最初のタスクから再開してください。自分が作成した記憶がコンパクション後に残っていなくても、そのコミットは Git に存在します。コンパクション後は、自分の記憶より台帳と git log を信頼してください。最初の行に別の計画ファイルが記載された台帳は、別の計画の進捗です。そのままにして、自分の新しい台帳を作成してください。
• 台帳は、最初の行にその識別情報を記載して作成してください。 # SDD ledger — plan: <plan file path>
• git clean -fdx を実行すると、ワークスペース（Git が無視する一時ファイル）が削除されます。その場合は git log から復元してください。

計画を一度読み、背景情報とグローバル制約を確認して、タスクごとに TODO を作成してください。計画に仕様書が記載されている場合は、それも読んでください。仕様書は計画の根拠となる権威ある情報源であり、計画内の矛盾は仕様書に従って解決します。参照可能な仕様書がない計画では、その旨を台帳に記録してください。その場合、仕様書なしで下した判断は暫定的なものです。

必須のサブスキル： タスク 1 の前に、今すぐ superpowers:test-driven-development を読み込んでください。このサブスキルは、以下のすべてのタスクの全手順に適用されます。計画内の手順に「失敗するテストを最初に書く」とすでに記載されていても、読み込みを省略してはいけません。

タスク 1 の前に、タスク間の競合がないか計画を確認してください。確認箇所は計画の Interfaces ブロックに記載されています。先行タスクが生成したものを後続タスクが使う場合は、それぞれについて、両方のタスク、先行タスクの生成物と後続タスクの利用対象、確認結果を記した台帳の行を 1 行作成してください。共有要素のないタスクについては行を作成しません。タスク間に共有要素がない計画の場合は、Pre-flight: no shared interfaces の 1 行だけを記載してください。各行で明らかになった競合は、仕様書を優先する情報源として裁定し、その裁定を該当行の横に記録してからタスク 1 を開始してください。各タスク固有の指示は、ブリーフを読む際に確認します。ここでは確認しません。

タスクの進め方

出力する内容とすべてのツール結果は、このセッションの残りの間、コンテキスト内に保持されます。長いテスト出力はワークスペース内のファイルにリダイレクトし、末尾部分を読んでください。計画全体ではなく、ブリーフを読んでください。

1. タスクを開始する

• このスキルの scripts/task-start PLAN_FILE N を実行します。1 回の実行でブリーフのパスと BASE（タスクの範囲の起点となるコミット）が表示されます。セットアップ時に読んだタスクも含め、すべてのタスクについてブリーフを読んでください。記憶は要約にすぎません。ブリーフには正確な値、シグネチャ、テストケースが記載されています。
• 該当タスクの TODO を in_progress に変更します。

ツール呼び出しは毎回、コンテキスト全体を読み直すターンです。作業に関する記録も同時に行い、コミットと同じ呼び出しで台帳に追記してください。記録だけの呼び出しを別に設けてはいけません。

2. 手順を進める

計画の手順はすでに RED-GREEN の順序になっています。セットアップ時に読み込まれた superpowers:test-driven-development のもと、その順序に従ってください。テスト手順では、まずコードを書き、最初に実行します。失敗するのを確認することは手順の一部であり、形式的なものではありません。実装前にテストが通る場合、それはテストについての重要な発見です。

コマンドを実行する各手順には、Expected: の行があります。コマンドを実行し、出力を読み、照合してください。結果は次の 3 つです。

• 一致した場合。 次の手順に進みます。
• コードに誤りがある場合。 superpowers:systematic-debugging を使います。原因を見つけ、手順の出力に合わせるためだけに症状を修正してはいけません。
• 計画に誤りがある場合 — 手順が仕様と矛盾している、以前のタスクのインターフェースがこのタスクで使用するものと一致しない、実行できないコマンドがある場合。仕様を満たす最小限の変更を判断し、Task <N>: Ruling: <finding> — <what you decided and why> として台帳に記録してから続行します。判断は記憶に頼らず、引き継がれます。同じインターフェースに関係する後続タスクでは、台帳からその判断を確認してください。

計画に記載されたコミット手順に従ってコミットしてください。タスクが複数のコミットにまたがっても問題ありません。レビュー対象範囲の起点となるのは BASE であり、HEAD~1 ではありません。

3. 完了条件

タスクの台帳行を記録する前に、以下のすべてが、このセッション内の証拠によって確認されている必要があります。差分が正しく見えることから推測してはいけません。

• ブリーフに記載されたすべてのテストが存在し、このタスク内で実行され、その出力を読みました。
• タスクの最終テスト実行が成功しました。task-done はその実行であり、コマンドと結果を台帳行に記録します。
• ブリーフにあるすべての Expected: 行を、実際の出力と照合しました。
• ブリーフからの逸脱はすべて、Ruling: 行に記録しました。

必須サブスキル： 完了の判断には superpowers:verification-before-completion が適用されます。項目が 1 つでも欠けていれば、タスクは完了していません。完了するまで作業を続けてください。

4. タスクを完了する

このスキルの scripts/task-done PLAN_FILE N BASE -- <test command> を、そのタスク全体についてブリーフで指定されたテストコマンドとともに実行します。テストを実行し、出力全体をワークスペースに保存して、末尾を表示します。そして、テストが成功した場合に限り、台帳に次の完了行を追記します。

Task <N>: complete (commits <base7>..<head7>, tests: <command> → <result>)

実行に失敗した場合、何も記録されず、タスクは完了しません。記録されたら、ToDo を完了としてマークし、次のタスクに進みます。

最終レビュー

../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD （MERGE_BASE = ブランチの開始元のコミット。例： git merge-base main HEAD）を実行し、出力されたファイルを使ってレビューします。

サブエージェントツールがある場合： 利用可能なモデルのうち最も高性能なものを使ってレビュー担当者を割り当てます。ブランチ全体のレビューは判断を伴う作業です。superpowers:requesting-code-review の code-reviewer.md を使い、パッケージのパス、計画と仕様のパス、計画に Review Focus セクションがあればその内容（計画のテストで検証されない入力クラスと失敗モード。レビュー担当者はそれぞれを意図的に確認します）、および判断の重み付けに使えるよう、台帳の Ruling: 行への参照を渡します。モデルを明示的に指定してください。指定しない場合はセッションのモデルが引き継がれますが、それが最も高性能とは限りません。この全工程で得られる、新しいコンテキストはこれだけです。省略したり、差分を自分で確認する作業に置き換えたりしないでください。

サブエージェントツールがない場合： code-reviewer.md を読み、パッケージに対して自分でレビューを行います。最後のタスクの台帳行の後に、独立した工程として実施してください。台帳に Final review: self-review (no subagent tool) と記録し、最終メッセージでもその旨を伝えます。実装者本人によるセルフレビューは、新しいレビュー担当者によるレビューよりも信頼性が低いため、それでマージ前の確認として十分かどうかは人間のパートナーが判断します。

指摘事項には、対応する前に優先順位を付けてください。レビュー担当者の重大度ラベルは参考情報であり、最終判断はあなたが行います。「判断を保留」とされた項目についても、最終判断はあなたが行います。そこにある各項目は、計画との不一致と同じように判断し、台帳に記録してください。形式は次のとおりです。Final: Ruling: <レビュー担当者が判断を保留した挙動> — <このソフトウェアを使う合理的な人が得る結果と、そのままで問題ない理由、または現在は指摘事項とする理由> — <誤っていた場合の代償>。まず、影響に基づいて重大度を再評価します。仕様はビジョンを示す文書であり、指摘の重大度は、その入力が仕様に記載されているかではなく、リリースされた場合にソフトウェアを使う合理的な人が受ける影響で決まります。仕様に入力が明記されていないという理由でレビュー担当者が Minor とした指摘は、影響ではなく仕様を評価しています。その後、次のように対応します。

• Critical と Important は修正工程の対象です。
• Minor は Final: minor (deferred): <一行の説明> として台帳に記録し、最終メッセージの「Deferred minors」に記載します。Minor は修正工程の対象にせず、裁定事項にもなりません。裁定とは不一致についての判断であり、仕上げの提案を見送ったという記録ではありません。

Critical と Important の指摘は、実装担当者であるあなた自身が、一度の工程で修正します。各修正は再レビューではなく TDD で検証します。指摘を再現するテストを書き、失敗することを確認してから修正し、その後、全テストスイートを実行してください。それぞれについて、Final: fixed <finding> — <test name> RED→GREEN, suite <N>/<N> の形式で台帳に記録します。最初に失敗するテストがない修正は検証済みとはみなしません。この工程後にテストスイートがすべて成功していなければ、工程は完了していません。再レビューは割り当てないでください。修正をカバーするテストで「対応済み」かどうかは確認でき、テストスイートの実行で「ほかに問題がない」ことも確認できるためです。

修正しないと判断した指摘は裁定事項です。Final: Ruling: <指摘> — <コードをそのままとする理由> — <誤っていた場合の代償> の形式で記録し、人間のパートナーに「Rulings I made」の一覧で伝えます。修正工程は一度限りです。

完了

何かを削除する前に、台帳にある Ruling: を含むすべての行を、行った順に「Rulings I made」として最終メッセージに記載してください。それぞれ、誤っていた場合の代償も記載します。また、minor (deferred) を含むすべての行を「Deferred minors」に記載してください。どちらの一覧も漏れがないようにしてください。あなたが人間のパートナーに代わって下した判断と、対応しないことにした指摘が伝わるのは、最終メッセージだけです。

最終レビューに問題がなく、修正がコミットされたら、この計画のワークスペースディレクトリを削除してください。記録は Git 履歴に残ります。兄弟ディレクトリはほかの計画が使っているため、そのままにしてください。

superpowers:finishing-a-development-branch を使用してください。

よくある正当化

言い訳	実態
「タスク N に何が書かれているか覚えています」	覚えているのは要約です。ブリーフには正確な値が記載されています。読んでください。
「計画のコードは正しいので、テストが失敗するのを確認するのは省きます」	失敗するのを見ていないテストは、何の証明にもなりません。これは手順の一つです。実行してください。
「各手順ごとではなく、最後に全テストを実行します」	どの手順で問題が起きたかを把握するには、手順ごとの実行が必要です。タスク終了時の実行は契約であり、代わりにはなりません。
「ここでは計画が間違っているので、正しいことをします」	正しいことをして、判断内容を台帳に記録してください。記録されていない逸脱は、秘密裏に行われた決定です。
「いくつかのタスクが終わってから台帳に記録します」	コンテキストの圧縮は、都合のよいタイミングを待ってはくれません。タスクごとに1行、コミットと同じメッセージに記録してください。
「次のタスクに進む前に確認します」	インラインを選んだのは、時間を節約するためです。進捗確認のプロンプトは、その時間を消費します。止まるのは4つの停止ポイントだけです。
「自分の差分は注意深く確認したので、最終レビュアーは不要です」	同じ作成者なら、見落としも同じです。今回得られる唯一の新鮮な視点がレビュアーです。
「テストは通るはずです。変更は些細なものだったので」	「はず」は証拠ではありません。契約では、コマンドとその出力が求められています。
「サブエージェントは遅くてコストもかかるので、最終レビューも省きます」	インラインにした時点で、タスクごとのレビュアーはすでに省かれています。ブランチ全体を1回レビューするのは最低限であり、上限ではありません。
「レビュアーが軽微と言ったので、軽微です」	そのラベルが評価したのは、仕様に記載がないことです。利用者にとって何を意味するかを評価してください。評価し直してから、ゲートを適用してください。
「修正は明らかなので、先に失敗するテストを書く必要はありません」	失敗するテストだけが、指摘が実際に正しく、今は解消されたことの証明です。それがなければ、差分と期待しかありません。
「作業中なので、軽微な問題も修正しておきます」	修正する軽微な問題ごとに、パートナーが求めていないテスト、修正、テストスイートの実行が必要になります。台帳に記録し、判断はパートナーに任せてください。

ワークフローの例

You: I'm using the executing-plans skill to implement this plan inline.

[Setup: worktree verified]
[Read plan once: docs/superpowers/plans/feature-plan.md; spec read]
[Resolve workspace: sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[Pre-flight scan: 2 shared-interface rows, 4 self-consistency rows, clean; written to ledger]
[Create todos for all tasks]

Task 1: Hook installation script

[task-start plan 1 → brief read; BASE a1b2c3d]
[Step 1: write failing test — written]
[Step 2: run it — FAIL: install_hook not defined. Matches Expected.]
[Step 3: implement — written]
[Step 4: run it — PASS 1/1. Matches Expected.]
[Step 5: commit — d4e5f6a]
[Contract: tests ran, output read, no deviations]
[task-done plan 1 a1b2c3d -- npm test -- hooks → ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, tests: npm test -- hooks → 1/1 pass)]

Task 2: Recovery modes

[task-start plan 2 → brief read; BASE d4e5f6a]
[Step 2: run failing test — FAIL, but on an import error: Task 1 exported
 installHook, brief consumes install_hook]
[Ruling: brief's consumer name is a typo against Task 1's Produces block;
 use installHook — Ledger: Task 2: Ruling: install_hook → installHook — matches Task 1 Produces — cost if wrong: one rename]
[Steps 2-5 as planned; commit b7c8d9e]
[task-done plan 2 d4e5f6a -- npm test -- recovery → ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, tests: npm test -- recovery → 8/8 pass)]

...

[After all tasks: review-package plan MERGE_BASE HEAD; dispatch code-reviewer, most capable model]
Reviewer: One Important finding — progress reporting interval hardcoded. Two Minor.
[Re-grade: Important stands; minors → ledger as deferred]
[Fix pass: test_progress_interval_configurable RED → extract PROGRESS_INTERVAL → GREEN; suite 12/12; commit]
[Ledger: Final: fixed hardcoded interval — test_progress_interval_configurable RED→GREEN, suite 12/12]

Rulings I made:
- Task 2: install_hook → installHook (brief typo; cost if wrong: one rename)

Deferred minors:
- README lacks a usage example
- recovery.js could split verify/repair into two files

[Delete this plan's workspace — the record now lives in git]

Using superpowers:finishing-a-development-branch.