From 1aebc06c46df2015ba9bf9ab4008e25082e50383 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Tue, 17 Mar 2026 09:47:28 -0400 Subject: [PATCH] docs: update documentation for v2.24 release features (#825) - README: add parallel orchestration link, update loop diagram with validate-milestone phase - architecture: add lazy provider loading, memory-extractor/store modules, update module table to v2.24 - auto-mode: add rate limit recovery section, parallel worker status in dashboard - commands: add headless new-milestone command with --context/--context-text/--auto flags - getting-started: add update check notification note - troubleshooting: update rate limit recovery guidance - visualizer: add task counts, discussion status to progress tab --- README.md | 5 ++++- docs/architecture.md | 11 +++++++++-- docs/auto-mode.md | 5 +++++ docs/commands.md | 13 +++++++++++++ docs/getting-started.md | 2 ++ docs/troubleshooting.md | 2 +- docs/visualizer.md | 12 +++++++----- 7 files changed, 41 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 41b94044b..0bf4214b7 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Full documentation is available in the [`docs/`](./docs/) directory: - **[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 +- **[Parallel Orchestration](./docs/parallel-orchestration.md)** — run multiple milestones simultaneously - **[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 @@ -112,9 +113,11 @@ Each slice flows through phases automatically: ``` Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice + ↓ (all slices done) + Validate Milestone → Complete Milestone ``` -**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned. +**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone. ### `/gsd auto` — The Main Event diff --git a/docs/architecture.md b/docs/architecture.md index 4b49bea68..752ab56d5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,6 +43,10 @@ vscode-extension/ VS Code extension — chat participant (@gsd), sidebar Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run. This means `npm update -g` takes effect immediately. +### Lazy Provider Loading + +LLM provider SDKs (Anthropic, OpenAI, Google, etc.) are lazy-loaded on first use rather than imported at startup. This significantly reduces cold-start time — only the provider you actually connect to gets loaded. + ### 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. @@ -118,7 +122,7 @@ The auto mode dispatch pipeline: Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the corresponding unit type is never dispatched. -## Key Modules (v2.19) +## Key Modules (v2.24) | Module | Purpose | |--------|---------| @@ -134,8 +138,11 @@ Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the | `triage-resolution.ts` | Capture resolution (inject, defer, replan, quick-task) | | `visualizer-overlay.ts` | Workflow visualizer TUI overlay | | `visualizer-data.ts` | Data loading for visualizer tabs | -| `visualizer-views.ts` | Tab renderers (progress, deps, metrics, timeline) | +| `visualizer-views.ts` | Tab renderers (progress, deps, metrics, timeline, discussion status) | | `metrics.ts` | Token and cost tracking ledger | | `state.ts` | State derivation from disk | | `preferences.ts` | Preference loading, merging, validation | +| `git-service.ts` | Git operations — commit, merge, worktree sync, completed-units cross-boundary sync | +| `memory-extractor.ts` | Extract reusable knowledge from session transcripts | +| `memory-store.ts` | Persistent memory store for cross-session knowledge | | `queue-order.ts` | Milestone queue ordering | diff --git a/docs/auto-mode.md b/docs/auto-mode.md index 48f0ae603..82a3047c9 100644 --- a/docs/auto-mode.md +++ b/docs/auto-mode.md @@ -62,6 +62,10 @@ When your project has independent milestones, you can run them simultaneously. E 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. +### Rate Limit Recovery + +When a provider hits a rate limit, GSD waits with exponential backoff (up to 5 minutes) and automatically resumes auto-mode after the cooldown period. No manual intervention needed — the session continues from where it left off. + ### 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. @@ -161,6 +165,7 @@ Open the workflow visualizer — interactive tabs for progress, dependencies, me - Cost projections - Completed and in-progress units - Pending capture count (when captures are awaiting triage) +- Parallel worker status (when running parallel milestones — includes 80% budget alert) ## Phase Skipping diff --git a/docs/commands.md b/docs/commands.md index 9f12993b0..8805c9d67 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -92,6 +92,7 @@ See [Parallel Orchestration](./parallel-orchestration.md) for full documentation | `gsd --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues | | `gsd config` | Re-run the setup wizard (LLM provider + tool keys) | | `gsd update` | Update GSD to the latest version | +| `gsd headless new-milestone` | Create a new milestone from a context file (headless — no TUI required) | ## Headless Mode @@ -112,6 +113,15 @@ gsd headless --timeout 600000 auto # Force a specific phase gsd headless dispatch plan + +# Create a new milestone from a context file and start auto mode +gsd headless new-milestone --context brief.md --auto + +# Create a milestone from inline text +gsd headless new-milestone --context-text "Build a REST API with auth" + +# Pipe context from stdin +echo "Build a CLI tool" | gsd headless new-milestone --context - ``` | Flag | Description | @@ -119,6 +129,9 @@ gsd headless dispatch plan | `--timeout N` | Overall timeout in milliseconds (default: 300000 / 5 min) | | `--json` | Stream all events as JSONL to stdout | | `--model ID` | Override the model for the headless session | +| `--context ` | Context file for `new-milestone` (use `-` for stdin) | +| `--context-text ` | Inline context text for `new-milestone` | +| `--auto` | Chain into auto-mode after milestone creation | **Exit codes:** `0` = complete, `1` = error or timeout, `2` = blocked. diff --git a/docs/getting-started.md b/docs/getting-started.md index 54366ca36..570753b49 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -8,6 +8,8 @@ npm install -g gsd-pi Requires Node.js ≥ 20.6.0 (22+ recommended) and Git. +GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip. + ### 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: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index bbcf700c1..7f9934234 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -52,7 +52,7 @@ It checks: **Symptoms:** Auto mode pauses with a provider error (rate limit, auth failure, etc.). -**Fix:** GSD automatically tries fallback models if configured. To add fallbacks: +**Fix:** GSD automatically resumes after rate limit cooldowns with exponential backoff (up to 5 minutes). For auth failures, GSD tries fallback models if configured: ```yaml models: diff --git a/docs/visualizer.md b/docs/visualizer.md index 6aa8e6747..7d17279f7 100644 --- a/docs/visualizer.md +++ b/docs/visualizer.md @@ -25,18 +25,20 @@ Switch tabs with `Tab`, `1`-`4`, or arrow keys. A tree view of milestones, slices, and tasks with completion status: ``` -M001: User Management - ✅ S01: Auth module +M001: User Management 3/6 tasks ⏳ + ✅ S01: Auth module 3/3 tasks ✅ T01: Core types ✅ T02: JWT middleware ✅ T03: Login flow - ⏳ S02: User dashboard + ⏳ S02: User dashboard 1/2 tasks ✅ T01: Layout component ⬜ T02: Profile page - ⬜ S03: Admin panel + ⬜ S03: Admin panel 0/1 tasks ``` -Shows checkmarks for completed items, spinners for in-progress, and empty boxes for pending. +Shows checkmarks for completed items, spinners for in-progress, and empty boxes for pending. Task counts and completion percentages are displayed at each level. + +**Discussion status** is also shown when milestones have been through a discussion phase — indicates whether requirements were captured and what state the discussion left off in. ### 2. Dependencies