@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/new-project.md

@@ -0,0 +1,1113 @@
+<purpose>
+Initialize a new project through unified flow: questioning, research (optional), requirements, roadmap. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. One workflow takes you from idea to ready-for-planning.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<auto_mode>
+## Auto Mode Detection
+
+Check if `--auto` flag is present in $ARGUMENTS.
+
+**If auto mode:**
+- Skip brownfield mapping offer (assume greenfield)
+- Skip deep questioning (extract context from provided document)
+- Config: Use existing product config from init-product (Step 2a sets auto_advance only)
+- After config: run Steps 6-9 automatically with smart defaults:
+  - Research: Always yes
+  - Requirements: Include all table stakes + features from provided document
+  - Requirements approval: Auto-approve
+  - Roadmap approval: Auto-approve
+
+**Document requirement:**
+Auto mode requires an idea document or spec reference — either:
+- File reference: `/dgs:new-project --auto @prd.md`
+- Pasted/written text in the prompt
+- Spec ID: `/dgs:new-project --auto <spec-id>`
+- Spec file path: `/dgs:new-project --auto @${project_root}/specs/X.md`
+
+If no document content provided, error:
+
+```
+Error: --auto requires an idea document or spec reference.
+
+Usage:
+  /dgs:new-project --auto @your-idea.md           # From idea document
+  /dgs:new-project --auto [paste or write idea]    # From freeform text
+  /dgs:new-project --auto <spec-id>                # From finalized spec
+  /dgs:new-project --auto @${project_root}/specs/X.md    # From spec file path
+
+The argument should be an idea document, freeform text, or a finalized spec.
+```
+
+**Spec-driven mode:**
+
+If the `--auto` argument references a spec file path or spec ID:
+1. Read the spec file (either from the provided path or by looking up via `node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs list --status final`)
+2. Validate the spec has `status: final` — if not, error: "Spec must be finalized before creating a project. Run /dgs:write-spec to complete it."
+3. Enter spec-driven flow (Steps 2b-2c below) instead of the standard auto flow
+
+**Detection:** If the argument after `--auto` contains `spec-` or ends with `.md` and exists in `${project_root}/specs/`, treat it as a spec reference. Otherwise, treat as a freeform document (existing behavior).
+</auto_mode>
+
+<process>
+
+## 1. Setup
+
+**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-project)
+```
+
+Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`, `state_path`, `roadmap_path`, `requirements_path`, `research_dir`.
+
+Load planning-tier context files:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+
+**If `project_exists` is true:** Error — project already initialized. Use `/dgs:progress`.
+
+**Config validation:** If `project_exists` is false, check that config has workflow preferences:
+
+```bash
+MODE=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-get mode --raw 2>/dev/null)
+```
+
+If `MODE` is empty/unset (no `mode` key in config), display error and exit:
+
+```
+Error: Workflow settings not configured. Run `/dgs:init-product` first to configure workflow settings.
+```
+
+**If `has_git` is false:** Initialize git:
+```bash
+git init
+```
+
+## 2. Brownfield Offer
+
+**If auto mode:** Skip to Step 4 (assume greenfield, synthesize PROJECT.md from provided document).
+
+**If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
+
+Use AskUserQuestion:
+- header: "Codebase"
+- question: "I detected existing code in this directory. Would you like to map the codebase first?"
+- options:
+  - "Map codebase first" — Run /dgs:map-codebase to understand existing architecture (Recommended)
+  - "Skip mapping" — Proceed with project initialization
+
+**If "Map codebase first":**
+```
+Run `/dgs:map-codebase` first, then return to `/dgs:new-project`
+```
+Exit command.
+
+**If "Skip mapping" OR `needs_codebase_map` is false:** Continue to Step 3.
+
+## 2a. Auto Mode Config (auto mode only)
+
+**If auto mode:** Use existing product config (set during `/dgs:init-product`). No config questions needed here.
+
+**Persist auto-advance to config (survives context compaction):**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.auto_advance true
+```
+
+Proceed to Step 4 (skip Step 3).
+
+## 2b. Spec-Driven Project Creation (spec-driven auto mode only)
+
+**Triggered when:** `--auto` argument references a spec file.
+
+### Parse the Spec
+
+Read the spec file and extract:
+- **Title** → becomes project name (slugified for folder name)
+- **Problem** section → project description / core value
+- **Goals** section → project goals
+- **Non-Goals** section → out of scope
+- **Requirements** (P0/P1/P2) → v1 requirements (P0 + P1) and future requirements (P2)
+- **User Stories** → inform requirement specificity
+- **Technical Considerations** → inform research/architecture
+- **"Repos likely touched"** or similar section → repos for cross-checking (Step 2c)
+
+### Derive Project Name
+
+Extract from spec title. Slugify for the project folder name. Example: "Review Configuration System" → `review-configuration-system`.
+
+### Write PROJECT.md
+
+Create `${project_path}` with standard template structure, but derived entirely from the spec:
+
+```markdown
+# [Spec Title]
+
+## Vision
+
+[Derived from spec Problem + Goals sections]
+
+## Core Value
+
+[Extracted from the spec's Problem section — the ONE thing this solves]
+
+## Source Spec
+
+`[relative path to spec file]`
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+[Requirements derived from spec P0 + P1 sections, each as a checkbox item]
+
+### Out of Scope
+
+[From spec Non-Goals + P2 requirements explicitly deferred]
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Spec-driven creation | Auto-generated from [spec id] | — |
+```
+
+**Important:** Transform spec requirements into standard DGS format:
+- Each spec requirement becomes a user-centric statement: "User can X"
+- Group by logical category
+- Do NOT copy verbatim — restructure for project planning context
+- Add a `Source spec: [path]` line to PROJECT.md (per user decision — reference, not copy)
+
+### Write REQUIREMENTS.md
+
+Generate `${requirements_path}` with:
+- REQ-IDs in `[CATEGORY]-[NUMBER]` format (e.g., AUTH-01, UI-02)
+- P0 requirements → v1 (must have)
+- P1 requirements → v1 (should have)
+- P2 requirements → Future
+- Non-Goals → Out of Scope with reasoning
+
+The requirements must be user-centric and atomic (one capability per requirement), following the quality criteria in the existing new-project workflow.
+
+### Commit and Continue
+
+Commit PROJECT.md and REQUIREMENTS.md, then continue to Step 5 (Resolve Model Profile) — skip Steps 3 (Deep Questioning) and 4 (Write PROJECT.md) since they're replaced by spec-driven derivation.
+
+**Branch name preview:** After the project folder is created, if `branching_strategy` is not `"none"`, show:
+```
+Branch names will look like: dgs/{project-slug}/phase-03-auth
+```
+
+After model profile resolution, proceed to Step 6, 7 (if research selected, auto-default yes), 8 (Create Roadmap), 8.5 (Overlap Check), 9 (Done).
+
+## 2c. Repo Cross-Check (spec-driven mode, v2 only)
+
+**Triggered when:** spec-driven mode AND v2 install (REPOS.md exists).
+
+### Extract Repos from Spec
+
+Parse the spec body for a "Repos likely touched" or "Technical Considerations" section. Extract any repo names mentioned.
+
+### Load Registered Repos
+
+```bash
+REPOS_JSON=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos list --raw)
+```
+
+Parse the JSON to get the list of registered repo names.
+
+### Compare
+
+For each repo name mentioned in the spec:
+- If it exists in REPOS.md registered repos → OK (no action)
+- If NOT registered → add to unregistered list
+
+### Handle Unregistered Repos
+
+If any unregistered repos found, display a blocking warning:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► REPO CHECK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+The spec references repos not registered with this product:
+```
+
+For EACH unregistered repo, use AskUserQuestion:
+
+```
+AskUserQuestion([{
+  question: "Repo '{repo_name}' is not registered. How should we handle it?",
+  header: "Repo",
+  multiSelect: false,
+  options: [
+    { label: "Continue", description: "Proceed without registering this repo" },
+    { label: "Register existing", description: "Register an already-existing repo at this path" },
+    { label: "Create + Register", description: "Create folder, git init, and register" },
+    { label: "Cancel", description: "Stop project creation" }
+  ]
+}])
+```
+
+**Handle each choice:**
+
+- **Continue:** Skip this repo, proceed to next
+- **Register existing:** Ask for path (suggest `../{repo_name}`), then run:
+  ```bash
+  node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos add "{path}" --name "{repo_name}"
+  ```
+- **Create + Register:**
+  ```bash
+  mkdir -p ../{repo_name}
+  cd ../{repo_name} && git init
+  node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos add "../{repo_name}" --name "{repo_name}"
+  ```
+- **Cancel:** Stop project creation entirely with message: "Project creation cancelled. Resolve repo registration and try again."
+
+After all repos handled, continue to Step 2b (or back to the standard flow).
+
+If no unregistered repos OR not v2: skip silently.
+
+## 3. Deep Questioning
+
+**If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4.
+
+**Display stage banner:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► QUESTIONING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Open the conversation:**
+
+Ask inline (freeform, NOT AskUserQuestion):
+
+"What do you want to build?"
+
+Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
+
+**Follow the thread:**
+
+Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
+
+Keep following threads. Each answer opens new threads to explore. Ask about:
+- What excited them
+- What problem sparked this
+- What they mean by vague terms
+- What it would actually look like
+- What's already decided
+
+Consult `questioning.md` for techniques:
+- Challenge vagueness
+- Make abstract concrete
+- Surface assumptions
+- Find edges
+- Reveal motivation
+
+**Check context (background, not out loud):**
+
+As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
+
+**Decision gate:**
+
+When you could write a clear PROJECT.md, use AskUserQuestion:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+## 4. Write PROJECT.md
+
+**If auto mode:** Synthesize from provided document. No "Ready?" gate was shown — proceed directly to commit.
+
+Synthesize all context into `${project_path}` using the template from `templates/project.md`.
+
+**For greenfield projects:**
+
+Initialize requirements as hypotheses:
+
+```markdown
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### Out of Scope
+
+- [Exclusion 1] — [why]
+- [Exclusion 2] — [why]
+```
+
+All Active requirements are hypotheses until shipped and validated.
+
+**For brownfield projects (codebase map exists):**
+
+Infer Validated requirements from existing code:
+
+1. Read `${project_root}/codebase/ARCHITECTURE.md` and `STACK.md`
+2. Identify what the codebase already does
+3. These become the initial Validated set
+
+```markdown
+## Requirements
+
+### Validated
+
+- ✓ [Existing capability 1] — existing
+- ✓ [Existing capability 2] — existing
+- ✓ [Existing capability 3] — existing
+
+### Active
+
+- [ ] [New requirement 1]
+- [ ] [New requirement 2]
+
+### Out of Scope
+
+- [Exclusion 1] — [why]
+```
+
+**Key Decisions:**
+
+Initialize with any decisions made during questioning:
+
+```markdown
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice from questioning] | [Why] | — Pending |
+```
+
+**Last updated footer:**
+
+```markdown
+---
+*Last updated: [date] after initialization*
+```
+
+Do not compress. Capture everything gathered.
+
+**Commit PROJECT.md:**
+
+```bash
+mkdir -p .planning
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --files ${project_path}
+```
+
+## 5. Resolve Model Profile
+
+Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
+
+## 6. Research Decision
+
+**If auto mode:** Default to "Research first" without asking.
+
+Use AskUserQuestion:
+- header: "Research"
+- question: "Research the domain ecosystem before defining requirements?"
+- options:
+  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
+  - "Skip research" — I know this domain well, go straight to requirements
+
+**If "Research first":**
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► RESEARCHING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Researching [domain] ecosystem...
+```
+
+Create research directory:
+```bash
+mkdir -p ${research_dir}
+```
+
+**Determine milestone context:**
+
+Check if this is greenfield or subsequent milestone:
+- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
+- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
+
+**Discover product-level documents:**
+
+Before spawning researchers, check for product-level documents that should inform research:
+
+```bash
+ls ${project_root}/docs/product/ 2>/dev/null
+```
+
+If the directory exists and contains files, store the list of file paths as `$product_doc_files`. For each file, format as a `<files_to_read>` entry: `- ${project_root}/docs/product/{filename} (Product doc)`. If the directory does not exist or is empty, set `$product_doc_files` to empty string.
+
+Display spawning indicator:
+```
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+```
+
+Spawn 4 parallel dgs-project-researcher agents with path references:
+
+```
+Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Stack dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: Research the standard stack for building [domain] from scratch.
+Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
+</milestone_context>
+
+<question>
+What's the standard 2025 stack for [domain]?
+</question>
+
+<files_to_read>
+- {project_path} (Project context and goals)
+${product_doc_files}
+</files_to_read>
+
+<downstream_consumer>
+Your STACK.md feeds into roadmap creation. Be prescriptive:
+- Specific libraries with versions
+- Clear rationale for each choice
+- What NOT to use and why
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Versions are current (verify with Context7/official docs, not training data)
+- [ ] Rationale explains WHY, not just WHAT
+- [ ] Confidence levels assigned to each recommendation
+</quality_gate>
+
+<output>
+Write to: ${research_dir}/STACK.md
+Use template: ~/.claude/deliver-great-systems/templates/research-project/STACK.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
+
+Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Features dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
+Subsequent: How do [target features] typically work? What's expected behavior?
+</milestone_context>
+
+<question>
+What features do [domain] products have? What's table stakes vs differentiating?
+</question>
+
+<files_to_read>
+- {project_path} (Project context)
+${product_doc_files}
+</files_to_read>
+
+<downstream_consumer>
+Your FEATURES.md feeds into requirements definition. Categorize clearly:
+- Table stakes (must have or users leave)
+- Differentiators (competitive advantage)
+- Anti-features (things to deliberately NOT build)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
+- [ ] Complexity noted for each feature
+- [ ] Dependencies between features identified
+</quality_gate>
+
+<output>
+Write to: ${research_dir}/FEATURES.md
+Use template: ~/.claude/deliver-great-systems/templates/research-project/FEATURES.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
+
+Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Architecture dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: How are [domain] systems typically structured? What are major components?
+Subsequent: How do [target features] integrate with existing [domain] architecture?
+</milestone_context>
+
+<question>
+How are [domain] systems typically structured? What are major components?
+</question>
+
+<files_to_read>
+- {project_path} (Project context)
+${product_doc_files}
+</files_to_read>
+
+<downstream_consumer>
+Your ARCHITECTURE.md informs phase structure in roadmap. Include:
+- Component boundaries (what talks to what)
+- Data flow (how information moves)
+- Suggested build order (dependencies between components)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Components clearly defined with boundaries
+- [ ] Data flow direction explicit
+- [ ] Build order implications noted
+</quality_gate>
+
+<output>
+Write to: ${research_dir}/ARCHITECTURE.md
+Use template: ~/.claude/deliver-great-systems/templates/research-project/ARCHITECTURE.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
+
+Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Pitfalls dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
+Subsequent: What are common mistakes when adding [target features] to [domain]?
+</milestone_context>
+
+<question>
+What do [domain] projects commonly get wrong? Critical mistakes?
+</question>
+
+<files_to_read>
+- {project_path} (Project context)
+${product_doc_files}
+</files_to_read>
+
+<downstream_consumer>
+Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
+- Warning signs (how to detect early)
+- Prevention strategy (how to avoid)
+- Which phase should address it
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Pitfalls are specific to this domain (not generic advice)
+- [ ] Prevention strategies are actionable
+- [ ] Phase mapping included where relevant
+</quality_gate>
+
+<output>
+Write to: ${research_dir}/PITFALLS.md
+Use template: ~/.claude/deliver-great-systems/templates/research-project/PITFALLS.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
+```
+
+After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
+
+```
+Task(prompt="
+<task>
+Synthesize research outputs into SUMMARY.md.
+</task>
+
+<files_to_read>
+- ${research_dir}/STACK.md
+- ${research_dir}/FEATURES.md
+- ${research_dir}/ARCHITECTURE.md
+- ${research_dir}/PITFALLS.md
+</files_to_read>
+
+<output>
+Write to: ${research_dir}/SUMMARY.md
+Use template: ~/.claude/deliver-great-systems/templates/research-project/SUMMARY.md
+Commit after writing.
+</output>
+", subagent_type="dgs-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+```
+
+Display research complete banner and key findings:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► RESEARCH COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Key Findings
+
+**Stack:** [from SUMMARY.md]
+**Table Stakes:** [from SUMMARY.md]
+**Watch Out For:** [from SUMMARY.md]
+
+Files: `${research_dir}/`
+```
+
+**If "Skip research":** Continue to Step 7.
+
+## 7. Define Requirements
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► DEFINING REQUIREMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Load context:**
+
+Read PROJECT.md and extract:
+- Core value (the ONE thing that must work)
+- Stated constraints (budget, timeline, tech limitations)
+- Any explicit scope boundaries
+
+**If research exists:** Read research/FEATURES.md and extract feature categories.
+
+**If auto mode:**
+- Auto-include all table stakes features (users expect these)
+- Include features explicitly mentioned in provided document
+- Auto-defer differentiators not mentioned in document
+- Skip per-category AskUserQuestion loops
+- Skip "Any additions?" question
+- Skip requirements approval gate
+- Generate REQUIREMENTS.md and commit directly
+
+**Present features by category (interactive mode only):**
+
+```
+Here are the features for [domain]:
+
+## Authentication
+**Table stakes:**
+- Sign up with email/password
+- Email verification
+- Password reset
+- Session management
+
+**Differentiators:**
+- Magic link login
+- OAuth (Google, GitHub)
+- 2FA
+
+**Research notes:** [any relevant notes]
+
+---
+
+## [Next Category]
+...
+```
+
+**If no research:** Gather requirements through conversation instead.
+
+Ask: "What are the main things users need to be able to do?"
+
+For each capability mentioned:
+- Ask clarifying questions to make it specific
+- Probe for related capabilities
+- Group into categories
+
+**Scope each category:**
+
+For each category, use AskUserQuestion:
+
+- header: "[Category]" (max 12 chars)
+- question: "Which [category] features are in v1?"
+- multiSelect: true
+- options:
+  - "[Feature 1]" — [brief description]
+  - "[Feature 2]" — [brief description]
+  - "[Feature 3]" — [brief description]
+  - "None for v1" — Defer entire category
+
+Track responses:
+- Selected features → v1 requirements
+- Unselected table stakes → v2 (users expect these)
+- Unselected differentiators → out of scope
+
+**Identify gaps:**
+
+Use AskUserQuestion:
+- header: "Additions"
+- question: "Any requirements research missed? (Features specific to your vision)"
+- options:
+  - "No, research covered it" — Proceed
+  - "Yes, let me add some" — Capture additions
+
+**Validate core value:**
+
+Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
+
+**Generate REQUIREMENTS.md:**
+
+Create `${requirements_path}` with:
+- v1 Requirements grouped by category (checkboxes, REQ-IDs)
+- v2 Requirements (deferred)
+- Out of Scope (explicit exclusions with reasoning)
+- Traceability section (empty, filled by roadmap)
+
+**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
+
+**Requirement quality criteria:**
+
+Good requirements are:
+- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
+- **User-centric:** "User can X" (not "System does Y")
+- **Atomic:** One capability per requirement (not "User can login and manage profile")
+- **Independent:** Minimal dependencies on other requirements
+
+Reject vague requirements. Push for specificity:
+- "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
+- "Support sharing" → "User can share post via link that opens in recipient's browser"
+
+**Present full requirements list (interactive mode only):**
+
+Show every requirement (not counts) for user confirmation:
+
+```
+## v1 Requirements
+
+### Authentication
+- [ ] **AUTH-01**: User can create account with email/password
+- [ ] **AUTH-02**: User can log in and stay logged in across sessions
+- [ ] **AUTH-03**: User can log out from any page
+
+### Content
+- [ ] **CONT-01**: User can create posts with text
+- [ ] **CONT-02**: User can edit their own posts
+
+[... full list ...]
+
+---
+
+Does this capture what you're building? (yes / adjust)
+```
+
+If "adjust": Return to scoping.
+
+**Commit requirements:**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define v1 requirements" --files ${requirements_path}
+```
+
+## 8. Create Roadmap
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning roadmapper...
+```
+
+Spawn dgs-roadmapper agent with path references:
+
+```
+Task(prompt="
+<planning_context>
+
+<files_to_read>
+- ${project_path} (Project context)
+- ${requirements_path} (v1 Requirements)
+- ${research_dir}/SUMMARY.md (Research findings - if exists)
+- ${config_path} (Depth and mode settings)
+${product_doc_files}
+</files_to_read>
+
+</planning_context>
+
+<instructions>
+Create roadmap:
+1. Derive phases from requirements (don't impose structure)
+2. Map every v1 requirement to exactly one phase
+3. Derive 2-5 success criteria per phase (observable user behaviors)
+4. Validate 100% coverage
+5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+6. Return ROADMAP CREATED with summary
+
+Write files first, then return. This ensures artifacts persist even if context is lost.
+</instructions>
+", subagent_type="dgs-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+```
+
+**Handle roadmapper return:**
+
+**If `## ROADMAP BLOCKED`:**
+- Present blocker information
+- Work with user to resolve
+- Re-spawn when resolved
+
+**If `## ROADMAP CREATED`:**
+
+Read the created ROADMAP.md and present it nicely inline:
+
+```
+---
+
+## Proposed Roadmap
+
+**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓
+
+| # | Phase | Goal | Requirements | Success Criteria |
+|---|-------|------|--------------|------------------|
+| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
+| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |
+| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
+...
+
+### Phase Details
+
+**Phase 1: [Name]**
+Goal: [goal]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [criterion]
+2. [criterion]
+3. [criterion]
+
+**Phase 2: [Name]**
+Goal: [goal]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [criterion]
+2. [criterion]
+
+[... continue for all phases ...]
+
+---
+```
+
+**If auto mode:** Skip approval gate — auto-approve and commit directly.
+
+**CRITICAL: Ask for approval before committing (interactive mode only):**
+
+Use AskUserQuestion:
+- header: "Roadmap"
+- question: "Does this roadmap structure work for you?"
+- options:
+  - "Approve" — Commit and continue
+  - "Adjust phases" — Tell me what to change
+  - "Review full file" — Show raw ROADMAP.md
+
+**If "Approve":** Continue to commit.
+
+**If "Adjust phases":**
+- Get user's adjustment notes
+- Re-spawn roadmapper with revision context:
+  ```
+  Task(prompt="
+  <revision>
+  User feedback on roadmap:
+  [user's notes]
+
+  <files_to_read>
+  - ${roadmap_path} (Current roadmap to revise)
+  </files_to_read>
+
+  Update the roadmap based on feedback. Edit files in place.
+  Return ROADMAP REVISED with changes made.
+  </revision>
+  ", subagent_type="dgs-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
+  ```
+- Present revised roadmap
+- Loop until user approves
+
+**If "Review full file":** Display raw `cat ${roadmap_path}`, then re-ask.
+
+**Commit roadmap (after approval or auto mode):**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create roadmap ([N] phases)" --files ${roadmap_path} ${state_path} ${requirements_path}
+```
+
+### Link Spec to Milestone (spec-driven mode only)
+
+If this project was created from a spec (spec-driven auto mode), update the spec's milestones frontmatter to record the bidirectional link:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs link-milestone --id "$SPEC_ID" --milestone "v1.0"
+```
+
+Include the updated spec file in a commit:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v1.0" --files $SPEC_PATH
+```
+
+## 8.5. Overlap Check (v2 only)
+
+If v2 install (PROJECTS.md or REPOS.md exists in the planning root):
+
+```bash
+OVERLAP=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs overlap check --raw 2>/dev/null)
+```
+
+Parse JSON. If `overlapping_repos` array is non-empty, display warning:
+
+```
+⚠ Cross-project overlap detected:
+
+| Repo | Also touched by |
+|------|----------------|
+| {repo} | {other-project} |
+
+This is informational — work can proceed.
+```
+
+If no overlaps or not v2: skip silently.
+
+## 9. Done
+
+Present completion summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► PROJECT INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**[Project Name]**
+
+| Artifact       | Location                    |
+|----------------|-----------------------------|
+| Project        | `${project_path}`           |
+| Config         | `${config_path}`            |
+| Research       | `${research_dir}/`          |
+| Requirements   | `${requirements_path}`      |
+| Roadmap        | `${roadmap_path}`           |
+
+**[N] phases** | **[X] requirements** | Ready to build ✓
+```
+
+**If spec-driven mode**, add to the summary table:
+
+```
+**Source:** `[spec path]`
+**Created from spec:** {spec_id} — "{spec_title}"
+```
+
+**If auto mode (spec-driven):**
+
+```
+**Created from spec:** {spec_id} — "{spec_title}"
+
+╔══════════════════════════════════════════╗
+║  AUTO-ADVANCING → DISCUSS PHASE 1        ║
+╚══════════════════════════════════════════╝
+```
+
+**If auto mode (idea-driven):**
+
+```
+╔══════════════════════════════════════════╗
+║  AUTO-ADVANCING → DISCUSS PHASE 1        ║
+╚══════════════════════════════════════════╝
+```
+
+Exit skill and invoke SlashCommand("/dgs:discuss-phase 1 --auto")
+
+**If interactive mode:**
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
+
+/dgs:discuss-phase 1 — gather context and clarify approach
+
+<sub>/clear first → fresh context window</sub>
+
+---
+
+**Also available:**
+- /dgs:plan-phase 1 — skip discussion, plan directly
+
+───────────────────────────────────────────────────────────────
+```
+
+</process>
+
+<output>
+
+- `${project_path}`
+- `${config_path}`
+- `${research_dir}/` (if research selected)
+  - `STACK.md`
+  - `FEATURES.md`
+  - `ARCHITECTURE.md`
+  - `PITFALLS.md`
+  - `SUMMARY.md`
+- `${requirements_path}`
+- `${roadmap_path}`
+- `${state_path}`
+
+</output>
+
+<success_criteria>
+
+- [ ] Planning root directory created
+- [ ] Git repo initialized
+- [ ] Brownfield detection completed
+- [ ] Deep questioning completed (threads followed, not rushed)
+- [ ] PROJECT.md captures full context → **committed**
+- [ ] Product config validated (mode, depth, workflow settings from init-product)
+- [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
+- [ ] Requirements gathered (from research or conversation)
+- [ ] User scoped each category (v1/v2/out of scope)
+- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
+- [ ] dgs-roadmapper spawned with context
+- [ ] Roadmap files written immediately (not draft)
+- [ ] User feedback incorporated (if any)
+- [ ] ROADMAP.md created with phases, requirement mappings, success criteria
+- [ ] STATE.md initialized
+- [ ] REQUIREMENTS.md traceability updated
+- [ ] Spec-driven mode: spec milestones field updated with link-milestone call
+- [ ] User knows next step is `/dgs:discuss-phase 1`
+
+**Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
+
+</success_criteria>