flowとは

flow はゲート付きビルドハーネスである。アイデアから真の完了証拠——デプロイ済みURL、インストールして動くCLI、importできるライブラリAPI、自らの完了定義に到達したスキル——までを、正直に満たさなければ進めないゲートを通して歩かせる。

登録するサービスでもなく、コードが依存するフレームワークでもない。コーディングエージェントにインストールするスキルである。flowが握るのはゲートと証跡だけ。ランタイムには決して触れない。 スタンドアロンだ：AgentKitもclaudekitも不要。ただし、それらのエンジンがあれば任意のマルチモデルレビューが解放される。

存在理由

コーディングエージェントは、もっともらしい計画、もっともらしい調査文書、作業完了のもっともらしい主張を喜んで出す。各成果物は単体ではよく読める。失敗は局所的ではなく構造的だ：ループ内の何も「ノー」と言う位置にいない。

被害の大半を占める失敗モードは2つある。

進捗に見える書類。 捏造された競合の引用を含む調査文書は、どんな構造チェックも通る。C級の機能をB級に書き上げたスコープ文書も通る。どちらもよく読める。どちらも現実との接触に耐えない。

完了していない「完了」。 テストが緑でブランチがマージされたという理由で、エージェントはカード完了を報告する。誰もページを開いていない。誰もコマンドを実行していない。「Tests pass」は、終端状態に静かに昇格された中間状態だ。

flowの答え

3つの約束。あとはすべてここから従う。

完了とは現実世界の証拠である。 すべてのカードは証拠を先に名指しし、ゲートはカードをdoneにできる前にその証拠の貼り付けを要求する。Webプロジェクトなら稼働中URLと実際の curl 出力。CLIなら実際の呼び出しと終了コードだ。マージ済みコードと緑のCIは明示的に認めない。完了とは現実世界の証拠を参照。

2つの層が合意しなければならない。 決定的スクリプトがごまかし可能な mechanics を捕まえる——未チェックのボックス、残った [FILL] プレースホルダ、空の証拠——exit 0か1で出る。スキルを読むモデルが、スクリプトにできないことを捕まえる：捏造された調査、すり替えられたスコープ、auth列のないエンドポイント。ゲートは両者が合意したときだけ通過する。2層ハーネスを参照。

ゲートで潰すことは正当な結果である。 「進め」しか言えないハーネスはベルトコンベアだ。Scopeで弱いアイデアを潰すのは安くて賢い。flowはそれを、回避すべき失敗ではなく一級の結果として扱う。

flowではないもの

プロジェクト管理ツールではない：ボードもバーンダウンも見積もりもない。コードジェネレータではない——コードを書くエージェントや人間にゲートをかけるだけだ。CIシステムでもないが、証拠の規則は大半のCIゲートより厳しい。そして、エージェントを賢くするラッパーでもない。エージェントを説明責任のあるものにする。それは別物であり、より有用だ。

実行の形

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

計画は flow/ 配下のファイルとして生きる6つのゲート付きステージだ。出荷は cards/ 配下の一連のカードであり、各カードはステージ05で書かれた契約に対する1つのスコープ付きビルドセッションだ。セッションの合間には耐久ストアがdebt・レトロ・トレース・プレイブックを保持する。次のセッションは過去の痛みを見た状態で始まる。

チャットがデフォルトの入口だ——作りたいものを説明すれば、コンシェルジュが次の一手を1つ提案する。/flow next のような手入力の動詞は、チャットルーティングに常に勝つ。

2層ハーネス

これが flow の核となる考えだ。あとはすべてその帰結である。

ゲートは性質の異なる2種類の失敗を捕まえなければならず、単一のコンポーネントが両方を得意にすることはない。そこで flow は2つの層を走らせ、ゲートは両方が合意したときだけ通過する。両層、さもなくば通過していない。

第1層 — 機械ゲート

