[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74768":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":16,"starSnapshotCount":16,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},74768,"gsd-2","gsd-build\u002Fgsd-2","gsd-build","A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture","",null,"TypeScript",7734,777,31,3,0,10,392,30,39.67,"MIT License",false,"main",true,[26,27,28],"context-engineering","meta-prompting","spec-driven-development","2026-06-12 02:03:27","\u003Cdiv align=\"center\">\n\n# GSD 2\n\n**The evolution of [Get Shit Done](https:\u002F\u002Fgithub.com\u002Fgsd-build\u002Fget-shit-done) — now a real coding agent.**\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fgsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fgsd-pi)\n[![npm downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002Fgsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fgsd-pi)\n[![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fgsd-build\u002FGSD-2?style=for-the-badge&logo=github&color=181717)](https:\u002F\u002Fgithub.com\u002Fgsd-build\u002FGSD-2)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https:\u002F\u002Fdiscord.com\u002Finvite\u002FnKXTsAcmbT)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue?style=for-the-badge)](LICENSE)\n[![$GSD Token](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F$GSD-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image\u002Fsvg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https:\u002F\u002Fdexscreener.com\u002Fsolana\u002Fdwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv)\n\nThe original GSD went viral as a prompt framework for Claude Code. It worked, but it was fighting the tool — injecting prompts through slash commands, hoping the LLM would follow instructions, with no actual control over context windows, sessions, or execution.\n\nThis version is different. GSD is now a standalone CLI built on the [Pi SDK](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi-mono), which gives it direct TypeScript access to the agent harness itself. That means GSD can actually _do_ what v1 could only _ask_ the LLM to do: clear context between tasks, inject exactly the right files at dispatch time, manage git branches, track cost and tokens, detect stuck loops, recover from crashes, and auto-advance through an entire milestone without human intervention.\n\nOne command. Walk away. Come back to a built project with clean git history.\n\n\u003Cpre>\u003Ccode>npm install -g gsd-pi@latest\u003C\u002Fcode>\u003C\u002Fpre>\n\n> GSD now provisions a managed [RTK](https:\u002F\u002Fgithub.com\u002Frtk-ai\u002Frtk) binary on supported macOS, Linux, and Windows installs to compress shell-command output in `bash`, `async_bash`, `bg_shell`, and verification flows. GSD forces `RTK_TELEMETRY_DISABLED=1` for all managed invocations. Set `GSD_RTK_DISABLED=1` to disable the integration.\n\n> **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](.\u002Fdocs\u002Fuser-docs\u002Fnode-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues.\n\n\u003C\u002Fdiv>\n\n---\n\n## What's New in v3.0\n\nThe v3.0 release closes the single-writer engine v3 control plane, finishes the ADR-013 memory cutover, and adds two new top-level commands. It also lands a long list of dispatch-ordering, recovery, and cross-platform fixes that have been accumulating since the v2.82 cut.\n\n### New Commands\n\n- **`\u002Fgsd verdict \u003Cpass|needs-attention|needs-remediation>`** — manually override the recorded milestone validation verdict when auto-mode pauses with a non-passing verdict. Previously the only recovery path was hand-editing `VALIDATION.md` frontmatter or hand-crafting a seven-field `gsd_validate_milestone` call. The new command resolves the active milestone if `--milestone` is omitted, preserves every other section of the existing validation file, and requires `--rationale` for non-pass verdicts. Paused-state messages now reference the command directly instead of \"update the verdict manually.\"\n- **`\u002Fgsd brief \u003Cmode>`** — generate a visual HTML brief in one of six modes (`diagram`, `plan`, `diff`, `recap`, `table`, `slides`). The HTML shell is unified with `\u002Fgsd export` so both surfaces produce consistent output.\n- **ROADMAP `[sketch]` badges** (ADR-011) — slices that have not been refined past sketch level are now badged in the rendered roadmap, so it's obvious at a glance which slices still need planning work.\n\n### Auto Orchestration Parity (Single-Writer Engine v3 Control Plane)\n\nThe v2.x dispatch layer accumulated parallel code paths between the legacy `auto.ts` loop and the newer Auto Orchestration kernel. v3.0 closes that gap:\n\n- **Dispatch adapter receives full session inputs** — the adapter now gets the same context the orchestrator does, eliminating a class of \"the new path is missing X\" bugs.\n- **Orchestrator reaches `runPreDispatch` parity** — pre-dispatch validation runs through the orchestrator path with the same checks the legacy path has, so behavior no longer depends on which entry point fired.\n- **Stuck-loop detection moved into Auto Orchestration** — previously partly in the legacy loop; now owned by the orchestrator so stuck detection participates in the same lifecycle as everything else.\n- **`AutoAdvanceResult` widened with `unit` and `action`** — callers can now branch on the actual outcome of an advance without re-deriving it.\n\n### Dispatch & Recovery Reliability\n\n- **State mutations now happen after pre-dispatch validation** — previously, auto-mode would mutate session state and emit journal events before pre-dispatch validation passed, so a failed validation could leave the journal believing a unit had dispatched. State writes now wait until validation succeeds.\n- **Provider 500 errors pause and retry instead of aborting** — auto-mode used to hard-stop the loop when a model provider returned a 5xx. The dispatch path now pauses with a retry budget so transient provider outages don't lose session state.\n- **`needs-attention` and `needs-remediation` verdicts guarded in dispatch** — completing-milestone no longer falsely loops when validation produced a non-pass terminal verdict. Combined with `\u002Fgsd verdict`, paused milestones are unstuck-able without hand-editing files.\n- **`validate-milestone` infinite-loop guard** — when an LLM failed to call `gsd_validate_milestone` and the unit ran without an artifact, dispatch would re-fire forever. The unit now fails closed with a recoverable error instead of looping.\n- **Empty milestone worktree recovery** — milestones that were entered, paused, and resumed against an empty\u002Forphaned worktree now recover cleanly instead of stalling.\n- **Stuck-detection key consistency across sessions** — derived keys now match how DB persistence records them (bare `unitId`), so cross-session stuck detection actually fires.\n- **DB-backed stale worker cleanup also covers hook dispatchers** — previously could leave crashed hook-dispatch rows active and poison the next session.\n- **Stale lock detection when worker PID is dead** — `clearLock()` now marks the DB worker as stopping so resume after a crash isn't blocked until the 30-minute stale window expires.\n- **Auto-mode crash on MCP tool resolution failure** — research-slice no longer reports false success when an MCP tool fails to resolve; the dispatch loop catches the failure instead of treating it as a completion.\n- **Auto-commit submodule + empty `keyFiles` handling** — `git add -- (none)` no longer crashes auto-commit, and `keyFiles` that live inside a submodule no longer throw `pathspec is in submodule`.\n\n### Verification & Safety\n\n- **Reject unsafe verify commands before execution** — the verification gate now refuses to run commands that violate the tools policy, instead of executing first and failing the gate afterwards.\n- **Reconcile preflight stash collisions** — milestone-entry stash now reconciles with pre-existing stashes instead of silently overwriting them.\n- **Execute-task verification fails closed** — when verification cannot reach a definitive verdict, it fails the task instead of optimistically passing.\n- **Read-required-before-write in prompts** — prompt contracts now require reading a file before writing it, reducing the rate of clobbered edits.\n- **Doctor blocks snapshots that contain conflict markers** — `\u002Fgsd doctor` refuses to take a snapshot of a working tree with unresolved merge conflicts.\n\n### Memory Architecture Cutover (ADR-013)\n\nThe v2.77 introduction of the memories table is now fully load-bearing. Decisions and KNOWLEDGE patterns\u002Flessons read from and write to memories first, with `DECISIONS.md` and `KNOWLEDGE.md` projected from that source:\n\n- **Stage 1** — prompt-inline decisions read from memories.\n- **Stage 2a–2c** — `DECISIONS.md` projection sources from memories; `KNOWLEDGE.md` backfill + hybrid projection; `\u002Fgsd knowledge` routes patterns and lessons into memories.\n- **Stage 3** — `gsd_save_decision` no longer writes to the legacy decisions table.\n- **Preflight scanner** — detects pre-cutover artifacts and warns before they cause divergence.\n\n### Cross-Platform & Infrastructure\n\n- **gsd.db on WSL2 9p mounts** — WAL+mmap pragmas were corrupting `gsd.db` on `\u002Fmnt\u002Fc` and `\u002Fmnt\u002Fd`. The database layer now detects 9p mounts and uses safer pragmas.\n- **Milestone merge on Windows** — silent failure when `gsd.db` held a SQLite WAL lock is now surfaced as a recoverable error instead of an empty merge.\n- **Web UI multi-drive access** — Windows users can now point the web UI at projects outside the `C:` drive.\n- **Bedrock context overflow in `--print` mode** — fixed; long contexts no longer crash headless runs against Bedrock models.\n- **OpenAI Codex 429 retries** — no longer fire inside the provider cooldown window (Gemini path was already correct).\n- **Antigravity model removal** — the misleading 404 from Cloud Code Assist when Antigravity models are removed is now a clear error message.\n- **cmux usability after exit** — GSD no longer leaves cmux in a broken terminal state after exit.\n\n### TUI, Web, and Visualizer\n\n- **Web visualizer tabs updated** — refreshed tab set across the 10-tab visualizer.\n- **Auto resume blocker surface** — when resume is blocked (e.g., needs-remediation + all slices complete), the blocker reason is shown prominently instead of buried.\n- **Pi-coding-agent rendering** — empty reasoning blocks no longer render a blank assistant rail for GPT-5.5 tool-only turns; interactive tool output defaults to expanded.\n- **Step-mode polish** — completion surface preserved across step-mode boundary; next-action guidance clarified after pause.\n- **HTML shell unified across `\u002Fgsd export` and `\u002Fgsd brief`** — one shared visual language for generated reports.\n\n### Subagent Telemetry\n\n- **Random tracking names** — subagent runs get human-readable random names that show up in dashboards, making it easier to trace a specific run across logs.\n- **Resumable isolated launches** — subagent launch records persist, so a crashed subagent can be resumed instead of restarted from scratch.\n\nSee the full [Changelog](.\u002FCHANGELOG.md) for the complete v3.0 entry and prior releases.\n\n\u003Cdetails>\n\u003Csummary>v2.82 highlights\u003C\u002Fsummary>\n\n### State Reconciliation & Drift Detection (ADR-017)\n\n- **Unified drift-detection framework** — a new state-reconciliation layer replaces ad-hoc recovery checks. Each drift kind (stale worker, unregistered milestone, roadmap divergence, missing completion timestamp, merge-state, stale render) is owned by a focused detector + idempotent repair handler registered in a single registry, with a cap=2 retry contract that ensures repair-then-retry settles cleanly.\n- **Stale session locks no longer block resume** — when a `\u002Fgsd auto` process is SIGKILL'd, sleep-killed, or otherwise crashes, the `auto.lock` file is left behind with a dead PID. Previously you had to wait out a 30-minute stale window before `\u002Fgsd` would resume. The new `stale-worker` drift handler verifies the PID is alive and clears orphaned locks proactively on startup.\n- **Unregistered milestones get imported automatically** — if you scaffold a milestone directory (with `ROADMAP.md`\u002F`CONTEXT.md`\u002F`SUMMARY.md`) but never re-imported, dispatch couldn't see it. The `unregistered-milestone` handler now imports those rows idempotently before dispatch.\n- **ROADMAP and DB stay in sync** — divergence between `ROADMAP.md` (parsed slice sequence + `depends` declarations) and the corresponding DB slice rows is detected per-milestone and reconciled via importer upserts plus an explicit `syncSliceDependencies` pass.\n- **Missing completion timestamps backfill from disk** — entities marked complete in the DB but with a null `completed_at` are now backfilled from `SUMMARY.md` mtime, deterministically and idempotently. Tasks are checked independently of their parent slice status.\n- **Parallel spawns reconcile before fanning out** — `\u002Fgsd parallel start` and slice-parallel-dispatch now run reconciliation at the parent before spawning auto-loop workers. Gate failures surface a typed exit reason (`slice-parallel-reconciliation-failed`) and a user-visible message.\n\n### Worktree Lifecycle Refactor (ADR-016 — final phases)\n\n- **Phase 2 complete** — the worktree-manager module finished absorbing fs primitives, git-CLI primitives, worktree-manager helpers, cache\u002Fpreferences\u002Fpaths, and the final `gitServiceFactory`. Lifecycle verbs are now first-class: `adoptOrphanWorktree`, `adoptSessionRoot`, `resumeFromPausedSession`, and `restoreToProjectRoot` are explicit entry points.\n- **Phase 3 closes strict-closure residuals** — dead defensive fallbacks removed from `auto.ts` stop-path catch blocks. The public `WorktreeLifecycleDeps` interface dropped 15 `@deprecated` optional fields; the active dep bag is now three fields.\n\n### Auto-Mode Reliability\n\n- **`complete-slice` closeout is read-only** — closeout prompts can no longer write project files, removing closeout-vs-next-slice races.\n- **Verification retries back off properly** — bounded exponential backoff with stuck detection between attempts; transient failures no longer spin.\n- **Auto-loop exit paths are journaled end-to-end** — post-unit finalize stops, all unit-end exits, and the run-unit failsafe now journal cleanly.\n- **Ghost completions and stale telemetry are guarded** — no stops on ghost completions before milestone stops fire; unmerged-exit telemetry gated on active worktrees.\n\n### TUI & Operator Experience\n\n- **Operations console redesign** — auto-mode dashboard, notification overlay, parallel-monitor overlay, health widget, header renderer, and welcome screen rebuilt against a shared `render-kit`.\n- **Milestone completion rollup** — `CompletionDashboardSnapshot` summarizes success criteria, DoD, requirements, deviations, follow-ups, key decisions, key files, lessons, cost, tokens, cache hit rate, and slice progress at milestone boundaries.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.81 highlights\u003C\u002Fsummary>\n\n- **Worktree safety is fail-closed** — write\u002Fedit operations enforce the worktree-isolation contract; lifecycle and projection split into dedicated modules; milestone merge closeout is harder to wedge.\n- **Memory, context, and token control** — artifact integrity fingerprints, time-decay memory ranking, safer FTS5 fallback, request-time tool scoping, leaner workflow prompts, and more accurate session\u002Fcontext token accounting.\n- **TUI polish** — compact tool output with targets, refreshed chat\u002Ftool cards, adaptive refresher layouts, stable welcome\u002Fheader lifecycle, and bottom-anchored auto-mode rendering.\n- **Reliability, tests, and CI** — auto-mode recovery and session handoff hardened, broad E2E coverage expansion (real-process MCP, fake LLM, native ABI, Docker, Windows), and a faster, less-noisy CI gate setup.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.80 highlights\u003C\u002Fsummary>\n\n- **DB-authoritative context** — UOK contracts moved through database-backed runtime state, auto-run context mode was wired end-to-end, and planned slices recover after artifact writes.\n- **Auto, deep mode, and gates** — deep queued milestones continue, deep project milestones register cleanly, depth-verification regressions were closed, and task commits respect the milestone completion guard.\n- **MCP, post-exec, and cross-platform hardening** — post-exec import fallback handling, React Router `+types` imports, `gsd_exec` write gating, project-save behavior, and home-directory fallback behavior were tightened.\n- **Reliability and review hardening** — auto orchestration contracts, cancellation context preservation, recovery stop lifecycle events, trace correlation, cleanup-on-throw, and phase-result guards were improved.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.79 highlights\u003C\u002Fsummary>\n\n- **DB-backed runtime coordination** — workers, leases, dispatches, command queue, locks, paused-session state, and stuck-state recovery moved into `gsd.db`\n- **Workspace\u002Fworktree isolation** — `GsdWorkspace` and `MilestoneScope` handles, symlink-safe canonicalization, worktree-scoped DB\u002Fmetrics, cwd anchoring, and `gsd worktree {list, merge, clean, remove}`\n- **Deep planning mode** — `\u002Fgsd new-project --deep`, research dispatch units, EVAL-REVIEW, project-shape-aware questioning, and approval-gate hardening\n- **Auto pipeline upgrades** — delegation-policy verdicts, reactive-execute default, proactive rate limiting, manifest-driven skill surfacing, and subagent telemetry\n- **MCP\u002Fmodel\u002Fcross-platform fixes** — global MCP config, `ask_user_questions` over MCP, provider-agnostic model routing, Ollama timeouts, Windows fixes, and Anthropic prompt-cache preservation\n- **Git and recovery reliability** — self-merge guards, safer slice cadence, milestone-ID reservation, auto-commit hygiene, retryable GitHub sync, atomic metrics writes, and stronger teardown handling\n- **VS Code and TUI polish** — checkpoint tree view, image paste preservation, and bundled `\u002Fgsd` slash command protection\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.78 highlights\u003C\u002Fsummary>\n\n- **Slice-cadence worktree collapse (#4765)** — `git.collapse_cadence: \"milestone\" | \"slice\"` shrinks the orphan window per-slice; pair with `git.milestone_resquash: true` to collapse to one milestone commit\n- **Worktree telemetry (#4764)** — journal events + `summarizeWorktreeTelemetry`; `\u002Fgsd forensics` worktree section with `worktree-orphan` and `worktree-unmerged-exit` anomalies\n- **Worktree-aware canonical milestone root (#4761)** — `resolveCanonicalMilestoneRoot` routes validators through the live worktree\n- **Bootstrap orphan audit (#4762)** — in-progress milestones with commits ahead of main are no longer skipped\n- **Unified component system** — skills, agents, pipelines, and marketplace as one component model wired through runtime, dispatch, and telemetry\n- **UnitContextManifest v2 (#4924, #4934)** — typed manifest with declarative tools-policy and typed computed artifacts; CI-guarded\n- **Composer migration phase 3 (#4782)** — `complete-slice`, `research-milestone`, `run-uat`, `reassess-roadmap` build context through the manifest composer\n- **Milestone scope classifier + pipeline variants (#4781)** — auto picks a pipeline variant from milestone shape\n- **Per-unit-type skill manifest resolver (#4779)** — skills wire into specific unit types instead of being globally on\n- **Single-writer-v3 control plane** — durable-state writer gaps closed\n- **Extensions framework** — `gsd extensions install \u002F update \u002F uninstall \u002F list \u002F info \u002F validate`; topological load order; cmux↔gsd decoupling via `cmux-events`; extracted `@gsd-extensions\u002Fgoogle-search`\n- **GPT-5.5 Codex support** + `xhigh` thinking level; auth mode in `\u002Fmodel`; permission granularity picker; headless auto default → `bypassPermissions` (#4657)\n- **Major git-safety pass** — TOCTOU ancestry guard, atomic sync-lock with PID-verified stale override, `.git\u002Findex.lock` 5-min gate, env overlay strip, rebase\u002Fcherry-pick\u002Frevert detection, working-tree stash before `reset --hard`, unborn-branch worktree guard, user hooks + `commit.gpgsign` on auto-commits\n- **Atomic `.gsd\u002F` state writes**; **compaction correctness fix (#4665)**; **write-gate hardening (#4950)**; **auto state-machine** non-retriable policy errors (#4973), baseline restoration (#4961, #4966); slice + crash recovery; empty-turn recovery shape canonicalized\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.77 highlights\u003C\u002Fsummary>\n\n- **Context Mode** — dispatch builds task-ready context automatically (artifacts, prior session, milestone\u002Fslice signals, execution metadata); enabled by default for new projects\n- **Sandboxed execution tools** — `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output paths for context-mode flows\n- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; decisions and KNOWLEDGE patterns\u002Flessons are memory-backed projections after the cutover\n- **Skill coverage** — 9 gap-closing skills landed plus 6 planning\u002Fdesign skills surfaced\n- **Hook stack** — Layer 0 shell hooks and additional Layer 2 lifecycle events\n- **TUI polish** — dedicated chat-frame style for skill invocations; active-row overflow fixes\n- **Worktree + dispatch resilience** — crash-recovery dispatch hardened, safer path derivation, improved worktree context fallback\n- **DB\u002Fschema guardrails** — migration\u002Findex ordering and schema version stamping tightened\n- **Preflight hardening** — milestone completion enforces stricter clean-root checks with auto-stash\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.75 highlights\u003C\u002Fsummary>\n\n- **Knowledge graph system** — structured knowledge graph built from project artifacts\n- **`\u002Fgsd extract-learnings`** — extracts decisions, lessons, patterns, and surprises into `LEARNINGS.md`\n- **Unified Orchestration Kernel (UOK)** — now the default execution path with plan-v2 compile gates and reactive\u002Fparallel scheduling\n- **GSD Extension API** — third-party extensions loadable from `.gsd\u002Fextensions\u002F` (#3338)\n- **v1 command parity** — 12 missing commands added, closing the migration gap\n- **Chat frame redesign** — unified styling for compaction notices, tool cards, and chat frame with timestamps and model headers\n- **Single-writer DB invariant** — engine database enforces single-writer to prevent corruption\n- **MCP worktree routing** — tool writes routed to active worktree; worktree paths accepted in project root guard\n- **Alibaba DashScope** — added as a standalone provider (#3891)\n- **Persistent language preference** — `\u002Fgsd language`\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.74 highlights\u003C\u002Fsummary>\n\n- **DB-authoritative milestone completeness** — milestone completion state is derived from the database, not file markers (#4179)\n- **Flat-rate provider detection** — extended to custom and externalCli providers\n- **Thinking level as effort** — Claude Code passes thinking level as an effort parameter\n- **False milestone merge prevention** — auto-mode no longer falsely merges after a `complete-milestone` failure (#4175)\n- **Premature auto-stop fix** — prevents auto-mode from stopping early on blocked phase + missing reassessment\n- **Inline tool call rendering** — assistant tool calls render inline with text instead of grouped at the end\n- **Custom model preservation** — custom model selection preserved on `\u002Fgsd auto` bootstrap (#4122)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.73 highlights\u003C\u002Fsummary>\n\n- **Alibaba DashScope provider** — added as a standalone provider (#3891)\n- **Layered depth enforcement** — discuss phase enforces depth gates for thorough requirements gathering (#4079)\n- **Memory pressure watchdog** — stuck detection state persisted across sessions (#3708)\n- **Ollama cloud auth** — cloud auth support and real context window resolution via `\u002Fapi\u002Fshow` (#4017)\n- **DB corruption prevention** — direct writes to `gsd.db` blocked via hooks (#3674)\n- **Circular dependency cleanup** — 3 circular dependencies broken in extension modules (#3730)\n- **Subagent permissions** — GSD subagents default to `bypassPermissions` with safe built-ins pre-authorized\n- **Security hardening** — auth middleware activated, shutdown\u002Fupdate routes hardened (#4023)\n- **Stale slice reconciliation** — stale slice rows reconciled and STATE.md rebuilt before DB close (#3658)\n- **Subagent model preference** — `subagent_model` preference wired through to dispatch prompt builders\n- **Pipeline integrity** — 5 pipeline issues addressed from release audit, package-lock.json regenerated during bumps\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.72 highlights\u003C\u002Fsummary>\n\n- **8 specialist subagents** — new specialist subagents and slim pro agents with GSD phase guard to prevent conflicts\n- **Model selection hardening** — unconfigured models blocked from selection, provider readiness required, session override honored\n- **Auto-mode resilience** — credential cooldown recovery with bounded retry budget, fire-and-forget auto start, scoped forensics\n- **TUI overhaul** — overlays, keyboard shortcuts, and notification flows redesigned for consistency\n- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction\n- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths\n- **Anti-fabrication guardrails** — discuss prompts enforce turn-taking to prevent fabricated user responses\n- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI\n- **MCP reliability** — every registered tool exposed, SDK subpath resolution fixed, abort signals threaded through\n- **Tool cache control** — `cache_control` breakpoints added to tool definitions for improved prompt caching\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.71 highlights\u003C\u002Fsummary>\n\n- **Secure credential collection over MCP** — `secure_env_collect` tool uses MCP form elicitation to collect secrets without exposing values in tool output\n- **MCP stream ordering** — tool output renders in correct order, fixing interleaved output in Claude Code and other MCP clients\n- **isError flag propagation** — workflow tool execution failures correctly return `isError: true`\n- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates\n- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking fixed with atomic lock acquisition\n- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers\n- **Pinned output fixes** — restored above editor during tool execution, cleared on turn completion\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>v2.70 and earlier\u003C\u002Fsummary>\n\n- **Full workflow over MCP (v2.68)** — slice replanning, milestone management, slice completion, task completion, and core planning tools exposed over MCP\n- **Transport-gated MCP (v2.68)** — workflow tool availability adapts to provider transport capabilities automatically\n- **Contextual tips system (v2.68)** — TUI and web terminal surface contextual tips based on workflow state\n- **Ask user questions over MCP (v2.70)** — interactive questions exposed via elicitation for external integrations\n- **Tiered Context Injection (M005)** — relevance-scoped context with 65%+ token reduction\n- **5-wave state machine hardening** — critical data integrity fixes across atomic writes, event log reconciliation, session recovery\n- **Slice-level parallelism** — dependency-aware parallel dispatch within a milestone\n- **MCP server** — 6 read-only project state tools for external integrations, auto-wrapup guard, and question dedup\n- **Ollama extension** — first-class local LLM support via Ollama, with dynamic routing enabled by default\n- **VS Code sidebar redesign** — SCM provider, checkpoints, diagnostics panel, activity feed, workflow controls, session forking\n- **Skills overhaul** — 30+ skill packs covering major frameworks, databases, and cloud platforms\n- **Single-writer state engine** — disciplined state transitions with machine guards and TOCTOU hardening\n- **DB-backed planning tools** — atomic SQLite tool calls for state transitions\n- **Declarative workflow engine** — YAML workflows through auto-loop\n- **Doctor: worktree lifecycle checks** — validates worktree health, detects orphans, consolidates cleanup\n\n\u003C\u002Fdetails>\n\n---\n\n## Documentation\n\nFull documentation is in the [`docs\u002F`](.\u002Fdocs\u002F) directory:\n\n### User Guides\n\n- **[Getting Started](.\u002Fdocs\u002Fuser-docs\u002Fgetting-started.md)** — install, first run, basic usage\n- **[Auto Mode](.\u002Fdocs\u002Fuser-docs\u002Fauto-mode.md)** — autonomous execution deep-dive\n- **[Configuration](.\u002Fdocs\u002Fuser-docs\u002Fconfiguration.md)** — all preferences, models, git, and hooks\n- **[Custom Models](.\u002Fdocs\u002Fuser-docs\u002Fcustom-models.md)** — add custom providers (Ollama, vLLM, LM Studio, proxies)\n- **[Token Optimization](.\u002Fdocs\u002Fuser-docs\u002Ftoken-optimization.md)** — profiles, context compression, complexity routing\n- **[Cost Management](.\u002Fdocs\u002Fuser-docs\u002Fcost-management.md)** — budgets, tracking, projections\n- **[Git Strategy](.\u002Fdocs\u002Fuser-docs\u002Fgit-strategy.md)** — worktree isolation, branching, merge behavior\n- **[Parallel Orchestration](.\u002Fdocs\u002Fuser-docs\u002Fparallel-orchestration.md)** — run multiple milestones simultaneously\n- **[Working in Teams](.\u002Fdocs\u002Fuser-docs\u002Fworking-in-teams.md)** — unique IDs, shared artifacts\n- **[Skills](.\u002Fdocs\u002Fuser-docs\u002Fskills.md)** — bundled skills, discovery, custom authoring\n- **[Commands Reference](.\u002Fdocs\u002Fuser-docs\u002Fcommands.md)** — all commands and keyboard shortcuts\n- **[Troubleshooting](.\u002Fdocs\u002Fuser-docs\u002Ftroubleshooting.md)** — common issues, doctor, forensics, recovery\n- **[Visualizer](.\u002Fdocs\u002Fuser-docs\u002Fvisualizer.md)** — workflow visualizer with stats and discussion status\n- **[Remote Questions](.\u002Fdocs\u002Fuser-docs\u002Fremote-questions.md)** — route decisions to Slack or Discord when human input is needed\n- **[Dynamic Model Routing](.\u002Fdocs\u002Fuser-docs\u002Fdynamic-model-routing.md)** — complexity-based model selection and budget pressure\n- **[Web Interface](.\u002Fdocs\u002Fuser-docs\u002Fweb-interface.md)** — browser-based project management and real-time progress\n- **[Migration from v1](.\u002Fdocs\u002Fuser-docs\u002Fmigration.md)** — `.planning` → `.gsd` migration\n- **[Docker Sandbox](.\u002Fdocker\u002FREADME.md)** — run GSD auto mode in an isolated Docker container\n\n### Developer Docs\n\n- **[Architecture](.\u002Fdocs\u002Fdev\u002Farchitecture.md)** — system design and dispatch pipeline\n- **[CI\u002FCD Pipeline](.\u002Fdocs\u002Fdev\u002Fci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)\n- **[E2E Testing](.\u002Ftests\u002Fe2e\u002FREADME.md)** — real-process CLI\u002Fruntime coverage and CI runner expectations\n- **[Pipeline Simplification (ADR-003)](.\u002Fdocs\u002Fdev\u002FADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion\n- **[VS Code Extension](.\u002Fvscode-extension\u002FREADME.md)** — chat participant, sidebar dashboard, RPC integration\n\n---\n\n## What Changed From v1\n\nThe original GSD was a collection of markdown prompts installed into `~\u002F.claude\u002Fcommands\u002F`. It relied entirely on the LLM reading those prompts and doing the right thing. That worked surprisingly well — but it had hard limits:\n\n- **No context control.** The LLM accumulated garbage over a long session. Quality degraded.\n- **No real automation.** \"Auto mode\" was the LLM calling itself in a loop, burning context on orchestration overhead.\n- **No crash recovery.** If the session died mid-task, you started over.\n- **No observability.** No cost tracking, no progress dashboard, no stuck detection.\n\nGSD v2 solves all of these because it's not a prompt framework anymore — it's a TypeScript application that _controls_ the agent session.\n\n|                      | v1 (Prompt Framework)        | v2 (Agent Application)                                  |\n| -------------------- | ---------------------------- | ------------------------------------------------------- |\n| Runtime              | Claude Code slash commands   | Standalone CLI via Pi SDK                               |\n| Context management   | Hope the LLM doesn't fill up | Fresh session per task, programmatic                    |\n| Auto mode            | LLM self-loop                | State machine reading `.gsd\u002F` files                     |\n| Crash recovery       | None                         | Lock files + session forensics                          |\n| Git strategy         | LLM writes git commands      | Worktree isolation, sequential commits, squash merge    |\n| Cost tracking        | None                         | Per-unit token\u002Fcost ledger with dashboard               |\n| Stuck detection      | None                         | Retry once, then stop with diagnostics                  |\n| Timeout supervision  | None                         | Soft\u002Fidle\u002Fhard timeouts with recovery steering          |\n| Context injection    | \"Read this file\"             | Pre-inlined into dispatch prompt                        |\n| Roadmap reassessment | Manual                       | Automatic after each slice completes                    |\n| Skill discovery      | None                         | Auto-detect and install relevant skills during research |\n| Verification         | Manual                       | Automated verification commands with auto-fix retries   |\n| Reporting            | None                         | Self-contained HTML reports with metrics and dep graphs |\n| Parallel execution   | None                         | Multi-worker parallel milestone orchestration           |\n\n### Migrating from v1\n\n> **Note:** Migration works best with a `ROADMAP.md` file for milestone structure. Without one, milestones are inferred from the `phases\u002F` directory.\n\nIf you have projects with `.planning` directories from the original Get Shit Done, you can migrate them to GSD-2's `.gsd` format:\n\n```bash\n# From within the project directory\n\u002Fgsd migrate\n\n# Or specify a path\n\u002Fgsd migrate ~\u002Fprojects\u002Fmy-old-project\n```\n\nThe migration tool:\n\n- Parses your old `PROJECT.md`, `ROADMAP.md`, `REQUIREMENTS.md`, phase directories, plans, summaries, and research\n- Maps phases → slices, plans → tasks, milestones → milestones\n- Preserves completion state (`[x]` phases stay done, summaries carry over)\n- Consolidates research files into the new structure\n- Shows a preview before writing anything\n- Optionally runs an agent-driven review of the output for quality assurance\n\nSupports format variations including milestone-sectioned roadmaps with `\u003Cdetails>` blocks, bold phase entries, bullet-format requirements, decimal phase numbering, and duplicate phase numbers across milestones.\n\n---\n\n## How It Works\n\nGSD structures work into a hierarchy:\n\n```\nMilestone  →  a shippable version (4-10 slices)\n  Slice    →  one demoable vertical capability (1-7 tasks)\n    Task   →  one context-window-sized unit of work\n```\n\nThe iron rule: **a task must fit in one context window.** If it can't, it's two tasks.\n\n### The Loop\n\nEach slice flows through phases automatically:\n\n```\nPlan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice\n                                                                                      ↓ (all slices done)\n                                                                              Validate Milestone → Complete Milestone\n```\n\n**Plan** scouts the codebase, researches relevant docs, and 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, then runs configured verification commands (lint, test, etc.) with auto-fix retries before the task closeout commit or snapshot is published. Failed or incomplete verification blocks execute-task closeout. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **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.\n\nWhen progressive planning is enabled, the first slice is fully planned up front while later slices may appear in `M###-ROADMAP.md` with a `` `[sketch]` `` badge. A sketch slice has an approved title, dependency shape, demo line, and scope boundary, but it has not yet been expanded into task plans; auto mode runs `refine-slice` just before execution to turn the sketch into a full slice plan using the latest prior-slice summaries.\n\n### `\u002Fgsd auto` — The Main Event\n\nThis is what makes GSD different. Run it, walk away, come back to built software.\n\n```\n\u002Fgsd auto\n```\n\nAuto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, 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 persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.\n\nThe database is authoritative for milestones, slices, tasks, requirements, summaries, and completion status. Durable decisions and project knowledge are stored in the `memories` table: decisions are `architecture` memories, and KNOWLEDGE patterns\u002Flessons are `pattern`\u002F`gotcha` memories. Markdown under `.gsd\u002F` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery\u002Fimport command. In worktree mode, artifact\u002Fprojection writes are rendered under the active worktree-local `.gsd\u002F`, while the project-root DB remains authoritative runtime state.\n\n`KNOWLEDGE.md` is hybrid: rules remain file-canonical, while patterns and lessons are stored in the `memories` table and rendered back into `KNOWLEDGE.md` on the next session-start projection. Existing pattern and lesson rows are backfilled into memories before projection, so newly captured patterns and lessons may appear in memory-backed prompt context before the file view refreshes.\n\n**What happens under the hood:**\n\n1. **Fresh session per unit** — Every task, every research phase, every planning step gets a clean 200k-token context window. No accumulated garbage. No \"I'll be more concise now.\"\n\n2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.\n\n3. **Context Mode** — Context Mode is enabled by default and gives eligible auto-mode units guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; capped stdout\u002Fstderr and metadata are saved under `.gsd\u002Fexec\u002F` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads a prior compaction snapshot from `.gsd\u002Flast-snapshot.md` when one exists. Opt out with `context_mode.enabled: false` to disable Context Mode guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume`; tune sandbox timeout\u002Foutput caps and environment forwarding with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, `context_mode.exec_digest_chars`, and `context_mode.exec_env_allowlist`.\n\n4. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone\u002F\u003CMID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.\n\n5. **Crash recovery** — Auto mode persists worker state, unit-dispatch state, and paused-session metadata in the project-root SQLite database. If the session dies, the next `\u002Fgsd auto` reconstructs the interrupted unit from DB-backed runtime state, reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator IPC still lives under `.gsd\u002Fparallel\u002F`, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).\n\n6. **Provider error recovery** — Transient provider errors (rate limits, 500\u002F503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.\n\n7. **Stuck and artifact detection** — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). Missing expected artifacts use a separate bounded path: GSD retries artifact verification up to 3 times with failure context, then pauses auto mode with the missing artifact error instead of looping indefinitely.\n\n8. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout starts recovery and only pauses auto mode if durable progress cannot be made. Runtime progress is recorded under `.gsd\u002Fruntime\u002F`, and journal events close out unit, finalize, and iteration phases for later forensics.\n\n9. **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.\n\n10. **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.\n\n11. **Verification enforcement** — Configure simple executable commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Verification commands must not use shell composition or control syntax such as pipes, redirects, semicolons, backticks, or command substitution. Failures trigger auto-fix retries before advancing. Execute-task commits and snapshots are deferred until verification passes; failed or incomplete verification blocks closeout instead of publishing changes. Auto-discovered checks from `package.json` and Python pytest project markers (`python-project`) run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.\n\n12. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.\n\n13. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `\u002Fgsd auto` to resume from disk state.\n\n### `\u002Fgsd` and `\u002Fgsd next` — Step Mode\n\nBy default, `\u002Fgsd` runs in **step mode**: the same state machine as auto mode, but it pauses between units with a wizard showing what completed and what's next. You advance one step at a time, review the output, and continue when ready.\n\n- **No `.gsd\u002F` directory** → Start a new project. Discussion flow captures your vision, constraints, and preferences.\n- **Milestone exists, no roadmap** → Discuss or research the milestone.\n- **Roadmap exists, slices pending** → Plan the next slice, execute one task, or switch to auto.\n- **Mid-task** → Resume from where you left off.\n\n`\u002Fgsd next` is an explicit alias for step mode. You can switch from step → auto mid-session via the wizard.\n\nStep mode is the on-ramp. Auto mode is the highway.\n\n---\n\n## Getting Started\n\n### Install\n\n```bash\nnpm install -g gsd-pi\n```\n\n### Log in to a provider\n\nFirst, choose your LLM provider:\n\n```bash\ngsd\n\u002Flogin\n```\n\nSelect from 20+ providers — Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, and more. If you have a Claude Max or Copilot subscription, the OAuth flow handles everything. Otherwise, paste your API key when prompted.\n\nGSD auto-selects a default model after login. To switch models later:\n\n```bash\n\u002Fmodel\n```\n\n### Use it\n\nOpen a terminal in your project and run:\n\n```bash\ngsd\n```\n\nGSD opens an interactive agent session. From there, you have two ways to work:\n\n**`\u002Fgsd` — step mode.** Type `\u002Fgsd` and GSD executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next. Same state machine as auto mode, but you stay in the loop. No project yet? It starts the discussion flow. Roadmap exists? It plans or executes the next step.\n\n**`\u002Fgsd auto` — autonomous mode.** Type `\u002Fgsd auto` and walk away. GSD researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. Fresh context window per task. No babysitting.\n\n### Two terminals, one project\n\nThe real workflow: run auto mode in one terminal, steer from another.\n\n**Terminal 1 — let it build**\n\n```bash\ngsd\n\u002Fgsd auto\n```\n\n**Terminal 2 — steer while it works**\n\n```bash\ngsd\n\u002Fgsd discuss    # talk through architecture decisions\n\u002Fgsd status     # check progress\n\u002Fgsd queue      # queue the next milestone\n```\n\nBoth terminals coordinate through the same project-root GSD runtime on local disk. The SQLite database is authoritative, `.gsd\u002F` markdown is refreshed from it, and your decisions in terminal 2 are picked up at the next phase boundary without stopping auto mode.\n\n### Headless mode — CI and scripts\n\n`gsd headless` runs any `\u002Fgsd` command without a TUI. Designed for CI pipelines, cron jobs, and scripted automation.\n\n```bash\n# Run auto mode in CI\ngsd headless --timeout 600000\n\n# Create and execute a milestone end-to-end\ngsd headless new-milestone --context spec.md --auto\n\n# One unit at a time (cron-friendly)\ngsd headless next\n\n# Instant JSON snapshot (no LLM, ~50ms)\ngsd headless query\n\n# Force a specific pipeline phase\ngsd headless dispatch plan\n```\n\nHeadless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error\u002Ftimeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `gsd headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](.\u002Fdocs\u002Fuser-docs\u002Fremote-questions.md) to route decisions to Slack or Discord when human input is needed.\n\n**Multi-session orchestration** — headless mode supports DB-backed coordination across multiple GSD workers on the same machine. Worker registration, milestone leases, unit dispatch tracking, and command delivery live in `.gsd\u002Fgsd.db`, while `.gsd\u002Fparallel\u002F` remains a local runtime area for per-milestone locks and isolation artifacts.\n\n### First launch\n\nOn first run, GSD launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. If you have an existing Pi installation, your provider credentials (LLM and tool keys) are imported automatically. Run `gsd config` anytime to re-run the wizard.\n\n### Commands\n\n| Command                 | What it does                                                                  |\n| ----------------------- | ----------------------------------------------------------------------------- |\n| `\u002Fgsd`                  | Step mode — executes one unit at a time, pauses between each                  |\n| `\u002Fgsd next`             | Explicit step mode (same as bare `\u002Fgsd`)                                      |\n| `\u002Fgsd auto`             | Autonomous mode — researches, plans, executes, commits, repeats               |\n| `\u002Fgsd new-project [--deep]` | Bootstrap a project with staged project-level discovery                  |\n| `\u002Fgsd quick`            | Execute a quick task with GSD guarantees, skip planning overhead              |\n| `\u002Fgsd stop`             | Stop auto mode gracefully                                                     |\n| `\u002Fgsd steer`            | Hard-steer plan documents during execution                                    |\n| `\u002Fgsd discuss`          | Discuss architecture and decisions (works alongside auto mode)                |\n| `\u002Fgsd rethink`          | Conversational project reorganization                                         |\n| `\u002Fgsd mcp`              | MCP server status and connectivity                                            |\n| `\u002Fgsd status`           | Progress dashboard                                                            |\n| `\u002Fgsd brief \u003Cmode>`     | Generate a visual HTML brief (diagram, plan, diff, recap, table, slides)      |\n| `\u002Fgsd queue`            | Queue\u002Freorder future milestones (`pending`, `queued`, or legacy `planned`; safe during auto mode) |\n| `\u002Fgsd prefs`            | Model selection, timeouts, budget ceiling                                     |\n| `\u002Fgsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format                           |\n| `\u002Fgsd help`             | Categorized command reference for all GSD subcommands                         |\n| `\u002Fgsd mode`             | Switch workflow mode (solo\u002Fteam) with coordinated defaults                    |\n| `\u002Fgsd workflow`         | Unified workflow plugins — list, run `\u003Cname>`, install, info, validate        |\n| `\u002Fgsd start \u003Ctemplate>` | Launch a bundled or custom workflow template (bugfix, release, etc.)          |\n| `\u002Fgsd forensics`        | Full-access GSD debugger for auto-mode failure investigation                  |\n| `\u002Fgsd cleanup`          | Archive phase directories from completed milestones                           |\n| `\u002Fgsd doctor`           | Runtime health checks — issues surface across widget, visualizer, and reports |\n| `\u002Fgsd keys`             | API key manager — list, add, remove, test, rotate, doctor                     |\n| `\u002Fgsd logs`             | Browse activity, debug, and metrics logs                                      |\n| `\u002Fgsd export --html`    | Generate HTML report for current or completed milestone                       |\n| `\u002Fworktree` (`\u002Fwt`)     | Git worktree lifecycle — create, switch, merge, remove                        |\n| `\u002Fgsd worktree` (`\u002Fgsd wt`) | TUI worktree management — list, merge, clean, remove with safety checks   |\n| `\u002Fvoice`                | Toggle real-time speech-to-text (macOS, Linux)                                |\n| `\u002Fexit`                 | Graceful shutdown — saves session state before exiting                        |\n| `\u002Fkill`                 | Kill GSD process immediately                                                  |\n| `\u002Fclear`                | Start a new session (alias for `\u002Fnew`)                                        |\n| `Ctrl+Alt+G`            | Toggle dashboard overlay                                                      |\n| `Ctrl+Alt+V`            | Toggle voice transcription                                                    |\n| `Ctrl+Alt+B`            | Show background shell processes                                               |\n| `Alt+V`                 | Paste clipboard image (macOS)                                                 |\n| `gsd config`            | Re-run the setup wizard (LLM provider + tool keys)                            |\n| `gsd update`            | Update GSD to the latest version                                              |\n| `gsd headless [cmd]`    | Run `\u002Fgsd` commands without TUI (CI, cron, scripts)                           |\n| `gsd headless query`    | Instant JSON snapshot — state, next dispatch, costs (no LLM)                  |\n| `gsd --continue` (`-c`) | Resume the most recent session for the current directory                      |\n| `gsd --worktree` (`-w`) | Launch an isolated worktree session for the active milestone                  |\n| `gsd sessions`          | Interactive session picker — browse and resume any saved session              |\n\n---\n\n## What GSD Manages For You\n\n### Context Engineering\n\nEvery dispatch is carefully constructed. The LLM never wastes tool calls on orientation.\n\n| Artifact           | Purpose                                                         |\n| ------------------ | --------------------------------------------------------------- |\n| `gsd.db`           | Authoritative runtime state for hierarchy and completion        |\n| `PROJECT.md`       | Living doc — what the project is right now                      |\n| `REQUIREMENTS.md`  | Project-level capability contract and out-of-scope list         |\n| `DECISIONS.md`     | Projected register of memory-backed architectural decisions     |\n| `KNOWLEDGE.md`     | Hybrid knowledge projection: manual Rules plus memory-backed Patterns\u002FLessons |\n| `RUNTIME.md`       | Runtime context — API endpoints, env vars, services (v2.39)     |\n| `runtime\u002Fresearch-decision.json` | Deep-mode marker for project research vs skip       |\n| `research\u002F*.md`    | Optional deep-mode project research: stack, features, architecture, pitfalls |\n| `STATE.md`         | Quick-glance dashboard rendered from the database                |\n| `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies, and `` `[sketch]` `` badges for slices awaiting `refine-slice` |\n| `M001-CONTEXT.md`  | User decisions from the discuss phase                           |\n| `M001-RESEARCH.md` | Codebase and ecosystem research                                 |\n| `S01-PLAN.md`      | Slice task decomposition with must-haves                        |\n| `T01-PLAN.md`      | Individual task plan with verification criteria                 |\n| `T01-SUMMARY.md`   | What happened — YAML frontmatter + narrative                    |\n| `S01-UAT.md`       | Human test script derived from slice outcomes                   |\n\n### Git Strategy\n\nBranch-per-slice with squash merge. Fully automated.\n\n```\nmain:\n  docs(M001\u002FS04): workflow documentation and examples\n  fix(M001\u002FS03): bug fixes and doc corrections\n  feat(M001\u002FS02): API endpoints and middleware\n  feat(M001\u002FS01): data model and type system\n\ngsd\u002FM001\u002FS01 (deleted after merge):\n  feat(S01\u002FT03): file writer with round-trip fidelity\n  feat(S01\u002FT02): markdown parser for plan files\n  feat(S01\u002FT01): core types and interfaces\n```\n\nOne squash commit per milestone on main (or whichever branch you started from). The worktree is torn down after merge. Git bisect works. Individual milestones are revertable. Commit messages are generated from task summaries — no more generic \"complete task\" messages.\n\n### Verification\n\nEvery task has must-haves — mechanically checkable outcomes:\n\n- **Truths** — Observable behaviors (\"User can sign up with email\")\n- **Artifacts** — Files that must exist with real implementation, not stubs\n- **Key Links** — Imports and wiring between artifacts\n\nThe verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).\n\n### Project Knowledge\n\n`.gsd\u002FKNOWLEDGE.md` remains the human-readable register for durable project knowledge, but the memory store is now authoritative for generated Patterns and Lessons. On startup, GSD backfills existing `## Patterns` and `## Lessons Learned` rows into `gsd.db` memories, then rewrites `KNOWLEDGE.md` as a hybrid projection: the manual `## Rules` section is preserved from the file, while Patterns and Lessons are rendered from the backfilled memory rows.\n\nKeep hand-authored operating rules in `## Rules` or add them with `\u002Fgsd knowledge rule`. Patterns and Lessons that agents discover are retrieved through the memory system for prompts and projected back into `KNOWLEDGE.md` for review, reports, and git history.\n\n### Dashboard\n\n`Ctrl+Alt+G` or `\u002Fgsd status` opens a real-time overlay showing:\n\n- Current milestone, slice, and task progress\n- Auto mode elapsed time and phase\n- Per-unit cost and token breakdown by phase, slice, and model\n- Cost projections based on completed work\n- Completed and in-progress units\n\n### HTML Reports\n\nAfter a milestone completes, GSD auto-generates a self-contained HTML report in `.gsd\u002Freports\u002F`. Each report includes project summary, progress tree, slice dependency graph (SVG DAG), cost\u002Ftoken metrics with bar charts, execution timeline, changelog, and knowledge base sections. No external dependencies — all CSS and JS are inlined, printable to PDF from any browser.\n\nAn auto-generated `index.html` shows all reports with progression metrics across milestones.\n\n- **Automatic** — generated after milestone completion (configurable via `auto_report` preference)\n- **Manual** — run `\u002Fgsd export --html` anytime\n\n---\n\n## Configuration\n\n### Preferences\n\nGSD preferences live in `~\u002F.gsd\u002FPREFERENCES.md` (global) or `.gsd\u002FPREFERENCES.md` (project). Manage with `\u002Fgsd prefs`.\n\n```yaml\n---\nversion: 1\nmodels:\n  research: claude-sonnet-4-6\n  planning:\n    model: claude-opus-4-7\n    fallbacks:\n      - openrouter\u002Fz-ai\u002Fglm-5\n      - openrouter\u002Fminimax\u002Fminimax-m2.5\n  execution: claude-sonnet-4-6\n  completion: claude-sonnet-4-6\nskill_discovery: suggest\nauto_supervisor:\n  soft_timeout_minutes: 20\n  idle_timeout_minutes: 10\n  hard_timeout_minutes: 30\nbudget_ceiling: 50.00\nunique_milestone_ids: true\nverification_commands:\n  - npm run lint\n  - npm run test\nauto_report: true\n---\n```\n\n**Key settings:**\n\n| Setting                           | What it controls                                                                                      |\n| --------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| `models.*`                        | Per-phase model selection — string for a single model, or `{model, fallbacks}` for automatic failover |\n| `planning_depth`                  | `light` \u002F `deep` — opt into staged project discovery before milestone planning                         |\n| `skill_discovery`                 | `auto` \u002F `suggest` \u002F `off` — how GSD finds and applies skills                                         |\n| `auto_supervisor.*`               | Timeout thresholds for auto mode supervision                                                          |\n| `budget_ceiling`                  | USD ceiling — auto mode pauses when reached                                                           |\n| `uat_dispatch`                    | Enable automatic UAT runs after slice completion                                                      |\n| `always_use_skills`               | Skills to always load when relevant                                                                   |\n| `skill_rules`                     | Situational rules for skill routing                                                                   |\n| `skill_staleness_days`            | Skills unused for N days get deprioritized (default: 60, 0 = disabled)                                |\n| `unique_milestone_ids`            | Uses unique milestone names to avoid clashes when working in teams of people                          |\n| `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |\n| `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |\n| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable prompt guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume` |\n| `context_mode.exec_timeout_ms`    | Timeout for sandboxed `gsd_exec` runs (default: 30000)                                                |\n| `context_mode.exec_stdout_cap_bytes` | Persisted stdout cap for `gsd_exec` output (default: 1048576)                                      |\n| `context_mode.exec_digest_chars`  | Trailing stdout characters returned to the agent context (default: 300)                              |\n| `context_mode.exec_env_allowlist` | Environment variables forwarded to sandboxed `gsd_exec` runs in addition to `PATH` and `HOME`        |\n| `verification_commands`           | Array of simple executable commands to run after task execution (e.g., `[\"npm run lint\", \"npm run test\"]`); avoid pipes, redirects, semicolons, backticks, and command substitution |\n| `verification_auto_fix`           | Auto-retry on verification failures (default: true)                                                   |\n| `verification_max_retries`        | Max retries for verification failures (default: 2)                                                    |\n| `phases.require_slice_discussion` | Pause auto-mode before each slice for human discussion review                                         |\n| `auto_report`                     | Auto-generate HTML reports after milestone completion (default: true)                                 |\n\n### Agent Instructions\n\nPlace an `AGENTS.md` file in any directory to provide persistent behavioral guidance for that scope. Pi core loads `AGENTS.md` automatically (with `CLAUDE.md` as a fallback) at both user and project levels. Use these files for coding standards, architectural decisions, domain terminology, or workflow preferences.\n\n> **Note:** The legacy `agent-instructions.md` format (`~\u002F.gsd\u002Fagent-instructions.md` and `.gsd\u002Fagent-instructions.md`) is deprecated and no longer loaded. Migrate any existing instructions to `AGENTS.md` or `CLAUDE.md`.\n\n### Debug Mode\n\nStart GSD with `gsd --debug` to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting auto-mode issues.\n\n### Token Optimization\n\nGSD includes a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model tier selection, phase skipping, and context compression:\n\n```yaml\ntoken_profile: budget # or balanced (default), quality\n```\n\n| Profile    | Savings | What It Does                                                                     |\n| ---------- | ------- | -------------------------------------------------------------------------------- |\n| `budget`   | 40-60%  | Light\u002Fstandard tier defaults, skip research\u002Freassess, minimal context inlining   |\n| `balanced` | 10-20%  | Standard tier for core work, light tier for simple work, standard context        |\n| `quality`  | 0%      | Heavy tier for planning, standard tier for core work, full context               |\n\n**Complexity-based routing** automatically classifies tasks as simple\u002Fstandard\u002Fcomplex and routes to appropriate available models. Token profiles define provider-agnostic tier intentions, so simple docs tasks use a light-tier configured model and complex architectural work can use a heavy-tier configured model. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history.\n\n**Budget pressure** graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers.\n\nSee the full [Token Optimization Guide](.\u002Fdocs\u002Fuser-docs\u002Ftoken-optimization.md) for details.\n\n### Bundled Tools\n\nGSD ships with 24 extensions, all loaded automatically:\n\n| Extension              | What it provides                                                                                                                                                                                                                                                                     |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **GSD**                | Core workflow engine, auto mode, commands, dashboard                                                                                                                                                                                                                                 |\n| **Browser Tools**      | Playwright-based browser with form intelligence, intent-ranked element finding, semantic actions, PDF export, session state persistence, network mocking, device emulation, structured extraction, visual diffing, region zoom, test code generation, and prompt injection detection |\n| **Search the Web**     | Brave Search, Tavily, or Jina page extraction                                                                                                                                                                                                                                        |\n| **Google Search**      | Gemini-powered web search with AI-synthesized answers                                                                                                                                                                                                                                |\n| **Context7**           | Up-to-date library\u002Fframework documentation                                                                                                                                                                                                                                           |\n| **Background Shell**   | Long-running process management with readiness detection                                                                                                                         ","GSD 2 是一个强大的元提示、上下文工程和规范驱动开发系统，能够使代理长时间自主工作而不失去对整体目标的追踪。项目核心功能包括直接通过 TypeScript 访问代理框架，实现任务间上下文清除、文件精确注入、Git 分支管理、成本与令牌跟踪、卡顿检测及自动恢复等。特别适用于需要长时间运行且要求高度自动化处理的任务场景，如复杂软件项目的持续集成\u002F持续部署（CI\u002FCD）流程优化。基于 MIT 许可证开放，支持 macOS、Linux 和 Windows 平台。",2,"2026-06-11 03:50:45","high_star"]