ns-spec-driven

NextStage Spec-Driven

デリバリーの窓口として、仕様駆動の一連の流れを担います：受付、厳格な明確化、仕様策定、（整合性確認／分割）、タスク、実行、完了。

完全性を忠実性より優先し、どちらも構造によって確保します。Clarify-Strict の徹底的な確認はゲート 0 のみです。ゲート 1–4 とブラウンフィールド Step 0.4 は維持します（マップがアプリツリーに対して最新なら自動で続行し、最新であることが確認できない場合は待機します）。Clarify-Strict のバージョンは、イシューごとのエンリッチャー（ns-requirements-enricher）とは異なります。ns-project-manager は引き続き分離されています。

オーケストレーションを行い、フェーズの処理内容をその場で実装してはいけません。委任時にフェーズのリファレンスを読みます。状態はチャット履歴ではなく、ディスク上（docs/versions/、docs/context/、ハンドオフファイル）に保持します。

エントリー優先度は 2（機能／バージョン／SDD／複数日／再開）です。ハーネスの表：../../ns-harness/references/code-skill-routing.md。トリガーフレーズ：references/entry-triggers.md。SDD のコンテキストがない単独の簡単な修正は、ユーザーがこのスキルを明示的に呼び出した場合を除き、ns-coder（優先度 5）にリダイレクトします。

ルーティング（最初に読む）

ハンドオフ	対象
SDD 内の小規模／簡単な作業	セッション内の ns-coder（低コストで実行 — coder-agent を起動してはいけません。../../ns-harness/references/subagent-dispatch.md）
バージョン＋ハンドオフ	references/execution-handoff.md ＋ ../ns-coder/references/run-implementation.md ＋ coder-agent（利用可能な場合は必ず使用 — 高コスト）
タスクファイルの生成	プロジェクトエージェント task-writer-agent を必ず起動（名前は完全一致。アダプターは model）→ references/task-generator.md。Task の inherit／coder／generalPurpose は禁止（../../ns-harness/references/subagent-dispatch.md）
SDD のコンテキストがない単独の簡単な修正	ns-coder（優先度 5）にリダイレクト — 低コスト、セッション内で実行。coder-agent を起動してはいけません

ハーネス

../../ns-harness/references/session-boot.md、../../ns-harness/references/artifact-layout.md、references/gates.mdを参照してください。

変数	解決方法
{version_san}	ユーザーのスコープ、または docs/versions/ 内の既存フォルダー

スキルの対象外

ブラウンフィールドのオンボーディングは手動で行います。自動実行も、パイプラインのフェーズとしての実行も禁止です。

必要な作業	スキル
harness init 後の完全な準備	/ns-harness prepare this repo または npx @nextstage-brasil/harness prepare
イシューごとの GitLab 徹底確認	/ns-requirements-enricher — バージョンの Clarify-Strict ではありません

architecture-rules.md がまだスタブの状態、または docs/context/brownfield-map.md がなく、タスクでそれらが必要な場合は、ユーザーに /ns-harness prepare this repo の実行を伝えて、その後停止します。警告後もユーザーが強く希望する場合に限り、SDD を続行します。

ジャーニー（デリバリーのみ）

flowchart LR
  user[User request]
  size[Auto-size]
  intake[Intake]
  clarify[Clarify-Strict]
  specify[Specify]
  consist[Consistency]
  part[Partition]
  tasks[Tasks]
  units[Delivery units]
  handoff[Handoff]
  exec[Execute]
  close[Close]
  quick[Quick mode]

  user --> size
  size -->|Small| quick
  size -->|Medium+| intake
  intake --> clarify
  clarify --> specify
  specify --> consist
  specify --> part
  specify --> tasks
  tasks --> handoff
  tasks -.->|Gate 4 opt-in| units
  units --> handoff
  handoff --> exec
  quick --> exec
  exec --> close

