ステージパイプライン

Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review -> Deploy -> Verify-live -> Retro
|------------------ planning (files in flow/) ------------------|  |------- shipping (inside cards/) -------|

パイプラインは作るべき文書のチェックリストではない。各ステージは、ビルドのその地点で起きがちな特定の自己欺瞞があるから存在し、ゲートはその欺瞞を狙う。

計画：6つのゲート付きファイル

計画の成果物は flow/ 配下に生き、順序が交渉不可になるよう番号が付く。

00 — Idea。 3文のピッチ：誰が問題を抱え、今日何をしていて、代わりに何をするか。ゲートが見ているのは、問題の服を着た解決策ではなく問題だ。プロジェクト全体でものを潰す最も安い場所がここだ。

01 — Research。 既にあるもの：競合、稼働システム、実際の価格。規則は先に調べろ、証拠であって雰囲気ではないだ。このステージは捏造が最も誘惑的で最も高くつく。捏造された競合の上に建てた計画は、何週間も自信満々に間違う。捏造された引用をスクリプトは検出できない。意味ゲートが唯一の防御だ。

02 — Scope。 機能に等級を付け、切る。ここでの典型的な失敗はすり替えだ——作りたいがためにC級の機能をB級に書き上げる。Scopeは大半のプロジェクトが救われるか失われる場所だ。だから work モードはまさにこの一点でのみ明示的なオペレータ承認のために止まり、他では止まらない。

03 — PRD。 生き残ったスコープが番号付き機能要件になる。ここで書いたすべての FRn は、後にカードに主張され、契約のインターフェースに serve されなければならない。その追跡は機械的に監査できる。計画からビルドの間に要件が静かに蒸発できない。

04 — ADR。 アーキテクチャ決定。却下したものとその理由を含む。却下案こそ価値ある部分だ：半年後、決着済みの問いを誰も蒸し返さない理由になる。

05 — Contract。 インターフェースを、コードが存在する前に書く。Webプロジェクトならメソッド・パス・認証・リクエストとレスポンスの形。CLIならコマンド・フラグ・出力の形・終了コード。ライブラリなら公開API面。スキルならエージェントが読むコマンド面。

Contractが決してスキップできない理由

他のすべての計画ステージは、正直に記録されたdebtでスキップできる。ステージ05はできない。決して。

Contractは継ぎ目だ。作る側はそれに向けて作り、使う側はそれをもとに作る。間の形が固定されているからこそ、両側は独立に進める。スキップしても時間は節約できない。コストが結合に移るだけだ。半分できた両側が不一致を発見し、誰かが片方を書き直す。

続く規律は厳しい：形を即興で作らない。形が間違っていたら、先に契約を修正してからコードを変える。今はnullやスタブで形を守れ。その実値が後のカードで出荷されるときも。

Contractがプロジェクトタイプに合わなければ、適応させる——「エンドポイント」を「インターフェース」や「コマンド」と読む——スキップするのではない。

出荷：カード

ステージ05が通過したら、/flow card でビルドカードを切る。各カードは1つのスコープ付きビルドセッションだ：allowed-filesリスト、実装する要件、verifyブロック、独立テスト、そして空から始まる証拠セクション。

ビルドし、敵対的にレビューし、デプロイし、ユーザーとしてライブで検証する。カードがdoneになるのは、現実世界の証拠が貼られ、チェックゲートが通過したときだ——テストが緑のときではない。

ブラウンフィールド：stage 00-inspect

既存コードベースはIdeaから始めない。/flow assess が flow/00-inspect.md を足場掛けしてゲートをかける——スタック、プロダクトが今日することとすべきこと、リスク、テストのベースラインを覆う現状マップだ。オペレータがレビューする。既存システムの計画が、リポジトリのREADMEの主張ではなく実際にそこにあるものに根ざすためのものだ。

Retro

実行ごとに正直な1行。オペレータが書き、エージェントは決して書かない。耐久層に注がれ、次のプロジェクトの recall がこのプロジェクトの痛みを浮かべる。

潰すことは正当な出口だ

すべてのゲートに結果は3つある。2つではない：通過、阻止、潰す。「進め」しか言えないハーネスは、コンプライアンス儀式付きのベルトコンベアだ。Scopeで弱いアイデアを潰すのは、ビルドで取り得る最も安い良い決定だ。

