singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: add GitBook-ready user-facing documentation

Browse source 
33 markdown files organized for GitBook import with SUMMARY.md navigation.
Covers installation, core concepts, auto mode, configuration, all providers,
cost management, skills, parallel orchestration, remote questions, teams,
headless CI, and full command reference. User-facing only — no internal/dev content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jeremy 2026-04-11 10:34:07 -05:00
parent 804f1d4b94
commit edf9d0be6f
33 changed files with 3151 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
gitbook/README.md Normal file
View file

@ -0,0 +1,65 @@
# What is GSD?
GSD is an AI-powered development agent that turns project ideas into working software. Describe what you want to build, and GSD researches, plans, codes, tests, and commits — with clean git history and full cost tracking.
## How It Works
GSD breaks your project into manageable pieces and works through them systematically:
```
You describe your project
↓
GSD creates a milestone with slices (features)
↓
Each slice is decomposed into tasks
↓
Tasks are executed one at a time in fresh AI sessions
↓
Code is committed, verified, and the next task begins
```
You can stay hands-on with **step mode** (reviewing each step) or let GSD run autonomously with **auto mode** while you grab coffee.
## Key Features
- **Autonomous execution** — `/gsd auto` runs research, planning, coding, testing, and committing without intervention
- **20+ LLM providers** — Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, local models, and more
- **Git isolation** — Each milestone works in its own worktree branch, merged cleanly when done
- **Cost tracking** — Real-time token usage, budget ceilings, and automatic model downgrading
- **Crash recovery** — Sessions resume automatically after interruptions
- **Skills system** — Domain-specific instruction sets for frameworks, languages, and tools
- **Parallel milestones** — Run multiple milestones simultaneously in isolated worktrees
- **Remote questions** — Get Discord, Slack, or Telegram notifications when GSD needs input
- **Web interface** — Browser-based dashboard with real-time progress
- **VS Code extension** — Chat participant, sidebar dashboard, and full command palette
- **Headless mode** — Run in CI pipelines, cron jobs, and scripted automation
## Quick Start
```bash
# Install
npm install -g gsd-pi
# Launch
gsd
# Start autonomous mode
/gsd auto
```
See [Installation](getting-started/installation.md) for detailed setup instructions.
## Two Ways to Work
| Mode | Command | Best For |
|------|---------|----------|
| **Step** | `/gsd` | Staying in the loop, reviewing each step |
| **Auto** | `/gsd auto` | Walking away, overnight builds, batch work |
The recommended workflow: run auto mode in one terminal, steer from another. See [Step Mode](core-concepts/step-mode.md) and [Auto Mode](core-concepts/auto-mode.md).
## Requirements
- **Node.js** 22.0.0 or later (24 LTS recommended)
- **Git** installed and configured
- An API key for at least one LLM provider (or use browser sign-in for Anthropic/GitHub Copilot)

49
gitbook/SUMMARY.md Normal file
View file

@ -0,0 +1,49 @@
# Table of contents
* [What is GSD?](README.md)
## Getting Started
* [Installation](getting-started/installation.md)
* [Your First Project](getting-started/first-project.md)
* [Choosing a Model](getting-started/choosing-a-model.md)
## Core Concepts
* [How GSD Organizes Work](core-concepts/project-structure.md)
* [Step Mode](core-concepts/step-mode.md)
* [Auto Mode](core-concepts/auto-mode.md)
## Configuration
* [Preferences](configuration/preferences.md)
* [Provider Setup](configuration/providers.md)
* [Custom Models](configuration/custom-models.md)
* [Git & Worktrees](configuration/git-settings.md)
* [Notifications](configuration/notifications.md)
* [MCP Servers](configuration/mcp-servers.md)
## Features
* [Cost Management](features/cost-management.md)
* [Token Optimization](features/token-optimization.md)
* [Dynamic Model Routing](features/dynamic-model-routing.md)
* [Skills](features/skills.md)
* [Captures & Triage](features/captures.md)
* [Workflow Visualizer](features/visualizer.md)
* [Workflow Templates](features/workflow-templates.md)
* [Web Interface](features/web-interface.md)
* [Remote Questions](features/remote-questions.md)
* [Working in Teams](features/teams.md)
* [Parallel Orchestration](features/parallel.md)
* [Headless & CI Mode](features/headless.md)
* [GitHub Sync](features/github-sync.md)
## Reference
* [Commands](reference/commands.md)
* [Keyboard Shortcuts](reference/keyboard-shortcuts.md)
* [CLI Flags](reference/cli-flags.md)
* [Environment Variables](reference/environment-variables.md)
* [Troubleshooting](reference/troubleshooting.md)
* [Migration from v1](reference/migration.md)

131
gitbook/configuration/custom-models.md Normal file
View file

@ -0,0 +1,131 @@
# Custom Models
Define custom models and providers in `~/.gsd/agent/models.json`. This lets you add models not in the default registry — self-hosted endpoints, fine-tuned models, proxies, or new provider releases.
## File Location
GSD looks for models.json at:
1. `~/.gsd/agent/models.json` (primary)
2. `~/.pi/agent/models.json` (fallback)
The file reloads each time you open `/model` — no restart needed.
## Basic Structure
```json
{
"providers": {
"my-provider": {
"baseUrl": "https://my-endpoint.example.com/v1",
"apiKey": "MY_PROVIDER_API_KEY",
"api": "openai-completions",
"models": [
{
"id": "model-id-here",
"name": "Friendly Model Name",
"reasoning": false,
"input": ["text"],
"contextWindow": 128000,
"maxTokens": 16384,
"cost": { "input": 0.15, "output": 0.60, "cacheRead": 0.015, "cacheWrite": 0.19 }
}
]
}
}
}
```
## API Key Resolution
The `apiKey` field can be:
- **An environment variable name**: `"OPENROUTER_API_KEY"` — GSD resolves it automatically
- **A literal value**: `"sk-abc123..."` — used directly
- **A dummy value**: `"not-needed"` — for local servers that don't require auth
## Compatibility Flags
Local and non-standard servers often need compatibility adjustments:
```json
{
"compat": {
"supportsDeveloperRole": false,
"supportsReasoningEffort": false,
"supportsUsageInStreaming": false,
"thinkingFormat": "qwen"
}
}
```
| Flag | Default | Purpose |
|------|---------|---------|
| `supportsDeveloperRole` | `true` | Set `false` if the server doesn't support the `developer` message role |
| `supportsReasoningEffort` | `true` | Set `false` if the server doesn't support reasoning effort parameters |
| `supportsUsageInStreaming` | `true` | Set `false` if streaming responses don't include token usage |
| `thinkingFormat` | — | Set `"qwen"` for Qwen thinking mode, `"qwen-chat-template"` for chat template variant |
## Custom Headers
For proxies that need extra headers:
```json
{
"providers": {
"litellm-proxy": {
"baseUrl": "https://litellm.example.com/v1",
"apiKey": "MY_API_KEY",
"api": "openai-completions",
"headers": {
"x-custom-header": "value"
},
"models": [...]
}
}
}
```
## Model Overrides
Override specific model settings without redefining the entire model:
```json
{
"providers": {
"openrouter": {
"modelOverrides": {
"anthropic/claude-sonnet-4": {
"compat": {
"openRouterRouting": {
"only": ["amazon-bedrock"]
}
}
}
}
}
}
}
```
## Cost Tracking
For accurate cost tracking with custom models, add the `cost` field (per million tokens):
```json
"cost": {
"input": 0.15,
"output": 0.60,
"cacheRead": 0.015,
"cacheWrite": 0.19
}
```
Without this, cost shows $0.00 — which is the expected default for custom models.
## Community Extensions
For providers not built into GSD, community extensions add full provider support:
| Extension | Provider | Install |
|-----------|----------|---------|
| `pi-dashscope` | Alibaba DashScope (Qwen3, GLM-5, etc.) | `gsd install npm:pi-dashscope` |

148
gitbook/configuration/git-settings.md Normal file
View file

@ -0,0 +1,148 @@
# Git & Worktrees
GSD uses git for milestone isolation and sequential commits. The strategy is fully automated — you don't need to manage branches manually.
## Isolation Modes
GSD supports three isolation modes, configured via `git.isolation` in preferences:
| Mode | Working Directory | Branch | Best For |
|------|-------------------|--------|----------|
| `worktree` (default) | `.gsd/worktrees/<MID>/` | `milestone/<MID>` | Most projects — full isolation |
| `branch` | Project root | `milestone/<MID>` | Submodule-heavy repos |
| `none` | Project root | Current branch | Hot-reload workflows |
### Worktree Mode (Default)
Each milestone gets its own git worktree and branch. All execution happens inside the worktree. On completion, everything is squash-merged to main as one clean commit. The worktree and branch are then cleaned up.
Changes in a milestone can't interfere with your main working copy.
### Branch Mode
Work happens in the project root on a `milestone/<MID>` branch. No worktree directory is created. Useful when worktrees cause problems with submodules or hardcoded paths.
### None Mode
Work happens directly on your current branch. No worktree, no milestone branch. GSD still commits with conventional commit messages. Use this when file isolation breaks dev tooling (file watchers, hot-reload, etc.).
## Branching Model
```
main ────────────────────────────────────────────
│ ↑
└── milestone/M001 (worktree) ─────────────┘
commit: feat: core types
commit: feat: markdown parser
commit: feat: file writer
→ squash-merged to main
```
## Workflow Modes
Set `mode` for sensible defaults instead of configuring each setting individually:
```yaml
mode: solo # personal projects
mode: team # shared repos
```
| Setting | `solo` | `team` |
|---------|--------|--------|
| `git.auto_push` | `true` | `false` |
| `git.push_branches` | `false` | `true` |
| `git.pre_merge_check` | `false` | `true` |
| `unique_milestone_ids` | `false` | `true` |
Mode defaults are the lowest priority — any explicit preference overrides them.
## Git Preferences
```yaml
git:
auto_push: false # push after commits
push_branches: false # push milestone branch to remote
remote: origin # git remote name
snapshots: true # WIP snapshot commits during long tasks
pre_merge_check: auto # validation before merge
commit_type: feat # override conventional commit prefix
main_branch: main # primary branch name
merge_strategy: squash # "squash" or "merge"
isolation: worktree # "worktree", "branch", or "none"
commit_docs: true # commit .gsd/ artifacts to git
manage_gitignore: true # let GSD manage .gitignore
auto_pr: false # create PR on milestone completion
pr_target_branch: develop # PR target branch
```
## Automatic Pull Requests
For teams using Gitflow or branch-based workflows:
```yaml
git:
auto_push: true
auto_pr: true
pr_target_branch: develop
```
When a milestone completes, GSD pushes the branch and creates a PR targeting your specified branch. Requires `gh` CLI installed and authenticated.
## Post-Worktree Hook
Run a script after worktree creation (copy `.env` files, symlink assets, etc.):
```yaml
git:
worktree_post_create: .gsd/hooks/post-worktree-create
```
Example hook:
```bash
#!/bin/bash
cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env"
ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets"
```
## Keeping `.gsd/` Local
For teams where only some members use GSD:
```yaml
git:
commit_docs: false
```
This adds `.gsd/` to `.gitignore` entirely. You get structured planning without affecting teammates who don't use GSD.
## Commit Format
Commits use conventional commit format with GSD metadata:
```
feat: core type definitions
GSD-Task: M001/S01/T01
```
## Manual Worktree Management
Use `/worktree` (or `/wt`) for manual worktree operations:
```
/worktree create
/worktree switch
/worktree merge
/worktree remove
```
## Self-Healing
GSD automatically recovers from common git issues:
- **Detached HEAD** — reattaches to the correct branch
- **Stale lock files** — removes `index.lock` from crashed processes
- **Orphaned worktrees** — detects and cleans up abandoned worktrees
Run `/gsd doctor` to check git health manually.