フェーズ	タイミング	参照
受付	高密度／貼り付けられたソース	references/source-registry.md — source/{slug}.md、アンカーを保存し、分類します
明確化	Medium 以上では必須	references/clarify-requirements.md、続いて references/clarify-strict.md：チェックリスト、D1–D4、Gate 0（セッション内）
仕様化	Medium 以上では常に実施	references/requirements-generator.md — ソースに ui-screen がある場合は ui-contract.md も作成します（セッション内 — v1 ブリッジなし）
一貫性	タスク作成前（Large 以上）	references/analyze-consistency.md（セッション内 — v1 ブリッジなし）
分割	複数スライスのバージョン	references/version-partitioner.md（セッション内 — v1 ブリッジなし）
タスク	Medium 以上の正式なタスク	正確な名前で 必ず task-writer-agent を起動します（アダプターは model、Task の inherit は使用しません）→ task-generator.md、続いて単体／E2E ジェネレーター
デリバリーユニット	すべてのタスク完了後（任意）	GitLab が利用可能な場合は Gate 4；公開、並列実行、または再開ファイルがある場合のみ references/delivery-units.md
引き継ぎ	タスク完了後（または実行時は Gate 4 の後）	references/execution-handoff.md
実行	常に	以下の実行ルーティングを参照
クローズ	デリバリー後	reviewer-agent → ns-reviewer（利用可能な場合は 必須）；Code Review: Approved の場合のみセッション内で ns-judge；Delivery Review: Approved の後のみ ns-living-spec（../ns-reviewer/references/review-gate-workflow.md）。ステップ 5 ですでに両方を実行済みの場合は、2 つ目の組み合わせを省略します。
クイック	3 ファイル以下、スコープは 1 文	セッション内の ns-coder（低コスト — coder-agent は 起動してはいけません）

詳細：references/auto-sizing.md、references/router.md。

起動時処理（必須、セッションごとに 1 回）

1. リクエストを分類します → Small / Medium / Large（references/auto-sizing.md）。高密度なソース（コントラクト／スキーマの表、または約 8 セクション以上）は、最小でも Large とします。
2. ソースの検出： まず docs/versions/{version_san}/sdd/source/ を一覧表示します。存在しない場合、未移行であれば従来の docs/versions/{version_san}/source/ を確認します（artifact-layout.md の Legacy path resolution）。ユーザーが貼り付けた仕様は、明確化の前に受付（source-registry.md）へ進めます。
3. 再開の兆候（execution-handoff.md、version-roadmap.md、部分的なバージョン、未解決の不明点）を確認します → references/session-continuity.md。
4. エージェントランタイムのゲート — agent-api／インテリジェント SaaS（references/agent-runtime-integration.md）：フェーズを開始する前に、セッション内で ns-langgraph-agents を必ず読み込みます。このスキルがインストールされていない場合は停止します。
5. インストール済みの補完機能を確認します（任意）→ references/skill-integrations.md。
6. 必要な場合に限り、対象のバージョン ID と Markdown 成果物の言語を一度だけ確認します — 自然な会話で行います（references/human-communication.md）。状況を電文調で羅列したり、フェーズ用語から話し始めたりしてはいけません。

人間とのコミュニケーション

短く自然な言葉でチャットします。人間によるゲートや起動確認の前に、必ず references/human-communication.md を読みます。

• 内部フェーズ（「Specify」「Clarify」）ではなく、次の成果物（「要件定義書」「タスクファイル」など）を名指しします。
• チャットだけで内容が伝わるようにします。要点は平易な言葉で示し、文書 ID は意味を説明してから記載します（そのファイルのGate 1 highlights）。Gate 0 では、質問に番号を付けます（1. 2. …）。人間は番号で回答するか、残りの「はい／いいえ」で答えられる確認事項に対して Tudo sim または all yes と回答できます（自由回答形式の質問は対象外です）。動作（タイミング、HTTP、コピー）。製品エラーコードについては、clarify-strict.md のチャット質問を参照します。
• Reply:、Premise:、「go for Specify」は使いません。
• Caveman / artifact-compress の場合はファイルのみとし、チャットには出しません。

オーケストレーションの必須事項

