Skip to main content
GSD Core stores all project configuration in .planning/config.json. The file is created automatically when you run /gsd-new-project and updated whenever you use the configuration commands. You can edit it directly or use the interactive configuration tools — both approaches produce the same result, and unrelated keys are always preserved on write.

​
Interactive configuration with /gsd-settings

Run /gsd-settings to open a six-section interactive wizard that walks you through every configurable workflow toggle and model profile setting. Answers are merged into your project’s config.json without overwriting keys you do not touch. 
/gsd-settings
The wizard is organized into six sections:
SectionSettings covered
PlanningResearch, Plan Checker, Pattern Mapper, Nyquist, UI Phase, UI Gate, AI Phase
ExecutionVerifier, TDD Mode, Code Review, Code Review Depth, UI Review
Docs & OutputCommit Docs, Skip Discuss, Worktrees
FeaturesIntel, Graphify
Model & PipelineModel Profile, Auto-Advance, Branching
MiscContext Warnings, Research Questions mode
At the end of the session you can optionally save the full settings object to ~/.gsd/defaults.json so future projects start from the same baseline configuration.

​
Targeted configuration with /gsd-config

Run /gsd-config for a more focused configuration experience. Without flags it covers the most common toggles. Use flags to access power-user settings, integrations, or to switch model profiles with a single command. 
/gsd-config                         # Common toggles: model, research, plan_check, verifier, branching
/gsd-config --advanced              # Power-user knobs: timeouts, templates, cross-AI, runtime
/gsd-config --integrations          # API keys, review CLI routing, agent-skill injection
/gsd-config --profile quality       # Switch to quality model profile
/gsd-config --profile balanced      # Switch to balanced model profile
/gsd-config --profile budget        # Switch to budget model profile
/gsd-config --profile inherit       # All agents inherit the session model
To use the adaptive profile, run /gsd-config without flags and select it from the interactive wizard’s Model & Pipeline section.

​
Core settings

SettingOptionsDefaultDescription
modeinteractive, yolointeractiveinteractive confirms decisions at each workflow step. yolo auto-approves everything — useful for prototyping where speed matters more than review.
granularitycoarse, standard, finestandardControls how many tasks the planner generates per phase. coarse produces 2–4 tasks, standard 4–6, fine 6–10.
model_profilequality, balanced, budget, adaptive, inheritbalancedModel tier assignment for each agent type. See Model Profiles for the full agent-to-tier mapping.
runtimeclaude, codex, gemini, qwen, opencode, and others(none)Active runtime for runtime-aware profile resolution. When set, profile tiers resolve to runtime-native model IDs.
context_windowany integer200000Context window size in tokens. Set 1000000 for 1M-context models. Values ≥ 500,000 enable adaptive context enrichment.
response_languagelanguage code(none)Language for all agent responses, e.g. "pt", "ko", "ja". Propagates to every spawned agent for cross-phase consistency.

​
Workflow toggles

All workflow toggles follow the absent = enabled pattern. If a key is missing from config.json, the feature defaults to true.
SettingDefaultDescription
workflow.researchtrueRun domain investigation before planning each phase. Disable with --skip-research per run or set false to skip globally.
workflow.plan_checktrueRun the plan verification loop after planning (up to 3 iterations).
workflow.verifiertrueRun post-execution verification against phase goals before shipping.
workflow.auto_advancefalseAutomatically chain discuss → plan → execute without stopping between steps.
workflow.tdd_modefalseEnable TDD pipeline as a first-class execution mode. The planner applies red-green-refactor sequencing to behavior-adding tasks.
workflow.code_reviewtrueEnable /gsd-code-review and the fix pipeline. Set false to gate the command project-wide.
workflow.security_enforcementtrueEnable threat-model-anchored security verification via /gsd-secure-phase.
workflow.auto_advance: false is the safe default. Set it to true only when your requirements are stable and you are comfortable with phases advancing without manual confirmation.

​
Common configuration combinations

The following combinations of settings are commonly used together:
Scenariomodegranularitymodel_profileresearchplan_checkverifier
Prototypingyolocoarsebudgetfalsefalsefalse
Normal developmentinteractivestandardbalancedtruetruetrue
Production releaseinteractivefinequalitytruetruetrue

​
Global defaults

Save settings as global defaults so every new project starts from the same baseline. GSD reads ~/.gsd/defaults.json when creating a new config.json and merges global defaults as the starting configuration. Per-project settings always override globals. 
/gsd-settings       # Offers to save to ~/.gsd/defaults.json at the end of the session
You can also write to the global defaults file directly: 
{
  "model_profile": "balanced",
  "granularity": "standard",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true
  }
}

​
Example config.json

The following example shows a typical production project configuration: 
{
  "mode": "interactive",
  "granularity": "fine",
  "model_profile": "quality",
  "context_window": 200000,
  "response_language": null,
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "auto_advance": false,
    "tdd_mode": false,
    "code_review": true,
    "code_review_depth": "standard",
    "security_enforcement": true,
    "security_asvs_level": 1,
    "security_block_on": "high"
  },
  "git": {
    "branching_strategy": "phase",
    "base_branch": "main"
  }
}