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.
Read all files referenced by the invoking prompt's execution_context before starting.
Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
- gsd-project-researcher — Researches project-level technical decisions
- gsd-research-synthesizer — Synthesizes findings from parallel research agents
- gsd-roadmapper — Creates phased execution roadmaps
If `section_manifest` is `null` or `"auto-mode-detection"` is in its `included` list: read and execute `gsd-core/workflows/new-project/steps/auto-mode-detection.md`. Otherwise skip — do not read the file.
## 1. Setup
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
```bash
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @therocketcode/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@therocketcode/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @therocketcode/gsd-core - it is either a different package or an @therocketcode/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
AUTO_PARAM=""; if [[ "$ARGUMENTS" =~ (^|[[:space:]])--auto([[:space:]]|$) ]]; then AUTO_PARAM="--auto"; fi
INIT=$(gsd_run query init.new-project $AUTO_PARAM)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS_RESEARCHER=$(gsd_run query agent-skills gsd-project-researcher)
AGENT_SKILLS_SYNTHESIZER=$(gsd_run query agent-skills gsd-research-synthesizer)
AGENT_SKILLS_ROADMAPPER=$(gsd_run query agent-skills gsd-roadmapper)
```
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_design_hint`, `design_pointer`, `design_hint_source`, `design_dismissed`, `has_git`, `git_worktree_root`, `in_nested_subdir`, `project_path`, `project_root`, `agents_installed`, `missing_agents`, `agent_runtime`, `agents_dir`, `requirements_exists`, `init_incomplete`, `requirements_path`, `roadmap_path`, `config_path`, `research_dir`, `response_language`. (This is the key set `init.new-project` actually emits — do not expect others.)
**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
**If `agents_installed` is false:** Display a warning before proceeding:
```text
⚠ GSD agents not installed. The following agents are missing from your agents directory:
{missing_agents joined with newline}
Runtime checked: {agent_runtime}
Agents directory checked: {agents_dir}
Subagent spawns (gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper) will fail
with "agent type not found" while they are missing. Run the installer with --global to make agents available:
npx @therocketcode/gsd-core@latest --global
Proceeding without research subagents — roadmap will be generated inline.
```
Skip Steps 6–7 (parallel research and synthesis) and proceed directly to roadmap creation in Step 8.
**Detect runtime and set instruction file name:**
Derive `RUNTIME` from the invoking prompt's `execution_context` path:
- Path contains `/.codex/` → `RUNTIME=codex`
- Path contains `/.gemini/` → `RUNTIME=gemini`
- Path contains `/.config/opencode/` or `/.opencode/` → `RUNTIME=opencode`
- Path contains `/.trae/` → `RUNTIME=trae`
- Otherwise → `RUNTIME=claude`
If `execution_context` path is not available, fall back to env vars:
```bash
if [ -n "$CODEX_HOME" ]; then RUNTIME="codex"
elif [ -n "$GEMINI_CONFIG_DIR" ]; then RUNTIME="gemini"
elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then RUNTIME="opencode"
elif [ -n "$TRAE_CONFIG_DIR" ]; then RUNTIME="trae"
else RUNTIME="claude"; fi
```
Set the instruction file variable via the shared runtime-name policy adapter (`gsd_run query project-instruction-file`, backed by `getProjectInstructionFile` in `runtime-name-policy.cjs` — the single source of truth shared with `profile-output.cjs`):
```bash
INSTRUCTION_FILE=$(gsd_run query project-instruction-file --runtime "$RUNTIME")
```
All subsequent references to the project instruction file use `$INSTRUCTION_FILE`.
**If `project_exists` is true and `init_incomplete` is true (#4040 — interrupted bootstrap):** Resume initialization instead of erroring. `.planning/` exists but initialization stopped before all core artifacts landed. Keep the existing `PROJECT.md` and any already-created artifacts (`REQUIREMENTS.md` if present, `config.json`); skip the steps that would recreate them and continue the flow from the first missing artifact in init order — `REQUIREMENTS.md` → `ROADMAP.md` + `STATE.md` — until all exist. Do not error and do not bounce the user back to `/gsd:progress` (that routing loop is the #4040 bug).
**Roadmap-after-strategy caveat:** in this fork `ROADMAP.md` and `STATE.md` are written by the `gsd-roadmap` skill after the strategy chain, never by this workflow (Step 8). A `.planning/` with PROJECT.md (carrying a `## Strategy Plan`) and REQUIREMENTS.md but no ROADMAP.md/STATE.md is **mid-chain, not an interrupted bootstrap** — `/gsd:progress` detects that shape first and points at the next strategy step or the roadmap skill. When resuming here, stop after REQUIREMENTS.md exists and hand off via Steps 7.6/9.
**If `project_exists` is true and `init_incomplete` is false:** Error — project already initialized. Use `/gsd:progress`.
**Git init (#3491 — never nest `.git` inside an existing worktree):**
- If `has_git` true and `in_nested_subdir` true: skip `git init`; warn `⚠ Initializing inside existing worktree (${git_worktree_root}); planning files will track to outer repo.`
- If `has_git` true and `in_nested_subdir` false: skip `git init` (already at worktree root).
- If `has_git` false: `git init`.
## 2. Brownfield Offer
**If auto mode:** Skip the interactive router and go to Step 4, but set Origin from `is_brownfield`/`has_existing_code` (existing code → brownfield-extend; else greenfield) — do not blindly assume greenfield. Synthesize PROJECT.md from the provided document.
If `section_manifest` is `null` or `"codebase-map-offer"` is in its `included` list: read and execute `gsd-core/workflows/new-project/steps/codebase-map-offer.md`. Otherwise skip — do not read the file.
**Provided-design detection (runs regardless of whether there is existing code — the design axis is orthogonal to Origin).** A provided design is a source of truth and must be detected + routed here, symmetric to the legacy path above — otherwise it gets laundered into vision-derived requirements and the build drifts from it (the address-failure: one design input → an invented multi-field schema). Init pre-detects the signal — branch on it (it is a **hint that you CONFIRM**, never a silent lock):
- **`design_dismissed` is true** (user passed `--no-design`) → Design-input: none; skip the prompt.
- **`has_design_hint` is true and `design_hint_source` is `arg`** (an explicit `--design `) → confirm by showing `design_pointer`, default Yes → record it.
- **`has_design_hint` is true with a weaker source** (`design-export` / `tokens-file` / `designs-dir`) → ask once with the detected `design_pointer` **pre-filled** so a false positive is one keystroke to reject: "I found `{design_pointer}` — is that a design to build to?"
- **`has_design_hint` is false** → still ask once (covers a Figma/Stitch URL the user will paste, which init can't detect), unless the user already said there's none.
- header: "Provided design"
- question: "Do you have a provided design or prototype to build to (Figma, an export, a clickable prototype, a tokens/component package)?"
- options:
- "Yes — here's the path/link" — record it → Step 4 sets `## Mode` Design-input to the pointer; the design is the authority on the observable shape
- "An existing design system to honor" — record it → Design-input = existing system
- "No / none" — Design-input: none
**If a provided design is recorded:** (a) record its pointer in `## Mode` Design-input (Step 4); (b) **ground requirements (Steps 3 + 7) by reading the design directly** — the pointer, per `@~/.claude/gsd-core/references/design-ingestion.md` — deriving them from **(the design) ∪ (the vision)**, lifting the design's literal user-facing fields and never generalizing them (mirrors the legacy `design ∪ old-behavior` rule); (c) the design is ingested into the in-repo oracle (`.planning/DESIGN-INVENTORY.md`) by the **next strategy step**, not here — Step 7.6 puts `model-domain` (or `frontend-architecture` for a frontend surface) first in the `## Strategy Plan` and auto-advances into it, and it writes the oracle before the build loop's design-fidelity gate runs (the planner is the fallback if both are skipped). **Do NOT run `model-domain` mid-new-project** — it reads the PROJECT.md/REQUIREMENTS that Steps 4/7 write, so it can only run after; the recorded design pointer + the Step-7.6 on-ramp are the correct mechanism (unlike `legacy-inventory`, which is a true pre-step because it reads only the old code).
If `section_manifest` is `null` or `"auto-mode-config"` is in its `included` list: read and execute `gsd-core/workflows/new-project/steps/auto-mode-config.md`. Otherwise skip — do not read the file.
## 2b. Prior Spike/Sketch Detection
Check for existing spike and sketch work that should inform project setup:
```bash
# Check for spike findings skill (project-local)
SPIKE_SKILL=$(ls ./.claude/skills/spike-findings-*/SKILL.md 2>/dev/null | head -1 || true)
# Check for sketch findings skill (project-local)
SKETCH_SKILL=$(ls ./.claude/skills/sketch-findings-*/SKILL.md 2>/dev/null | head -1 || true)
# Check for raw spikes/sketches in .planning/
HAS_SPIKES=$(ls .planning/spikes/MANIFEST.md 2>/dev/null)
HAS_SKETCHES=$(ls .planning/sketches/MANIFEST.md 2>/dev/null)
```
If any of these exist, surface them before questioning:
```
⚡ Prior exploration detected:
{if SPIKE_SKILL} ✓ Spike findings skill: {path} — validated patterns from experiments
{if SKETCH_SKILL} ✓ Sketch findings skill: {path} — validated design decisions
{if HAS_SPIKES && !SPIKE_SKILL} ◆ Raw spikes in .planning/spikes/ — consider `/gsd:spike --wrap-up` to package findings
{if HAS_SKETCHES && !SKETCH_SKILL} ◆ Raw sketches in .planning/sketches/ — consider `/gsd:sketch --wrap-up` to package findings
These findings will be incorporated into project context and available to planning agents.
```
If spike/sketch findings skills exist, read their SKILL.md files to inform the questioning phase — they contain validated patterns, constraints, and design decisions that should shape the project definition.
## 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:**
```
### GSD ► QUESTIONING
```
**If `.planning/PRODUCT-BRIEF.md` exists, read it first.** It is a validated product definition from `/gsd:discover-product` (outcome, target user, narrowest wedge, demand evidence, four-risks status, prioritized scope, explicit "not in scope"). Ground the questioning in it — **confirm and fill gaps rather than re-asking what it already answers** — and carry its outcome, wedge, and prioritized scope into PROJECT.md (Core Value / What This Is) and the requirements (Steps 4 and 7). Frame PROJECT.md around the brief's *outcome*, not a re-derived feature list.
**If `.planning/LEGACY-INVENTORY.md` exists** (rewrite/refactor/vibe-coded mode, from `/gsd:legacy-inventory`), read it too and **derive requirements from (the design) ∪ (the old-system behavior)** per its coverage matrix + three-way gap map — never from the design alone. Honor its **"never lose a feature" gate** (every old capability becomes a requirement or an explicitly-dropped item with the user's prior sign-off) and carry its salvage dispositions + source-of-truth precedence into the requirements (Steps 4 and 7).
**If a provided design is recorded (Step 2's design detection),** **read the design directly** — the `## Mode` Design-input pointer, per `@~/.claude/gsd-core/references/design-ingestion.md` (the in-repo oracle doesn't exist yet; `model-domain`/`frontend-architecture` write it as the next strategy step) — and **derive requirements from (the design) ∪ (the vision)**: lift its literal user-facing fields (a single `address` input is one `address` field, not four), never generalize or invent beyond them, and never drop a design-shown field. The design is the authority on the observable shape (§ Source precedence in `@~/.claude/gsd-core/references/exploration-and-adaptability.md`).
**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.
**Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in `.planning/config.json` (or the config from init context). When enabled, before asking follow-up questions about a topic area:
1. Do a brief web search for best practices related to what the user described
2. Mention key findings naturally as you ask questions (e.g., "Most projects like this use X — is that what you're thinking, or something different?")
3. This makes questions more informed without changing the conversational flow
When disabled (default), ask questions directly as before.
**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.
After each elicitation round, append it to `.planning/PROJECT-DISCUSSION-LOG.md` per `gsd-core/references/context-lifecycle.md` (skip if `context_lifecycle.discussion_logs` is disabled). When the log exists at commit time, include `.planning/PROJECT-DISCUSSION-LOG.md` in the PROJECT.md docs commit below — the log is the durable record of the reasoning and must not be left untracked.
## 4. Write PROJECT.md
**If auto mode:** Synthesize from provided document. No "Ready?" gate was shown — proceed directly to commit.
Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
**Fill the `## Mode` section (the persisted mode-combination — read by every downstream strategy/build skill so they don't re-detect).** Detect the three orthogonal dimensions per `@~/.claude/gsd-core/references/exploration-and-adaptability.md`, using the init signals + the conversation + any PRODUCT-BRIEF / provided design:
- **Origin:** greenfield (no existing code) · brownfield-extend (`is_brownfield`/`has_existing_code` and the intent is to *add to* it) · rewrite/refactor (existing code but the intent is to *replace* it).
- **Design input:** none · a provided design to ingest (a design-tool export / prototype / generated-design artifact the user supplied) · an existing design system to honor.
- **Code-quality baseline:** clean · legacy-debt · vibe-coded-to-harden (AI-prototyped, thin on tests/seams).
Record the named combination (e.g. "greenfield-rewrite + new-design + salvageable-old-code"). When a dimension is genuinely unclear, ask one targeted question rather than guessing.
**Record `## Sources` rows (the literal-source registry) as you fill `## Mode`.** One line per literal source this project grounds in — `- · — `, kinds `design` / `legacy` / `vibe` / `context-app`:
- provided design → `- design · — ` (mirrors Design-input);
- Origin rewrite/refactor → `- legacy · — behavior source (rewrite)`;
- Code-quality vibe-coded-to-harden → `- vibe · — intent source; do not pin its behavior`;
- any additional reference/context app the user pointed at → `- context-app · — `.
`gsd_run query grounding required` reads these (the `sources` field) and downstream agents explore them directly — an unrecorded source is invisible to the grounding loop.
**Multi-surface nudge.** If you detect multiple *independent* surfaces with genuinely different archetypes (e.g. a backend service **and** a separate frontend app **and** a CLI in one repo), say so: GSD models **one surface per project** (`@~/.claude/gsd-core/references/strategy-flow.md`). Recommend running GSD **per package/surface**, or ask the user to pick the **primary** surface for this project and record its Mode — do not average divergent surfaces into one Mode.
**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 `.planning/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*
```
**Evolution section** (include at the end of PROJECT.md, before the footer):
```markdown
## Evolution
This document evolves at phase transitions and milestone boundaries.
**After each phase transition** (via `/gsd-transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted
**After each milestone** (via `/gsd:complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state
```
Do not compress. Capture everything gathered.
**Commit PROJECT.md:**
```bash
mkdir -p .planning
gsd_run query commit "docs: initialize project" --files .planning/PROJECT.md
```
## 5. Workflow Preferences
**If auto mode:** Skip — config was collected in Step 2a. Proceed to Step 5.5.
**Check for global defaults** at `~/.gsd/defaults.json`. If the file exists, read and display its contents before asking:
```bash
DEFAULTS_RAW=$(cat ~/.gsd/defaults.json 2>/dev/null)
```
Format the JSON into human-readable bullets using these label mappings:
- `mode` → "Mode"
- `granularity` → "Granularity"
- `parallelization` → "Execution" (`true` → "Parallel", `false` → "Sequential")
- `commit_docs` → "Git Tracking" (`true` → "Yes", `false` → "No")
- `model_profile` → "AI Models"
- `workflow.research` → "Research" (`true` → "Yes", `false` → "No")
- `workflow.plan_check` → "Plan Check" (`true` → "Yes", `false` → "No")
- `workflow.verifier` → "Verifier" (`true` → "Yes", `false` → "No")
- `plan_review.source_grounding` → "Drift Guard" (`true` → "Yes", `false` → "No")
Display above the prompt:
```text
Your saved defaults (~/.gsd/defaults.json):
• Mode: [value]
• Granularity: [value]
• Execution: [Parallel|Sequential]
• Git Tracking: [Yes|No]
• AI Models: [value]
• Research: [Yes|No]
• Plan Check: [Yes|No]
• Verifier: [Yes|No]
• Drift Guard: [Yes|No]
```
Then ask:
```text
AskUserQuestion([
{
question: "Use these saved defaults?",
header: "Defaults",
multiSelect: false,
options: [
{ label: "Use as-is (Recommended)", description: "Proceed with the defaults shown above" },
{ label: "Modify some settings", description: "Keep defaults, change a few" },
{ label: "Configure fresh", description: "Walk through all questions from scratch" }
]
}
])
```
**If "Use as-is":** use the defaults values for config.json and skip directly to **Commit config.json** below.
**If "Modify some settings":** present a selection of every setting with its current saved value.
**If TEXT_MODE is active** (non-Claude runtimes): display a numbered list and ask the user to type the numbers of settings they want to change (comma-separated). Parse the response and proceed.
```text
Which settings do you want to change? (enter numbers, comma-separated)
1. Mode — Currently: [value]
2. Granularity — Currently: [value]
3. Execution — Currently: [Parallel|Sequential]
4. Git Tracking — Currently: [Yes|No]
5. AI Models — Currently: [value]
6. Research — Currently: [Yes|No]
7. Plan Check — Currently: [Yes|No]
8. Verifier — Currently: [Yes|No]
9. Drift Guard — Currently: [Yes|No]
```
**Otherwise** (Claude runtime with AskUserQuestion): use a two-block split
to stay within the 4-option runtime cap.
```text
AskUserQuestion([
{
question: "Do you want to change any core workflow settings (Mode, Granularity, Execution, Git Tracking)?",
header: "Core Settings",
multiSelect: false,
options: [
{ label: "Yes", description: "Choose from core workflow settings" },
{ label: "No", description: "Skip core workflow settings" }
]
}
])
```
If "Yes", ask:
```text
AskUserQuestion([
{
question: "Which core workflow settings do you want to change?",
header: "Core Select",
multiSelect: true,
options: [
{ label: "Mode", description: "Currently: [value]" },
{ label: "Granularity", description: "Currently: [value]" },
{ label: "Execution", description: "Currently: [Parallel|Sequential]" },
{ label: "Git Tracking", description: "Currently: [Yes|No]" }
]
}
])
```
Then ask:
```text
AskUserQuestion([
{
question: "Do you want to change any model/agent settings (AI Models, Research, Plan Check, Verifier)?",
header: "Agent Settings",
multiSelect: false,
options: [
{ label: "Yes", description: "Choose from model/agent settings" },
{ label: "No", description: "Skip model/agent settings" }
]
}
])
```
If "Yes", ask:
```text
AskUserQuestion([
{
question: "Which model/agent settings do you want to change?",
header: "Agent Select",
multiSelect: true,
options: [
{ label: "AI Models", description: "Currently: [value]" },
{ label: "Research", description: "Currently: [Yes|No]" },
{ label: "Plan Check", description: "Currently: [Yes|No]" },
{ label: "Verifier", description: "Currently: [Yes|No]" }
]
}
])
```
Then ask:
```text
AskUserQuestion([
{
question: "Do you want to change the Drift Guard setting (plan-review source-grounding)?",
header: "Drift Guard",
multiSelect: false,
options: [
{ label: "Yes", description: "Toggle Drift Guard (currently: [Yes|No])" },
{ label: "No", description: "Keep current Drift Guard setting" }
]
}
])
```
For each selected setting across both blocks, ask only that question using the
option set from Round 1 / Round 2 below. Merge user answers over the saved
defaults — unchanged settings retain their saved values. Then skip to
**Commit config.json**.
**If "Configure fresh" or `~/.gsd/defaults.json` doesn't exist:** proceed with the questions below.
**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: "Granularity",
question: "How finely should scope be sliced into phases?",
multiSelect: false,
options: [
{ label: "Coarse", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
{ label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
{ label: "Fine", description: "Many focused phases (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" }
]
}
]
// Model profile uses a two-question split because AskUserQuestion enforces a hard
// 4-option cap and there are 5 valid profiles (quality, balanced, budget, adaptive,
// inherit). Q1 routes between adaptive/standard-tier/inherit; Q2 (shown only when
// Q1 = "Standard tier…") picks among the three standard profiles. Mirrors the
// /gsd:settings split (#3784, #1516).
questions: [
{
header: "AI Models",
question: "Which AI models for planning agents?",
multiSelect: false,
options: [
{ label: "Adaptive (Recommended)", description: "Role-based cost optimization: heavy roles use the highest-tier model available on the active runtime, light roles use the cheapest. Best balance of quality and cost across all supported runtimes (Claude, Codex, Gemini, OpenRouter, local)." },
{ label: "Standard tier…", description: "Choose Quality, Balanced, or Budget — flat tier applied to all agents" },
{ label: "Inherit", description: "Use the current session model for all agents (required for non-Claude runtimes: Codex, Gemini CLI, OpenCode /model, OpenRouter, local models)" }
]
}
]
**Conditional visibility — model_profile (Q2):**
Only ask this question when Q1's answer is "Standard tier…".
If Q1 = "Adaptive (Recommended)" → write model_profile=adaptive and SKIP Q2.
If Q1 = "Inherit" → write model_profile=inherit and SKIP Q2.
If user cancels Q2 after picking "Standard tier…" → leave existing model_profile value unchanged.
questions: [
{
question: "Which standard profile? (Quality / Balanced / Budget)",
header: "Model Tier",
multiSelect: false,
options: [
{ label: "Quality", description: "Opus everywhere except verification (highest cost) — Claude only" },
{ label: "Balanced", description: "Opus for planning, Sonnet for research/execution/verification — Claude only" },
{ label: "Budget", description: "Sonnet for writing, Haiku for research/verification (lowest cost) — Claude only" }
]
}
]
// Map UI choices → config values:
// Q1 "Adaptive (Recommended)" → model_profile = "adaptive"
// Q1 "Inherit" → model_profile = "inherit"
// Q1 "Standard tier…" + Q2 "Quality" → model_profile = "quality"
// Q1 "Standard tier…" + Q2 "Balanced" → model_profile = "balanced"
// Q1 "Standard tier…" + Q2 "Budget" → model_profile = "budget"
```
**PR body onboarding:** Ask which optional PRD-style sections `/gsd:ship` should append to generated PR bodies. Use the same `ship.pr_body_sections` mapping as Step 2a: selected sections get `enabled: true`, seeded-but-unselected sections get `enabled: false`, and selecting none writes an empty list. Prefer lean/agile PRD sections that make user value, acceptance criteria, Definition of Done, and stakeholder traceability explicit.
Recommended options:
- `User Stories & Acceptance Criteria`
- `Risks & Dependencies`
- `Success Metrics & Release Criteria`
- `Stakeholder Review & Approval`
Create `.planning/config.json` with all settings (CLI fills in remaining defaults automatically):
```bash
mkdir -p .planning
gsd_run query config-new-project '{"mode":"[yolo|interactive]","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"quality|balanced|budget|adaptive|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":[false if granularity=coarse, true otherwise]},"plan_review":{"source_grounding":true|false},"ship":{"pr_body_sections":[{"heading":"User Stories & Acceptance Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria","fallback":"- Acceptance criteria are covered by the linked requirements and verification evidence."},{"heading":"Risks & Dependencies","enabled":true|false,"source":"PLAN.md ## Risks || PLAN.md ## Dependencies","fallback":"- No known high-risk rollout dependencies."},{"heading":"Success Metrics & Release Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## Definition of Done || VERIFICATION.md ## Release Criteria","fallback":"- Release when automated verification and required manual checks pass."},{"heading":"Stakeholder Review & Approval","enabled":true|false,"template":"- Product owner approval pending for {phase_name}."}]}}'
```
**Note:** Run `/gsd:settings` anytime to update model profile, workflow agents, branching strategy, and other preferences.
**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
gsd_run query commit "chore: add project config" --files .planning/config.json
```
## 5.1. Sub-Repo Detection
**Detect multi-repo workspace:**
Check for directories with their own `.git` folders (separate repos within the workspace):
```bash
find . -maxdepth 1 -type d -not -name ".*" -not -name "node_modules" -exec test -d "{}/.git" \; -print
```
**If sub-repos found:**
Strip the `./` prefix to get directory names (e.g., `./backend` → `backend`).
Use AskUserQuestion:
- header: "Multi-Repo Workspace"
- question: "I detected separate git repos in this workspace. Which directories contain code that GSD should commit to?"
- multiSelect: true
- options: one option per detected directory
- "[directory name]" — Separate git repo
**If user selects one or more directories:**
- Set `planning.sub_repos` in config.json to the selected directory names array (e.g., `["backend", "frontend"]`)
- Auto-set `planning.commit_docs` to `false` (planning docs stay local in multi-repo workspaces)
- Add `.planning/` to `.gitignore` if not already present
Config changes are saved locally — no commit needed since `commit_docs` is `false` in multi-repo mode.
**If no sub-repos found or user selects none:** Continue with no changes to config.
## 5.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:
```
### GSD ► RESEARCHING
Researching [domain] ecosystem...
```
Create research directory:
```bash
mkdir -p .planning/research
```
**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... (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze)
→ Stack research
→ Features research
→ Architecture research
→ Pitfalls research
```
Spawn 4 parallel gsd-project-researcher agents with path references:
> **Model omission (#2517).** Omit the `model` parameter entirely when the value it would carry (`researcher_model`, `synthesizer_model`, `roadmapper_model`) is `"inherit"` or empty. An empty value 404s on runtimes without native tier aliases — the default on non-Claude runtimes. Omitting it inherits the orchestrator's model. See @gsd-core/references/model-profile-resolution.md.
```text
Agent(prompt="
Project Research — Stack dimension for [domain].
[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.
What's the standard 2025 stack for [domain]?
- {project_path} (Project context and goals)
${AGENT_SKILLS_RESEARCHER}
Your STACK.md feeds into roadmap creation. Be prescriptive:
- Specific libraries with versions
- Clear rationale for each choice
- What NOT to use and why
- [ ] Versions are current (verify with Context7/official docs, not training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Confidence levels assigned to each recommendation
> **Runtime-aware dispatch (#2508 Phase 4).** GSD workflows dispatch specialized subagents by role. Before dispatching on a built-in-only runtime (kimi-code — three built-ins only), resolve the role to a built-in via `gsd_run query resolve-dispatch-type --requested --raw`. On named-dispatch runtimes (Claude/OpenCode/…) the role is returned unchanged; on kimi-code it maps to `coder`/`explore`/`plan` by role-suffix. The persona rides `${AGENT_SKILLS_}` (Phase 3) regardless. See @gsd-core/references/runtime-aware-dispatch.md.
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Stack research")
Agent(prompt="
Project Research — Features dimension for [domain].
[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?
What features do [domain] products have? What's table stakes vs differentiating?
- {project_path} (Project context)
${AGENT_SKILLS_RESEARCHER}
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)
- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
- [ ] Complexity noted for each feature
- [ ] Dependencies between features identified
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Features research")
Agent(prompt="
Project Research — Architecture dimension for [domain].
[greenfield OR subsequent]
Greenfield: How are [domain] systems typically structured? What are major components?
Subsequent: How do [target features] integrate with existing [domain] architecture?
How are [domain] systems typically structured? What are major components?
- {project_path} (Project context)
${AGENT_SKILLS_RESEARCHER}
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)
- [ ] Components clearly defined with boundaries
- [ ] Data flow direction explicit
- [ ] Build order implications noted
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Architecture research")
Agent(prompt="
Project Research — Pitfalls dimension for [domain].
[greenfield OR subsequent]
Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
Subsequent: What are common mistakes when adding [target features] to [domain]?
What do [domain] projects commonly get wrong? Critical mistakes?
- {project_path} (Project context)
${AGENT_SKILLS_RESEARCHER}
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
- [ ] Pitfalls are specific to this domain (not generic advice)
- [ ] Prevention strategies are actionable
- [ ] Phase mapping included where relevant
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Pitfalls research")
```
> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all 4 researcher Agent() calls above, do NOT read research files or synthesize content independently while the subagents are active. Wait for all 4 researchers to complete before spawning the synthesizer. This prevents duplicate work and wasted context.
After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
```text
Agent(prompt="
Synthesize research outputs into SUMMARY.md.
- {research_dir}/STACK.md
- {research_dir}/FEATURES.md
- {research_dir}/ARCHITECTURE.md
- {research_dir}/PITFALLS.md
${AGENT_SKILLS_SYNTHESIZER}
", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
```
> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
**Synthesizer output self-heal (#222) — verify SUMMARY.md materialized:** The synthesizer's canonical output is `.planning/research/SUMMARY.md` on disk; its brief structured return (`## SYNTHESIS COMPLETE` plus a few `###` confirmation lines) is NOT the file content. A known LLM false-refusal (issue #222) sometimes makes the agent return the full SUMMARY.md document inline — fabricating a write restriction (e.g. "the runtime is blocking file writes") — instead of writing the file. Prompt hardening alone does not fully eliminate it, so the orchestrator MUST absorb the failure deterministically before spawning `gsd-roadmapper`:
1. Verify `.planning/research/SUMMARY.md` exists AND is substantive — non-empty, and free of any leftover `` continuation sentinel (which marks a truncated/incomplete write). You may validate with `gsd_run verify-summary .planning/research/SUMMARY.md` — it exits 0 regardless, so check its JSON `passed` field (`"passed": false` means missing or invalid), not the process exit code. If it passes, continue normally.
2. If it is MISSING or invalid AND the synthesizer's return message contains the FULL SUMMARY.md document — recognizable by the template's top-level markers `# Project Research Summary`, `## Key Findings`, `## Implications for Roadmap`, and `## Sources`, not merely the brief `## SYNTHESIS COMPLETE` confirmation — the false-refusal fired: write that returned document to `.planning/research/SUMMARY.md` with the Write tool, then commit ALL research artifacts the synthesizer owns (it commits on behalf of the four researchers) with `gsd_run query commit "docs: complete project research" --files .planning/research/` unless they are already committed. Log `⚠ #222 self-heal: synthesizer returned SUMMARY.md inline without writing it; orchestrator persisted the file.`
3. If it is MISSING or invalid AND the return is only a brief confirmation (no full SUMMARY document to recover), the synthesizer genuinely failed — surface the error and stop; do NOT spawn `gsd-roadmapper` against a missing or incomplete SUMMARY.md.
This guarantees `gsd-roadmapper` (which lists SUMMARY.md as required reading) never runs against a missing or truncated SUMMARY.md.
Display research complete banner and key findings:
```
### GSD ► RESEARCH COMPLETE ✓
## Key Findings
**Stack:** [from SUMMARY.md]
**Table Stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md]
Files: `.planning/research/`
```
**If "Skip research":** Continue to Step 7.
## 7. Define Requirements
Display stage banner:
```
### GSD ► 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 `.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
gsd_run query commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
```
## 7.5. Project Structure Mode
**If auto mode:** Set `PROJECT_MODE=mvp` and skip this prompt.
**Mode prompt: Vertical MVP vs Horizontal Layers.**
Ask the user how they want to structure the project. Use `AskUserQuestion` with two options:
- **Vertical MVP** — get a working app fast, add features slice by slice. Each phase delivers an end-to-end user capability. *(Recommended for new products and rapid-iteration MVPs.)*
- **Horizontal Layers** — build complete technical layers (DB → API → UI → wiring) and assemble at the end. *(Better for infrastructure-heavy projects with multiple developers.)*
Set `PROJECT_MODE=mvp` if the user picks Vertical MVP, otherwise `PROJECT_MODE=standard`.
**Persist the choice for the deferred roadmap.** The roadmap is no longer created here — it is generated after the strategy chain by `/gsd:roadmap` (`gsd-roadmap`), which runs in a later session and cannot see this shell variable. Record the choice as a marker in PROJECT.md so the deferred roadmap applies the correct per-phase template:
```bash
grep -qi 'roadmap-mode:' .planning/PROJECT.md 2>/dev/null || printf '\n\n' "$PROJECT_MODE" >> .planning/PROJECT.md
```
When `TEXT_MODE=true` (per the workflow's existing TEXT_MODE handling for non-Claude runtimes), present the same two options as a plain-text numbered list and ask the user to type their choice number.
## 7.6. Strategy Plan (the on-ramp into the strategy chain)
Context is now ready (PROJECT.md + `## Mode` + REQUIREMENTS + any PRODUCT-BRIEF), so recommend the **archetype-tailored strategy path** before building — this is the on-ramp the build loop depends on. **Read `@~/.claude/gsd-core/references/strategy-flow.md` now.**
1. **Derive the archetype** from `## Mode` (Origin × Design-input × Code-quality) + the surface axes (Surface · Domain richness · Security exposure · Deployment · Criticality). Read these from the brief/requirements/project; **ask only the axes nothing has answered** (one `AskUserQuestion`/`--text` screen, recommended defaults — e.g. "Will this deploy as a service, ship as a package, or run locally?"; "Does it handle payments/PII/regulated data?"). `--auto`: infer all axes from the docs, no prompt.
2. **Select the recommended path** from the matrix + overlays (brownfield/refactor/harden via `## Mode`; design-provided; the vibe-coded hardening playlist). It is always a subset/reorder of the canonical spine in `strategy-chain.md` — skipping `frontend-architecture` for backend/CLI, scaling `security-strategy` depth, etc.
3. **Write `## Strategy Plan`** into PROJECT.md (the archetype line, the ordered recommended steps with status `recommended`, and the skip-ledger scaffold) per the template.
4. **Present it** and let the user accept / customize / skip-to-build. A declined recommended step → a skip-ledger line (`- — skipped (, )`); enforcers note it once, don't re-nag. The build loop honors whatever artifacts exist, so a partial path is safe.
The Step-9 handoff then leads with the **first recommended step** of this plan. (The coarse roadmap below stays coarse; `plan-phase`'s elaboration gate refines it against whatever strategy artifacts get produced.)
## 8. Finalize project context
The roadmap is **no longer created here.** It is generated once, after the strategy chain, by `/gsd:roadmap` (`gsd-roadmap`) — so it is born fully-informed against the locked strategy artifacts instead of coarse-then-patched. This step just finalizes the project instruction file and commits the context artifacts; the Step-9 handoff routes into the strategy chain (or straight to `/gsd:roadmap` when no strategy steps are recommended).
**Generate or refresh project instruction file before final commit:**
```bash
gsd_run query generate-claude-md --output "$INSTRUCTION_FILE"
```
This ensures new projects get the default GSD workflow-enforcement guidance and current project context in `$INSTRUCTION_FILE`.
**Commit project context (ROADMAP.md / STATE.md do not exist yet — they are written later by `/gsd:roadmap`):**
```bash
gsd_run query commit "docs: finalize project context" --files .planning/PROJECT.md .planning/REQUIREMENTS.md "$INSTRUCTION_FILE"
```
## 9. Done
Present completion summary:
```
### GSD ► PROJECT INITIALIZED ✓
**[Project Name]**
| Artifact | Location |
|----------------|-----------------------------|
| Project | `.planning/PROJECT.md` |
| Config | `.planning/config.json` |
| Research | `.planning/research/` |
| Requirements | `.planning/REQUIREMENTS.md` |
| Roadmap | created after your strategy chain |
| Project guide | `$INSTRUCTION_FILE` |
**[N] phases** | **[X] requirements** | Ready to build ✓
```
**Determine the on-ramp from `## Strategy Plan`** (written in Step 7.6):
```bash
NEXT_STRATEGY=$(gsd_run query project strategy-plan --raw 2>/dev/null) # the first `recommended` step, or empty
```
`NEXT_STRATEGY` is the first step whose status is `recommended` (e.g. `model-domain`, `recommend-architecture`). If the plan has **no** recommended steps (prototype archetype, or the user skipped to build), it is empty → hand off to the build loop (the panels below).
**If auto mode:**
- **If `NEXT_STRATEGY` is set:** auto-advance **into the strategy chain** — exit and dispatch `Skill(skill="gsd-${NEXT_STRATEGY}", args="--auto")` (the Skill tool, never a `SlashCommand` — an interpolated `/gsd:${…}` name is invisible to the install-time slash-form converter and resolves to nothing on skill-only installs). That step, on completion, runs the **strategy auto-advance driver** (`@~/.claude/gsd-core/workflows/strategy-chain/modes/advance.md`) which dispatches the next `## Strategy Plan` step (honoring skips) and ultimately the build loop — so the chain runs hands-off, no longer dead-ending after the first step.
```
### AUTO-ADVANCING → STRATEGY: ${NEXT_STRATEGY}
```
- **Else** (no strategy steps recommended — prototype archetype, or the user skipped to build): there is no strategy chain to carry the transition, so create the roadmap now — exit and invoke `SlashCommand("/gsd:roadmap --auto")`. `gsd-roadmap` creates the roadmap (coarse, since no strategy artifacts exist) and then chains onward to `/gsd:discuss-phase 1 --auto`.
**If interactive mode AND `NEXT_STRATEGY` is set:**
```
---
## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
**Your strategy plan:** [the ordered `## Strategy Plan` steps]
/clear then:
/gsd:${NEXT_STRATEGY} — [one-line purpose] (first step of your strategy plan; it chains onward to the build loop)
---
**Also available:**
- /gsd:roadmap — skip strategy and start building directly (creates the roadmap now, then points to discuss-phase)
(declining a recommended step records a skip-ledger entry; the build loop honors whatever artifacts exist)
---
```
**If interactive mode AND `NEXT_STRATEGY` is empty** (straight to build):
No strategy chain carries this transition and no ROADMAP.md exists yet, so the next step is to create the roadmap. Point the user at `/gsd:roadmap` — it creates the roadmap (coarse, since no strategy artifacts exist) and then points onward to `/gsd:discuss-phase 1`:
```
---
## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
**[${PROJECT_CODE}] ${PROJECT_TITLE}** — requirements scoped; roadmap pending
/clear then:
/gsd:roadmap — generate the roadmap, then start building
---
```
- [ ] .planning/ directory created
- [ ] Git repo initialized
- [ ] Brownfield detection completed
- [ ] Deep questioning completed (threads followed, not rushed)
- [ ] PROJECT.md captures full context → **committed**
- [ ] config.json has workflow mode, granularity, parallelization → **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)
- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
- [ ] Roadmap **deferred** to `/gsd:roadmap` (created once after the strategy chain, born fully-informed) — not spawned here
- [ ] `` marker persisted in PROJECT.md (Step 7.5) so the deferred roadmap applies the correct MVP/standard template
- [ ] `$INSTRUCTION_FILE` generated with GSD workflow guidance (runtime-derived via the shared `getProjectInstructionFile` policy — `AGENTS.md` for codex/opencode/kilo/kimi, `.github/copilot-instructions.md` for copilot, `GEMINI.md` for gemini/antigravity, `.claude/CLAUDE.md` for claude; an existing hand-crafted file without GSD markers is left untouched unless `--force`)
- [ ] `## Strategy Plan` written from the archetype (Step 7.6); user directed to its first recommended step (or to `/gsd:roadmap` when no strategy steps are recommended)
**Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.