From 59134fa42682883e72338f5598ae0e6409ad6ec0 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 16 Mar 2026 23:56:00 -0400 Subject: [PATCH] docs: update documentation for v2.23 release features (#788) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New v2.23 features documented: - getting-started.md: Add VS Code extension install section (chat participant, sidebar dashboard, command palette, RPC requirement) - README.md: Add VS Code extension to documentation index, update troubleshooting link to include forensics - docs/README.md: Add VS Code extension to user documentation table - architecture.md: Add headless mode, MCP server mode, and VS Code extension to system structure diagram; expand Browser Tools description to cover 10 new tools (PDF export, device emulation, visual regression, structured extraction, route mocking, etc.); add missing extensions (Async Jobs, Remote Questions, TTSR, Universal Config) - auto-mode.md: Add validate-milestone phase to the pipeline diagram and phase descriptions — reconciliation gate before milestone completion - configuration.md: Add models.json resolution section — custom model definitions with ~/.gsd/agent/models.json and ~/.pi/agent/models.json fallback Co-authored-by: TÂCHES --- README.md | 1 + docs/README.md | 1 + docs/architecture.md | 11 ++++++++++- docs/auto-mode.md | 3 +++ docs/configuration.md | 9 +++++++++ docs/getting-started.md | 10 ++++++++++ 6 files changed, 34 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 70e8b57e5..41b94044b 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ Full documentation is available in the [`docs/`](./docs/) directory: - **[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, forensics, recovery +- **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration --- diff --git a/docs/README.md b/docs/README.md index 855fa68fd..76ac5aa81 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,6 +22,7 @@ Welcome to the GSD documentation. This covers everything from getting started to | [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 | +| [VS Code Extension](../vscode-extension/README.md) | Chat participant, sidebar dashboard, and RPC integration for VS Code | ## Architecture & Internals diff --git a/docs/architecture.md b/docs/architecture.md index 3fc29d2ca..4b49bea68 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -18,6 +18,11 @@ gsd (CLI binary) ├─ agents/ scout, researcher, worker ├─ AGENTS.md Agent routing instructions └─ GSD-WORKFLOW.md Manual bootstrap protocol + +gsd headless Headless mode — CI/cron orchestration via RPC child process +gsd --mode mcp MCP server mode — exposes tools over stdin/stdout + +vscode-extension/ VS Code extension — chat participant (@gsd), sidebar dashboard, RPC integration ``` ## Key Design Decisions @@ -47,7 +52,7 @@ Every dispatch creates a new agent session. The LLM starts with a clean context | 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 | +| **Browser Tools** | Playwright-based browser automation — navigation, forms, screenshots, PDF export, device emulation, visual regression, structured data extraction, route mocking, accessibility tree inspection, 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 | @@ -60,6 +65,10 @@ Every dispatch creates a new agent session. The LLM starts with a clean context | **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 | +| **Async Jobs** | Background command execution with `async_bash`, `await_job`, `cancel_job` | +| **Remote Questions** | Discord, Slack, and Telegram integration for headless question routing | +| **TTSR** | Tool-triggered system rules — conditional context injection based on tool usage | +| **Universal Config** | Discovery of existing AI tool configurations (Claude Code, Cursor, Windsurf, etc.) | ## Bundled Agents diff --git a/docs/auto-mode.md b/docs/auto-mode.md index 5b95bc6f6..48f0ae603 100644 --- a/docs/auto-mode.md +++ b/docs/auto-mode.md @@ -12,6 +12,8 @@ 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 @@ -19,6 +21,7 @@ Research → Plan → Execute (per task) → Complete → Reassess Roadmap → N - **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 +- **Validate Milestone** — reconciliation gate after all slices complete; compares roadmap success criteria against actual results, catches gaps before sealing the milestone ## Key Properties diff --git a/docs/configuration.md b/docs/configuration.md index b38f11f77..7214f173d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -76,6 +76,15 @@ models: - Provider targeting: use `provider/model` format (e.g., `bedrock/claude-sonnet-4-6`) or the `provider` field in object format - Omit a key to use whatever model is currently active +### Custom Model Definitions (`models.json`) + +Define custom models in `~/.gsd/agent/models.json`. This lets you add models not included in the default registry — useful for self-hosted endpoints, fine-tuned models, or new releases. + +GSD resolves models.json with fallback logic: +1. `~/.gsd/agent/models.json` — primary (GSD) +2. `~/.pi/agent/models.json` — fallback (Pi) +3. If neither exists, creates `~/.gsd/agent/models.json` + **With fallbacks:** ```yaml diff --git a/docs/getting-started.md b/docs/getting-started.md index c2909e936..54366ca36 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -8,6 +8,16 @@ npm install -g gsd-pi Requires Node.js ≥ 20.6.0 (22+ recommended) and Git. +### 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. + ## First Launch Run `gsd` in any directory: