construct

construct — ビルド可能なSRDに落とし込んだプロダクトアイデア

エンジンの根拠とカバレッジの制限については、engine-evidenceをお読みください。

constructは、要件と決定事項がモデルの記憶ではなく実際の調査に基づく 「ソフトウェア要件定義書スイート」を、プロダクトアイデアから作成します。 決定論的エンジン（scripts/construct.mjs、依存関係ゼロの Node）が、検索、資料集の作成、SRDの生成、検証をコードで行います。 あなたの役割は、インタビューを実施し、調査を進め、生成されたひな形を 正確で十分な根拠に基づくSRDへと仕上げることです。

基本ルール： 推測した要件より、根拠に基づく要件を優先します。 エンジンが取得した調査結果（競合製品、OSSの先行事例、技術文書、 StackOverflow）を活用して、スコープ、NFR、アーキテクチャ上の決定事項を正当化し、 [E#]で根拠を引用します。根拠の提示は、デフォルトでは参考情報です。 construct checkは引用のカバレッジを報告します。必要なカバレッジのしきい値を下回ると 失敗するようにするには、--min-grounding <0-100>を指定します。カバレッジは 参照の数を数えます。引用した根拠が主張を実際に裏付けているか確認するには、 reviewとcheck --semanticを使います。

1行で表す手順

[brainstorm] → interview → research → analyze → drill → render → enrich → red-team → check → present → [build]

construct status --out <run>は、現在あるものと正確な次のコマンドを表示します。 作業を再開するときや、次に何をすべきか分からなくなったときは、いつでも使ってください。

constructを実行しない方がよい場合

質問1に進む前に適合性を確認してください。適合しないと、手順全体が無駄になります。

• 既存のコードベースがある。 constructは、グリーンフィールドのプロダクト仕様を作成します。 既存のリポジトリを文書化したり発展させたりするには、代わりに reconstructを使ってください。
• 1つの依頼に複数のプロダクトが含まれる。 1回の実行で扱うプロダクトは1つです。 分割案を提示し、どれから仕様を作るべきか勧め、残りは保留します。
• 明確に説明できるアイデアがない。 initには一文での説明が必要です。 ユーザーが問題を一文で述べられない場合は、construct brainstormを実行し、 実際の形が見えてくるまでアイデアを広げます。「AIの何か」のような状態で 実行を開始しないでください。
• 図、名称、見積もりだけを求めている。 そのまま回答してください。SRD スイートは、依頼された成果物ではありません。

状況に応じた進め方

ユーザーの状況…	開始地点	読む資料
アイデアは大まかで、検討したい	ステップ0、brainstorm	references/brainstorm-playbook.md
アイデアが明確	ステップ1、インタビュー	references/interview-playbook.md
すでにbrief.jsonがある	ステップ2、research	references/research-playbook.md
SRDを生成済みで、内容をさらに充実させたい	ステップ4で加筆し、続いてステップ5	references/srd-authoring.md
SRDの検証が済み、アプリを作りたい	ステップ8、審判役としてverify	references/build-playbook.md
機能が6つを超える、またはモジュール式の構成を指定している	ステップ1＋モジュール分割	references/srd-authoring.md
根拠の提示を参考情報ではなく必須にしたい	check --min-grounding Nを実行し、続いてreview	references/grounding-coverage.md
ビルドではなく、使い捨ての仕様が欲しい	render --level light	references/srd-authoring.md

初回は、1 → 2 → 3 → 4 → 5 → 6 → 7の順に進めます。作業を再開するときは通常、 まずstatusを実行し、表示された手順に従って再開します。

8つのコマンドで進める基本の手順

node scripts/construct.mjs init     --idea "<one-liner>" --out ./my-idea   # then interview → brief.json
node scripts/construct.mjs research --out ./my-idea --angles market,oss,tech
node scripts/construct.mjs analyze  --out ./my-idea                        # what is thin + the drill for each gap
node scripts/construct.mjs research --out ./my-idea --angles market,oss,tech --url <proven,urls>
node scripts/construct.mjs render   --out ./my-idea --level complex
#   … enrich SRD.json, then:
node scripts/construct.mjs render   --out ./my-idea --from-srd
node scripts/construct.mjs check    --out ./my-idea
node scripts/construct.mjs review   --out ./my-idea                        # adjudicate → check --semantic

スクリプト

コミット済みの依存関係不要のバンドルが1つあります。node scripts/construct.mjs <command>で実行します。 npm installもAPIキーも不要です。利用できるすべてのコマンドについては--helpを参照してください。 ここでは概要を説明します。

コマンド	機能
init --idea "<s>" --out <run>	実行フォルダーと brief.json のひな形を作成します
brainstorm --out <run> [--merge]	任意で発散型ボードを作成します。--merge を指定すると、採用したアイデアを brief に、保留したアイデアを openQuestions（ゲートをブロックする 🧠）に反映します
research --out <run> [--angles …] [--url …] [--docs-url …]	<run>/evidence/ に根拠を収集します。何かに根拠を与える唯一のコマンドです。
analyze --out <run>	不十分な箇所、つまり UNGROUNDED として出力されるすべての主張と、それを解消するための調査を表示します。ゲートにはなりません。
web | oss | tech | so --out <run>	1 つの切り口を調査します。標準出力に表示するだけで、--url／--docs-url を含め、何も保存しません。
render --out <run> [--level light|complex]	SRD ツリーと SRD.json を生成します。--level の既定値は light です。ビルドの可能性が少しでもある場合は、complex を指定してください。
render --out <run> --from-srd	編集済みの SRD.json からツリーを再生成します。これにより、拡充内容を保存できます。
check --out <run>	厳格な構造ゲートと、参考情報としての根拠レポートを実行します
review --out <run> [--apply <f>]	主張↔根拠の作業リストを表示し、その後、check --semantic がゲート判定に使う判定台帳を表示します
verify --out <run> [--app <dir>] [--acceptance] [--run-tests] [--strict]	既定では静的な整合性を確認します。--acceptance --run-tests を指定すると、現在の基準にひも付いたコマンドを実行します（--app の既定値は conventions.appDir です）
status --out <run> [--json]	存在するものと、次に実行するコマンドを表示します。--json を指定するとビルドの進捗も含まれます
orchestrate --out <run> [--phase …] [--eco]	この実行のファンアウトを出力します（下記参照）
semantic up|down|status	任意のローカル Docker スタックを操作します
firecrawl up|down|status	任意のローカル Firecrawl スタックを操作します。キー不要でメインコンテンツを抽出します。稼働中は、組み込みの HTML ストリッパーの代わりにすべてのページを通してクリーニングします。停止中は何も変わりません。
cache status|clean [--all]	research の再実行にかかるコストをほぼゼロにするページキャッシュを操作します

知っておくと、予期せぬ挙動に驚かずに済むことが 3 つあります。

• --prd の指定は引き継がれます。 後続の render でこれを省略すると、requirements/prd/ を削除せずに実行を拒否します。もう一度 --prd を指定するか、意図的に削除する場合は --no-prd を指定してください。
• check --semantic はフェイルクローズです。 VERIFY.json が存在しない、読み取れない、または判定が完了していない場合は FAIL となります。別のレンダーを対象に判定されたファイルも同様です。--allow-unverified を指定すると警告に緩和されます。使用する際はその旨を明記してください。
• レンダラーのひな形では、check は complex でハードエラーになります。 このレベルはビルドの準備が整っていることを証明します。作成されていない受け入れ基準では何も証明できません。 （references/requirements-rubric.md。）

規約。 --out <run>（別名 --run）、--q <focus>（別名 --question）を指定します。--refresh はページキャッシュを無視して OSS リポジトリを再クローンします。--offline はキャッシュのみを使い、キャッシュにない場合はその旨を正直に報告します。 --web-engine auto|searxng|ddg|claude|firecrawl は検索エンジンを固定します（firecrawl は明示的に指定した場合のみ使用され、auto では検索されません）。--firecrawl <url|off> は抽出レイヤーの接続先を変更するか、組み込み抽出ツールを強制します。--concurrency <n>（既定値は 4）は、切り口ごとの同時取得数を制限します。--max-tech <n>（既定値は 3）は、tech が根拠を調査する候補技術の数を指定します。--per-source <n>（既定値は 6）は、各ソースで保持する根拠の数を指定します。--source <kind> は web --url のページを再分類します。ほとんどのコマンドは --json を受け付けます。結果に応じて処理を分岐する場合は、これを優先してください。

終了コード。 0 正常 · 1 ゲート失敗、使用方法のエラー、またはランタイムエラー · 2 オーケストレーションの前提条件エラー。作業リストがまだ存在しないフェーズも含みます（メッセージに、その作業リストを生成するコマンドが表示されます）。analyze はゲートになりません。 意味上の判定は、表示された抜粋の外にあるテキストも含め、クレーム全体と引用された証拠の内容に紐づきます。判定中は生成された VERIFY.todo.json を保持してください。最小限の判定行がそのフィンガープリントを継承するのは、エンジンが現在の SRD および証拠との一致を確認した後だけです。自己完結型の判定ではフィンガープリントを保持してください。レガシーまたは欠落した作業リストでは、以前の未紐づけの行を紐づけられません。check --semantic はそれらを拒否します。変更された内容については review を再実行し、判定をやり直してください。--allow-unverified は、紐づけの失敗を警告に明示的に格下げします。

ワークフロー

一度だけ呼び出され、根拠に基づく完全な SRD を返すことが期待されています。ループを最後まで進め、ユーザーに実際の判断を求める場合にのみ一時停止してください。

0. ブレインストーミング — 任意、発散的、インタビューの前に実施します。 ユーザーがまだ明確なアイデアを言語化できない場合や、まず選択肢を検討したい場合は、init の後に construct brainstorm --out <run> を実行し、6 つの観点に沿ってユーザーと一緒にアイデア候補を作成してから、採用するものを --merge で brief.json に統合します。ユーザーがすでに希望を把握している場合は省略してください。references/brainstorm-playbook.md に従ってください。

1. ユーザーへのインタビュー — 質問は一度に 1 つです。 調査の前に製品を明確にします。references/interview-playbook.md（および、記入済みのブリーフと、その最も難しい項目を導き出したやり取りについては references/brief-example.md）に従い、課題、対象ユーザー、中核となる価値、必須／推奨／任意の機能、制約（予算、スケジュール、チーム、コンプライアンス）、候補となる技術、競合または OSS の候補を確認します。質問ごとに回答案を提示し、質問をまとめて一度に投げかけないでください。回答は brief.json に記録します（construct init で開始してください）。 モジュール分割： 製品が自然にモジュール化される場合（機能がおよそ 6 個を超える場合、またはユーザーが src/modules/… のようなモジュール型アーキテクチャを指定する場合）は、モジュール分割案を提示して記録してください。brief.modules（id/name/description/dependsOn）に加え、すべての機能に module を設定します。レンダリング時にモジュールごとに 1 つの PRD が出力され、check によって分割が強制されます（全機能を割り当てる必要があります）。モジュール ID はフォルダー名になるため、スラッグ形式を保ち、機能タイトルはモジュール間で一意にしてください（BUILD-PLAN の進捗はタイトルをキーとして管理されます）。

2. 調査 — アイデアに根拠を与えます。 次を実行します。

   node scripts/construct.mjs research --out <run> --angles market,oss,tech
   

   これにより、ウェブ上の競合を見つけ、比較対象となる OSS プロジェクト（および現実の落とし穴を把握するための課題や PR）を調査し、候補技術のドキュメントと StackOverflow を取得します。<run>/evidence/EVIDENCE.md を読んでください。

3. さらに掘り下げます — analyze の結果がクリーンになるか、ユーザーが停止するまで続けます。 次を実行します。

   node scripts/construct.mjs analyze --out <run>
   

   不足している箇所 — 機能、競合他社、候補技術、照合可能な根拠のない OSS シード — を正確に示し、それぞれの不足を解消する調査コマンドを出力します。並行して進めます： 並列サブエージェントを起動できる場合は、不足箇所ごとに 1 つずつ割り当てます（エンジンが起動用のコマンドを出力します： node scripts/construct.mjs orchestrate --out <run> --phase research）。 各サブエージェントには、要件の一行要約、不足箇所、調査コマンド、専用の WebSearch を渡します。サブエージェントは、5 行以内の要約と、根拠として有用な URL を返します。サブエージェントは、実行フォルダーに書き込んではなりません。調査コマンドは標準出力に結果を出し、ドシエを書き込むのは construct research のみです。これを実行できるのはあなたのみです。調査結果を反映するには、実証済みの URL を固定して research を 1 回だけ再実行します。 construct research --out <run> --angles market,oss,tech --url <u,...> [--docs-url <d,...>] → analyze を再実行します。調査を実行すると、指定した角度と URL のみからドシエが再構築されます。以前の調査結果が失われないよう、必ずすべての角度を指定してください。固定した URL は予算によって除外されず、予算による削減があった場合はドシエの注記に記載されます。[E#] ID は再実行後も変わらないため、SRD に記載済みの引用は同じソースを参照し続けます。（サブエージェントを使えない場合は、不足箇所を 1 つずつ自分で調査します。）見つかった内容をユーザーに伝え、方向性はユーザーに委ねます。必須機能と重要な判断事項を優先し、ユーザーが十分だと言った時点で終了します。references/orchestration.md と references/research-playbook.md を参照してください。

4. SRD を生成します。 要件が固まり、ドシエが充実したら、次を実行します。

   node scripts/construct.mjs render --out <run> --level complex
   

   開発の可能性が少しでもある場合は、complex を選択します。後でレベルを切り替えると FR ID が振り直されます（references/srd-authoring.md を参照）。 これにより SRD ツリーが生成されます（以下を参照）。データモデルとインターフェースには、要件から推測した内容があらかじめ設定されています。そのまま信用せず、必ず確認してください。続いて、内容を充実させます。すべての 🧠 Decide: コールアウトを解決し、テンプレート化された受け入れ基準と NFR メトリクスを、検証可能で範囲が明確な記述に磨き上げます（references/acceptance-criteria.md に従ってください。complex では、レンダラーのテンプレート由来の基準が残っていると、警告ではなく致命的なエラーになります。このレベルはビルド準備完了を保証するためです）。データモデルとインターフェースを修正・拡張し、根拠となる要件や判断事項に、ドシエから [E#] の引用を追加します。内容の充実化を保存するには、SRD.json を編集して render --out <run> --from-srd を再実行してください。これにより、Markdown とゲート対象のマニフェストの整合性が保たれます。生成済みの .md だけを手作業で編集しても、次回のレンダリングで上書きされます。references/srd-authoring.md と references/citation-format.md を参照してください。 complex では、デザインシステム（design/）も充実させます。あらかじめ設定されたデザイントークンを製品の実際のブランド値に置き換え、コンポーネントと画面／フローの一覧を確認し、アクセシビリティ基準を目標規格に合わせて明確化します（要件から導出し、既定では WCAG 2.2 AA を使用します）。references/design-system-authoring.md を参照してください。

5. 敵対的レビュー — 新たな視点で徹底的に検証します。 実行フォルダーのパスと references/adversarial-review.md 以外のコンテキストを持たないレビュー担当の サブエージェントを1つ起動します（サブエージェントを使えない場合は、自分で チェックリストに厳密に従い、敵対的な読み手としてレビューします）。SRDの 弱点を探し、曖昧さ、テスト不能な基準、欠落している失敗時の経路、引用の 形骸化、矛盾などを洗い出し、タグ付きの指摘を返すようにします。 [blocker] はすべて修正し、[advisory] は判断に基づいて対応してから、 check を再実行します。問題がなくなるまで繰り返します — 新たな [blocker] が見つからない時点で終了します（問題のないラウンドが1回あれば 十分です。デフォルトで3回実施する必要はありません）。最後の備えとして、 3ラウンド後も [blocker] が見つかる場合は、残りの問題をユーザーに伝えて 終了します。3ラウンドで問題がなくならないSRDには、専門家の判断が必要な 構造的な問題があります。 complex レベルで、真に意見が分かれ、変更が難しいADRについては、 references/orchestration.md にある3名の審査員によるパネルも実施します （次のコマンドで出力します： orchestrate --out <run> --phase adr-judges --adr <id>）。

6. 検証します（3つのレイヤー）。

   • 構造（必須）: node scripts/construct.mjs check --out <run> を実行します。 未解決の 🧠、機能要件が一つもないこと、受け入れ基準のないFR、 存在しないエンティティ／インターフェース／NFRへの参照、必須のNFR カテゴリーの欠落、不正なADRがある場合は失敗します。合格するまで修正します。
   • 根拠との関連付け（参考）: 同じコマンドでカバレッジが出力されます。 要件や意思決定のうち、根拠を引用している割合を示します。重要な意思決定、 特に基盤となるものについては、必要に応じて割合を高めます。 references/grounding-coverage.md を参照してください。デフォルトでは ビルドは失敗しないため、適切に判断してください。ユーザーが根拠との関連付けを 必須にする ことを望む場合は、オプトインのゲートを追加します： check --out <run> --min-grounding 70。
   • 主張の裏付け（オプトインのゲート。その後はフェイルクローズ）: カバレッジは引用数を数えるだけで、引用が正しいかどうかは確認しません。 construct review --out <run> で主張と根拠の対応リストを作成し、 各組み合わせを判定します（references/orchestration.md のパターン4に従って 作業を分担します。次のコマンドで出力します： orchestrate --out <run> --phase claim-review）。verdicts.json を作成し、 review --apply verdicts.json を実行してから、 check --out <run> --semantic を実行します。 --semantic は必ず review --apply の後に実行してください。 このオプションは、裏付けのゲートが実際に有効になったことを検証します。 そのため、VERIFY.json がない、不完全である、または以前のレンダリングに 対して判定されている場合は、チェックが黙って合格するのではなく失敗します。 提示前に、基盤となるFR／ADRについて一度は確認しておく価値があります。 構造上 check に合格し、レビューで新たな [blocker] が見つからず、 根拠との関連付けが適切になるまで、手順3〜6を繰り返します。

7. 提示します。 成果物ではなく、意思決定から説明します。調査によって 何が変わったか、基盤となるADRとそのコスト、および対応する [E#]、 スコープの境界、まだわかっていないことを、曖昧にせず明示します。 ゲートの結果も正確に報告します。check が成功しても、それが意味するのは 構造上の完成であって、内容が優れていることではありません。また、カバレッジは 引用数を数えるだけで、引用が正しいかどうかは確認しません。そのうえで、 次に何をしたいかをユーザーに尋ねます。頼まれていないのに構築を始めないで ください。references/presenting.md に従います。

8. ビルド（ユーザーが SRD だけでなくアプリを求めている場合）。 レンダリングでは BUILD-PLAN.json も出力されます。これは機械可読なタスク DAG です（T-000 の骨組み + FR ごとに 1 つのタスク、must → should → could、エンティティを考慮した依存関係）。 acceptance エントリは SRD.json 内の該当箇所を指しています。アプリのコードはすべて あなたが書き、エンジンが審査します。 references/build-playbook.md に従ってください。

   • T-000（スキャフォールド、テストハーネス、CI）を実行し、 BUILD-PLAN.json の conventions.appDir と conventions.testCommand を設定します。
   • タスクごとに、トポロジカル順に、SRD.json から受け入れ基準を読み取ります。 TDD で進めてください。各テストには FR ID を記載します（例： describe("FR-001 …")。これを verify が grep します）。artifacts と tests を記録し、status: "done" に設定します。次のタスクに進む前に node scripts/construct.mjs verify --out <run> を実行し、エラーがあれば修正します。
   • 同じマイルストーンのタスク同士には依存関係がないため、準備完了のタスク群 （status --out <run> --json）は並行してビルドできます。タスクごとに独立した git worktree を 1 つ用意し、BUILD-PLAN.json への結果の取り込みはあなた自身が行います （references/orchestration.md のパターン 5。並列展開には orchestrate --out <run> --phase build を使用します）。
   • マイルストーンごとに verify --out <run> --run-tests --strict を実行し、 その後、マイルストーンの敵対的レビューを行います。新たな視点で、どのテストも 実際には検証していない受け入れ基準がないかを探してください（プレイブックを参照。 references/verify.md では、verify が証明できることとできないことを説明しています）。
   • ビルド中に FR が誤りだと判明した場合は、ブリーフを修正して再レンダリングします （進捗は機能タイトルを基準に統合されます）。変更された FR ID を付け直し、 check を再実行します。
   • アプリを実装済みと宣言する前に、references/verify.md の基準ひも付けプロトコルに従い、 verify --out <run> --strict --acceptance --run-tests --json を実行します。 現在のすべての基準が passed でなければなりません。failed または not-tested が ある場合は、実装済みと宣言できません。専用のアサーションを確認してください。 終了コード 0 が証明するのはコマンドが成功したことだけであり、スキップされたテスト、 空のテスト、または弱められたテストがビジネス要件を満たすことではありません。

問題が発生した場合

症状	対処方法
check が 🧠 のコールアウトで失敗する	判断を下してください。ADR、要件、またはスコープに反映し、brief.openQuestions から削除して再レンダリングします。決定を先送りにすることは仕様のバグであるため、これはゲートになっています。
check が レンダラーのスキャフォールド を名指しして失敗する	その基準や契約は作成されていません。書き直すか（references/requirements-rubric.md）、使い捨ての仕様であれば --level light に切り替えてください。
render が「requirements/prd exists」と拒否する	前回のレンダリングで --prd が使われています。再生成するには --prd を再指定するか、意図的に削除するには --no-prd を指定します。
check --semantic が明らかな原因なしに 1 で終了する	失敗時に閉じる動作です。review を実行し、各ペアを裁定してから review --apply を実行し、その後に --semantic を指定します。レビュー後に再レンダリングした場合も、レビューは無効になります。
orchestrate --phase <p> が 2 で終了する	そのフェーズの作業リストはまだありません。メッセージに、その作業リストを作成するコマンドが表示されます。
リサーチで何も見つからない	曖昧な candidateTech／competitors を具体化して再実行します。その後、自分で WebSearch を使ってページを指定します：research --url <u,...>。何も得られない試行が 2 回続いたら終了してください。前提条件または openQuestion を記録して先に進みます。根拠を捏造するより、情報が少なくても誠実な SRD のほうが優れています。
テストが、SRD にもう存在しない FR ID を参照している	再レンダリングで番号が振り直されています。テストの ID を付け直してください。verify に古い ID が表示されます。
実行に予想以上に時間がかかる	construct cache status を実行します。キャッシュが空の場合はページごとに全データを取得するため、時間がかかります。--offline を使うとキャッシュだけで動作します。角度ごとのコストは evidence/meta.json と EVIDENCE.md の末尾に記載されています。

よくある間違い

• ドリルを根拠と混同すること。 web／oss／tech／so は出力するだけです。引用できる証拠として永続化されるのは、research --url／research --docs-url のみです。
• 角度を減らして research を再実行すること。 入力した内容だけを使ってドシエを作り直します。必ずすべての角度を渡してください。そうしないと、以前の証拠が失われます。
• ビルドが可能なのに、デフォルトの light でレンダリングすること。 後から切り替えると FR ID が振り直され、テストタグが無効になります。
• レンダリング済みの .md を編集して終わりにすること。 次回のレンダリングで上書きされます。SRD.json を編集してから、render --from-srd を実行してください。
• サブエージェントに実行フォルダーへの書き込みを許すこと。 書き込むのはあなた一人です。サブエージェントはテキストを返します。
• check を通過する前に提示すること。 カバレッジ率は合格基準ではありません。未解決の 🧠 があれば未完了です。

完了の判断基準

以下の条件をすべて満たせば SRD は完成です。推測せず、必ず明示的に確認してください。

1. construct check が 0 で終了する。
2. すべての must 要件に、「エラーが表示される」ではなく、具体的な動作を示す失敗時の基準がある。
3. 重要な判断（スタック、データストア、ビルドか購入か、差別化要因）のすべてに、主張の内容を実際に裏付ける証拠が引用されている。少なくとも 3 つは抜き打ちで確認済みである。
4. データモデルとインターフェースは、レンダラーの推定に任せたままにせず、検証済みである。
5. レッドチームのレビューで、新たなブロッカーが見つからなかった。
6. 未解決の事項は、暗黙に推測せず、前提または openQuestion として記録されている。

セルフテスト： あなたと一度も話したことのない開発者が、この SRD だけをもとに、概要ではなく契約を正しく理解して、必須要件を実装できるでしょうか？どの回答にも会話が必要なら、SRD は未完成です。

オーケストレーション — ハーネスに応じた振り分け

4 つのフェーズで、単位ごとにファイルベースの状態を並行処理します。research（analyze の各ギャップに 1 人のリサーチャー）、claim-review（VERIFY.todo.json の各ペアに 1 人の懐疑的レビュー担当者）、adr-judges（異論のある ADR 1 件を対象とする、固定の 3 観点パネル）、build（準備完了タスクごとに 1 人の worktree 分離ビルダー）です。orchestrate は、実行時点の最新状態に基づき、絶対パスと実際の作業単位を組み込んで生成します。

node scripts/construct.mjs orchestrate --out <run> [--phase research|claim-review|adr-judges|build] [--adr <id>] [--eco] [--list]

使用するハーネス	各フェーズの実行方法
Workflow ツールがある	orchestrate --phase <p> を実行し、次に Workflow({ scriptPath: "<run>/orchestration/<p>.workflow.mjs" }) を実行
サブエージェントはあるが、Workflow ツールはない	同じ orchestrate を実行し、<run>/orchestration/agents/<role>.md ごとに、バッチあたり 1 人のサブエージェントを割り当てる
エコモード、またはサブエージェントがない	orchestrate --eco を実行し、<run>/orchestration/RUNBOOK.md に従って順番に進める

どの段階でも変わらない 2 つのルール。 サブエージェントは実行フォルダーに書き込みません。断片を返し、あなたが取り込んでください（ビルダーは自身の Git worktree 内でのみコードを書きます）。また、並行処理は最適化であり、必須ではありません。すべてのフェーズには、同一の成果物を生成する逐次実行の代替手段があるため、ゲートはハーネスに依存しません。パターン、出力契約、予算に関するガイダンスについては、references/orchestration.md を参照してください。

生成される内容（--out の下に作成される SRD ツリー）

00-overview/   VISION.md · SCOPE.md (+ 🧠 open decisions)
requirements/  FUNCTIONAL.md (FR-NNN · priority · Given/When/Then · [E#];
               an index linking each FR to its module PRD in modules mode)
               NON-FUNCTIONAL.md (NFR-NNN by category · metric · [E#])
               prd/PRD-FR-NNN-*.md (+ README index — only with --prd)
prd/           README.md · <module>/PRD.md   (modules mode only: one PRD per
               module — full FR blocks, NFR refs, data/interface slices, deps)
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADRs)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (complex only; --no-design to skip)
competitive/   LANDSCAPE.md (competitors + OSS prior art)
BUILD-PLAN.md · BUILD-PLAN.json (task DAG for the build phase; tasks carry their
               module in modules mode)
TRACEABILITY.md (FR ↔ module ↔ NFR ↔ ADR ↔ entity ↔ interface ↔ component ↔ screen)
evidence/      EVIDENCE.md · evidence.json · meta.json · ids.json (the [E#]
               ledger — do not hand-edit; it is what keeps citations stable)
VERIFY.md · VERIFY.todo.json · VERIFY.json   (the claim-support worklist and its
               adjudicated ledger — written by `review` / `review --apply`)
orchestration/ <phase>.workflow.mjs · agents/<role>.md · RUNBOOK.md
               (written by `orchestrate`; `out/` is where subagents may return)
brief.json · SRD.json

evidence/、VERIFY.md、orchestration/ は取得または生成されたテキストです。check は意図的にこれらを 🧠／TODO の対象としてスキャンしないため、証拠の抜粋に何を引用してもゲートに引っかかりません。

light は簡潔な構成を維持します。complex では、NFR 一式、2 つ目の ADR、失敗時の受け入れ基準、完全なトレーサビリティマトリックス、さらに デザインシステムのサブツリー（design/：原則、トークン、コンポーネント、画面／フロー、アクセシビリティ契約。--no-design で除外可能）が追加されます。単一ファイルの SRD.md を作成する場合は、--merge を追加してください（modules モードでも FR ブロックは常にすべて含まれます）。

オプションのローカルスタック（完全ローカル、API キー不要）

construct semantic up を実行すると、ローカルの Docker スタック（Qdrant、Ollama、SearXNG）が起動します。その後、 research --angles market,oss,tech,semantic --semantic を実行すると、収集したエビデンスが 埋め込みの関連性に基づいて再ランキングされます。データがマシンの外に出ることはありません。スタックが停止している場合、--semantic は通知を記録し、 従来のキーワードベースのランキングを維持します。

construct firecrawl up を実行すると、2 つ目の、より大きなスタック（約 3 GB、独自の extract プロファイル）が起動します。このスタックは semantic up では起動されません。稼働中は、リサーチパイプラインが取得するすべてのページが、組み込みの HTML 抽出処理ではなく、 Firecrawl のメインコンテンツの Markdown を通して整形されます。これにより、JavaScript でレンダリングされたページからもエビデンスを取得できるようになります。こちらも API キーは不要です。失敗した場合はすべて、組み込みの抽出処理にフォールバックし、その旨がドシエの注記に記録されます。そのため、スタックが停止していても、最悪の場合の動作はこれまでと同じです。 references/semantic-setup.md を参照してください。

参考資料

• references/brainstorm-playbook.md — オプションの発散ステップについて説明します。6 つの視点から候補アイデアを生成し、採用したアイデアをブリーフにまとめます。
• references/interview-playbook.md — 一度に 1 つずつ質問しながらブリーフを引き出す方法です。
• references/brief-example.md — 記入済みの brief.json、最も難しい項目を作成したやり取り、およびうまく機能する理由です。
• references/research-playbook.md — 視点を選び、「十分な水準」に達するまで掘り下げる方法です。
• references/orchestration.md — 3 層の動的ワークフローモデルと、サブエージェントのパターンについて説明します。リサーチの並列展開、レッドチーム、審査パネル、主張と裏付けのレビューの並列展開、ビルドの並列展開（および単一執筆者のルール）を含みます。並列展開パターンは、construct orchestrate によってすぐに起動できる形で出力されます。
• references/adversarial-review.md — レッドチームのチェックリストと、検出事項の取り決めです。
• references/srd-authoring.md — 🧠 の注記の解決、テスト可能な要件と ADR の作成方法です。
• references/design-system-authoring.md — complex デザインシステムを、トークン、コンポーネント、画面／フロー、アクセシビリティに関する取り決めで充実させる方法です。
• references/requirements-rubric.md — check が要件に求める ISO/IEC/IEEE 29148:2018 の特性、2 つの重大度、およびゲートが成功した場合に意味することと、意味しないことです。
• references/acceptance-criteria.md — 不適切な Given／When／Then の書き換え例と、測定可能な非機能要件の指標パターンです。
• references/forbidden-patterns.md — レビューで決して通らない表現と、それぞれに置き換える表現の形式です。
• references/citation-format.md — [E#] による根拠付けの規約です。
• references/grounding-coverage.md — 参考情報としてのカバレッジレポートの意味と、カバレッジを高める方法です。
• references/build-playbook.md — ビルドループについて説明します。タスク単位の TDD、FR タグの規約、マイルストーンのゲート、マイルストーンレビューを含みます。
• references/verify.md — 各 verify チェックで確認できることと、人による確認が必要な点です。
• references/presenting.md — ステップ 7：SRD を引き渡す際に伝えることと、ゲートの結果を正確に報告する方法です。
• references/provider-apis.md — OSS のイシュー／PR をホストごとに API キーなしで取得する方法です。
• references/web-discovery.md — 多層構成の、API キー不要な Web 検索です。
• references/semantic-setup.md — オプションのローカル Docker スタックです。