the-flow

/the-flow — SDD パイプラインのディスパッチ

SDD パイプライン全体を対象とする公開スキルです。フローアーキテクチャパターン（docs/skills-pipeline/flow-architecture.md）に基づいて構築されています。契約に基づく動詞を持つ各ステージのサブスキルは references/stages/ に、ガイドモードのエンジンは references/00-routing.md に、コーチングの語り口は references/coach.md にあります。フローを初めて使う場合は、references/getting-started.md をご覧ください。

段階的開示が契約です。現在のステップに対応するサブスキルを1つだけ読み込んでください。最初にすべてを読むことはありません。

2つの読み込み方法

ガイドモード — /the-flow（引数なし、または <slug> / <ord>-<slug>）：

1. references/00-routing.md（エントリーパス、状態の契約、Graph）と references/coach.md（レール、ナレーション、表示してから提案）を読み込みます。
2. 00-routing.md に従って、新規開始／再開／引き継ぎを解決します。ステップが受け入れられたときに、現在のステージのサブスキルのみを読み込み、区切りをコーチングします。
3. ガイドモードは、すべての the-flow 状態を管理し、そのすべてを harness flow nav 呼び出しを通じて進行させます。位置とセッションバッグの両方が対象です。フライトプラン（the-flow.json → the-flow.md）が唯一の状態基盤です（plan 024 — CLI が生成します。手書きは禁止です。まず機能の事前確認を実行してください。§ 前提条件を参照）。セッションで最初にフライトプランを変更する前に、references/flight-plan-ops.md も読み込んでください。ナビゲーションモデル、主軸と寄り道のルール、動詞のフラグと注意点が記載されています（必要時に読み込み、最初からは読み込みません。サブスキルから読み込むこともありません）。

直接ジャンプ — /the-flow <id> <verb> [flags]：

1. 以下のレジストリでステージを解決します。IDと動詞はそれぞれ単独で解決できます（6 と入力するのは implement と入力するのと同じです）。両方が指定された場合、同じステージを示している必要があります。異なる場合はレジストリを表示して、どちらを指しているのか確認してください（推測してはいけません）。
2. そのサブスキルのみを読み込み、指定されたフラグを使って実行します（動詞がこれまでに受け取っていたものと同じフラグです）。
3. コーチング、レール、状態への書き込みはありません。また、ハーネスの区切りもありません（ハーネスによるオーケストレーションはガイドエンジンの役割です。直接ジャンプは、設計上ハーネスを使わず、動詞のみを実行します）。成果物は従来どおりの場所に保存されます。次回のガイドモード実行時に、存在をもとに検出して状態を追いつかせます。

サブスキルが引用先として references/00-routing.md § 共通規約を必要とする場合、そのサブスキルから遅延読み込みしてもかまいません。これも段階的開示です（パターンで認められている例外1）。実行していないステージのサブスキルを読むことは認められません。

レジストリ

この表がマスターです（Graph のマスターは 00-routing.md § Graph、references/getting-started.md はレンダリングされたビューです）。フローの ID を割り当て、動詞をモジュールに紐付け、各コントラクトを示します。

