Configuration - Get Shit Done

GSD stores project settings in .planning/config.json. Configure during /gsd:new-project or update anytime with /gsd:settings.

Configuration Commands

/gsd:settings              # Opens interactive configuration menu

Configuration Schema

Complete config.json structure:

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}"
  }
}

Core Settings

Mode

Controls approval behavior throughout the workflow.

Option	Behavior	Best For
`interactive` (default)	Confirms at each step	Normal development, learning GSD
`yolo`	Auto-approves all decisions	Rapid prototyping, familiar domains

{
  "mode": "interactive"
}

Granularity

Controls how finely scope is sliced into phases.

Option	Phases × Plans	Best For
`coarse`	3-5 phases	Small projects, rapid prototyping
`standard` (default)	5-8 phases	Most projects
`fine`	8-12 phases	Complex projects, critical work

More phases = smaller scope per phase = more reliable execution, but more overhead.

Model Profiles

Balance quality vs token spend by controlling which Claude model each agent uses.

Profile Overview

Profile	Planning	Execution	Verification	Best For
`quality`	Opus	Opus	Sonnet	Critical work, quota available
`balanced` (default)	Opus	Sonnet	Sonnet	Most projects
`budget`	Sonnet	Sonnet	Haiku	High-volume work, prototyping

Per-Agent Model Breakdown

Agent	`quality`	`balanced`	`budget`
gsd-planner	Opus	Opus	Sonnet
gsd-roadmapper	Opus	Sonnet	Sonnet
gsd-executor	Opus	Sonnet	Sonnet
gsd-phase-researcher	Opus	Sonnet	Haiku
gsd-project-researcher	Opus	Sonnet	Haiku
gsd-research-synthesizer	Sonnet	Sonnet	Haiku
gsd-debugger	Opus	Sonnet	Sonnet
gsd-codebase-mapper	Sonnet	Haiku	Haiku
gsd-verifier	Sonnet	Sonnet	Haiku
gsd-plan-checker	Sonnet	Sonnet	Haiku
gsd-integration-checker	Sonnet	Sonnet	Haiku

Profile Philosophy

Quality

Opus for all decision-making agents, Sonnet for read-only verification.Use when quota is available and the work is critical.

Balanced

Opus only for planning (where architecture decisions happen), Sonnet for everything else.The default for good reason. Best cost/quality tradeoff.

Budget

Sonnet for anything that writes code, Haiku for research and verification.Use for high-volume work or less critical phases.

Switching Profiles

/gsd:set-profile quality

Planning Settings

Commit Documentation

Controls whether .planning/ files are committed to git.

{
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  }
}

Setting	Options	Default	What It Controls
`commit_docs`	`true`, `false`	`true`	Whether `.planning/` files are committed to git
`search_gitignored`	`true`, `false`	`false`	Add `--no-ignore` to broad searches to include `.planning/`

If .planning/ is in .gitignore, commit_docs is automatically false regardless of the config value.

Working on sensitive projects? Set commit_docs: false and add .planning/ to .gitignore. Planning artifacts stay local and never touch git.

Workflow Agents

These spawn additional agents during planning/execution. They improve quality but add tokens and time.

{
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  }
}

Agent Reference

Research Agent

Default: trueWhat it does: Researches domain before planning each phase. Spawns 4 parallel agents:

Stack researcher - Libraries, patterns, tooling
Features researcher - Similar implementations
Architecture researcher - Design patterns
Pitfalls researcher - Common mistakes

Output: {phase}-RESEARCH.mdDisable when: Domain is familiar, conserving tokens, rapid iteration.Override per-invocation:

/gsd:plan-phase --skip-research

Plan Checker

Default: trueWhat it does: Verifies plans achieve phase goals before execution. Checks 8 dimensions:

Requirements coverage
Task atomicity
Dependency ordering
File organization
Verification steps
Technical decisions
Implementation clarity
Automated validation (Nyquist)

Loops up to 3 times until plans pass.Disable when: Plans are simple, conserving tokens, trusted domain.Override per-invocation:

/gsd:plan-phase --skip-verify

Verifier

Default: trueWhat it does: Confirms must-haves were delivered after execution. Checks codebase against phase goals.Output: {phase}-VERIFICATION.mdDisable when: Manual testing only, rapid iteration.

Nyquist Validation

Default: trueWhat it does: Maps automated test coverage to each requirement during plan-phase research. Ensures feedback mechanism exists before code is written.

Detects existing test infrastructure
Maps requirements to test commands
Identifies test scaffolding needed (Wave 0 tasks)
Plan checker enforces as 8th verification dimension

Output: {phase}-VALIDATION.md - the feedback contract for the phaseDisable when: Rapid prototyping phases where test infrastructure isn’t the focus.Learn more: See Validation Architecture

Performance vs Quality Presets

Recommended combinations for different scenarios:

Scenario	Mode	Granularity	Profile	Research	Plan Check	Verifier
Prototyping	`yolo`	`coarse`	`budget`	off	off	off
Normal dev	`interactive`	`standard`	`balanced`	on	on	on
Production	`interactive`	`fine`	`quality`	on	on	on

Git Branching

Control how GSD handles branches during execution.

