Skip to main content
GSD stores project settings in .planning/config.json. This file controls workflow behavior, model selection, git branching, and execution parameters.

​
Configuration File Location

.planning/config.json
Configure during /gsd:new-project or update later with /gsd:settings.

​
Full Schema

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "auto_advance": false,
    "nyquist_validation": true
  },
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  },
  "parallelization": {
    "enabled": true,
    "plan_level": true,
    "task_level": false,
    "skip_checkpoints": true,
    "max_concurrent_agents": 3,
    "min_plans_for_parallel": 2
  },
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}"
  },
  "gates": {
    "confirm_project": true,
    "confirm_phases": true,
    "confirm_roadmap": true,
    "confirm_breakdown": true,
    "confirm_plan": true,
    "execute_next_plan": true,
    "issues_review": true,
    "confirm_transition": true
  },
  "safety": {
    "always_confirm_destructive": true,
    "always_confirm_external_services": true
  }
}

​
Core Settings

​
mode
string
default:"interactive"
Execution mode:
  • interactive — Confirm at each decision point
  • yolo — Auto-approve all decisions
​
granularity
string
default:"standard"
Phase breakdown granularity:
  • coarse — 3-5 phases (larger scope per phase)
  • standard — 5-8 phases (balanced)
  • fine — 8-12 phases (smallest atomic units)
​
model_profile
string
default:"balanced"
Model tier for agents. See Model Profiles for per-agent breakdown:
  • quality — Opus for planning/execution, Sonnet for verification
  • balanced — Opus for planning, Sonnet for execution/verification
  • budget — Sonnet for code, Haiku for research/verification

​
Workflow Settings

​
workflow.research
boolean
default:"true"
Spawn researcher during plan-phase to investigate domain, stack, and implementation patterns.Disable when: Domain is familiar, or conserving tokens.
​
workflow.plan_check
boolean
default:"true"
Spawn plan checker to verify plans achieve phase goals. Loops up to 3 times until plans pass verification.Disable when: Speed is critical, or plans are simple.
​
workflow.verifier
boolean
default:"true"
Spawn verifier after execute-phase to confirm must-haves were delivered.Disable when: Manual verification is sufficient.
​
workflow.auto_advance
boolean
default:"false"
Auto-chain discuss → plan → execute without stopping.Enable when: Running known phases in batch mode.Warning: Less control between stages.
​
workflow.nyquist_validation
boolean
default:"true"
Research automated test coverage during planning. Maps requirements to test commands.Disable when: Rapid prototyping or phases without tests.Outputs {phase}-VALIDATION.md with feedback contract.

​
Planning Settings

​
planning.commit_docs
boolean
default:"true"
Track .planning/ files in git.Set to false when:
  • Working on sensitive/private projects
  • Don’t want planning artifacts in version control
Automatically false if .planning/ is in .gitignore.
​
planning.search_gitignored
boolean
default:"false"
Add --no-ignore to broad searches to include .planning/ directory.Enable when: Need to search planning docs for context.

​
Parallelization Settings

​
parallelization.enabled
boolean
default:"true"
Run independent plans simultaneously during execute-phase.
​
parallelization.plan_level
boolean
default:"true"
Parallelize at the plan level (multiple plans in same wave).
​
parallelization.task_level
boolean
default:"false"
Parallelize individual tasks within a plan.Warning: Experimental. May cause race conditions.
​
parallelization.skip_checkpoints
boolean
default:"true"
Skip intermediate checkpoints during parallel execution.
​
parallelization.max_concurrent_agents
number
default:"3"
Maximum number of executor agents running simultaneously.Adjust based on:
  • API rate limits
  • Cost tolerance
  • System resources
​
parallelization.min_plans_for_parallel
number
default:"2"
Minimum plans required to trigger parallel execution.Single-plan phases always run sequentially.

​
Git Settings

​
git.branching_strategy
string
default:"none"
Branch creation strategy. See Git Settings for details:
  • none — Commit to current branch (default)
  • phase — Create branch per phase
  • milestone — Create branch for entire milestone
​
git.phase_branch_template
string
default:"gsd/phase-{phase}-{slug}"
Template for phase branch names.Variables:
  • {phase} — Zero-padded phase number (e.g., “03”)
  • {slug} — Lowercase hyphenated phase name
Example: gsd/phase-03-user-authentication
​
git.milestone_branch_template
string
default:"gsd/{milestone}-{slug}"
Template for milestone branch names.Variables:
  • {milestone} — Version identifier (e.g., “v1.0”)
  • {slug} — Lowercase hyphenated milestone name
Example: gsd/v1.0-mvp

​
Confirmation Gates

All gates default to true in interactive mode.
​
gates.confirm_project
boolean
default:"true"
Confirm project initialization details.
​
gates.confirm_phases
boolean
default:"true"
Confirm phase breakdown.
​
gates.confirm_roadmap
boolean
default:"true"
Confirm full roadmap before proceeding.
​
gates.confirm_breakdown
boolean
default:"true"
Confirm task breakdown within plans.
​
gates.confirm_plan
boolean
default:"true"
Confirm each plan before execution.
​
gates.execute_next_plan
boolean
default:"true"
Confirm before executing next plan in sequence.
​
gates.issues_review
boolean
default:"true"
Review issues found during verification.
​
gates.confirm_transition
boolean
default:"true"
Confirm transitions between major stages.
In yolo mode, all gates are automatically set to false.

​
Safety Settings

​
safety.always_confirm_destructive
boolean
default:"true"
Always confirm destructive operations (deletes, force pushes) regardless of mode.
​
safety.always_confirm_external_services
boolean
default:"true"
Always confirm operations involving external services (API calls, deployments).

​
Updating Configuration

​
Interactive Update

/gsd:settings
Guided prompts for all major settings.

​
Quick Profile Switch

/gsd:set-profile quality
/gsd:set-profile balanced
/gsd:set-profile budget

​
Manual Edit

Edit .planning/config.json directly: 
vim .planning/config.json
GSD reads config at command invocation. Changes take effect immediately.

​
Global Defaults

Save settings as defaults for all new projects:
  1. Configure current project: /gsd:settings
  2. When prompted, choose “Save as defaults”
  3. Settings written to ~/.gsd/defaults.json
New projects created with /gsd:new-project inherit these defaults.

​
Command Overrides

Override config per-invocation: 
/gsd:plan-phase --skip-research
/gsd:plan-phase --skip-verify
/gsd:plan-phase --research  # Force research even if disabled