@jokerized/getresearchdone 0.4.1

package/commands/init.md

@@ -0,0 +1,1508 @@
+---
+description: Initialize a new R&D project from idea to roadmap
+argument-hint: [--auto @document.md | --yolo]
+---
+
+<purpose>
+Initialize a new R&D project through unified flow: questioning, research (optional), requirements, roadmap, research landscape, and product-level quality targets. 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>
+
+<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 questions still required (Step 5)
+- 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
+- Research landscape initialization is automatic
+- If research context (papers, benchmarks) is provided in document, populate LANDSCAPE.md
+
+**Document requirement:**
+Auto mode requires an idea document via @ reference (e.g., `/grd:init --auto @prd.md`). If no document provided, error:
+
+```
+Error: --auto requires an idea document via @ reference.
+
+Usage: /grd:init --auto @your-idea.md
+
+The document should describe what you want to build.
+```
+</auto_mode>
+
+<yolo_mode>
+## YOLO Mode Detection
+
+Check if `autonomous_mode` is true in `.planning/config.json` (or if `--yolo` flag is present).
+
+**If YOLO mode:**
+- Skip deep questioning entirely — synthesize PROJECT.md from available context (README, existing code, any provided documents)
+- Skip all approval gates (requirements, roadmap)
+- Auto-select "Research first" with smart defaults
+- Auto-approve config with: YOLO mode, Standard depth, Parallel, Yes git tracking, all agents enabled
+- Research landscape initialized automatically
+- Proceed through entire flow without human interaction
+</yolo_mode>
+
+<process>
+
+## 1. Setup
+
+**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
+
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js 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`, `autonomous_mode`, `research_dir`, `phases_dir`, `codebase_dir`.
+
+**If `project_exists` is true:** Skip to **Step 5 (Workflow Preferences)** — reconfigure settings with existing values pre-populated. Show the user:
+
+```
+Project already initialized. Entering configuration mode.
+Current settings will be shown as defaults — change what you need.
+```
+
+**If `has_git` is false:** Initialize git:
+```bash
+git init
+```
+
+## 2. Brownfield Offer
+
+**If auto mode or YOLO mode:** Skip to Step 4 (assume greenfield, synthesize PROJECT.md from provided document or available context).
+
+**If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
+
+Use AskUserQuestion:
+- header: "Existing Code"
+- question: "I detected existing code in this directory. Would you like to map the codebase first?"
+- options:
+  - "Map codebase first" — Run /grd:map-codebase to understand existing architecture (Recommended)
+  - "Skip mapping" — Proceed with project initialization
+
+**If "Map codebase first":**
+```
+Run `/grd:map-codebase` first, then return to `/grd:init`
+```
+Exit command.
+
+**If "Skip mapping" OR `needs_codebase_map` is false:** Continue to Step 3.
+
+## 3. Deep Questioning
+
+**If auto mode:** Skip. Extract project context from provided document instead and proceed to Step 4.
+
+**If YOLO mode:** Skip. Synthesize from README, existing code analysis, and any available context. Proceed to Step 4.
+
+**Display stage banner:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► 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
+- What research or papers informed this
+- What baselines or benchmarks matter
+
+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.
+
+**If YOLO mode:** Synthesize from all available context (README, code, docs). Proceed directly to commit.
+
+Synthesize all context into `.planning/PROJECT.md` 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 `${codebase_dir}/ARCHITECTURE.md` and `STACK.md`
+2. Identify what the codebase already does
+3. These become the initial Validated set
+
+```markdown
+## Requirements
+
+### Validated
+
+- V [Existing capability 1] — existing
+- V [Existing capability 2] — existing
+- V [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_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
+```
+
+## 4.5. Initialize Research Landscape
+
+**Create research landscape directory and files:**
+
+```bash
+mkdir -p ${research_dir}
+```
+
+Create `${research_dir}/LANDSCAPE.md`:
+```markdown
+# Research Landscape
+
+## Domain
+[Extracted from PROJECT.md — the research area / problem space]
+
+## Key Methods
+<!-- Updated by /grd:survey -->
+
+## State of the Art
+<!-- Updated by /grd:survey -->
+
+## Open Problems
+<!-- Identified gaps and opportunities -->
+
+---
+*Initialized: [date]*
+```
+
+Create `${research_dir}/PAPERS.md`:
+```markdown
+# Paper Registry
+
+## Reviewed
+<!-- Papers analyzed via /grd:deep-dive -->
+
+## Queue
+<!-- Papers to review -->
+
+---
+*Initialized: [date]*
+```
+
+Create `${research_dir}/BENCHMARKS.md`:
+```markdown
+# Benchmarks & Baselines
+
+## Metrics
+<!-- Key metrics for this project -->
+
+## Baselines
+<!-- Current performance baselines -->
+
+## Targets
+<!-- Quality targets by phase -->
+
+---
+*Initialized: [date]*
+```
+
+Create `${research_dir}/KNOWHOW.md`:
+```markdown
+# Know-How Registry
+
+## Techniques
+<!-- Proven techniques and their conditions -->
+
+## Anti-Patterns
+<!-- What to avoid and why -->
+
+## Implementation Notes
+<!-- Practical notes from execution -->
+
+---
+*Initialized: [date]*
+```
+
+**Commit research landscape:**
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: initialize research landscape" --files ${research_dir}/LANDSCAPE.md ${research_dir}/PAPERS.md ${research_dir}/BENCHMARKS.md ${research_dir}/KNOWHOW.md
+```
+
+## 5. Workflow Preferences
+
+**Pre-population from existing config:** If `.planning/config.json` already exists, read it first. For each question below, pre-select the option matching the current config value. This lets users see and confirm or change their current settings. When presenting questions, indicate the current value with "(current)" appended to the matching option label.
+
+**If YOLO mode:** Auto-set config with defaults and skip to Step 5.5:
+```json
+{
+  "mode": "yolo",
+  "depth": "standard",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "balanced",
+  "autonomous_mode": true,
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true
+  },
+  "research_gates": {
+    "verification_design": false,
+    "method_selection": false,
+    "baseline_review": false
+  }
+}
+```
+
+**Round 1 — Core workflow settings (4 questions):**
+
+```
+questions: [
+  {
+    header: "Mode",
+    question: "How do you want to work?",
+    multiSelect: false,
+    options: [
+      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
+      { label: "Interactive", description: "Confirm at each step" }
+    ]
+  },
+  {
+    header: "Depth",
+    question: "How thorough should planning be?",
+    multiSelect: false,
+    options: [
+      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
+      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
+    ]
+  },
+  {
+    header: "Execution",
+    question: "Run plans in parallel?",
+    multiSelect: false,
+    options: [
+      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
+      { label: "Sequential", description: "One plan at a time" }
+    ]
+  },
+  {
+    header: "Git Tracking",
+    question: "Commit planning docs to git?",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
+      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
+    ]
+  }
+]
+```
+
+**Round 2 — Workflow agents:**
+
+These spawn additional agents during planning/execution. They add tokens and time but improve quality.
+
+| Agent | When it runs | What it does |
+|-------|--------------|--------------|
+| **Researcher** | Before planning each phase | Investigates domain, finds patterns, surfaces gotchas |
+| **Plan Checker** | After plan is created | Verifies plan actually achieves the phase goal |
+| **Verifier** | After phase execution | Confirms must-haves were delivered |
+
+All recommended for important projects. Skip for quick experiments.
+
+```
+questions: [
+  {
+    header: "Research",
+    question: "Research before planning each phase? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
+      { label: "No", description: "Plan directly from requirements" }
+    ]
+  },
+  {
+    header: "Plan Check",
+    question: "Verify plans will achieve their goals? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
+      { label: "No", description: "Execute plans without verification" }
+    ]
+  },
+  {
+    header: "Verifier",
+    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
+      { label: "No", description: "Trust execution, skip verification" }
+    ]
+  },
+  {
+    header: "Model Profile",
+    question: "Which AI models for planning agents?",
+    multiSelect: false,
+    options: [
+      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
+      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
+      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
+    ]
+  }
+]
+```
+
+**Round 3 — Research gates (R&D-specific):**
+
+```
+questions: [
+  {
+    header: "Research Gates",
+    question: "Pause for human review at these research checkpoints?",
+    multiSelect: true,
+    options: [
+      { label: "Verification Design", description: "Review EVAL.md before execution (recommended for novel methods)" },
+      { label: "Method Selection", description: "Review method choice before planning" },
+      { label: "Baseline Review", description: "Review baseline assessment before setting targets" }
+    ]
+  }
+]
+```
+
+**Round 4 — Execution backend:**
+
+```
+questions: [
+  {
+    header: "Execution Backend",
+    question: "How should GRD execute work?",
+    multiSelect: false,
+    options: [
+      { label: "GRD (Default)", description: "Use GRD's own commands/skills with the configured AI backend" },
+      { label: "Superpowers", description: "Use Superpowers plugin system — supports multi-account rotation across AI backends" },
+      { label: "Overstory", description: "Use Overstory multi-agent orchestration — tmux + git worktrees" },
+      { label: "Claude Code", description: "Use Claude Code native subagents directly" },
+      { label: "Codex", description: "Use OpenAI Codex CLI" },
+      { label: "Gemini", description: "Use Google Gemini CLI" },
+      { label: "OpenCode", description: "Use OpenCode CLI (provider-agnostic)" }
+    ]
+  }
+]
+```
+
+Backend mapping:
+- "GRD (Default)" → `backend: "grd"`
+- "Superpowers" → `backend: "superpowers"`
+- "Overstory" → `backend: "overstory"`
+- "Claude Code" → `backend: "claude"`
+- "Codex" → `backend: "codex"`
+- "Gemini" → `backend: "gemini"`
+- "OpenCode" → `backend: "opencode"`
+
+**Round 5 — AI Accounts (always shown, not conditional on backend choice):**
+
+Account rotation works with ANY execution backend — it controls which AI service credentials the scheduler uses when spawning subprocesses. This round detects which CLIs are installed, then asks the user about their accounts.
+
+**Step 5a: Detect installed CLIs only (NOT config dirs).**
+
+```bash
+which claude 2>/dev/null && echo "DETECTED: claude"
+which codex 2>/dev/null && echo "DETECTED: codex"
+which gemini 2>/dev/null && echo "DETECTED: gemini"
+which opencode 2>/dev/null && echo "DETECTED: opencode"
+```
+
+Do NOT scan for config directories — the filesystem cannot tell you which directories are real authenticated accounts vs. backups, test dirs, or leftover state. Only the user knows how many accounts they have.
+
+**Step 5b: Ask about account rotation.**
+
+```
+I found these AI CLIs installed:
+  ✓ claude
+  ✓ codex
+  ✗ gemini (not installed)
+  ✗ opencode (not installed)
+```
+
+```
+questions: [
+  {
+    header: "AI Account Rotation",
+    question: "Do you have multiple AI service accounts (e.g., personal + work subscriptions) that you want GRD to rotate between? This avoids rate limits during long autopilot runs.",
+    multiSelect: false,
+    options: [
+      { label: "Yes — I have multiple accounts", description: "I'll tell you about each one" },
+      { label: "No — just one account", description: "Use my default CLI credentials" }
+    ]
+  }
+]
+```
+
+If "No" → skip to Step 5f (single-account defaults).
+
+**Step 5c: For each installed CLI, ask how many accounts the user has.**
+
+Only ask about CLIs that were detected in Step 5a. Ask one backend at a time:
+
+```
+questions: [
+  {
+    header: "Claude Accounts",
+    question: "How many Claude accounts do you want to rotate between?",
+    multiSelect: false,
+    options: [
+      { label: "1 (default only)", description: "Just ~/.claude or your default config" },
+      { label: "2" },
+      { label: "3" },
+      { label: "More (I'll specify)" }
+    ]
+  }
+]
+```
+
+Repeat for each detected backend (codex, gemini, opencode).
+
+If the user answers "1" for every backend, there's nothing to rotate — skip to Step 5f.
+
+**Step 5d: For each account, ask where its config directory is.**
+
+For backends where the user has 2+ accounts, ask for each config directory path. Pre-fill the first account with the CLI's default path:
+
+```
+Claude account 1 — config directory:
+  [~/.claude]  ← default, press Enter to accept
+
+Claude account 2 — config directory:
+  [Enter path, e.g. ~/.claude-work]
+
+Claude account 3 — config directory:
+  [Enter path]
+```
+
+After each path, explain how to set it up if the user hasn't already:
+
+```
+ℹ  To authenticate a new account at that path:
+     CLAUDE_CONFIG_DIR=~/.claude-work claude auth login
+```
+
+The equivalent for each backend:
+- Claude: `CLAUDE_CONFIG_DIR=<path> claude auth login`
+- Codex: `CODEX_HOME=<path> codex auth login`
+- Gemini: `GEMINI_CLI_HOME=<path> gemini auth login`
+- OpenCode: `OPENCODE_CONFIG_DIR=<path> opencode auth login`
+
+**Step 5e: Ask for priority order and fallback.**
+
+Only if the user has 2+ backends:
+
+```
+questions: [
+  {
+    header: "Backend Priority",
+    question: "Which AI backend should GRD try first?",
+    multiSelect: false,
+    options: [
+      // Only show backends the user configured accounts for:
+      { label: "Claude first, then Codex", description: "Try Claude accounts first; use Codex if all Claude accounts hit rate limits" },
+      { label: "Codex first, then Claude" }
+    ]
+  },
+  {
+    header: "Fallback",
+    question: "If ALL your accounts are rate-limited, which backend should GRD fall back to?",
+    multiSelect: false,
+    options: [
+      { label: "Same as primary (wait for recovery)", description: "GRD waits up to 90 minutes for an account to recover — recommended" },
+      { label: "Gemini", description: "Use Gemini as a last resort" },
+      { label: "OpenCode", description: "Use OpenCode as a last resort" }
+    ]
+  }
+]
+```
+
+If the user only has one backend (e.g., 3 Claude accounts but no Codex), skip the priority question.
+
+**Step 5f: Validate each path.**
+
+For each config directory the user entered:
+
+```bash
+test -d "<path>" && echo "OK" || echo "MISSING"
+```
+
+If missing:
+
+```
+⚠ <path> does not exist yet.
+
+  To create it and authenticate:
+    CLAUDE_CONFIG_DIR=<path> claude auth login
+
+  Include it anyway? (You can authenticate later)  [Yes / No]
+```
+
+**Step 5g: Confirm and write config.**
+
+Show a summary before writing:
+
+```
+Account rotation configuration:
+
+  Claude (3 accounts):
+    1. ~/.claude (validated ✓)
+    2. ~/.claude-personal (validated ✓)
+    3. ~/.claude-work (validated ✓)
+
+  Priority: claude
+  Fallback: wait for recovery (max 90 min)
+
+  Token optimization: balanced (change later with `gd settings token_profile`)
+
+  Save this configuration? [Yes / No]
+```
+
+If "No" → let user re-enter.
+
+**Step 5h: If "No" to rotation or single account, configure minimal defaults.**
+
+Write a scheduler config with no rotation:
+
+```json
+{
+  "scheduler": {
+    "backend_priority": ["claude"],
+    "free_fallback": { "backend": "claude" }
+  }
+}
+```
+
+No `superpowers.accounts` needed. The scheduler still provides token tracking, rate-limit wait-for-recovery, budget pressure detection, and idle watchdog — just without multi-account rotation.
+
+**Conditional: If "Overstory" selected, ask sub-options:**
+
+```
+questions: [
+  {
+    header: "Runtime",
+    question: "Overstory runtime adapter for workers?",
+    multiSelect: false,
+    options: [
+      { label: "claude (Default)", description: "Claude Code as the worker runtime" },
+      { label: "codex", description: "OpenAI Codex as the worker runtime" },
+      { label: "cursor", description: "Cursor as the worker runtime" },
+      { label: "copilot", description: "GitHub Copilot as the worker runtime" }
+    ]
+  },
+  {
+    header: "Merge Strategy",
+    question: "Merge strategy for completed agent results?",
+    multiSelect: false,
+    options: [
+      { label: "Auto (Default)", description: "FIFO merge queue — automatically merge as agents complete" },
+      { label: "Manual", description: "Prompt for confirmation before each merge" }
+    ]
+  }
+]
+```
+
+Create `.planning/config.json` with all settings:
+
+```json
+{
+  "mode": "yolo|interactive",
+  "depth": "quick|standard|comprehensive",
+  "parallelization": true|false,
+  "commit_docs": true|false,
+  "model_profile": "quality|balanced|budget",
+  "autonomous_mode": false,
+  "backend": "grd|superpowers|overstory|claude|codex|gemini|opencode",
+  "workflow": {
+    "research": true|false,
+    "plan_check": true|false,
+    "verifier": true|false
+  },
+  "research_gates": {
+    "verification_design": true|false,
+    "method_selection": true|false,
+    "baseline_review": true|false
+  },
+  "superpowers": {
+    "default_backend": "claude|codex|gemini|opencode",
+    "account_rotation": true|false,
+    "accounts": {
+      // Populated from Round 5 auto-detection + user selection:
+      "claude": [{ "config_dir": "~/.claude" }, { "config_dir": "~/.claude-personal" }],
+      "codex": [{ "config_dir": "~/.codex" }]
+    }
+  },
+  "scheduler": {
+    "backend_priority": ["claude", "codex", "gemini", "opencode"],
+    "free_fallback": { "backend": "opencode" },
+    "prediction": {
+      "window_minutes": 15,
+      "ewma_alpha": 0.3,
+      "safety_margin_tasks": 1.5,
+      "min_samples": 3
+    }
+  },
+  "overstory": {
+    "runtime": "claude|codex|cursor|copilot",
+    "merge_strategy": "auto|manual",
+    "poll_interval_ms": 5000
+  }
+}
+```
+
+Include `superpowers` section only when backend is "superpowers".
+Include `scheduler` section only when backend is "superpowers" and account_rotation is true.
+Include `overstory` section only when backend is "overstory".
+
+Superpowers Accounts:
+- Parse comma-separated paths for each backend
+- For each non-empty backend, create `superpowers.accounts.<backend>` array of `{ config_dir: "<path>" }` objects
+- Empty entries are omitted from config
+
+Backend Priority:
+- Parse comma-separated backend names → `scheduler.backend_priority` array
+- Only include backends that have accounts configured
+
+Free Fallback:
+- "OpenCode (Default)" → `scheduler.free_fallback: { "backend": "opencode" }`
+- "Claude Code" → `scheduler.free_fallback: { "backend": "claude" }`
+- "Codex" → `scheduler.free_fallback: { "backend": "codex" }`
+- "Gemini" → `scheduler.free_fallback: { "backend": "gemini" }`
+
+Prediction defaults are always included in `scheduler.prediction` — these are sensible defaults that users rarely need to change.
+When reconfiguring an existing project (`project_exists` is true), merge new values into existing config — do not overwrite unrelated fields.
+
+**If commit_docs = No:**
+- Set `commit_docs: false` in config.json
+- Add `.planning/` to `.gitignore` (create if needed)
+
+**If commit_docs = Yes:**
+- No additional gitignore entries needed
+
+**Commit config.json:**
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "chore: add project config" --files .planning/config.json
+```
+
+**Note:** Run `/grd:settings` anytime to update these preferences.
+
+## 5.5. Resolve Model Profile
+
+Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
+
+## 6. Research Decision
+
+**If auto mode or YOLO 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:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► 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)
+
+Display spawning indicator:
+```
+* Spawning 4 researchers in parallel...
+  -> Stack research
+  -> Features research
+  -> Architecture research
+  -> Pitfalls research
+```
+
+Spawn 4 parallel grd-project-researcher agents with rich context:
+
+```
+Task(prompt="First, read ${CLAUDE_PLUGIN_ROOT}/agents/grd-project-researcher.md for your role and instructions.
+
+PATHS:
+research_dir: ${research_dir}
+codebase_dir: ${codebase_dir}
+phases_dir: ${phases_dir}
+
+<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>
+
+<project_context>
+[PROJECT.md summary - core value, constraints, what they're building]
+</project_context>
+
+<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_PLUGIN_ROOT}/templates/research-project/STACK.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
+
+Task(prompt="First, read ${CLAUDE_PLUGIN_ROOT}/agents/grd-project-researcher.md for your role and instructions.
+
+PATHS:
+research_dir: ${research_dir}
+codebase_dir: ${codebase_dir}
+phases_dir: ${phases_dir}
+
+<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>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<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_PLUGIN_ROOT}/templates/research-project/FEATURES.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
+
+Task(prompt="First, read ${CLAUDE_PLUGIN_ROOT}/agents/grd-project-researcher.md for your role and instructions.
+
+PATHS:
+research_dir: ${research_dir}
+codebase_dir: ${codebase_dir}
+phases_dir: ${phases_dir}
+
+<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>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<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_PLUGIN_ROOT}/templates/research-project/ARCHITECTURE.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
+
+Task(prompt="First, read ${CLAUDE_PLUGIN_ROOT}/agents/grd-project-researcher.md for your role and instructions.
+
+PATHS:
+research_dir: ${research_dir}
+codebase_dir: ${codebase_dir}
+phases_dir: ${phases_dir}
+
+<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>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<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_PLUGIN_ROOT}/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>
+
+<research_files>
+Read these files:
+- ${research_dir}/STACK.md
+- ${research_dir}/FEATURES.md
+- ${research_dir}/ARCHITECTURE.md
+- ${research_dir}/PITFALLS.md
+</research_files>
+
+PATHS:
+research_dir: ${research_dir}
+codebase_dir: ${codebase_dir}
+phases_dir: ${phases_dir}
+
+<output>
+Write to: ${research_dir}/SUMMARY.md
+Use template: ${CLAUDE_PLUGIN_ROOT}/templates/research-project/SUMMARY.md
+Commit after writing.
+</output>
+", subagent_type="grd:grd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+```
+
+Display research complete banner and key findings:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► 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:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► 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 or YOLO 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 name]"
+- 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 `.planning/REQUIREMENTS.md` 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_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
+```
+
+## 8. Create Roadmap
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+* Spawning roadmapper...
+```
+
+Spawn grd-roadmapper agent with context:
+
+```
+Task(prompt="
+<planning_context>
+
+**Project:**
+@.planning/PROJECT.md
+
+**Requirements:**
+@.planning/REQUIREMENTS.md
+
+**Research (if exists):**
+@${research_dir}/SUMMARY.md
+
+**Config:**
+@.planning/config.json
+
+</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="grd:grd-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 or YOLO 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]
+
+  Current ROADMAP.md: @.planning/ROADMAP.md
+
+  Update the roadmap based on feedback. Edit files in place.
+  Return ROADMAP REVISED with changes made.
+  </revision>
+  ", subagent_type="grd:grd-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
+  ```
+- Present revised roadmap
+- Loop until user approves
+
+**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
+
+**Commit roadmap (after approval or auto/YOLO mode):**
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+## 8.5. Product-Level Quality Targets
+
+**After roadmap is committed, offer product-level planning:**
+
+**If YOLO mode:** Skip — quality targets will be set during eval planning.
+
+Use AskUserQuestion:
+- header: "Quality Targets"
+- question: "Set product-level quality targets now? These define success metrics for the whole project."
+- options:
+  - "Set targets now" — Define metrics, baselines, and targets
+  - "Skip for now" — Set targets during phase planning instead
+
+**If "Set targets now":**
+```
+Run `/grd:product-plan` to create product-level quality targets
+```
+
+## 8.7. Baseline Assessment
+
+**If `has_existing_code` is true (brownfield):**
+
+**If YOLO mode:** Auto-run baseline assessment.
+
+Use AskUserQuestion:
+- header: "Baseline"
+- question: "Assess current code quality baseline? This measures where you are now so improvements are measurable."
+- options:
+  - "Assess baseline" — Run quantitative assessment of current code
+  - "Skip baseline" — Start fresh without baseline measurements
+
+**If "Assess baseline":**
+```
+Run `/grd:assess-baseline` to establish performance baseline
+```
+
+## 8.9. Long-Term Roadmap
+
+**After roadmap is committed, offer long-term roadmap creation:**
+
+**If YOLO mode:** Skip — LT roadmap can be created later.
+
+Check if LONG-TERM-ROADMAP.md already exists:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap list --raw 2>/dev/null
+```
+
+**If no LT roadmap exists:**
+
+Use AskUserQuestion:
+- header: "LT Roadmap"
+- question: "Create a long-term roadmap? This groups milestones into strategic LT milestones for multi-milestone planning."
+- options:
+  - "Create LT roadmap" — Initialize from current milestones and define future LT milestones
+  - "Skip for now" — Create later with `/grd:long-term-roadmap init`
+
+**If "Create LT roadmap":**
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap init
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: initialize long-term roadmap" --files .planning/LONG-TERM-ROADMAP.md
+```
+Display the created roadmap and offer refinement:
+```
+Long-term roadmap created. Use `/grd:long-term-roadmap add` to add more LT milestones.
+```
+
+## 9. Done
+
+Present completion with next steps:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► PROJECT INITIALIZED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**[Project Name]**
+
+| Artifact          | Location                       |
+|-------------------|--------------------------------|
+| Project           | `.planning/PROJECT.md`         |
+| Config            | `.planning/config.json`        |
+| Research          | `${research_dir}/`             |
+| Research Landscape| `${research_dir}/LANDSCAPE.md` |
+| Papers Registry   | `${research_dir}/PAPERS.md`    |
+| Benchmarks        | `${research_dir}/BENCHMARKS.md`|
+| Know-How          | `${research_dir}/KNOWHOW.md`   |
+| Requirements      | `.planning/REQUIREMENTS.md`    |
+| Roadmap           | `.planning/ROADMAP.md`         |
+
+**[N] phases** | **[X] requirements** | Ready to build
+
+---
+
+## Next Up
+
+**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
+
+/grd:discuss-phase 1 — gather context and clarify approach
+
+<sub>/clear first -> fresh context window</sub>
+
+---
+
+**Also available:**
+- /grd:plan-phase 1 — skip discussion, plan directly
+- /grd:survey — scan research landscape for your domain
+- /grd:assess-baseline — measure current code quality (if brownfield)
+
+---
+```
+
+</process>
+
+<output>
+
+- `.planning/PROJECT.md`
+- `.planning/config.json`
+- `${research_dir}/` (if research selected)
+  - `STACK.md`
+  - `FEATURES.md`
+  - `ARCHITECTURE.md`
+  - `PITFALLS.md`
+  - `SUMMARY.md`
+- `${research_dir}/LANDSCAPE.md`
+- `${research_dir}/PAPERS.md`
+- `${research_dir}/BENCHMARKS.md`
+- `${research_dir}/KNOWHOW.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
+
+</output>
+
+<success_criteria>
+
+- [ ] .planning/ directory created
+- [ ] Git repo initialized
+- [ ] Brownfield detection completed
+- [ ] Deep questioning completed (threads followed, not rushed) — or skipped in YOLO mode
+- [ ] PROJECT.md captures full context -> **committed**
+- [ ] Research landscape initialized (LANDSCAPE.md, PAPERS.md, BENCHMARKS.md, KNOWHOW.md) -> **committed**
+- [ ] config.json has workflow mode, depth, parallelization, research_gates, autonomous_mode -> **committed**
+- [ ] Research completed (if selected) — 4 parallel agents spawned -> **committed**
+- [ ] Requirements gathered (from research or conversation)
+- [ ] User scoped each category (v1/v2/out of scope) — or auto-scoped in YOLO mode
+- [ ] REQUIREMENTS.md created with REQ-IDs -> **committed**
+- [ ] grd-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
+- [ ] Product-level quality targets offered (if interactive)
+- [ ] Baseline assessment offered (if brownfield)
+- [ ] Long-term roadmap creation offered (if interactive)
+- [ ] User knows next step is `/grd:discuss-phase 1`
+
+**Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
+
+</success_criteria>