runner/flow.sh は決定的なbashエンジンで、exit 0か1で出る。ステージとカードのライフサイクルを握り、ごまかしやすく検出も容易なものをチェックする：

未チェックのゲートボックス（## Open decisions 配下の残った - [ ] 箇条書きを含む——同じスキャナが両方を処理する）
残った [FILL] プレースホルダ
カードステータスの妥当性
doneを主張するカードの空の ## Evidence セクション

exitコードがグラウンドトゥルースだ。モデルへの規則は単刀直入だ：常に先にスクリプトを実行し、exitコードを読み、忠実に中継する。自分の判断で置き換えてはならない。

この層にできないのは意味を読むことだ。本物の競合引用と捏造されたものを見分けられない。正直なB級機能と、B級に書き上げられたC級を見分けられない。

第2層 — 意味ゲート

それがモデルの仕事だ。スクリプトが通過した後、スキルはステージごとのチャレンジ群を適用し、オペレータが進むことを許可する前に行う。ここで捏造された調査が問われ、すり替えられたスコープが名指しされ、auth列のないエンドポイントが旗を立てられ、証拠セクションに貼られた「tests pass」が中間状態として却下される。

指示は対称的で、両方向に重要だ：中身のない成果物を黙って進めてはならない。健全なものを黙って止めてもならない。スクリプトは通過したが内容が弱いとき、オペレータにはそのまま告げる——機械的には通過したが、質的には弱い——そしてオペレータが決める。

なぜ1つの賢いチェッカーにしないのか

スクリプトは意味を判断できない。モデルは mechanics について決定的であることを信頼できない。分ければ各失敗クラスを実際に捕まえられる場所に置け、ごまかし可能な半分を説得可能ではなく強制可能にする。exit 1 の意見を言いくるめることはできない。捏造された市場引用を検出する正規表現も書けない。

もう1つ、微妙だが重要な利点がある。機械層が実exitコードを持つ別プロセスであるため、ゲートについてのモデル自身の主張は監査可能だ。「ゲートは通過した」と言うエージェントを、そのエージェントが生み出していない信号と突き合わせられる。

第3の層：耐久メモリ

両層の下に耐久層がある——intakeとリスクレーン、storyとproof、traceとtier、decision、backlogを保持するPythonとSQLiteのストアだ。gracefulに縮退する：python3 がなければゲートは動き続け、この層だけがオフになる。

+---------------------------------------------------------------+
|  Semantic layer  -  SKILL.md + references/  (the model)       |
|  judgment: hollow content, grade-laundering, adversarial      |
|  review, agent orchestration, work mode, auto tiers           |
+---------------------------------------------------------------+
              | calls (exit code = ground truth)
              v
+---------------------------------------------------------------+
|  Mechanical layer  -  runner/flow.sh  (bash, exit 0/1)        |
|  stage/card lifecycle, gate checks, debt ledger,              |
|  design check, harness passthrough                            |
+---------------------------------------------------------------+
              | reads/writes (best-effort, graceful degrade)
              v
+---------------------------------------------------------------+
|  Durable layer  -  Python + sqlite3 (flow-owned)              |
|  intake/risk-lane, story+proof, trace+tier, decision, backlog |
+---------------------------------------------------------------+

外部メモリである。進捗と摩擦はセッションとコンテキストウィンドウを越えて生き残る。長いプロジェクトが会話の中だけで生きるときの緩やかな劣化への解毒剤だ。

エージェントへの帰結

エージェントは差し替え可能。ゲートは固定だ。ステージは、専門エージェントがいれば起草を委譲でき、いなければ内蔵動作にフォールバックする。ゲートはどの経路でも同一なので、エージェントの不在がバーを下げることは決してない。エージェントが起草し、ゲートが裁く。

任意のクロスベンダーエンジンにも同じ規則が適用される。第2・第3のモデルがカードをレビューできるが、その評決はトリアージに資するだけ——自動で通すことも落とすこともない。

