ソフトウェアファクトリ（Software Factory）
まずあらゆるスコープの疑問を解消し、責務を凍結します。重いフェーズはすべて新しいサブエージェントに委譲し、コードを書いていない独立した検証者（Verifier）によって完了を証明します。
┌──────────┐ ┌──────┐ ┌────────┐ ┌───────┐ ┌────────┐
│ DISCOVER │ → │ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
│ (発見) │ │ (計画)│ │ (チェック)│ │ (構築) │ │ (検証) │
└──────────┘ └──────┘ └────────┘ └───────┘ └────────┘
疑問ゼロ 確認 責務 バッチ 作成者≠検証者
5つのムーブ、.specs/features/<feature>/ 配下の3つの永続的成果物、そしてメインチャット内でコンテキストウィンドウを肥大化させない薄型オーケストレーター（Thin Orchestrator） で構成されます。
- DISCOVER（発見）：読み取り専用の
scoutサブエージェントがコードベースをスキャンし、コンパクトな（約30行）あいまいさ要約書を返します。メインチャットは、具体的な選択肢と推奨デフォルト値を使ってユーザーに質問し、未確認の仮定がゼロになるまで繰り返します（すべての行に対してConfirmed? y）。discovery.md を参照。 - PLAN（計画）：
plannerサブエージェントが.specs/features/<feature>/plan.md（問題、フロー、影響、関係、表面、着地、評価基準、スコープ外、前提条件、観測可能、情報源）を作成し、validate_plan.pyを実行します。ユーザーはplan.mdに簡単なサインオフを行います。plan.md を参照。 - CHECKS（チェック）：
plan.mdのサインオフ後、自律的な計画後ループが開始されます。specifierサブエージェントが.specs/features/<feature>/checks.md（主張＋証明、カバレッジ結合、テストポリシー、スイープ、ハンドオフ演算）を作成し、validate_checks.pyを実行します。checks.md を参照。 - BUILD（構築）：スライス/バッチごとに1つの
builderサブエージェントが、チェックに厳密に従ってテストを作成し、コードを実装し、証明を実行し、checks.mdを更新し、check_commit.pyを使用してコミットします。build.md を参照。 - VERIFY（検証）と修正ループ：独立した
verifierサブエージェント（決してビルダーではない）が<feature base>..HEADをすべてのチェックに対して監査し、.specs/features/<feature>/verification.mdを作成し、validate_verification.pyを実行します。いずれかのチェックが失敗した場合、fixerサブエージェントがランク付けされたギャップを解決し、新しいverifierが再検証します（最大3ラウンド）。verify.md および orchestration.md を参照。
なぜこの形式なのか
コーディングエージェントは、複雑な機能において2つの予測可能な理由で失敗します：
- コンテキストウィンドウの肥大化：単一のチャットセッションがリポジトリを探索し、ユーザーにインタビューし、計画を書き、チェックを導出し、テストとコードを作成し、自身の作業を検証しようとすると、コンテキストウィンドウが満杯になり、情報損失を伴う圧縮が発生します。
- 未確認の要件と自己レビューの盲点：プロダクトの振る舞いを黙って推測したり（
Confirmed? n）、作成者自身に完了を自己認定させると、作成者自身の盲点がそのまま出荷されます。
software-factory は両方を解決します：
- 薄型オーケストレーター（メインチャットで15kトークン未満）：メインチャットは厳密に調整役とユーザーインタビュアーとして機能します。コードベースの読み取り、成果物の作成、コーディング、テスト、検証はすべて、
scout、planner、specifier、builder、verifier、fixerといった独立した一時的なサブエージェント内で実行され、これらは.specs/features/<feature>/ディスク上のファイルとgitコミットを介してのみ通信します。完全なディスパッチプロトコル： orchestration.md。 - 小さく凍結された責務セットと独立した検証者：時代遅れになりがちな詳細なタスクチェックリストやコンポーネントカタログ（クラスごとの
Purpose/Location/Interfaces）はありません。一方通行の扉はLandingに文字通りの形状を持ちます；可逆的な配置は差分で決定されます。
重要なルール
固定されたセット。これらはすべてのプロファイルで維持されます：
- 未確認の仮定ゼロ（
Confirmed? y）。プロダクトやスコープの振る舞いを黙って推測してはいけません。DISCOVER中に明らかになったあらゆるグレーゾーンは、具体的な選択肢と推奨デフォルト値を使って質問するか、ユーザーが明示的に委任する必要があります（Confirmed? y）。validate_plan.pyはConfirmed?がnまたは空白の行を拒否します。 - 薄型オーケストレーターと厳格な1サブエージェント・フェーズ境界（
scout!=planner!=specifier!=builder!=verifier）。メインチャットを約15kトークン未満に保ちます。2つのフェーズを1つのサブエージェント呼び出しに決してマージしないでください：scoutは探索し、約30行のあいまいさ要約書を返すのみ。plannerはplan.mdを作成しvalidate_plan.pyを実行するのみで、その後停止して終了します。specifierはchecks.mdを作成しvalidate_checks.pyを実行するのみで、その後停止して終了します（テストファイルや実装コードを決して作成してはいけません。BUILDに続けてはいけません）。builderはspecifierが戻った後にのみ実行されます。複数スライスの機能（S1、S2、...）の場合、各スライスに対して1つの別個のbuilderサブエージェントを順次ディスパッチし、各スライスが新しいコンテキストウィンドウで実行され、ユーザーに進捗を報告できるようにします。verifierは最後のbuilderがコミットした後、新しいサブエージェントでのみ実行されます。
- すべてのチェックは、具体的な値を伴う1つの観測可能な主張と、その証明 — 終了コードで解決される正確なテストセレクターまたはコマンド。証明がないチェックはチェックではありません。
- テストはチェックが言うことをアサートし、コードがたまたま行うことをアサートしてはいけません。実装を読んでテストを書いてはいけません。
- アサーションを弱めたり、テストを削除したり、スイートを通すためにテストをスキップしたりしてはいけません。真に間違ったチェックは編集ではなく、停止して質問する対象です。
- チェックと
Test policy行は一旦承認されたら固定です。plan.mdでは、Landing、Relations、Surfaceは追加専用です — 構築中に発見された扉は、それを閉じるコードの前に行が追加され、ユーザーが承認した行は決して書き換えられません。FlowとImpactは、パスを変更するコミットで真実に保たれます。 - 検証者は新しいサブエージェントであり、決して作成者ではなく、オプションでもなく、聞かれるのを待つこともありません。オーケストレーターは、機能の最後のコミットが
<feature base>..HEADに着地した直後、すべてのチェックとともに検証者をディスパッチします。 - プロファイルは最低基準であり、
validate_verification.pyによって強制されます。 - 完了のゲートはスクリプトであり、感覚ではありません：
validate_verification.pyが終了コード0で終了する必要があります。 - 影響範囲： 承認された仕様は、ローカル編集とローカルコミットを許可します。
git push、デプロイ、および本番データの変更には、そのアクションに対する明示的な承認が必要です。
プロファイル
プロジェクトは、AGENTS.md または同等の場所で、どれだけ実行するかを宣言します。宣言がない場合：light。
## software-factory
profile: light
budget: 150k
| プロファイル | 追加するもの | 捕捉できないもの |
|---|---|---|
light（デフォルト） | 各名前付きテストが存在し実行されることを示して HEAD で証明を実行、チェックごとに1つの配置されたアサーション、レベルとサンプリングのギャップ、Swept existing の再読み取り | 証明がない集合メンバー；間違った実装でもパスするテスト |
standard | Coverage 結合の再計算、各判定付きの Test policy 行、アサーションサーフェスごとに1つの欠陥 | 拘束力のある情報源と矛盾するチェック；誰も構築しなかった画面 |
ui | 拘束力のある情報源を開いて比較、画面ごとのコピーと配置の列挙 | 間隔、色、フォントウェイトのみ、画面ごとに列挙 |
validate_verification.py は、checks.md が承認されたプロファイルと異なるレポートを拒否し、欠陥行がないかカバレッジが再計算されていない standard レポートを拒否し、拘束力のある情報源セクションがない ui レポートを拒否します。
成果物
.specs/
├── STATE.md # 決定ログ（AD-NNN）+ ハンドオフスナップショット
├── LESSONS.md # scripts/lessons.py によってレンダリング - 手動編集禁止
├── lessons.json # 機械所有
└── features/<feature>/
├── plan.md # 問題、フロー、影響、関係、表面、着地、評価基準、前提条件（すべてy）、観測可能
├── checks.md # 主張＋証明、カバレッジ結合、テストポリシー、スイープ、ハンドオフバッチ
└── verification.md # 独立した検証者のレポート
各フェーズがコンテンツを生成した時点で対応するファイルを作成します。おおよそ3ファイル未満の変更で、一方通行の扉がなく、スコープのあいまいさがゼロの場合、## Intent パラグラフを含む checks.md のみを作成し、plan.md をスキップします。
plan.md の5つの境界のある設計セクション
| セクション | レビュー対象 | 除外されるもの |
|---|---|---|
Flow | パス、ホップごとに1行 | 存在しない、またはドアによって作成されないモジュール — つまり配置 |
Impact | 何が変更されるか：用語、および既存データ | リスクレジスター |
Relations | エンティティ、カーディナリティ、一方通行制約 | カラムと型 |
Surface | ルート、入力、出力、ステータス | リクエストボディの仕様、およびチェックID — それらはまだ存在しません |
Landing | 一方通行の扉、文字通りの形状と、却下された代替案 | リファクタリングで元に戻せるものはすべて |
フロー
- Discover（発見） — 読み取り専用の
scoutサブエージェントをディスパッチしてリポジトリ、.specs/STATE.md、.specs/LESSONS.mdを検査し、約30行のあいまいさ要約書を返します。Observableサーフェスと9つの暗黙の次元にわたって、ユーザーと本物の製品およびスコープのグレーゾーンを（一度に最大2質問、具体的な選択肢と推奨デフォルト値）を歩き、疑問が0になるまで続けます：discovery.md。 - Plan（計画） —
plannerサブエージェントを、確認された発見の決定とともにディスパッチし、.specs/features/<feature>/plan.mdを作成し、validate_plan.pyに合格させます。plan.mdをユーザーに提示し、迅速なサインオフを得ます：plan.md。 - Checks（チェック） —
plan.mdが承認されたら、自律的に実行します。専用のspecifierサブエージェントをディスパッチして.specs/features/<feature>/checks.md（主張＋証明、Coverage結合、Swept、## Handoffバッチサイジング）を導出し、validate_checks.pyに合格させ、その後、コードやテストが書かれる前にそのサブエージェントを終了します：checks.md。 - Build（構築） —
specifierが終了した後、各スライス（S1、S2、...）ごとに1つの新しいbuilderサブエージェントを順次ディスパッチします。各ビルダーは、割り当てられたスライスのチェックからテストを作成し、実装し、証明を実行し、checks.mdにBoundaryを記録し、check_commit.pyでコミットして終了します：build.md。 - Verify & Fix（検証と修正） — 新しい
verifierサブエージェントを<feature base>..HEADに対してディスパッチし、verification.mdを作成し、validate_verification.pyを実行します。FAIL の場合、fixerサブエージェントをディスパッチし、再検証します（最大3ラウンド）：verify.md。 - Orchestration & Subagent Dispatch（オーケストレーションとサブエージェントディスパッチ） — 薄型オーケストレーターのルール、コンテキストウィンドウ予算、マルチエージェントマッピング（
antigravity、claude、codex）：orchestration.md。 - Durable Memory（永続メモリ） — プロジェクト決定（
STATE.md）、セッションハンドオフ、検証ベースの教訓（lessons.py）：memory.md。
スクリプト
<skill-dir> をこの SKILL.md を含むディレクトリとして解決し、python3 <skill-dir>/scripts/<name>.py を呼び出します。カレントワーキングディレクトリがプロジェクトルートと異なる場合は --root を渡します。ゼロ以外の終了コードは停止して修正することを意味します。
| タイミング | コマンド |
|---|---|
| パイプラインフェーズと次のサブエージェントロールの検査 | orchestrate.py status <feature> --root <dir> |
| 分離されたサブエージェントプロンプトの生成 | orchestrate.py prompt <feature> --role <scout|planner|specifier|builder|verifier|fixer> --root <dir> |
| オーケストレーター経由のフェーズゲート実行 | orchestrate.py gate <feature> --phase <plan|checks|verify> --root <dir> |
CLI経由のサブエージェントディスパッチ（--dry-run も可） | orchestrate.py dispatch <feature> --role <role> --agent <antigravity|claude|codex> [--dry-run] |
plan.md の提示前 | validate_plan.py <feature> |
BUILD 開始前 | validate_checks.py <feature> |
| 各コミット前 | check_commit.py --message "<msg>" |
| 完了宣言前 | validate_verification.py <feature> |
| 蒸留時 | lessons.py add ... |
| バリデーター、スクリプト、テンプレート編集後 | selftest.py |
サブエージェントとハンドオフ
すべてのフェーズは、独自のサブエージェント呼び出し内で厳密に分離されています（scout -> planner -> specifier -> builder [S1] -> builder [S2] -> ... -> verifier -> fixer）。specifier（CHECKS）と builder（BUILD）を同じサブエージェントで決して組み合わせないでください。BUILD 中に、機能に複数のスライス（S1、S2、...）がある場合、各スライスに対して1つの別個の builder サブエージェントを順次ディスパッチし、各ビルダーがクリーンなコンテキストウィンドウで開始し、迅速に終了し、グリーンでスライスをコミットし、薄型オーケストレーターに進捗更新を返すようにします。
最後のビルダースライスがグリーンで戻ったとき、オーケストレーターはユーザーに尋ねることなく、同じターンで独立した verifier サブエージェントを直ちにディスパッチします。
知識連鎖
厳密な順序で：既存のコードと規約、プロジェクトドキュメント、ライブラリドキュメント（利用可能な場合はContext7）、ウェブ検索、その後不確かとしてフラグを立てます。API、フラグ、コマンド、振る舞いを決して発明してはいけません。
出力動作
成果物を生成し、フェーズを説明しないでください。判定を先頭に持ってきてください。決定事項を断定的に述べてください。フィラーや機械的な回避表現は削除してください。セクションの見出しは英語のままにしてください（ゲートによって検証されるスキーマです）。