65
gitbook/configuration/mcp-servers.md Normal file
View file

@ -0,0 +1,65 @@
# MCP Servers
GSD can connect to external MCP (Model Context Protocol) servers for local tools, internal APIs, self-hosted services, or integrations not built in as native extensions.
## Configuration Files
GSD reads MCP config from these project-local paths:
- `.mcp.json` — repo-shared config (safe to commit)
- `.gsd/mcp.json` — local-only config (not shared)
If both exist, server names are merged and the first definition found wins.
## Supported Transports
| Transport | Config Shape | Use When |
|-----------|-------------|----------|
| `stdio` | `command` + optional `args`, `env`, `cwd` | Launching a local MCP server |
| `http` | `url` | Connecting to an already-running server |
## Examples
### stdio Server
```json
{
"mcpServers": {
"my-server": {
"type": "stdio",
"command": "/absolute/path/to/python3",
"args": ["/absolute/path/to/server.py"],
"env": {
"API_URL": "http://localhost:8000"
}
}
}
}
```
### HTTP Server
```json
{
"mcpServers": {
"my-http-server": {
"url": "http://localhost:8080/mcp"
}
}
}
```
## Verifying a Server
After adding config, verify from a GSD session:
1. `mcp_servers` — confirms GSD sees the config
2. `mcp_discover(server="my-server")` — confirms the server starts and responds
3. `mcp_call(server="my-server", tool="<tool>", args={...})` — confirms a real tool call works
## Tips
- Use **absolute paths** for executables and scripts
- Set required **environment variables** directly in the MCP config's `env` block
- Use `.mcp.json` for team-shared servers; `.gsd/mcp.json` for machine-local ones
- If a server depends on local paths or personal secrets, keep it in `.gsd/mcp.json`

38
gitbook/configuration/notifications.md Normal file
View file

@ -0,0 +1,38 @@
# Notifications
GSD sends desktop notifications during auto mode to keep you informed without watching the terminal.
## Configuration
```yaml
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
```
## macOS Setup
GSD uses `terminal-notifier` when available, falling back to `osascript`.
**Recommended:** Install `terminal-notifier` for reliable delivery:
```bash
brew install terminal-notifier
```
**Why?** The `osascript` fallback attributes notifications to your terminal app (Ghostty, iTerm2, etc.), which may not have notification permissions. `terminal-notifier` registers as its own app and prompts for permission on first use.
### Notifications Not Appearing?
1. Check **System Settings → Notifications** for your terminal app
2. Install `terminal-notifier` (recommended)
3. Test with:
```bash
terminal-notifier -title "GSD" -message "working!" -sound Glass
```
If your terminal app doesn't appear in Notification settings, it may need to send at least one notification first to register. See [Troubleshooting](../reference/troubleshooting.md) for more details.

238
gitbook/configuration/preferences.md Normal file
View file

@ -0,0 +1,238 @@
# Preferences
GSD preferences live in YAML frontmatter markdown files. You can configure them globally or per-project.
## Managing Preferences
```
/gsd prefs # open the global preferences wizard
/gsd prefs project # open the project preferences wizard
/gsd prefs status # show current values and where they come from
```
## Preference Files
| Scope | Path | Applies To |
|-------|------|-----------|
| Global | `~/.gsd/PREFERENCES.md` | All projects |
| Project | `.gsd/PREFERENCES.md` | Current project only |
**How they merge:**
- **Scalar fields** (`budget_ceiling`, `token_profile`): 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
## Quick Example
```yaml
---
version: 1
# Model selection
models:
research: claude-sonnet-4-6
planning: claude-opus-4-6
execution: claude-sonnet-4-6
completion: claude-sonnet-4-6
# Token optimization
token_profile: balanced
# Budget
budget_ceiling: 25.00
budget_enforcement: pause
# Supervision
auto_supervisor:
soft_timeout_minutes: 15
hard_timeout_minutes: 25
# Git
git:
auto_push: true
merge_strategy: squash
isolation: worktree
# Verification
verification_commands:
- npm run lint
- npm run test
# Notifications
notifications:
on_milestone: true
on_attention: true
---
```
## All Settings
### `models`
Per-phase model selection. See [Choosing a Model](../getting-started/choosing-a-model.md).
```yaml
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
completion: claude-sonnet-4-6
subagent: claude-sonnet-4-6
```
### `token_profile`
Coordinates model selection, phase skipping, and context compression. Values: `budget`, `balanced` (default), `quality`. See [Token Optimization](../features/token-optimization.md).
### `budget_ceiling`
Maximum USD to spend during auto mode:
```yaml
budget_ceiling: 50.00
```
### `budget_enforcement`
What happens when the ceiling is reached:
| Value | Behavior |
|-------|----------|
| `warn` | Log a warning, continue |
| `pause` | Pause auto mode (default) |
| `halt` | Stop auto mode entirely |
### `auto_supervisor`
Timeout thresholds for auto mode:
```yaml
auto_supervisor:
soft_timeout_minutes: 20 # warn AI to wrap up
idle_timeout_minutes: 10 # detect stalls
hard_timeout_minutes: 30 # pause auto mode
```
### `verification_commands`
Shell commands that run after every task execution:
```yaml
verification_commands:
- npm run lint
- npm run test
verification_auto_fix: true # auto-retry on failure (default)
verification_max_retries: 2 # max attempts (default: 2)
```
### `phases`
Fine-grained control over which phases run:
```yaml
phases:
skip_research: false
skip_reassess: false
skip_slice_research: true
reassess_after_slice: true
require_slice_discussion: false
```
### `skill_discovery`
| Value | Behavior |
|-------|----------|
| `auto` | Skills found and applied automatically |
| `suggest` | Skills identified but not auto-applied (default) |
| `off` | Skill discovery disabled |
### `dynamic_routing`
Automatic model selection by task complexity. See [Dynamic Model Routing](../features/dynamic-model-routing.md).
```yaml
dynamic_routing:
enabled: true
escalate_on_failure: true
budget_pressure: true
```
### `git`
Git behavior. See [Git & Worktrees](git-settings.md).
```yaml
git:
auto_push: false
merge_strategy: squash
isolation: worktree
commit_docs: true
auto_pr: false
```
### `notifications`
See [Notifications](notifications.md).
```yaml
notifications:
enabled: true
on_complete: true
on_error: true
on_milestone: true
on_attention: true
```
### `remote_questions`
Route questions to Slack, Discord, or Telegram. See [Remote Questions](../features/remote-questions.md).
```yaml
remote_questions:
channel: discord
channel_id: "1234567890123456789"
timeout_minutes: 5
```
### `parallel`
Run multiple milestones simultaneously. See [Parallel Orchestration](../features/parallel.md).
```yaml
parallel:
enabled: false
max_workers: 2
budget_ceiling: 50.00
```
### `custom_instructions`
Durable instructions appended to every session:
```yaml
custom_instructions:
- "Always use TypeScript strict mode"
- "Prefer functional patterns over classes"
```
For project-specific patterns, use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically.
### `context_pause_threshold`
Context window usage percentage at which auto mode pauses:
```yaml
context_pause_threshold: 80 # pause at 80%
```
### `show_token_cost`
Show per-prompt and cumulative session token cost in the footer:
```yaml
show_token_cost: true
```

277
gitbook/configuration/providers.md Normal file
View file

