msd-core/gsd-core/workflows/new-project.md

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.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

<available_agent_types> 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 </available_agent_types>

<auto_mode>

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.

</auto_mode>

Compact Content Gate. Read and follow gsd-core/references/compact-content-gate.md now — it states the workflow.compact_content check and the resolution rule this spine defers to. When it directs a Read, read gsd-core/workflows/new-project/detail/elaboration.md in full before continuing past this point; its content elaborates on two sections below (Step 2b's prior spike/sketch detection, and Step 6's researcher/synthesizer prompts).

1. Setup

MANDATORY FIRST STEP — Execute these checks before ANY user interaction:

_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 @opengsd/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":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/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_git, git_worktree_root, in_nested_subdir, project_path, agents_installed, missing_agents, agent_runtime, agents_dir, required_agents, required_agents_installed, missing_required_agents, agent_skill_payloads_available, agent_skill_payload_agents, requirements_exists, init_incomplete, requirements_path, roadmap_path, config_path, research_dir, response_language.

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:

⚠ 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}
Required new-project agents missing:
  {missing_required_agents joined with newline, or "none"}

Agent skill payloads available: {agent_skill_payloads_available}
Agent skill payload agents:
  {agent_skill_payload_agents joined with newline, or "none"}

Skill payloads only provide prompt context. Named subagent spawns still require agent
definitions to be installed for this runtime.

Subagent spawns (gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper) will fail
with "agent type not found" if `required_agents_installed` is false. Run the installer with --global to make agents available:

  npx @opengsd/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:

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):

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).

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 to Step 4 (assume greenfield, synthesize PROJECT.md from 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.

If "Skip mapping" OR needs_codebase_map is false: Continue to Step 3.

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 a spike/sketch findings skill or raw .planning/{spikes,sketches}/MANIFEST.md files. If any exist, surface them before questioning (which findings-skill, if any, and any raw un-wrapped spikes/sketches worth /gsd:spike --wrap-up / /gsd:sketch --wrap-up), and if a findings skill exists, read its SKILL.md to inform the questioning phase — it carries validated patterns, constraints, and design decisions that should shape the project definition.

Exact detection commands and the surfaced-findings banner: gsd-core/workflows/new-project/detail/elaboration.md § 1.

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

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.

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.

For greenfield projects:

Initialize requirements as hypotheses:

## 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

## 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:

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| [Choice from questioning] | [Why] | — Pending |

Last updated footer:

---
*Last updated: [date] after initialization*

Evolution section (include at the end of PROJECT.md, before the footer):

## 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:

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:

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:

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:

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.

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.

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:

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:

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:

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:

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.

A fourth question in this same round covers Compact Content (#4139) — not a spawned agent, but grouped here because it's the last general workflow-behavior toggle before the more involved AI-models round below.

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: "Compact Content",
    question: "Use token-minimized instruction content where available? (smaller context footprint)",
    multiSelect: false,
    options: [
      { label: "No (Recommended)", description: "Full instruction detail loaded every time. Best while evaluating GSD or on a large context window." },
      { label: "Yes", description: "Terser instructions where a compact variant exists; canonical detail loads only when actually needed. Frees up context for long sessions or large codebases." }
    ]
  }
]

// 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):

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,"compact_content":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:

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 (separate repos within the workspace — this also finds linked git worktree children, whose .git is a file rather than a directory, unlike a plain find -type d predicate would):

gsd_run query init.new-project

Read the sub_repos_detected array from the JSON output — each entry is a bare directory name already relative to the workspace root (e.g. "backend").

If sub-repos found:

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:

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 — one per dimension (Stack, Features, Architecture, Pitfalls) — each given the domain and greenfield/subsequent milestone context, a dimension-specific question, a downstream-consumer note (what the next stage needs from this file), and a quality gate; each writes its own file (STACK.md / FEATURES.md / ARCHITECTURE.md / PITFALLS.md) under {research_dir}/ from its template.

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.

