singularity-forge/docs/configuration.md

Configuration

GSD preferences live in ~/.gsd/preferences.md (global) or .gsd/preferences.md (project-local). Manage interactively with /gsd prefs.

Preferences File Format

Preferences use YAML frontmatter in a markdown file:

---
version: 1
models:
  research: claude-sonnet-4-6
  planning: claude-opus-4-6
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
skill_discovery: suggest
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
budget_ceiling: 50.00
token_profile: balanced
---

Global vs Project Preferences

Scope	Path	Applies to
Global	~/.gsd/preferences.md	All projects
Project	.gsd/preferences.md	Current project only

Merge behavior:

• Scalar fields (skill_discovery, budget_ceiling): project wins if defined
• Array fields (always_use_skills, etc.): concatenated (global first, then project)
• Object fields (models, git, auto_supervisor): shallow-merged, project overrides per-key

All Settings

models

Per-phase model selection. Each key accepts a model string or an object with fallbacks.

models:
  research: claude-sonnet-4-6
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
  execution: claude-sonnet-4-6
  execution_simple: claude-haiku-4-5-20250414
  completion: claude-sonnet-4-6
  subagent: claude-sonnet-4-6

Phases: research, planning, execution, execution_simple, completion, subagent

• execution_simple — used for tasks classified as "simple" by the complexity router
• subagent — model for delegated subagent tasks (scout, researcher, worker)
• Provider targeting: use provider/model format (e.g., bedrock/claude-sonnet-4-6) or the provider field in object format

token_profile

Coordinates model selection, phase skipping, and context compression. See Token Optimization.

Values: budget, balanced (default), quality

phases

Fine-grained control over which phases run in auto mode:

phases:
  skip_research: false        # skip milestone-level research
  skip_reassess: false        # skip roadmap reassessment after each slice
  skip_slice_research: true   # skip per-slice research

These are usually set automatically by token_profile, but can be overridden explicitly.

skill_discovery

Controls how GSD finds and applies skills during auto mode.

Value	Behavior
auto	Skills found and applied automatically
suggest	Skills identified during research but not auto-installed (default)
off	Skill discovery disabled

auto_supervisor

Timeout thresholds for auto mode supervision:

auto_supervisor:
  soft_timeout_minutes: 20    # warn LLM to wrap up
  idle_timeout_minutes: 10    # detect stalls
  hard_timeout_minutes: 30    # pause auto mode

budget_ceiling

USD ceiling. Auto mode pauses when reached.

budget_ceiling: 50.00

budget_enforcement

How the budget ceiling is enforced:

Value	Behavior
warn	Log a warning but continue
pause	Pause auto mode (default when ceiling is set)
halt	Stop auto mode entirely

uat_dispatch

Enable automatic UAT (User Acceptance Test) runs after slice completion:

uat_dispatch: true

unique_milestone_ids

Generate milestone IDs with a random suffix to avoid collisions in team workflows:

unique_milestone_ids: true
# Produces: M001-eh88as instead of M001

git

Git behavior configuration. All fields optional:

git:
  auto_push: false            # push commits to remote after committing
  push_branches: false        # push milestone branch to remote
  remote: origin              # git remote name
  snapshots: false            # WIP snapshot commits during long tasks
  pre_merge_check: false      # run checks before worktree merge (true/false/"auto")
  commit_type: feat           # override conventional commit prefix
  main_branch: main           # primary branch name
  commit_docs: true           # commit .gsd/ artifacts to git (set false to keep local)

notifications

Control what notifications GSD sends (for remote question integrations):

notifications:
  enabled: true
  on_complete: true           # notify on unit completion
  on_error: true              # notify on errors
  on_budget: true             # notify on budget thresholds
  on_milestone: true          # notify when milestone finishes
  on_attention: true          # notify when manual attention needed

remote_questions

Route interactive questions to Slack or Discord for headless auto-mode:

remote_questions:
  channel: slack              # or discord
  channel_id: "C1234567890"
  timeout_minutes: 15
  poll_interval_seconds: 10

post_unit_hooks

Custom hooks that fire after specific unit types complete:

post_unit_hooks:
  - name: code-review
    after: [execute-task]
    prompt: "Review the code changes for quality and security issues."
    model: claude-opus-4-6
    max_cycles: 1

pre_dispatch_hooks

Hooks that intercept units before dispatch:

pre_dispatch_hooks:
  - name: add-context
    before: [execute-task]
    action: modify
    prepend: "Remember to follow our coding standards document."

always_use_skills / prefer_skills / avoid_skills

Skill routing preferences:

always_use_skills:
  - debug-like-expert
prefer_skills:
  - frontend-design
avoid_skills: []

skill_rules

Situational skill routing:

skill_rules:
  - when: task involves authentication
    use: [clerk]
  - when: frontend styling work
    prefer: [frontend-design]

custom_instructions

Durable instructions appended to every session:

custom_instructions:
  - "Always use TypeScript strict mode"
  - "Prefer functional patterns over classes"