From 2f2d0507c1db21f236b949345a6ac9a8669842ec Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 16 Mar 2026 23:47:20 -0400 Subject: [PATCH] docs: update documentation for v2.22 features (#787) New v2.22 features documented: - commands.md: Add /gsd forensics (post-mortem investigation) and /gsd cleanup - commands.md: Add MCP Server Mode section for --mode mcp - configuration.md: Add /gsd prefs import-claude commands for Claude marketplace import - skills.md: Add review, test, and lint skills to bundled skills table - auto-mode.md: Add Post-Mortem Investigation section referencing /gsd forensics - troubleshooting.md: Add forensics to Getting Help section, fix corrupted duplicate line - README.md: Update troubleshooting link description to include forensics --- README.md | 2 +- docs/auto-mode.md | 4 ++++ docs/commands.md | 13 +++++++++++++ docs/configuration.md | 3 +++ docs/skills.md | 3 +++ docs/troubleshooting.md | 2 +- 6 files changed, 25 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c232fa73e..70e8b57e5 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Full documentation is available in the [`docs/`](./docs/) directory: - **[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 +- **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, forensics, recovery - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration --- diff --git a/docs/auto-mode.md b/docs/auto-mode.md index dbf35fd94..5b95bc6f6 100644 --- a/docs/auto-mode.md +++ b/docs/auto-mode.md @@ -63,6 +63,10 @@ A lock file tracks the current unit. If the session dies, the next `/gsd auto` r 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. +### Post-Mortem Investigation + +When auto mode fails or produces unexpected results, `/gsd forensics` provides structured post-mortem analysis. It inspects activity logs, crash locks, and session state to identify root causes — whether the failure was a model error, missing context, a stuck loop, or a broken tool call. See [Troubleshooting](./troubleshooting.md) for more on diagnosing issues. + ### Timeout Supervision Three timeout tiers prevent runaway sessions: diff --git a/docs/commands.md b/docs/commands.md index 488d27c3f..9f12993b0 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -15,6 +15,8 @@ | `/gsd queue` | Queue and reorder future milestones (safe during auto mode) | | `/gsd capture` | Fire-and-forget thought capture (works during auto mode) | | `/gsd triage` | Manually trigger triage of pending captures | +| `/gsd forensics` | Post-mortem investigation of auto-mode failures — structured root-cause analysis with log inspection | +| `/gsd cleanup` | Clean up GSD state files and stale worktrees | | `/gsd visualize` | Open workflow visualizer (progress, deps, metrics, timeline) | | `/gsd knowledge` | Add persistent project knowledge (rule, pattern, or lesson) | | `/gsd help` | Categorized command reference with descriptions for all GSD subcommands | @@ -121,3 +123,14 @@ gsd headless dispatch plan **Exit codes:** `0` = complete, `1` = error or timeout, `2` = blocked. Any `/gsd` subcommand works as a positional argument — `gsd headless status`, `gsd headless doctor`, `gsd headless dispatch execute`, etc. + +## MCP Server Mode + +`gsd --mode mcp` runs GSD as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdin/stdout. This exposes all GSD tools (read, write, edit, bash, etc.) to external AI clients — Claude Desktop, VS Code Copilot, and any MCP-compatible host. + +```bash +# Start GSD as an MCP server +gsd --mode mcp +``` + +The server registers all tools from the agent session and maps MCP `tools/list` and `tools/call` requests to GSD tool definitions. It runs until the transport closes. diff --git a/docs/configuration.md b/docs/configuration.md index 9b18fcd6b..b38f11f77 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,6 +12,9 @@ GSD preferences live in `~/.gsd/preferences.md` (global) or `.gsd/preferences.md | `/gsd prefs status` | Show current preference files, merged values, and skill resolution status | | `/gsd prefs wizard` | Alias for `/gsd prefs global` | | `/gsd prefs setup` | Alias for `/gsd prefs wizard` — creates preferences file if missing | +| `/gsd prefs import-claude` | Import Claude marketplace plugins and skills as namespaced GSD components | +| `/gsd prefs import-claude global` | Import to global scope | +| `/gsd prefs import-claude project` | Import to project scope | ## Preferences File Format diff --git a/docs/skills.md b/docs/skills.md index 213b19579..5a9cab0dd 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -21,6 +21,9 @@ GSD ships with these skills, installed to `~/.gsd/agent/skills/`: | `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 | +| `review` | Code review — staged changes, PRs, security, performance | Diff-aware code review with quality analysis | +| `test` | Test generation and execution — auto-detects frameworks | Generate tests or run existing suites with failure analysis | +| `lint` | Linting and formatting — ESLint, Biome, Prettier | Auto-detect linter, fix issues, report remaining problems | ## Skill Discovery diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 699d2c7ae..bbcf700c1 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -111,5 +111,5 @@ Doctor rebuilds `STATE.md` from plan and roadmap files on disk and fixes detecte - **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 +- **Forensics:** `/gsd forensics` for structured post-mortem analysis of auto-mode failures - **Session logs:** `.gsd/activity/` contains JSONL session dumps for crash forensics -ctivity/` contains JSONL session dumps for crash forensics