diff --git a/README.md b/README.md index e9aa8173a..d938b4fb7 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,25 @@ One command. Walk away. Come back to a built project with clean git history. --- +## Documentation + +Full documentation is available in the [`docs/`](./docs/) directory: + +- **[Getting Started](./docs/getting-started.md)** — install, first run, basic usage +- **[Auto Mode](./docs/auto-mode.md)** — autonomous execution deep-dive +- **[Configuration](./docs/configuration.md)** — all preferences, models, git, and hooks +- **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing (v2.17) +- **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections +- **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior +- **[Working in Teams](./docs/working-in-teams.md)** — unique IDs, shared artifacts +- **[Skills](./docs/skills.md)** — bundled skills, discovery, custom authoring +- **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts +- **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline +- **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, recovery +- **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration + +--- + ## What Changed From v1 The original GSD was a collection of markdown prompts installed into `~/.claude/commands/`. It relied entirely on the LLM reading those prompts and doing the right thing. That worked surprisingly well — but it had hard limits: @@ -334,6 +353,26 @@ unique_milestone_ids: true | `skill_rules` | Situational rules for skill routing | | `unique_milestone_ids` | Uses unique milestone names to avoid clashes when working in teams of people | +### Token Optimization (v2.17) + +GSD 2.17 introduced a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression: + +```yaml +token_profile: budget # or balanced (default), quality +``` + +| Profile | Savings | What It Does | +|---------|---------|-------------| +| `budget` | 40-60% | Cheap models, skip research/reassess, minimal context inlining | +| `balanced` | 10-20% | Default models, skip slice research, standard context | +| `quality` | 0% | All phases, all context, full model power | + +**Complexity-based routing** automatically classifies tasks as simple/standard/complex and routes to appropriate models. Simple docs tasks get Haiku; complex architectural work gets Opus. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history. + +**Budget pressure** graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers. + +See the full [Token Optimization Guide](./docs/token-optimization.md) for details. + ### Bundled Tools GSD ships with 14 extensions, all loaded automatically: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..2fb1ee3c6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,44 @@ +# GSD Documentation + +Welcome to the GSD documentation. This covers everything from getting started to advanced configuration, auto-mode internals, and extending GSD with the Pi SDK. + +## User Documentation + +| Guide | Description | +|-------|-------------| +| [Getting Started](./getting-started.md) | Installation, first run, and basic usage | +| [Auto Mode](./auto-mode.md) | How autonomous execution works — the state machine, crash recovery, and steering | +| [Commands Reference](./commands.md) | All commands, keyboard shortcuts, and CLI flags | +| [Configuration](./configuration.md) | Preferences, model selection, git settings, and token profiles | +| [Token Optimization](./token-optimization.md) | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) | +| [Cost Management](./cost-management.md) | Budget ceilings, cost tracking, projections, and enforcement modes | +| [Git Strategy](./git-strategy.md) | Worktree isolation, branching model, and merge behavior | +| [Working in Teams](./working-in-teams.md) | Unique milestone IDs, `.gitignore` setup, and shared planning artifacts | +| [Skills](./skills.md) | Bundled skills, skill discovery, and custom skill authoring | +| [Migration from v1](./migration.md) | Migrating `.planning` directories from the original GSD | +| [Troubleshooting](./troubleshooting.md) | Common issues, `/gsd doctor`, and recovery procedures | + +## Architecture & Internals + +| Guide | Description | +|-------|-------------| +| [Architecture Overview](./architecture.md) | System design, extension model, state-on-disk, and dispatch pipeline | +| [Native Engine](../native/README.md) | Rust N-API modules for performance-critical operations | +| [ADR-001: Branchless Worktree Architecture](./ADR-001-branchless-worktree-architecture.md) | Decision record for the v2.14 git architecture | + +## Pi SDK Documentation + +These guides cover the underlying Pi SDK that GSD is built on. Useful if you want to extend GSD or build your own agent application. + +| Guide | Description | +|-------|-------------| +| [What is Pi](./what-is-pi/README.md) | Core concepts — modes, agent loop, sessions, tools, providers | +| [Extending Pi](./extending-pi/README.md) | Building extensions — tools, commands, UI, events, state | +| [Context & Hooks](./context-and-hooks/README.md) | Context pipeline, hook reference, inter-extension communication | +| [Pi UI / TUI](./pi-ui-tui/README.md) | Terminal UI components, theming, keyboard input, rendering | + +## Research + +| Guide | Description | +|-------|-------------| +| [Building Coding Agents](./building-coding-agents/README.md) | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs | diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 000000000..38ec524a2 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,108 @@ +# Architecture Overview + +GSD is a TypeScript application built on the [Pi SDK](https://github.com/badlogic/pi-mono). It embeds the Pi coding agent and extends it with the GSD workflow engine, auto mode state machine, and project management primitives. + +## System Structure + +``` +gsd (CLI binary) + └─ loader.ts Sets PI_PACKAGE_DIR, GSD env vars, dynamic-imports cli.ts + └─ cli.ts Wires SDK managers, loads extensions, starts InteractiveMode + ├─ onboarding.ts First-run setup wizard (LLM provider + tool keys) + ├─ wizard.ts Env hydration from stored auth.json credentials + ├─ app-paths.ts ~/.gsd/agent/, ~/.gsd/sessions/, auth.json + ├─ resource-loader.ts Syncs bundled extensions + agents to ~/.gsd/agent/ + └─ src/resources/ + ├─ extensions/gsd/ Core GSD extension + ├─ extensions/... 12 supporting extensions + ├─ agents/ scout, researcher, worker + ├─ AGENTS.md Agent routing instructions + └─ GSD-WORKFLOW.md Manual bootstrap protocol +``` + +## Key Design Decisions + +### State Lives on Disk + +`.gsd/` is the sole source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions. This enables crash recovery, multi-terminal steering, and session resumption. + +### Two-File Loader Pattern + +`loader.ts` sets all environment variables with zero SDK imports, then dynamically imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates. + +### `pkg/` Shim Directory + +`PI_PACKAGE_DIR` points to `pkg/` (not project root) to avoid Pi's theme resolution colliding with GSD's `src/` directory. Contains only `piConfig` and theme assets. + +### Always-Overwrite Sync + +Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run. This means `npm update -g` takes effect immediately. + +### Fresh Session Per Unit + +Every dispatch creates a new agent session. The LLM starts with a clean context window containing only the pre-inlined artifacts it needs. This prevents quality degradation from context accumulation. + +## Bundled Extensions + +| Extension | What It Provides | +|-----------|-----------------| +| **GSD** | Core workflow engine — auto mode, state machine, commands, dashboard | +| **Browser Tools** | Playwright-based browser with form intelligence and semantic actions | +| **Search the Web** | Brave Search, Tavily, or Jina page extraction | +| **Google Search** | Gemini-powered web search with AI-synthesized answers | +| **Context7** | Up-to-date library/framework documentation | +| **Background Shell** | Long-running process management with readiness detection | +| **Subagent** | Delegated tasks with isolated context windows | +| **Mac Tools** | macOS native app automation via Accessibility APIs | +| **MCPorter** | Lazy on-demand MCP server integration | +| **Voice** | Real-time speech-to-text (macOS, Linux) | +| **Slash Commands** | Custom command creation | +| **LSP** | Language Server Protocol — diagnostics, definitions, references, hover, rename | +| **Ask User Questions** | Structured user input with single/multi-select | +| **Secure Env Collect** | Masked secret collection | + +## Bundled Agents + +| Agent | Role | +|-------|------| +| **Scout** | Fast codebase recon — compressed context for handoff | +| **Researcher** | Web research — finds and synthesizes current information | +| **Worker** | General-purpose execution in an isolated context window | + +## Native Engine + +Performance-critical operations use a Rust N-API engine: + +- **grep** — ripgrep-backed content search +- **glob** — gitignore-aware file discovery +- **ps** — cross-platform process tree management +- **highlight** — syntect-based syntax highlighting +- **ast** — structural code search via ast-grep +- **diff** — fuzzy text matching and unified diff generation +- **text** — ANSI-aware text measurement and wrapping +- **html** — HTML-to-Markdown conversion +- **image** — decode, encode, resize images +- **fd** — fuzzy file path discovery +- **clipboard** — native clipboard access +- **git** — libgit2-backed git read operations (v2.16+) +- **parser** — GSD file parsing and frontmatter extraction + +## Dispatch Pipeline + +The auto mode dispatch pipeline: + +``` +1. Read disk state (STATE.md, roadmap, plans) +2. Determine next unit type and ID +3. Classify complexity → select model tier +4. Apply budget pressure adjustments +5. Check routing history for adaptive adjustments +6. Resolve effective model (with fallbacks) +7. Build dispatch prompt (applying inline level compression) +8. Create fresh agent session +9. Inject prompt and let LLM execute +10. On completion: snapshot metrics, verify artifacts, persist state +11. Loop to step 1 +``` + +Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the corresponding unit type is never dispatched. diff --git a/docs/auto-mode.md b/docs/auto-mode.md new file mode 100644 index 000000000..f930cee55 --- /dev/null +++ b/docs/auto-mode.md @@ -0,0 +1,143 @@ +# Auto Mode + +Auto mode is GSD's autonomous execution engine. Run `/gsd auto`, walk away, come back to built software with clean git history. + +## How It Works + +Auto mode is a **state machine driven by files on disk**. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit. + +### The Loop + +Each slice flows through phases automatically: + +``` +Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice +``` + +- **Research** — scouts the codebase and relevant docs +- **Plan** — decomposes the slice into tasks with must-haves +- **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 + +## Key Properties + +### Fresh Session Per Unit + +Every task, research phase, and planning step gets a clean context window. No accumulated garbage. No degraded quality from context bloat. The dispatch prompt includes everything needed — task plans, prior summaries, dependency context, decisions register — so the LLM starts oriented instead of spending tool calls reading files. + +### Context Pre-Loading + +The dispatch prompt is carefully constructed with: + +| Inlined Artifact | Purpose | +|------------------|---------| +| Task plan | What to build | +| Slice plan | Where this task fits | +| Prior task summaries | What's already done | +| Dependency summaries | Cross-slice context | +| Roadmap excerpt | Overall direction | +| Decisions register | Architectural context | + +The amount of context inlined is controlled by your [token profile](./token-optimization.md). Budget mode inlines minimal context; quality mode inlines everything. + +### Git Worktree Isolation + +Each milestone runs in its own git worktree with a `milestone/` branch. All slice work commits sequentially — no branch switching, no merge conflicts mid-milestone. When the milestone completes, it's squash-merged to main as one clean commit. + +See [Git Strategy](./git-strategy.md) for details. + +### Crash Recovery + +A lock file tracks the current unit. If the 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. + +### Stuck Detection + +If the same unit dispatches twice (the LLM didn't produce the expected artifact), GSD retries once with a deep diagnostic prompt. If it fails again, auto mode stops with the exact file it expected, so you can intervene. + +### Timeout Supervision + +Three timeout tiers prevent runaway sessions: + +| Timeout | Default | Behavior | +|---------|---------|----------| +| Soft | 20 min | Warns the LLM to wrap up | +| Idle | 10 min | Detects stalls, intervenes | +| Hard | 30 min | Pauses auto mode | + +Recovery steering nudges the LLM to finish durable output before timing out. Configure in preferences: + +```yaml +auto_supervisor: + soft_timeout_minutes: 20 + idle_timeout_minutes: 10 + hard_timeout_minutes: 30 +``` + +### 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](./cost-management.md). + +### Adaptive Replanning + +After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing. This can be skipped with the `balanced` or `budget` token profiles. + +## Controlling Auto Mode + +### Start + +``` +/gsd auto +``` + +### 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 +``` + +Hard-steer plan documents during execution without stopping the pipeline. Changes are picked up at the next phase boundary. + +## 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 + +## Phase Skipping + +Token profiles can skip certain phases to reduce cost: + +| Phase | `budget` | `balanced` | `quality` | +|-------|----------|------------|-----------| +| Milestone Research | Skipped | Runs | Runs | +| Slice Research | Skipped | Skipped | Runs | +| Reassess Roadmap | Skipped | Runs | Runs | + +See [Token Optimization](./token-optimization.md) for details. diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 000000000..5414ea16e --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,54 @@ +# Commands Reference + +## Session Commands + +| Command | Description | +|---------|-------------| +| `/gsd` | Step mode — execute one unit at a time, pause between each | +| `/gsd next` | Explicit step mode (same as `/gsd`) | +| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat | +| `/gsd stop` | Stop auto mode gracefully | +| `/gsd steer` | Hard-steer plan documents during execution | +| `/gsd discuss` | Discuss architecture and decisions (works alongside auto mode) | +| `/gsd status` | Progress dashboard | +| `/gsd queue` | Queue future milestones (safe during auto mode) | +| `/gsd prefs` | Model selection, timeouts, budget ceiling | +| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format | +| `/gsd doctor` | Validate `.gsd/` integrity, find and fix issues | + +## Git Commands + +| Command | Description | +|---------|-------------| +| `/worktree` (`/wt`) | Git worktree lifecycle — create, switch, merge, remove | + +## Session Management + +| Command | Description | +|---------|-------------| +| `/clear` | Start a new session (alias for `/new`) | +| `/exit` | Graceful shutdown — saves session state before exiting | +| `/kill` | Kill GSD process immediately | +| `/model` | Switch the active model | +| `/login` | Log in to an LLM provider | +| `/thinking` | Toggle thinking level during sessions | +| `/voice` | Toggle real-time speech-to-text (macOS, Linux) | + +## Keyboard Shortcuts + +| Shortcut | Action | +|----------|--------| +| `Ctrl+Alt+G` | Toggle dashboard overlay | +| `Ctrl+Alt+V` | Toggle voice transcription | +| `Ctrl+Alt+B` | Show background shell processes | +| `Escape` | Pause auto mode (preserves conversation) | + +> **Note:** In terminals without Kitty keyboard protocol support (macOS Terminal.app, JetBrains IDEs), slash-command fallbacks are shown instead of `Ctrl+Alt` shortcuts. + +## CLI Flags + +| Flag | Description | +|------|-------------| +| `gsd` | Start a new interactive session | +| `gsd --continue` (`-c`) | Resume the most recent session for the current directory | +| `gsd config` | Re-run the setup wizard (LLM provider + tool keys) | diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 000000000..8f1a034e4 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,238 @@ +# Configuration + +GSD preferences live in `~/.gsd/preferences.md` (global) or `.gsd/preferences.md` (project-local). Manage interactively with `/gsd prefs`. + +## Preferences File Format + +Preferences use YAML frontmatter in a markdown file: + +```yaml +--- +version: 1 +models: + research: claude-sonnet-4-6 + planning: claude-opus-4-6 + execution: claude-sonnet-4-6 + completion: claude-sonnet-4-6 +skill_discovery: suggest +auto_supervisor: + soft_timeout_minutes: 20 + idle_timeout_minutes: 10 + hard_timeout_minutes: 30 +budget_ceiling: 50.00 +token_profile: balanced +--- +``` + +## Global vs Project Preferences + +| Scope | Path | Applies to | +|-------|------|-----------| +| Global | `~/.gsd/preferences.md` | All projects | +| Project | `.gsd/preferences.md` | Current project only | + +**Merge behavior:** +- **Scalar fields** (`skill_discovery`, `budget_ceiling`): project wins if defined +- **Array fields** (`always_use_skills`, etc.): concatenated (global first, then project) +- **Object fields** (`models`, `git`, `auto_supervisor`): shallow-merged, project overrides per-key + +## All Settings + +### `models` + +Per-phase model selection. Each key accepts a model string or an object with fallbacks. + +```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-20250414 + completion: claude-sonnet-4-6 + subagent: claude-sonnet-4-6 +``` + +**Phases:** `research`, `planning`, `execution`, `execution_simple`, `completion`, `subagent` + +- `execution_simple` — used for tasks classified as "simple" by the [complexity router](./token-optimization.md#complexity-based-task-routing) +- `subagent` — model for delegated subagent tasks (scout, researcher, worker) +- Provider targeting: use `provider/model` format (e.g., `bedrock/claude-sonnet-4-6`) or the `provider` field in object format + +### `token_profile` + +Coordinates model selection, phase skipping, and context compression. See [Token Optimization](./token-optimization.md). + +Values: `budget`, `balanced` (default), `quality` + +### `phases` + +Fine-grained control over which phases run in auto mode: + +```yaml +phases: + skip_research: false # skip milestone-level research + skip_reassess: false # skip roadmap reassessment after each slice + skip_slice_research: true # skip per-slice research +``` + +These are usually set automatically by `token_profile`, but can be overridden explicitly. + +### `skill_discovery` + +Controls how GSD finds and applies skills during auto mode. + +| Value | Behavior | +|-------|----------| +| `auto` | Skills found and applied automatically | +| `suggest` | Skills identified during research but not auto-installed (default) | +| `off` | Skill discovery disabled | + +### `auto_supervisor` + +Timeout thresholds for auto mode supervision: + +```yaml +auto_supervisor: + soft_timeout_minutes: 20 # warn LLM to wrap up + idle_timeout_minutes: 10 # detect stalls + hard_timeout_minutes: 30 # pause auto mode +``` + +### `budget_ceiling` + +USD ceiling. Auto mode pauses when reached. + +```yaml +budget_ceiling: 50.00 +``` + +### `budget_enforcement` + +How the budget ceiling is enforced: + +| Value | Behavior | +|-------|----------| +| `warn` | Log a warning but continue | +| `pause` | Pause auto mode (default when ceiling is set) | +| `halt` | Stop auto mode entirely | + +### `uat_dispatch` + +Enable automatic UAT (User Acceptance Test) runs after slice completion: + +```yaml +uat_dispatch: true +``` + +### `unique_milestone_ids` + +Generate milestone IDs with a random suffix to avoid collisions in team workflows: + +```yaml +unique_milestone_ids: true +# Produces: M001-eh88as instead of M001 +``` + +### `git` + +Git behavior configuration. All fields optional: + +```yaml +git: + auto_push: false # push commits to remote after committing + push_branches: false # push milestone branch to remote + remote: origin # git remote name + snapshots: false # WIP snapshot commits during long tasks + pre_merge_check: false # run checks before worktree merge (true/false/"auto") + commit_type: feat # override conventional commit prefix + main_branch: main # primary branch name + commit_docs: true # commit .gsd/ artifacts to git (set false to keep local) +``` + +### `notifications` + +Control what notifications GSD sends (for remote question integrations): + +```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 +``` + +### `remote_questions` + +Route interactive questions to Slack or Discord for headless auto-mode: + +```yaml +remote_questions: + channel: slack # or discord + channel_id: "C1234567890" + timeout_minutes: 15 + poll_interval_seconds: 10 +``` + +### `post_unit_hooks` + +Custom hooks that fire after specific unit types complete: + +```yaml +post_unit_hooks: + - name: code-review + after: [execute-task] + prompt: "Review the code changes for quality and security issues." + model: claude-opus-4-6 + max_cycles: 1 +``` + +### `pre_dispatch_hooks` + +Hooks that intercept units before dispatch: + +```yaml +pre_dispatch_hooks: + - name: add-context + before: [execute-task] + action: modify + prepend: "Remember to follow our coding standards document." +``` + +### `always_use_skills` / `prefer_skills` / `avoid_skills` + +Skill routing preferences: + +```yaml +always_use_skills: + - debug-like-expert +prefer_skills: + - frontend-design +avoid_skills: [] +``` + +### `skill_rules` + +Situational skill routing: + +```yaml +skill_rules: + - when: task involves authentication + use: [clerk] + - when: frontend styling work + prefer: [frontend-design] +``` + +### `custom_instructions` + +Durable instructions appended to every session: + +```yaml +custom_instructions: + - "Always use TypeScript strict mode" + - "Prefer functional patterns over classes" +``` diff --git a/docs/cost-management.md b/docs/cost-management.md new file mode 100644 index 000000000..efd3398e6 --- /dev/null +++ b/docs/cost-management.md @@ -0,0 +1,91 @@ +# Cost Management + +GSD tracks token usage and cost for every unit of work dispatched during auto mode. This data powers the dashboard, budget enforcement, and cost projections. + +## Cost Tracking + +Every unit's metrics are captured automatically: + +- **Token counts** — input, output, cache read, cache write, total +- **Cost** — USD cost per unit +- **Duration** — wall-clock time +- **Tool calls** — number of tool invocations +- **Message counts** — assistant and user messages + +Data is stored in `.gsd/metrics.json` and survives across sessions. + +### Viewing Costs + +**Dashboard:** `Ctrl+Alt+G` or `/gsd status` shows real-time cost breakdown. + +**Aggregations available:** +- By phase (research, planning, execution, completion, reassessment) +- By slice (M001/S01, M001/S02, ...) +- By model (which models consumed the most budget) +- Project totals + +## Budget Ceiling + +Set a maximum spend for a project: + +```yaml +--- +version: 1 +budget_ceiling: 50.00 +--- +``` + +### Enforcement Modes + +Control what happens when the ceiling is reached: + +```yaml +budget_enforcement: pause # default when ceiling is set +``` + +| Mode | Behavior | +|------|----------| +| `warn` | Log a warning, continue executing | +| `pause` | Pause auto mode, wait for user action | +| `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) +``` + +Projections use per-slice averages from completed work. If the budget ceiling has been reached, a warning is appended. + +## Budget Pressure & Model Downgrading + +When approaching the budget ceiling, the [complexity router](./token-optimization.md#budget-pressure) automatically downgrades model assignments to cheaper tiers. This is graduated: + +- **< 50% used** — no adjustment +- **50-75% used** — standard tasks downgrade to light +- **75-90% used** — same, more aggressive +- **> 90% used** — nearly everything downgrades; only heavy tasks stay at standard + +This ensures the budget is spread across remaining work instead of being exhausted early on complex tasks. + +## Token Profiles & Cost + +The `token_profile` preference directly affects cost: + +| Profile | Typical Savings | How | +|---------|----------------|-----| +| `budget` | 40-60% | Cheaper models, phase skipping, minimal context | +| `balanced` | 10-20% | Default models, skip slice research, standard context | +| `quality` | 0% (baseline) | Full models, all phases, full context | + +See [Token Optimization](./token-optimization.md) for details. + +## 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` profile for well-understood, repetitive work +- Use `quality` only when architectural decisions are being made +- Per-phase model selection lets you use Opus only for planning while keeping execution on Sonnet diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..ad6f90b91 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,133 @@ +# Getting Started + +## Install + +```bash +npm install -g gsd-pi +``` + +Requires Node.js ≥ 20.6.0 (22+ recommended) and Git. + +## First Launch + +Run `gsd` in any directory: + +```bash +gsd +``` + +On first launch, GSD runs a setup wizard: + +1. **LLM Provider** — select 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. + +If you have an existing Pi installation, provider credentials are imported automatically. + +Re-run the wizard anytime with: + +```bash +gsd config +``` + +## Choose a Model + +GSD auto-selects a default model after login. Switch later with: + +``` +/model +``` + +Or configure per-phase models in preferences — see [Configuration](./configuration.md). + +## Two Ways to Work + +### Step Mode — `/gsd` + +Type `/gsd` inside a session. GSD executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next. + +- **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 + +Step mode is the on-ramp. You stay in the loop, reviewing output between each step. + +### Auto Mode — `/gsd auto` + +Type `/gsd auto` and walk away. GSD autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. + +``` +/gsd auto +``` + +See [Auto Mode](./auto-mode.md) for full details. + +## Two Terminals, One Project + +The recommended workflow: 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 +``` + +Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically. + +## Project Structure + +GSD organizes work into a hierarchy: + +``` +Milestone → a shippable version (4-10 slices) + Slice → one demoable vertical capability (1-7 tasks) + Task → one context-window-sized unit of work +``` + +The iron rule: **a task must fit in one context window.** If it can't, it's two tasks. + +All state lives on disk in `.gsd/`: + +``` +.gsd/ + PROJECT.md — what the project is right now + REQUIREMENTS.md — requirement contract (active/validated/deferred) + DECISIONS.md — append-only architectural decisions + STATE.md — quick-glance status + milestones/ + M001/ + M001-ROADMAP.md — slice plan with risk levels and dependencies + M001-CONTEXT.md — scope and goals from discussion + slices/ + S01/ + S01-PLAN.md — task decomposition + S01-SUMMARY.md — what happened + S01-UAT.md — human test script + tasks/ + T01-PLAN.md + T01-SUMMARY.md +``` + +## Resume a Session + +```bash +gsd --continue # or gsd -c +``` + +Resumes the most recent session for the current directory. + +## Next Steps + +- [Auto Mode](./auto-mode.md) — deep dive into autonomous execution +- [Configuration](./configuration.md) — model selection, timeouts, budgets +- [Commands Reference](./commands.md) — all commands and shortcuts diff --git a/docs/git-strategy.md b/docs/git-strategy.md new file mode 100644 index 000000000..14c1241be --- /dev/null +++ b/docs/git-strategy.md @@ -0,0 +1,92 @@ +# Git Strategy + +GSD uses git worktrees for milestone isolation and sequential commits within each milestone. The strategy is fully automated — you don't need to manage branches manually. + +## Branching Model + +``` +main ───────────────────────────────────────────────────────── + │ ↑ + └── milestone/M001 (worktree) ────────────────────────┘ + commit: feat(S01/T01): core types + commit: feat(S01/T02): markdown parser + commit: feat(S01/T03): file writer + commit: docs(M001/S01): workflow docs + ... + → squash-merged to main as single commit +``` + +### Key Properties + +- **One worktree per milestone** — all work happens in `.gsd/worktrees//` +- **Sequential commits on one branch** — no per-slice branches, no merge conflicts within a milestone +- **Squash merge to main** — when the milestone completes, all commits are squashed into one clean commit on main +- **Worktree teardown** — after merge, the worktree and branch are cleaned up + +### Commit Format + +Commits use conventional commit format with scope: + +``` +feat(S01/T01): core type definitions +feat(S01/T02): markdown parser for plan files +fix(M001/S03): bug fixes and doc corrections +docs(M001/S04): workflow documentation +``` + +## Worktree Management + +### Automatic (Auto Mode) + +Auto mode creates and manages worktrees automatically: + +1. When a milestone starts, a worktree is created at `.gsd/worktrees//` on branch `milestone/` +2. Planning artifacts from `.gsd/milestones/` are copied into the worktree +3. All execution happens inside the worktree +4. On milestone completion, the worktree is squash-merged to the integration branch +5. The worktree and branch are removed + +### Manual + +Use the `/worktree` (or `/wt`) command for manual worktree management: + +``` +/worktree create +/worktree switch +/worktree merge +/worktree remove +``` + +## Git Preferences + +Configure git behavior in preferences: + +```yaml +git: + auto_push: false # push after commits + push_branches: false # push milestone branch + remote: origin + snapshots: false # WIP snapshot commits + pre_merge_check: false # pre-merge validation + commit_type: feat # override commit type prefix + main_branch: main # primary branch name + commit_docs: true # commit .gsd/ to git +``` + +### `commit_docs: false` + +When set to `false`, GSD adds `.gsd/` to `.gitignore` and keeps all planning artifacts local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. + +## Self-Healing + +GSD includes automatic recovery for common git issues: + +- **Detached HEAD** — automatically reattaches to the correct branch +- **Stale lock files** — removes `index.lock` files from crashed processes +- **Orphaned worktrees** — detects and offers to clean up abandoned worktrees + +Run `/gsd doctor` to check git health manually. + +## Native Git Operations + +Since v2.16, GSD uses libgit2 via native bindings for read-heavy operations in the dispatch hot path. This eliminates ~70 process spawns per dispatch cycle, improving auto-mode throughput. diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 000000000..8676d1af2 --- /dev/null +++ b/docs/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 agent-driven review of the output 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 with: + +``` +/gsd doctor +``` + +This checks `.gsd/` integrity and flags any structural issues. diff --git a/docs/skills.md b/docs/skills.md new file mode 100644 index 000000000..af1001ddb --- /dev/null +++ b/docs/skills.md @@ -0,0 +1,84 @@ +# Skills + +Skills are specialized instruction sets that GSD loads when the task matches. They provide domain-specific guidance for the LLM — coding patterns, framework idioms, testing strategies, and tool usage. + +## Bundled Skills + +GSD ships with these skills, installed to `~/.gsd/agent/skills/`: + +| Skill | Trigger | Description | +|-------|---------|-------------| +| `frontend-design` | Web UI work — components, pages, dashboards, styling | Production-grade frontend with high design quality | +| `swiftui` | macOS/iOS apps — SwiftUI, Xcode, App Store | Full lifecycle from creation to shipping | +| `debug-like-expert` | Complex debugging — after standard approaches fail | Methodical investigation with evidence gathering | +| `rust-core` | Rust code — ownership, lifetimes, traits, async | Idiomatic, safe, performant Rust patterns | +| `axum-web-framework` | Axum web apps — routing, middleware, extractors | Complete Axum development guide | +| `axum-tests` | Testing Axum apps — integration tests, mock state | Test patterns for Axum applications | +| `tauri` | Tauri v2 desktop apps — setup, plugins, bundling | Cross-platform desktop app development | +| `tauri-ipc-developer` | Tauri IPC — React-Rust type-safe communication | Command scaffolding and serialization | +| `tauri-devtools` | Tauri debugging — CrabNebula DevTools integration | Profiling and monitoring | +| `github-workflows` | GitHub Actions — CI/CD, workflow debugging | Live syntax, run monitoring, failure diagnosis | +| `security-audit` | Security auditing — dependency scanning, OWASP | Comprehensive security assessment | +| `security-review` | Code security review — injection, XSS, auth flaws | Vulnerability-focused code review | +| `security-docker` | Docker security — Dockerfile, runtime hardening | Container security best practices | + +## Skill Discovery + +The `skill_discovery` preference controls how GSD finds skills during auto mode: + +| Mode | Behavior | +|------|----------| +| `auto` | Skills are found and applied automatically | +| `suggest` | Skills are identified but require confirmation (default) | +| `off` | No skill discovery | + +## Skill Preferences + +Control which skills are used via preferences: + +```yaml +--- +version: 1 +always_use_skills: + - debug-like-expert +prefer_skills: + - frontend-design +avoid_skills: + - security-docker +skill_rules: + - when: task involves Clerk authentication + use: [clerk] + - when: frontend styling work + prefer: [frontend-design] +--- +``` + +### Resolution Order + +Skills can be referenced by: +1. **Bare name** — e.g., `frontend-design` → scans `~/.gsd/agent/skills/` and project skills +2. **Absolute path** — e.g., `/Users/you/.gsd/agent/skills/my-skill/SKILL.md` +3. **Directory path** — e.g., `~/custom-skills/my-skill` → looks for `SKILL.md` inside + +User skills (`~/.gsd/agent/skills/`) take precedence over project skills. + +## Custom Skills + +Create your own skills by adding a directory with a `SKILL.md` file: + +``` +~/.gsd/agent/skills/my-skill/ + SKILL.md — instructions for the LLM + references/ — optional reference files +``` + +The `SKILL.md` file contains instructions the LLM follows when the skill is active. Reference files can be loaded by the skill instructions as needed. + +### Project-Local Skills + +Place skills in your project for project-specific guidance: + +``` +.pi/agent/skills/my-project-skill/ + SKILL.md +``` diff --git a/docs/token-optimization.md b/docs/token-optimization.md new file mode 100644 index 000000000..3f930f5f0 --- /dev/null +++ b/docs/token-optimization.md @@ -0,0 +1,266 @@ +# Token Optimization + +*Introduced in v2.17.0* + +GSD 2.17 introduces a coordinated token optimization system that can reduce token usage by 40-60% without sacrificing output quality for most workloads. The system has three pillars: **token profiles**, **context compression**, and **complexity-based task routing**. + +## Token Profiles + +A token profile is a single preference that coordinates model selection, phase skipping, and context compression level. Set it in your preferences: + +```yaml +--- +version: 1 +token_profile: balanced +--- +``` + +Three profiles are available: + +### `budget` — Maximum Savings (40-60% reduction) + +Optimized for cost-sensitive workflows. Uses cheaper models, skips optional phases, and compresses dispatch context to the minimum needed. + +| Dimension | Setting | +|-----------|---------| +| Planning model | Sonnet | +| Execution model | Sonnet | +| Simple task model | Haiku | +| Completion model | Haiku | +| Subagent model | Haiku | +| Milestone research | **Skipped** | +| Slice research | **Skipped** | +| Roadmap reassessment | **Skipped** | +| Context inline level | **Minimal** — drops decisions, requirements, extra templates | + +Best for: prototyping, small projects, well-understood codebases, cost-conscious iteration. + +### `balanced` — Smart Defaults (default) + +The default profile. Keeps the important phases, skips the ones with diminishing returns for most projects, and uses standard context compression. + +| Dimension | Setting | +|-----------|---------| +| Planning model | User's default | +| Execution model | User's default | +| Simple task model | User's default | +| Completion model | User's default | +| Subagent model | Sonnet | +| Milestone research | Runs | +| Slice research | **Skipped** | +| Roadmap reassessment | Runs | +| Context inline level | **Standard** — includes key context, drops low-signal extras | + +Best for: most projects, day-to-day development. + +### `quality` — Full Context (no compression) + +Every phase runs. Every context artifact is inlined. No shortcuts. + +| Dimension | Setting | +|-----------|---------| +| All models | User's configured defaults | +| All phases | Run | +| Context inline level | **Full** — everything inlined | + +Best for: complex architectures, greenfield projects requiring deep research, critical production work. + +## Context Compression + +Each token profile maps to an **inline level** that controls how much context is pre-loaded into dispatch prompts: + +| Profile | Inline Level | What's Included | +|---------|-------------|-----------------| +| `budget` | `minimal` | Task plan, essential prior summaries (truncated). Drops decisions register, requirements, UAT template, secrets manifest. | +| `balanced` | `standard` | Task plan, prior summaries, slice plan, roadmap excerpt. Drops some supplementary templates. | +| `quality` | `full` | Everything — all plans, summaries, decisions, requirements, templates, and root files. | + +### How Compression Works + +Dispatch prompt builders accept an `inlineLevel` parameter. At each level, specific artifacts are gated: + +**Minimal level reductions:** +- `buildExecuteTaskPrompt` — drops the decisions template, truncates prior summaries to the most recent one +- `buildPlanMilestonePrompt` — drops `PROJECT.md`, `REQUIREMENTS.md`, decisions, and supplementary templates like `secrets-manifest` +- `buildCompleteSlicePrompt` — drops requirements and UAT template inlining +- `buildCompleteMilestonePrompt` — drops root GSD file inlining +- `buildReassessRoadmapPrompt` — drops project, requirements, and decisions files + +These are cumulative — `standard` drops a subset, `minimal` drops more. The `full` level preserves all context (the pre-2.17 behavior). + +### Overriding Inline Level + +The inline level is derived from your `token_profile`. To control phases independently of the profile, use the `phases` preference: + +```yaml +--- +version: 1 +token_profile: budget +phases: + skip_research: false # override: run research even on budget +--- +``` + +Explicit `phases` settings always override the profile defaults. + +## Complexity-Based Task Routing + +GSD automatically classifies each task by complexity and routes it to an appropriate model tier. This means simple documentation fixes don't burn expensive Opus tokens, while complex architectural work gets the reasoning power it needs. + +### How Classification Works + +Tasks are classified by analyzing the task plan: + +| Signal | Simple | Standard | Complex | +|--------|--------|----------|---------| +| Step count | ≤ 3 | 4-7 | ≥ 8 | +| File count | ≤ 3 | 4-7 | ≥ 8 | +| Description length | < 500 chars | 500-2000 | > 2000 chars | +| Code blocks | — | — | ≥ 5 | +| Signal words | None | Any present | — | + +**Signal words** that prevent simple classification: `research`, `investigate`, `refactor`, `migrate`, `integrate`, `complex`, `architect`, `redesign`, `security`, `performance`, `concurrent`, `parallel`, `distributed`, `backward compat`, `migration`, `architecture`, `concurrency`, `compatibility`. + +Empty or malformed plans default to `standard` (conservative). + +### Unit Type Defaults + +Non-task units have built-in tier assignments: + +| Unit Type | Default Tier | +|-----------|-------------| +| `complete-slice`, `run-uat` | Light | +| `research-*`, `plan-*`, `execute-task`, `complete-milestone` | Standard | +| `replan-slice`, `reassess-roadmap` | Heavy | +| `hook/*` | Light | + +### Model Routing + +Each tier maps to a model configuration: + +| Tier | Model Phase Key | Typical Model | +|------|----------------|---------------| +| Light | `completion` | Haiku (budget) / user default | +| Standard | `execution` | Sonnet / user default | +| Heavy | `execution` | Opus / user default | + +Simple tasks use the `execution_simple` model key when configured. This is set automatically by the `budget` profile to Haiku. + +### Budget Pressure + +When approaching your budget ceiling, the classifier automatically downgrades tiers: + +| Budget Used | Effect | +|------------|--------| +| < 50% | No adjustment | +| 50-75% | Standard → Light | +| 75-90% | Standard → Light | +| > 90% | Everything except Heavy → Light; Heavy → Standard | + +This graduated approach preserves model quality for the most complex work while progressively reducing cost as the ceiling approaches. + +## Adaptive Learning (Routing History) + +GSD tracks the success and failure of each tier assignment over time and adjusts future classifications accordingly. This is opt-in — it happens automatically and persists in `.gsd/routing-history.json`. + +### How It Works + +1. After each unit completes, the outcome (success/failure) is recorded against the unit type and tier used +2. Outcomes are tracked per-pattern (e.g., `execute-task`, `execute-task:docs`) with a rolling window of the last 50 entries +3. If a tier's failure rate exceeds 20% for a given pattern, future classifications for that pattern are bumped up one tier +4. The system also accepts tag-specific patterns (e.g., `execute-task:test` vs `execute-task:frontend`) for more granular routing + +### User Feedback + +GSD accepts manual feedback to accelerate learning: + +- **"over"** — the model was overpowered for this task (encourages downgrading) +- **"under"** — the model wasn't capable enough (encourages upgrading) +- **"ok"** — correct assignment (no adjustment) + +Feedback signals are weighted 2× compared to automatic outcomes. + +### Data Management + +```bash +# Routing history is stored per-project +.gsd/routing-history.json + +# Clear history to reset adaptive learning +# (happens via the routing-history module API) +``` + +The feedback array is capped at 200 entries. Per-pattern outcome counts use a rolling window of 50 to prevent stale data from dominating. + +## Configuration Examples + +### Cost-Optimized Setup + +```yaml +--- +version: 1 +token_profile: budget +budget_ceiling: 25.00 +models: + execution_simple: claude-haiku-4-5-20250414 +--- +``` + +### Balanced with Custom Models + +```yaml +--- +version: 1 +token_profile: balanced +models: + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + execution: claude-sonnet-4-6 +--- +``` + +### Full Quality for Critical Work + +```yaml +--- +version: 1 +token_profile: quality +models: + planning: claude-opus-4-6 + execution: claude-opus-4-6 +--- +``` + +### Per-Phase Overrides + +The `token_profile` sets defaults, but explicit preferences always win: + +```yaml +--- +version: 1 +token_profile: budget +phases: + skip_research: false # override: keep milestone research +models: + planning: claude-opus-4-6 # override: use Opus for planning despite budget profile +--- +``` + +## How the Pieces Fit Together + +``` +preferences.md + └─ token_profile: balanced + ├─ resolveProfileDefaults() → model defaults + phase skip defaults + ├─ resolveInlineLevel() → standard + │ └─ prompt builders gate context inclusion by level + └─ classifyUnitComplexity() → routes to execution/execution_simple model + ├─ task plan analysis (steps, files, signals) + ├─ unit type defaults + ├─ budget pressure adjustment + └─ adaptive learning from routing-history.json +``` + +The profile is resolved once and flows through the entire dispatch pipeline. Explicit preferences override profile defaults at every layer. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 000000000..3d368cbd3 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,114 @@ +# Troubleshooting + +## `/gsd doctor` + +The built-in diagnostic tool validates `.gsd/` integrity: + +``` +/gsd doctor +``` + +It checks: +- File structure and naming conventions +- Roadmap ↔ slice ↔ task referential integrity +- Completion state consistency +- Git worktree health +- Stale lock files and orphaned runtime records + +## Common Issues + +### Auto mode loops on the same unit + +**Symptoms:** The same unit (e.g., `research-slice` or `plan-slice`) dispatches repeatedly until hitting the dispatch limit. + +**Causes:** +- Stale cache after a crash — the in-memory file listing doesn't reflect new artifacts +- The LLM didn't produce the expected artifact file + +**Fix:** Run `/gsd doctor` to repair state, then resume with `/gsd auto`. If the issue persists, check that the expected artifact file exists on disk. + +### Auto mode stops with "Loop detected" + +**Cause:** A unit failed to produce its expected artifact twice in a row. + +**Fix:** Check the task plan for clarity. If the plan is ambiguous, refine it manually, then `/gsd auto` to resume. + +### Wrong files in worktree + +**Symptoms:** Planning artifacts or code appear in the wrong directory. + +**Cause:** The LLM wrote to the main repo instead of the worktree. + +**Fix:** This was fixed in v2.14+. If you're on an older version, update. The dispatch prompt now includes explicit working directory instructions. + +### `npm install -g gsd-pi` fails + +**Common causes:** +- Missing workspace packages — fixed in v2.10.4+ +- `postinstall` hangs on Linux (Playwright `--with-deps` triggering sudo) — fixed in v2.3.6+ +- Node.js version too old — requires ≥ 20.6.0 + +### Provider errors during auto mode + +**Symptoms:** Auto mode pauses with a provider error (rate limit, auth failure, etc.). + +**Fix:** GSD automatically tries fallback models if configured. To add fallbacks: + +```yaml +models: + execution: + model: claude-sonnet-4-6 + fallbacks: + - openrouter/minimax/minimax-m2.5 +``` + +### Budget ceiling reached + +**Symptoms:** Auto mode pauses with "Budget ceiling reached." + +**Fix:** Increase `budget_ceiling` in preferences, or switch to `budget` token profile to reduce per-unit cost, then resume with `/gsd auto`. + +### Stale lock file + +**Symptoms:** Auto mode won't start, says another session is running. + +**Fix:** If no other session is actually running, delete `.gsd/auto.lock` manually. GSD includes stale lock detection (checks if the PID is still alive), but edge cases exist. + +### Git merge conflicts + +**Symptoms:** Worktree merge fails on `.gsd/` files. + +**Fix:** GSD auto-resolves conflicts on `.gsd/` runtime files. For content conflicts in code files, the LLM is given an opportunity to resolve them via a fix-merge session. If that fails, manual resolution is needed. + +## Recovery Procedures + +### Reset auto mode state + +```bash +rm .gsd/auto.lock +rm .gsd/completed-units.json +``` + +Then `/gsd auto` to restart from current disk state. + +### Reset routing history + +If adaptive model routing is producing bad results, clear the routing history: + +```bash +rm .gsd/routing-history.json +``` + +### Full state rebuild + +``` +/gsd doctor +``` + +Doctor rebuilds `STATE.md` from plan and roadmap files on disk and fixes detected 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` for real-time diagnostics +- **Session logs:** `.gsd/activity/` contains JSONL session dumps for crash forensics diff --git a/docs/working-in-teams.md b/docs/working-in-teams.md new file mode 100644 index 000000000..febea592c --- /dev/null +++ b/docs/working-in-teams.md @@ -0,0 +1,99 @@ +# Working in Teams + +GSD supports multi-user workflows where several developers work on the same repository concurrently. + +## Setup + +### 1. Enable Unique Milestone IDs + +Prevent ID collisions when multiple developers create milestones: + +```yaml +# .gsd/preferences.md (project-level, committed to git) +--- +version: 1 +unique_milestone_ids: true +--- +``` + +This generates milestone IDs like `M001-eh88as` instead of plain `M001`. The random suffix ensures no two developers clash. + +### 2. Configure `.gitignore` + +Share planning artifacts (milestones, roadmaps, decisions) while keeping runtime files local: + +```bash +# ── GSD: Runtime / Ephemeral (per-developer, per-session) ────── +.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 cache, runtime records, worktrees, activity logs + +### 3. Commit the Preferences + +```bash +git add .gsd/preferences.md +git commit -m "chore: enable GSD team workflow" +``` + +## `commit_docs: false` + +For teams where only some members use GSD, or when company policy requires a clean repo: + +```yaml +git: + commit_docs: false +``` + +This adds `.gsd/` to `.gitignore` entirely and keeps all artifacts local. The developer gets the benefits of structured planning without affecting teammates who don't use GSD. + +## Migrating an Existing Project + +If you have an existing project with `.gsd/` blanket-ignored: + +1. Ensure no milestones are in progress (clean state) +2. Update `.gitignore` to use the selective pattern above +3. Add `unique_milestone_ids: true` to `.gsd/preferences.md` +4. Optionally rename existing milestones to use unique IDs: + ``` + I have turned on unique milestone ids, please update all old milestone + ids to use this new format e.g. M001-abc123 where abc123 is a random + 6 char lowercase alpha numeric string. Update all references in all + .gsd file contents, file names and directory names. Validate your work + once done to ensure referential integrity. + ``` +5. Commit + +## Parallel Development + +Multiple developers can run auto mode simultaneously on different milestones. Each developer: + +- Gets their own worktree (`.gsd/worktrees//`, gitignored) +- Works on a unique `milestone/` branch +- Squash-merges to main independently + +Milestone dependencies can be declared in `M00X-CONTEXT.md` frontmatter: + +```yaml +--- +depends_on: [M001-eh88as] +--- +``` + +GSD enforces that dependent milestones complete before starting downstream work.