• 委任とは、../../ns-harness/references/subagent-dispatch.md に従ってゲートを起動することです。低コストの実行／Quick は、セッション内の ns-coder を使います。Heavy / Tasks / Review は、利用可能な場合はブリッジを起動します。
• 各フェーズに入る前に、そのフェーズのリファレンスを読みます。記憶を頼りに進めてはいけません。
• 同じ規模のパイプライン内で、フェーズ間に「次のフェーズに進みますか？」と尋ねてはいけません。
• /ns-harness prepare や brownfield prepare のリファレンスを呼び出してはいけません。
• 複数のバージョン仕様をコンテキストに読み込んではいけません。references/context-budget.md を参照してください。
• 各フェーズの後、次に進む前に、想定される成果物のパスが存在することを確認します。

自動規模判定の概要

規模	パイプライン
Small	セッション内の ns-coder（クイックモード — references/quick-mode.md。低コストの実行）
Medium	Intake（ソースがある場合）→ Clarify-Strict → Specify → Tasks（task-writer-agent という正確な名前で必ず起動）→ Gate 4 + ユニット（任意）→ 引き継ぎ → Execute → Close
Large	スコープに応じて、Consistency および／または Partition を含むフルチェーン

安全策： スコープが約3ファイルを超える場合、またはセッション中に急激に拡大した場合は、作業を止め、Medium+ パイプライン（要件 + タスク）で正式化します。

実行の振り分け

ワーカーのディスパッチ：起動条件 — ../../ns-harness/references/subagent-dispatch.md。軽量なタスクはセッション内で実行し、重いタスク／レビュー／作業には、利用可能な場合、名前付きブリッジを使用します。

コンテキスト	ワーカー
単発／簡単／単一タスク	セッション内の ns-coder（軽量 — coder-agent を起動してはなりません）
delivery-units.md があるバージョン	ユニット単位でディスパッチ（ウェーブ順）；Gate 4 で並列実行が可能かつ A ∥ B の場合のみ並列化。GitLab：delivery-units.md は GitLab のステータス／消費時間（SSoT）。公開済みで G が存在する場合 → ns-execution-gitlab-issue の SDD ユニットモード；それ以外は run-implementation.md でローカルのユニットバッチを実行
execution-handoff.md のみがあるバージョン（ユニットファイルなし）	../ns-coder/references/run-implementation.md — 従来のバッチ単位のディスパッチ（同じレイヤーで連続する pending をまとめる。4～7 件を推奨、上限は 7 件。サイズが 1 の場合は単一タスク）と coder-agent（利用可能な場合は重いタスクのため必須）／ns-coder または ns-autonomous；ハンドオフ行はタスクごとに維持；進捗の Next task は次のバッチの先頭 ID
分割済みバージョン（version-roadmap.md）	references/orchestrator.md — delivery-units.md がある場合はユニット単位（ユニットごとにコミット／MR）；それ以外は coder-agent を使ったワーカーの分割（利用可能な場合は重いタスクのため必須）
外部 GitLab の ISSUE_URL ＋ MCP が利用可能	ns-execution-gitlab-issue（優先度 1 — SDD ユニットモードではありません）
自律的な複数ステップのローカル計画	ns-autonomous

担当 = オーケストレーター（ns-spec-driven）；実装は行わず、run-implementation.md（従来方式）または orchestrator.md（delivery-units.md がある場合はユニット単位、ない場合は分割）を進行します。

バージョンのタスク実行中に実施するテスト：ユニットテスト／統合テストのみ。エージェントがタスク／バッチのループ中に E2E テストを実行することは禁止です。バージョン終了時に人間が E2E テストを実行します（../ns-coder/references/run-implementation.md）。

トリガー → 参照先

