Merge branch 'next' into feat/1820-specless-predicate-rail

2026-07-07 07:49:07 -04:00
parent 91998dcbca d2ae7fe391
commit ea4378063f
171 changed files with 5853 additions and 498 deletions
--- a/.changeset/1143-claude-orchestration-capability.md
+++ b/.changeset/1143-claude-orchestration-capability.md
@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2044
+---
+**A default-off, BETA, claude-only "Claude orchestration" capability** — adopts Claude Code's Workflow tool (`/effort ultracode`, Agent SDK ≥ v0.3.149) as an optional parallel-execution backend for the GSD loop, restoring the wave parallelism + plan-checker + verifier that the #853 backgrounded-agent nesting limitation forces inline on Claude Code, and folding the existing `gsd-ultraplan-phase` plan-offload under the same runtime gate. When `claude_orchestration.enabled` is on AND the runtime is Claude AND the Workflow tool is detected AND the Agent SDK meets the floor (`claude_orchestration.min_agent_sdk_version`, default `0.3.149`), `execute-phase` emits a generated Workflow script (`waves → parallel() barriers`, `plans → agent({ agentType: 'gsd-executor', isolation: 'worktree' })`, `files_modified overlap → separate sequential stages`, `resumeFromRunId` wired to the phase run id, shared `budget` pool) that composes the SAME executor agent + worktree isolation the inline path uses, so artifacts/commits are produced identically. Detection is pure and fail-closed (any miss → inline), so on any runtime lacking the Workflow tool behaviour is byte-identical to today. Adds a pure module `gsd-core/bin/lib/claude-orchestration.cjs` (`detectWorkflowBackend`, `emitWorkflowScript`), the `capabilities/claude-orchestration/` declaration with two gated loop contributions (`execute:wave:post`, `plan:post`) and a `claude-orchestration` command family (`gsd-tools claude-orchestration detect-backend|emit-workflow`), federated config keys, and an ADR-1143 implementation amendment. (#1143)
--- a/.changeset/eager-tunas-swim.md
+++ b/.changeset/eager-tunas-swim.md
@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 1991
+---
+**`/gsd-quick` no longer halts with a stale-base worktree mismatch** — the worktree executor now degrades to sequential execution when its fork base has diverged from origin/HEAD, instead of spawning a worktree guaranteed to fail the base-mismatch guard.
--- a/.changeset/gentle-badgers-roar.md
+++ b/.changeset/gentle-badgers-roar.md
@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2048
+---
+**`model_overrides` Claude model IDs now resolve to Agent-tool aliases on the claude runtime** — a full Claude model ID (e.g. `claude-sonnet-5`) in `model_overrides` was returned verbatim and silently dropped by the Claude Agent tool (whose `model` parameter documents only tier aliases), causing the spawned subagent to inherit the parent session model instead of the configured one. It now maps to the tier alias (`sonnet`/`opus`/`haiku`/`fable`), consistent with the `model_policy` path (#1144). Bare aliases, non-Claude values, and non-Claude runtimes are unchanged; a Claude ID with no alias warns once and falls through to tier resolution. (#2041)
--- a/.changeset/noble-foxes-purr.md
+++ b/.changeset/noble-foxes-purr.md
@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2051
+---
+**`capability state` and `loop render-hooks` now accept `--runtime` to override the auto-detected runtime** — previously both commands parsed only `--config-dir`, so the runtime config dir was derived from the persisted `.planning/config.json` runtime (precedence `GSD_RUNTIME` → `config.runtime` → `claude`). A repo that persisted `runtime:"codex"` resolved the config dir to `~/.codex`, where the Claude skill isn't installed, so every skill-bearing capability reported `surfaced:false` and `execute:post`/`verify:post` hooks silently no-op'd when the operator drove GSD from Claude Code. `--runtime <r>` (canonicalized, so aliases like `codex-app` work) now bypasses that fallback so the config dir resolves to the explicitly-named runtime's home. Behavior without the flag is unchanged. (#2003)
--- a/.changeset/steady-ibex-run.md
+++ b/.changeset/steady-ibex-run.md
@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2049
+---
+**Skill-bearing capabilities now surface correctly on flat command-layout installs** — on an install using the flat `commands/gsd-<stem>.md` source layout (e.g. a Claude Code local project install with no `commands/gsd/` subdir), every skill-bearing capability (`nyquist`, `code-review`, `security`, `ui`, `mempalace`, `ai-integration`, `profile-pipeline`) was silently reported `surfaced:false`/`enabled:false`/`active:false`, so their loop hooks (`verify:post`, `execute:post`, etc.) never fired even with the corresponding `workflow.*` toggle on. The skill-manifest resolver now detects the flat layout and produces the same stems the nested `commands/gsd/*.md` loader does. (#1858)
--- a/.changeset/steady-mice-frolic.md
+++ b/.changeset/steady-mice-frolic.md
@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 1994
+---
+**`/gsd:onboard` guides brownfield setup** — existing repos now have a top-level onboarding command that routes through codebase mapping, docs ingest, project initialization, and an onboarding summary without silently overwriting planning files.
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
    {
      "name": "gsd-core",
      "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
-      "version": "1.7.0-rc.3",
+      "version": "1.7.0-rc.4",
      "source": "./",
      "author": {
        "name": "open-gsd",
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
  "name": "gsd-core",
  "displayName": "GSD Core",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
  "author": {
    "name": "open-gsd",
--- a/.gitignore
+++ b/.gitignore
@@ -193,6 +193,7 @@ build/
 /gsd-core/bin/lib/eval.cjs
 /gsd-core/bin/lib/eval-command-router.cjs
 /gsd-core/bin/lib/init-command-router.cjs
+/gsd-core/bin/lib/onboard-projection.cjs
 /gsd-core/bin/lib/agent-command-router.cjs
 /gsd-core/bin/lib/agent-install-check.cjs
 /gsd-core/bin/lib/task-command-router.cjs
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -68,7 +68,7 @@ Canonical command normalization and resolution Interface (`query-command-resolut
 Module owning command resolution, policy projection (`mutation`, `output_mode`), unknown-command diagnosis, and handler Adapter binding at one seam for query dispatch.

 ### Init Command Module
-Module owning the `init.*` family of query handlers that compose atomic queries into the flat JSON bundles consumed by init workflows (`/gsd-execute-phase`, `/gsd-plan-phase`, `/gsd-verify-work`, `/gsd-new-project`, `/gsd-manager`, `/gsd-progress`, `/gsd-resume`, etc.). Source of truth: `gsd-core/bin/lib/init.cjs` — the basic handlers (plus `withProjectRoot` project-identity injection) and the 3 heavyweight handlers (`initNewProject`, `initProgress`, `initManager`). All handlers return `{ data: <flat JSON> }`. Test seams: `tests/init.test.cjs` and `tests/init-manager.test.cjs` (cover withProjectRoot precedence, progress/manager precedence regression #2674, workstream scoping regression #3196, and cross-milestone dependency regression #2267). (The SDK `handlers/init/*.ts` sources and the `init*.test.ts` seams were retired with the SDK package per ADR-0174.)
+Module owning the `init.*` family of query handlers that compose atomic queries into the flat JSON bundles consumed by init workflows (`/gsd-execute-phase`, `/gsd-plan-phase`, `/gsd-verify-work`, `/gsd-new-project`, `/gsd-onboard`, `/gsd-manager`, `/gsd-progress`, `/gsd-resume`, etc.). Source of truth: `src/init.cts` and the compiled `gsd-core/bin/lib/init.cjs`; onboarding routing readiness lives in `src/onboard-projection.cts`. The basic handlers (plus `withProjectRoot` project-identity injection) and the heavyweight handlers (`initNewProject`, `initOnboard`, `initProgress`, `initManager`) return `{ data: <flat JSON> }`. Test seams: `tests/init.test.cjs`, `tests/onboard-command.test.cjs`, and `tests/init-manager.test.cjs` (cover withProjectRoot precedence, onboarding projection/rendering, progress/manager precedence regression #2674, workstream scoping regression #3196, and cross-milestone dependency regression #2267). (The SDK `handlers/init/*.ts` sources and the `init*.test.ts` seams were retired with the SDK package per ADR-0174.)

 ### Command Routing Hub
 Single dispatch seam (`gsd-core/bin/lib/command-routing-hub.cjs`) that centralizes CJS routing, the no-throw pure-result contract, typed error variants, and dispatch-event emission for all command family adapters. Interface: `createHub({ cjsRegistry, manifest, logger }) → hub`; `hub.dispatch({ family, subcommand, args, cwd, raw, parentTraceId? }) → Result` where `Result = { ok: true, data } | { ok: false, kind, ...typedPayload }` and `kind ∈ { UnknownCommand, InvalidArgs, HandlerRefusal, HandlerFailure }`. The `InvalidArgs` variant carries an optional `exitReason?: string` field (amendment #1642 / #1644 Phase 1) holding the `ERROR_REASON` enum value, separate from `reason` (the explanation text); the `makeInvalidArgs(arg, reason, exitReason?)` factory omits the field when the third arg is absent, undefined, or empty — preserving the strict-keys invariant tested at `tests/command-routing-hub.test.cjs:444`. The Hub is single-runtime (no mode selection, no sdkLoader), never prints, never exits, never throws. Adapters call `createHub`, dispatch, then translate the pure Result to `output()`/`error()` calls; when an `InvalidArgs` Result carries `exitReason`, the adapter passes it as the second arg to `error(message, exitReason)` so the JSON-error envelope (`GSD_JSON_ERRORS=1`) preserves the typed reason. Source: `gsd-core/bin/lib/command-routing-hub.cjs`; ADR: `docs/adr/0174-retire-gsd-sdk-package-boundary.md` (§5 amended #1642).
@@ -220,6 +220,8 @@ ADR-1244 Phase 4 (D5+D6) orchestration seam (`gsd-core/bin/lib/capability-lifecy
 ### Capability Command Dispatch
 ADR-1244 Phase 5 (D7) registry-driven dispatch of capability command families. First-party families (`graphify`/`intel`/`audit`, shipped in `bin/lib/`) dispatch via `dispatchCapabilityCommand` (`gsd-core/bin/gsd-tools.cjs`) against the FROZEN `capability-registry.cjs` `commandFamilies` (confined to `bin/lib/`) — unchanged. Third-party (installed overlay) families dispatch via `dispatchOverlayCapabilityCommand`: after the first-party path returns false, it calls `loadRegistry({ includeInstalled, cwd })` and dispatches a family iff its `capId` is in `_overlay.commandRoots` — which `capability-loader.cjs` populates ONLY for accepted overlay capabilities that declare `commands` AND pass the loader's activation gate (a **committed** ledger entry, present and non-`_pending`, PLUS — for PROJECT scope — a matching user consent record in the Capability Consent Store; GLOBAL scope needs no consent record). A bundle dropped on disk with no install (no ledger entry) or no on-this-machine consent is NOT command-dispatchable. The router module is `require()`'d FROM the capability's install root via `defaultRequireFromInstallRoot` (bare-`.cjs` basename + `realpath` containment, rejecting `..` traversal and symlink escape); same own-property/function/sync-only guards as the first-party path. Wired into the `runCommand` default arm before "Unknown command". A repo-planted project ledger no longer activates anything on its own (#1459) — see `docs/explanation/capability-trust-model.md` "project-scope trust boundary".

+### Claude Orchestration Capability
+Default-off, BETA, claude-only Capability (`capabilities/claude-orchestration/`, `role: feature`, `runtimeCompat.supported: ["claude"]`, `tier: full`, `activationKey: claude_orchestration.enabled`) adopting Claude Code's Workflow tool (the engine behind `/effort ultracode`, Agent SDK ≥ v0.3.149) as an optional parallel-execution backend for the GSD loop, and folding the `gsd-ultraplan-phase` plan-offload under the same runtime gate (#1143; ADR-1143). Pure, fail-closed core in `gsd-core/bin/lib/claude-orchestration.cjs` (generated from `src/claude-orchestration.cts`): `detectWorkflowBackend({ runtimeId, hostIntegration, config, agentSdkVersion }) → { available, backend:'workflow'|'inline', reason }` (gate ladder: enabled → Claude → execution_backend ≠ inline → host dispatch nested+background → valid Agent SDK → SDK ≥ floor; every miss degrades to `inline`, never throws); `emitWorkflowScript({ phaseDir, waves, runId, budgetTokens? }) → { ok, script, summary }` mapping waves → `parallel()` stage barriers, plans → `agent({ agentType:'gsd-executor', isolation:'worktree' })`, `files_modified` overlap → separate sequential stages (greedy first-fit), `resumeFromRunId` wired to the run id, shared `budget(tokens)`; all interpolated identifiers validated script-safe (no `"`,`\`,control chars) and briefs JSON-quoted (review anti-injection). Registers two loop contributions at WIRED points only (execute:wave:pre/execute:pre are declared but not rendered, same constraint external-job documents): `execute:wave:post into:executor` (Workflow-backend guidance) and `plan:post into:planner` (ultraplan ownership declaration), both `when: claude_orchestration.enabled`, `onError: skip`. Federated config keys (`claude_orchestration.enabled` default false, `execution_backend` enum auto|workflow|inline default auto, `min_agent_sdk_version` string default "0.3.149") live only in the registry — uninstall removes them cleanly. Pre-release versions of the floor compare below GA (SemVer precedence). Restores the wave parallelism + plan-checker + verifier that #853 forces inline on Claude Code; on any runtime lacking the Workflow tool, behaviour is byte-identical to today. BETA v1 ships detection + emission + declarative ultraplan ownership + a `claude-orchestration` command family (`gsd-tools claude-orchestration detect-backend|emit-workflow`, router `gsd-core/bin/lib/claude-orchestration-command-router.cjs` from `src/claude-orchestration-command-router.cts`); full install-profile migration of the ultraplan skill into `skills[]` is a follow-up (CLUSTERS/profile gate). Test anchors: `tests/claude-orchestration.test.cjs`, `tests/claude-orchestration-command-router.test.cjs`.
 ### Loop Extension Point
 A named, stable site on a host loop step (per-step `pre`/`post` plus per-wave in Execute; 12 total) where Capabilities register hooks. Three hook kinds: `step` (runs as its own sequenced unit), `contribution` (injects into the core step's prompt/context), and `gate` (checks and optionally blocks via a declared `blocking` flag). Each hook declares the artifacts it produces and consumes; hook order is derived by topological sort of that produces/consumes graph (capability-id tiebreak), which also defines data flow — file-artifact based, surviving `/clear` and fresh executor contexts. Hooks are surfaced by runtime resolution with concrete projection: the workflow calls a query that resolves the active hooks and returns fully-rendered, ordered markdown for the executor. Failure is default-resilient — a non-gate hook that errors is skipped with a warning; a hook may opt into `onError: halt`. Part of the Capability system. ADR-857 phase 3c ships the registry-consuming query layer: `gsd-core/bin/lib/loop-resolver.cjs` exposes `resolveLoopHooks({ point, registry, config })` (pure, no I/O), `renderLoopHooks(resolved)` (pure markdown renderer), and `cmdLoopRenderHooks(cwd, point, raw, opts)` (I/O entry point); activated via `gsd-tools loop render-hooks <point>` which emits `{ point, activeHooks[], rendered }`. Activation is driven by `when` (dotted config key resolved against `loadConfig`), with inline literal `__proto__`/`constructor`/`prototype` prototype-pollution guard. The first phase-6 cutovers wiring workflows to this query have landed — ui-phase at `plan:pre` and ui-review at `verify:post` (in `plan-phase.md`/`autonomous.md`); further per-feature cutovers are ongoing.

--- a/README.ja-JP.md
+++ b/README.ja-JP.md
@@ -47,13 +47,14 @@ npx @opengsd/gsd-core@latest

 別のランタイムをお使いの場合や Node.js がない場合は [ランタイムへのインストール](docs/ja-JP/how-to/install-on-your-runtime.md) を参照してください。

-インストール後、最初のプロジェクトを開始します。
+インストール後、新規プロジェクトを開始するか、既存リポジトリをオンボーディングします。

 ```bash
-/gsd-new-project
+/gsd-new-project   # グリーンフィールドプロジェクト
+/gsd-onboard       # 既存コードベース
 ```

-初めての方は [はじめてのプロジェクト](docs/ja-JP/tutorials/your-first-project.md) で、インストールから最初のフェーズ出荷までのガイド付きチュートリアルをご覧ください。
+初めての方は [はじめてのプロジェクト](docs/ja-JP/tutorials/your-first-project.md) で、インストールから最初のフェーズ出荷までのガイド付きチュートリアルをご覧ください。既存リポジトリの場合は [既存コードベースのオンボーディング](docs/ja-JP/tutorials/onboarding-an-existing-codebase.md) を参照してください。

 ---

--- a/README.ko-KR.md
+++ b/README.ko-KR.md
@@ -47,13 +47,14 @@ npx @opengsd/gsd-core@latest

 다른 런타임이나 Node.js가 없는 환경은 [런타임에 설치하기](docs/ko-KR/how-to/install-on-your-runtime.md)를 참조하세요.

-설치 후 첫 번째 프로젝트를 시작합니다:
+설치 후 새 프로젝트를 시작하거나 기존 저장소를 온보딩합니다:

 ```bash
-/gsd-new-project
+/gsd-new-project   # 그린필드 프로젝트
+/gsd-onboard       # 기존 코드베이스
 ```

-처음 사용하시나요? [첫 번째 프로젝트](docs/ko-KR/tutorials/your-first-project.md)를 따라 설치부터 첫 단계 출시까지 안내받으세요.
+처음 사용하시나요? [첫 번째 프로젝트](docs/ko-KR/tutorials/your-first-project.md)를 따라 설치부터 첫 단계 출시까지 안내받으세요. 기존 저장소라면 [기존 코드베이스 온보딩](docs/ko-KR/tutorials/onboarding-an-existing-codebase.md)을 참고하세요.

 ---

--- a/README.md
+++ b/README.md
@@ -47,13 +47,14 @@ The installer prompts for your runtime (Claude Code, OpenCode, Antigravity CLI,

 On another runtime or without Node.js? See [Install on your runtime](docs/how-to/install-on-your-runtime.md).

-Once installed, start your first project:
+Once installed, start a new project or onboard an existing repo:

 ```bash
-/gsd-new-project
+/gsd-new-project   # greenfield project
+/gsd-onboard       # existing codebase
 ```

-New here? Follow [Your first project](docs/tutorials/your-first-project.md) for a guided walkthrough from install to first shipped phase.
+New here? Follow [Your first project](docs/tutorials/your-first-project.md) for a guided walkthrough from install to first shipped phase, or [Onboarding an existing codebase](docs/tutorials/onboarding-an-existing-codebase.md) for brownfield setup.

 ---

--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -47,13 +47,14 @@ O instalador solicita seu ambiente de execução (Claude Code, OpenCode, Gemini

 Em outro runtime ou sem Node.js? Consulte [Instalar no seu runtime](docs/pt-BR/how-to/install-on-your-runtime.md).

-Após a instalação, inicie seu primeiro projeto:
+Após a instalação, inicie um projeto novo ou integre um repositório existente:

 ```bash
-/gsd-new-project
+/gsd-new-project   # projeto greenfield
+/gsd-onboard       # base de código existente
 ```

-É a primeira vez? Siga [Seu primeiro projeto](docs/pt-BR/tutorials/your-first-project.md) para um passo a passo guiado, desde a instalação até a primeira fase entregue.
+É a primeira vez? Siga [Seu primeiro projeto](docs/pt-BR/tutorials/your-first-project.md) para um passo a passo guiado, desde a instalação até a primeira fase entregue. Para um repositório existente, consulte [Integrar uma base de código existente](docs/pt-BR/tutorials/onboarding-an-existing-codebase.md).

 ---

--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -47,13 +47,14 @@ npx @opengsd/gsd-core@latest

 使用其他运行时或没有 Node.js？请参阅[在你的运行时上安装](docs/zh-CN/how-to/install-on-your-runtime.md)。

-安装完成后，启动你的第一个项目：
+安装完成后，启动一个新项目或接入现有仓库：

 ```bash
-/gsd-new-project
+/gsd-new-project   # 新建项目
+/gsd-onboard       # 现有代码库
 ```

-初次使用？请按照[你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)进行引导式操作，从安装到完成第一个交付阶段。
+初次使用？请按照[你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)进行引导式操作，从安装到完成第一个交付阶段。对于现有仓库，请参阅[接入现有代码库](docs/zh-CN/tutorials/onboarding-an-existing-codebase.md)。

 ---

--- a/capabilities/ai-integration/capability.json
+++ b/capabilities/ai-integration/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "ai-integration",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "AI design contract",
  "description": "AI-SPEC design contract workflow for phases that build AI systems; owns the AI integration command, agents, and workflow.ai_integration_phase activation key.",
  "tier": "full",
--- a/capabilities/antigravity/capability.json
+++ b/capabilities/antigravity/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "antigravity",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Antigravity",
  "description": "Google Antigravity IDE — nested under ~/.gemini/antigravity; probed across 1.x and 2.x layouts; Gemini hook event dialect; flat skill layout; tier-1 support.",
  "tier": "core",
--- a/capabilities/assumption-delta/capability.json
+++ b/capabilities/assumption-delta/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "assumption-delta",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Assumption-delta architecture checkpoint",
  "description": "Rarely-firing advisory checkpoint that triggers when a phase makes something plural, optional, or chosen that used to be singular, required, or derived. Surfaces one identity-model question (promote the new general representation to primary, or add it alongside?) so a silent primary-key drift does not accumulate into a later user-facing bug. Non-blocking; fires only on a detected signal.",
  "tier": "full",
--- a/capabilities/audit/capability.json
+++ b/capabilities/audit/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "audit",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Audit",
  "description": "Open-artifact audit and UAT-gap audit for milestone close gates; exposes `gsd-tools audit-uat` (cross-phase UAT outstanding items) and `gsd-tools audit-open` (structured open-artifact scan across debug, tasks, threads, todos, seeds, UAT, verification, context-questions).",
  "tier": "full",
--- a/capabilities/augment/capability.json
+++ b/capabilities/augment/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "augment",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Augment Code",
  "description": "Augment Code CLI — commands + nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
  "tier": "core",
--- a/capabilities/claude-orchestration/capability.json
+++ b/capabilities/claude-orchestration/capability.json
@@ -0,0 +1,85 @@
+{
+  "id": "claude-orchestration",
+  "role": "feature",
+  "version": "1.7.0-rc.4",
+  "title": "Claude orchestration (Workflow backend)",
+  "description": "Default-off, BETA, claude-only capability that adopts Claude Code's Workflow tool (the engine behind /effort ultracode) as an optional parallel-execution backend for the GSD loop. When the runtime exposes the Workflow tool and claude_orchestration.execution_backend resolves to 'workflow', execute-phase emits a generated Workflow script (waves -> parallel() barriers, plans -> agent({ agentType: 'gsd-executor', isolation: 'worktree' }), files_modified overlap -> separate sequential stages, resumeFromRunId wired to the phase run id, shared token budget) that composes the SAME gsd-executor agent and worktree isolation the inline path uses, restoring the wave parallelism the #853 backgrounded-agent nesting limitation forces inline on Claude Code. (The plan-checker and verifier remain inline until separately wired — this capability delivers the parallel-execution backend, not those gates.) Also folds the ultraplan plan-offload under one runtime gate (plan:* surface). On any runtime lacking the Workflow tool, or when the capability is disabled, behaviour is byte-identical to today (inline/manual dispatch). Detection + emission live in gsd-core/bin/lib/claude-orchestration.cjs (pure, fail-closed). Mirrors the existing gsd-ultraplan-phase BETA-isolation posture.",
+  "tier": "full",
+  "requires": [],
+  "engines": {
+    "gsd": ">=1.7.0"
+  },
+  "runtimeCompat": {
+    "supported": [
+      "claude"
+    ],
+    "unsupported": []
+  },
+  "skills": [],
+  "agents": [],
+  "hooks": [],
+  "commands": [
+    {
+      "family": "claude-orchestration",
+      "module": "claude-orchestration-command-router.cjs",
+      "router": "routeClaudeOrchestrationCommand",
+      "subcommands": [
+        "detect-backend",
+        "emit-workflow"
+      ]
+    }
+  ],
+  "activationKey": "claude_orchestration.enabled",
+  "config": {
+    "claude_orchestration.enabled": {
+      "type": "boolean",
+      "default": false,
+      "description": "Master toggle for the Claude orchestration capability. Default-off + BETA: the Workflow-tool execution backend and the ultraplan plan-offload surface are inert unless this is true. When false, loop behaviour is byte-identical to a non-Claude runtime (inline/manual dispatch)."
+    },
+    "claude_orchestration.execution_backend": {
+      "type": "enum",
+      "values": [
+        "auto",
+        "workflow",
+        "inline"
+      ],
+      "default": "auto",
+      "description": "Which execute-phase dispatch backend to use when the capability is enabled. 'auto' (default) activates the Workflow backend only when the runtime is Claude AND the Workflow tool is detected AND the Agent SDK meets claude_orchestration.min_agent_sdk_version; otherwise it falls back to inline. 'workflow' forces the Workflow backend when the tool is present AND the Agent SDK meets the floor (still fails closed to inline if the tool is absent or the SDK is too old — the floor applies in both modes). 'inline' forces today's manual one-agent-per-message dispatch regardless of tool availability."
+    },
+    "claude_orchestration.min_agent_sdk_version": {
+      "type": "string",
+      "default": "0.3.149",
+      "description": "Minimum Agent SDK version required to activate the Workflow backend under execution_backend='auto'. Defaults to 0.3.149 (the release that introduced the Workflow tool). Raise to pin a higher floor; the detection seam fails closed to inline for any runtime reporting an older or unknown version."
+    }
+  },
+  "steps": [],
+  "contributions": [
+    {
+      "point": "execute:wave:post",
+      "into": "executor",
+      "fragment": {
+        "path": "fragments/execute-wave-post.md"
+      },
+      "produces": [],
+      "consumes": [
+        "PLAN.md"
+      ],
+      "when": "claude_orchestration.enabled",
+      "onError": "skip"
+    },
+    {
+      "point": "plan:post",
+      "into": "planner",
+      "fragment": {
+        "path": "fragments/plan-post.md"
+      },
+      "produces": [],
+      "consumes": [
+        "CONTEXT.md"
+      ],
+      "when": "claude_orchestration.enabled",
+      "onError": "skip"
+    }
+  ],
+  "gates": []
+}
--- a/capabilities/claude-orchestration/fragments/execute-wave-post.md
+++ b/capabilities/claude-orchestration/fragments/execute-wave-post.md
@@ -0,0 +1,64 @@
+# Claude orchestration — Workflow execution backend (BETA)
+
+> Injected at `execute:wave:post` `into: executor` only when
+> `claude_orchestration.enabled` is true. Default-off; `onError: skip`.
+
+## When this contribution is active
+
+The Claude orchestration capability is **default-off and BETA**. It activates only
+when ALL of the following hold:
+
+1. `claude_orchestration.enabled` is `true` in `.planning/config.json`, AND
+2. the active runtime is **Claude Code** (the Workflow tool is Claude / Agent
+   SDK-specific), AND
+3. `claude_orchestration.execution_backend` resolves to `workflow` — either
+   explicitly, or via `auto` — **and** the Agent SDK version is
+   `>= claude_orchestration.min_agent_sdk_version` (default `0.3.149`). The SDK
+   floor applies in both `auto` and `workflow` modes (fail-closed: a pre-release
+   or older SDK never activates the preview backend).
+
+Detection is fail-closed: any miss degrades to **inline, manual, one-agent-per-
+message dispatch** — exactly today's behaviour. On a non-Claude runtime this
+contribution is a no-op.
+
+## What the executor does when the Workflow backend is active
+
+Instead of the orchestrator fanning out one `Agent(subagent_type=gsd-executor,
+isolation=worktree, run_in_background=true)` per message (which on Claude Code
+cannot nest further subagents — #853 — and so degrades to sequential inline
+execution), execute-phase **emits a generated Workflow script** and lets the main
+loop orchestrate it:
+
+- **waves → one or more sequential `parallel()` barriers** — each wave is a
+  barrier group; when plans within a wave share `files_modified`, they are split
+  into separate sequential stages within that wave's barrier (the next wave
+  still waits for the previous wave to complete).
+- **plans → `agent(brief, { agentType: 'gsd-executor', isolation: 'worktree' })`**
+  — the SAME executor agent and worktree isolation the inline path uses, so the
+  produced `SUMMARY.md` and commits are identical.
+- **`files_modified` overlap → separate sequential stages** — two plans that
+  touch the same file are placed in different stages within the wave (the same
+  overlap rule execute-phase already applies inline).
+- **`resumeFromRunId`** — wired to the phase run id, so an interrupted phase
+  resumes without re-running completed plans.
+- **`budget(tokens)`** — a shared token pool across the whole phase when the
+  orchestrator passes a `budgetTokens` value to `emitWorkflowScript` (it is a
+  function parameter, not a config key; the orchestrator decides the budget).
+
+The emitter is a pure function exposed through the capability command surface:
+`gsd-tools claude-orchestration emit-workflow --waves <manifest.json> --run-id <id>
+[--phase-dir <dir>] [--budget <n>]` (or `require('gsd-core/bin/lib/claude-orchestration.cjs').emitWorkflowScript`
+directly). It maps the phase's wave/plan manifest to the Workflow script string
+and never invokes the Workflow tool itself; the orchestrator runs the emitted
+script. Detection is resolved by the orchestrator calling the pure
+`detectWorkflowBackend` with the LIVE host descriptor (the CLI
+`gsd-tools claude-orchestration detect-backend` is a simulation harness that
+assumes a capable host unless `--no-nested-dispatch` is passed — it does not probe
+the real runtime; the orchestrator supplies the real descriptor).
+
+## Fallback contract
+
+If detection resolves to `inline` (tool absent, SDK too old, runtime not Claude,
+or the capability disabled), execute-phase MUST proceed with the standard inline
+wave dispatch. The executor MUST NOT assume parallelism, a shared budget, or
+resume-from-run-id semantics in that mode.
--- a/capabilities/claude-orchestration/fragments/plan-post.md
+++ b/capabilities/claude-orchestration/fragments/plan-post.md
@@ -0,0 +1,28 @@
+# Claude orchestration — ultraplan plan-offload ownership (BETA)
+
+> Injected at `plan:post` `into: planner` only when
+> `claude_orchestration.enabled` is true. Default-off; `onError: skip`.
+
+## Ownership declaration
+
+The `gsd-ultraplan-phase` plan-offload surface (offloading GSD's plan phase to
+Claude Code's ultraplan cloud) is **owned by this capability**, not by a
+standalone BETA skill. Both surfaces share one runtime gate
+(`claude_orchestration.enabled`), one BETA boundary, and one Claude-Code-only
+detection seam.
+
+## When the planner should consider ultraplan offload
+
+When this contribution is active (capability enabled, Claude Code runtime), the
+planner MAY offer the `/gsd-ultraplan-phase` path as an alternative to local
+`/gsd-plan-phase` for phases where cloud-assisted planning adds value. This is
+advisory, not mandatory — the stable local planner remains the default.
+
+## Fallback contract
+
+If the capability is disabled, or the runtime is not Claude Code, ultraplan
+offload is **not surfaced** and the planner proceeds with the standard local
+`/gsd-plan-phase`. The `gsd-ultraplan-phase` command itself remains installed
+(its own runtime gate already no-ops on non-Claude runtimes); this contribution
+only governs whether the capability manifest advertises it as part of the
+orchestration surface.
--- a/capabilities/claude/capability.json
+++ b/capabilities/claude/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "claude",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Claude Code",
  "description": "Anthropic Claude Code — primary development runtime; tier-1 support with full hook surface and skills-based global install.",
  "tier": "core",
--- a/capabilities/cline/capability.json
+++ b/capabilities/cline/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "cline",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Cline",
  "description": "Cline (VS Code extension) — global-only nested-skill layout; cline-rules hook surface (.clinerules); no hook events emitted; tier-2 support.",
  "tier": "core",
--- a/capabilities/code-review/capability.json
+++ b/capabilities/code-review/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "code-review",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Code review",
  "description": "Source-file code review and review-fix workflow support for completed execution work.",
  "tier": "full",
--- a/capabilities/codebuddy/capability.json
+++ b/capabilities/codebuddy/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "codebuddy",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "CodeBuddy",
  "description": "CodeBuddy (Tencent) — converted commands + skills artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
  "tier": "core",
--- a/capabilities/codex/capability.json
+++ b/capabilities/codex/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "codex",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "OpenAI Codex CLI",
  "description": "OpenAI Codex CLI — shell-var command style; per-agent sandbox tiers; config.toml + hooks.json hook surface; tier-1 support.",
  "tier": "core",
--- a/capabilities/copilot/capability.json
+++ b/capabilities/copilot/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "copilot",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "GitHub Copilot",
  "description": "GitHub Copilot (VS Code) — markdown config format; copilot-inline hook surface; no hook events emitted; flat skill nesting (unconfirmed recursive loader); tier-2 support.",
  "tier": "core",
--- a/capabilities/cursor/capability.json
+++ b/capabilities/cursor/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "cursor",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Cursor",
  "description": "Cursor IDE — skills + converted commands artifact layout; hooks.json surface; Claude hook event dialect; recursive skill loader (flat nesting); tier-2 support.",
  "tier": "core",
--- a/capabilities/drift/capability.json
+++ b/capabilities/drift/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "drift",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Drift detection gates",
  "description": "Drift detection gates for the planning loop. At execute:wave:post: a blocking schema drift gate (detects schema files changed without a database push) and a non-blocking codebase drift gate (detects structural additions not reflected in STRUCTURE.md). At plan:pre: a non-blocking, warn-only codebase drift gate (gated on workflow.plan_drift_precheck) that flags a stale codebase map before planning, so plans are authored against a fresh STRUCTURE.md instead of discovering drift mid-execution.",
  "tier": "full",
--- a/capabilities/external-job/capability.json
+++ b/capabilities/external-job/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "external-job",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Async external-job scheduler adapter",
  "description": "Default-off producer of the async external-job manifest (#1164). At execute:wave:post an executor can externalize long-running compute (SLURM first, scheduler-pluggable), commit a .planning/async-jobs/<job>.json manifest, defer SUMMARY.md, and return external_job_waiting. The core loop (#1165) consumes the manifest; this capability is the only thing that writes it. NOTE on contribution point: #1164 specifies execute:wave:pre, but execute-phase.md only dispatches execute:wave:post today (wave:pre is declared in the loop host contract but not rendered); wiring wave:pre dispatch is a core-loop change #1164 explicitly puts out of scope, so this capability registers at wave:post and the executor honors the runtime_budget classification guidance before running any tagged task. The adapter (scripts/slurm-adapter.cjs) reads external_job.submit_timeout_ms / poll_timeout_ms / artifact_dir through the canonical capability-config seam (env override > config > registry default).",
  "tier": "full",
--- a/capabilities/gap-analysis/capability.json
+++ b/capabilities/gap-analysis/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "gap-analysis",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Post-planning gap analysis",
  "description": "Proactive, non-blocking post-planning coverage report. After all PLAN.md files are generated, cross-references every REQ-ID and D-ID from REQUIREMENTS.md and CONTEXT.md against plan bodies. Emits a Source | Item | Status table. Does not block phase advancement.",
  "tier": "standard",
--- a/capabilities/graphify/capability.json
+++ b/capabilities/graphify/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "graphify",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Knowledge graph",
  "description": "Build, query, and inspect the project knowledge graph in `.planning/graphs/`; exposes graphify CLI subcommands (build, query, status, diff) and the /gsd-graphify skill.",
  "tier": "full",
--- a/capabilities/hermes/capability.json
+++ b/capabilities/hermes/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "hermes",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Hermes Agent",
  "description": "Hermes Agent (NousResearch) — skills nest under skills/gsd/ category bucket; nested skill layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
  "tier": "core",
--- a/capabilities/intel/capability.json
+++ b/capabilities/intel/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "intel",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Codebase intelligence",
  "description": "Code-intelligence store for codebase querying, diff, snapshot, and API-surface extraction; exposes `gsd-tools intel` subcommands (query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface) and backs `/gsd-map-codebase` and `gsd-intel-updater`.",
  "tier": "full",
--- a/capabilities/kilo/capability.json
+++ b/capabilities/kilo/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "kilo",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Kilo Code",
  "description": "Kilo Code — XDG-based config dir; global skills at ~/.kilo/skills (separate from XDG config); flat command/ + skills artifact layout; no lifecycle hook registration; tier-2 support.",
  "tier": "core",
--- a/capabilities/kimi/capability.json
+++ b/capabilities/kimi/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "kimi",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Kimi CLI",
  "description": "Kimi CLI (Moonshot AI) — generic agents root at ~/.config/agents; skills + kimi-agents artifact layout; no hook surface; no hook events; tier-2 support.",
  "tier": "core",
--- a/capabilities/mempalace/capability.json
+++ b/capabilities/mempalace/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "mempalace",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "MemPalace memory",
  "description": "Cross-session, cross-project memory: deliberate recall before discuss/plan and verbatim capture + temporal-KG sync at phase boundaries, via the MemPalace MCP server and CLI.",
  "tier": "full",
--- a/capabilities/nyquist/capability.json
+++ b/capabilities/nyquist/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "nyquist",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Nyquist validation",
  "description": "Validation coverage audit that maps executed work back to tests and manual-only evidence.",
  "tier": "full",
--- a/capabilities/opencode/capability.json
+++ b/capabilities/opencode/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "opencode",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "OpenCode",
  "description": "OpenCode — XDG-based config dir; flat command/ + skills artifact layout; settings-json config format; no lifecycle hook registration; tier-2 support.",
  "tier": "core",
--- a/capabilities/pattern-mapper/capability.json
+++ b/capabilities/pattern-mapper/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "pattern-mapper",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Pattern mapping",
  "description": "Optional codebase-pattern mapping before planning; owns the pattern mapper agent and workflow.pattern_mapper activation key.",
  "tier": "full",
--- a/capabilities/profile-pipeline/capability.json
+++ b/capabilities/profile-pipeline/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "profile-pipeline",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Developer profiling pipeline",
  "description": "Developer behavioral profiling from Claude Code session history; scans session JSONL files, extracts and samples user messages, and generates profile artifacts (USER-PROFILE.md, dev-preferences.md, CLAUDE.md sections). Exposes eight `gsd-tools` commands: scan-sessions, extract-messages, profile-sample (pipeline phase) and write-profile, profile-questionnaire, generate-dev-preferences, generate-claude-profile, generate-claude-md (output phase). Backs the /gsd-profile-user skill and gsd-user-profiler agent.",
  "tier": "full",
--- a/capabilities/qwen/capability.json
+++ b/capabilities/qwen/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "qwen",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Qwen Code",
  "description": "Qwen Code (Alibaba) — nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
  "tier": "core",
--- a/capabilities/research/capability.json
+++ b/capabilities/research/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "research",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Phase research",
  "description": "Optional phase research before planning; owns the phase researcher agent and workflow.research activation key.",
  "tier": "standard",
--- a/capabilities/schema-gate/capability.json
+++ b/capabilities/schema-gate/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "schema-gate",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Schema push detection gate",
  "description": "Detects ORM schema-relevant files in the phase scope during planning and injects a mandatory [BLOCKING] schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.",
  "tier": "full",
--- a/capabilities/security/capability.json
+++ b/capabilities/security/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "security",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Security enforcement",
  "description": "Threat mitigation verification and ship-time security blocking for phases with security enforcement enabled.",
  "tier": "full",
--- a/capabilities/tdd/capability.json
+++ b/capabilities/tdd/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "tdd",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Test-driven development",
  "description": "Injects TDD heuristics into the planner and enforces RED/GREEN gate compliance on type:tdd plans after execution. Owns workflow.tdd_mode; the --tdd CLI flag is the ephemeral override.",
  "tier": "full",
--- a/capabilities/trae/capability.json
+++ b/capabilities/trae/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "trae",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Trae IDE",
  "description": "Trae IDE — nested-skill artifact layout; no hook surface (profile-marker-only config); tier-2 support.",
  "tier": "core",
--- a/capabilities/ui/capability.json
+++ b/capabilities/ui/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "ui",
  "role": "feature",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "UI design contracts",
  "description": "UI-SPEC design contract + retrospective UI audit for frontend phases.",
  "tier": "full",
--- a/capabilities/windsurf/capability.json
+++ b/capabilities/windsurf/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "windsurf",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "Windsurf",
  "description": "Windsurf (Codeium) — workspace workflow artifact layout for slash commands; no hook surface; no hook events; tier-2 support.",
  "tier": "core",
--- a/capabilities/zcode/capability.json
+++ b/capabilities/zcode/capability.json
@@ -1,7 +1,7 @@
 {
  "id": "zcode",
  "role": "runtime",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
  "title": "ZCode",
  "description": "ZCode (Z.ai) — desktop Agentic Development Environment for GLM-5.2; Claude-shaped nested skills at ~/.zcode/skills/<name>/SKILL.md, slash commands, named subagents, native MCP; declarative plugin surface; profile-marker install; tier-2 community support.",
  "tier": "core",
--- a/commands/gsd/map-codebase.md
+++ b/commands/gsd/map-codebase.md
@@ -9,7 +9,7 @@ allowed-tools:
  - Grep
  - Write
  - Agent
-requires: [config, new-project, plan-phase]
+requires: [config, new-project, plan-phase, onboard]
 ---

 <objective>
@@ -42,7 +42,7 @@ Parse the first token of $ARGUMENTS:
 Check for .planning/STATE.md - loads context if project already initialized

 **This command can run:**
- Before /gsd:new-project (brownfield codebases) - creates codebase map first
+- Via /gsd:onboard for first-time brownfield setup - creates codebase map first
 - After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
 - Anytime to refresh codebase understanding
 </context>
@@ -51,7 +51,7 @@ Check for .planning/STATE.md - loads context if project already initialized
 **Use map-codebase for:**
 - Brownfield projects before initialization (understand existing code first)
 - Refreshing codebase map after significant changes
- Onboarding to an unfamiliar codebase
+- Refreshing or deepening an onboarded codebase map
 - Before major refactoring (understand current state)
 - When STATE.md references outdated codebase info

@@ -71,7 +71,7 @@ Check for .planning/STATE.md - loads context if project already initialized
 4. Wait for agents to complete, collect confirmations (NOT document contents)
 5. Verify all 7 documents exist with line counts
 6. Commit codebase map
-7. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
+7. Offer next steps (typically: /gsd:onboard, /gsd:new-project, or /gsd:plan-phase)
 </process>

 <success_criteria>
--- a/commands/gsd/ns-project.md
+++ b/commands/gsd/ns-project.md
@@ -5,7 +5,7 @@ argument-hint: ""
 allowed-tools:
  - Read
  - Skill
-requires: [new-project, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
+requires: [new-project, onboard, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
 ---

 Route to the appropriate project / milestone skill based on the user's intent.
@@ -15,6 +15,7 @@ inline as part of `gsd-audit-milestone`'s output.
 | User wants | Invoke |
 |---|---|
 | Start a new project | gsd-new-project |
+| Onboard an existing codebase | gsd-onboard |
 | Create a new milestone | gsd-new-milestone |
 | Complete the current milestone | gsd-complete-milestone |
 | Audit a milestone for issues | gsd-audit-milestone |
--- a/commands/gsd/onboard.md
+++ b/commands/gsd/onboard.md
@@ -0,0 +1,46 @@
+---
+name: gsd:onboard
+description: Guide existing codebase onboarding through mapping, doc ingest, and planning setup
+argument-hint: "[--fast] [--text]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [config, new-project, map-codebase, ingest-docs, manager]
+---
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<objective>
+Guide brownfield onboarding for an existing codebase by routing through the existing GSD primitives in the safe order: codebase map → docs ingest → project initialization → onboarding summary.
+
+**Creates or confirms:**
+- `.planning/codebase/` — evidence-backed codebase map from `/gsd:map-codebase`
+- `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` — project setup from `/gsd:new-project` or `/gsd:ingest-docs`
+- `.planning/onboarding/SUMMARY.md` — lightweight index of what was learned and the next command
+
+**Non-goals:** This command does not execute phases, ship work, or overwrite existing planning artifacts without an explicit gate.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/onboard.md
+@~/.claude/gsd-core/references/ui-brand.md
+@~/.claude/gsd-core/references/gate-prompts.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags:
+- `--fast` — prefer `/gsd:map-codebase --fast` for the mapping handoff; the complete map is still required before `/gsd:new-project`.
+- `--text` — use plain-text numbered lists instead of TUI menus.
+</context>
+
+<process>
+Execute the onboard workflow end-to-end. Preserve all safety gates, text-mode fallbacks, idempotency checks, and top-level handoff rules for nested interactive commands.
+</process>
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -620,7 +620,8 @@ Equivalent paths for other runtimes:
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # Brownfield mapping (from /gsd-map-codebase)
+├── codebase/               # Brownfield mapping (from /gsd-map-codebase or /gsd-onboard)
+├── onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
 │   ├── STACK.md            # YAML frontmatter carries `last_mapped_commit`
 │   ├── ARCHITECTURE.md     # for the post-execute drift gate (#2003)
 │   ├── CONVENTIONS.md
--- a/docs/CLI-TOOLS.md
+++ b/docs/CLI-TOOLS.md
@@ -421,13 +421,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Init Commands (Compound Context Loading)

-Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data.
+Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data. `init onboard [--fast] [--text]` reports brownfield signals, planning-doc candidates, codebase-map completeness, fast-map readiness, text-mode routing, partial planning state, and onboarding summary status for `/gsd-onboard`.

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -58,6 +58,25 @@ Initialize a new project with deep context gathering.

 ---

+### `/gsd-onboard`
+
+Guide an existing codebase through first-time GSD onboarding. The command checks repo state, routes you through codebase mapping, optional docs ingest, project initialization, and creates an onboarding summary once planning exists.
+
+| Flag | Description |
+|------|-------------|
+| `--fast` | Prefer the lightweight `/gsd-map-codebase --fast` mapping handoff; a complete map is still required before `/gsd-new-project` |
+| `--text` | Use numbered plain-text gates instead of TUI menus |
+
+**Prerequisites:** Existing repo or planning docs. For empty greenfield projects, use `/gsd-new-project`.
+**Produces:** `.planning/codebase/` via map-codebase, `.planning/` via new-project or ingest-docs, and `.planning/onboarding/SUMMARY.md` after project setup.
+
+```bash
+/gsd-onboard           # Guided brownfield onboarding
+/gsd-onboard --fast    # Use lightweight codebase mapping first, then complete the map before project setup
+```
+
+---
+
 ### `/gsd-workspace`

 Manage GSD workspaces — create, list, or remove isolated workspace environments with repo copies and independent `.planning/` directories.
@@ -1183,7 +1202,7 @@ gsd capability remove my-cap --scope project          # Turn the installed overl

 ### `/gsd-map-codebase`

-Analyze existing codebase with parallel mapper agents. Use `--fast` for a quick single-agent scan, or `--query` to search existing intel.
+Analyze existing codebase with parallel mapper agents. Use `--fast` for a quick single-agent scan, or `--query` to search existing intel. First-time brownfield setup should usually start with `/gsd-onboard`, which hands off to this command when a map is missing.

 | Argument | Required | Description |
 |----------|----------|-------------|
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -38,6 +38,7 @@
  - [Model Profiles](#26-model-profiles)
 - [Brownfield Features](#brownfield-features)
  - [Codebase Mapping](#27-codebase-mapping)
+  - [Existing Codebase Onboarding](#27b-existing-codebase-onboarding)
 - [Utility Features](#utility-features)
  - [Debug System](#28-debug-system)
  - [Todo Management](#29-todo-management)
@@ -789,7 +790,7 @@

 **Command:** `/gsd-map-codebase [area]`

-**Purpose:** Analyze an existing codebase before starting a new project, so GSD understands what exists.
+**Purpose:** Analyze an existing codebase before starting a new project or as the mapping handoff from `/gsd-onboard`, so GSD understands what exists.

 **Requirements:**
 - REQ-MAP-01: System MUST spawn parallel mapper agents for each analysis area
@@ -817,6 +818,27 @@ only the subtrees the phase actually changed. Each produced document carries
 `last_mapped_commit` in its YAML frontmatter so drift can be measured
 against the mapping point, not HEAD.

+### 27b. Existing Codebase Onboarding
+
+**Command:** `/gsd-onboard [--fast] [--text]`
+
+**Purpose:** Guide first-time setup for an existing repository by checking brownfield state, routing through codebase mapping and docs ingest, then handing off to project initialization without silently overwriting planning artifacts.
+
+**Requirements:**
+- REQ-ONBOARD-01: System MUST detect existing code, package manifests, planning documents, partial `.planning/` state, and complete or missing codebase-map files.
+- REQ-ONBOARD-02: System MUST hand off to `/gsd-map-codebase` or `/gsd-map-codebase --fast` when brownfield code lacks the required `.planning/codebase/` map files; fast-map readiness is partial and MUST NOT be treated as sufficient for `/gsd-new-project`.
+- REQ-ONBOARD-03: System MUST offer `/gsd-ingest-docs` before `/gsd-new-project` when ADR/PRD/SPEC/RFC candidates exist and no project exists.
+- REQ-ONBOARD-04: System MUST refuse to report onboarding complete until `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist.
+- REQ-ONBOARD-05: System MUST create or confirm `.planning/onboarding/SUMMARY.md` only after project setup exists.
+- REQ-ONBOARD-06: System MUST support `--text` for numbered plain-text gates on runtimes without interactive menus.
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| `.planning/codebase/` | Codebase map produced by the `/gsd-map-codebase` handoff |
+| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | Planning setup produced by `/gsd-new-project` or `/gsd-ingest-docs` |
+| `.planning/onboarding/SUMMARY.md` | Onboarding status, artifact index, and next-command summary |
+
 ### 27a. Post-Execute Codebase Drift Detection

 **Introduced by:** #2003
--- a/docs/INVENTORY-MANIFEST.json
+++ b/docs/INVENTORY-MANIFEST.json
@@ -78,6 +78,7 @@
      "/gsd-ns-project",
      "/gsd-ns-review",
      "/gsd-ns-workflow",
+      "/gsd-onboard",
      "/gsd-pause-work",
      "/gsd-phase",
      "/gsd-plan-phase",
@@ -160,6 +161,7 @@
      "next.md",
      "node-repair.md",
      "note.md",
+      "onboard.md",
      "pause-work.md",
      "plan-milestone-gaps.md",
      "plan-phase.md",
@@ -225,6 +227,7 @@
      "gates.md",
      "git-integration.md",
      "git-planning-commit.md",
+      "gsd-run-resolver.md",
      "honest-verifier.md",
      "ios-scaffold.md",
      "loop-hook-dispatch.md",
@@ -307,6 +310,8 @@
      "capability-writer.cjs",
      "check-command-router.cjs",
      "cjs-command-router-adapter.cjs",
+      "claude-orchestration-command-router.cjs",
+      "claude-orchestration.cjs",
      "cli-exit.cjs",
      "cli-skew-check.cjs",
      "clock.cjs",
@@ -368,6 +373,7 @@
      "model-catalog.cjs",
      "model-profiles.cjs",
      "model-resolver.cjs",
+      "onboard-projection.cjs",
      "package-identity.cjs",
      "package-legitimacy.cjs",
      "phase-command-router.cjs",
--- a/docs/INVENTORY.md
+++ b/docs/INVENTORY.md
@@ -79,6 +79,7 @@ These six routers are descriptor-only entries that the model picks first; the bo
 | Command | Role | Source |
 |---------|------|--------|
 | `/gsd-new-project` | Initialize a new project with deep context gathering and PROJECT.md. | [commands/gsd/new-project.md](../commands/gsd/new-project.md) |
+| `/gsd-onboard` | Guide existing codebase onboarding through mapping, docs ingest, project setup, and onboarding summary. | [commands/gsd/onboard.md](../commands/gsd/onboard.md) |
 | `/gsd-workspace` | Manage GSD workspaces — create (`--new`), list (`--list`), or remove (`--remove`) isolated workspace environments. | [commands/gsd/workspace.md](../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | Gather phase context through adaptive questioning before planning. | [commands/gsd/discuss-phase.md](../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | Plan a phase as a vertical MVP slice — user story, SPIDR splitting, then plan-phase. | [commands/gsd/mvp-phase.md](../commands/gsd/mvp-phase.md) |
@@ -223,6 +224,7 @@ Full roster at `gsd-core/workflows/*.md`. Workflows are thin orchestrators that
 | `milestone-summary.md` | Milestone summary synthesis — onboarding and review artifact from milestone artifacts. | `/gsd-milestone-summary` |
 | `new-milestone.md` | Start a new milestone cycle — load project context, gather goals, update PROJECT.md/STATE.md. | `/gsd-new-milestone` |
 | `new-project.md` | Unified new-project flow — questioning, research (optional), requirements, roadmap. | `/gsd-new-project` |
+| `onboard.md` | Brownfield onboarding orchestration — map codebase, ingest docs, initialize planning, summarize next step. | `/gsd-onboard` |
 | `new-workspace.md` | Create an isolated workspace with repo worktrees/clones and an independent `.planning/`. | `/gsd-workspace --new` |
 | `next.md` | Detect current project state and automatically advance to the next logical step. | `/gsd-progress --next` |
 | `node-repair.md` | Autonomous repair operator for failed task verification; invoked by `execute-plan`. | `execute-plan.md` (recovery) |
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -79,7 +79,7 @@ The core GSD loop is: **discuss → plan → execute → verify → ship**, repe

 See [Your first project](tutorials/your-first-project.md).

-For onboarding an existing codebase before starting a new milestone, see [Onboarding an existing codebase](tutorials/onboarding-an-existing-codebase.md).
+For onboarding an existing codebase before starting a new milestone, run `/gsd-onboard` or see [Onboarding an existing codebase](tutorials/onboarding-an-existing-codebase.md).

 **Relevant flags at a glance:**

@@ -536,11 +536,13 @@ claude --dangerously-skip-permissions
 ### Existing Codebase

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow the printed top-level handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

+`/gsd-onboard` routes through `/gsd-map-codebase`, `/gsd-ingest-docs`, and `/gsd-new-project` without nesting interactive workflows or overwriting existing planning files silently.
+
 **Post-execute drift detection (#2003).** After every `/gsd-execute-phase`, GSD checks whether the phase introduced enough structural change to make `.planning/codebase/STRUCTURE.md` stale. Flip the behavior with:

 ```bash
@@ -986,7 +988,8 @@ To disable parallel execution entirely: `/gsd-settings` → set `parallelization
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/adr/1143-claude-orchestration-capability.md
+++ b/docs/adr/1143-claude-orchestration-capability.md
@@ -86,3 +86,39 @@ These existing multi-model features (`execute-phase` `cross_ai_delegation`, the
 - **Neutral:** no effect on non-Claude runtimes by construction; no behavior change until explicitly enabled.

 > **Governance note:** This ADR is a *draft design* accompanying feature request #1143. Per CONTRIBUTING, it is PR'd only after the issue receives `approved-feature`, and the capability is implemented only after #857 is released.
+
+## Amendment (2026-07-06): BETA v1 implementation landed
+
+#857 is **released** (CLOSED); the capability infrastructure is live. The BETA v1
+of this capability has shipped as `capabilities/claude-orchestration/` with the
+scope agreed in the Decision, refined to the lowest-risk first slice:
+
+- **Detection + emission** live as pure, fail-closed functions in
+  `gsd-core/bin/lib/claude-orchestration.cjs` (source `src/claude-orchestration.cts`):
+  `detectWorkflowBackend` (gate ladder: enabled → Claude runtime →
+  execution_backend ≠ inline → host dispatch nested+background → valid Agent SDK
+  → SDK ≥ `claude_orchestration.min_agent_sdk_version`, default `0.3.149`) and
+  `emitWorkflowScript` (waves → `parallel()` stage barriers, plans →
+  `agent({ agentType: 'gsd-executor', isolation: 'worktree' })`, `files_modified`
+  overlap → separate sequential stages, `resumeFromRunId` wired to the phase run
+  id, shared `budget(tokens)` pool). All interpolated values are validated as
+  script-safe identifiers or JSON-quoted (review Finding 1).
+- **Loop registration** is at the two **wired** points the loop host contract
+  actually renders: `execute:wave:post into:executor` (Workflow-backend guidance)
+  and `plan:post into:planner` (ultraplan ownership declaration). `execute:wave:pre`
+  and `execute:pre` are declared in the contract but **not wired** today, so the
+  capability registers at `wave:post` (the constraint `external-job` also documents).
+- **Config** is federated (`claude_orchestration.enabled` default false /
+  `activationKey`, `execution_backend` enum `auto|workflow|inline` default `auto`,
+  `min_agent_sdk_version`); the keys live only in the registry, so uninstall
+  removes them cleanly.
+- **ultraplan ownership** is declared in the manifest (`plan:post` contribution);
+  full install-profile migration of the `gsd-ultraplan-phase` skill into the
+  capability's `skills[]` is deferred to a follow-up (it triggers the CLUSTERS /
+  profile membership gate and is a heavier, install-machinery change).
+
+Status remains **Proposed** — the BETA is default-off and the end-to-end Workflow
+execution path (actual orchestration via the Workflow tool inside Claude Code) is
+not verifiable outside that runtime. The capability is structurally complete and
+tested at the contract level; flipping to Accepted follows maintainer sign-off on
+the E2E behaviour once exercised on Claude Code with the Workflow tool present.
--- a/docs/adr/1990-existing-code-onboarding.md
+++ b/docs/adr/1990-existing-code-onboarding.md
@@ -0,0 +1,69 @@
+# Existing Code Onboarding Module owns deterministic repo-state detection and onboarding route selection
+
+- **Status:** Proposed
+- **Date:** 2026-07-06
+- **Issue:** #1990
+- **Implementation:** PR #1994
+
+## Context
+
+GSD already ships strong individual primitives for adopting an existing codebase: `/gsd:map-codebase` (parallel codebase analysis), `/gsd:ingest-docs` (classify and consolidate existing ADR/PRD/SPEC/RFC docs), and `/gsd:new-project` (planning initialization). What it lacked was a single guided entry point that inspects a brownfield repository and tells the user *which primitive runs first*.
+
+Left to prose alone, that ordering is ambiguous and unsafe: a user can initialize planning before a codebase map exists, skip relevant design docs, or overwrite/duplicate `.planning/` context instead of reusing it. The ordering is not a matter of taste — it is a **dependency graph** (a map should exist before planning; existing design docs should be ingested before a fresh `/gsd:new-project`; nothing should clobber an in-progress `.planning/`). A dependency graph that decides the next safe action from filesystem state is a *projection*, not something a workflow's natural-language instructions can evaluate reliably or test.
+
+GSD already has the seam for this. The **Init Command Module** (`src/init.cts` → `gsd-core/bin/lib/init.cjs`) owns the `init.*` family of query handlers that compose atomic queries into the flat JSON bundles that init workflows consume, alongside the projection-module precedent set by the **Planning Path Projection Module** (ADR-0006) and the **Shell Command Projection Module** (ADR-0009). Adding `/gsd:onboard` as free-form workflow prose that scans the tree inline would put untested, non-deterministic filesystem logic in markdown — precisely the anti-pattern those projection modules exist to prevent.
+
+## Decision
+
+Introduce the **Existing Code Onboarding Module** (implemented as the `src/onboard-projection.cts` → `gsd-core/bin/lib/onboard-projection.cjs` projection) as the Seam that owns **deterministic detection of brownfield repository state and the selection of the next onboarding action**. It is a pure, side-effect-free projection consumed by the Init Command Module's `initOnboard` handler and rendered by the `/gsd:onboard` workflow. It never writes; detection and route selection are a function of repository state only.
+
+**Detected state (inputs):**
+
+| Signal | Rule / invariant |
+|---|---|
+| Brownfield code present | Depth-capped recursive scan for source files (`hasCodeFilesInternal`) OR a recognized package manifest (`hasPackageFileInternal`). |
+| Generated / vendor exclusion | Scan skips `CODE_SCAN_SKIP_DIRS` (`node_modules`, `dist`, `build`, `.next`, `.nuxt`, `.svelte-kit`, `coverage`, `vendor`, `.venv`, `venv`) so vendored trees never produce a false brownfield positive. |
+| Codebase-map completeness | Whether `.planning/codebase/` holds the canonical map artifacts. |
+| Existing design docs | Presence of ADR/PRD/SPEC/RFC-style candidates (root, nested, and segment-based). |
+| Partial planning state | Whether some but not all of `PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md` / `STATE.md` exist. |
+
+**Route selection (output), ordered by dependency, not by convenience:**
+
+1. Brownfield code without a complete `.planning/codebase/` map → hand off to `/gsd:map-codebase` (or `/gsd:map-codebase --fast` in fast mode).
+2. Design-doc candidates present and no project yet → offer `/gsd:ingest-docs` **before** `/gsd:new-project`.
+3. Otherwise → `/gsd:new-project`.
+
+The gate order is load-bearing: **partial-planning and fast-map-completeness are evaluated before the docs-ingest branch**, so a half-mapped or half-initialized repo is never routed past the step it still owes. Handoff commands are runtime-formatted (`buildHandoffCommands` / `formatGsdSlash`) so the projected next command is correct for the installed runtime's slash syntax.
+
+**Safety invariants (the reason this is a Module, not a helper):**
+
+- **Idempotent / no silent overwrite.** Onboarding never mutates existing tracked `.planning/` artifacts; re-running leaves them byte-unchanged.
+- **`SUMMARY.md` is a trailing artifact.** `.planning/onboarding/SUMMARY.md` is written only *after* project setup exists, and only if absent.
+- **"Complete" is a conjunction.** Onboarding does not report complete until `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist — no single-file short-circuit.
+- **Text-mode parity.** `--text` renders the same gate decisions as numbered plain-text prompts, so runtimes without an interactive picker get identical routing.
+
+## What stays OUTSIDE this Module
+
+- **The primitives themselves.** `/gsd:map-codebase`, `/gsd:ingest-docs`, and `/gsd:new-project` retain their own behavior; the Module only *chooses and orders* them. It projects the route; it does not re-implement the destinations.
+- **Writing planning artifacts.** All `.planning/` writes remain owned by the destination commands and the Installer/planning modules. The projection is read-only.
+- **The workflow's rendering.** `gsd-core/workflows/onboard.md` owns menu/gate presentation; the command `commands/gsd/onboard.md` (and its skill mirror) owns delegation. The Module owns only the state→route decision they consume.
+
+## Consequences
+
+- Brownfield onboarding becomes a single, testable entry point with deterministic routing, rather than order-of-operations folklore in prose. The projection is unit-tested (`tests/onboard-command.test.cjs`) for brownfield/greenfield detection, vendor-dir exclusion, gate ordering (partial-planning before docs-ingest), idempotency/no-mutation, and runtime-formatted handoffs.
+- The Init Command Module gains one more heavyweight handler (`initOnboard`) with the same `{ data: <flat JSON> }` contract as its siblings — no new dispatch shape.
+- **New maintenance coupling, now explicit.** The Module's completeness checks must track the canonical `.planning/codebase/` artifact list and the routing targets' identities; if `/gsd:map-codebase` / `/gsd:ingest-docs` / `/gsd:new-project` change their entry contracts, this projection must follow. This ADR records that coupling as the known cost of centralizing the routing decision (the alternative — duplicating the decision across each primitive — is worse).
+- No new runtime dependencies; no change to existing command semantics (additive).
+
+## Open questions
+
+- Should codebase-map completeness be sourced from a single shared predicate (owned by the map module) rather than re-encoded here, so the two cannot drift?
+- The `/gsd:onboard` workflow sources its `gsd_run` bootstrap from a shared `references/gsd-run-resolver.md` snippet rather than inlining it. If that delegation pattern is adopted by other workflows, it likely deserves its own short ADR — noting it here so the precedent is visible rather than silently established.
+
+## References
+
+- ADR-0006 — Planning Path Projection Module (projection-module precedent for `.planning` path resolution).
+- ADR-0009 — Shell Command Projection Module (runtime-aware projection precedent).
+- Init Command Module (`src/init.cts` → `gsd-core/bin/lib/init.cjs`) — owner of the `init.*` handler family that consumes this projection via `initOnboard`.
+- `CONTEXT.md` § Init Command Module — where the onboarding projection is registered.
+- Issue #1990 — feature spec and acceptance criteria.
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -64,6 +64,7 @@ See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#prop
 | [1769-state-md-transition-module.md](1769-state-md-transition-module.md) | STATE.md Transition Module — intent-based transitions over scattered RMW callbacks | Proposed |
 | [1817-state-md-rebuild-derivability-contract.md](1817-state-md-rebuild-derivability-contract.md) | STATE.md rebuild — derivability contract (capstone 11th transition) | Accepted |
 | [2008-command-exit-zero-gate.md](2008-command-exit-zero-gate.md) | Generic gate-predicate evaluator with a `command-exit-zero` kind (#2008) | Accepted |
+| [1990-existing-code-onboarding.md](1990-existing-code-onboarding.md) | Existing Code Onboarding Module owns deterministic repo-state detection and onboarding route selection | Proposed |

 ## Seam map

--- a/docs/explanation/claude-orchestration-capability.md
+++ b/docs/explanation/claude-orchestration-capability.md
@@ -0,0 +1,94 @@
+# Claude orchestration capability (BETA)
+
+> **Explanation** — *why this capability exists and how it fits the loop.* For the
+> step-by-step, see the [capability reference](../reference/capability-matrix.md);
+> for the design record, see [ADR-1143](../adr/1143-claude-orchestration-capability.md).
+
+## The problem
+
+GSD's `execute-phase` is wave-based: plans carry a wave number, waves run
+sequentially, and plans *within* a wave run in parallel when their
+`files_modified` sets don't overlap. On most runtimes GSD realizes that by
+fanning out one backgrounded `gsd-executor` agent (in a worktree) per plan.
+
+On **Claude Code** that fan-out degrades. Backgrounded agents on Claude Code have
+no `Agent`/`Task` tool, so they cannot nest subagents ([#853]). The autonomous
+loop therefore falls back to **inline sequential execution** — and with it
+silently drops wave parallelism, the plan-checker, and the verifier — on the one
+runtime most GSD users run.
+
+Claude Code ships an orchestration primitive that sidesteps exactly this: the
+**Workflow tool** (the engine behind `/effort ultracode`, Agent SDK ≥ v0.3.149).
+A Workflow script *is* the orchestrator — it runs from the main loop and spawns
+subagents itself via `agent()`, `parallel()` (barrier), `pipeline()`, and
+`phase()`, with `isolation: 'worktree'`, a shared token `budget`, and
+`resumeFromRunId`.
+
+## The capability
+
+`claude-orchestration` is a **default-off, BETA, claude-only** capability that
+adopts the Workflow tool as an optional, runtime-gated parallel-execution
+backend, and folds the existing `gsd-ultraplan-phase` plan-offload under the same
+gate. It is blocked-on-nothing now that the ADR-857 capability system is released.
+
+- **`role: feature`**, `runtimeCompat.supported: ["claude"]`, `tier: full`.
+- **`activationKey: claude_orchestration.enabled`** — default `false`. Nothing
+  changes until you opt in.
+- Registers at two **wired** loop points: `execute:wave:post` (into the executor)
+  and `plan:post` (into the planner). Both are `onError: skip` and gated by the
+  `enabled` key.
+
+## How it decides whether to activate
+
+Detection is a pure, **fail-closed** function — `detectWorkflowBackend`. The
+Workflow backend activates only when *every* gate passes; any miss degrades to
+`inline` (today's behaviour):
+
+1. `claude_orchestration.enabled` is true.
+2. The runtime is Claude (the Workflow tool is Claude / Agent SDK-specific).
+3. `claude_orchestration.execution_backend` is `auto` or `workflow` (not `inline`).
+4. The host descriptor advertises `dispatch.nested` **and** `dispatch.background`
+   (the nesting-capable Claude-Code shape — a proxy for Workflow-tool presence,
+   meaningful only after gate 2).
+5. The Agent SDK reports a valid semver version.
+6. That version is `>= claude_orchestration.min_agent_sdk_version`
+   (default `0.3.149`). A pre-release of the floor (e.g. `0.3.149-rc.1`) compares
+   *below* the GA release per SemVer, so the preview backend stays off.
+
+## What the executor runs when the backend is active
+
+`emitWorkflowScript` maps the phase's wave/plan model onto Workflow primitives:
+
+| GSD concept | Workflow primitive |
+|---|---|
+| Wave | `parallel()` stage barrier |
+| Plan | `agent(brief, { agentType: 'gsd-executor', isolation: 'worktree' })` |
+| `files_modified` overlap | forces the plans into separate sequential stages |
+| Phase run id | `resumeFromRunId("<id>")` |
+| Phase token cap | `budget(<tokens>)` |
+
+Because the emitted script composes the **same** `gsd-executor` agent and
+**worktree isolation** the inline path uses, it produces the same `SUMMARY.md`
+artifacts and commits — the only difference is the execution vehicle.
+
+## The fallback contract
+
+On any runtime lacking the Workflow tool — or when the capability is disabled,
+the SDK is too old, or detection fails for any reason — execute-phase proceeds
+with the standard inline wave dispatch. This is a release gate, not a nicety: a
+regression test asserts the inline fallback on every non-capable combination, so
+the capability is default-off and low-risk by construction.
+
+## BETA scope (v1)
+
+The first slice ships **detection + emission + declarative ultraplan ownership**.
+The emitter is exercised at the contract level (structure, overlap splitting,
+resume, budget, anti-injection). End-to-end execution through the Workflow tool
+is verifiable only inside Claude Code with the tool present. Full install-profile
+migration of the `gsd-ultraplan-phase` skill into the capability's `skills[]`
+array is a follow-up (it touches the cluster/profile machinery); for v1 the
+manifest *declares* ultraplan ownership at `plan:post` and the existing skill's
+own runtime gate continues to no-op on non-Claude runtimes.
+
+[#853]: https://github.com/open-gsd/gsd-core/issues/853
+[#1143]: https://github.com/open-gsd/gsd-core/issues/1143
--- a/docs/how-to/enable-claude-orchestration-workflow-backend.md
+++ b/docs/how-to/enable-claude-orchestration-workflow-backend.md
@@ -0,0 +1,171 @@
+# How to enable and use the Claude orchestration backend (BETA)
+
+Run GSD's execute-phase waves through Claude Code's Workflow tool (`/effort ultracode`, Agent SDK ≥ v0.3.149) instead of the default one-agent-per-message dispatch, and fold the `gsd-ultraplan-phase` plan-offload under the same gate. On Claude Code this restores the wave parallelism that backgrounded-agent nesting (#853) otherwise forces inline.
+
+> **BETA.** This capability tracks a Claude Code preview surface. It is default-off, fail-closed, and Claude-only. Every detection miss degrades silently to today's inline behaviour — enabling it can never break the loop. See the [explanation doc](../explanation/claude-orchestration-capability.md) for the why, and [ADR-1143](../adr/1143-claude-orchestration-capability.md) for the design.
+
+**What you need:**
+- GSD installed with the `full` profile (the capability is `tier: full`).
+- **Claude Code** with the Workflow tool available (Agent SDK ≥ `0.3.149`). On any other runtime the capability is an explicit no-op — you can flip the switch safely, nothing happens.
+- A GSD project with at least one planned phase (you need a wave/plan manifest to emit a script for).
+
+---
+
+## Step 1 — Enable the capability
+
+The capability ships disabled. Turn on the master switch inside your GSD project:
+
+```bash
+gsd-tools query config-set claude_orchestration.enabled true
+```
+
+That single key gates everything — both the Workflow-backend hook at `execute:wave:post` and the ultraplan ownership declaration at `plan:post`. All other `claude_orchestration.*` keys are optional refinements.
+
+Verify it took:
+
+```bash
+gsd-tools query config-get claude_orchestration.enabled
+# → true
+```
+
+---
+
+## Step 2 — Check whether your runtime qualifies
+
+Detection is fail-closed: the Workflow backend activates only when **every** gate opens. Before relying on it, confirm your runtime reports as capable:
+
+```bash
+gsd-tools claude-orchestration detect-backend \
+  --runtime claude \
+  --agent-sdk-version 1.2.0
+```
+
+You will get one of two results:
+
+| `backend` | `available` | Meaning |
+|-----------|-------------|---------|
+| `workflow` | `true` | Every gate passed — the emitter will produce a Workflow script the orchestrator can run. |
+| `inline` | `false` | A gate failed. The `reason` field tells you which: `capability_disabled`, `runtime_not_claude`, `backend_inline`, `workflow_tool_unavailable`, `agent_sdk_version_unknown`, or `agent_sdk_version_below_floor`. |
+
+> **The CLI is a simulation harness, not a probe.** `detect-backend` assumes a capable host descriptor unless you pass `--no-nested-dispatch`. It exists so you (and the orchestrator) can ask "given these facts, would the backend activate?" The real detection the loop uses is the pure `detectWorkflowBackend` function, called with the live host descriptor.
+
+### If detection returns `inline`
+
+Work through the `reason`:
+
+- **`runtime_not_claude`** — you are on Codex / Cursor / opencode / etc. The Workflow tool is Claude-specific; there is nothing to enable here. Your loop is unchanged.
+- **`agent_sdk_version_below_floor`** — upgrade Claude Code / the Agent SDK to at least `claude_orchestration.min_agent_sdk_version` (default `0.3.149`). A pre-release of the floor (e.g. `0.3.149-rc.1`) compares *below* the GA release and will not activate.
+- **`workflow_tool_unavailable`** — your host descriptor does not advertise nested + background dispatch. This is unusual on Claude Code; if you see it, the Workflow tool is not present in this session.
+- **`agent_sdk_version_unknown`** — the version could not be determined. Supply it explicitly via `--agent-sdk-version`.
+
+### Pin a higher floor (optional)
+
+If you want to gate the BETA behind a newer Agent SDK than the default:
+
+```bash
+gsd-tools query config-set claude_orchestration.min_agent_sdk_version 1.0.0
+```
+
+---
+
+## Step 3 — Choose the execution backend
+
+`claude_orchestration.execution_backend` controls how aggressively the backend is used once detection passes:
+
+| Value | Behaviour |
+|-------|-----------|
+| `auto` (default) | Use the Workflow backend **if** detection passes; otherwise inline. The safe, recommended value. |
+| `workflow` | Force the Workflow backend when the tool is present (still fails closed to inline if the tool is absent or the SDK is too old — the floor applies in both modes). |
+| `inline` | Force today's manual one-agent-per-message dispatch, even on a capable Claude Code runtime. Use this to A/B compare or to temporarily retire the BETA. |
+
+Switch with:
+
+```bash
+gsd-tools query config-set claude_orchestration.execution_backend workflow
+```
+
+---
+
+## Step 4 — Emit a Workflow script for a phase
+
+With the capability enabled and detection passing, generate the Workflow script for a phase's wave/plan manifest. The manifest is the wave/plan model execute-phase already builds:
+
+```json
+{
+  "waves": [
+    {
+      "id": "w1",
+      "plans": [
+        { "id": "p1", "brief": "Implement the foo module", "files_modified": ["src/foo.cts"] },
+        { "id": "p2", "brief": "Wire the bar seam", "files_modified": ["src/bar.cts"] }
+      ]
+    }
+  ]
+}
+```
+
+Emit the script:
+
+```bash
+gsd-tools claude-orchestration emit-workflow \
+  --waves .planning/phases/01-foo/waves.json \
+  --run-id phase-01-foo \
+  --phase-dir .planning/phases/01-foo \
+  --budget 500000
+```
+
+The output is a generated Workflow script that maps GSD's model 1:1 onto Workflow primitives:
+
+- **waves → sequential `parallel()` barriers** (split into separate stages within a wave when `files_modified` overlap),
+- **plans → `agent(brief, { agentType: "gsd-executor", isolation: "worktree" })`** — the **same** executor agent and worktree isolation the inline path uses,
+- **`resumeFromRunId("<run-id>")`** wired to the phase run id,
+- **`budget(<tokens>)`** — a shared token pool across the whole phase (omit `--budget` to skip).
+
+Because the script composes the same `gsd-executor` agent + worktree isolation + `SUMMARY.md` artifact as the inline path, the artifacts and commits it produces are identical — only the execution vehicle differs.
+
+### Run the emitted script
+
+Feed the emitted script to Claude Code's Workflow tool (`/effort ultracode`, or an Agent SDK `Workflow` invocation). The orchestrator runs it; each `agent()` call spawns a `gsd-executor` in its own worktree, waves barrier between each other, and `resumeFromRunId` lets an interrupted phase resume without re-running completed plans.
+
+---
+
+## Step 5 — Ultraplan plan-offload
+
+Enabling the capability also folds `gsd-ultraplan-phase` under the same runtime gate. When the capability is on, the planner may offer the `/gsd-ultraplan-phase` path (offload plan-phase to Claude Code's ultraplan cloud) as an alternative to local `/gsd-plan-phase`. This is advisory — the stable local planner remains the default.
+
+If the capability is off, or the runtime is not Claude Code, ultraplan offload is not surfaced and `/gsd-plan-phase` runs as normal.
+
+---
+
+## Disabling
+
+To turn the capability off and return to byte-identical inline behaviour:
+
+```bash
+gsd-tools query config-set claude_orchestration.enabled false
+```
+
+Or force inline dispatch while leaving the capability otherwise on:
+
+```bash
+gsd-tools query config-set claude_orchestration.execution_backend inline
+```
+
+Either step is sufficient — no uninstall or resurface needed. The federated config keys live only in the capability registry, so they vanish cleanly if the capability is ever removed.
+
+---
+
+## What is and is not wired in BETA v1
+
+**Working today:**
+- Detection (`detectWorkflowBackend` / `gsd-tools claude-orchestration detect-backend`) — fail-closed, tested across every gate.
+- Emission (`emitWorkflowScript` / `gsd-tools claude-orchestration emit-workflow`) — waves→barriers, overlap→stages, resume, budget, anti-injection.
+- The contribution fragments at `execute:wave:post` and `plan:post` (gated, `onError: skip`).
+- Inline fallback on every non-capable combination (regression-tested).
+
+**Not yet wired (follow-ups):**
+- `execute-phase.md` does not yet auto-branch to emit-and-run the Workflow script. Today you emit the script explicitly (Step 4) and run it via the Workflow tool. Automatic dispatch inside the loop is the next milestone.
+- The plan-checker and verifier still run inline — this capability delivers the parallel-execution backend, not those gates.
+- Full install-profile migration of the `gsd-ultraplan-phase` skill into the capability's `skills[]` (it is currently declared in the manifest; the skill's own runtime gate continues to no-op on non-Claude runtimes).
+
+If a preview-API change breaks detection, the capability degrades to inline; it cannot destabilise the core loop.
--- a/docs/how-to/fix-worktree-base-mismatch.md
+++ b/docs/how-to/fix-worktree-base-mismatch.md
@@ -1,16 +1,16 @@
 # How to fix the worktree base-mismatch (exit 42) error

-**Goal:** Understand why `/gsd-execute-phase` halts with `FATAL: worktree base mismatch` / exit 42 when your branch is ahead of the default branch, and choose the right fix to restore normal — or parallel — execution.
+**Goal:** Understand why `/gsd-execute-phase` or `/gsd-quick` halts with `FATAL: worktree base mismatch` / exit 42 when your branch is ahead of the default branch, and choose the right fix to restore normal — or parallel — execution.

-**Prerequisites:** GSD Core is installed and you have an active project. You have run `/gsd-execute-phase` and either seen the exit-42 error or the one-line `⚠ Worktree base mismatch` warning.
+**Prerequisites:** GSD Core is installed and you have an active project. You have run `/gsd-execute-phase` or `/gsd-quick` and either seen the exit-42 error or the one-line `⚠ Worktree base mismatch` warning.

 ---

 ## What you will see

-When you run `/gsd-execute-phase` on a branch that is ahead of the repository's default branch (for example, an unmerged milestone branch, a long-lived feature branch, or a branch with commits not yet in `origin/HEAD`), you may see one of two messages:
+When you run `/gsd-execute-phase` or `/gsd-quick` on a branch that is ahead of the repository's default branch (for example, an unmerged milestone branch, a long-lived feature branch, or a branch with commits not yet in `origin/HEAD`), you may see one of two messages:

-**Automatic-degrade warning (phase still completes):**
+**Automatic-degrade warning (phase or quick task still completes):**

 ```
 ⚠ Worktree base mismatch: HEAD (abc12345) differs from origin/HEAD (def67890).
@@ -19,7 +19,7 @@ To keep parallel worktrees, set worktree.baseRef:"head" in
 .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.
 ```

-The phase runs to completion sequentially; nothing is blocked. This is the runtime mitigation.
+The phase or quick task runs to completion sequentially; nothing is blocked. This is the runtime mitigation (`/gsd-execute-phase`: #683/#1369; `/gsd-quick`: #1941).

 **Exit-42 halt (older installs or misconfigured environments):**

--- a/docs/how-to/install-minimal-and-add-skills.md
+++ b/docs/how-to/install-minimal-and-add-skills.md
@@ -45,7 +45,7 @@ If `core` is too small, pick a wider profile instead. Pass it with `--profile=<n
 | Profile | What you get | Approx. description tokens |
 |---------|--------------|--------------------------|
 | `core` | The eight core-loop skills above. No agents. | ~130 desc tokens |
-| `standard` | Everything in `core` plus common management skills — `review`, `config`, `progress`, `resume-work`, `pause-work`, `workspace` — and the sub-agents those skills need. | ~700 desc tokens |
+| `standard` | Everything in `core` plus brownfield onboarding (`onboard`), common management skills — `review`, `config`, `progress`, `resume-work`, `pause-work`, `workspace` — and the sub-agents those skills need. | ~700 desc tokens |
 | `full` | Every skill and every sub-agent. This is the default when you pass no profile flag. | ~1,200 desc tokens |

 ```bash
--- a/docs/how-to/install-on-your-runtime.md
+++ b/docs/how-to/install-on-your-runtime.md
@@ -465,10 +465,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## After install

-Restart your runtime to pick up new commands and agents. Then start your first project:
+Restart your runtime to pick up new commands and agents. Then start a new project or onboard an existing repo:

 ```bash
-/gsd-new-project
+/gsd-new-project   # greenfield project
+/gsd-onboard       # existing codebase
 ```

 If the command is not found after restart, verify the install directory matches the runtime's expected config path. The prerelease-editions section above covers the most common mismatch.
--- a/docs/ja-JP/ARCHITECTURE.md
+++ b/docs/ja-JP/ARCHITECTURE.md
@@ -474,7 +474,8 @@ UI-SPEC.md (per phase) ───────────────────
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # ブラウンフィールドマッピング（/gsd-map-codebase から）
+├── codebase/               # ブラウンフィールドマッピング（/gsd-map-codebase または /gsd-onboard から）
+├── onboarding/             # ブラウンフィールドオンボーディング概要（/gsd-onboard から）
 │   ├── STACK.md
 │   ├── ARCHITECTURE.md
 │   ├── CONVENTIONS.md
--- a/docs/ja-JP/CLI-TOOLS.md
+++ b/docs/ja-JP/CLI-TOOLS.md
@@ -288,13 +288,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Init コマンド（複合コンテキスト読み込み）

-特定のワークフローに必要なすべてのコンテキストを一度に読み込みます。プロジェクト情報、設定、状態、ワークフロー固有のデータを含む JSON を返します。
+特定のワークフローに必要なすべてのコンテキストを一度に読み込みます。プロジェクト情報、設定、状態、ワークフロー固有のデータを含む JSON を返します。`init onboard [--fast] [--text]` は `/gsd-onboard` 用に、brownfield シグナル、計画ドキュメント候補、コードベースマップの完全性、fast マップの準備状況、テキストモードルーティング、部分的な planning 状態、オンボーディングサマリー状態を返します。

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/ja-JP/COMMANDS.md
+++ b/docs/ja-JP/COMMANDS.md
@@ -51,6 +51,25 @@ v1.40 では、最初のステージエントリーポイントとして6つの

 ---

+### `/gsd-onboard`
+
+既存コードベースの初回 GSD オンボーディングを案内します。リポジトリ状態を確認し、コードベースマッピング、任意のドキュメント取り込み、プロジェクト初期化へ安全にハンドオフし、計画が揃った後にオンボーディング summary を作成します。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--fast` | 軽量な `/gsd-map-codebase --fast` マッピングハンドオフを優先。ただし `/gsd-new-project` 前には完全なマップが必要 |
+| `--text` | TUI メニューではなく番号付きプレーンテキストのゲートを使用 |
+
+**前提条件:** 既存リポジトリまたは計画ドキュメント。空のグリーンフィールドプロジェクトには `/gsd-new-project` を使用します。
+**生成物:** map-codebase による `.planning/codebase/`、new-project または ingest-docs による `.planning/`、セットアップ後の `.planning/onboarding/SUMMARY.md`。
+
+```bash
+/gsd-onboard           # ガイド付き brownfield オンボーディング
+/gsd-onboard --fast    # 先に軽量マップを使い、その後プロジェクト設定前に完全マップを作成
+```
+
+---
+
 ### `/gsd-workspace`

 GSD ワークスペースを管理 — リポジトリコピーと独立した `.planning/` ディレクトリを持つ隔離されたワークスペース環境を作成、一覧表示、または削除します。
--- a/docs/ja-JP/FEATURES.md
+++ b/docs/ja-JP/FEATURES.md
@@ -38,6 +38,7 @@
  - [モデルプロファイル](#26-モデルプロファイル)
 - [ブラウンフィールド機能](#ブラウンフィールド機能)
  - [コードベースマッピング](#27-コードベースマッピング)
+  - [既存コードベースオンボーディング](#27b-既存コードベースオンボーディング)
 - [ユーティリティ機能](#ユーティリティ機能)
  - [デバッグシステム](#28-デバッグシステム)
  - [Todo 管理](#29-todo-管理)
@@ -781,7 +782,7 @@

 **コマンド:** `/gsd-map-codebase [area]`

-**目的:** 新しいプロジェクトを開始する前に既存のコードベースを分析し、GSD が既存の構成を理解できるようにします。
+**目的:** 新しいプロジェクトを開始する前、または `/gsd-onboard` からのマッピングハンドオフとして既存のコードベースを分析し、GSD が既存の構成を理解できるようにします。

 **要件:**
 - REQ-MAP-01: システムは各分析領域に対して並列マッパーエージェントを起動しなければならない
@@ -805,6 +806,27 @@
 `--paths <p1,p2,...>` スコープヒントを受け付けます。指定した場合、ツリー全体をスキャンする代わりに、リストされたリポジトリ相対プレフィックスに探索を制限します。
 これはフェーズが実際に変更したサブツリーのみを更新するために、実行後コードベースドリフトゲートが使用するパスウェイです。各生成ドキュメントはその YAML フロントマターに `last_mapped_commit` を持ち、ドリフトを HEAD ではなくマッピング時点と照らし合わせて計測できます。

+### 27b. 既存コードベースオンボーディング
+
+**コマンド:** `/gsd-onboard [--fast] [--text]`
+
+**目的:** 既存リポジトリの初回セットアップを案内し、brownfield 状態を確認してコードベースマッピング、docs 取り込み、プロジェクト初期化へ安全にハンドオフします。
+
+**要件:**
+- REQ-ONBOARD-01: 既存コード、package manifest、計画ドキュメント、部分的な `.planning/`、コードベースマップの不足を検出する。
+- REQ-ONBOARD-02: 必要な `.planning/codebase/` マップファイルがない brownfield では `/gsd-map-codebase` または `/gsd-map-codebase --fast` へハンドオフする。fast マップの readiness は部分的であり、`/gsd-new-project` に十分として扱ってはならない。
+- REQ-ONBOARD-03: ADR/PRD/SPEC/RFC 候補があり project がない場合、`/gsd-new-project` の前に `/gsd-ingest-docs` を提示する。
+- REQ-ONBOARD-04: `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md` が揃うまで完了扱いにしない。
+- REQ-ONBOARD-05: project setup 後にのみ `.planning/onboarding/SUMMARY.md` を作成または確認する。
+- REQ-ONBOARD-06: 対話型メニューがない runtime 向けに、`--text` で番号付きプレーンテキスト gate をサポートする。
+
+**生成物:**
+| Artifact | 説明 |
+|----------|-------------|
+| `.planning/codebase/` | `/gsd-map-codebase` handoff が生成するコードベースマップ |
+| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | `/gsd-new-project` または `/gsd-ingest-docs` が生成する planning setup |
+| `.planning/onboarding/SUMMARY.md` | Onboarding status、artifact index、next-command summary |
+
 ### 27a. 実行後コードベースドリフト検出

 **導入:** #2003
--- a/docs/ja-JP/INVENTORY.md
+++ b/docs/ja-JP/INVENTORY.md
@@ -78,6 +78,7 @@
 | コマンド | 役割 | ソース |
 |----------|------|--------|
 | `/gsd-new-project` | 深いコンテキスト収集と PROJECT.md で新しいプロジェクトを初期化。 | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-onboard` | 既存コードベースをマッピング、ドキュメント取り込み、プロジェクト設定、onboarding summary へ案内。 | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
 | `/gsd-workspace` | GSD ワークスペースを管理 — 独立したワークスペース環境を作成（`--new`）、一覧表示（`--list`）、削除（`--remove`）。 | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | 計画前にアダプティブな質問でフェーズコンテキストを収集。 | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | フェーズを垂直 MVP スライスとして計画 — ユーザーストーリー、SPIDR 分割、その後 plan-phase。 | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
@@ -218,6 +219,7 @@
 | `milestone-summary.md` | マイルストーンサマリー合成 — マイルストーンアーティファクトからオンボーディングとレビューアーティファクトを作成。 | `/gsd-milestone-summary` |
 | `new-milestone.md` | 新しいマイルストーンサイクルを開始 — プロジェクトコンテキストを読み込み、目標を収集して PROJECT.md/STATE.md を更新。 | `/gsd-new-milestone` |
 | `new-project.md` | 統合新プロジェクトフロー — 質問、調査（任意）、要件、ロードマップ。 | `/gsd-new-project` |
+| `onboard.md` | Brownfield onboarding orchestration — コードベースをマップし、docs を取り込み、planning を初期化し、次のステップを要約。 | `/gsd-onboard` |
 | `new-workspace.md` | リポジトリのワークツリー/クローンと独立した `.planning/` を持つ独立したワークスペースを作成。 | `/gsd-workspace --new` |
 | `next.md` | 現在のプロジェクト状態を検出して次の論理的なステップに自動的に進む。 | `/gsd-progress --next` |
 | `node-repair.md` | タスク検証が失敗した場合の自律修復オペレーター。`execute-plan` から呼び出し。 | `execute-plan.md` (recovery) |
--- a/docs/ja-JP/USER-GUIDE.md
+++ b/docs/ja-JP/USER-GUIDE.md
@@ -474,8 +474,8 @@ claude --dangerously-skip-permissions
 ### 既存のコードベース

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow printed handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

@@ -864,7 +864,8 @@ All subagent/executor commits MUST use `--no-verify`.
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/ja-JP/how-to/install-on-your-runtime.md
+++ b/docs/ja-JP/how-to/install-on-your-runtime.md
@@ -273,10 +273,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## インストール後の作業

-新しいコマンドとエージェントを反映するためにランタイムを再起動してください。その後、最初のプロジェクトを開始します。
+新しいコマンドとエージェントを反映するためにランタイムを再起動してください。その後、新規プロジェクトを開始するか既存リポジトリをオンボーディングします。

 ```bash
-/gsd-new-project
+/gsd-new-project   # グリーンフィールドプロジェクト
+/gsd-onboard       # 既存コードベース
 ```

 再起動後もコマンドが見つからない場合は、インストールディレクトリがランタイムの期待する設定パスと一致しているか確認してください。最もよくある不一致については上記のプレリリースエディションのセクションを参照してください。
--- a/docs/ja-JP/reference/planning-artifacts.md
+++ b/docs/ja-JP/reference/planning-artifacts.md
@@ -23,6 +23,8 @@
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # ブラウンフィールドオンボーディング概要（オプション）
+│   └── SUMMARY.md
 ├── intel/                              # クエリ可能なシンボルインデックス（オプション、intel.enabled）
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@
 | | |
 |---|---|
 | **用途** | プロジェクトの正規アイデンティティ: 概要、対象ユーザー、コアバリュー、要件、制約、主要な意思決定。プロダクトの進化に伴いプロジェクトライフサイクル全体を通じて更新されます。 |
-| **生成元** | `/gsd-new-project`（初回作成）; 意思決定が検証されると `/gsd-complete-milestone` によって更新されます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; 意思決定が検証されると `/gsd-complete-milestone` によって更新されます。 |
 | **参照先** | すべてのプランニングワークフロー; `gsd-phase-researcher`、`gsd-planner`（コンテキスト）; `discuss-phase`（過去の意思決定）; `gsd-plan-checker`（プロジェクト制約）。 |

 ### `ROADMAP.md`
@@ -56,7 +58,7 @@
 | | |
 |---|---|
 | **用途** | マイルストーンおよびフェーズ一覧。ゴール、要件 ID、成功基準、フェーズごとの正規リファレンスを含みます。プロジェクトが何をどの順序で構築するかに関する唯一の信頼できる情報源です。 |
-| **生成元** | `/gsd-new-project`（初回作成）; `/gsd-phase --insert` および `/gsd-complete-milestone` によって更新されます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; `/gsd-phase --insert` および `/gsd-complete-milestone` によって更新されます。 |
 | **参照先** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`; フェーズ情報を必要とするすべてのオーケストレーションコマンド; `gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |

 ### `REQUIREMENTS.md`
@@ -64,7 +66,7 @@
 | | |
 |---|---|
 | **用途** | 番号付きのチェック可能な受け入れ基準。各要件はロードマップフェーズにマッピングされる ID（例: `AUTH-01`）を持ちます。フェーズが実行されると要件を完了済みとしてマークします。 |
-| **生成元** | `/gsd-new-project`（初回作成）; `execute-phase` によって要件が完了済みとしてマークされます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; `execute-phase` によって要件が完了済みとしてマークされます。 |
 | **参照先** | `gsd-planner`（プランはすべてのフェーズ要件 ID に対処しなければならない）; `gsd-plan-checker` ディメンション1（要件カバレッジ）; `discuss-phase`（過去の要件）。 |

 ### `STATE.md`
@@ -72,7 +74,7 @@
 | | |
 |---|---|
 | **用途** | 現在地を追跡するリビングドキュメント — 現在のフェーズとプラン、進捗指標、蓄積された意思決定、セッション継続性ノート。すべてのワークフロー実行の開始時に読み込まれます。重要なアクションのたびに更新されます。 |
-| **生成元** | `/gsd-new-project`（初回作成）; すべてのフェーズワークフロー、`/gsd-pause-work`、`/gsd-resume-work` によって継続的に更新されます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; すべてのフェーズワークフロー、`/gsd-pause-work`、`/gsd-resume-work` によって継続的に更新されます。 |
 | **参照先** | すべてのオーケストレーションワークフロー; `/gsd-progress`; `/gsd-quick` 経由のアドホックタスク実行; `gsd-planner` および `gsd-phase-researcher`（プロジェクトの意思決定）。 |

 完全なフィールドリファレンスは [STATE.md スキーマ](state-md.md) を参照してください。
@@ -87,6 +89,14 @@

 完全なスキーマは [CONFIGURATION](../../CONFIGURATION.md) を参照してください。

+### `onboarding/SUMMARY.md`（オプション）
+
+| | |
+|---|---|
+| **用途** | ブラウンフィールドオンボーディングの索引。アーティファクト状態、コードベースマッピングの完了状況、初回セットアップ後に推奨される次の GSD コマンドを記録します。 |
+| **生成元** | `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md` がすべて存在した後の `/gsd-onboard`。 |
+| **参照先** | 初回セットアップを確認する人間、および既存オンボーディング状態を確認する今後の `/gsd-onboard` 実行。 |
+
 ### `MILESTONES.md`（オプション）

 | | |
--- a/docs/ja-JP/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/ja-JP/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,15 @@ claude --dangerously-skip-permissions

 ---

-## ステップ 3 — コードベースのマッピング
+## ステップ 3 — Brownfield オンボーディングの開始

-プロジェクトを作成する前に、GSD Core に既存のコードを学習させてください。これがブラウンフィールドの計画を正確にするステップです。
+プロジェクトを作成する前に、GSD Core にリポジトリ状態を確認させ、安全な次のトップレベルコマンドを表示させます。これにより、コードベースコンテキストの取りこぼしや既存 planning ファイルの上書きを防げます。

 ```text
-/gsd-map-codebase
+/gsd-onboard
 ```

-GSD Core が4つの並行マッパーサブエージェントを生成します（「Spawning 4 parallel codebase mapper agents…」という通知が表示されます。1〜5分かかりますので中断しないでください）。各エージェントはそれぞれ異なる観点に注目します:
+オンボーディングがコードベースマップ不足を示したら、推奨オプションを選び、表示された `/gsd-map-codebase` ハンドオフを実行してから `/gsd-onboard` を再実行します。`/gsd-onboard --fast` は軽量な初回パスには使えますが、`/gsd-new-project` の前には完全なマップが必要です。`/gsd-map-codebase` が4つの並行マッパーサブエージェントを生成します（「Spawning 4 parallel codebase mapper agents…」という通知が表示されます。1〜5分かかりますので中断しないでください）。各エージェントはそれぞれ異なる観点に注目します:

 | エージェント | 観点 |
 |-------|-------|
@@ -84,7 +84,7 @@ Created .planning/codebase/:

 ---

-## ステップ 4 — コンテキストをクリアしてプロジェクトを作成
+## ステップ 4 — オンボーディングを再実行してプロジェクトを初期化する

 セッションウィンドウをクリアします:

@@ -92,12 +92,14 @@ Created .planning/codebase/:
 /clear
 ```

-プロジェクトを作成します。前のステップで GSD Core が既存のコードを見つけているため、これがブラウンフィールドプロジェクトであることをすでに把握しています。`/gsd-new-project` を実行すると、既存のものを再説明するのではなく、*追加する*内容に焦点を当てた質問がされます:
+`/gsd-onboard` をもう一度実行します。GSD Core が ADR、PRD、spec、RFC、またはルートレベルの要件ドキュメントを検出した場合は、先に推奨される `/gsd-ingest-docs` ハンドオフを実行し、その後 `/gsd-onboard` を再実行してください。コンテキストが整うと、オンボーディングはプロジェクト初期化のハンドオフを表示します:

 ```text
 /gsd-new-project
 ```

+前のステップで GSD Core が既存のコードを見つけているため、`/gsd-new-project` はこれがブラウンフィールドプロジェクトだと分かっています。質問は既存のものを再説明するのではなく、*追加する*内容に焦点を当てます:
+
 GSD Core が何を作りたいかを尋ねます。コードベース全体の説明ではなく、追加する機能で答えてください:

 ```text
@@ -124,6 +126,8 @@ Proposed Roadmap

 ロードマップを承認してください。

+プロジェクト設定が完了したら、もう一度 `/gsd-onboard` を実行します。`PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md` がすべて存在するため、オンボーディングは `.planning/onboarding/SUMMARY.md` を作成または確認します。
+
 **`.planning/` に作成されるファイル:**

 ```text
@@ -133,6 +137,7 @@ Proposed Roadmap
  ROADMAP.md          ← フェーズ 1、ステータス: pending
  STATE.md            ← セッションメモリ
  config.json         ← ワークフロー設定
+  onboarding/SUMMARY.md ← オンボーディング状態と次のコマンド
  codebase/           ← ステップ 3 の7つのマップファイル
 ```

@@ -212,6 +217,7 @@ GSD Core があなたの `CONVENTIONS.md` と `ARCHITECTURE.md` を読み込ん

 ## 学んだこと

+- `/gsd-onboard` が対話型コマンドをネストしたり既存 planning ファイルを上書きしたりせずに、ブラウンフィールド設定を安全に順序付ける仕組み。
 - `/gsd-map-codebase` が4つの並行エージェントを実行して `.planning/codebase/` に `STACK.md`、`ARCHITECTURE.md`、`CONVENTIONS.md`、`CONCERNS.md`、`STRUCTURE.md`、`TESTING.md`、`INTEGRATIONS.md` を生成する仕組み。
 - ブラウンフィールドリポジトリで `/gsd-new-project` を実行すると、*追加する*内容に焦点を当てた質問がされ、既存コードから Validated 要件が自動入力される仕組み。
 - コードベースマップが `/gsd-discuss-phase` のすべての質問を形成する方法 — ファイルパス、パターン、規約が実際のコードから導出される。
--- a/docs/ko-KR/ARCHITECTURE.md
+++ b/docs/ko-KR/ARCHITECTURE.md
@@ -512,7 +512,8 @@ UI-SPEC.md (단계별) ───────────────────
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # 브라운필드 매핑 (/gsd-map-codebase에서)
+├── codebase/               # 브라운필드 매핑 (/gsd-map-codebase 또는 /gsd-onboard에서)
+├── onboarding/             # 브라운필드 온보딩 요약 (/gsd-onboard에서)
 │   ├── STACK.md            # YAML 전문에 `last_mapped_commit` 포함
 │   ├── ARCHITECTURE.md     # 실행 후 드리프트 게이트를 위한 (#2003)
 │   ├── CONVENTIONS.md
--- a/docs/ko-KR/CLI-TOOLS.md
+++ b/docs/ko-KR/CLI-TOOLS.md
@@ -288,13 +288,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Init 명령 (복합 컨텍스트 로딩)

-하나의 호출로 특정 워크플로우에 필요한 모든 컨텍스트를 로드합니다. 프로젝트 정보, 설정, 상태, 워크플로우별 데이터가 포함된 JSON을 반환합니다.
+하나의 호출로 특정 워크플로우에 필요한 모든 컨텍스트를 로드합니다. 프로젝트 정보, 설정, 상태, 워크플로우별 데이터가 포함된 JSON을 반환합니다. `init onboard [--fast] [--text]`는 `/gsd-onboard`를 위해 brownfield 신호, 계획 문서 후보, 코드베이스 맵 완성도, fast 맵 준비 상태, 텍스트 모드 라우팅, 부분 planning 상태, 온보딩 요약 상태를 반환합니다.

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/ko-KR/COMMANDS.md
+++ b/docs/ko-KR/COMMANDS.md
@@ -51,6 +51,25 @@ v1.40에서 여섯 개의 네임스페이스 라우터가 1단계 진입점으

 ---

+### `/gsd-onboard`
+
+기존 코드베이스의 최초 GSD 온보딩을 안내합니다. 저장소 상태를 확인하고 코드베이스 매핑, 선택적 문서 수집, 프로젝트 초기화로 안전하게 넘긴 뒤 계획 파일이 준비되면 onboarding summary를 만듭니다.
+
+| 플래그 | 설명 |
+|------|-------------|
+| `--fast` | 경량 `/gsd-map-codebase --fast` 매핑 handoff 우선 사용. 단, `/gsd-new-project` 전에는 완전한 맵이 필요 |
+| `--text` | TUI 메뉴 대신 번호가 있는 plain-text gate 사용 |
+
+**전제 조건:** 기존 저장소 또는 계획 문서. 빈 greenfield 프로젝트는 `/gsd-new-project`를 사용하세요.
+**생성 결과:** map-codebase의 `.planning/codebase/`, new-project 또는 ingest-docs의 `.planning/`, 설정 후 `.planning/onboarding/SUMMARY.md`.
+
+```bash
+/gsd-onboard           # 안내형 brownfield 온보딩
+/gsd-onboard --fast    # 먼저 경량 맵을 사용하고, 프로젝트 설정 전 완전한 맵 작성
+```
+
+---
+
 ### `/gsd-workspace`

 GSD 워크스페이스 관리 — 리포지토리 복사본과 독립적인 `.planning/` 디렉토리를 갖는 격리된 워크스페이스 환경을 생성, 나열, 또는 삭제합니다.
--- a/docs/ko-KR/FEATURES.md
+++ b/docs/ko-KR/FEATURES.md
@@ -38,6 +38,7 @@
  - [모델 프로파일](#26-model-profiles)
 - [브라운필드 기능](#brownfield-features)
  - [코드베이스 매핑](#27-codebase-mapping)
+  - [기존 코드베이스 온보딩](#27b-existing-codebase-onboarding)
 - [유틸리티 기능](#utility-features)
  - [디버그 시스템](#28-debug-system)
  - [할 일 관리](#29-todo-management)
@@ -716,7 +717,7 @@

 **명령어:** `/gsd-map-codebase [area]`

-**목적:** 새 프로젝트를 시작하기 전에 기존 코드베이스를 분석하여 GSD가 무엇이 존재하는지 이해하도록 합니다.
+**목적:** 새 프로젝트 시작 전 또는 `/gsd-onboard`의 매핑 handoff로 기존 코드베이스를 분석하여 GSD가 무엇이 존재하는지 이해하도록 합니다.

 **요구사항.**
 - REQ-MAP-01: 각 분석 영역에 대한 병렬 매퍼 에이전트를 생성해야 합니다.
@@ -736,6 +737,27 @@
 | `TESTING.md` | 테스트 인프라, 커버리지, 패턴 |
 | `INTEGRATIONS.md` | 외부 서비스, API, 서드파티 의존성 |

+### 27b. Existing Codebase Onboarding
+
+**명령어:** `/gsd-onboard [--fast] [--text]`
+
+**목적:** 기존 저장소의 최초 설정을 안내하고 brownfield 상태를 확인해 코드베이스 매핑, docs 수집, 프로젝트 초기화로 안전하게 handoff합니다.
+
+**요구사항.**
+- REQ-ONBOARD-01: 기존 코드, package manifest, planning 문서, 부분 `.planning/` 상태, 코드베이스 맵 누락을 감지해야 합니다.
+- REQ-ONBOARD-02: 필요한 `.planning/codebase/` 맵 파일이 없는 brownfield에서는 `/gsd-map-codebase` 또는 `/gsd-map-codebase --fast`로 handoff해야 합니다. fast 맵 readiness는 부분 상태이며 `/gsd-new-project`에 충분한 것으로 취급해서는 안 됩니다.
+- REQ-ONBOARD-03: ADR/PRD/SPEC/RFC 후보가 있고 project가 없으면 `/gsd-new-project` 전에 `/gsd-ingest-docs`를 제안해야 합니다.
+- REQ-ONBOARD-04: `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`가 모두 있을 때까지 완료로 보고하지 않아야 합니다.
+- REQ-ONBOARD-05: project setup 후에만 `.planning/onboarding/SUMMARY.md`를 만들거나 확인해야 합니다.
+- REQ-ONBOARD-06: 대화형 메뉴가 없는 runtime을 위해 `--text` 번호형 plain-text gate를 지원해야 합니다.
+
+**생성 산출물.**
+| 산출물 | 설명 |
+|----------|-------------|
+| `.planning/codebase/` | `/gsd-map-codebase` handoff가 생성한 코드베이스 맵 |
+| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | `/gsd-new-project` 또는 `/gsd-ingest-docs`가 생성한 planning setup |
+| `.planning/onboarding/SUMMARY.md` | Onboarding status, artifact index, next-command summary |
+
 ---

 ## 유틸리티 기능
--- a/docs/ko-KR/INVENTORY.md
+++ b/docs/ko-KR/INVENTORY.md
@@ -78,6 +78,7 @@
 | 명령어 | 역할 | 소스 |
 |---------|------|--------|
 | `/gsd-new-project` | 심층 컨텍스트 수집 및 PROJECT.md로 새 프로젝트 초기화. | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-onboard` | 기존 코드베이스를 매핑, 문서 수집, 프로젝트 설정, onboarding summary로 안내합니다. | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
 | `/gsd-workspace` | GSD 워크스페이스 관리 — 격리된 워크스페이스 환경을 생성(`--new`), 목록(`--list`), 또는 제거(`--remove`). | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | 계획 전 적응형 질문을 통한 단계 컨텍스트 수집. | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | 수직 MVP 슬라이스로 단계 계획 — 사용자 스토리, SPIDR 분할, 이후 plan-phase. | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
@@ -218,6 +219,7 @@
 | `milestone-summary.md` | 마일스톤 아티팩트에서 온보딩 및 검토용 마일스톤 요약 합성. | `/gsd-milestone-summary` |
 | `new-milestone.md` | 새 마일스톤 사이클 시작 — 프로젝트 컨텍스트 로드, 목표 수집, PROJECT.md/STATE.md 업데이트. | `/gsd-new-milestone` |
 | `new-project.md` | 통합 새 프로젝트 플로우 — 질문, 조사(선택), 요구사항, 로드맵. | `/gsd-new-project` |
+| `onboard.md` | Brownfield 온보딩 오케스트레이션 — 코드베이스 매핑, 문서 수집, planning 초기화, 다음 단계 요약. | `/gsd-onboard` |
 | `new-workspace.md` | 저장소 워크트리/클론과 독립적인 `.planning/`이 포함된 격리된 워크스페이스 생성. | `/gsd-workspace --new` |
 | `next.md` | 현재 프로젝트 상태를 감지하고 다음 논리적 단계로 자동 진행. | `/gsd-progress --next` |
 | `node-repair.md` | 실패한 태스크 검증을 위한 자율 수리 오퍼레이터; `execute-plan`에 의해 호출. | `execute-plan.md` (복구) |
--- a/docs/ko-KR/USER-GUIDE.md
+++ b/docs/ko-KR/USER-GUIDE.md
@@ -474,8 +474,8 @@ claude --dangerously-skip-permissions
 ### 기존 코드베이스

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow printed handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

@@ -864,7 +864,8 @@ All subagent/executor commits MUST use `--no-verify`.
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/ko-KR/how-to/install-on-your-runtime.md
+++ b/docs/ko-KR/how-to/install-on-your-runtime.md
@@ -273,10 +273,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## 설치 후

-새 명령과 에이전트를 적용하려면 런타임을 재시작하세요. 그런 다음 첫 번째 프로젝트를 시작합니다:
+새 명령과 에이전트를 적용하려면 런타임을 재시작하세요. 그런 다음 새 프로젝트를 시작하거나 기존 저장소를 온보딩합니다:

 ```bash
-/gsd-new-project
+/gsd-new-project   # 그린필드 프로젝트
+/gsd-onboard       # 기존 코드베이스
 ```

 재시작 후 명령을 찾을 수 없다면 설치 디렉터리가 런타임이 기대하는 설정 경로와 일치하는지 확인하세요. 위의 프리릴리스 에디션 섹션에서 가장 흔한 불일치 사례를 다룹니다.
--- a/docs/ko-KR/reference/planning-artifacts.md
+++ b/docs/ko-KR/reference/planning-artifacts.md
@@ -23,6 +23,8 @@
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # 브라운필드 온보딩 요약 (선택)
+│   └── SUMMARY.md
 ├── intel/                              # 쿼리 가능한 심볼 인덱스 (선택, intel.enabled)
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@
 | | |
 |---|---|
 | **목적** | 표준 프로젝트 아이덴티티: 무엇인지, 누구를 위한 것인지, 핵심 가치, 요구사항, 제약 사항, 주요 결정. 제품이 발전함에 따라 프로젝트 생명주기 전반에 걸쳐 업데이트됩니다. |
-| **생성자** | `/gsd-new-project` (최초 생성); 결정이 검증됨에 따라 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); 결정이 검증됨에 따라 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
 | **소비자** | 모든 플래닝 워크플로; `gsd-phase-researcher`, `gsd-planner` (컨텍스트); `discuss-phase` (이전 결정); `gsd-plan-checker` (프로젝트 제약 사항). |

 ### `ROADMAP.md`
@@ -56,7 +58,7 @@
 | | |
 |---|---|
 | **목적** | 목표, 요구사항 ID, 성공 기준, 페이즈별 표준 참조가 있는 마일스톤 및 페이즈 목록. 프로젝트가 무엇을 빌드하고 어떤 순서로 하는지에 대한 단일 진실의 원천. |
-| **생성자** | `/gsd-new-project` (최초 생성); `/gsd-phase --insert`와 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); `/gsd-phase --insert`와 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
 | **소비자** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; 페이즈 정보가 필요한 모든 오케스트레이션 명령; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |

 ### `REQUIREMENTS.md`
@@ -64,7 +66,7 @@
 | | |
 |---|---|
 | **목적** | 프로젝트의 번호가 매겨진 체크 가능한 인수 기준. 각 요구사항은 로드맵 페이즈에 매핑되는 ID(예: `AUTH-01`)를 가집니다. 페이즈가 실행됨에 따라 요구사항을 완료로 표시합니다. |
-| **생성자** | `/gsd-new-project` (최초 생성); `execute-phase`에 의해 요구사항이 완료로 표시됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); `execute-phase`에 의해 요구사항이 완료로 표시됩니다. |
 | **소비자** | `gsd-planner` (플랜은 모든 페이즈 요구사항 ID를 처리해야 함); `gsd-plan-checker` Dimension 1 (요구사항 커버리지); `discuss-phase` (이전 요구사항). |

 ### `STATE.md`
@@ -72,7 +74,7 @@
 | | |
 |---|---|
 | **목적** | 살아있는 위치 추적기 — 현재 페이즈와 플랜, 진행 지표, 누적된 결정, 세션 연속성 노트. 모든 워크플로 실행 시작 시 읽힙니다. 중요한 작업 이후 업데이트됩니다. |
-| **생성자** | `/gsd-new-project` (최초 생성); 모든 페이즈 워크플로, `/gsd-pause-work`, `/gsd-resume-work`에 의해 지속적으로 업데이트됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); 모든 페이즈 워크플로, `/gsd-pause-work`, `/gsd-resume-work`에 의해 지속적으로 업데이트됩니다. |
 | **소비자** | 모든 오케스트레이션 워크플로; `/gsd-progress`; `/gsd-quick`을 통한 임시 태스크 실행; `gsd-planner` 및 `gsd-phase-researcher` (프로젝트 결정). |

 전체 필드 참조는 [STATE.md 스키마](state-md.md)를 참조하세요.
@@ -87,6 +89,14 @@

 전체 스키마는 [CONFIGURATION](../../CONFIGURATION.md)을 참조하세요.

+### `onboarding/SUMMARY.md` (선택)
+
+| | |
+|---|---|
+| **목적** | 브라운필드 온보딩 인덱스. 아티팩트 상태, 코드베이스 매핑 완료 여부, 초기 설정 후 권장되는 다음 GSD 명령을 기록합니다. |
+| **생성자** | `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`가 모두 존재한 뒤 `/gsd-onboard`. |
+| **소비자** | 초기 설정을 검토하는 사람; 기존 온보딩 상태를 확인하는 향후 `/gsd-onboard` 실행. |
+
 ### `MILESTONES.md` (선택)

 | | |
--- a/docs/ko-KR/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/ko-KR/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,15 @@ claude --dangerously-skip-permissions

 ---

-## Step 3 — 코드베이스 매핑
+## Step 3 — 브라운필드 온보딩 시작

-프로젝트를 생성하기 전에 GSD Core가 이미 존재하는 것을 학습하도록 합니다. 이 단계가 브라운필드 계획의 정확도를 높이는 핵심입니다.
+프로젝트를 생성하기 전에 GSD Core가 저장소 상태를 검사하고 안전한 다음 top-level 명령을 알려주게 하세요. 이 단계는 코드베이스 컨텍스트를 건너뛰거나 기존 planning 파일을 덮어쓰는 일을 방지합니다.

 ```text
-/gsd-map-codebase
+/gsd-onboard
 ```

-GSD Core가 4개의 병렬 매퍼 서브 에이전트를 생성합니다("Spawning 4 parallel codebase mapper agents…" 메시지가 표시되며, 1–5분 소요됩니다. 중단하지 마세요). 각 에이전트는 서로 다른 관심사에 집중합니다:
+온보딩이 코드베이스 맵 누락을 보고하면 권장 옵션을 선택하고 출력된 `/gsd-map-codebase` handoff를 실행한 뒤 `/gsd-onboard`를 다시 실행합니다. `/gsd-onboard --fast`는 가벼운 첫 패스에는 충분하지만, `/gsd-new-project` 전에는 완전한 맵이 필요합니다. `/gsd-map-codebase`가 4개의 병렬 매퍼 서브 에이전트를 생성합니다("Spawning 4 parallel codebase mapper agents…" 메시지가 표시되며, 1–5분 소요됩니다. 중단하지 마세요). 각 에이전트는 서로 다른 관심사에 집중합니다:

 | 에이전트 | 집중 영역 |
 |---------|---------|
@@ -84,7 +84,7 @@ Created .planning/codebase/:

 ---

-## Step 4 — 컨텍스트 초기화 후 프로젝트 생성
+## Step 4 — 온보딩 재실행 및 프로젝트 초기화

 세션 창을 초기화합니다:

@@ -92,7 +92,7 @@ Created .planning/codebase/:
 /clear
 ```

-이제 프로젝트를 생성합니다. GSD Core가 이전 단계에서 기존 코드를 발견했으므로, 이미 이것이 브라운필드 프로젝트임을 알고 있습니다. `/gsd-new-project`를 실행하면 기존의 것을 재구성하는 것이 아니라 *추가하는* 것에 집중한 질문을 합니다:
+이제 `/gsd-onboard`를 다시 실행합니다. GSD Core가 ADR, PRD, spec, RFC 또는 루트 요구사항 문서를 감지하면 먼저 권장되는 `/gsd-ingest-docs` handoff를 실행하고 이후 `/gsd-onboard`를 다시 실행하세요. 컨텍스트가 준비되면 온보딩이 프로젝트 초기화 handoff를 출력합니다:

 ```text
 /gsd-new-project
@@ -124,6 +124,8 @@ Proposed Roadmap

 로드맵을 승인합니다.

+프로젝트 설정이 끝난 뒤 `/gsd-onboard`를 한 번 더 실행합니다. 이제 `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`가 모두 있으므로 온보딩은 `.planning/onboarding/SUMMARY.md`를 생성하거나 확인합니다.
+
 **`.planning/`에 생성되는 파일:**

 ```text
@@ -133,6 +135,7 @@ Proposed Roadmap
  ROADMAP.md          ← Phase 1, 상태: pending
  STATE.md            ← 세션 메모리
  config.json         ← 워크플로 설정
+  onboarding/SUMMARY.md ← 온보딩 상태와 다음 명령
  codebase/           ← Step 3에서 생성된 7개의 맵 파일
 ```

@@ -212,6 +215,7 @@ GSD Core가 `CONVENTIONS.md`와 `ARCHITECTURE.md`를 읽었으므로, 질문들

 ## 배운 내용

+- `/gsd-onboard`가 인터랙티브 명령을 중첩하거나 기존 planning 파일을 덮어쓰지 않고 브라운필드 설정을 안전하게 순서화하는 방법.
 - `/gsd-map-codebase`가 4개의 병렬 에이전트를 실행하여 `.planning/codebase/`에 `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, `INTEGRATIONS.md`를 생성하는 방법.
 - 브라운필드 저장소에서 `/gsd-new-project`가 *추가하는* 것에 집중한 질문을 하고 기존 코드에서 Validated 요구사항을 채우는 방법.
 - 코드베이스 맵이 `/gsd-discuss-phase`의 모든 질문을 형성하는 방법 — 파일 경로, 패턴, 컨벤션이 실제 코드에서 옵니다.
--- a/docs/pt-BR/ARCHITECTURE.md
+++ b/docs/pt-BR/ARCHITECTURE.md
@@ -527,7 +527,8 @@ Caminhos equivalentes para outros runtimes:
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # Mapeamento de brownfield (do /gsd-map-codebase)
+├── codebase/               # Mapeamento de brownfield (do /gsd-map-codebase ou /gsd-onboard)
+├── onboarding/             # Resumo de onboarding brownfield (do /gsd-onboard)
 │   ├── STACK.md            # Frontmatter YAML carrega `last_mapped_commit`
 │   ├── ARCHITECTURE.md     # para o portão de desvio pós-execução (#2003)
 │   ├── CONVENTIONS.md
--- a/docs/pt-BR/CLI-TOOLS.md
+++ b/docs/pt-BR/CLI-TOOLS.md
@@ -290,13 +290,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Comandos Init (Carregamento de Contexto Composto)

-Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho.
+Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho. `init onboard [--fast] [--text]` retorna, para `/gsd-onboard`, sinais de brownfield, candidatos a docs de planning, completude do mapa de código, prontidão do mapa fast, roteamento em modo texto, estado parcial de planning e status do resumo de onboarding.

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/pt-BR/COMMANDS.md
+++ b/docs/pt-BR/COMMANDS.md
@@ -51,6 +51,25 @@ Inicializa um novo projeto com coleta aprofundada de contexto.

 ---

+### `/gsd-onboard`
+
+Guia o onboarding inicial de um código existente no GSD. O comando verifica o estado do repositório, encaminha com segurança por mapeamento da base de código, ingestão opcional de documentos, inicialização do projeto e cria um onboarding summary quando o planejamento existe.
+
+| Flag | Descrição |
+|------|-----------|
+| `--fast` | Prefere o handoff leve `/gsd-map-codebase --fast`; um mapa completo ainda é necessário antes de `/gsd-new-project` |
+| `--text` | Usa gates numerados em texto puro em vez de menus TUI |
+
+**Pré-requisitos:** Repositório existente ou documentos de planejamento. Para projetos greenfield vazios, use `/gsd-new-project`.
+**Produz:** `.planning/codebase/` via map-codebase, `.planning/` via new-project ou ingest-docs, e `.planning/onboarding/SUMMARY.md` após a configuração do projeto.
+
+```bash
+/gsd-onboard           # Onboarding brownfield guiado
+/gsd-onboard --fast    # Usa primeiro o mapa leve e depois completa o mapa antes do setup do projeto
+```
+
+---
+
 ### `/gsd-workspace`

 Gerencia workspaces do GSD — cria, lista ou remove ambientes de workspace isolados com cópias de repositório e diretórios `.planning/` independentes.
--- a/docs/pt-BR/FEATURES.md
+++ b/docs/pt-BR/FEATURES.md
@@ -14,7 +14,7 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
 - **Commits atômicos por tarefa** para rastreabilidade e rollback
 - **Verificação pós-execução** com foco em objetivos da fase
 - **UAT guiado** via `/gsd-verify-work`
- **Suporte brownfield** com `/gsd-map-codebase`
+- **Suporte brownfield** com `/gsd-onboard` e `/gsd-map-codebase`
 - **Workstreams** para trilhas paralelas sem colisão de estado
 - **Backlog, seeds e threads** para memória de médio/longo prazo

@@ -68,7 +68,7 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
 |--------|----------|
 | Projeto novo | `/gsd-new-project` -> `/gsd-discuss-phase` -> `/gsd-plan-phase` -> `/gsd-execute-phase` |
 | Correção rápida | `/gsd-quick` |
-| Código existente | `/gsd-map-codebase` -> `/gsd-new-project` |
+| Código existente | `/gsd-onboard` -> handoffs para `/gsd-map-codebase`, `/gsd-ingest-docs`, `/gsd-new-project` |
 | Fechamento de release | `/gsd-audit-milestone` -> `/gsd-complete-milestone` |

 ---
--- a/docs/pt-BR/INVENTORY.md
+++ b/docs/pt-BR/INVENTORY.md
@@ -78,6 +78,7 @@ Esses seis roteadores são entradas apenas descritivas que o modelo seleciona pr
 | Comando | Função | Fonte |
 |---------|--------|-------|
 | `/gsd-new-project` | Inicializa um novo projeto com coleta profunda de contexto e PROJECT.md. | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-onboard` | Guia código existente por mapeamento, ingestão de docs, configuração de projeto e onboarding summary. | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
 | `/gsd-workspace` | Gerencia workspaces GSD — criar (`--new`), listar (`--list`) ou remover (`--remove`) ambientes de workspace isolados. | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | Coleta contexto da fase por meio de perguntas adaptativas antes do planejamento. | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | Planeja uma fase como uma fatia vertical de MVP — história de usuário, divisão SPIDR, depois plan-phase. | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
@@ -218,6 +219,7 @@ Registro completo em `get-shit-done/workflows/*.md`. Workflows são orquestrador
 | `milestone-summary.md` | Síntese do resumo do milestone — artefato de onboarding e revisão a partir dos artefatos do milestone. | `/gsd-milestone-summary` |
 | `new-milestone.md` | Inicia um novo ciclo de milestone — carregar contexto do projeto, coletar objetivos, atualizar PROJECT.md/STATE.md. | `/gsd-new-milestone` |
 | `new-project.md` | Fluxo unificado de novo projeto — questionamento, pesquisa (opcional), requisitos, roadmap. | `/gsd-new-project` |
+| `onboard.md` | Orquestração de onboarding brownfield — mapear código, ingerir docs, inicializar planning e resumir próximo passo. | `/gsd-onboard` |
 | `new-workspace.md` | Cria um workspace isolado com worktrees/clones do repositório e um `.planning/` independente. | `/gsd-workspace --new` |
 | `next.md` | Detecta o estado atual do projeto e avança automaticamente para o próximo passo lógico. | `/gsd-progress --next` |
 | `node-repair.md` | Operador de reparo autônomo para verificação de tarefa com falha; invocado por `execute-plan`. | `execute-plan.md` (recuperação) |
--- a/docs/pt-BR/USER-GUIDE.md
+++ b/docs/pt-BR/USER-GUIDE.md
@@ -474,8 +474,8 @@ claude --dangerously-skip-permissions
 ### Base de código existente

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow printed handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

@@ -864,7 +864,8 @@ Para desativar a execução paralela completamente: `/gsd-settings` → defina `
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/pt-BR/how-to/install-on-your-runtime.md
+++ b/docs/pt-BR/how-to/install-on-your-runtime.md
@@ -273,10 +273,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## Após a instalação

-Reinicie seu ambiente para carregar os novos comandos e agentes. Em seguida, inicie seu primeiro projeto:
+Reinicie seu ambiente para carregar os novos comandos e agentes. Em seguida, inicie um projeto novo ou faça onboarding de um repositório existente:

 ```bash
-/gsd-new-project
+/gsd-new-project   # projeto greenfield
+/gsd-onboard       # base de código existente
 ```

 Se o comando não for encontrado após o reinício, verifique se o diretório de instalação corresponde ao caminho de configuração esperado pelo ambiente. A seção de edições de pré-lançamento acima cobre a incompatibilidade mais comum.
--- a/docs/pt-BR/reference/planning-artifacts.md
+++ b/docs/pt-BR/reference/planning-artifacts.md
@@ -23,6 +23,8 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # Resumo de onboarding brownfield (opcional)
+│   └── SUMMARY.md
 ├── intel/                              # Índice de símbolos consultável (opcional, intel.enabled)
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Identidade canônica do projeto: o que é, para quem é, valor central, requisitos, restrições e decisões-chave. Atualizado ao longo do ciclo de vida do projeto conforme o produto evolui. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-complete-milestone` à medida que as decisões são validadas. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); atualizado por `/gsd-complete-milestone` à medida que as decisões são validadas. |
 | **Consumido por** | Todos os fluxos de trabalho de planejamento; `gsd-phase-researcher`, `gsd-planner` (contexto); `discuss-phase` (decisões anteriores); `gsd-plan-checker` (restrições do projeto). |

 ### `ROADMAP.md`
@@ -56,7 +58,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Listagem de marcos e fases com objetivos, IDs de requisitos, critérios de sucesso e referências canônicas por fase. A fonte única de verdade sobre o que o projeto está construindo e em que ordem. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-phase --insert` e `/gsd-complete-milestone`. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); atualizado por `/gsd-phase --insert` e `/gsd-complete-milestone`. |
 | **Consumido por** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; todos os comandos de orquestração que precisam de informações de fase; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |

 ### `REQUIREMENTS.md`
@@ -64,7 +66,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Critérios de aceitação numerados e verificáveis para o projeto. Cada requisito possui um ID (ex.: `AUTH-01`) que mapeia para as fases do roadmap. Marca os requisitos como concluídos conforme as fases são executadas. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); requisitos marcados como concluídos por `execute-phase`. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); requisitos marcados como concluídos por `execute-phase`. |
 | **Consumido por** | `gsd-planner` (os planos devem contemplar todos os IDs de requisitos da fase); `gsd-plan-checker` Dimensão 1 (cobertura de requisitos); `discuss-phase` (requisitos anteriores). |

 ### `STATE.md`
@@ -72,7 +74,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Rastreador de posição em andamento — fase e plano atuais, métricas de progresso, decisões acumuladas, notas de continuidade de sessão. Lido no início de toda execução de fluxo de trabalho. Atualizado após cada ação significativa. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado continuamente por todos os fluxos de fase, `/gsd-pause-work`, `/gsd-resume-work`. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); atualizado continuamente por todos os fluxos de fase, `/gsd-pause-work`, `/gsd-resume-work`. |
 | **Consumido por** | Todos os fluxos de orquestração; `/gsd-progress`; execução de tarefas avulsas via `/gsd-quick`; `gsd-planner` e `gsd-phase-researcher` (decisões do projeto). |

 Consulte o [esquema de STATE.md](state-md.md) para a referência completa de campos.
@@ -87,6 +89,14 @@ Consulte o [esquema de STATE.md](state-md.md) para a referência completa de cam

 Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.

+### `onboarding/SUMMARY.md` (opcional)
+
+| | |
+|---|---|
+| **Finalidade** | Índice de onboarding brownfield que registra status dos artefatos, se o mapeamento do código-base está completo e o próximo comando GSD recomendado após a configuração inicial. |
+| **Produzido por** | `/gsd-onboard` depois que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem. |
+| **Consumido por** | Humanos revisando a configuração inicial; futuras execuções de `/gsd-onboard` ao confirmar o estado de onboarding existente. |
+
 ### `MILESTONES.md` (opcional)

 | | |
--- a/docs/pt-BR/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/pt-BR/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,15 @@ claude --dangerously-skip-permissions

 ---

-## Passo 3 — Mapear a base de código
+## Passo 3 — Iniciar o onboarding brownfield

-Antes de criar um projeto, deixe o GSD Core aprender o que já existe. Este é o passo que torna o planejamento brownfield preciso.
+Antes de criar um projeto, deixe o GSD Core inspecionar o estado do repositório e indicar o próximo comando de nível superior seguro. Este passo evita pular contexto de código ou sobrescrever arquivos de planning existentes.

 ```text
-/gsd-map-codebase
+/gsd-onboard
 ```

-O GSD Core cria quatro sub-agentes mapeadores paralelos (você verá "Spawning 4 parallel codebase mapper agents…" — isso leva de 1 a 5 minutos; não interrompa). Cada agente foca em uma preocupação diferente:
+Se o onboarding informar que o mapa da base de código está ausente, escolha a opção recomendada e execute o handoff `/gsd-map-codebase` impresso antes de rodar `/gsd-onboard` novamente. `/gsd-onboard --fast` serve para uma primeira passada leve, mas um mapa completo ainda é necessário antes de `/gsd-new-project`. O `/gsd-map-codebase` cria quatro sub-agentes mapeadores paralelos (você verá "Spawning 4 parallel codebase mapper agents…" — isso leva de 1 a 5 minutos; não interrompa). Cada agente foca em uma preocupação diferente:

 | Agente | Foco |
 |--------|------|
@@ -84,7 +84,7 @@ Abra `.planning/codebase/CONCERNS.md`. Este é o arquivo mais útil para ler ant

 ---

-## Passo 4 — Limpar o contexto e criar o projeto
+## Passo 4 — Reexecutar o onboarding e inicializar o projeto

 Limpe a janela de sessão:

@@ -92,12 +92,14 @@ Limpe a janela de sessão:
 /clear
 ```

-Agora crie o projeto. Como o GSD Core encontrou código existente no passo anterior, já sabe que se trata de um projeto brownfield. Quando você executa `/gsd-new-project`, as perguntas focam no que você está *adicionando*, e não em reconstruir o que já existe:
+Agora execute `/gsd-onboard` novamente. Se o GSD Core detectar ADRs, PRDs, specs, RFCs ou requisitos de nível raiz, aceite o handoff recomendado para `/gsd-ingest-docs` primeiro e depois rode `/gsd-onboard` de novo. Quando o contexto estiver pronto, o onboarding imprimirá o handoff de inicialização:

 ```text
 /gsd-new-project
 ```

+Como o GSD Core encontrou código existente no passo anterior, `/gsd-new-project` sabe que é um projeto brownfield. As perguntas focam no que você está *adicionando*, não em reconstruir o que já existe:
+
 O GSD Core pergunta o que você quer construir. Responda com o recurso que está adicionando, e não com uma descrição de toda a base de código:

 ```text
@@ -124,6 +126,8 @@ Proposed Roadmap

 Aprove o roteiro.

+Execute `/gsd-onboard` mais uma vez depois que a configuração do projeto terminar. Agora que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem, o onboarding cria ou confirma `.planning/onboarding/SUMMARY.md`.
+
 **O que é criado em `.planning/`:**

 ```text
@@ -133,6 +137,7 @@ Aprove o roteiro.
  ROADMAP.md          ← Fase 1, status: pending
  STATE.md            ← memória de sessão
  config.json         ← configurações do fluxo de trabalho
+  onboarding/SUMMARY.md ← status do onboarding e próximo comando
  codebase/           ← os sete arquivos de mapa do Passo 3
 ```

@@ -212,6 +217,7 @@ Para cada recurso futuro, execute `/gsd-map-codebase` novamente sempre que a est

 ## O que você aprendeu

+- Como `/gsd-onboard` sequencia com segurança o setup brownfield sem aninhar comandos interativos ou sobrescrever planning existente.
 - Como `/gsd-map-codebase` executa quatro agentes paralelos para produzir `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md` e `INTEGRATIONS.md` em `.planning/codebase/`.
 - Como `/gsd-new-project` em um repositório brownfield concentra as perguntas no que você está *adicionando* e preenche os requisitos Validated a partir do código existente.
 - Como o mapa da base de código orienta cada pergunta em `/gsd-discuss-phase` — caminhos de arquivos, padrões e convenções vêm do seu código real.
--- a/docs/reference/capability-matrix.md
+++ b/docs/reference/capability-matrix.md
@@ -44,7 +44,7 @@ Core package and are stamped with the package version at release (per
 ADR-1244 D6). They are not subject to the consent or integrity-pin flow applied
 to third-party capabilities.

-### Feature capabilities (role: feature) — 18
+### Feature capabilities (role: feature) — 19

 Feature capabilities extend what the loop does — contributing research,
 planning, execution, verification, or ship artefacts at the loop extension
@@ -55,6 +55,7 @@ points.
 | `ai-integration` | feature | full | `>=1.6.0` | `plan:pre` | step | first-party |
 | `assumption-delta` | feature | full | `>=1.6.0` | `plan:pre` | contribution | first-party |
 | `audit` | feature | full | `>=1.6.0` | — | — | first-party |
+| `claude-orchestration` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:post` | contribution | first-party |
 | `code-review` | feature | full | `>=1.6.0` | `execute:post` | step | first-party |
 | `drift` | feature | full | `>=1.6.0` | `plan:pre`, `execute:wave:post` | gate | first-party |
 | `external-job` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:post` | contribution | first-party |
--- a/docs/reference/planning-artifacts.md
+++ b/docs/reference/planning-artifacts.md
@@ -23,6 +23,8 @@ The `.planning/` directory is GSD Core's shared memory for a project. Every work
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # Brownfield onboarding summary (optional)
+│   └── SUMMARY.md
 ├── intel/                              # Queryable symbol index (optional, intel.enabled)
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@ The `.planning/` directory is GSD Core's shared memory for a project. Every work
 | | |
 |---|---|
 | **Purpose** | Canonical project identity: what it is, who it is for, core value, requirements, constraints, and key decisions. Updated throughout the project lifecycle as the product evolves. |
-| **Produced by** | `/gsd-new-project` (initial creation); updated by `/gsd-complete-milestone` as decisions are validated. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated by `/gsd-complete-milestone` as decisions are validated. |
 | **Consumed by** | All planning workflows; `gsd-phase-researcher`, `gsd-planner` (context); `discuss-phase` (prior decisions); `gsd-plan-checker` (project constraints). |

 Includes an optional `## Business Context` section (Customer, Revenue model, Success metric, Strategy notes) for monetized or customer-facing projects — four one-line fields that connect business outcomes to requirement prioritization. It is deleted for internal tools, experiments, or meta workspaces, and reviewed at each milestone by `/gsd-complete-milestone` when present.
@@ -58,7 +60,7 @@ Includes an optional `## Business Context` section (Customer, Revenue model, Suc
 | | |
 |---|---|
 | **Purpose** | Milestone and phase listing with goals, requirement IDs, success criteria, and canonical references per phase. The single source of truth for what the project is building and in what order. |
-| **Produced by** | `/gsd-new-project` (initial creation); updated by `/gsd-phase --insert` and `/gsd-complete-milestone`. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated by `/gsd-phase --insert` and `/gsd-complete-milestone`. |
 | **Consumed by** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; all orchestration commands that need phase information; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |

 ### `REQUIREMENTS.md`
@@ -66,7 +68,7 @@ Includes an optional `## Business Context` section (Customer, Revenue model, Suc
 | | |
 |---|---|
 | **Purpose** | Numbered, checkable acceptance criteria for the project. Each requirement carries an ID (e.g., `AUTH-01`) that maps to roadmap phases. Marks requirements complete as phases are executed. |
-| **Produced by** | `/gsd-new-project` (initial creation); requirements marked complete by `execute-phase`. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); requirements marked complete by `execute-phase`. |
 | **Consumed by** | `gsd-planner` (plans must address all phase requirement IDs); `gsd-plan-checker` Dimension 1 (requirement coverage); `discuss-phase` (prior requirements). |

 ### `STATE.md`
@@ -74,7 +76,7 @@ Includes an optional `## Business Context` section (Customer, Revenue model, Suc
 | | |
 |---|---|
 | **Purpose** | Living position tracker — current phase and plan, progress metrics, accumulated decisions, session continuity notes. Read at the start of every workflow run. Updated after every significant action. |
-| **Produced by** | `/gsd-new-project` (initial creation); updated continuously by all phase workflows, `/gsd-pause-work`, `/gsd-resume-work`. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated continuously by all phase workflows, `/gsd-pause-work`, `/gsd-resume-work`. |
 | **Consumed by** | All orchestration workflows; `/gsd-progress`; ad-hoc task execution via `/gsd-quick`; `gsd-planner` and `gsd-phase-researcher` (project decisions). |

 See [STATE.md schema](state-md.md) for the full field reference.
@@ -89,6 +91,14 @@ See [STATE.md schema](state-md.md) for the full field reference.

 See [CONFIGURATION](../CONFIGURATION.md) for the complete schema.

+### `onboarding/SUMMARY.md` (optional)
+
+| | |
+|---|---|
+| **Purpose** | Brownfield onboarding index that records artifact status, whether codebase mapping is complete, and the next recommended GSD command after first-time setup. |
+| **Produced by** | `/gsd-onboard` after `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist. |
+| **Consumed by** | Humans reviewing first-time setup; future `/gsd-onboard` runs when confirming existing onboarding state. |
+
 ### `MILESTONES.md` (optional)

 | | |
--- a/docs/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,21 @@ claude --dangerously-skip-permissions

 ---

-## Step 3 — Map the codebase
+## Step 3 — Start brownfield onboarding

-Before creating a project, let GSD Core learn what already exists. This is the step that makes brownfield planning accurate.
+Before creating a project, let GSD Core inspect the repo state and tell you the safe next top-level command. This is the step that prevents brownfield setup from skipping codebase context or overwriting existing planning files.
+
+```text
+/gsd-onboard
+```
+
+If code exists and `.planning/codebase/` is missing, GSD Core asks you to map the codebase first. Choose the recommended mapping option, then run the printed handoff command:

 ```text
 /gsd-map-codebase
 ```

-GSD Core spawns four parallel mapper sub-agents (you'll see "Spawning 4 parallel codebase mapper agents…" — this takes 1–5 minutes; do not interrupt). Each agent focuses on a different concern:
+Use `/gsd-onboard --fast` if you want the onboarding gate to prefer `/gsd-map-codebase --fast` for a lighter first pass. Fast mode is only enough for lightweight onboarding; `/gsd-onboard` still sends you back to the full mapper before `/gsd-new-project`. The full mapper spawns four parallel mapper sub-agents (you'll see "Spawning 4 parallel codebase mapper agents…" — this takes 1–5 minutes; do not interrupt). Each agent focuses on a different concern:

 | Agent | Focus |
 |-------|-------|
@@ -84,7 +90,7 @@ Open `.planning/codebase/CONCERNS.md`. This is the most useful file to read befo

 ---

-## Step 4 — Clear context and create the project
+## Step 4 — Rerun onboarding and initialize the project

 Clear the session window:

@@ -92,12 +98,20 @@ Clear the session window:
 /clear
 ```

-Now create the project. Because GSD Core found existing code in the last step, it already knows this is a brownfield project. When you run `/gsd-new-project`, the questions focus on what you are *adding*, not rebuilding what already exists:
+Now rerun onboarding:
+
+```text
+/gsd-onboard
+```
+
+If GSD Core detects ADRs, PRDs, specs, RFCs, or top-level requirements docs, choose the recommended docs-ingest handoff first and rerun `/gsd-onboard` afterward. Once codebase context and any existing docs are handled, onboarding prints the project-initialization handoff:

 ```text
 /gsd-new-project
 ```

+Because GSD Core found existing code in the previous step, `/gsd-new-project` knows this is a brownfield project. The questions focus on what you are *adding*, not rebuilding what already exists:
+
 GSD Core asks what you want to build. Answer with the feature you are adding, not a description of the whole codebase:

 ```text
@@ -138,6 +152,20 @@ Approve the roadmap.

 Notice that `.planning/codebase/` is already there from Step 3. GSD Core read those files when writing `PROJECT.md`, which is why it could populate the Validated requirements without you describing them.

+Run onboarding one more time after project setup completes:
+
+```text
+/gsd-onboard
+```
+
+Now that `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist, onboarding creates or confirms:
+
+```text
+.planning/onboarding/SUMMARY.md
+```
+
+This summary is a lightweight index of the setup artifacts and the next command to run.
+
 ---

 ## Step 5 — Clear context and discuss Phase 1
@@ -206,12 +234,13 @@ You now have a project with a codebase map, a discuss decision record, and verif
 /gsd-ship 1
 ```

-For every future feature, run `/gsd-map-codebase` again whenever the structure changes significantly, so the codebase map stays fresh.
+For every future feature, run `/gsd-map-codebase` again whenever the structure changes significantly, so the codebase map stays fresh. Rerun `/gsd-onboard` only when you want to re-check first-time setup completeness or regenerate the onboarding summary.

 ---

 ## What you've learned

+- How `/gsd-onboard` safely sequences brownfield setup without nesting interactive commands or overwriting existing planning files.
 - How `/gsd-map-codebase` runs four parallel agents to produce `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, and `INTEGRATIONS.md` in `.planning/codebase/`.
 - How `/gsd-new-project` in a brownfield repo focuses questions on what you are *adding* and populates Validated requirements from existing code.
 - How the codebase map shapes every question in `/gsd-discuss-phase` — file paths, patterns, and conventions come from your actual code.
@@ -222,5 +251,5 @@ For every future feature, run `/gsd-map-codebase` again whenever the structure c
 ## Related

 - [Your first project](your-first-project.md) — the full greenfield loop from install to PR
- [Map codebase via Commands](../COMMANDS.md) — all `/gsd-map-codebase` flags and subcommands
+- [Commands](../COMMANDS.md) — `/gsd-onboard`, plus all `/gsd-map-codebase` flags and subcommands
 - [Documentation index](../README.md)
--- a/Show More
+++ b/Show More