@edupia-tutor/spec-driven-docs 0.14.0

package/commands/setup-ai-first.md

@@ -0,0 +1,545 @@
+# /setup-ai-first — Initialize Spec-Driven Docs in a Project
+
+Walk the user through a one-time setup that creates all required directories, installs CLAUDE.md, and verifies the environment.
+
+## Gate
+# Gate — Universal Entry Procedure
+
+Every command must execute this gate before proceeding with its specific logic.
+
+## Step 0 — Sub-Agent Mode Check
+
+Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+
+1. Attempt to parse `$ARGUMENTS` as JSON.
+2. If it parses successfully **and** contains `"_agent_mode": true`:
+   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
+   - Set target file = `payload.target_file`
+   - Set loaded context = `payload.context` (do NOT run context-loader.md)
+   - Set UC scope = `payload.uc_id` (process only this UC)
+   - Set line range = `payload.uc_section` (read only that PRD section)
+   - Proceed directly to the command-specific logic.
+3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+
+## Step 0-B — Model Check
+
+*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+
+Complex generation and review commands require strong reasoning.
+Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+
+Display and wait for response:
+
+```
+⚙️  MODEL CHECK
+──────────────────────────────────────────────────────────────────
+  Recommended  : claude-opus-4 (or latest Opus model)
+  Why needed   : Spec analysis, architecture review, code generation
+                 require deep reasoning. Smaller models miss edge cases.
+
+  To switch in Claude Code:
+    • Settings → Model → select "claude-opus"
+    • or: /model → choose claude-opus
+
+  Running on claude-opus?
+    Y — yes, on claude-opus → proceed
+    S — skip check (I accept lower quality risk with current model)
+──────────────────────────────────────────────────────────────────
+```
+
+- "Y" → proceed to Step 1.
+- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
+- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+
+## Step 1 — Resolve Target File
+
+1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
+2. If `$ARGUMENTS` is a **bare UC-ID / ticket ID / partial name** (no path) → resolve it to a file by globbing the feature-package layout. The `{prd-slug}` is **not known yet**, so use a `*` wildcard for that segment, and a recursive `**` under `bdd/` so the platform subfolders (`bdd/web/`, `bdd/app/`, `bdd/system/`) are all covered:
+   - **BDD commands** (target is a `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — or `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` if the domain is also unknown. If a platform/scope is implied by the command (e.g. a system tech-doc needs the `system/` BDD), prefer the match under that platform subfolder.
+   - **PRD commands** (target is `prd.md`): `{specs_dir}/{domain}/*/prd.md` (match the feature folder whose id corresponds), else `{specs_dir}/*/*/prd.md`.
+   - **tech-docs commands**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **design-spec commands**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+
+   Once a file matches: set it as the target **and** record `domain` + `prd_slug` from its path (per the extraction rule in `context-loader.md` Step 1 — `prd_slug` = first segment after `{specs_dir}/{domain}/`). Every path the command later reads or writes (sibling BDD/tech-docs/design-spec/trace) uses **that resolved `prd_slug`**, so all artifacts stay in one feature package. If several files match (e.g. multiple platforms), pick per the command's platform/scope or list them and ask.
+3. If `$ARGUMENTS` is empty or no match found:
+   - List files in the relevant directory for this command (e.g., `specs/*/*/prd.md` for PRD commands, `specs/*/*/bdd/**/*.feature` for BDD commands).
+   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
+   - Wait for user selection before continuing.
+
+## Step 2 — Execute Context Loader
+
+Load all project context by following the procedure in `steps/context-loader.md`.
+Store all loaded context in memory for use throughout this command session.
+
+## Step 3 — CHECKPOINT
+
+After completing Steps 1 and 2, display a summary and wait for confirmation:
+
+```
+CHECKPOINT
+-----------
+Target     : {resolved file path}
+Project    : {project.name from project-context.yaml}
+Tech stack : {language} / {framework}
+Module     : {module if set, else "not configured"}
+Domains    : {comma-separated domain list}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" or "N" from the user before continuing.
+- "Y" → proceed to the command-specific steps below.
+- "N" → stop and ask what the user wants to change.
+
+
+*Note: For this command — **skip Gate Steps 1, 2, and 3** (there is no input file and no project context yet). Only run Step 0-B (model check). The project root is the **current working directory**. Proceed directly to the Precondition Check below.*
+
+---
+
+## Precondition Check
+
+Check if already set up:
+- If `CLAUDE.md` **and** `.agent/project-context.yaml` both exist → ask: "This project is already initialized. Re-run setup to regenerate config files? (Y/N)"
+  - N → stop
+  - Y → continue (existing files will be preserved — each step will offer merge/skip)
+- If only `specs/` exists or only partial setup detected → continue normally (safe to re-run)
+
+## Step 0.5 — Project Type
+
+Ask the user:
+
+```
+What type of project is this?
+  1. Single-service  — one codebase, one platform (standard setup)
+  2. Umbrella repo   — this repo contains multiple service submodules (microservices / multi-app)
+  3. PO Spec repo    — docs only, no runnable code (PRD + design-spec only)
+```
+
+Store the answer as `project_type`. Default to `1` if user does not answer.
+
+Based on answer:
+
+**project_type = 1 (Single-service):** Continue standard setup below.
+
+**project_type = 2 (Umbrella):** Ask two follow-up questions:
+- "Path to spec submodule (e.g. `free-trial-specs`)? Press Enter to skip."
+- "List services as `domain:module` pairs, comma-separated
+  (e.g. `user:java-spring,order:java-spring`). Press Enter to skip."
+
+Then:
+- Skip creating any `specs/` artifacts (all specs — PRD, BDD, tech-docs, design-spec — live in the spec submodule under the feature-package layout `specs/{domain}/{prd-slug}/`)
+- Create only: `.trace/`, `.agent/review/` at umbrella level
+  *(Unless user explicitly asks to create the full structure)*
+- Generate `.agent/project-context.yaml` in umbrella mode with the services and spec_source provided
+- Skip creating `CLAUDE.md` (umbrella has no single tech stack)
+- After setup, remind: "Open each service submodule separately in Claude Code to install the framework there if needed."
+
+**project_type = 3 (PO Spec repo):**
+- Create base dirs: `specs/product-definition/`, `specs/domain-knowledge/`, `feedback/`, `.agent/review/`
+- Per-feature artifacts (`specs/{domain}/{prd-slug}/{prd.md, bdd/, tech-docs/, design-spec/}`) are created on demand by the generate commands — do NOT pre-create them
+- Skip: `.trace/` (per-service, lives beside code in each service submodule)
+- Generate minimal `CLAUDE.md` with only §1 (project overview) and §7 (git conventions)
+- Ask the user: **"List your business domains (e.g. auth, payment, loyalty):"** — store as domain list for `project-context.yaml` and remind PO these names must be used consistently as `@trace.domain` in every PRD
+- Inform:
+  - Commands for PO repo: `/define-product`, `/generate-prd`, `/review-context`, `/generate-design-spec`
+  - **Critical for dev team handoff:** Every PRD must have `@trace.domain: {domain}` in its frontmatter. Dev team uses this to route generated BDD/code to the correct service submodule. Inconsistent domain names will break routing.
+  - Recommended PRD frontmatter:
+    ```
+    @trace.domain: {domain}    ← must match a key in dev team's services config
+    @trace.id: {TICKET-ID}
+    @trace.status: draft | approved
+    ```
+
+## Step 1 — Create Directory Structure
+
+Create these directories (skip if they exist):
+
+```
+{project-root}/
+├── specs/
+│   ├── product-definition/   ← Output of /define-product
+│   └── domain-knowledge/     ← business dictionary & domain context
+├── .trace/                   ← .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+└── .agent/
+    └── review/
+```
+
+**Feature-package layout** — per-feature spec artifacts are NOT pre-created. Each generate
+command creates its own folder on demand under `specs/{domain}/{prd-slug}/`:
+
+```
+specs/{domain}/{prd-slug}/
+├── prd.md                    ← /generate-prd
+├── bdd/                      ← /generate-bdd (.feature files)
+├── tech-docs/                ← /generate-tech-docs
+└── design-spec/              ← /generate-design-spec (FE/App platforms only)
+```
+
+*Which base dirs to create varies by `project_type` set in Step 0.5:*
+
+| project_type | Create | Skip |
+|---|---|---|
+| **1 — Single-service** | Base structure above (`specs/product-definition/`, `specs/domain-knowledge/`, `.trace/`, `.agent/review/`) | per-feature folders (created on demand) |
+| **2 — Umbrella** | `.trace/` + `.agent/review/` only (at umbrella root) | Everything else — **all specs live in the spec submodule (`spec_source`)** under `specs/{domain}/{prd-slug}/`; service submodules hold only **code + `.trace/`** |
+| **3 — PO Spec repo** | `specs/product-definition/`, `specs/domain-knowledge/`, **`feedback/`**, `.agent/review/` (per-feature `specs/{domain}/{prd-slug}/` folders created on demand) | `.trace/` (per-service, lives beside code in each service submodule) |
+
+## Step 2 — Create CLAUDE.md
+
+*Skip this step entirely if `project_type = 2` (Umbrella) — umbrella has no single tech stack.*
+*For `project_type = 3` (PO Spec repo) — create a minimal CLAUDE.md with only §1 (project overview) and §7 (git conventions). Skip §2–§6.*
+
+Check if `CLAUDE.md` exists:
+- Yes → ask "Merge template or skip?"
+- No → create from the template below
+
+After creating, instruct: "Open CLAUDE.md and fill in the `{{PLACEHOLDER}}` values with your project information."
+
+### CLAUDE.md Template
+
+```
+# §1. Project Overview
+Project: {{PROJECT_NAME}}
+Language: {{LANGUAGE}}
+Framework: {{FRAMEWORK}}
+Build: {{BUILD_COMMAND}}
+Test: {{TEST_COMMAND}}
+Domains: {{COMMA_SEPARATED_DOMAINS}}
+
+# §2. Architecture
+layers: "{{LAYER_STACK}}"
+# Example: Controller → Facade → Service → Repository
+rules:
+  - "Controllers must not contain business logic"
+  - "Services own transaction boundaries"
+
+# §3. Coding Standards
+naming:
+  classes: "{{NAMING_CONVENTION}}"
+  methods: "{{METHOD_CONVENTION}}"
+response_wrapper: "{{WRAPPER}}"
+forbidden:
+  - "Magic numbers"
+  - "Debug print statements"
+
+# §4. Traceability
+# Every controller method must be tagged:
+# @trace.implements={UC-ID}-{SC-ID}
+# @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature  ← adjust if specs_dir differs in .agent/project-context.yaml
+# Tests must be tagged:
+# @trace.verifies={UC-ID}
+
+# §5. Error Handling
+not_found: "{{NOT_FOUND_EXCEPTION}}"
+http_codes: { get: 200, create: 201, not_found: 404, validation: 400 }
+
+# §6. Build & Test
+build_command: "{{BUILD_COMMAND}}"
+test_command: "{{TEST_COMMAND}}"
+run_command: "{{RUN_COMMAND}}"
+
+# §7. Git Conventions
+branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
+commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
+```
+
+## Step 3 — Create project-context.yaml
+
+*For `project_type = 2` (Umbrella):*
+- *If `.agent/project-context.yaml` was already generated by `--init --umbrella` → open it and verify/edit the `services` section (domain keys, paths, modules). Skip template copy below.*
+- *If not yet generated → ask: "Spec submodule path?" and "Services (domain:module pairs)?" then generate umbrella config (see Step 0.5 for format).*
+
+Create `.agent/project-context.yaml` using `.agent/templates/project-context.yaml` as the source template.
+
+Copy the template and instruct: "Open `.agent/project-context.yaml` and fill in all `{{PLACEHOLDER}}` values. The `paths` section is pre-configured with sensible defaults — adjust if your project uses different directory names."
+
+## Step 4 — Create business-dictionary.md
+
+*Skip Steps 4 and 5 if `project_type = 2` (Umbrella) — business dictionary and core entities live in the spec submodule and are managed by the PO team. Dev team reads them from `{spec_source}/specs/domain-knowledge/`.*
+
+
+Create `specs/domain-knowledge/business-dictionary.md` if it does not exist:
+
+```markdown
+# Business Dictionary — {{PROJECT_NAME}}
+
+> Canonical terminology for this project. All PRDs, BDD specs, and code must follow these terms.
+> Managed by: PO / SA team.
+
+## Canonical Terms
+
+| Canonical Term | Description / Context |
+|----------------|----------------------|
+| {Term}         | {Short description, usage scope} |
+
+## Banned Terms
+
+| ❌ Do NOT use | ✅ Use instead    | Reason |
+|---------------|-------------------|--------|
+| {banned}      | {canonical}       | {why}  |
+
+## Status / Enum Registry
+
+| Entity | Field   | Allowed Values     |
+|--------|---------|--------------------|
+| {Entity} | status | {value1, value2} |
+```
+
+Instruct: "Open `specs/domain-knowledge/business-dictionary.md` and add your project terminology. This file will be read by all commands to enforce consistent naming."
+
+## Step 5 — Create core-entities.md
+
+Create `specs/domain-knowledge/core-entities.md` if it does not exist:
+
+```markdown
+# Core Entities — {{PROJECT_NAME}}
+
+> Machine-readable entity glossary for AI-assisted development.
+> Loaded by all commands so AI knows your domain model without reading source code.
+> Managed by: Tech Lead / Architect.
+>
+> HOW TO USE:
+> - Add one `## Entity: {Name}` section per domain entity (aggregate root, value object, etc.)
+> - Keep field descriptions concise — this is a REFERENCE, not API docs
+> - Update this file whenever you add/rename fields or change business invariants
+
+---
+
+## Entity: {EntityName}
+
+**Purpose**: {1-2 sentences — what this entity represents and why it exists in the domain}
+**Domain**: {domain}
+**Storage**: {e.g., `orders` table in PostgreSQL | `orders` collection in MongoDB}
+**Owner service**: {service/module that owns this entity}
+
+| Field        | Type    | Nullable | Description                         |
+|--------------|---------|----------|-------------------------------------|
+| id           | UUID    | No       | Primary key                         |
+| {field_name} | {type}  | Yes/No   | {short description}                 |
+| status       | Enum    | No       | See Status Registry in business-dictionary.md |
+
+**Business invariants:**
+- {Rule 1: e.g., "status can only transition: PENDING → ACTIVE → CLOSED"}
+- {Rule 2: e.g., "total must equal sum of line items"}
+
+**Relationships:**
+- `{EntityA}` 1:N `{EntityB}` — {one sentence description}
+- `{EntityA}` N:N `{EntityC}` via `{junction_table}` — {description}
+
+---
+
+## Entity: {AnotherEntity}
+
+*(Add more entities following the same pattern above)*
+```
+
+Instruct: "Open `specs/domain-knowledge/core-entities.md` and define your key domain entities. Start with aggregate roots. This file is loaded by every AI command — good definitions here save significant back-and-forth during code generation."
+
+## Step 6 — Install VS Code Extension (Recommended)
+
+Recommend the user install the **Spec Driven Docs Tools** VS Code extension — it provides Review Board + Living Documentation panels that integrate with this workflow.
+
+```bash
+code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+```
+
+Or: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → search **Spec Driven Docs Tools**.
+
+**What it does:**
+- 📋 **Review Board** — visual UI to review findings from `/refine-prd`, `/review-context`, `/review-tech-docs`
+- 📊 **Living Documentation** — traceability dashboard driven by `.trace/*.tsv`
+
+## Step 7 — Verify
+
+Checklist varies by `project_type`:
+
+**project_type = 1 (Single-service):**
+- [ ] `specs/` exists
+- [ ] `specs/product-definition/` exists
+- [ ] `specs/domain-knowledge/` exists
+- [ ] `.trace/` exists
+  *(per-feature `specs/{domain}/{prd-slug}/` folders are created on demand — not checked here)*
+- [ ] `.agent/project-context.yaml` exists
+- [ ] `CLAUDE.md` exists
+- [ ] `specs/domain-knowledge/business-dictionary.md` exists
+- [ ] `specs/domain-knowledge/core-entities.md` exists
+
+**project_type = 2 (Umbrella):**
+- [ ] `.agent/project-context.yaml` exists with `setup.mode: umbrella`
+- [ ] `services` section has at least one entry with correct domain keys
+- [ ] `spec_source` path exists (e.g., `my-project-specs/` directory is present)
+- [ ] `.agent/review/` exists
+- [ ] Spec submodule initialized: `git submodule status` shows no `-` prefix
+
+**project_type = 3 (PO Spec repo):**
+- [ ] `specs/product-definition/` exists
+- [ ] `specs/domain-knowledge/` exists
+- [ ] `feedback/` exists
+  *(per-feature `specs/{domain}/{prd-slug}/` folders are created on demand — not checked here)*
+- [ ] `.agent/review/` exists
+- [ ] `.agent/project-context.yaml` exists
+- [ ] `CLAUDE.md` exists (minimal)
+- [ ] `specs/domain-knowledge/business-dictionary.md` exists
+- [ ] `specs/domain-knowledge/core-entities.md` exists
+
+## Output
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
+
+Format the footer as:
+```
+---
+Status   : {badge}
+{Output Artifacts block}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
+```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+
+
+```
+/setup-ai-first Complete ✅
+```
+
+Output varies by `project_type`:
+
+**Single-service:**
+```
+Next:
+  1. Fill CLAUDE.md (replace {{PLACEHOLDER}} values)
+  2. Fill .agent/project-context.yaml
+  3. Fill specs/domain-knowledge/business-dictionary.md
+  4. Fill specs/domain-knowledge/core-entities.md
+  5. git add and commit those 4 files
+  6. Install VS Code extension:
+     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+  7. /define-product to start your first feature
+```
+
+**Umbrella:**
+```
+Next:
+  1. Review .agent/project-context.yaml:
+     - Update services[].path to match actual submodule directory names
+     - Update services domain keys to match @trace.domain in your PRD files
+     - Confirm spec_source path is correct
+
+  2. Run /sync — one command that handles everything else:
+     /sync
+     → git pull + submodule init + spec submodule update
+     → Auto-create .agent/project-context.yaml for each service submodule
+       (detects module from pom.xml / go.mod / package.json / pubspec.yaml etc.)
+     → Sync Living Docs panel
+     → Refresh spec-manifest.yaml
+
+  3. Start generating:
+     /generate-bdd {spec_source}/specs/{domain}/{prd-slug}/prd.md
+```
+
+**PO Spec repo:**
+```
+Next:
+  1. Fill .agent/project-context.yaml:
+     - domains: [list all business domains — these become @trace.domain values in PRDs]
+     - project.name, project.description
+  2. Fill specs/domain-knowledge/business-dictionary.md  ← canonical terms
+  3. Fill specs/domain-knowledge/core-entities.md        ← entity glossary
+  4. git add and commit those files
+  5. Install VS Code extension:
+     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+  6. /define-product to start your first feature
+
+⚠️  Dev team handoff reminder:
+  - Each PRD must have @trace.domain matching one of your domains list
+  - When dev team sets up their umbrella repo, they map these domain names
+    to service submodule paths in their project-context.yaml services section
+  - Share domain names with dev team before they configure their umbrellas
+```