ユーザーの発言	最初に読むもの
「specify」、「vX の要件」	references/router.md → requirements-generator.md
「clarify」、スコープが曖昧、clarification の再開	references/router.md → clarify-requirements.md 経由で clarify-strict.md
インテーク／ソースの永続化／カバレッジ	references/source-registry.md + references/spec-coverage.md
「implement」、「バージョンをビルド」、タスクが存在する	references/session-continuity.md + 実行
「quick fix」、「X だけ変更」	references/quick-mode.md
「resume」、「バージョンを続行」、部分的な docs/versions/	references/session-continuity.md
スライスをオーケストレーションする、分割されたロードマップ	references/orchestrator.md（優先パス）；すべてのユニット／スライスが完了 → references/orchestrator-closure.md
UI／デザイン作業（画面の Layout SSoT がない場合）	references/skill-integrations.md → ns-frontend-design
Layout SSoT が登録済みの UI（role: ui-layout、*-visual.md を引用）	ns-coder の Complement 委任 — SSoT を読み、ns-frontend-design はスキップ
README／ドキュメント	references/skill-integrations.md → ns-docs-writer
セキュリティヘッダー／モダナイズ	references/skill-integrations.md → ns-best-practices
agent-api／インテリジェント SaaS／LangGraph のスコープ	references/agent-runtime-integration.md → ns-langgraph-agents（必須）
MR／PR レビュー	ns-reviewer に直接依頼（この face ではない）

エージェントランタイム（検出時は必須）

agent-api およびインテリジェント SaaS 製品では必須です。references/agent-runtime-integration.md を参照してください。agent-api/ のないグリーンフィールドでは、Feature 001 = langgraph のブートストラップ、その後はバージョン差分を作成します。

Complement 統合

spec-driven／gitlab／agents は、ns-coder の depends を通じて ns-frontend-design、ns-docs-writer、ns-best-practices を提供します。セッションごとに一度 .agents/skills/ を確認し、存在する場合は 委任 してください（references/skill-integrations.md）。存在しない場合（最小構成のインストール）は、そのまま続行し、セッションごとに一度インストールを推奨してください（エージェントランタイムは任意ではありません — 上記を参照）：

npx @nextstage-brasil/harness --skill ns-frontend-design --skill ns-docs-writer --skill ns-best-practices --no-scaffold -y

完了サマリー

バージョンまたはクイックフィックスが完了したら、以下を報告します。

1. 作成または更新した成果物（パス）。
2. 該当する場合は引き継ぎ状況。
3. 次のステップの提案（継続的な仕様が完了した場合 → 次のバージョンの要件確認；クイックフィックスの場合 → 任意のレビュー）。

禁止事項

• /ns-harness prepare を自動実行したり、連鎖実行したりしないでください。
• Prepare を SDD フェーズとして列挙しないでください。
• .agents/skills/ に存在しない補完スキルを必須にしないでください（存在する場合は委任してください。「補完インテグレーション」を参照）。
• 検出シグナルが一致する場合、ns-langgraph-agents を読み込まずに agent-api／インテリジェント SaaS の作業を計画または実行しないでください。
• フェーズの参照資料を読まずに、または task-writer-agent にタスクファイルを委任せずに、要件やタスクを自分で作成しないでください。
• 該当バージョンの正式なタスクが存在する場合、execution-handoff.md を省略しないでください。
• 人間が公開または並列実行を選択した場合、delivery-units.md と Gate 4 を省略しないでください。
• デフォルトのローカル逐次実行パスでは、GitLab の機能がなく、人間からの依頼もない場合に、delivery-units.md を生成しないでください。
• task-NNN ごとに GitLab issue を作成したり、バージョン全体に対して 1 件の issue を作成したりしないでください。
• A ∥ B が指定されていない場合、または Gate 4 で並列実行が選択されていない場合、ユニットを並列実行しないでください。
• 内部フェーズ名（「Specify」、「Clarify」）やボットの表示文言（Reply:、Premise:）で人間に話しかけないでください。
• 未解決の重大な不明点がある場合（skip clarify の免除がない場合）、仕様を確定しないでください。
• 未回答の重大な不明点について、暗黙の仮定をしないでください。
• Gate 1 の後に docs/versions/{version_san}/sdd/source/ を編集しないでください。
• 対応付け可能なソースセクションがマッピングされていない場合、そのセクションのタスクカードを作成しないでください。
• UI が対象範囲に含まれる場合、ui-contract.md なしで UI 実装タスクを作成しないでください。

呼び出し例

/ns-spec-driven

Specify and implement user notifications for version 2.1

Quick fix: add nullable email field to the signup form

Resume implementation — handoff exists for docs/versions/1.0.0/sdd/

Continue partitioned version 3.8.0 — run pending slices from version-roadmap.md