完了とは現実世界の証拠

すべてのカードは完了証拠を先に名指しし、ゲートはカードをdoneにできる前にその証拠の貼り付けを要求する。「Tests pass」と「コードがマージされた」は中間状態だ。完了では決してない。

防ぐ失敗

エージェント支援ビルドが壊れる最も一般的な形はバグではない。ステータスだ。テストが緑で、レビューが承認され、ブランチがマージされたという理由でカード完了が報告される。これらの主張はすべて真だ。誰もページを開いていない。

これらの信号は各々、気にかけているものの代理を測っている。テストはシステムに対する自分のモデルを自分自身に対して測る。マージはdiffへの合意を測る。どちらも実際の稼働世界に触れない。代理は現実から静かにずれ、ダッシュボードがすべて緑のまさにそのときにずれが見えなくなる。

修正は代理を増やすことではない。実物の一度の観測を要求することだ。

プロジェクトタイプごとの証拠

プロジェクトタイプが証拠の形を決める。精神はどの場合も同一だ：誰かがデプロイされた現実に触れ、返ってきたものを貼った。

プロジェクトタイプ	完了証拠
`web`	稼働中のデプロイ済みURLと実際の `curl` 出力
`cli`	ツールがインストールでき、実際の呼び出しが期待通りの出力と終了コードを返す
`library`	公開APIがimportでき、使用例が動き、カバレッジ閾値を満たす
`skill`	スキルホームにインストールされ、実際の実行が自らの完了定義に到達する

/flow project-type <type> でタイプを設定する。デフォルトは web。契約の継ぎ目とタイプ行列の残りはプロジェクトタイプ。

証拠にならないもの

どれほど立派でも、プロセスの成果物は証拠にならない：

承認済みプルリクエスト
緑のCIバッジやワークフロー実行
出荷内容を説明するリリースノート
何も見つからなかったコードレビュー
作業完了を言うエージェント自身の要約

機械層はここに下限を強制する：プロセスの文章だけの証拠セクションを持つカードは却下される。その場の議論で規律を骨抜きにできない。下限の先で、意味ゲートがより難しい問いを立てる——この証拠は世界なのか、世界の記述なのか？

エージェントの自己評価は明示的に除外される。すべてのゲートのグラウンドトゥルース信号は、エージェントが生み出していないものだ：スクリプトのexitコード、実際の検証コマンドの出力、ライブチェック。

空の証拠セクションをゲートがこれほど攻撃的に拒否する理由

  [x] status is 'done' but ## Evidence is empty (paste world-state proof: URL/curl/DB row)
FAIL: C-001 has gate violations (above).

コードが完成し正しくても発火する。理由はこうだ：証拠を取る最も安い瞬間は、どうせ稼働物を見ていたその瞬間だ。後回しにすれば、記憶から再構成される。再構成された証拠と捏造された証拠は見分けがつかない。

同じ理由がCLI所有の反転 /flow card done C-NNN を駆動する：check と同じ規則を適用し、ゲートが落ちれば反転を取り消す。中身のないdoneを生むコードパスは存在しない。

正直な出口

カードが今どうしても証明できない——デプロイ先がまだない、外部サービスが落ちている——なら、答えは証拠を弱めることではない。露出をdebtとして、書面で、閉じる条件付きで記録することだ。debtは可視で、recall に現れる。中身のないdoneは不可視で、本番に現れる。

その行を開く方法と、スキップが拒否されるときは debtでゲートをスキップする。証拠をカードに貼る方法はカードの作成とチェック。

意味チャレンジ

機械的通過は、ファイルが構造的に完全だという意味だ。内容が真かどうかは何も言わない。意味チャレンジは、スクリプト通過後にモデルが適用するステージごとの問いの集合であり、ステージごとに意図的に特化している。各ステージが異なる嘘を誘うからだ。