id	verb	module	consumes → produces	flags
1a	explore	references/stages/10-explore.md	意図 → research-dossier.md	"<intent>"
1b	plan	references/stages/20-plan.md	意図、ドシエ?、ワークショップ?、カバレッジ? → <slug>-plan.md（1 つのドキュメント：ビジネス仕様 + 実装計画、常に両方を 1 回のアトミックな処理で作成。ゲート G1–G7。/validate-v2 を自動実行。計画途中の確認事項については § 再入を参照）	"<intent>" [--simple] [--skip-clarify]
2c	workshop	references/stages/25-workshop.md	計画/仕様?、トピック → workshops/*.md（決定事項の正式な記録）	<plan> "<topic>" [--from-spec] [--list]
3a	adr	references/stages/35-adr.md	計画/仕様のコンテキスト → docs/adr/*.md	"<decision>"
5	tasks	references/stages/50-phase-tasks.md	計画 → tasks/<phase>/tasks.md + コンテキストブリーフ	--phase "<Phase N: Title>" --plan "<path>"
6	implement	references/stages/60-implement.md	計画、タスク? → コード + execution.log.md（フェーズは厳密に 1 つ）	--plan "<path>" [--phase "<Phase N: Title>"] [--subtask "<ORD-slug>"] [--companion] [--companion-slug "<slug>"]
6a	progress	references/stages/62-progress.md	タスクの結果 → 更新されたタスク表 + 実行ログ（各タスク後に implement 動詞が読み取ります。コンパニオンの振り返りを管理します）	--plan --phase --task --status [--companion-run-id] [--companion-slug]
7	review	references/stages/70-review.md	計画、コード → reviews/*.md	--plan "<path>" [--phase "<Phase N: Title>"]
8	ship	references/stages/80-ship.md	計画、レビュー → プッシュ済みブランチ + PR（リポジトリガイダンスを考慮）+ 監視対象の CI チェック。プッシュと PR のオープンはそれぞれ確認後に実行。マージは任意。テレメトリをフラッシュ（確認なし）	--plan "<path>" [--base "<branch>"] [--no-watch] [--draft]
8c	reconcile	references/stages/80-merge.md	（条件付きの寄り道 — ベースが分岐している場合）→ 調整/マージ計画。マージは PROCEED と入力した場合にのみ実行	--plan "<path>" [--target "<branch>"]
sync	sync	references/00-routing.md	フライトプラン + 計画アーティファクト → 調整済みフライトプラン：現在の知識が示す過去/現在/将来のすべてのフェーズ + ワークショップ + ハーネスのシームノードを補完します。冪等（完全なスパインに対しては何も書き込みません）。助言のみ、CLI 専用で、nav は進めません	（なし）— ガイド付きの各エントリで自動実行されます。オンデマンドでも呼び出せます

モジュールが指定パスにない場合は、その旨を伝えて停止してください。記憶を頼りにステージを作り上げてはいけません。

8 ship はスパインの最終ステージで、8c reconcile は条件付きの寄り道です（ベースが実質的に分岐した場合にのみ実行されます）。スパインには含まれません。入力された merge と従来の plan-8-v2-merge は 8c reconcile に解決されます（エイリアス表は下記）。 sync はメンテナンス用の動詞であり、ジャーニーのステージではありません。序数 ID を持たず、ステージアーティファクトを生成せず、カーソルを移動したりステージを実行したりすることもありません。これはエンジンのエントリごとに行うスパイン調整処理です（ルーチンは references/00-routing.md § スパインの調整にあります）。オンデマンドで誰でも実行できる動詞として公開されています（また、直接ジャンプして作成した計画や手動で採用した計画を 1 回の呼び出しで修復できます）。8c reconcile（分岐した Git ベースをマージします。これとは無関係です）とは異なります。不変条件 #11 を参照してください。

コマンド文法

表示するコマンドは常に /the-flow <id> <verb> [flags] 形式です。例：/the-flow 6 implement --plan "<path>"。 ID または動詞だけでも解決できますが、表示形式では必ず両方を指定します。対応しない組み合わせの場合は、レジストリを表示して確認します。このセクションが文法の唯一の定義です。他の場所にあるコマンド表記（説明文、状態ファイル、ビュー）はすべて、ここでの定義とレジストリの行から生成し、手書きしてはなりません。 メンテナンス用の動詞 sync は単独で解決されます（ID と動詞が同じトークンです）。/the-flow sync を実行すると、必要に応じてスパイン調整処理が実行されます。ステージフラグは指定できず、ジャーニーが先に進むこともありません。

古いスラッグの変換とエイリアス（読み取り時）

統合前に作成されたドキュメントやレガシー状態ファイルには、廃止されたスキルのスラッグを含むコマンドが記載されている場合があります（例：残存する .the-flow-state.json の pending_command。再開時の一度限りのバックフィルでのみ読み取られます — § State）。読み取り時に変換し、廃止されたスラッグを実行してはなりません。保留中のコマンドの現在の情報源は nav.next とコマンド文法です。表示時に生成し、保存はしません。フラグはそのまま引き継ぎます。ターゲットは ID＋フラグ形式で保存されます（完全なコマンド文字列ではありません）。表示または状態への書き込み時に、コマンド文法とレジストリを使って生成します。

廃止されたスラッグ／入力エイリアス	→ ターゲット（ID＋フラグ）
plan-1a-v2-explore	1a explore
plan-1b-v3-specify-and-clarify	1b plan
plan-1b-v2-specify	1b plan
plan-2-v2-clarify	1b plan（モジュール § Re-entry）
plan-2c-v2-workshop	2c workshop
plan-3-v3-architect	1b plan
plan-3-v2-architect	1b plan
入力 specify	1b plan
入力 architect または ID 3	1b plan
plan-3a-v2-adr	3a adr
plan-5-v2-phase-tasks-and-brief	5 tasks
plan-6-v2-implement-phase	6 implement
plan-6-v2-implement-phase-companion	6 implement --companion
plan-6a-v2-update-progress	6a progress
plan-7-v2-code-review	7 review
plan-8-v2-merge	8c reconcile
入力 merge	8c reconcile
入力 6c または companion	6 implement --companion

対応するスラッグがない場合は、ステージのエイリアスだけを表示して確認します。推測してはなりません。（認識できない /plan-* コマンドの場合は、レジストリの ID／動詞を表示し、意図したステージを確認します。）

厳守すべき不変条件（すべてのステージ、両方のロードパス）

1. まず表示し、その後に実行を提案します。 § Command grammar（id と verb の両方を含み、数字だけにはしません）に従ってレンダリングした正確なコマンドを、コピー可能なブロックで表示します。これにより、読者は id を知らなくても何が実行されるかを確認できます。その後、実行を提案します。1 ターンにつき、承認されたステップは 1 つです（ガイドモード）。設計上の例外が 1 つあります。 ハーネスの ルーター呼び出し（/eng-harness-flow --hook … --json）は、各境界で自動実行されます。これは読み取り専用の助言的な呼び出しで、位置ベースのため、コンテキストが長くなったり圧縮されたりしても忘れられません。ルーティング先の アクション だけが、表示してから実行を提案する方式に従います（呼び出しのみの深さ — references/harness-seams.md § How the engine presents a seam）。
2. 明示的な確認なしに、取り消せない操作は行いません。 外部に影響するアクションには、それぞれ確認が必要です。ship verb の push と PR のオープンは別々に確認します（push への「はい」は、PR をオープンすることへの「はい」ではありません）。reconcile merge（8c）と即時 merge は、ユーザーが PROCEED と入力した後にのみ実行します。一般的な「はい」では実行しません。(意図的な例外が 1 つあります。ship は確認なしでテレメトリーをフラッシュします。harness telemetry sync により、refs/harness-telemetry/* へツリー外の件数のみの push を行います。作業は公開されず、ブランチや PR にも触れず、取り消し可能なため、外部に影響する操作の確認対象ではありません。)
3. /compact は実行しません — これはユーザーが入力する CLI 組み込みコマンドです。次のように案内します。「自分で /compact を入力してから、/the-flow を再実行してください」。
4. ゲート設定、スコア付け、ブロックは行いません。 これらが表面化させる アクション（ワークショップ、バックプレッシャー調査、圧縮、コンパニオン）は、すべてスキップ可能です。ベストエフォートであり、しきい値もコンプライアンスの最低基準もありません。スコープに関する注記：「スキップ可能」とは、シームがルーティングする アクション を指し、シームのルーター 呼び出し を指すものではありません。#1/#9 に従い、/eng-harness-flow --hook … --json の呼び出しは、すべてのシームで位置ベースに自動実行されます。ユーザーが拒否するのは アクション であり、呼び出し ではありません。
5. 洞察を捏造しません。 語る詳細はすべて実在するアーティファクトに基づかせます。読み取れない場合はその旨を伝え、ファイルの存在確認や git status に切り替えます。
6. フライトプランを手動編集せず、状態ファイルも手作業で作成しません。 the-flow.md は常に harness flow render によって the-flow.json から再生成します。the-flow.json 自体は harness flow の呼び出しを通じてのみ変更されます（plan 024 — CLI が生成元です）。.the-flow-state.json は存在しません。the-flow の状態（位置 + セッションの bag）はすべて the-flow.json に保存され、これを書き込めるのは CLI だけです。ガイドモードには、対応する CLI が必要です（§ Prerequisite）。
7. minih は実行しません。 implement verb のコンパニオンモード（--companion）がコンパニオンプロトコルを管理します。利用できる機能について説明します。エージェントの記録をフライトプランに書き込む機能は、v2 の harness flow agent verb が実装されるまで保留です。実装されるまでは agents[] は空のままにし、手動編集もしません（不変条件 #6 に従います）。
8. 時間の見積もりは一切示しません — Complexity Score（CS 1–5）のみ使用します（references/00-routing.md § Shared conventions）。
9. Harness は唯一の入口であり、各シームで自動実行されます。 Harness とのすべての接点で /eng-harness-flow --hook …（恒久的な --event エイリアス）を使用し、子スキルの名前を挙げたり呼び出したりしません。ルーターの 呼び出し は、各シームで永続的な nav.now の位置から機械的に自動実行されるため（長いコンテキストや圧縮後も機能します）、ルーティング先の アクション は引き続き、表示してから実行を提案します（呼び出しのみ）。Harness シームのオーケストレーションは flow が所有します（references/harness-seams.md）。サブスキルは harness を認識しません。
10. すべてのステージは深く考えるタスクです — そのステージに必要なだけ徹底的に推論します。
11. 一連の流れを完全な状態に保ち、ガイドモードのエントリーごとに照合します。 ガイドモードでのすべてのエントリー（再開 および 取り込み）において、エンジンは説明を始める前に spine-reconcile pass（references/00-routing.md § Reconcile the spine。sync verb として公開）を実行します。プランに記載された全フェーズ／ワークショップの一覧とハーネスのシームノードの集合を the-flow.json と比較し、現在の知識から存在が分かるのにフライトプランに欠けているものをすべて補います — 過去／現在／未来の全フェーズ、すべてのワークショップ、そして — D1 のもとでは無条件に — フェーズごとのハーネスシームノードです（プロビジョニングによって変わるのは、それらを実行するかどうかだけであり、ノードが存在するかどうかではありません）。これは冪等であり（一連の流れが完全な場合は何も書き込みません）、検出結果は助言的で、CLI のみで実行され（不変条件 #6）、ゲート設定も nav の進行もステージの実行もしません。機械的な強制手段は references/00-routing.md § CLI-driven cadence の Tier-1 run-now ステップ（step 3、render と同列）です — 文章上の記憶ではありません。「長いセッションや圧縮されたセッションでもスキップできない」という位置ベースの保証に沿って実行されるため、RUN は必須かつ機械的（render と同等）ですが、検出する内容は引き続き助言的であり、ゲート設定には使いません。ユーザーに「すべてのフェーズや作業が含まれているか確認して」と頼ませてはいけません。その漏れを防ぐために、この不変条件があります。Direct-jump は設計上 harness を使わないため、自動で照合しません。sync verb を使えば、必要に応じてこの処理を実行できます。
12. 各ターンの状況を把握し、nav を読み、orient を実行して、一連の流れを再確認します。 ガイドモードの各ターンで何らかの操作を行う前に、永続化された位置（harness flow nav show）を読み、harness flow orient を実行します。これにより、レールに加え、nav.now ノードの label／command／作成済みの instructions[] と、その場で対応が必要な作業が表示されます。これは位置ベースで機械的な処理であり、Tier-1 cadence のステップで、render および spine-reconcile（#11）と同列です。エントリーごとに無条件で実行し、提案するステップにはしません。シームの自動実行（#9）と同じく、「長いセッションや圧縮されたセッションでもスキップできない」という保証に沿って実行します。これは「性能の低いモデルがフローに従わない」という問題への対策です。「次に何をすればよいか」を推論ではなく読み取りにすることで、性能の低いモデルでも（あるいはコンテキストを新たに /compact した後でも）、ターンごとに一連の流れを再確認し、そこから逸脱しないようにします。ノードの instructions[] は毎ターン読み直し、記憶に頼りません。orient の読み取りは必須かつ機械的ですが、表示される内容（指示、対応が必要な作業）は引き続き助言的で、ゲート設定には使いません（作業がゲートになることはありません — #4）。(敵対的なほど性能の低いモデルに対する確実な強制には、最終的にハーネス側のターンごとのフックが必要です。スキルができるのは指示までです。このより大きな要望は記録されていますが、進行を妨げるものではありません。)

状態

永続状態はフライトプランそのものです。nav（位置情報＋自由形式のbag）と、docs/plans/<ord>-<slug>/the-flow.json内のノードステータスで構成され（the-flow.mdにレンダリングされます）。独立した状態ファイルはありません。状態を書き込むのはCLIだけです。コントラクト、書き込み権限、Graphについてはreferences/00-routing.mdを、ハーネスシームのオーケストレーション（検出、シームマップ、ノード出力、上流コントラクト）についてはreferences/harness-seams.mdを参照してください。サブスキルは自身のステージ成果物（仕様／計画／タスク／実行ログ／レビュー）を管理しますが、the-flowの状態は書き込まず、ハーネスに関する知識も持ちません。

前提条件 — 十分な機能を備えたharness flow CLI（機能＋最低バージョン）

ガイドモードでは、harness flow動詞ファミリー（plan 024）だけを使ってフライトプラン（the-flow.json → the-flow.md）を操作します。これは実行時の必須依存関係です。

• 機能の事前チェック — ガイドセッションごとに1回、最初にフライトプランを変更する前に実行します。 harness flow --help（バージョンの下限も確認する場合はharness --version）を実行して確認してください。harnessが見つからない場合、flow動詞ファミリーが存在しない場合（古いCLI）、またはそのインターフェースがcreate／insert-node／nav／rail／renderに対応できるほど新しくない場合は、次の率直な案内を表示してエラーで停止します。"the-flowには、十分な機能を備えたharness flow CLI（plan 024）が必要です。harness update（またはnpm i -g @ai-substrate/engineering-harness）を実行してから、/the-flowを再実行してください。" JSONを手作業で操作する代替手段は使わないでください。書き込みを行うのはCLIだけです。
• 採用設定は不要です。 これはengineering-harnessのループではありません。the-flowのフライトプランはdocs/plans/<ord>-<slug>/the-flow.jsonに保存され、.harness/のセットアップも、ガバナンス文書も、ハーネスの採用も必要ありません。必要なのは、グローバルCLIが$PATH上にあることだけです（harnessはgitのようにどこでも使えるツールです）。フライトプランのスキーマはこのスキルに含まれており（references/flight-plan.schema.json）、--schema経由で渡されます。利用側のリポジトリにバンドルされたり、インストールされたりするものはありません。
• 互換性のない旧形式は引き継ぎません（E308）。 plan 024以前の手動操作によるフロー（provenanceブロックがないthe-flow.json）は移行されません。CLIは読み取り時にE308（legacy-format）を返します。これは不具合ではなく、妥当な停止です。harness flow create flight-plan --schema <skill base>/references/flight-plan.schema.json --agent the-flowで作り直してください（<skill base>はこのスキルのベースディレクトリです。例：~/.claude/skills/the-flow。--agent the-flowにより、再構築されたレールのタイトルは[the-flow]になります。それ以前の.mdは静的な記録として残ります）。
• バージョンの不一致は実行時依存関係の不足であり、自動的な代替手段ではありません。
  • スキルのほうが新しい場合（スキルがインストール済みCLIより新しいCLIを必要とする場合）→ 上記の機能チェックで停止し、「harness updateを実行してください」と案内します。
  • CLIのほうが新しい場合（JSONを手動操作する旧版のthe-flowを新しいCLIで実行した場合）→ 旧版の手動操作で書き込まれたthe-flow.jsonを新しいCLIが読み取ると、provenanceがないためE308を返します。これは黙って状態が分岐するのではなく、明示的に停止します。解決方法はスキルの更新であり、個別の例外処理を追加することではありません。
• デプロイ順序 — CLIを先に、スキルを後に。 この移行済みスキルをデプロイする前に、必ず十分な機能を備えたharness flowを公開するか、harness updateで更新してください。これにより、スキルの公開直後から事前チェックが通るようになります。ロールバックは追加的で元に戻せます。スキルを元に戻し、harness update --pin <prev>を実行してください（CLIはグローバルなnpmパッケージです）。