Configuration

One file holds your settings: .groundwork/config.json. It's read fresh at each step, so changes take effect immediately. Editors validate it against config.schema.json next to it.

{
  "$schema": "./config.schema.json",
  "approvalMode": "per-card",
  "experience": "new",
  "tokenBudget": 2000,
  "guards": ["no-ai-trailers"],
  "commitFormat": "[{id}] {title}",
  "commands": {
    "install": "npm install",
    "test": "npm test",
    "lint": "npm run lint",
    "build": "npm run build",
    "run": "npm run dev"
  }
}

FieldsCopy Anchor Link

commandsCopy Anchor Link

The commands block is how the agent knows your project:

• test, lint, build are the checks a card must pass.
• run is how to start the app so a person or the agent can use it. Roles use it to check a card in the running app, and approval stops show it as "how to check it yourself."
• install is used when setting up.

Leave a command empty if the project doesn't have it. gw-plan fills these in when a stack is chosen, and checks they actually run on your machine before writing them down.

Models per roleCopy Anchor Link

Optional, and only used by adapters — the markdown core ignores it. A value is either one model name for every tool, or an object keyed by adapter name, since each tool names models its own way:

{
  "models": {
    "tester": "<a cheaper model>",
    "implementer": "<a mid-tier model>",
    "reviewer": {
      "claude-code": "<the strongest model>",
      "opencode": "<provider>/<model>"
    }
  }
}

The idea: cheaper models for the mechanical roles, the strongest for the reviewer's judgment. Leave a role out to use the tool's default. doctor warns about role names that don't exist.

Changing settings mid-projectCopy Anchor Link

Just edit the file — nothing else needs updating:

• Switching approvalMode changes the next stop, not past ones.
• Switching experience changes tone immediately (from the next step, since it's read each time).
• Raising tokenBudget after a deliberate decision is fine; doctor shows the real number.