Researchは捏造された競合と出典のない数字を誘う。Scopeはすり替えを誘う——作りたい機能を、稼いだ等級より1つ上に書き上げる。PRDは所有者のない要件と、機能のない痛みを誘う。Contractはauth列のないエンドポイントを誘う。カードは世界ではなくプロセスを記述する証拠を誘う。汎用的な「これは良いか？」プロンプトではどれも確実に捕まらない。ステージごとの名指しチャレンジなら捕まる。

指示は両方向に走る：中身のない成果物を黙って進めてはならない。健全なものを黙って止めてもならない。機械的には通過したが弱く読めるとき、オペレータにはそのまま告げ、オペレータが決める。この層が実際に機能することの行動的証明もある——/flow eval は中身がないが機械的にはクリーンなfixtureを fresh な判定者に食わせ、旗が立つかを採点する。下限であり保証ではない。

汎用ではなくステージごと

Idea (00)。 ピッチは本当に3文か（誰が / 痛み / 何をする）？名指しの人物は実在の具体的な人物や集団か、「ユーザー」ではないか？痛みは具体的か、カテゴリではないか？forge-ideaの儀式は任意だ。このゲートがチェックする条件に決してならない。

Research (01)。 捏造リスクが最大。3つの競合を実際に開いたか？web・市場プロダクトなら：不満は出典リンク付きの本物の引用か、最初の10ユーザーのチャネルは具体的な場所か？cli・library・skill・内製ツールなら：一次の摩擦は具体的で観測されたものか、受益者は名指しか——「市場チャネルなし」はここでは想定内であり、潰す理由ではない。コストは実数でなければならず、推測ではない。

Scope (02)。 すり替えに注意。CはCと呼べ（リアルタイム、ゼロからの決済、自作認証、自律エージェントパイプライン、重い並行性）。重要なプロダクト選択が開いたままなら（クォータ、身元キー、テナンシ、応答契約、強制の所有者）、止まって列挙する——設定可能なデフォルトは権威ではない。## Assumptions 配下の箇条書きが、オペレータやADRの権威なしにプロダクト法をエンコードしているなら、それは未解決の決定か停止であり、黙ったデフォルトではない。

PRD (03)。 成功指標は実数か、「より良いUX」ではないか？すべての痛みは証拠を引用し、それを殺すv1機能を名指しているか。すべてのv1機能は少なくとも1つの痛みを殺すか？どちら側の孤児もスコープドリフトだ。見知らぬ人がこれだけでv1をビルドできるか、オペレータに何も聞かずに？

ADR (04)。 各決定は本物の却下案を名指しているか、藁人形ではないか？ストレージ・認証・デプロイは実際に決まったか、「TBD」ではないか？やらないリストは、 deferred について正直か？

Contract (05)。 インターフェースはプロジェクトタイプの継ぎ目だ：web = エンドポイント、cli = コマンド + フラグ + 出力/exit、library = 公開関数 + 引数 + 戻り値、skill = コマンド/ファイル。すべてのPRD機能は少なくとも1つのインターフェースに対応し、逆も同様。すべてのインターフェースは入出力の形を持ち、名前は漂流しない。アクセス/効果列はすべてのインターフェースで実物だ——webプロダクトで空欄にするな。自身の信頼源として名指す文書があれば、通過前に契約をそれと突き合わせて読む。ここの矛盾は「通過」として出荷され、すべてのカードが継承する。

カード（/flow check C-NNN）。 スコープは1つか？## Independent test はユーザー可視の証拠か、「単体テストが通る」ではないか？diffは ## Allowed files 内に収まるか？形は flow/05-contract.md と完全一致か？## Evidence は現実世界か——クリックできるURL、実際のcurl出力、DB行——各項目はそれを生んだ成果物やコマンドを名指しているか？

