> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opengsd.net/llms.txt
> Use this file to discover all available pages before exploring further.

# GSD Core Configuration Settings and Options Reference

> Configure GSD Core in .planning/config.json using the interactive wizard, /gsd-config flags, or direct JSON edits for workflow toggles and core settings.

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.

```bash theme={null}
/gsd-settings
```

The wizard is organized into six sections:

<Accordion title="Section breakdown">
  | Section              | Settings covered                                                             |
  | -------------------- | ---------------------------------------------------------------------------- |
  | **Planning**         | Research, Plan Checker, Pattern Mapper, Nyquist, UI Phase, UI Gate, AI Phase |
  | **Execution**        | Verifier, TDD Mode, Code Review, Code Review Depth, UI Review                |
  | **Docs & Output**    | Commit Docs, Skip Discuss, Worktrees                                         |
  | **Features**         | Intel, Graphify                                                              |
  | **Model & Pipeline** | Model Profile, Auto-Advance, Branching                                       |
  | **Misc**             | Context Warnings, Research Questions mode                                    |
</Accordion>

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.

```bash theme={null}
/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

| Setting             | Options                                                     | Default       | Description                                                                                                                                            |
| ------------------- | ----------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mode`              | `interactive`, `yolo`                                       | `interactive` | `interactive` confirms decisions at each workflow step. `yolo` auto-approves everything — useful for prototyping where speed matters more than review. |
| `granularity`       | `coarse`, `standard`, `fine`                                | `standard`    | Controls how many tasks the planner generates per phase. `coarse` produces 2–4 tasks, `standard` 4–6, `fine` 6–10.                                     |
| `model_profile`     | `quality`, `balanced`, `budget`, `adaptive`, `inherit`      | `balanced`    | Model tier assignment for each agent type. See [Model Profiles](/core/configuration/model-profiles) for the full agent-to-tier mapping.                |
| `runtime`           | `claude`, `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_window`    | any integer                                                 | `200000`      | Context window size in tokens. Set `1000000` for 1M-context models. Values ≥ 500,000 enable adaptive context enrichment.                               |
| `response_language` | language 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`.

| Setting                         | Default | Description                                                                                                                      |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `workflow.research`             | `true`  | Run domain investigation before planning each phase. Disable with `--skip-research` per run or set `false` to skip globally.     |
| `workflow.plan_check`           | `true`  | Run the plan verification loop after planning (up to 3 iterations).                                                              |
| `workflow.verifier`             | `true`  | Run post-execution verification against phase goals before shipping.                                                             |
| `workflow.auto_advance`         | `false` | Automatically chain discuss → plan → execute without stopping between steps.                                                     |
| `workflow.tdd_mode`             | `false` | Enable TDD pipeline as a first-class execution mode. The planner applies red-green-refactor sequencing to behavior-adding tasks. |
| `workflow.code_review`          | `true`  | Enable `/gsd-code-review` and the fix pipeline. Set `false` to gate the command project-wide.                                    |
| `workflow.security_enforcement` | `true`  | Enable threat-model-anchored security verification via `/gsd-secure-phase`.                                                      |

<Note>
  `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.
</Note>

## Common configuration combinations

The following combinations of settings are commonly used together:

| Scenario           | `mode`        | `granularity` | `model_profile` | `research` | `plan_check` | `verifier` |
| ------------------ | ------------- | ------------- | --------------- | ---------- | ------------ | ---------- |
| Prototyping        | `yolo`        | `coarse`      | `budget`        | `false`    | `false`      | `false`    |
| Normal development | `interactive` | `standard`    | `balanced`      | `true`     | `true`       | `true`     |
| Production release | `interactive` | `fine`        | `quality`       | `true`     | `true`       | `true`     |

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

```bash theme={null}
/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
  }
}
```