Configuration Schema

Complete reference for .planning/config.json with all fields, types, and defaults

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

Related References

• Model Profiles — Per-agent model breakdown
• Workflow Agents — Research, plan_check, verifier details
• Git Settings — Branching strategies and templates