Model omission (#2517) applies to every one of these 5 spawns (4 researchers + synthesizer): omit the model= parameter entirely when the value it would carry (researcher_model, synthesizer_model) is "inherit" or empty — passing it literally 404s on runtimes without native tier aliases (the default on non-Claude runtimes). Omitting model= inherits the orchestrator's model.

After all 4 agents complete, spawn synthesizer to create SUMMARY.md:

Agent(prompt="
<task>
Synthesize research outputs into SUMMARY.md.
</task>

<required_reading>
- {research_dir}/STACK.md
- {research_dir}/FEATURES.md
- {research_dir}/ARCHITECTURE.md
- {research_dir}/PITFALLS.md
</required_reading>

${AGENT_SKILLS_SYNTHESIZER}

<output>
Write to: {research_dir}/SUMMARY.md
Use template: ~/.claude/gsd-core/templates/research-project/SUMMARY.md
Commit after writing.
</output>
", 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 <!-- gsd:write-continue --> 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.

Exact agent prompts (all four researcher dimensions): gsd-core/workflows/new-project/detail/elaboration.md § 2.

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:

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.

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.

8. Create Roadmap

Display stage banner:

### GSD ► CREATING ROADMAP

◆ Spawning roadmapper... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)

ROADMAP.md template — mode-aware emit. When generating the initial ROADMAP.md:

• If PROJECT_MODE=mvp: under each ### Phase N: header, emit **Mode:** mvp on the line immediately following **Goal:**. This sets every initial phase to MVP mode (per Phase-4-Persistence decision: per-phase mode, not project-wide config).
• If PROJECT_MODE=standard: emit the standard ROADMAP.md template with no **Mode:** lines (Horizontal Layers standard template — no behavioral change for users who pick Horizontal Layers).

Example MVP-mode emit for Phase 1:

### Phase 1: [Name]
**Goal:** [Goal]
**Mode:** mvp
**Success Criteria**:
1. [Criterion]

Pass PROJECT_MODE to the roadmapper so it applies the correct template.

Spawn gsd-roadmapper agent with path references:

Agent(prompt="
<planning_context>

<required_reading>
- {project_path} (Project context)
- {requirements_path} (v1 Requirements)
- {research_dir}/SUMMARY.md (Research findings - if exists)
- {config_path} (Granularity and mode settings)
</required_reading>

${AGENT_SKILLS_ROADMAPPER}

</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="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")

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.

Handle roadmapper return:

If ## ROADMAP BLOCKED:

• Present blocker information
• Work with user to resolve
• Re-spawn when resolved

If ## ROADMAP CREATED:

Read the created ROADMAP.md and present it nicely inline:

---

## Proposed Roadmap

**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓

| # | Phase | Goal | Requirements | Success Criteria |
|---|-------|------|--------------|------------------|
| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |
| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
...

### Phase Details

**Phase 1: [Name]**
Goal: [goal]
Requirements: [REQ-IDs]
Success criteria:
1. [criterion]
2. [criterion]
3. [criterion]

**Phase 2: [Name]**
Goal: [goal]
Requirements: [REQ-IDs]
Success criteria:
1. [criterion]
2. [criterion]

[... continue for all phases ...]

---

If auto mode: Skip approval gate — auto-approve and commit directly.

CRITICAL: Ask for approval before committing (interactive mode only):

Use AskUserQuestion:

• header: "Roadmap"
• question: "Does this roadmap structure work for you?"
• options:
  • "Approve" — Commit and continue
  • "Adjust phases" — Tell me what to change
  • "Review full file" — Show raw ROADMAP.md

If "Approve": Continue to commit.

If "Adjust phases":

• Get user's adjustment notes

• Re-spawn roadmapper with revision context:

  Agent(prompt="
  <revision>
  User feedback on roadmap:
  [user's notes]
  
  <required_reading>
  - {roadmap_path} (Current roadmap to revise)
  </required_reading>
  
  ${AGENT_SKILLS_ROADMAPPER}
  
  Update the roadmap based on feedback. Edit files in place.
  Return ROADMAP REVISED with changes made.
  </revision>
  ", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
  

  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.

• Present revised roadmap

• Loop until user approves

If "Review full file": Display raw cat .planning/ROADMAP.md, then re-ask.

Generate or refresh project instruction file before final commit:

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 roadmap (after approval or auto mode):

gsd_run query commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.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        | `.planning/ROADMAP.md`      |
| Project guide  | `$INSTRUCTION_FILE`         |

**[N] phases** | **[X] requirements** | Ready to build ✓

If auto mode:

### AUTO-ADVANCING → DISCUSS PHASE 1

Exit skill and invoke SlashCommand("/gsd:discuss-phase 1 --auto")

If interactive mode:

Check if Phase 1 has UI indicators (look for **UI hint**: yes in Phase 1 detail section of ROADMAP.md):

PHASE1_SECTION=$(gsd_run query roadmap.get-phase 1 2>/dev/null)
PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false")

If Phase 1 has UI (PHASE1_HAS_UI is true):

---

## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}

**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]

/clear then:

/gsd:discuss-phase 1 — gather context and clarify approach

---

**Also available:**
- /gsd:ui-phase 1 — generate UI design contract (recommended for frontend phases)
- /gsd:plan-phase 1 — skip discussion, plan directly

---

If Phase 1 has no UI:

---

## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}

**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]

/clear then:

/gsd:discuss-phase 1 — gather context and clarify approach

---

**Also available:**
- /gsd:plan-phase 1 — skip discussion, plan directly

---

• .planning/PROJECT.md
• .planning/config.json
• .planning/research/ (if research selected)
  • STACK.md
  • FEATURES.md
  • ARCHITECTURE.md
  • PITFALLS.md
  • SUMMARY.md
• .planning/REQUIREMENTS.md
• .planning/ROADMAP.md
• .planning/STATE.md
• $INSTRUCTION_FILE (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)

<success_criteria>

• .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
• gsd-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
• $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)
• User knows next step is /gsd:discuss-phase 1

Atomic commits: Each phase commits its artifacts immediately. If context is lost, artifacts persist.

</success_criteria>