`/flow next` で進む

/flow next は今いるステージをゲートチェックし、通過したときだけ次を開ける。ランナーは flow/ 内の既存の最高連続ステージファイルを現在とみなす——ステージファイルは、それ以前の全ステージが存在するときだけ数える（00–04 なしの単独 05 は現在とみなさない）。計画が完了するのは6つのステージゲートすべてがクリーンのときだけ。そのとき初めて /flow card が開く。

機械層が落ちると、何が悪いかを正確に行番号付きで出力して止まる——未チェックのゲートボックス、残った [FILL] プレースホルダ。FAILは決して進まない。リストが診断のすべてだ：名指しのファイルを開き、その行を直し、/flow next を再実行する。どのボックスが空だったか推測しない。

スクリプトが通過したら、進む許可の前に、完了したばかりのステージの意味チャレンジが適用される。機械的にはクリーンだが中身のない成果物も、弱いと名指される。teach モードではエージェントはボックスをチェックも成果物を代筆もしない。何が落ちているかを告げるだけだ。

潰すことは正当な終端状態だ。どのゲートで止まることも、特にScopeでは、flowの失敗ではなく名誉ある結果だ。通過・阻止・潰すが3つの答えだ。「進め」しか言えないハーネスはベルトコンベアだ。

プロジェクトタイプ

flow はwebの形で生まれた。他種のソフトウェアを支援する正直な方法は、ゲートを曖昧に一般化することではなく、変わる3つを正確に名指すことだった。ステージ05の前に /flow project-type web|cli|library|skill で設定する。値は PROJECT_TYPE ファイルに保存され、デフォルトは web。引数なしで実行すると現在の値とそれが含意する完了証拠規則を出力する。

タイプが適応させるのは、ステージ05の契約の継ぎ目、標準カード列、完了証拠の意味だ。あとはすべて——各ゲートの精神、「コードより先に契約」、「完了とは現実世界の証拠」——不変だ。後からタイプを変えるのは契約の再訪を意味する。今は安く、後では高い。

web。 契約：HTTPエンドポイント（メソッド、パス、認証、リクエスト、レスポンス）。OpenAPIを提供。完了：稼働中のデプロイ済みURLと実際の curl 出力。
cli。 契約：コマンド、フラグ、出力の形、終了コード。完了：ツールがインストールでき、実際の呼び出しが期待通りの出力と終了コードを返す。CLIビルドの初手：/flow project-type cli。
library。 契約：公開API面——公開関数と型とその形。完了：公開APIがimportでき、使用例が動き、カバレッジ閾値を満たす。
skill。 契約：エージェントが読むコマンドとファイル。完了：スキルホームにインストールされ、実際の実行が自らの完了定義に到達する。スキルビルドの初手：/flow project-type skill。

CLIビルドは薄めたwebビルドではない：生むべき証拠は同じく具体的だ。デプロイ済みURLではなく、インストールされたツールと実際の終了コードという形を取るだけだ。ゲート自体は不変——証拠の形だけが動く。

ステージ05のゲート文言の一部はまだ「エンドポイント」と言い、auth列を求める。webの味付けだ。他タイプでは「エンドポイント」を「インターフェース」や「コマンド」と読み、認証の代わりに書き込みと副作用を置く——ステージの前文がその適応を明示的に許可している。等価なドリフトなしチェックは、タイプごとの完了証拠が実際に通過することだ。

プロジェクトタイプ行列

/flow project-type <web|cli|library|skill> で設定。PROJECT_TYPE に保存。デフォルト web。

タイプ	契約の継ぎ目（ステージ05）	完了証拠	カード列
`web`	HTTPエンドポイント——メソッド、パス、認証、リクエスト、レスポンス。OpenAPIを提供	稼働中のデプロイ済みURLと実際の `curl` 出力	scaffoldと `/healthz`、垂直スライス、バックエンド、契約テスト、UIモック、フロントエンド、e2e
`cli`	コマンド、フラグ、出力の形、終了コード	ツールがインストールでき、実際の呼び出しが期待通りの出力と終了コードを返す	scaffoldと1つの実コマンド、サブコマンド群、テスト、クリーンディレクトリでのインストールスモーク
`library`	公開API面——公開関数と型とその形	公開APIがimportでき、使用例が動き、カバレッジ閾値を満たす	scaffoldとコアAPI、APIの反復、テスト、動く使用例、publishドライラン
`skill`	エージェントが読むコマンドとファイル	スキルホームにインストールされ、実際の実行が自らの完了定義に到達する	scaffoldと1つの動くコマンド、referenceとlaw、インストール、ドッグフーディング実行