@ -0,0 +1,277 @@
# Provider Setup
Step-by-step setup instructions for every LLM provider GSD supports. If you ran the onboarding wizard (`gsd config`) and picked a provider, you may already be configured — check with `/model` inside a session.
## Quick Reference
| Provider | Auth Method | Environment Variable |
|----------|-------------|---------------------|
| Anthropic | OAuth or API key | `ANTHROPIC_API_KEY` |
| OpenAI | API key | `OPENAI_API_KEY` |
| Google Gemini | API key | `GEMINI_API_KEY` |
| OpenRouter | API key | `OPENROUTER_API_KEY` |
| Groq | API key | `GROQ_API_KEY` |
| xAI (Grok) | API key | `XAI_API_KEY` |
| Mistral | API key | `MISTRAL_API_KEY` |
| GitHub Copilot | OAuth | `GH_TOKEN` |
| Amazon Bedrock | IAM credentials | `AWS_PROFILE` or `AWS_ACCESS_KEY_ID` |
| Vertex AI | ADC | `GOOGLE_APPLICATION_CREDENTIALS` |
| Azure OpenAI | API key | `AZURE_OPENAI_API_KEY` |
| Ollama | None (local) | — |
| LM Studio | None (local) | — |
| vLLM / SGLang | None (local) | — |
## Built-in Providers
### Anthropic (Claude)
**Recommended.** Anthropic models have the deepest integration: built-in web search, extended thinking, and prompt caching.
**Option A — Browser sign-in (recommended):**
```bash
gsd config
# Choose "Sign in with your browser" → "Anthropic (Claude)"
```
Or inside a session: `/login`
**Option B — API key:**
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```
### OpenAI
```bash
export OPENAI_API_KEY="sk-..."
```
Or run `gsd config` and choose "Paste an API key" then "OpenAI".
### Google Gemini
```bash
export GEMINI_API_KEY="..."
```
### OpenRouter
OpenRouter aggregates 200+ models from multiple providers behind a single API key.
1. Get a key at [openrouter.ai/keys](https://openrouter.ai/keys)
2. Set it:
```bash
export OPENROUTER_API_KEY="sk-or-..."
```
3. In GSD, type `/model` to select an OpenRouter model (prefixed with `openrouter/`)
To add models not in the built-in list, add them to `~/.gsd/agent/models.json`. See [Custom Models](custom-models.md).
### Groq
```bash
export GROQ_API_KEY="gsk_..."
```
### xAI (Grok)
```bash
export XAI_API_KEY="xai-..."
```
### Mistral
```bash
export MISTRAL_API_KEY="..."
```
### GitHub Copilot
Uses OAuth — sign in through the browser:
```bash
gsd config
# Choose "Sign in with your browser" → "GitHub Copilot"
```
Requires an active GitHub Copilot subscription.
### Amazon Bedrock
Bedrock uses AWS IAM credentials:
```bash
# Named profile
export AWS_PROFILE="my-profile"
# Or IAM keys
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# Or bearer token
export AWS_BEARER_TOKEN_BEDROCK="..."
```
ECS task roles and IRSA (Kubernetes) are also detected automatically.
### Anthropic on Vertex AI
```bash
gcloud auth application-default login
export ANTHROPIC_VERTEX_PROJECT_ID="my-project-id"
```
### Azure OpenAI
```bash
export AZURE_OPENAI_API_KEY="..."
```
## Local Providers
Local providers run on your machine. They require a `models.json` configuration file at `~/.gsd/agent/models.json` because GSD needs to know the endpoint URL and available models.
The file reloads each time you open `/model` — no restart needed.
### Ollama
1. Install and start Ollama:
```bash
brew install ollama
ollama serve
```
2. Pull a model:
```bash
ollama pull llama3.1:8b
```
3. Create `~/.gsd/agent/models.json`:
```json
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"apiKey": "ollama",
"compat": {
"supportsDeveloperRole": false,
"supportsReasoningEffort": false
},
"models": [
{ "id": "llama3.1:8b" }
]
}
}
}
```
4. In GSD, type `/model` and select your Ollama model.
### LM Studio
1. Install [LM Studio](https://lmstudio.ai)
2. Go to "Local Server" tab, load a model, click "Start Server" (default port 1234)
3. Create `~/.gsd/agent/models.json`:
```json
{
"providers": {
"lm-studio": {
"baseUrl": "http://localhost:1234/v1",
"api": "openai-completions",
"apiKey": "lm-studio",
"compat": {
"supportsDeveloperRole": false,
"supportsReasoningEffort": false
},
"models": [
{ "id": "your-model-name" }
]
}
}
}
```
### vLLM
```json
{
"providers": {
"vllm": {
"baseUrl": "http://localhost:8000/v1",
"api": "openai-completions",
"apiKey": "vllm",
"compat": {
"supportsDeveloperRole": false,
"supportsReasoningEffort": false,
"supportsUsageInStreaming": false
},
"models": [
{ "id": "meta-llama/Llama-3.1-8B-Instruct" }
]
}
}
}
```
### SGLang
```json
{
"providers": {
"sglang": {
"baseUrl": "http://localhost:30000/v1",
"api": "openai-completions",
"apiKey": "sglang",
"compat": {
"supportsDeveloperRole": false,
"supportsReasoningEffort": false
},
"models": [
{ "id": "meta-llama/Llama-3.1-8B-Instruct" }
]
}
}
}
```
## Custom OpenAI-Compatible Endpoints
Any server that implements the OpenAI Chat Completions API can work with GSD — proxies (LiteLLM, Portkey, Helicone), self-hosted inference, new providers.
**Quickest path:**
```bash
gsd config
# Choose "Paste an API key" → "Custom (OpenAI-compatible)"
# Enter: base URL, API key, model ID
```
This writes `~/.gsd/agent/models.json` for you. See [Custom Models](custom-models.md) for manual setup.
## Verifying Your Setup
1. Launch GSD: `gsd`
2. Check available models: `/model`
3. Select your model from the picker
4. Send a test message to confirm it responds
If the model doesn't appear, check:
- The environment variable is set in the current shell
- `models.json` is valid JSON
- The server is running (for local providers)
## Common Issues
| Problem | Cause | Fix |
|---------|-------|-----|
| "Authentication failed" with valid key | Key not visible to GSD | Export in the same terminal, or save via `gsd config` |
| OpenRouter models not in `/model` | No API key set | Set `OPENROUTER_API_KEY` and restart |
| Ollama returns empty responses | Server not running or model not pulled | Run `ollama serve` and `ollama pull <model>` |
| LM Studio model ID mismatch | ID doesn't match server | Check LM Studio's server tab for the exact identifier |
| `developer` role error | Local server doesn't support it | Set `compat.supportsDeveloperRole: false` |
| `stream_options` error | Server doesn't support streaming usage | Set `compat.supportsUsageInStreaming: false` |
| Cost shows $0.00 | Default for custom models | Add `cost` field to model definition |

183
gitbook/core-concepts/auto-mode.md Normal file
View file

@ -0,0 +1,183 @@
# Auto Mode
Auto mode is GSD's autonomous execution engine. Run `/gsd auto`, walk away, come back to built software with clean git history.
## Starting Auto Mode
```
/gsd auto
```
GSD reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh AI session with all relevant context, and lets the AI execute. When it finishes, GSD reads disk state again and dispatches the next unit. This continues until the milestone is complete.
## The Execution Loop
Each slice flows through phases automatically:
```
Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
↓ (all done)
Validate Milestone
```
- **Plan** — scouts the codebase, researches docs, decomposes the slice into tasks
- **Execute** — runs each task in a fresh context window
- **Complete** — writes summary, UAT script, marks roadmap, commits
- **Reassess** — checks if the roadmap still makes sense after what was learned
- **Validate** — after all slices, verifies success criteria were actually met
## Controlling Auto Mode
### Pause
Press **Escape**. The conversation is preserved. You can interact with the agent, inspect state, or resume.
### Resume
```
/gsd auto
```
Auto mode reads disk state and picks up where it left off.
### Stop
```
/gsd stop
```
Stops auto mode gracefully. Can be run from a different terminal.
### Steer
```
/gsd steer
```
Modify plan documents during execution without stopping. Changes are picked up at the next phase boundary.
### Capture Thoughts
```
/gsd capture "add rate limiting to API endpoints"
```
Fire-and-forget thought capture. Captures are triaged automatically between tasks without pausing execution. See [Captures & Triage](../features/captures.md).
## Fresh Session Per Unit
Every task gets a clean AI context window. No accumulated garbage, no quality degradation from context bloat. The dispatch prompt includes everything needed — task plans, prior summaries, decisions, dependency context — so the AI starts oriented.
## Git Isolation
GSD isolates milestone work using one of three modes:
| Mode | How It Works | Best For |
|------|-------------|----------|
| `worktree` (default) | Each milestone gets its own directory and branch | Most projects |
| `branch` | Work happens in the project root on a milestone branch | Submodule-heavy repos |
| `none` | Work happens directly on your current branch | Hot-reload workflows |
In worktree mode, all commits are squash-merged to main as one clean commit when the milestone completes. See [Git & Worktrees](../configuration/git-settings.md).
## Crash Recovery
If a session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
In headless mode (`gsd headless auto`), crashes trigger automatic restart with exponential backoff (5s → 10s → 30s, up to 3 attempts). Combined with crash recovery, this enables true overnight "fire and forget" execution.
## Provider Error Recovery
GSD handles provider errors automatically:
| Error Type | Examples | What Happens |
|-----------|----------|-------------|
| Rate limit | 429, "too many requests" | Auto-resumes after cooldown (60s or retry-after header) |
| Server error | 500, 502, 503, "overloaded" | Auto-resumes after 30s |
| Permanent | "unauthorized", "invalid key" | Pauses — requires manual resume |
No manual intervention needed for transient errors.
## Timeout Supervision
Three timeout tiers prevent runaway sessions:
| Timeout | Default | What Happens |
|---------|---------|-------------|
| Soft | 20 min | Warns the AI to wrap up |
| Idle | 10 min | Detects stalls, intervenes |
| Hard | 30 min | Pauses auto mode |
Configure in preferences:
```yaml
auto_supervisor:
soft_timeout_minutes: 20
idle_timeout_minutes: 10
hard_timeout_minutes: 30
```
## Verification Gates
Configure shell commands that run automatically after every task:
```yaml
verification_commands:
- npm run lint
- npm run test
verification_auto_fix: true # auto-retry on failure
verification_max_retries: 2 # max retry attempts
```
If verification fails, the AI sees the output and attempts to fix the issues before advancing. This ensures quality gates are enforced mechanically.
## Slice Discussion Gate
For projects requiring human review before each slice:
```yaml
require_slice_discussion: true
```
Auto mode pauses before each slice, showing the plan for your approval before building.
## Stuck Detection
GSD uses sliding-window analysis to detect stuck loops — not just "same unit dispatched twice" but also cycles like A→B→A→B. On detection, GSD retries once with a diagnostic prompt. If it fails again, auto mode stops with details so you can intervene.
## Cost Tracking
Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending. See [Cost Management](../features/cost-management.md).
## Dashboard
`Ctrl+Alt+G` or `/gsd status` shows real-time progress:
- Current milestone, slice, and task
- Auto mode elapsed time and phase
- Per-unit cost and token breakdown
- Cost projections
- Completed and in-progress units
- Pending capture count
- Parallel worker status (when running parallel milestones)
## HTML Reports
After a milestone completes, GSD generates a self-contained HTML report in `.gsd/reports/` with project summary, progress tree, dependency graph, cost metrics, timeline, and changelog. Generate manually with:
```
/gsd export --html
/gsd export --html --all # all milestones
```
## Diagnostic Tools
If auto mode has issues, GSD provides two diagnostic tools:
- **`/gsd doctor`** — validates `.gsd/` integrity, checks referential consistency, fixes structural issues
- **`/gsd forensics`** — full post-mortem debugger with anomaly detection, unit traces, metrics analysis, and AI-guided investigation
```
/gsd doctor
/gsd forensics [optional problem description]
```

104
gitbook/core-concepts/project-structure.md Normal file
View file

@ -0,0 +1,104 @@
# How GSD Organizes Work
GSD uses a three-level hierarchy to break projects into manageable pieces that an AI can execute reliably.
## The Hierarchy
```
Milestone → a shippable version (4-10 slices)
Slice → one demoable vertical feature (1-7 tasks)
Task → one context-window-sized unit of work
```
### Milestones
A milestone is a shippable version of your project — an MVP, a major release, or a feature set that delivers standalone value. Milestones typically contain 4-10 slices.
Examples:
- "MVP with user auth, dashboard, and settings"
- "v2.0 with real-time collaboration and API v2"
- "Security hardening milestone"
### Slices
A slice is one demoable, vertical capability within a milestone. It cuts across layers (database, backend, frontend) to deliver something you could show to a user. Slices contain 1-7 tasks.
Examples:
- "User authentication with JWT"
- "Dashboard layout with charts"
- "API rate limiting"
### Tasks
A task is the smallest unit of work — something that fits in one AI context window. If a task can't be completed in a single AI session, it's broken into smaller tasks.
Examples:
- "Create the User model and migration"
- "Implement JWT middleware"
- "Build the login form component"
## The `.gsd/` Directory
All project state lives on disk in a `.gsd/` directory at your project root:
```
.gsd/
PROJECT.md — living description of what the project is
REQUIREMENTS.md — requirement contract (active/validated/deferred)
DECISIONS.md — append-only architectural decisions log
KNOWLEDGE.md — cross-session rules, patterns, and lessons
RUNTIME.md — runtime context: API endpoints, env vars, services
STATE.md — quick-glance status of current work
PREFERENCES.md — project-level preferences (optional)
milestones/
M001/
M001-ROADMAP.md — slice plan with risk levels and dependencies
M001-CONTEXT.md — scope and goals from discussion phase
slices/
S01/
S01-PLAN.md — task decomposition for this slice
S01-SUMMARY.md — what was built and what changed
S01-UAT.md — human test script
tasks/
T01-PLAN.md — detailed plan for this task
T01-SUMMARY.md — what the task accomplished
```
### Key Files
| File | Purpose |
|------|---------|
| `PROJECT.md` | High-level project description, updated as the project evolves |
| `REQUIREMENTS.md` | Formal requirement contract — tracks what's active, validated, and deferred |
| `DECISIONS.md` | Append-only log of architectural decisions with rationale |
| `KNOWLEDGE.md` | Rules, patterns, and lessons learned across sessions — GSD reads this at the start of every task |
| `RUNTIME.md` | Runtime context like API URLs, ports, and environment variables |
| `STATE.md` | Current status at a glance — auto-generated, don't edit manually |
## How Work Flows
Each slice flows through phases:
```
Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
```
1. **Plan** — GSD scouts the codebase, researches relevant docs, and decomposes the slice into tasks with clear requirements
2. **Execute** — Each task runs in a fresh AI session with focused context
3. **Complete** — GSD writes summaries, generates a UAT script, and commits
4. **Reassess** — The roadmap is checked against reality — slices may be reordered, added, or removed
5. **Next Slice** — The loop continues until all slices are done
After all slices complete, a **milestone validation** gate checks that success criteria were actually met before sealing the milestone.
## Adding Knowledge
GSD maintains a knowledge base that persists across sessions. Add rules, patterns, or lessons:
```
/gsd knowledge rule "Always use parameterized queries for database access"
/gsd knowledge pattern "Service classes go in src/services/"
/gsd knowledge lesson "The OAuth flow requires the redirect URL to match exactly"
```
This knowledge is injected into every task prompt automatically.

54
gitbook/core-concepts/step-mode.md Normal file
View file

@ -0,0 +1,54 @@
# Step Mode
Step mode is GSD's interactive, one-step-at-a-time workflow. You stay in the loop, reviewing output between each step.
## Starting Step Mode
```
/gsd
```
GSD reads the state of your `.gsd/` directory and presents a wizard showing what's completed and what's next. It then executes one unit of work and pauses.
## How It Works
Step mode adapts to your project's current state:
| State | What Happens |
|-------|-------------|
| No `.gsd/` directory | Starts a discussion flow to capture your project vision |
| Milestone exists, no roadmap | Opens a discussion or research phase for the milestone |
| Roadmap exists, slices pending | Plans the next slice or executes the next task |
| Mid-task | Resumes where you left off |
After each unit completes, you see results and decide what to do next. This is ideal for:
- New projects where you want to shape the architecture
- Critical work where you want to review each step
- Learning how GSD works before trusting auto mode
## Steering During Step Mode
Between steps, you can:
- **Discuss** — `/gsd discuss` to talk through architecture decisions
- **Skip** — `/gsd skip` to prevent a unit from being dispatched
- **Undo** — `/gsd undo` to revert the last completed unit
- **Switch to auto** — `/gsd auto` to let GSD continue autonomously
## When to Use Step Mode
- **First milestone** — Review GSD's work before trusting it to run solo
- **Architectural decisions** — When you want to guide the approach
- **Unfamiliar codebases** — When you want to ensure GSD understands the project
- **High-stakes changes** — When mistakes would be costly
## Transitioning to Auto Mode
Once you're comfortable with GSD's approach, switch to auto mode:
```
/gsd auto
```
You can always press **Escape** to pause auto mode and return to step-by-step control.

54
gitbook/features/captures.md Normal file
View file

@ -0,0 +1,54 @@
# Captures & Triage
Captures let you fire-and-forget thoughts during auto-mode execution. Instead of pausing auto mode to steer, capture ideas, bugs, or scope changes and let GSD triage them at natural seams between tasks.
## Quick Start
While auto mode is running (or any time):
```
/gsd capture "add rate limiting to the API endpoints"
/gsd capture "the auth flow should support OAuth, not just JWT"
```
Captures are appended to `.gsd/CAPTURES.md` and triaged automatically between tasks.
## How It Works
```
Capture → Triage → Confirm → Resolve → Resume
```
1. **Capture** — your thought is saved with a timestamp
2. **Triage** — between tasks, GSD classifies each capture
3. **Confirm** — you see the proposed resolution and approve or adjust
4. **Resolve** — the resolution is applied
5. **Resume** — auto mode continues
## Classification Types
Each capture is classified into one of five types:
| Type | Meaning | What Happens |
|------|---------|-------------|
| `quick-task` | Small, self-contained fix | Executed immediately |
| `inject` | New task needed in current slice | Task added to active slice |
| `defer` | Important but not urgent | Deferred to roadmap reassessment |
| `replan` | Changes the current approach | Triggers slice replan |
| `note` | Informational, no action needed | Acknowledged, no changes |
Plan-modifying resolutions (inject, replan) require your confirmation.
## Manual Triage
Trigger triage manually at any time:
```
/gsd triage
```
Useful when you've accumulated several captures and want to process them before the next natural seam.
## Dashboard Integration
The progress widget shows a pending capture count badge when captures are waiting for triage.

74
gitbook/features/cost-management.md Normal file
View file

@ -0,0 +1,74 @@
# Cost Management
GSD tracks token usage and cost for every unit of work during auto mode. This data powers the dashboard, budget enforcement, and cost projections.
## Viewing Costs
**Dashboard:** Press `Ctrl+Alt+G` or type `/gsd status` for real-time cost breakdown.
**Visualizer:** `/gsd visualize` → Metrics tab for detailed charts.
**Aggregations:**
- By phase (research, planning, execution, completion, reassessment)
- By slice
- By model
- Project totals
## Budget Ceiling
Set a maximum spend:
```yaml
budget_ceiling: 50.00
```
### Enforcement Modes
```yaml
budget_enforcement: pause # default when ceiling is set
```
| Mode | What Happens |
|------|-------------|
| `warn` | Log a warning, keep going |
| `pause` | Pause auto mode, wait for you |
| `halt` | Stop auto mode entirely |
## Cost Projections
Once at least two slices have completed, GSD projects the remaining cost:
```
Projected remaining: $12.40 ($6.20/slice avg × 2 remaining)
```
## Budget Pressure
When approaching the budget ceiling, GSD automatically uses cheaper models:
| Budget Used | Effect |
|------------|--------|
| < 50% | No adjustment |
| 50-75% | Standard tasks downgrade to lighter models |
| 75-90% | More aggressive downgrading |
| > 90% | Nearly everything downgrades; only complex tasks stay at standard |
This spreads your budget across remaining work instead of exhausting it early.
## Token Profiles & Cost
| Profile | Typical Savings | How |
|---------|----------------|-----|
| `budget` | 40-60% | Cheaper models, phase skipping, minimal context |
| `balanced` | 10-20% | Default models, standard context |
| `quality` | 0% (baseline) | All phases, full context |
## Tips
- Start with `balanced` profile and a generous `budget_ceiling` to establish baseline costs
- Check `/gsd status` after a few slices to see per-slice cost averages
- Switch to `budget` for well-understood, repetitive work
- Use `quality` only when architectural decisions are being made
- Use per-phase model selection to save: Opus for planning, Sonnet for execution
- Enable `dynamic_routing` for automatic model downgrading on simple tasks
- Use `/gsd visualize` → Metrics tab to see where your budget is going

88
gitbook/features/dynamic-model-routing.md Normal file
View file

@ -0,0 +1,88 @@
# Dynamic Model Routing
Dynamic model routing automatically selects cheaper models for simple work and reserves expensive models for complex tasks. This reduces cost by 20-50% without sacrificing quality where it matters.
## Enabling
```yaml
dynamic_routing:
enabled: true
```
## How It Works
Each unit passes through two stages:
1. **Complexity classification** — classifies work as light, standard, or heavy
2. **Capability scoring** — within the tier, ranks models by how well they match the task
**Key rule:** Your configured model is always the ceiling — routing never upgrades beyond what you've set.
| Tier | Typical Work | Model Level |
|------|-------------|-------------|
| Light | Slice completion, UAT, hooks | Haiku-class |
| Standard | Research, planning, execution | Sonnet-class |
| Heavy | Replanning, roadmap reassessment | Opus-class |
## Configuration
```yaml
dynamic_routing:
enabled: true
tier_models: # optional: explicit model per tier
light: claude-haiku-4-5
standard: claude-sonnet-4-6
heavy: claude-opus-4-6
escalate_on_failure: true # bump tier on failure (default)
budget_pressure: true # auto-downgrade near budget ceiling (default)
cross_provider: true # consider models from other providers (default)
capability_routing: true # score models by task fit (default)
```
### Escalate on Failure
When a task fails at a given tier, the router escalates to the next tier on retry: Light → Standard → Heavy. This prevents cheap models from burning retries on work that needs more reasoning.
### Budget Pressure
When approaching the budget ceiling, the router progressively downgrades:
| Budget Used | Effect |
|------------|--------|
| < 50% | No adjustment |
| 50-75% | Standard → Light |
| 75-90% | More aggressive |
| > 90% | Nearly everything → Light |
### Cross-Provider
When enabled, the router may select models from providers other than your primary, using the built-in cost table to find the cheapest model at each tier.
### Capability Routing
Models are scored across 7 dimensions: coding, debugging, research, reasoning, speed, long context handling, and instruction following. Different task types weight these dimensions differently — a research task prioritizes research and reasoning, while an execution task prioritizes coding and instruction following.
Set `capability_routing: false` to revert to simple cheapest-in-tier selection.
## Interaction with Token Profiles
Dynamic routing and token profiles work together:
- **Token profiles** control phase skipping and context compression
- **Dynamic routing** controls per-unit model selection
The `budget` profile + dynamic routing provides maximum cost savings.
## Adaptive Learning
GSD tracks routing outcomes in `.gsd/routing-history.json`. If a tier's failure rate exceeds 20% for a given task type, future classifications are bumped up.
Use `/gsd rate` to submit feedback:
```
/gsd rate over # too powerful — use cheaper next time
/gsd rate ok # just right
/gsd rate under # too weak — use stronger next time
```
Feedback is weighted 2x compared to automatic outcomes.

44
gitbook/features/github-sync.md Normal file
View file

@ -0,0 +1,44 @@
# GitHub Sync
GSD can auto-sync milestones, slices, and tasks to GitHub Issues, PRs, and Milestones.
## Setup
1. Install and authenticate the `gh` CLI:
```bash
gh auth login
```
2. Enable in preferences:
```yaml
github:
enabled: true
repo: "owner/repo" # auto-detected from git remote if omitted
labels: [gsd, auto-generated] # labels for created items
```
## Commands
| Command | Description |
|---------|-------------|
| `/github-sync bootstrap` | Initial setup — creates GitHub Milestones, Issues, and draft PRs from current `.gsd/` state |
| `/github-sync status` | Show sync mapping counts (milestones, slices, tasks) |
## How It Works
- Milestones → GitHub Milestones
- Slices → GitHub Issues (linked to milestone)
- Tasks → GitHub Issue checklists
- Completed slices → Draft PRs
Sync mapping is persisted in `.gsd/.github-sync.json`. The sync is rate-limit aware — it skips when the GitHub API rate limit is low.
## Configuration
```yaml
github:
enabled: true
repo: "owner/repo"
labels: [gsd, auto-generated]
project: "Project ID" # optional: GitHub Project board
```

86
gitbook/features/headless.md Normal file
View file

@ -0,0 +1,86 @@
# Headless & CI Mode
`gsd headless` runs GSD commands without a terminal UI — designed for CI pipelines, cron jobs, and scripted automation.
## Basic Usage
```bash
# Run auto mode
gsd headless
# Run a single unit
gsd headless next
# With timeout for CI
gsd headless --timeout 600000 auto
# Force a specific phase
gsd headless dispatch plan
# Stream all events as JSONL
gsd headless --json auto
```
## Creating Milestones Headlessly
```bash
# From a context file
gsd headless new-milestone --context brief.md --auto
# From inline text
gsd headless new-milestone --context-text "Build a REST API with auth"
# Pipe from stdin
echo "Build a CLI tool" | gsd headless new-milestone --context -
```
## CLI Flags
| Flag | Default | Description |
|------|---------|-------------|
| `--timeout N` | 300000 (5 min) | Overall timeout in milliseconds |
| `--max-restarts N` | 3 | Auto-restart on crash (0 to disable) |
| `--json` | — | Stream events as JSONL to stdout |
| `--model ID` | — | Override model for this session |
| `--context <file>` | — | Context file for `new-milestone` (use `-` for stdin) |
| `--context-text <text>` | — | Inline context for `new-milestone` |
| `--auto` | — | Chain into auto mode after milestone creation |
## Exit Codes
| Code | Meaning |
|------|---------|
| `0` | Complete |
| `1` | Error or timeout |
| `2` | Blocked |
## Instant State Query
`gsd headless query` returns a JSON snapshot of project state — no AI session, instant response (~50ms):
```bash
gsd headless query | jq '.state.phase'
# "executing"
gsd headless query | jq '.next'
# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"}
gsd headless query | jq '.cost.total'
# 4.25
```
Any `/gsd` subcommand works as a positional argument: `gsd headless status`, `gsd headless doctor`, etc.
## MCP Server Mode
`gsd --mode mcp` runs GSD as a Model Context Protocol server over stdin/stdout, exposing all GSD tools to external AI clients:
```bash
gsd --mode mcp
```
Compatible with Claude Desktop, VS Code Copilot, and any MCP host.
## Auto-Restart
In headless mode, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). SIGINT/SIGTERM bypasses restart. Combined with crash recovery, this enables true overnight unattended execution.

97
gitbook/features/parallel.md Normal file
View file

@ -0,0 +1,97 @@
# Parallel Orchestration
Run multiple milestones simultaneously in isolated git worktrees. Each milestone gets its own worker process, branch, and context window.
{% hint style="info" %}
Parallel mode is off by default. Enable it in preferences to use `/gsd parallel` commands.
{% endhint %}
## Quick Start
1. Enable parallel mode:
```yaml
parallel:
enabled: true
max_workers: 2
```
2. Start parallel execution:
```
/gsd parallel start
```
GSD scans milestones, checks dependencies and file overlap, shows an eligibility report, and spawns workers.
3. Monitor:
```
/gsd parallel status
```
4. Stop:
```
/gsd parallel stop
```
## How It Works
Each worker is a separate GSD process with complete isolation:
| Resource | Isolation |
|----------|----------|
| Filesystem | Own git worktree |
| Git branch | `milestone/<MID>` |
| Context window | Separate process |
| Metrics | Own `metrics.json` |
| Crash recovery | Own `auto.lock` |
Workers communicate with the coordinator through file-based IPC — heartbeat files and signal files in `.gsd/parallel/`.
## Eligibility
Before starting, GSD checks which milestones can run concurrently:
1. **Not complete** — finished milestones are skipped
2. **Dependencies satisfied** — all `dependsOn` entries must be complete
3. **File overlap** — milestones touching the same files get a warning (but are still eligible since they run in separate worktrees)
## Configuration
```yaml
parallel:
enabled: false # master toggle (default: false)
max_workers: 2 # concurrent workers (1-4)
budget_ceiling: 50.00 # aggregate cost limit
merge_strategy: "per-milestone" # when to merge back
auto_merge: "confirm" # "auto", "confirm", or "manual"
```
## Commands
| Command | Description |
|---------|-------------|
| `/gsd parallel start` | Analyze and start workers |
| `/gsd parallel status` | Show all workers with progress and cost |
| `/gsd parallel stop [MID]` | Stop all or a specific worker |
| `/gsd parallel pause [MID]` | Pause all or a specific worker |
| `/gsd parallel resume [MID]` | Resume paused workers |
| `/gsd parallel merge [MID]` | Merge completed milestones to main |
## Merge Reconciliation
When milestones complete, their changes merge back to main:
- `.gsd/` state files are auto-resolved
- Code conflicts halt the merge — resolve manually and retry with `/gsd parallel merge <MID>`
## Budget Management
When `budget_ceiling` is set, aggregate cost across all workers is tracked. When the ceiling is reached, workers are signaled to stop.
## Troubleshooting
| Problem | Fix |
|---------|-----|
| "Parallel mode is not enabled" | Set `parallel.enabled: true` |
| "No eligible milestones" | All milestones are complete or blocked; check `/gsd queue` |
| Worker crashed | Run `/gsd doctor --fix`, then `/gsd parallel start` |
| Merge conflicts | Resolve in `.gsd/worktrees/<MID>/`, then `/gsd parallel merge <MID>` |
| Workers seem stuck | Check if budget ceiling was reached via `/gsd parallel status` |

90
gitbook/features/remote-questions.md Normal file
View file

@ -0,0 +1,90 @@
# Remote Questions
Remote questions let GSD ask for your input via Slack, Discord, or Telegram when running in headless auto mode. When GSD needs a decision, it posts the question to your configured channel and polls for a response.
## Setup
### Discord
```
/gsd remote discord
```
The wizard prompts for your bot token, validates it, lets you pick a server and channel, sends a test message, and saves the config.
**Bot requirements:**
- A bot application with a token from the [Discord Developer Portal](https://discord.com/developers/applications)
- Bot invited to the server with: Send Messages, Read Message History, Add Reactions, View Channel
- `DISCORD_BOT_TOKEN` environment variable set
### Slack
```
/gsd remote slack
```
**Bot requirements:**
- A Slack app with a bot token (`xoxb-...`) from [Slack API](https://api.slack.com/apps)
- Bot invited to the target channel
- Scopes: `chat:write`, `reactions:read`, `reactions:write`, `channels:read`, `groups:read`, `channels:history`, `groups:history`
### Telegram
```
/gsd remote telegram
```
**Bot requirements:**
- A bot token from [@BotFather](https://t.me/BotFather)
- Bot added to the target group chat
- `TELEGRAM_BOT_TOKEN` environment variable set
## Configuration
```yaml
remote_questions:
channel: discord # or slack or telegram
channel_id: "1234567890123456789"
timeout_minutes: 5 # 1-30, default 5
poll_interval_seconds: 5 # 2-30, default 5
```
## How It Works
1. GSD encounters a decision point during auto mode
2. The question is posted to your channel as a rich message
3. GSD polls for a response at the configured interval
4. You respond by:
- **Reacting** with a number emoji (1️⃣, 2️⃣, etc.) for single-question prompts
- **Replying** with a number, comma-separated numbers, or free text
5. GSD picks up the response and continues
6. A ✅ reaction confirms receipt
### Response Formats
**Single question:** React with a number emoji, reply with a number, or reply with free text.
**Multiple questions:** Reply with semicolons (`1;2;custom text`) or newlines (one answer per line).
### Timeouts
If no response arrives within `timeout_minutes`, GSD continues with a timeout result — typically making a conservative default choice.
## Commands
| Command | Description |
|---------|-------------|
| `/gsd remote` | Show menu and current status |
| `/gsd remote slack` | Set up Slack |
| `/gsd remote discord` | Set up Discord |
| `/gsd remote telegram` | Set up Telegram |
| `/gsd remote status` | Show current config |
| `/gsd remote disconnect` | Remove configuration |
## Troubleshooting
| Problem | Fix |
|---------|-----|
| "Remote auth failed" | Verify bot token is correct and not expired |
| "Could not send to channel" | Check bot has Send Messages permission; invite bot to channel |
| No response detected | Make sure you're replying to the prompt message, not posting a new one |

120
gitbook/features/skills.md Normal file
View file

@ -0,0 +1,120 @@
# Skills
Skills are specialized instruction sets that GSD loads when the task matches. They provide domain-specific guidance — coding patterns, framework idioms, testing strategies, and tool usage.
Skills follow the open [Agent Skills standard](https://agentskills.io/) and work across multiple AI agents, not just GSD.
## Skill Directories
| Location | Scope | Description |
|----------|-------|------------|
| `~/.agents/skills/` | Global | Shared across all projects |
| `.agents/skills/` (project root) | Project | Project-specific, committable to git |
Global skills take precedence when names collide.
## Installing Skills
Skills are installed via the [skills.sh CLI](https://skills.sh):
```bash
# Interactive — choose skills and target agents
npx skills add dpearson2699/swift-ios-skills
# Install specific skills
npx skills add dpearson2699/swift-ios-skills --skill swift-concurrency --skill swiftui-patterns -y
# Install all from a repo
npx skills add dpearson2699/swift-ios-skills --all
# Check for updates
npx skills check
# Update installed skills
npx skills update
```
## Onboarding Catalog
During `gsd init`, GSD detects your project's tech stack and recommends relevant skill packs:
- **Swift** — SwiftUI, Swift Core, concurrency, Charts, Testing
- **iOS** — App Intents, Widgets, StoreKit, MapKit, Core ML, Vision, accessibility
- **Web** — React, React Native, frontend design, accessibility
- **Languages** — Rust, Python, Go patterns and best practices
- **General** — Document handling (PDF, DOCX, XLSX)
## Skill Discovery
The `skill_discovery` preference controls how GSD finds skills during auto mode:
| Mode | Behavior |
|------|----------|
| `auto` | Skills found and applied automatically |
| `suggest` | Skills identified but require confirmation (default) |
| `off` | No skill discovery |
## Skill Preferences
Control which skills are used:
```yaml
always_use_skills:
- debug-like-expert
prefer_skills:
- frontend-design
avoid_skills:
- security-docker
skill_rules:
- when: task involves authentication
use: [clerk]
- when: frontend styling work
prefer: [frontend-design]
```
## Creating Custom Skills
Create your own skill by adding a directory with a `SKILL.md` file:
```
~/.agents/skills/my-skill/
SKILL.md — instructions for the AI
references/ — optional reference files
```
The `SKILL.md` contains instructions the AI follows when the skill is active.
### Project-Local Skills
Place skills in your project root for project-specific guidance:
```
.agents/skills/my-project-skill/
SKILL.md
```
Project-local skills can be committed to git so team members share the same skill set.
## Skill Health Dashboard
Track skill performance:
```
/gsd skill-health # overview table
/gsd skill-health rust-core # detailed view for one skill
/gsd skill-health --stale 30 # skills unused for 30+ days
/gsd skill-health --declining # skills with falling success rates
```
The dashboard flags:
- Success rate below 70% over the last 10 uses
- Token usage rising 20%+ compared to previous window
- Skills unused beyond the configured threshold
### Staleness Detection
```yaml
skill_staleness_days: 60 # flag skills unused for 60+ days (0 to disable)
```
Stale skills are excluded from automatic matching but remain available for explicit use.

91
gitbook/features/teams.md Normal file
View file

@ -0,0 +1,91 @@
# Working in Teams
GSD supports multi-user workflows where several developers work on the same repository concurrently.
## Quick Setup
The simplest way: set team mode in your project preferences.
```yaml
# .gsd/PREFERENCES.md (committed to git)
---
version: 1
mode: team
---
```
This enables unique milestone IDs, push branches, pre-merge checks, and other team-appropriate defaults in one setting.
## What Team Mode Does
| Setting | Effect |
|---------|--------|
| `unique_milestone_ids` | IDs like `M001-eh88as` instead of `M001` — no collisions |
| `git.push_branches` | Milestone branches are pushed to remote |
| `git.pre_merge_check` | Validation runs before merging |
You can override individual settings on top of `mode: team`.
## Configure `.gitignore`
Share planning artifacts while keeping runtime files local:
```bash
# Runtime files (per-developer, gitignore these)
.gsd/auto.lock
.gsd/completed-units.json
.gsd/STATE.md
.gsd/metrics.json
.gsd/activity/
.gsd/runtime/
.gsd/worktrees/
.gsd/milestones/**/continue.md
.gsd/milestones/**/*-CONTINUE.md
```
**What gets shared** (committed to git):
- `.gsd/PREFERENCES.md` — project preferences
- `.gsd/PROJECT.md` — living project description
- `.gsd/REQUIREMENTS.md` — requirement contract
- `.gsd/DECISIONS.md` — architectural decisions
- `.gsd/milestones/` — roadmaps, plans, summaries, research
**What stays local** (gitignored):
- Lock files, metrics, state, activity logs, worktrees
## Commit the Config
```bash
git add .gsd/PREFERENCES.md
git commit -m "chore: enable GSD team workflow"
```
## Keeping `.gsd/` Local
For teams where only some members use GSD:
```yaml
git:
commit_docs: false
```
This gitignores `.gsd/` entirely. You get structured planning without affecting teammates.
## Parallel Development
Multiple developers can run auto mode simultaneously on different milestones. Each developer:
- Gets their own worktree (`.gsd/worktrees/<MID>/`)
- Works on a unique `milestone/<MID>` branch
- Squash-merges to main independently
Milestone dependencies can be declared:
```yaml
# In M00X-CONTEXT.md frontmatter
---
depends_on: [M001-eh88as]
---
```
GSD enforces that dependent milestones complete before starting downstream work.

108
gitbook/features/token-optimization.md Normal file
View file

@ -0,0 +1,108 @@
# Token Optimization
GSD's token optimization system can reduce token usage by 40-60% without sacrificing output quality. It has three pillars: **token profiles**, **context compression**, and **complexity-based task routing**.
## Token Profiles
A token profile coordinates model selection, phase skipping, and context compression with a single setting:
```yaml
token_profile: balanced
```
### `budget` — Maximum Savings (40-60%)
| Setting | Value |
|---------|-------|
| Planning model | Sonnet |
| Execution model | Sonnet |
| Simple task model | Haiku |
| Milestone research | Skipped |
| Slice research | Skipped |
| Roadmap reassessment | Skipped |
| Context level | Minimal |
Best for: prototyping, small projects, well-understood codebases.
### `balanced` — Smart Defaults (default)
| Setting | Value |
|---------|-------|
| All models | User's default |
| Milestone research | Runs |
| Slice research | Skipped |
| Roadmap reassessment | Runs |
| Context level | Standard |
Best for: most projects, day-to-day development.
### `quality` — Full Context
| Setting | Value |
|---------|-------|
| All models | User's configured defaults |
| All phases | Run |
| Context level | Full |
Best for: complex architectures, greenfield projects, critical work.
## Context Compression
Each profile controls how much context is pre-loaded into AI prompts:
| Profile | What's Included |
|---------|----------------|
| `budget` | Task plan and essential prior summaries only |
| `balanced` | Task plan, summaries, slice plan, roadmap excerpt |
| `quality` | Everything — all plans, summaries, decisions, requirements |
## Complexity-Based Task Routing
GSD classifies each task by complexity and routes it to an appropriate model:
| Complexity | Indicators | Model Level |
|-----------|------------|-------------|
| Simple | ≤3 steps, ≤3 files, short description | Haiku-class |
| Standard | 4-7 steps, 4-7 files | Sonnet-class |
| Complex | ≥8 steps, ≥8 files, complexity keywords | Opus-class |
**Complexity keywords** that prevent simple classification: `refactor`, `migrate`, `integrate`, `architect`, `security`, `performance`, `concurrent`, `distributed`, and others.
{% hint style="info" %}
Dynamic routing requires `models` configured in your preferences and `dynamic_routing.enabled: true`. See [Dynamic Model Routing](dynamic-model-routing.md).
{% endhint %}
## Overriding Profile Defaults
The `token_profile` sets defaults, but explicit preferences always win:
```yaml
token_profile: budget
phases:
skip_research: false # override: keep research
models:
planning: claude-opus-4-6 # override: use Opus for planning
```
## Adaptive Learning
GSD tracks success and failure of tier assignments over time. If a model tier's failure rate exceeds 20% for a given task type, future tasks of that type are bumped to a higher tier.
Submit manual feedback with:
```
/gsd rate over # model was overpowered — use cheaper next time
/gsd rate ok # model was appropriate
/gsd rate under # model was too weak — use stronger next time
```
## Observation Masking
During auto mode, old tool results are replaced with lightweight placeholders before each AI call. This reduces token usage between compactions with zero overhead.
```yaml
context_management:
observation_masking: true # default: true
observation_mask_turns: 8 # keep results from last 8 turns
tool_result_max_chars: 800 # truncate large tool outputs
```

82
gitbook/features/visualizer.md Normal file
View file

@ -0,0 +1,82 @@
# Workflow Visualizer
The workflow visualizer is a full-screen terminal overlay showing project progress, dependencies, cost metrics, and execution timeline.
## Opening
```
/gsd visualize
```
Or configure automatic display after milestone completion:
```yaml
auto_visualize: true
```
## Tabs
Switch tabs with `Tab`, `1`-`4`, or arrow keys.
### 1. Progress
A tree view of milestones, slices, and tasks with completion status:
```
M001: User Management 3/6 tasks
✅ S01: Auth module 3/3 tasks
✅ T01: Core types
✅ T02: JWT middleware
✅ T03: Login flow
⏳ S02: User dashboard 1/2 tasks
✅ T01: Layout component
⬜ T02: Profile page
```
### 2. Dependencies
An ASCII dependency graph showing slice relationships:
```
S01 ──→ S02 ──→ S04
└───→ S03 ──↗
```
### 3. Metrics
Bar charts showing cost and token usage:
- By phase (research, planning, execution, completion)
- By slice (with running totals)
- By model (which models consumed the most budget)
### 4. Timeline
Chronological execution history: unit type, timestamps, duration, model, and token counts.
## Controls
| Key | Action |
|-----|--------|
| `Tab` | Next tab |
| `Shift+Tab` | Previous tab |
| `1`-`4` | Jump to tab |
| `↑`/`↓` | Scroll |
| `Escape` / `q` | Close |
The visualizer auto-refreshes every 2 seconds, staying current alongside running auto mode.
## HTML Reports
For shareable reports outside the terminal:
```
/gsd export --html # current milestone
/gsd export --html --all # all milestones
```
Generates self-contained HTML files in `.gsd/reports/` with progress tree, dependency graph, cost charts, timeline, and changelog. All CSS and JS are inlined — no external dependencies. Printable to PDF from any browser.
```yaml
auto_report: true # auto-generate after milestone completion (default)
```

37
gitbook/features/web-interface.md Normal file
View file

@ -0,0 +1,37 @@
# Web Interface
GSD includes a browser-based interface for project management and real-time progress monitoring.
## Quick Start
```bash
gsd --web
```
This starts a local web server and opens the dashboard in your default browser.
## CLI Flags
```bash
gsd --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com"
```
| Flag | Default | Description |
|------|---------|-------------|
| `--host` | `localhost` | Bind address |
| `--port` | `3000` | Port |
| `--allowed-origins` | (none) | Comma-separated CORS origins |
## Features
- **Project management** — view milestones, slices, and tasks in a visual dashboard
- **Real-time progress** — live updates as auto mode executes
- **Multi-project support** — manage multiple projects from one browser tab via `?project=` URL parameter
- **Change project root** — switch directories from the web UI without restarting
- **Onboarding flow** — API key setup and provider configuration in the browser
- **Model selection** — switch models and providers from the web UI
## Platform Notes
- **macOS/Linux** — Full support
- **Windows** — Web build is skipped due to Next.js compatibility issues; CLI remains fully functional

45
gitbook/features/workflow-templates.md Normal file
View file

@ -0,0 +1,45 @@
# Workflow Templates
Workflow templates are pre-built patterns for common development tasks. Instead of setting up a full milestone for a quick bugfix or spike, use a template to get started immediately.
## Using Templates
```
/gsd start # pick from available templates
/gsd start resume # resume an in-progress workflow
```
## Available Templates
| Template | Purpose |
|----------|---------|
| `bugfix` | Fix a specific bug with diagnosis and verification |
| `spike` | Time-boxed investigation or prototype |
| `feature` | Standard feature development |
| `hotfix` | Urgent production fix |
| `refactor` | Code restructuring and cleanup |
| `security-audit` | Security review and remediation |
| `dep-upgrade` | Dependency update and migration |
| `full-project` | Complete project from scratch |
## Listing and Inspecting
```
/gsd templates # list all available templates
/gsd templates info <name> # show details for a template
```
## Custom Workflows
Create your own workflow definitions:
```
/gsd workflow new # create a new workflow YAML
/gsd workflow run <name> # start a workflow run
/gsd workflow list # list active runs
/gsd workflow validate <name> # validate definition
/gsd workflow pause # pause running workflow
/gsd workflow resume # resume paused workflow
```
Custom workflows are defined in YAML and can specify phases, dependencies, and configuration for each step.

94
gitbook/getting-started/choosing-a-model.md Normal file
View file

@ -0,0 +1,94 @@
# Choosing a Model
GSD auto-selects a default model after you log in to a provider. You can switch models at any time.
## Switch Models
Inside a GSD session, type:
```
/model
```
This opens an interactive picker showing all available models from your configured providers.
## Per-Phase Models
Different phases of work have different requirements. You can assign specific models to each phase in your preferences:
```yaml
models:
research: claude-sonnet-4-6 # scouting and research
planning: claude-opus-4-6 # architectural decisions
execution: claude-sonnet-4-6 # writing code
execution_simple: claude-haiku-4-5 # simple tasks (docs, config)
completion: claude-sonnet-4-6 # summaries and wrap-up
subagent: claude-sonnet-4-6 # delegated sub-tasks
```
Omit a key to use whatever model is currently active for that phase.
## Model Fallbacks
If a model is unavailable (provider down, rate limited, credits exhausted), GSD can automatically fall back to another:
```yaml
models:
planning:
model: claude-opus-4-6
fallbacks:
- openrouter/z-ai/glm-5
- openrouter/moonshotai/kimi-k2.5
```
Fallbacks are tried in order until one works.
## Token Profiles
Token profiles coordinate model selection, phase skipping, and context compression with a single setting:
| Profile | Cost Savings | Best For |
|---------|-------------|----------|
| `budget` | 40-60% | Prototyping, small projects, well-understood codebases |
| `balanced` | 10-20% | Most projects, day-to-day development (default) |
| `quality` | 0% (baseline) | Complex architectures, greenfield projects, critical work |
```yaml
token_profile: balanced
```
See [Token Optimization](../features/token-optimization.md) for details.
## Dynamic Model Routing
When enabled, GSD automatically picks cheaper models for simple tasks and reserves expensive ones for complex work:
```yaml
dynamic_routing:
enabled: true
```
A documentation fix gets Haiku. An architectural refactor gets Opus. Your configured model is always the ceiling — routing never upgrades beyond what you've set.
See [Dynamic Model Routing](../features/dynamic-model-routing.md) for the full guide.
## Supported Providers
GSD supports 20+ providers out of the box. See [Provider Setup](../configuration/providers.md) for setup instructions:
| Provider | Auth Method |
|----------|-------------|
| Anthropic (Claude) | OAuth or API key |
| OpenAI | API key |
| Google Gemini | API key |
| OpenRouter | API key |
| Groq | API key |
| xAI (Grok) | API key |
| Mistral | API key |
| GitHub Copilot | OAuth |
| Amazon Bedrock | IAM credentials |
| Vertex AI | ADC |
| Azure OpenAI | API key |
| Ollama | Local (no auth) |
| LM Studio | Local (no auth) |
| vLLM / SGLang | Local (no auth) |

128
gitbook/getting-started/first-project.md Normal file
View file

@ -0,0 +1,128 @@
# Your First Project
## Launch GSD
Open a terminal in any project directory (or an empty one) and run:
```bash
gsd
```
GSD shows a welcome screen with your version, active model, and available tool keys.
## Start a Discussion
Type `/gsd` to enter step mode. GSD reads the state of your project directory and determines the next logical action:
- **No `.gsd/` directory** — starts a discussion flow to capture your project vision
- **Milestone exists, no roadmap** — discuss or research the milestone
- **Roadmap exists, slices pending** — plan the next slice or execute a task
- **Mid-task** — resume where you left off
For a new project, GSD will ask you to describe what you want to build. Talk through your vision — GSD captures requirements, architectural decisions, and scope.
## The Project Hierarchy
After discussion, GSD organizes your work into:
```
Milestone → a shippable version (4-10 slices)
Slice → one demoable feature (1-7 tasks)
Task → one context-window-sized unit of work
```
The key rule: **a task must fit in one AI context window.** If it can't, it becomes two tasks.
## Run Auto Mode
Once you have a milestone and roadmap, let GSD take the wheel:
```
/gsd auto
```
GSD autonomously:
1. **Plans** each slice — scouts the codebase, researches docs, decomposes into tasks
2. **Executes** each task — writes code in a fresh AI session
3. **Completes** the slice — writes summaries, commits with meaningful messages
4. **Reassesses** the roadmap — checks if the plan still makes sense
5. **Repeats** until the milestone is done
## The Two-Terminal Workflow
The recommended approach: auto mode in one terminal, steering from another.
**Terminal 1 — let it build:**
```bash
gsd
/gsd auto
```
**Terminal 2 — steer while it works:**
```bash
gsd
/gsd discuss # talk through architecture decisions
/gsd status # check progress
/gsd queue # queue the next milestone
/gsd capture "add rate limiting to the API" # fire-and-forget thought
```
Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically.
## Check Progress
Press `Ctrl+Alt+G` or type `/gsd status` to see the dashboard:
- Current milestone, slice, and task
- Elapsed time and phase
- Per-unit cost and token breakdown
- Completed and in-progress work
## Resume a Session
```bash
gsd --continue # or gsd -c
```
Resumes the most recent session for the current directory.
To browse and pick from all saved sessions:
```bash
gsd sessions
```
Shows each session's date, message count, and preview so you can choose which to resume.
## What's on Disk
All state lives in `.gsd/` inside your project:
```
.gsd/
PROJECT.md — what the project is
REQUIREMENTS.md — requirement contract
DECISIONS.md — architectural decisions
KNOWLEDGE.md — cross-session rules and patterns
STATE.md — quick-glance status
milestones/
M001/
M001-ROADMAP.md — slice plan with dependencies
M001-CONTEXT.md — scope and goals
slices/
S01/
S01-PLAN.md — task decomposition
S01-SUMMARY.md — what happened
S01-UAT.md — test script
tasks/
T01-PLAN.md
T01-SUMMARY.md
```
## Next Steps
- [Auto Mode](../core-concepts/auto-mode.md) — deep dive into autonomous execution
- [Preferences](../configuration/preferences.md) — model selection, timeouts, budgets
- [Commands](../reference/commands.md) — all commands and shortcuts

84
gitbook/getting-started/installation.md Normal file
View file

@ -0,0 +1,84 @@
# Installation
## Install GSD
```bash
npm install -g gsd-pi
```
Requires **Node.js 22.0.0 or later** (24 LTS recommended) and **Git**.
{% hint style="info" %}
**`command not found: gsd`?** Your shell may not have npm's global bin directory in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin` to your PATH. See [Troubleshooting](../reference/troubleshooting.md) for details.
{% endhint %}
GSD checks for updates once every 24 hours. When a new version is available, you'll see a prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`.
## Set Up Your LLM Provider
Launch GSD for the first time:
```bash
gsd
```
The setup wizard walks you through:
1. **LLM Provider** — choose from 20+ providers (Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, Azure, and more). OAuth flows handle Claude Max and Copilot subscriptions automatically; otherwise paste an API key.
2. **Tool API Keys** (optional) — Brave Search, Context7, Jina, Slack, Discord. Press Enter to skip any.
Re-run the wizard anytime with:
```bash
gsd config
```
For detailed provider setup, see [Provider Setup](../configuration/providers.md).
## Set Up API Keys for Tools
If you use a non-Anthropic model, you may need a search API key for web search. Run `/gsd config` inside any GSD session to set keys globally — they're saved to `~/.gsd/agent/auth.json` and apply to all projects.
| Tool | Purpose | Get a Key |
|------|---------|-----------|
| Tavily Search | Web search for non-Anthropic models | [tavily.com](https://tavily.com/app/api-keys) |
| Brave Search | Web search for non-Anthropic models | [brave.com](https://brave.com/search/api) |
| Context7 Docs | Library documentation lookup | [context7.com](https://context7.com/dashboard) |
Anthropic models have built-in web search and don't need these keys.
## VS Code Extension
GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions.
The extension provides:
- **`@gsd` chat participant** — talk to the agent in VS Code Chat
- **Sidebar dashboard** — connection status, model info, token usage, quick actions
- **Full command palette** — start/stop agent, switch models, export sessions
The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC.
## Web Interface
GSD also has a browser-based interface:
```bash
gsd --web
```
This starts a local web server with a visual dashboard, real-time progress, and multi-project support. See [Web Interface](../features/web-interface.md) for details.
## Alternative Binary Name
If the `gsd` command conflicts with another tool (e.g., the oh-my-zsh git plugin aliases `gsd` to `git svn dcommit`), use the alternative:
```bash
gsd-cli
```
Both `gsd` and `gsd-cli` point to the same binary. To remove the conflict permanently, add this to your `~/.zshrc`:
```bash
unalias gsd 2>/dev/null
```

61
gitbook/reference/cli-flags.md Normal file
View file

@ -0,0 +1,61 @@
# CLI Flags
## Starting GSD
| Flag | Description |
|------|-------------|
| `gsd` | Start a new interactive session |
| `gsd --continue` (`-c`) | Resume the most recent session |
| `gsd --model <id>` | Override the default model for this session |
| `gsd --web [path]` | Start browser-based web interface |
| `gsd --worktree` (`-w`) [name] | Start in a git worktree |
| `gsd --no-session` | Disable session persistence |
| `gsd --extension <path>` | Load an additional extension (repeatable) |
| `gsd --append-system-prompt <text>` | Append text to the system prompt |
| `gsd --tools <list>` | Comma-separated tools to enable |
| `gsd --version` (`-v`) | Print version and exit |
| `gsd --help` (`-h`) | Print help and exit |
| `gsd --debug` | Enable diagnostic logging |
## Non-Interactive Modes
| Flag | Description |
|------|-------------|
| `gsd --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) |
| `gsd --mode <text\|json\|rpc\|mcp>` | Output mode for non-interactive use |
## Session Management
| Command | Description |
|---------|-------------|
| `gsd sessions` | Interactive session picker — list and resume saved sessions |
| `gsd --list-models [search]` | List available models and exit |
## Configuration
| Command | Description |
|---------|-------------|
| `gsd config` | Set up global API keys |
| `gsd update` | Update to the latest version |
## Headless Mode
| Flag | Description |
|------|-------------|
| `gsd headless` | Run without TUI |
| `gsd headless --timeout N` | Timeout in ms (default: 300000) |
| `gsd headless --max-restarts N` | Auto-restart on crash (default: 3) |
| `gsd headless --json` | Stream events as JSONL |
| `gsd headless --model ID` | Override model |
| `gsd headless --context <file>` | Context file for `new-milestone` |
| `gsd headless --context-text <text>` | Inline context for `new-milestone` |
| `gsd headless --auto` | Chain into auto mode after milestone creation |
| `gsd headless query` | Instant JSON state snapshot (~50ms) |
## Web Interface
| Flag | Default | Description |
|------|---------|-------------|
| `--host` | `localhost` | Bind address |
| `--port` | `3000` | Port |
| `--allowed-origins` | (none) | CORS origins |

128
gitbook/reference/commands.md Normal file
View file

@ -0,0 +1,128 @@
# Commands
## Session Commands
| Command | Description |
|---------|-------------|
| `/gsd` | Step mode — execute one unit at a time |
| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat |
| `/gsd quick` | Quick task with GSD guarantees but no full planning |
| `/gsd stop` | Stop auto mode gracefully |
| `/gsd pause` | Pause auto mode (preserves state) |
| `/gsd steer` | Modify plan documents during execution |
| `/gsd discuss` | Discuss architecture and decisions |
| `/gsd status` | Progress dashboard |
| `/gsd widget` | Cycle dashboard widget: full / small / min / off |
| `/gsd queue` | Queue and reorder future milestones |
| `/gsd capture` | Fire-and-forget thought capture |
| `/gsd triage` | Manually trigger capture triage |
| `/gsd dispatch` | Dispatch a specific phase directly |
| `/gsd history` | View execution history (supports `--cost`, `--phase`, `--model` filters) |
| `/gsd forensics` | Full debugger for auto-mode failures |
| `/gsd cleanup` | Clean up state files and stale worktrees |
| `/gsd visualize` | Open workflow visualizer |
| `/gsd export --html` | Generate HTML report for current milestone |
| `/gsd export --html --all` | Generate reports for all milestones |
| `/gsd update` | Update GSD to the latest version |
| `/gsd knowledge` | Add persistent project knowledge |
| `/gsd fast` | Toggle service tier for supported models |
| `/gsd rate` | Rate last unit's model tier (over/ok/under) |
| `/gsd changelog` | Show release notes |
| `/gsd logs` | Browse activity and debug logs |
| `/gsd remote` | Control remote auto-mode |
| `/gsd help` | Show all available commands |
## Configuration & Diagnostics
| Command | Description |
|---------|-------------|
| `/gsd prefs` | Preferences wizard |
| `/gsd mode` | Switch workflow mode (solo/team) |
| `/gsd config` | Re-run provider setup wizard |
| `/gsd keys` | API key manager |
| `/gsd doctor` | Runtime health checks with auto-fix |
| `/gsd inspect` | Show database diagnostics |
| `/gsd init` | Project init wizard |
| `/gsd setup` | Global setup status |
| `/gsd skill-health` | Skill lifecycle dashboard |
| `/gsd hooks` | Show configured hooks |
| `/gsd migrate` | Migrate v1 `.planning` to `.gsd` format |
## Milestone Management
| Command | Description |
|---------|-------------|
| `/gsd new-milestone` | Create a new milestone |
| `/gsd skip` | Prevent a unit from auto-mode dispatch |
| `/gsd undo` | Revert last completed unit |
| `/gsd undo-task` | Reset a specific task's completion state |
| `/gsd reset-slice` | Reset a slice and all its tasks |
| `/gsd park` | Park a milestone (skip without deleting) |
| `/gsd unpark` | Reactivate a parked milestone |
## Parallel Orchestration
| Command | Description |
|---------|-------------|
| `/gsd parallel start` | Analyze and start parallel workers |
| `/gsd parallel status` | Show worker state and progress |
| `/gsd parallel stop [MID]` | Stop workers |
| `/gsd parallel pause [MID]` | Pause workers |
| `/gsd parallel resume [MID]` | Resume workers |
| `/gsd parallel merge [MID]` | Merge completed milestones |
## Workflow Templates
| Command | Description |
|---------|-------------|
| `/gsd start` | Start a workflow template |
| `/gsd start resume` | Resume an in-progress workflow |
| `/gsd templates` | List available templates |
| `/gsd templates info <name>` | Show template details |
## Custom Workflows
| Command | Description |
|---------|-------------|
| `/gsd workflow new` | Create a workflow definition |
| `/gsd workflow run <name>` | Start a workflow run |
| `/gsd workflow list` | List workflow runs |
| `/gsd workflow validate <name>` | Validate a workflow YAML |
| `/gsd workflow pause` | Pause workflow auto-mode |
| `/gsd workflow resume` | Resume paused workflow |
## Extensions
| Command | Description |
|---------|-------------|
| `/gsd extensions list` | List all extensions |
| `/gsd extensions enable <id>` | Enable an extension |
| `/gsd extensions disable <id>` | Disable an extension |
| `/gsd extensions info <id>` | Show extension details |
## GitHub Sync
| Command | Description |
|---------|-------------|
| `/github-sync bootstrap` | Initial GitHub sync setup |
| `/github-sync status` | Show sync mapping counts |
## Session Management
| Command | Description |
|---------|-------------|
| `/clear` | Start a new session |
| `/exit` | Graceful shutdown |
| `/model` | Switch the active model |
| `/login` | Log in to an LLM provider |
| `/thinking` | Toggle thinking level |
| `/voice` | Toggle speech-to-text |
| `/worktree` (`/wt`) | Git worktree management |
## In-Session Update
```
/gsd update
```
Checks npm for a newer version and installs it without leaving the session.

56
gitbook/reference/environment-variables.md Normal file
View file

@ -0,0 +1,56 @@
# Environment Variables
## GSD Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `GSD_HOME` | `~/.gsd` | Global GSD directory. All paths derive from this unless individually overridden. |
| `GSD_PROJECT_ID` | (auto-hash) | Override automatic project identity hash. Useful for CI/CD or sharing state across repo clones. |
| `GSD_STATE_DIR` | `$GSD_HOME` | Per-project state root. Controls where `projects/<repo-hash>/` directories are created. |
| `GSD_CODING_AGENT_DIR` | `$GSD_HOME/agent` | Agent directory for extensions, auth, and managed resources. |
| `GSD_FETCH_ALLOWED_URLS` | (none) | Comma-separated hostnames exempt from internal URL blocking. |
| `GSD_ALLOWED_COMMAND_PREFIXES` | (built-in) | Comma-separated command prefixes allowed for value resolution. |
| `GSD_WEB_PROJECT_CWD` | — | Default project path for `gsd --web` when `?project=` is not specified. |
## LLM Provider Keys
| Variable | Provider |
|----------|----------|
| `ANTHROPIC_API_KEY` | Anthropic (Claude) |
| `OPENAI_API_KEY` | OpenAI |
| `GEMINI_API_KEY` | Google Gemini |
| `OPENROUTER_API_KEY` | OpenRouter |
| `GROQ_API_KEY` | Groq |
| `XAI_API_KEY` | xAI (Grok) |
| `MISTRAL_API_KEY` | Mistral |
| `GH_TOKEN` | GitHub Copilot |
| `AWS_PROFILE` | Amazon Bedrock (named profile) |
| `AWS_ACCESS_KEY_ID` | Amazon Bedrock (IAM keys) |
| `AWS_SECRET_ACCESS_KEY` | Amazon Bedrock (IAM keys) |
| `AWS_REGION` | Amazon Bedrock (region) |
| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock (bearer token) |
| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI |
| `GOOGLE_APPLICATION_CREDENTIALS` | Vertex AI (ADC) |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI |
## Tool API Keys
| Variable | Purpose |
|----------|---------|
| `TAVILY_API_KEY` | Tavily web search |
| `BRAVE_API_KEY` | Brave web search |
| `CONTEXT7_API_KEY` | Context7 documentation lookup |
| `DISCORD_BOT_TOKEN` | Discord remote questions |
| `TELEGRAM_BOT_TOKEN` | Telegram remote questions |
## URL Blocking
The `fetch_page` tool blocks requests to private/internal networks by default (SSRF protection). To allow specific internal hosts:
```bash
export GSD_FETCH_ALLOWED_URLS="internal-docs.company.com,192.168.1.50"
```
Or set `fetchAllowedUrls` in `~/.gsd/agent/settings.json`.
Blocked by default: private IP ranges, cloud metadata endpoints, localhost, non-HTTP protocols, IPv6 private ranges.

33
gitbook/reference/keyboard-shortcuts.md Normal file
View file

@ -0,0 +1,33 @@
# Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+Alt+G` | Toggle dashboard overlay |
| `Ctrl+Alt+V` | Toggle voice transcription |
| `Ctrl+Alt+B` | Show background shell processes |
| `Ctrl+V` / `Alt+V` | Paste image from clipboard (screenshot → vision input) |
| `Escape` | Pause auto mode (preserves conversation) |
## Terminal Compatibility
In terminals without Kitty keyboard protocol support (macOS Terminal.app, JetBrains IDEs), slash-command fallbacks are shown instead of `Ctrl+Alt` shortcuts.
{% hint style="tip" %}
If `Ctrl+V` is intercepted by your terminal (e.g. Warp), use `Alt+V` instead for clipboard image paste.
{% endhint %}
## iTerm2 Note
If `Ctrl+Alt` shortcuts trigger the wrong action (e.g., `Ctrl+Alt+G` opens external editor instead of the dashboard), go to **Profiles → Keys → General** and set **Left Option Key** to **Esc+**. This makes Alt/Option work correctly with Ctrl combinations.
## cmux Integration
If you use cmux (terminal multiplexer), GSD can integrate with it:
| Command | Description |
|---------|-------------|
| `/gsd cmux status` | Show cmux detection and capabilities |
| `/gsd cmux on` / `off` | Enable/disable integration |
| `/gsd cmux notifications on/off` | Toggle desktop notifications |
| `/gsd cmux sidebar on/off` | Toggle sidebar metadata |
| `/gsd cmux splits on/off` | Toggle visual subagent splits |

48
gitbook/reference/migration.md Normal file
View file

@ -0,0 +1,48 @@
# Migration from v1
If you have projects with `.planning` directories from the original Get Shit Done (v1), you can migrate them to GSD-2's `.gsd` format.
## Running the Migration
```bash
# From within the project directory
/gsd migrate
# Or specify a path
/gsd migrate ~/projects/my-old-project
```
## What Gets Migrated
The migration tool:
- Parses your old `PROJECT.md`, `ROADMAP.md`, `REQUIREMENTS.md`, phase directories, plans, summaries, and research
- Maps phases → slices, plans → tasks, milestones → milestones
- Preserves completion state (`[x]` phases stay done, summaries carry over)
- Consolidates research files into the new structure
- Shows a preview before writing anything
- Optionally runs an AI-driven review for quality assurance
## Supported Formats
The migration handles various v1 format variations:
- Milestone-sectioned roadmaps with `<details>` blocks
- Bold phase entries
- Bullet-format requirements
- Decimal phase numbering
- Duplicate phase numbers across milestones
## Requirements
Migration works best with a `ROADMAP.md` file for milestone structure. Without one, milestones are inferred from the `phases/` directory.
## Post-Migration
After migrating, verify the output:
```
/gsd doctor
```
This checks `.gsd/` integrity and flags any structural issues.

151
gitbook/reference/troubleshooting.md Normal file
View file

@ -0,0 +1,151 @@
# Troubleshooting
## `/gsd doctor`
The built-in diagnostic tool validates `.gsd/` integrity:
```
/gsd doctor
```
It checks file structure, roadmap ↔ slice ↔ task consistency, completion state, git health, stale locks, and orphaned records.
## Common Issues
### Auto mode loops on the same unit
The same unit dispatches repeatedly.
**Fix:** Run `/gsd doctor` to repair state, then `/gsd auto`. If it persists, check that the expected artifact file exists on disk.
### Auto mode stops with "Loop detected"
A unit failed to produce its expected artifact twice.
**Fix:** Check the task plan for clarity. Refine it manually, then `/gsd auto`.
### `command not found: gsd` after install
npm's global bin directory isn't in `$PATH`.
**Fix:**
```bash
npm prefix -g
# Add the bin dir to PATH:
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
**Common causes:**
- **Homebrew Node** — `/opt/homebrew/bin` missing from PATH
- **Version manager (nvm, fnm, mise)** — global bin is version-specific
- **oh-my-zsh** — `gitfast` plugin aliases `gsd` to `git svn dcommit`; check with `alias gsd`
### Provider errors during auto mode
| Error Type | Auto-Resume? | Delay |
|-----------|-------------|-------|
| Rate limit (429) | Yes | 60s or retry-after header |
| Server error (500, 502, 503) | Yes | 30s |
| Auth/billing ("unauthorized") | No | Manual resume required |
For permanent errors, configure fallback models:
```yaml
models:
execution:
model: claude-sonnet-4-6
fallbacks:
- openrouter/minimax/minimax-m2.5
```
### Budget ceiling reached
Auto mode pauses with "Budget ceiling reached."
**Fix:** Increase `budget_ceiling` in preferences, or switch to `budget` token profile, then `/gsd auto`.
### Stale lock file
Auto mode won't start, says another session is running.
**Fix:** GSD auto-detects stale locks (dead PID = auto cleanup). If automatic recovery fails:
```bash
rm -f .gsd/auto.lock
rm -rf "$(dirname .gsd)/.gsd.lock"
```
### Git merge conflicts
Worktree merge fails on `.gsd/` files.
**Fix:** `.gsd/` conflicts are auto-resolved. Code conflicts get an AI fix attempt; if that fails, resolve manually.
### Notifications not appearing on macOS
**Fix:** Install `terminal-notifier`:
```bash
brew install terminal-notifier
```
See [Notifications](../configuration/notifications.md) for details.
## MCP Issues
### No servers configured
**Fix:** Add server to `.mcp.json` or `.gsd/mcp.json`, verify JSON is valid, run `mcp_servers(refresh=true)`.
### Server discovery times out
**Fix:** Run the configured command outside GSD to confirm it starts. Check that backend services are reachable.
### Server connection closed immediately
**Fix:** Verify `command` and `args` paths are correct and absolute. Run the command manually to catch errors.
## Recovery Procedures
### Reset auto mode state
```bash
rm .gsd/auto.lock
rm .gsd/completed-units.json
```
Then `/gsd auto` to restart from current state.
### Reset routing history
```bash
rm .gsd/routing-history.json
```
### Full state rebuild
```
/gsd doctor
```
Rebuilds `STATE.md` from plan and roadmap files and fixes inconsistencies.
## Getting Help
- **GitHub Issues:** [github.com/gsd-build/GSD-2/issues](https://github.com/gsd-build/GSD-2/issues)
- **Dashboard:** `Ctrl+Alt+G` or `/gsd status`
- **Forensics:** `/gsd forensics` for post-mortem analysis
- **Session logs:** `.gsd/activity/` contains JSONL session dumps
## Platform-Specific Issues
### iTerm2
`Ctrl+Alt` shortcuts trigger wrong actions → Set **Profiles → Keys → General → Left Option Key** to **Esc+**.
### Windows
- LSP ENOENT on MSYS2/Git Bash → Fixed in v2.29+, upgrade
- EBUSY errors during builds → Close browser extension, or change output directory
- Transient EBUSY/EPERM on `.gsd/` files → Retry; close file-locking tools if persistent