Consistency（/flow consistency）。 助言的。ビルドパスを決して止めない。ランナーのIDベース通過の後も、モデルが捕まえなければならない：中身のないカバレッジ（それを届けないカードに貼られた FRn）、成果物間で矛盾する要件、v1として復活したカットリスト機能、用語の漂流（ticket / issue / request）。

モデル向けのチャレンジ全文はフッターにリンクされたメンテナファイルにある。セキュリティクラスのスキップとautoのHALTはこのページではない。作業が止まらなければならないとき。

システムアーキテクチャ

flow は協調する3つの層とオンディスクの成果物だ：ごまかし可能な mechanics のための高速で決定的なエンジン、判断のためのスキル、記録がセッションを生き延びるための耐久ストア。公開のオペレータ像は4つの部品だ——スキル、ランナー、成果物、2つのバージョンチャネル。

スキル

意味層は SKILL.md と skills/flow/references/ 配下のプレイブックだ。ホストエージェントが読むもの：ディスパッチ、ゲートキーパー、オーケストレーション。runner/flow.sh が0を返した後にこの層が上のステージごとのチャレンジを走らせる。スクリプトのexitコードを雰囲気の通過で置き換えることは決してない。

ランナー

機械層は runner/flow.sh だ。bash、決定的、exit 0か1。ステージとカードのライフサイクル、ゲートチェック（[FILL]、ボックス、空の証拠）、debt台帳、デザインチェック、ハーネスのパススルーを握る。exitコードがグラウンドトゥルースだ。常に先に実行し、常に忠実に中継する。

下にはflow所有のPythonとSQLiteのCLIがあり、intakeとリスクレーン、storyとproof、traceとtier、decision、backlogを保持する。python3 がなければゲートは動き続け、この耐久層だけがオフになる。

成果物

成果物はスキルホームの内側ではなく、ビルド対象のプロジェクトの中に生きる：

flow/00-idea.md .. 05-contract.md   計画、ゲート付き
cards/C-NNN.md                      出荷単位
MODE, RETRO.md, DEBT.md, AUTO-LOG.md, DESIGN.md
.flow/harness.db                    耐久記録

flow/ 配下の計画ファイルがゲート付きステージだ。cards/ 配下の各カードはステージ05の契約に対する1つのスコープ付きビルドセッションだ。台帳ファイルと .flow/harness.db が、debt・レトロ・トレースを次のコンテキストウィンドウへ生かす仕組みだ。

2つのバージョンチャネル

配布は同じ正準ツリーに注ぐ2つの並行チャネルだ。npmインストーラ（npx @manhquy/flow-skill@latest）が主要経路：純Node、シェル不要。リポジトリのインストールスクリプトは開発とCIで使う参照実装だ。どちらも同じスキルホームを書く。プロジェクトはゲートやカードを再発行せずにチャネルを切り替えられる。

  monorepo skills/flow/  --npm run sync-->  npm-wrapper/skills/flow  --npm pack-->  registry
         |                                         |
         | install.sh / agent skill homes          | npx @manhquy/flow-skill@latest
         v                                         v
  ~/.claude/skills/flow                     same tree via installer CLI

これらのチャネルは異なる成果物にバージョンを付ける。スキル製品はゲート・SKILL.md・ランナー・reference・テンプレートにバージョンを付ける——ビルドを裁くものだ。npmパッケージはインストーラCLIにだけバージョンを付ける：エージェント検出、コピー先、フラグ。一致しないのが当然だ。--help は両方の数字を出力する。どの文書からではなく、自分のマシンで確認すること。ペアリングの話（どちらの数字をpinするか）は 2つのバージョン番号。

次に行く

ステージパイプライン — 各ゲートが何から守るか。
インストールと初回実行 — ゲートの拒否を見る。
カードの作成とチェック — 証拠を貼り、doneにする。

メンテナのホーム（公開ページではない）：docs/adr/0001-discipline-layer-identity.md、skills/flow/references/gate-rules.md、docs/system-architecture.md。