diff --git a/gitbook/README.md b/gitbook/README.md new file mode 100644 index 000000000..cb84bae87 --- /dev/null +++ b/gitbook/README.md @@ -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) diff --git a/gitbook/SUMMARY.md b/gitbook/SUMMARY.md new file mode 100644 index 000000000..962364bbe --- /dev/null +++ b/gitbook/SUMMARY.md @@ -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) diff --git a/gitbook/configuration/custom-models.md b/gitbook/configuration/custom-models.md new file mode 100644 index 000000000..8f02512ff --- /dev/null +++ b/gitbook/configuration/custom-models.md @@ -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` | diff --git a/gitbook/configuration/git-settings.md b/gitbook/configuration/git-settings.md new file mode 100644 index 000000000..cf4c0d524 --- /dev/null +++ b/gitbook/configuration/git-settings.md @@ -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//` | `milestone/` | Most projects — full isolation | +| `branch` | Project root | `milestone/` | 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/` 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. diff --git a/gitbook/configuration/mcp-servers.md b/gitbook/configuration/mcp-servers.md new file mode 100644 index 000000000..6079fa3a7 --- /dev/null +++ b/gitbook/configuration/mcp-servers.md @@ -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="", 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` diff --git a/gitbook/configuration/notifications.md b/gitbook/configuration/notifications.md new file mode 100644 index 000000000..54acd0d67 --- /dev/null +++ b/gitbook/configuration/notifications.md @@ -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. diff --git a/gitbook/configuration/preferences.md b/gitbook/configuration/preferences.md new file mode 100644 index 000000000..3a997150a --- /dev/null +++ b/gitbook/configuration/preferences.md @@ -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 +``` diff --git a/gitbook/configuration/providers.md b/gitbook/configuration/providers.md new file mode 100644 index 000000000..4cb709142 --- /dev/null +++ b/gitbook/configuration/providers.md @@ -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 ` | +| 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 | diff --git a/gitbook/core-concepts/auto-mode.md b/gitbook/core-concepts/auto-mode.md new file mode 100644 index 000000000..b611f85ff --- /dev/null +++ b/gitbook/core-concepts/auto-mode.md @@ -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] +``` diff --git a/gitbook/core-concepts/project-structure.md b/gitbook/core-concepts/project-structure.md new file mode 100644 index 000000000..6aa6e9078 --- /dev/null +++ b/gitbook/core-concepts/project-structure.md @@ -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. diff --git a/gitbook/core-concepts/step-mode.md b/gitbook/core-concepts/step-mode.md new file mode 100644 index 000000000..750c56728 --- /dev/null +++ b/gitbook/core-concepts/step-mode.md @@ -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. diff --git a/gitbook/features/captures.md b/gitbook/features/captures.md new file mode 100644 index 000000000..54a2a27e1 --- /dev/null +++ b/gitbook/features/captures.md @@ -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. diff --git a/gitbook/features/cost-management.md b/gitbook/features/cost-management.md new file mode 100644 index 000000000..62204c586 --- /dev/null +++ b/gitbook/features/cost-management.md @@ -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 diff --git a/gitbook/features/dynamic-model-routing.md b/gitbook/features/dynamic-model-routing.md new file mode 100644 index 000000000..a9903f715 --- /dev/null +++ b/gitbook/features/dynamic-model-routing.md @@ -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. diff --git a/gitbook/features/github-sync.md b/gitbook/features/github-sync.md new file mode 100644 index 000000000..aa89c8602 --- /dev/null +++ b/gitbook/features/github-sync.md @@ -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 +``` diff --git a/gitbook/features/headless.md b/gitbook/features/headless.md new file mode 100644 index 000000000..5cc1e9351 --- /dev/null +++ b/gitbook/features/headless.md @@ -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 ` | — | Context file for `new-milestone` (use `-` for stdin) | +| `--context-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. diff --git a/gitbook/features/parallel.md b/gitbook/features/parallel.md new file mode 100644 index 000000000..a94615308 --- /dev/null +++ b/gitbook/features/parallel.md @@ -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/` | +| 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 ` + +## 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//`, then `/gsd parallel merge ` | +| Workers seem stuck | Check if budget ceiling was reached via `/gsd parallel status` | diff --git a/gitbook/features/remote-questions.md b/gitbook/features/remote-questions.md new file mode 100644 index 000000000..2c16ef8db --- /dev/null +++ b/gitbook/features/remote-questions.md @@ -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 | diff --git a/gitbook/features/skills.md b/gitbook/features/skills.md new file mode 100644 index 000000000..4a9fd46b7 --- /dev/null +++ b/gitbook/features/skills.md @@ -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. diff --git a/gitbook/features/teams.md b/gitbook/features/teams.md new file mode 100644 index 000000000..44dac0c57 --- /dev/null +++ b/gitbook/features/teams.md @@ -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//`) +- Works on a unique `milestone/` 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. diff --git a/gitbook/features/token-optimization.md b/gitbook/features/token-optimization.md new file mode 100644 index 000000000..c89493618 --- /dev/null +++ b/gitbook/features/token-optimization.md @@ -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 +``` diff --git a/gitbook/features/visualizer.md b/gitbook/features/visualizer.md new file mode 100644 index 000000000..4155ec144 --- /dev/null +++ b/gitbook/features/visualizer.md @@ -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) +``` diff --git a/gitbook/features/web-interface.md b/gitbook/features/web-interface.md new file mode 100644 index 000000000..6870ffc41 --- /dev/null +++ b/gitbook/features/web-interface.md @@ -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 diff --git a/gitbook/features/workflow-templates.md b/gitbook/features/workflow-templates.md new file mode 100644 index 000000000..45246a33b --- /dev/null +++ b/gitbook/features/workflow-templates.md @@ -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 # show details for a template +``` + +## Custom Workflows + +Create your own workflow definitions: + +``` +/gsd workflow new # create a new workflow YAML +/gsd workflow run # start a workflow run +/gsd workflow list # list active runs +/gsd workflow validate # 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. diff --git a/gitbook/getting-started/choosing-a-model.md b/gitbook/getting-started/choosing-a-model.md new file mode 100644 index 000000000..64b2e3aad --- /dev/null +++ b/gitbook/getting-started/choosing-a-model.md @@ -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) | diff --git a/gitbook/getting-started/first-project.md b/gitbook/getting-started/first-project.md new file mode 100644 index 000000000..dd0551035 --- /dev/null +++ b/gitbook/getting-started/first-project.md @@ -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 diff --git a/gitbook/getting-started/installation.md b/gitbook/getting-started/installation.md new file mode 100644 index 000000000..e1e72fe80 --- /dev/null +++ b/gitbook/getting-started/installation.md @@ -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 +``` diff --git a/gitbook/reference/cli-flags.md b/gitbook/reference/cli-flags.md new file mode 100644 index 000000000..a1de87f37 --- /dev/null +++ b/gitbook/reference/cli-flags.md @@ -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 ` | 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 ` | Load an additional extension (repeatable) | +| `gsd --append-system-prompt ` | Append text to the system prompt | +| `gsd --tools ` | 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 ` | 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 ` | Context file for `new-milestone` | +| `gsd headless --context-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 | diff --git a/gitbook/reference/commands.md b/gitbook/reference/commands.md new file mode 100644 index 000000000..e042723da --- /dev/null +++ b/gitbook/reference/commands.md @@ -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 ` | Show template details | + +## Custom Workflows + +| Command | Description | +|---------|-------------| +| `/gsd workflow new` | Create a workflow definition | +| `/gsd workflow run ` | Start a workflow run | +| `/gsd workflow list` | List workflow runs | +| `/gsd workflow validate ` | 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 ` | Enable an extension | +| `/gsd extensions disable ` | Disable an extension | +| `/gsd extensions info ` | 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. diff --git a/gitbook/reference/environment-variables.md b/gitbook/reference/environment-variables.md new file mode 100644 index 000000000..c23af72df --- /dev/null +++ b/gitbook/reference/environment-variables.md @@ -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//` 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. diff --git a/gitbook/reference/keyboard-shortcuts.md b/gitbook/reference/keyboard-shortcuts.md new file mode 100644 index 000000000..8b2013729 --- /dev/null +++ b/gitbook/reference/keyboard-shortcuts.md @@ -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 | diff --git a/gitbook/reference/migration.md b/gitbook/reference/migration.md new file mode 100644 index 000000000..54d548dc8 --- /dev/null +++ b/gitbook/reference/migration.md @@ -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 `
` 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. diff --git a/gitbook/reference/troubleshooting.md b/gitbook/reference/troubleshooting.md new file mode 100644 index 000000000..8102ede58 --- /dev/null +++ b/gitbook/reference/troubleshooting.md @@ -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