{
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}"
  }
}

Branching Strategies

None

Default: Commits to current branchBest for: Solo development, simple projectsAll commits go directly to your current branch. No branch management overhead.

Phase

Creates: One branch per phaseBest for: Code review per phase, granular rollbackEach phase gets its own branch. Merged at phase completion.

Milestone

Creates: One branch per milestoneBest for: Release branches, PR per versionAll phases share one branch. Merged at milestone completion.

Branch Templates

Customize branch naming patterns:

{
  "git": {
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}"
  }
}

Template variables:

{phase} - Zero-padded phase number (e.g., “03”)
{slug} - Lowercase hyphenated phase name (e.g., “user-authentication”)
{milestone} - Version identifier (e.g., “v1.0”)

Example branches:

Phase: gsd/phase-03-user-authentication
Milestone: gsd/v1.0-mvp-launch

Merge Behavior

At milestone completion, GSD offers:

Squash merge (recommended) - Clean single commit per milestone
Merge with history - Preserve all atomic commits

If you use phase branching strategy, you may accumulate many branches. Clean them up periodically:

git branch -d gsd/phase-*

Security: Protecting Sensitive Files

GSD’s codebase mapping and analysis commands read files to understand your project. Protect files containing secrets by adding them to Claude Code’s deny list:

Open Settings

Edit .claude/settings.json (project-level) or global settings

Add Deny Patterns

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/secrets/*)",
      "Read(**/*credential*)",
      "Read(**/*.pem)",
      "Read(**/*.key)"
    ]
  }
}

This prevents Claude from reading these files entirely, regardless of what commands you run.

GSD includes built-in protections against committing secrets, but defense-in-depth is best practice. Deny read access as a first line of defense.

Configuration Examples

Prototyping Setup

Fast iteration, minimal overhead:

{
  "mode": "yolo",
  "granularity": "coarse",
  "model_profile": "budget",
  "workflow": {
    "research": false,
    "plan_check": false,
    "verifier": false,
    "nyquist_validation": false
  },
  "git": {
    "branching_strategy": "none"
  }
}

Production Setup

Maximum quality, thorough validation:

{
  "mode": "interactive",
  "granularity": "fine",
  "model_profile": "quality",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "git": {
    "branching_strategy": "phase",
    "phase_branch_template": "feature/phase-{phase}-{slug}"
  }
}

Team Collaboration Setup

Branch per milestone, code review workflow:

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "planning": {
    "commit_docs": true
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "git": {
    "branching_strategy": "milestone",
    "milestone_branch_template": "release/{milestone}"
  }
}

Private Project Setup

Local planning docs, no git tracking:

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "planning": {
    "commit_docs": false,
    "search_gitignored": true
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "git": {
    "branching_strategy": "none"
  }
}

Add to .gitignore:

.planning/

Command-Line Overrides

Some settings can be overridden per command:

/gsd:plan-phase --skip-research

Troubleshooting Configuration

Changes Not Taking Effect

Verify config file exists: .planning/config.json
Validate JSON syntax (no trailing commas)
Restart your AI coding assistant
Check /gsd:progress to confirm settings

Model Costs Too High

Reduce token usage:

/gsd:set-profile budget
/gsd:settings
# Disable research
# Disable plan_check
# Disable verifier

Config File Missing

Run /gsd:settings to regenerate:

/gsd:settings

Or create manually using the schema above.

Next Steps

Core Concepts

Understand how GSD works under the hood

Workflow Agents

Deep dive into the agent system

Commands

Complete reference for all GSD commands

Advanced Topics

Deep dive into architecture and agent system

Overview

Getting Started

Core Concepts

Workflow

Guides

Advanced

​Configuration Commands

​Configuration Schema

​Core Settings

​Mode

​Granularity

​Model Profiles

​Profile Overview

​Per-Agent Model Breakdown

​Profile Philosophy

Quality

Balanced

Budget

​Switching Profiles

​Planning Settings

​Commit Documentation

​Workflow Agents

​Agent Reference

​Performance vs Quality Presets

​Git Branching

​Branching Strategies

None

Phase

Milestone

​Branch Templates

​Merge Behavior

​Security: Protecting Sensitive Files

​Configuration Examples

​Prototyping Setup

​Production Setup

​Team Collaboration Setup

​Private Project Setup

​Command-Line Overrides

​Troubleshooting Configuration

​Changes Not Taking Effect

​Model Costs Too High

​Config File Missing

​Next Steps

Core Concepts

Workflow Agents

Commands

Advanced Topics

Configuration Commands

Configuration Schema

Core Settings

Mode

Granularity

Model Profiles

Profile Overview

Per-Agent Model Breakdown

Profile Philosophy

Switching Profiles

Planning Settings

Commit Documentation

Workflow Agents

Agent Reference

Performance vs Quality Presets

Git Branching

Branching Strategies

Branch Templates

Merge Behavior

Security: Protecting Sensitive Files

Configuration Examples

Prototyping Setup

Production Setup

Team Collaboration Setup

Private Project Setup

Command-Line Overrides

Troubleshooting Configuration

Changes Not Taking Effect

Model Costs Too High

Config File Missing

Next Steps