4タイプ共通の定数：すべての要件はインターフェースに対応し、すべてのインターフェースはコードより先に形を書かれ、契約は継ぎ目であり、「tests pass」や「マージ済み」は決して完了ではない。

モードと実行戦略

flow には4つのモード軸があり、真に独立している。プロジェクトごとに各軸を設定し、仕事の要求に応じて組み合わせる。

オーサリングモードはゲート成果物を誰が書くかを決める：teach（デフォルト）はあなたが書き、エージェントはゲートキープだけする。work はエージェントが一度インタビューし、ステージ00から05を起草し、スコープの承認でのみ止まる。

プロジェクトタイプは完了の意味を決める——webなら稼働中URL、CLIなら実際の呼び出しと終了コード、ライブラリならimportできるAPI、スキルならインストールされた実行。

実行モードはカードのビルド方法を決める：手動（card、ビルド、checkをあなたが駆動）か、auto（セキュリティクラスで止まる段階的自律実行）。

グリーンフィールド対ブラウンフィールドは開始点を決める：新規ならステージ00-idea、既存コードベースならゲート付き現状評価。

どの軸もバーを変えない。ゲートと完了規則はすべての組み合わせで同一だ。モードが動かすのはオーサーシップ・証拠の形・駆動だけであり、ゲートの高さではない。

未解決の決定を明確にする

未解決のプロダクト決定は、Scope・PRD・Contractの成果物上の ## Open decisions 見出し配下に - [ ] 箇条書きとして生きる。ゲートが既に使うのと同じボックススキャナが数える。つまり未確定の決定は、誰も読まないコメントに座るのではなく、本当にステージを止める。

/flow clarify は残った箇条書きを、そのセクションに絞って出力し、常にexit 0だ——助言的な出力器であり、第2のゲートではない。確定は境界のある任意の書き戻し儀式だ：箇条書きを1つずつ片付け、決定を成果物に記録し、ボックスをチェックする。clarify の何も /flow next の前提条件ではない。ボックスを強制するゲートスキャナが既にそうだからだ。

ステージ成果物

ランナーは各ステージの解放に応じてテンプレートをプロジェクトにコピーする。計画の成果物は flow/ 配下、出荷単位は cards/ 配下、台帳はプロジェクトルートだ。下のパスはファイルであり、見出しではない。

パス	ステージ	内容
`flow/00-idea.md`	00	3文のピッチ：誰が問題を抱え、今日何をしていて、代わりに何をするか
`flow/00-inspect.md`	brownfield	現状評価：スタック、プロダクト目標に対する機能、リスク、テストベースライン
`flow/01-research.md`	01	既にあるもの——競合、稼働システム、実際の証拠
`flow/02-scope.md`	02	等級付き機能、カット、スコープ承認
`flow/03-prd.md`	03	番号付き機能要件（`FRn`）
`flow/04-adr.md`	04	却下案を含むアーキテクチャ決定
`flow/05-contract.md`	05	インターフェースをコードより先に書く。継ぎ目。スキップ不可
`flow/constitution.md`	任意	オペレータ執筆のプロジェクトごとの不変条件、助言的
`cards/C-NNN.md`	build	1つのスコープ付きビルドセッション：allowed files、implements、verify、独立テスト、証拠、リスク
`MODE`, `PROJECT_TYPE`	—	オーサリングモードとプロジェクトタイプ
`DEBT.md`, `RETRO.md`, `AUTO-LOG.md`	—	意図的スキップ、レトロ行、自律実行ログ
`.flow/harness.db`	—	耐久記録

すべての計画成果物は [FILL] プレースホルダとゲートボックス付きで出荷される。どちらも機械的にスキャンされ、未解決のままではステージが落ちる。未解決の決定は ## Open decisions 見出し配下に属し、同じスキャナが数える。