{"owner":"gsd-build","repo":"get-shit-done","hasSkills":true,"totalSkillsCount":24,"totalTokensCount":53061,"categories":["root-instruction","command-prompt","project-spec","subagent-persona","anthropic-skill","copilot-instructions"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","commands/gsd/milestone-summary.md","docs/AGENTS.md","docs/ARCHITECTURE.md","docs/agents/cjs-sdk-seam.md","docs/agents/domain.md","docs/agents/issue-tracker.md","docs/agents/triage-labels.md","docs/skills/discovery-contract.md","docs/zh-CN/references/checkpoints.md","docs/zh-CN/references/continuation-format.md","docs/zh-CN/references/decimal-phase-calculation.md","docs/zh-CN/references/git-integration.md","docs/zh-CN/references/git-planning-commit.md","docs/zh-CN/references/model-profile-resolution.md","docs/zh-CN/references/model-profiles.md","docs/zh-CN/references/phase-argument-parsing.md","docs/zh-CN/references/planning-config.md","docs/zh-CN/references/questioning.md","docs/zh-CN/references/tdd.md","docs/zh-CN/references/ui-brand.md","docs/zh-CN/references/verification-patterns.md","get-shit-done/references/sketch-theme-system.md","get-shit-done/templates/copilot-instructions.md"],"skills":{"AGENTS.md":"# Repository Guidelines\n\n## Active Discussions\n\nFor current work on **Grok Build compatibility** and multi-runtime synchronization across Grok Build, Claude Code, Gemini CLI, and Codex, see:\n\n- `docs/discussions/grok-build-support-2026-05.md`\n\n## Project Structure & Module Organization\n\nThis repository ships GSD as a Node.js CLI and SDK. Root package entry points live in `bin/`, scripts in `scripts/`, runtime hooks in `hooks/`, command definitions in `commands/gsd/`, and workflow/template content in `get-shit-done/`. Agent role files are in `agents/`; docs are in `docs/`; logos and terminal images are in `assets/`. Root tests are in `tests/*.test.cjs`. The TypeScript SDK is isolated under `sdk/`, with source and Vitest tests in `sdk/src/`.\n\n## Build, Test, and Development Commands\n\nUse Node.js `>=22`.\n\n- `npm install`: install root dependencies.\n- `npm test`: builds the SDK first, then runs root `node:test` suites via `scripts/run-tests.cjs`.\n- `npm run test:coverage`: runs root tests with `c8` and enforces 70% line coverage for included CommonJS library files.\n- `npm run build:hooks`: rebuilds generated hook artifacts.\n- `npm run build:sdk`: installs SDK dependencies and builds TypeScript.\n- `cd sdk && npm test`: runs SDK Vitest unit and integration projects.\n- `cd sdk && npm run build`: type-checks and emits `sdk/dist/`.\n\n## Coding Style & Naming Conventions\n\nMatch the existing style in the edited area. Root JavaScript is CommonJS, generally strict-mode, two-space indentation, semicolons, `const`/`let`, and `node:` imports for built-ins. SDK code is strict TypeScript using ESM/`NodeNext`. Keep command, workflow, and test filenames kebab-case, for example `commands/gsd/plan-phase.md` and `tests/bug-2396-makefile-test-priority.test.cjs`. Agent files use `gsd-*.md`. Avoid unrelated formatting and unnecessary dependencies.\n\n## Testing Guidelines\n\nRoot tests use Node’s built-in `node:test` and `node:assert/strict`; do not add Jest, Mocha, or Chai. Prefer helpers from `tests/helpers.cjs` for temporary projects, cleanup, and CLI execution. Name root tests `*.test.cjs`; run one with `node --test tests/name.test.cjs`. SDK tests use Vitest with `*.test.ts` for unit tests and `*.integration.test.ts` for integration tests.\n\n## Commit & Pull Request Guidelines\n\nRecent history follows Conventional Commit prefixes such as `fix:`, `feat:`, and `ci:`, often with issue references: `fix(#2623): resolve parent .planning root...`. Keep commits scoped and descriptive.\n\nEvery PR must link an approved or confirmed issue with `Closes #123`, `Fixes #123`, or `Resolves #123`. Use the matching template in `.github/PULL_REQUEST_TEMPLATE/`. Include behavior changes, root cause when relevant, test evidence, affected platforms/runtimes, and update `CHANGELOG.md` or docs for user-facing changes.\n\n## Security & Configuration Tips\n\nDo not commit secrets, local config, or generated worktree artifacts. Before release-facing changes, run the relevant scan scripts in `scripts/`, especially `secret-scan.sh`, `base64-scan.sh`, and `prompt-injection-scan.sh`.\n","commands/gsd/milestone-summary.md":"---\ntype: prompt\nname: gsd:milestone-summary\ndescription: Generate a comprehensive project summary from milestone artifacts for team onboarding and review\nargument-hint: \"[version]\"\nallowed-tools:\n - Read\n - Write\n - Bash\n - Grep\n - Glob\n---\n\n\nGenerate a structured milestone summary for team onboarding and project review. Reads completed milestone artifacts (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION files) and produces a human-friendly overview of what was built, how, and why.\n\nPurpose: Enable new team members to understand a completed project by reading one document and asking follow-up questions.\nOutput: MILESTONE_SUMMARY written to `.planning/reports/`, presented inline, optional interactive Q&A.\n\n\n\n@~/.claude/get-shit-done/workflows/milestone-summary.md\n\n\n\n**Project files:**\n- `.planning/ROADMAP.md`\n- `.planning/PROJECT.md`\n- `.planning/STATE.md`\n- `.planning/RETROSPECTIVE.md`\n- `.planning/milestones/v{version}-ROADMAP.md` (if archived)\n- `.planning/milestones/v{version}-REQUIREMENTS.md` (if archived)\n- `.planning/phases/*-*/` (SUMMARY.md, VERIFICATION.md, CONTEXT.md, RESEARCH.md)\n\n**User input:**\n- Version: $ARGUMENTS (optional — defaults to current/latest milestone)\n\n\n\nExecute end-to-end.\n\n\n\n- Milestone version resolved (from args, STATE.md, or archive scan)\n- All available artifacts read (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION, RESEARCH, RETROSPECTIVE)\n- Summary document written to `.planning/reports/MILESTONE_SUMMARY-v{version}.md`\n- All 7 sections generated (Overview, Architecture, Phases, Decisions, Requirements, Tech Debt, Getting Started)\n- Summary presented inline to user\n- Interactive Q&A offered\n- STATE.md updated\n\n","docs/AGENTS.md":"# GSD Agent Reference\n\n> Full role cards for 21 primary agents plus concise stubs for 12 advanced/specialized agents (33 shipped agents total). The `agents/` directory and [`docs/INVENTORY.md`](INVENTORY.md) are the authoritative roster; see [Architecture](ARCHITECTURE.md) for context.\n\n---\n\n## Overview\n\nGSD uses a multi-agent architecture where thin orchestrators (workflow files) spawn specialized agents with fresh context windows. Each agent has a focused role, limited tool access, and produces specific artifacts.\n\n### Agent Categories\n\n> The table below covers the **21 primary agents** detailed in this section. Twelve additional shipped agents (pattern-mapper, debug-session-manager, code-reviewer, code-fixer, ai-researcher, domain-researcher, eval-planner, eval-auditor, framework-selector, intel-updater, doc-classifier, doc-synthesizer) have concise stubs in the [Advanced and Specialized Agents](#advanced-and-specialized-agents) section below. For the authoritative 33-agent roster, see [`docs/INVENTORY.md`](INVENTORY.md) and the `agents/` directory.\n\n| Category | Count | Agents |\n|----------|-------|--------|\n| Researchers | 3 | project-researcher, phase-researcher, ui-researcher |\n| Analyzers | 2 | assumptions-analyzer, advisor-researcher |\n| Synthesizers | 1 | research-synthesizer |\n| Planners | 1 | planner |\n| Roadmappers | 1 | roadmapper |\n| Executors | 1 | executor |\n| Checkers | 3 | plan-checker, integration-checker, ui-checker |\n| Verifiers | 1 | verifier |\n| Auditors | 3 | nyquist-auditor, ui-auditor, security-auditor |\n| Mappers | 1 | codebase-mapper |\n| Debuggers | 1 | debugger |\n| Doc Writers | 2 | doc-writer, doc-verifier |\n| Profilers | 1 | user-profiler |\n\n---\n\n## Agent Details\n\n### gsd-project-researcher\n\n**Role:** Researches domain ecosystem before roadmap creation.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project`, `/gsd-new-milestone` |\n| **Parallelism** | 4 instances (stack, features, architecture, pitfalls) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |\n\n**Capabilities:**\n- Web search for current ecosystem information\n- Context7 MCP integration for library documentation\n- Writes research documents directly to disk (reduces orchestrator context load)\n\n---\n\n### gsd-phase-researcher\n\n**Role:** Researches how to implement a specific phase before planning.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` |\n| **Parallelism** | 4 instances (same focus areas as project researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `{phase}-RESEARCH.md` |\n\n**Capabilities:**\n- Reads CONTEXT.md to focus research on user's decisions\n- Investigates implementation patterns for the specific phase domain\n- Detects test infrastructure for Nyquist validation mapping\n\n---\n\n### gsd-ui-researcher\n\n**Role:** Produces UI design contracts for frontend phases.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#E879F9` (fuchsia) |\n| **Produces** | `{phase}-UI-SPEC.md` |\n\n**Capabilities:**\n- Detects design system state (shadcn components.json, Tailwind config, existing tokens)\n- Offers shadcn initialization for React/Next.js/Vite projects\n- Asks only unanswered design contract questions\n- Enforces registry safety gate for third-party components\n\n---\n\n### gsd-assumptions-analyzer\n\n**Role:** Deeply analyzes codebase for a phase and returns structured assumptions with evidence, confidence levels, and consequences if wrong.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase-assumptions` workflow (when `workflow.discuss_mode = 'assumptions'`) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | Structured assumptions with decision statements, evidence file paths, confidence levels |\n\n**Key behaviors:**\n- Reads ROADMAP.md phase description and prior CONTEXT.md files\n- Searches codebase for files related to the phase (components, patterns, similar features)\n- Reads 5-15 most relevant source files to form evidence-based assumptions\n- Classifies confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways)\n- Flags topics that need external research (library compatibility, ecosystem best practices)\n- Output calibrated by tier: full_maturity (3-5 areas), standard (3-4), minimal_decisive (2-3)\n\n---\n\n### gsd-advisor-researcher\n\n**Role:** Researches a single gray area decision during discuss-phase advisor mode and returns a structured comparison table.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase` workflow (when ADVISOR_MODE = true) |\n| **Parallelism** | Multiple instances (one per gray area) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | 5-column comparison table (Option / Pros / Cons / Complexity / Recommendation) with rationale paragraph |\n\n**Key behaviors:**\n- Researches a single assigned gray area using Claude's knowledge, Context7, and web search\n- Produces genuinely viable options — no padding with filler alternatives\n- Complexity column uses impact surface + risk (never time estimates)\n- Recommendations are conditional (\"Rec if X\", \"Rec if Y\") — never single-winner ranking\n- Output calibrated by tier: full_maturity (3-5 options with maturity signals), standard (2-4), minimal_decisive (2 options, decisive recommendation)\n\n---\n\n### gsd-research-synthesizer\n\n**Role:** Combines outputs from parallel researchers into a unified summary.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` (after 4 researchers complete) |\n| **Parallelism** | Single instance (sequential after researchers) |\n| **Tools** | Read, Write, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `.planning/research/SUMMARY.md` |\n\n---\n\n### gsd-planner\n\n**Role:** Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase`, `/gsd-quick` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep, WebFetch, mcp (context7) |\n| **Model (balanced)** | Opus |\n| **Color** | Green |\n| **Produces** | `{phase}-{N}-PLAN.md` files |\n\n**Key behaviors:**\n- Reads PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md\n- Creates 2-3 atomic task plans sized for single context windows\n- Uses XML structure with `` elements\n- Includes `read_first` and `acceptance_criteria` sections\n- Groups plans into dependency waves\n- Performs reachability check to validate plan steps reference accessible files and APIs (v1.32)\n\n---\n\n### gsd-roadmapper\n\n**Role:** Creates project roadmaps with phase breakdown and requirement mapping.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `ROADMAP.md` |\n\n**Key behaviors:**\n- Maps requirements to phases (traceability)\n- Derives success criteria from requirements\n- Respects granularity setting for phase count\n- Validates coverage (every v1 requirement mapped to a phase)\n\n---\n\n### gsd-executor\n\n**Role:** Executes GSD plans with atomic commits, deviation handling, and checkpoint protocols.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase`, `/gsd-quick` |\n| **Parallelism** | Multiple (parallel within waves, sequential across waves) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Yellow |\n| **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` |\n\n**Key behaviors:**\n- Fresh 200K context window per plan\n- Follows XML task instructions precisely\n- Atomic git commit per completed task\n- Handles checkpoint types: auto, human-verify, decision, human-action\n- Reports deviations from plan in SUMMARY.md\n- Invokes node repair on verification failure\n\n---\n\n### gsd-plan-checker\n\n**Role:** Verifies plans will achieve phase goals before execution.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (verification loop, max 3 iterations) |\n| **Parallelism** | Single instance (iterative) |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | PASS/FAIL verdict with specific feedback |\n\n**8 Verification Dimensions:**\n1. Requirement coverage\n2. Task atomicity\n3. Dependency ordering\n4. File scope\n5. Verification commands\n6. Context fit\n7. Gap detection\n8. Nyquist compliance (when enabled)\n\n---\n\n### gsd-integration-checker\n\n**Role:** Verifies cross-phase integration and end-to-end flows.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-audit-milestone` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Blue |\n| **Produces** | Integration verification report |\n\n---\n\n### gsd-ui-checker\n\n**Role:** Validates UI-SPEC.md design contracts against quality dimensions.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` (validation loop, max 2 iterations) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#22D3EE` (cyan) |\n| **Produces** | BLOCK/FLAG/PASS verdict |\n\n---\n\n### gsd-verifier\n\n**Role:** Verifies phase goal achievement through goal-backward analysis.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase` (after all executors complete) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | `{phase}-VERIFICATION.md` |\n\n**Key behaviors:**\n- Checks codebase against phase goals, not just task completion\n- PASS/FAIL with specific evidence\n- Logs issues for `/gsd-verify-work` to address\n- Milestone scope filtering: gaps addressed in later phases are marked as \"deferred\", not reported as failures (v1.32)\n- **Test quality audit** (v1.32): verifies that tests prove what they claim by checking for disabled/skipped tests on requirements, circular test patterns (system generating its own expected values), assertion strength (existence vs. value vs. behavioral), and expected value provenance. Blockers from test quality audit override an otherwise passing verification\n\n---\n\n### gsd-nyquist-auditor\n\n**Role:** Fills Nyquist validation gaps by generating tests.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-validate-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Produces** | Test files, updated `VALIDATION.md` |\n\n**Key behaviors:**\n- Never modifies implementation code — only test files\n- Max 3 attempts per gap\n- Flags implementation bugs as escalations for user\n\n---\n\n### gsd-ui-auditor\n\n**Role:** Retroactive 6-pillar visual audit of implemented frontend code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F472B6` (pink) |\n| **Produces** | `{phase}-UI-REVIEW.md` with scores |\n\n**6 Audit Pillars (scored 1-4):**\n1. Copywriting\n2. Visuals\n3. Color\n4. Typography\n5. Spacing\n6. Experience Design\n\n---\n\n### gsd-codebase-mapper\n\n**Role:** Explores codebase and writes structured analysis documents.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase`, post-execute drift gate in `/gsd-execute-phase` |\n| **Parallelism** | 4 instances (tech, architecture, quality, concerns) |\n| **Tools** | Read, Bash, Grep, Glob, Write |\n| **Model (balanced)** | Haiku |\n| **Color** | Cyan |\n| **Produces** | `.planning/codebase/*.md` (7 documents, with `last_mapped_commit` frontmatter) |\n\n**Key behaviors:**\n- Read-only exploration + structured output\n- Writes documents directly to disk\n- No reasoning required — pattern extraction from file contents\n\n**`--paths ` scope hint (#2003):**\nAccepts an optional `--paths` directive in its prompt. When present, the\nmapper restricts Glob/Grep/Bash exploration to the listed repo-relative path\nprefixes — this is the incremental-remap path used by the post-execute\ncodebase-drift gate. Path values that contain `..`, start with `/`, or\ninclude shell metacharacters are rejected. Without the hint, the mapper\nruns its default whole-repo scan.\n\n---\n\n### gsd-debugger\n\n**Role:** Investigates bugs using scientific method with persistent state.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug`, `/gsd-verify-work` (for failures) |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | `.planning/debug/*.md`, knowledge-base updates |\n\n**Debug Session Lifecycle:**\n`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved`\n\n**Key behaviors:**\n- Tracks hypotheses, evidence, and eliminated theories\n- State persists across context resets\n- Requires human verification before marking resolved\n- Appends to persistent knowledge base on resolution\n- Consults knowledge base on new sessions\n\n---\n\n### gsd-user-profiler\n\n**Role:** Analyzes session messages across 8 behavioral dimensions to produce a scored developer profile.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-profile-user` |\n| **Parallelism** | Single instance |\n| **Tools** | Read |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `USER-PROFILE.md`, `CLAUDE.md` profile section |\n\n**Behavioral Dimensions:**\nCommunication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth.\n\n**Key behaviors:**\n- Read-only agent — analyzes extracted session data, does not modify files\n- Produces scored dimensions with confidence levels and evidence citations\n- Questionnaire fallback when session history is unavailable\n\n---\n\n### gsd-doc-writer\n\n**Role:** Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode, and project context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` |\n| **Parallelism** | Multiple instances (one per doc type) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | Project documentation files (README, architecture, API docs, etc.) |\n\n**Key behaviors:**\n- Supports modes: create, update, supplement, fix\n- Handles doc types: readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing, custom\n- Monorepo-aware: can generate per-package READMEs\n- Fix mode accepts failure objects from gsd-doc-verifier for targeted corrections\n- Writes directly to disk — does not return content to orchestrator\n\n---\n\n### gsd-doc-verifier\n\n**Role:** Verifies factual claims in generated documentation against the live codebase.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` (after doc-writer completes) |\n| **Parallelism** | Multiple instances (one per doc file) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Structured JSON verification results per doc |\n\n**Key behaviors:**\n- Extracts checkable claims (file paths, function names, CLI commands, config keys)\n- Verifies each claim against filesystem using tools only — no assumptions\n- Writes structured JSON result file for orchestrator to process\n- Failed claims feed back to doc-writer in fix mode\n\n---\n\n### gsd-security-auditor\n\n**Role:** Verifies threat mitigations from PLAN.md threat model exist in implemented code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-secure-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `{phase}-SECURITY.md` |\n\n**Key behaviors:**\n- Verifies each threat by its declared disposition (mitigate / accept / transfer)\n- Does NOT scan blindly for new vulnerabilities — verifies declared mitigations only\n- Implementation files are read-only — never patches implementation code\n- Unmitigated threats reported as OPEN_THREATS or ESCALATE\n- Supports ASVS levels 1/2/3 for verification depth\n\n---\n\n## Advanced and Specialized Agents\n\nTwelve additional agents ship under `agents/gsd-*.md` and are used by specialty workflows (`/gsd-ai-integration-phase`, `/gsd-eval-review`, `/gsd-code-review`, `/gsd-code-review --fix`, `/gsd-debug`, `/gsd-map-codebase --query`, `/gsd-ingest-docs`) and by the planner pipeline. Each carries full frontmatter in its agent file; the stubs below are concise by design. The authoritative roster (with spawner and primary-doc status per agent) lives in [`docs/INVENTORY.md`](INVENTORY.md).\n\n### gsd-pattern-mapper\n\n**Role:** Read-only codebase analysis that maps files-to-be-created or modified to their closest existing analogs, producing `PATTERNS.md` for the planner to consume.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (between research and planning) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep, Write |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `PATTERNS.md` in the phase directory |\n\n**Key behaviors:**\n- Extracts file list from CONTEXT.md and RESEARCH.md; classifies each by role (controller, component, service, model, middleware, utility, config, test) and data flow (CRUD, streaming, file I/O, event-driven, request-response)\n- Searches for the closest existing analog per file and extracts concrete code excerpts (imports, auth patterns, core pattern, error handling)\n- Strictly read-only against source; only writes `PATTERNS.md`\n\n---\n\n### gsd-debug-session-manager\n\n**Role:** Runs the full `/gsd-debug` checkpoint-and-continuation loop in an isolated context so the orchestrator's main context stays lean; spawns `gsd-debugger` agents, dispatches specialist skills, and handles user checkpoints via AskUserQuestion.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug` |\n| **Parallelism** | Single instance (interactive, stateful) |\n| **Tools** | Read, Write, Bash, Grep, Glob, Task, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Compact summary returned to main context; evolves the `.planning/debug/{slug}.md` session file |\n\n**Key behaviors:**\n- Reads the debug session file first; passes file paths (not inlined contents) to spawned agents to respect context budget\n- Treats all user-supplied AskUserQuestion content as data-only, wrapped in DATA_START/DATA_END markers\n- Coordinates TDD gates and reasoning checkpoints introduced in v1.36.0\n\n---\n\n### gsd-code-reviewer\n\n**Role:** Reviews source files for bugs, security vulnerabilities, and code-quality problems; produces a structured `REVIEW.md` with severity-classified findings.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review` |\n| **Parallelism** | Typically single instance per review scope |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | `REVIEW.md` in the phase directory |\n\n**Key behaviors:**\n- Detects bugs (logic errors, null/undefined checks, off-by-one, type mismatches, unreachable code), security issues (injection, XSS, hardcoded secrets, insecure crypto), and quality issues\n- Honors `CLAUDE.md` project conventions and `.claude/skills/` / `.agents/skills/` rules when present\n- Read-only against implementation source — never modifies code under review\n\n---\n\n### gsd-code-fixer\n\n**Role:** Applies fixes to findings from `REVIEW.md` with intelligent (non-blind) patching and atomic per-fix commits; produces `REVIEW-FIX.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review --fix` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Edit, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#10B981` (emerald) |\n| **Produces** | `REVIEW-FIX.md`; one atomic git commit per applied fix |\n\n**Key behaviors:**\n- Treats `REVIEW.md` suggestions as guidance, not a patch to apply literally\n- Commits each fix atomically so review and rollback stay granular\n- Honors `CLAUDE.md` and project-skill rules during fixes\n\n---\n\n### gsd-ai-researcher\n\n**Role:** Researches a chosen AI/LLM framework's official documentation and distills it into implementation-ready guidance — framework quick reference, patterns, and pitfalls — for the Section 3–4b body of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential with domain-researcher / eval-planner) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#34D399` (green) |\n| **Produces** | Sections 3–4b of `AI-SPEC.md` (framework quick reference + implementation guidance) |\n\n**Key behaviors:**\n- Uses Context7 MCP when available; falls back to the `ctx7` CLI via Bash when MCP tools are stripped from the agent\n- Anchors guidance to the specific use case, not generic framework overviews\n\n---\n\n### gsd-domain-researcher\n\n**Role:** Surfaces the business-domain and real-world evaluation context for an AI system — expert rubric ingredients, failure modes, regulatory context — before the eval-planner turns it into measurable rubrics. Writes Section 1b of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#A78BFA` (violet) |\n| **Produces** | Section 1b of `AI-SPEC.md` |\n\n**Key behaviors:**\n- Researches the domain, not the technical framework — its output feeds the eval-planner downstream\n- Produces rubric ingredients that downstream evaluators can turn into measurable criteria\n\n---\n\n### gsd-eval-planner\n\n**Role:** Designs the structured evaluation strategy for an AI phase — failure modes, eval dimensions with rubrics, tooling, reference dataset, guardrails, production monitoring. Writes Sections 5–7 of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential after domain-researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | Sections 5–7 of `AI-SPEC.md` (Evaluation Strategy, Guardrails, Production Monitoring) |\n\n**Required reading:** `get-shit-done/references/ai-evals.md` (evaluation framework).\n\n**Key behaviors:**\n- Turns domain-researcher rubric ingredients into measurable, tooled evaluation criteria\n- Does not re-derive domain context — reads Section 1 and 1b of `AI-SPEC.md` as established input\n\n---\n\n### gsd-eval-auditor\n\n**Role:** Retroactive audit of an implemented AI phase's evaluation coverage against its planned `AI-SPEC.md` eval strategy. Scores each eval dimension `COVERED` / `PARTIAL` / `MISSING` and produces `EVAL-REVIEW.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-eval-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `EVAL-REVIEW.md` with dimension scores, findings, and remediation guidance |\n\n**Required reading:** `get-shit-done/references/ai-evals.md`.\n\n**Key behaviors:**\n- Compares the implemented codebase against the planned eval strategy — never re-plans\n- Reads implementation files incrementally to respect context budget\n\n---\n\n### gsd-framework-selector\n\n**Role:** Interactive decision-matrix agent that runs a ≤6-question interview, scores candidate AI/LLM frameworks, and returns a ranked recommendation with rationale.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#38BDF8` (sky blue) |\n| **Produces** | Scored ranked recommendation (structured return to orchestrator) |\n\n**Required reading:** `get-shit-done/references/ai-frameworks.md` (decision matrix).\n\n**Key behaviors:**\n- Scans `package.json`, `pyproject.toml`, `requirements*.txt` for existing AI libraries before the interview to avoid recommending a rejected framework\n- Asks only what the codebase scan and CONTEXT.md have not already answered\n\n---\n\n### gsd-intel-updater\n\n**Role:** Reads project source and writes structured intel (JSON + Markdown) into `.planning/intel/`, building a queryable codebase knowledge base that other agents use instead of performing expensive fresh exploration.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase --query` (refresh / update flows) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | `.planning/intel/*.json` (and companion Markdown) consumed by `gsd-sdk query intel` |\n\n**Key behaviors:**\n- Writes current state only — no temporal language, every claim references an actual file path\n- Uses Glob / Read / Grep for cross-platform correctness; Bash is reserved for `gsd-sdk query intel` CLI calls\n\n---\n\n### gsd-doc-classifier\n\n**Role:** Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN. Extracts title, scope summary, and cross-references. Writes a JSON classification file used by `gsd-doc-synthesizer` to build a consolidated context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (parallel fan-out over the doc corpus) |\n| **Parallelism** | One instance per input document |\n| **Tools** | Read, Write, Grep, Glob |\n| **Model (balanced)** | Haiku |\n| **Color** | Yellow |\n| **Produces** | One JSON classification file per input doc (type, title, scope, refs) |\n\n**Key behaviors:**\n- Single-doc scope — never synthesizes or resolves conflicts (that is the synthesizer's job)\n- Heuristic-first classification; returns UNKNOWN when the doc lacks type signals rather than guessing\n\n---\n\n### gsd-doc-synthesizer\n\n**Role:** Synthesizes classified planning docs into a single consolidated context. Applies precedence rules, detects cross-reference cycles, enforces LOCKED-vs-LOCKED hard-blocks, and writes `INGEST-CONFLICTS.md` with three buckets (auto-resolved, competing-variants, unresolved-blockers).\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (after classifier fan-in) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Grep, Glob, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Consolidated context for `.planning/` plus `INGEST-CONFLICTS.md` report |\n\n**Key behaviors:**\n- Hard-blocks on LOCKED-vs-LOCKED ADR contradictions instead of silently picking a winner\n- Follows the `references/doc-conflict-engine.md` contract so `/gsd-import` and `/gsd-ingest-docs` produce consistent conflict reports\n\n---\n\n## Agent Tool Permissions Summary\n\n> **Scope:** this table covers the 21 primary agents only. The 12 advanced/specialized agents listed above carry their own tool surfaces in their `agents/gsd-*.md` frontmatter (summarized in the per-agent stubs above and in [`docs/INVENTORY.md`](INVENTORY.md)).\n\n| Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |\n|-------|------|-------|------|------|------|------|-----------|----------|-----|\n| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | |\n| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| research-synthesizer | ✓ | ✓ | | ✓ | | | | | |\n| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |\n| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |\n| user-profiler | ✓ | | | | | | | | |\n| doc-writer | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| doc-verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| security-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n\n**Principle of Least Privilege:**\n- Checkers are read-only (no Write/Edit) — they evaluate, never modify\n- Researchers have web access — they need current ecosystem information\n- Executors have Edit — they modify code but not web access\n- Mappers have Write — they write analysis documents but not Edit (no code changes)\n","docs/ARCHITECTURE.md":"# GSD Architecture\n\n> System architecture for contributors and advanced users. For user-facing documentation, see [Feature Reference](FEATURES.md) or [User Guide](USER-GUIDE.md).\n\n---\n\n## Table of Contents\n\n- [System Overview](#system-overview)\n- [Design Principles](#design-principles)\n- [Component Architecture](#component-architecture)\n- [Agent Model](#agent-model)\n- [Data Flow](#data-flow)\n- [File System Layout](#file-system-layout)\n- [Installer Architecture](#installer-architecture)\n- [Hook System](#hook-system)\n- [CLI Tools Layer](#cli-tools-layer)\n- [Runtime Abstraction](#runtime-abstraction)\n\n---\n\n## System Overview\n\nGSD is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:\n\n1. **Context engineering** — Structured artifacts that give the AI everything it needs per task\n2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows\n3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline\n4. **State management** — Persistent project memory across sessions and context resets\n\n```\n┌──────────────────────────────────────────────────────┐\n│ USER │\n│ /gsd-command [args] │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ COMMAND LAYER │\n│ commands/gsd/*.md — Prompt-based command files │\n│ (Claude Code custom commands / Codex skills) │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ WORKFLOW LAYER │\n│ get-shit-done/workflows/*.md — Orchestration logic │\n│ (Reads references, spawns agents, manages state) │\n└──────┬──────────────┬─────────────────┬──────────────┘\n │ │ │\n┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐\n│ AGENT │ │ AGENT │ │ AGENT │\n│ (fresh │ │ (fresh │ │ (fresh │\n│ context) │ │ context)│ │ context) │\n└──────┬──────┘ └─────┬─────┘ └────────┬───────┘\n │ │ │\n┌──────▼──────────────▼─────────────────▼──────────────┐\n│ CLI TOOLS LAYER │\n│ gsd-sdk query (sdk/src/query) + gsd-tools.cjs │\n│ Programmatic SDK bridge: GSDTools/query-runtime-bridge.ts │\n└──────────────────────┬───────────────────────────────┘\n │\n┌──────────────────────▼───────────────────────────────┐\n│ FILE SYSTEM (.planning/) │\n│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │\n│ STATE.md | config.json | phases/ | research/ │\n└──────────────────────────────────────────────────────┘\n```\n\n---\n\n## Design Principles\n\n### 1. Fresh Context Per Agent\n\nEvery agent spawned by an orchestrator gets a clean context window (up to 200K tokens). This eliminates context rot — the quality degradation that happens as an AI fills its context window with accumulated conversation.\n\n### 2. Thin Orchestrators\n\nWorkflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:\n\n- Load context via `gsd-sdk query init.` (or legacy `gsd-tools.cjs init `)\n- Spawn specialized agents with focused prompts\n- Collect results and route to the next step\n- Update state between steps\n\n### 3. File-Based State\n\nAll state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means:\n\n- State survives context resets (`/clear`)\n- State is inspectable by both humans and agents\n- State can be committed to git for team visibility\n\n### 4. Absent = Enabled\n\nWorkflow feature flags follow the **absent = enabled** pattern. If a key is missing from `config.json`, it defaults to `true`. Users explicitly disable features; they don't need to enable defaults.\n\n### 5. Defense in Depth\n\nMultiple layers prevent common failure modes:\n\n- Plans are verified before execution (plan-checker agent)\n- Execution produces atomic commits per task\n- Post-execution verification checks against phase goals\n- UAT provides human verification as final gate\n\n---\n\n## Component Architecture\n\n### Commands (`commands/gsd/*.md`)\n\nUser-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as:\n\n- **Claude Code:** Custom slash commands (hyphen form, `/gsd-command-name`)\n- **OpenCode / Kilo:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Codex:** Skills (`$gsd-command-name`)\n- **Copilot:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Gemini CLI:** Slash commands under the `gsd:` namespace (colon form, `/gsd:command-name`) — Gemini namespaces all custom commands under their plugin id, so the install path rewrites every body-text reference to colon form\n- **Antigravity:** Skills\n\n**Total commands:** see [`docs/INVENTORY.md`](INVENTORY.md#commands) for the authoritative count and full roster.\n\n#### Two-stage hierarchical routing (v1.40, [#2792](https://github.com/gsd-build/get-shit-done/issues/2792))\n\nTo keep the eager skill-listing token cost low, v1.40 introduces six namespace **meta-skills** (`gsd-workflow`, `gsd-project`, `gsd-quality`, `gsd-context`, `gsd-manage`, `gsd-ideate` — sourced from `commands/gsd/ns-*.md`, but the invocable `name:` is the bare form shown here) layered above the concrete sub-skills. The model sees 6 namespace routers (~120 tokens) instead of a flat 86-skill listing (~2,150 tokens), selects a namespace, then routes to the concrete sub-skill via a routing table embedded in the namespace router's body. Namespace skills are **additive** — every concrete command is still directly invocable.\n\nThe router descriptions use pipe-separated keyword tags (≤ 60 chars) per the Tool Attention research showing keyword-dense tags outperform prose for routing at ~40 % the token cost.\n\n#### MCP token-budget interaction\n\nThe eager skill listing is one of two recurring per-turn token costs. The other is the MCP tool schema injected by every enabled MCP server in `.claude/settings.json`. Heavyweight MCP servers (browser/playwright, Mac-tools, Windows-tools) can each cost 20 k+ tokens per turn — often dwarfing what `model_profile` tuning saves. The toggle lives in the Claude Code harness (`enabledMcpjsonServers` / `disabledMcpjsonServers` in `.claude/settings.json`) and is **not** a GSD concern. Together, the two-stage routing layer (#2792) and disciplined MCP enablement are the largest cost levers per turn. See [`docs/USER-GUIDE.md`](USER-GUIDE.md) and `references/context-budget.md` for the audit checklist.\n\n### Workflows (`get-shit-done/workflows/*.md`)\n\nOrchestration logic that commands reference. Contains the step-by-step process including:\n\n- Context loading via `gsd-sdk query` init handlers (or legacy `gsd-tools.cjs init`)\n- Agent spawn instructions with model resolution\n- Gate/checkpoint definitions\n- State update patterns\n- Error handling and recovery\n\n**Total workflows:** see [`docs/INVENTORY.md`](INVENTORY.md#workflows) for the authoritative count and full roster.\n\n#### Progressive disclosure for workflows\n\nWorkflow files are loaded verbatim into Claude's context every time the\ncorresponding `/gsd-*` command is invoked. To keep that cost bounded, the\nworkflow size budget enforced by `tests/workflow-size-budget.test.cjs`\nmirrors the agent budget from #2361:\n\n| Tier | Per-file line limit |\n|-----------|--------------------|\n| `XL` | 1700 — top-level orchestrators (`execute-phase`, `plan-phase`, `new-project`) |\n| `LARGE` | 1500 — multi-step planners and large feature workflows |\n| `DEFAULT` | 1000 — focused single-purpose workflows (the target tier) |\n\n`workflows/discuss-phase.md` is held to a stricter <500-line ceiling per\nissue #2551. When a workflow grows beyond its tier, extract per-mode bodies\ninto `workflows//modes/.md`, templates into\n`workflows//templates/`, and shared knowledge into\n`get-shit-done/references/`. The parent file becomes a thin dispatcher that\nReads only the mode and template files needed for the current invocation.\n\n`workflows/discuss-phase/` is the canonical example of this pattern —\nparent dispatches, modes/ holds per-flag behavior (`power.md`, `all.md`,\n`auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`,\n`advisor.md`), and templates/ holds CONTEXT.md, DISCUSSION-LOG.md, and\ncheckpoint.json schemas that are read only when the corresponding output\nfile is being written.\n\n### Agents (`agents/*.md`)\n\nSpecialized agent definitions with frontmatter specifying:\n\n- `name` — Agent identifier\n- `description` — Role and purpose\n- `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)\n- `color` — Terminal output color for visual distinction\n\n**Total agents:** 33\n\n### References (`get-shit-done/references/*.md`)\n\nShared knowledge documents that workflows and agents `@-reference` (see [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) for the authoritative count and full roster):\n\n**Core references:**\n\n- `checkpoints.md` — Checkpoint type definitions and interaction patterns\n- `gates.md` — 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier\n- `model-profiles.md` — Per-agent model tier assignments\n- `model-profile-resolution.md` — Model resolution algorithm documentation\n- `verification-patterns.md` — How to verify different artifact types\n- `verification-overrides.md` — Per-artifact verification override rules\n- `planning-config.md` — Full config schema and behavior\n- `git-integration.md` — Git commit, branching, and history patterns\n- `git-planning-commit.md` — Planning directory commit conventions\n- `questioning.md` — Dream extraction philosophy for project initialization\n- `tdd.md` — Test-driven development integration patterns\n- `ui-brand.md` — Visual output formatting patterns\n- `common-bug-patterns.md` — Common bug patterns for code review and verification\n\n**Workflow references:**\n\n- `agent-contracts.md` — Formal interface between orchestrators and agents\n- `context-budget.md` — Context window budget allocation rules\n- `continuation-format.md` — Session continuation/resume format\n- `domain-probes.md` — Domain-specific probing questions for discuss-phase\n- `gate-prompts.md` — Gate/checkpoint prompt templates\n- `revision-loop.md` — Plan revision iteration patterns\n- `universal-anti-patterns.md` — Common anti-patterns to detect and avoid\n- `artifact-types.md` — Planning artifact type definitions\n- `phase-argument-parsing.md` — Phase argument parsing conventions\n- `decimal-phase-calculation.md` — Decimal sub-phase numbering rules\n- `workstream-flag.md` — Workstream active pointer conventions\n- `user-profiling.md` — User behavioral profiling methodology\n- `thinking-partner.md` — Conditional thinking partner activation at decision points\n\n**Thinking model references:**\n\nReferences for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows:\n\n- `thinking-models-debug.md` — Thinking model patterns for debugging workflows\n- `thinking-models-execution.md` — Thinking model patterns for execution agents\n- `thinking-models-planning.md` — Thinking model patterns for planning agents\n- `thinking-models-research.md` — Thinking model patterns for research agents\n- `thinking-models-verification.md` — Thinking model patterns for verification agents\n\n**Modular planner decomposition:**\n\nThe planner agent (`agents/gsd-planner.md`) was decomposed from a single monolithic file into a core agent plus reference modules to stay under the 50K character limit imposed by some runtimes:\n\n- `planner-gap-closure.md` — Gap closure mode behavior (reads VERIFICATION.md, targeted replanning)\n- `planner-reviews.md` — Cross-AI review integration (reads REVIEWS.md from `/gsd-review`)\n- `planner-revision.md` — Plan revision patterns for iterative refinement\n\n### Templates (`get-shit-done/templates/`)\n\nMarkdown templates for all planning artifacts. Used by `gsd-sdk query template.fill` / `phase.scaffold` (and legacy `gsd-tools.cjs template fill` / top-level `scaffold`) to create pre-structured files:\n- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files\n- `phase-prompt.md` — Phase execution prompt template\n- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates\n- `DEBUG.md` — Debug session tracking template\n- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Specialized verification templates\n- `discussion-log.md` — Discussion audit trail template\n- `codebase/` — Brownfield mapping templates (stack, architecture, conventions, concerns, structure, testing, integrations)\n- `research-project/` — Research output templates (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)\n\n### Hooks (`hooks/`)\n\nRuntime hooks that integrate with the host AI agent:\n\n| Hook | Event | Purpose |\n|------|-------|---------|\n| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar |\n| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining |\n| `gsd-check-update.js` | `SessionStart` | Foreground trigger for the background update check |\n| `gsd-check-update-worker.js` | (helper) | Background worker spawned by `gsd-check-update.js`; no direct event registration |\n| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) |\n| `gsd-read-injection-scanner.js` | `PostToolUse` | Scans Read tool output for injected instructions in untrusted content |\n| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |\n| `gsd-read-guard.js` | `PreToolUse` | Advisory guard preventing Edit/Write on files not yet read in the session |\n| `gsd-session-state.sh` | `PostToolUse` | Session state tracking for shell-based runtimes |\n| `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional commit enforcement |\n| `gsd-phase-boundary.sh` | `PostToolUse` | Phase boundary detection for workflow transitions |\n\nSee [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 11-hook roster.\n\n### SDK Runtime Bridge Module (`sdk/src/query-runtime-bridge.ts`)\n\nProgrammatic SDK callers (`GSDTools`) route through one seam that owns query dispatch policy:\n\n- Native registry dispatch preference\n- Explicit subprocess fallback policy (`allowFallbackToSubprocess`)\n- Strict SDK mode (`strictSdk`) for fail-fast native-only enforcement\n- Structured dispatch observability (`onDispatchEvent`) with mode, reason, duration, and outcome\n\nThis keeps callers thin adapters and centralizes transport decisions for SDK publishability.\n\n### Command Routing Hub (`get-shit-done/bin/lib/command-routing-hub.cjs`)\n\nCJS command family routers migrate to dispatch through `CommandRoutingHub` incrementally. `phase-command-router.cjs` is the first migration (issue #3788); remaining routers (`phases-command-router.cjs`, `roadmap-command-router.cjs`, etc.) continue using `routeCjsCommandFamily` until migrated in follow-up issues. The hub owns three cross-cutting concerns that each router previously duplicated: (1) mode selection (`sdk` when `tryLoadSdk()` succeeds and no `GSD_WORKSTREAM` is active, `cjs` otherwise), set once at construction; (2) a no-throw pure-result contract (`hub.dispatch()` catches all exceptions and returns `{ ok: false, errorKind, message, details }` instead of propagating); and (3) a closed six-value `errorKind` enum exported as the frozen `ERROR_KINDS` object. Router adapters remain thin CLI translators — they build the hub, call `dispatch`, then map the Result to `output()`/`error()` calls. No transparent SDK→CJS fallback: an SDK-mode hub that encounters a load or dispatch failure returns `SdkLoadFailed` or `SdkDispatchFailed` without retrying via CJS. See `docs/adr/0012-command-routing-hub.md`.\n\n### CLI Tools (`get-shit-done/bin/`)\n\nNode.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) for the authoritative roster):\n\n\n| Module | Responsibility |\n| ---------------------- | --------------------------------------------------------------------------------------------------- |\n| `core.cjs` | Error handling, output formatting, shared utilities; compatibility re-exports for planning helpers |\n| `planning-workspace.cjs` | Planning seam (`planningDir`, `planningPaths`, active workstream routing, `.planning/.lock`) |\n| `state.cjs` | STATE.md parsing, updating, progression, metrics |\n| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |\n| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |\n| `config.cjs` | config.json read/write, section initialization |\n| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |\n| `template.cjs` | Template selection and filling with variable substitution |\n| `frontmatter.cjs` | YAML frontmatter CRUD operations |\n| `init.cjs` | Compound context loading for each workflow type |\n| `milestone.cjs` | Milestone archival, requirements marking |\n| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |\n| `model-profiles.cjs` | Model profile resolution table |\n| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |\n| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |\n| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |\n| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |\n| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |\n| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |\n| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |\n\n\n---\n\n## Agent Model\n\n### Orchestrator → Agent Pattern\n\n```\nOrchestrator (workflow .md)\n │\n ├── Load context: gsd-sdk query init. (or legacy gsd-tools.cjs init)\n │ Returns JSON with: project info, config, state, phase details\n │\n ├── Resolve model: gsd-sdk query resolve-model \n │ Returns: opus | sonnet | haiku | inherit\n │\n ├── Spawn Agent (Task/SubAgent call)\n │ ├── Agent prompt (agents/*.md)\n │ ├── Context payload (init JSON)\n │ ├── Model assignment\n │ └── Tool permissions\n │\n ├── Collect result\n │\n └── Update state: gsd-sdk query state.update / state.patch / state.advance-plan (or legacy gsd-tools.cjs)\n```\n\n### Primary Agent Spawn Categories\n\nConceptual spawn-pattern taxonomy for the 21 primary agents. For the authoritative 31-agent roster (including the 10 advanced/specialized agents such as `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), see [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped).\n\n\n| Category | Agents | Parallelism |\n| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |\n| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |\n| **Planners** | gsd-planner, gsd-roadmapper | Sequential |\n| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |\n| **Executors** | gsd-executor | Parallel within waves, sequential across waves |\n| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |\n| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |\n| **Debuggers** | gsd-debugger | Sequential (interactive) |\n| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |\n| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |\n| **Profilers** | gsd-user-profiler | Sequential |\n| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |\n\n\n### Wave Execution Model\n\nDuring `execute-phase`, plans are grouped into dependency waves:\n\n```\nWave Analysis:\n Plan 01 (no deps) ─┐\n Plan 02 (no deps) ─┤── Wave 1 (parallel)\n Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1)\n Plan 04 (depends: 02) ─┘\n Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)\n```\n\nEach executor gets:\n\n- Fresh 200K context window (or up to 1M for models that support it)\n- The specific PLAN.md to execute\n- Project context (PROJECT.md, STATE.md)\n- Phase context (CONTEXT.md, RESEARCH.md if available)\n\n### Adaptive Context Enrichment (1M Models)\n\nWhen the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4.6), subagent prompts are automatically enriched with additional context that would not fit in standard 200K windows:\n\n- **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase\n- **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification\n\nThe orchestrator reads `context_window` from config (`gsd-sdk query config-get context_window`, or legacy `gsd-tools.cjs config-get`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.\n\n#### Parallel Commit Safety\n\nWhen multiple executors run within the same wave, two mechanisms prevent conflicts:\n\n1. `--no-verify` commits — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.\n2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter.\n\n---\n\n## Data Flow\n\n### New Project Flow\n\n```\nUser input (idea description)\n │\n ▼\nQuestions (questioning.md philosophy)\n │\n ▼\n4x Project Researchers (parallel)\n ├── Stack → STACK.md\n ├── Features → FEATURES.md\n ├── Architecture → ARCHITECTURE.md\n └── Pitfalls → PITFALLS.md\n │\n ▼\nResearch Synthesizer → SUMMARY.md\n │\n ▼\nRequirements extraction → REQUIREMENTS.md\n │\n ▼\nRoadmapper → ROADMAP.md\n │\n ▼\nUser approval → STATE.md initialized\n```\n\n### Phase Execution Flow\n\n```\ndiscuss-phase → CONTEXT.md (user preferences)\n │\n ▼\nui-phase → UI-SPEC.md (design contract, optional)\n │\n ▼\nplan-phase\n ├── Research gate (blocks if RESEARCH.md has unresolved open questions)\n ├── Phase Researcher → RESEARCH.md\n │ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,\n │ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md\n ├── Planner (with reachability check) → PLAN.md files\n │ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;\n │ T-{phase}-SC STRIDE row added for install-bearing plans\n ├── Plan Checker → Verify loop (max 3x)\n ├── Requirements coverage gate (REQ-IDs → plans)\n └── Decision coverage gate (CONTEXT.md `` → plans, BLOCKING — #2492)\n │\n ▼\nstate planned-phase → STATE.md (Planned/Ready to execute)\n │\n ▼\nexecute-phase (context reduction: truncated prompts, cache-friendly ordering)\n ├── Wave analysis (dependency grouping)\n ├── Executor per plan → code + atomic commits\n ├── SUMMARY.md per plan\n └── Verifier → VERIFICATION.md\n └── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)\n │\n ▼\nverify-work → UAT.md (user acceptance testing)\n │\n ▼\nui-review → UI-REVIEW.md (visual audit, optional)\n```\n\n### Context Propagation\n\nEach workflow stage produces artifacts that feed into subsequent stages:\n\n```\nPROJECT.md ────────────────────────────────────────────► All agents\nREQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor\nROADMAP.md ────────────────────────────────────────────► Orchestrators\nSTATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)\nCONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor\nRESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker\nPLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker\nSUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking\nUI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor\n```\n\n---\n\n## File System Layout\n\n### Installation Files\n\n```\n~/.claude/ # Claude Code (global install)\n├── skills/gsd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)\n├── commands/gsd/*.md # Local Claude installs use slash commands instead of global skills\n├── get-shit-done/\n│ ├── bin/gsd-tools.cjs # CLI utility\n│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)\n│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)\n│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)\n│ └── templates/ # Planning artifact templates\n├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)\n├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)\n├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)\n├── settings.json # Hook registrations\n└── VERSION # Installed version number\n```\n\nEquivalent paths for other runtimes:\n\n- **OpenCode:** `~/.config/opencode/` global or `./.opencode/` local\n- **Kilo:** `~/.config/kilo/` global or `./.kilo/` local\n- **Gemini CLI:** `~/.gemini/` global or `./.gemini/` local\n- **Codex:** `~/.codex/` global or `./.codex/` local\n- **Copilot:** `~/.copilot/` global or `./.github/` local\n- **Antigravity:** `~/.gemini/antigravity/` global or `./.agent/` local\n- **Cursor:** `~/.cursor/` global or `./.cursor/` local\n- **Windsurf:** `~/.codeium/windsurf/` global or `./.windsurf/` local\n- **Augment Code:** `~/.augment/` global or `./.augment/` local\n- **Trae:** `~/.trae/` global or `./.trae/` local\n- **Qwen Code:** `~/.qwen/` global or `./.qwen/` local\n- **Hermes Agent:** `~/.hermes/` global or `./.hermes/` local\n- **CodeBuddy:** `~/.codebuddy/` global or `./.codebuddy/` local\n- **Cline:** `~/.cline/` global or project-root `.clinerules` local\n\n### Project Files (`.planning/`)\n\n```\n.planning/\n├── PROJECT.md # Project vision, constraints, decisions, evolution rules\n├── REQUIREMENTS.md # Scoped requirements (v1/v2/out-of-scope)\n├── ROADMAP.md # Phase breakdown with status tracking\n├── STATE.md # Living memory: position, decisions, blockers, metrics\n├── config.json # Workflow configuration\n├── MILESTONES.md # Completed milestone archive\n├── research/ # Domain research from /gsd-new-project\n│ ├── SUMMARY.md\n│ ├── STACK.md\n│ ├── FEATURES.md\n│ ├── ARCHITECTURE.md\n│ └── PITFALLS.md\n├── codebase/ # Brownfield mapping (from /gsd-map-codebase)\n│ ├── STACK.md # YAML frontmatter carries `last_mapped_commit`\n│ ├── ARCHITECTURE.md # for the post-execute drift gate (#2003)\n│ ├── CONVENTIONS.md\n│ ├── CONCERNS.md\n│ ├── STRUCTURE.md\n│ ├── TESTING.md\n│ └── INTEGRATIONS.md\n├── phases/\n│ └── XX-phase-name/\n│ ├── XX-CONTEXT.md # User preferences (from discuss-phase)\n│ ├── XX-RESEARCH.md # Ecosystem research (from plan-phase)\n│ ├── XX-YY-PLAN.md # Execution plans\n│ ├── XX-YY-SUMMARY.md # Execution outcomes\n│ ├── XX-VERIFICATION.md # Post-execution verification\n│ ├── XX-VALIDATION.md # Nyquist test coverage mapping\n│ ├── XX-UI-SPEC.md # UI design contract (from ui-phase)\n│ ├── XX-UI-REVIEW.md # Visual audit scores (from ui-review)\n│ └── XX-UAT.md # User acceptance test results\n├── quick/ # Quick task tracking\n│ └── YYMMDD-xxx-slug/\n│ ├── PLAN.md\n│ └── SUMMARY.md\n├── todos/\n│ ├── pending/ # Captured ideas\n│ └── done/ # Completed todos\n├── threads/ # Persistent context threads (from /gsd-thread)\n├── seeds/ # Forward-looking ideas (from /gsd-capture --seed)\n├── debug/ # Active debug sessions\n│ ├── *.md # Active sessions\n│ ├── resolved/ # Archived sessions\n│ └── knowledge-base.md # Persistent debug learnings\n├── ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)\n└── continue-here.md # Context handoff (from pause-work)\n```\n\n### Post-Execute Codebase Drift Gate (#2003)\n\nAfter the last wave of `/gsd-execute-phase` commits, the workflow runs a\nnon-blocking `codebase_drift_gate` step (between `schema_drift_gate` and\n`verify_phase_goal`). It compares the diff `last_mapped_commit..HEAD`\nagainst `.planning/codebase/STRUCTURE.md` and counts four kinds of\nstructural elements:\n\n1. New directories outside mapped paths\n2. New barrel exports at `(packages|apps)//src/index.*`\n3. New migration files\n4. New route modules under `routes/` or `api/`\n\nIf the count meets `workflow.drift_threshold` (default 3), the gate either\n**warns** (default) with the suggested `/gsd-map-codebase --paths …` command,\nor **auto-remaps** (`workflow.drift_action = auto-remap`) by spawning\n`gsd-codebase-mapper` scoped to the affected paths. Any error in detection\nor remap is logged and the phase continues — drift detection cannot fail\nverification.\n\n`last_mapped_commit` lives in YAML frontmatter at the top of each\n`.planning/codebase/*.md` file; `bin/lib/drift.cjs` provides\n`readMappedCommit` and `writeMappedCommit` round-trip helpers.\n\n---\n\n## Installer Architecture\n\nThe installer (`bin/install.js`, ~10,700 lines) handles:\n\n1. **Runtime detection** — Interactive prompt or CLI flags (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--augment`, `--trae`, `--qwen`, `--hermes`, `--codebuddy`, `--cline`, `--all`)\n2. **Location selection** — Global (`--global`) or local (`--local`)\n3. **File deployment** — Copies commands, skills, workflows, references, templates, agents, and hooks\n4. **Runtime adaptation** — Transforms file content per runtime:\n - Claude Code: Uses as-is\n - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format\n - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths\n - Codex: Generates TOML config + skills from commands\n - Copilot: Maps tool names (Read→read, Bash→execute, etc.)\n - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)\n - Antigravity: Skills-first with Google model equivalents\n - Cursor: Skills-first with Cursor rule references\n - Windsurf: Skills-first with Windsurf rule references\n - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration\n - Qwen Code: Skills-first with Qwen-branded path and prompt rewrites\n - Hermes Agent: Category-based skills under `skills/gsd/`\n - CodeBuddy: Skills-first with CodeBuddy path and prompt rewrites\n - Cline: Writes `.clinerules` for rule-based integration\n - Augment Code: Skills-first with full skill conversion and config management\n5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths\n6. **Settings integration** — Registers hooks in runtime's `settings.json`\n7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-update --reapply`\n8. **Manifest tracking** — Writes `gsd-file-manifest.json` for clean uninstall\n9. **Uninstall mode** — `--uninstall` removes all GSD files, hooks, and settings\n\nInstall-time file moves, stale-artifact cleanup, config rewrites, and user-data\npreservation are governed by the Installer Migration Module. See\n[Installer Migrations](installer-migrations.md) and\n[ADR 0008](adr/0008-installer-migration-module.md).\nThe migration module also owns the gated first-time baseline scan for legacy\ninstalls, classifying known runtime install surfaces before later migrations\nremove or rewrite anything.\n\n### Platform Handling\n\n- **Windows:** `windowsHide` on child processes, EPERM/EACCES protection on protected directories, path separator normalization\n- **WSL:** Detects Windows Node.js running on WSL and warns about path mismatches\n- **Docker/CI:** Supports `CLAUDE_CONFIG_DIR` env var for custom config directory locations\n\n---\n\n## Hook System\n\n### Architecture\n\n```\nRuntime Engine (Claude Code / Gemini CLI)\n │\n ├── statusLine event ──► gsd-statusline.js\n │ Reads: stdin (session JSON)\n │ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)\n │\n ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js\n │ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)\n │ Writes: stdout (hookSpecificOutput with additionalContext warning)\n │\n └── SessionStart event ──► gsd-check-update.js\n Reads: VERSION file\n Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)\n```\n\n### Context Monitor Thresholds\n\n\n| Remaining Context | Level | Agent Behavior |\n| ----------------- | -------- | --------------------------------------- |\n| > 35% | Normal | No warning injected |\n| ≤ 35% | WARNING | \"Avoid starting new complex work\" |\n| ≤ 25% | CRITICAL | \"Context nearly exhausted, inform user\" |\n\n\nDebounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce.\n\n### Safety Properties\n\n- All hooks wrap in try/catch, exit silently on error\n- stdin timeout guard (3s) prevents hanging on pipe issues\n- Stale metrics (>60s old) are ignored\n- Missing bridge files handled gracefully (subagents, fresh sessions)\n- Context monitor is advisory — never issues imperative commands that override user preferences\n\n### Package Legitimacy Gate (v1.42.1)\n\nThe researcher → planner → executor pipeline includes a supply-chain gate against slopsquatting (AI-hallucinated package names pre-registered with malicious post-install scripts).\n\n**Threat model:** GSD automates the full path from \"researcher names a package\" to \"executor runs `npm install`\". A hallucinated name that passes `npm view` (proving only registration, not legitimacy) would previously flow through undetected. ~20% of AI-generated package references are hallucinated; ~43% of those names recur consistently across prompts, making pre-registration economically viable for attackers.\n\n**Gate layers:**\n\n| Layer | Component | Action |\n|-------|-----------|--------|\n| Research | `gsd-phase-researcher` | Runs `slopcheck install --json`; writes `## Package Legitimacy Audit` table to RESEARCH.md; strips `[SLOP]` packages before RESEARCH.md is written |\n| Planning | `gsd-planner` | Reads Audit table; inserts `checkpoint:human-verify` before any `[ASSUMED]` or `[SUS]` install task; adds `T-{phase}-SC` STRIDE supply-chain row to `` |\n| Execution | `gsd-executor` | RULE 3 excludes package installation from auto-fix scope; failed installs surface as checkpoints, never silent substitutions |\n\n**Claim provenance integration:** Package names discovered via WebSearch are tagged `[ASSUMED]` (not `[VERIFIED]`) regardless of `npm view` result. This extends the existing `[ASSUMED]` / `[VERIFIED]` / `[CITED]` provenance system by enforcing the provenance tag as a hard gate at the install boundary — `[ASSUMED]` always generates a `checkpoint:human-verify` in PLAN.md.\n\n**Ecosystem coverage:** The researcher uses registry-specific verification commands — `npm view` (Node), `pip index versions` (Python), `cargo search` (Rust) — rather than a single generic check. This catches cross-ecosystem hallucination (~9% rate documented in 2025 USENIX research).\n\n**Graceful degradation:** If `slopcheck` is unavailable, every recommended package is tagged `[ASSUMED]` and gated with a checkpoint. Research and planning proceed; the system never hard-fails on a missing tool dependency.\n\n**External dependency:** `slopcheck` (MIT, pip-installable). If abandoned, the `[ASSUMED]`-gate fallback maintains human-checkpoint coverage.\n\n---\n\n### Security Hooks (v1.27)\n\n**Prompt Guard** (`gsd-prompt-guard.js`):\n\n- Triggers on Write/Edit to `.planning/` files\n- Scans content for prompt injection patterns (role override, instruction bypass, system tag injection)\n- Advisory-only — logs detection, does not block\n- Patterns are inlined (subset of `security.cjs`) for hook independence\n\n**Workflow Guard** (`gsd-workflow-guard.js`):\n\n- Triggers on Write/Edit to non-`.planning/` files\n- Detects edits outside GSD workflow context (no active `/gsd-` command or Task subagent)\n- Advises using `/gsd-quick` or `/gsd-fast` for state-tracked changes\n- Opt-in via `hooks.workflow_guard: true` (default: false)\n\n---\n\n## Runtime Abstraction\n\nGSD supports multiple AI coding runtimes through a unified command/workflow architecture:\n\n### Runtime Install Contract Matrix\n\nThis matrix describes the runtime surfaces the installer materializes today.\nThe migration-specific ownership and source snapshots live in\n[Installer Migrations](installer-migrations.md#runtime-configuration-contract-registry).\n\n| Runtime | Global root | Local root | Invocation surface | Agent surface | Config and hooks |\n| --- | --- | --- | --- | --- | --- |\n| Claude Code | `~/.claude` | `./.claude` | Global `skills/gsd-*/SKILL.md`; local `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` hook and statusLine entries |\n| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` or `opencode.jsonc`; no GSD hooks |\n| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` or `kilo.jsonc`; no GSD hooks |\n| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` feature flag, hooks, and statusline |\n| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | `agents/` source markdown plus per-agent TOML | `config.toml` `[agents.gsd-*]`, `[features].hooks` (canonical; legacy alias `codex_hooks` is recognized and migrated forward on reinstall, #3566), and hook tables |\n| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` and `copilot-instructions.md` | `.agent.md` files | No GSD hooks or statusline |\n| Antigravity | `~/.gemini/antigravity` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Gemini-style `settings.json` hook entries when installed by GSD |\n| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | No GSD hooks or statusline |\n| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` plus `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Cline | `~/.cline` | project root | `.clinerules` | Rules only | No GSD hooks or statusline |\n\n### Upstream Contract Sources\n\nRuntime install expectations are checked against primary documentation where\navailable. The current source snapshot is 2026-05-11:\n\n- Claude Code: Anthropic slash commands, settings, hooks, and subagents docs.\n- OpenCode and Kilo: OpenCode config docs and Kilo custom subagent docs.\n- Gemini CLI and Qwen Code: command/config docs; Qwen command docs were last\n updated 2026-05-06.\n- Codex: OpenAI Codex docs and `config-schema.json`; the installer also carries\n Codex 0.124.0 compatibility for agent table shape.\n- Copilot, Cursor, Cline, Augment, Hermes, and CodeBuddy: vendor docs for\n custom instructions, rules, skills, or config.\n- Antigravity, Windsurf, and Trae: source-limited rows. The installer documents\n current compatibility shims, and migrations must refresh those sources before\n rewriting their config.\n\n### Abstraction Points\n\n1. **Tool name mapping** — Each runtime has its own tool names (e.g., Claude's `Bash` → Copilot's `execute`)\n2. **Hook event names** — Claude uses `PostToolUse`, Gemini uses `AfterTool`\n3. **Agent frontmatter** — Each runtime has its own agent definition format\n4. **Path conventions** — Each runtime stores config in different directories\n5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection\n\nThe installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.\n","docs/agents/cjs-sdk-seam.md":"# CJS↔SDK Hard-Seam Migration: Complete Reference\n## Issue #3575 (Parent: #3524)\n\n---\n\n## Migration overview\n\nThe CJS↔SDK hard-seam migration (#3524) eliminates a class of config-schema drift bugs by introducing single sources of truth at every decision point where CJS and SDK code previously diverged. The migration proceeded in six phases:\n\n| Phase | PR | Summary |\n|-------|----|---------|\n| Phase 1 | [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) | `state-document` Shared Module — source-of-truth at `sdk/src/state-document/`, generator, freshness check, CJS Adapter (`state-document.generated.cjs`). Worked example for the pattern. |\n| Phase 2 | [#3540](https://github.com/gsd-build/get-shit-done/pull/3540) | `configuration` Shared Module — `sdk/shared/config-schema.manifest.json` + `sdk/shared/config-defaults.manifest.json` as data manifests; generator + freshness check + CJS Adapter. |\n| Phase 3 | [#3548](https://github.com/gsd-build/get-shit-done/pull/3548) | `workstream-inventory` Shared Module — source-of-truth at `sdk/src/workstream-inventory/`, builder, generator, freshness check, CJS Adapter. |\n| Phase 4 | [#3554](https://github.com/gsd-build/get-shit-done/pull/3554) | `project-root` Shared Module — source-of-truth at `sdk/src/project-root/`, generator, freshness check, CJS Adapter. |\n| Phase 5.0 | [#3558](https://github.com/gsd-build/get-shit-done/pull/3558) | `runtime-bridge-sync` worker — enables CJS-side execution of SDK native handlers; state.* family initial router delegation via `executeForCjs`. |\n| Phase 5.1 | [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) | `state.*` router delegation complete — all known state subcommands delegated via `executeForCjs`; Phase 5.0 worker bug fix. |\n| Phase 6 | [#3577](https://github.com/gsd-build/get-shit-done/pull/3577) (closes [#3575](https://github.com/gsd-build/get-shit-done/issues/3575)) | Enforcement hardening + Final completion — hand-sync drift lint, CODEOWNERS, 6 family-router migrations, 5 Shared Module migrations (plan-scan, secrets, schema-detect, decisions, workstream-name-policy), workstream native support, parity fixes. Migration feature-complete: 22 cooperating siblings, 0 backlog pairs. |\n\n---\n\n## Phase 6 Retrospective: 15 config-schema drift bugs\n\nThis section captures 15 recurring config-schema drift bugs that motivated the migration. For each, we record what drifted, the surgical fix, and which Phase 6 enforcement layer would have prevented it.\n\n---\n\n### #1535 — Silent failure on unrecognized config.json keys\n- **Drifted:** `loadConfig` silently ignored any top-level key in `.planning/config.json` not in `VALID_CONFIG_KEYS`, giving users no feedback when hand-edited or external-tool-added keys had no effect.\n- **Fix landed:** PR #1542 — added stderr warning listing unrecognized keys.\n- **Would have been blocked by:** **handsync lint** — a seam-aware linter would forbid having parallel hand-authored config validators (CJS `config.cjs` and SDK `config-mutation.ts`) that could silently diverge.\n\n---\n\n### #1542 — fix(config): warn on unrecognized keys in config.json instead of silent drop\n- **Drifted:** No drift in this bug itself; it *fixed* #1535's silent-drop behavior by adding the warning.\n- **Fix landed:** PR #1542 — merged as the direct fix for #1535.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check on config validation) — both CJS and SDK config paths would be regenerated from a single source-of-truth schema module, eliminating the silent-drop risk.\n\n---\n\n### #2047 — bug: config-set rejects intel.enabled despite being a documented config key\n- **Drifted:** `intel.enabled` was documented in workflows and gated in runtime code (`intel.cjs:58`), but missing from `VALID_CONFIG_KEYS` in `config.cjs`, so `config-set` rejected it.\n- **Fix landed:** PR #2021 — added `intel.enabled` to `VALID_CONFIG_KEYS` in CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every config key gated in runtime code or documented in workflows must appear in the validator allowlist.\n\n---\n\n### #2052 — fix(config): add intel.enabled to VALID_CONFIG_KEYS\n- **Drifted:** Same as #2047 (missing from allowlist).\n- **Fix landed:** PR #2021 (same PR as #2047 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2047.\n\n---\n\n### #2638 — bug: loadConfig writes sub_repos to top-level, then warns it's unknown\n- **Drifted:** After #2561 canonicalized `sub_repos` to `planning.sub_repos`, the legacy migration and filesystem auto-sync in `loadConfig` still wrote to top-level `parsed.sub_repos`, which was then flagged as unknown.\n- **Fix landed:** PR #2668 — rewrote both paths to target `parsed.planning.sub_repos` and deleted stale top-level copy.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check for config shape) — the canonical location for `sub_repos` would be codified in a schema, and any code path writing to it would be verified against that schema at lint time.\n\n---\n\n### #2655 — fix(core): write sub_repos to planning.sub_repos, not top-level\n- **Drifted:** Same as #2638.\n- **Fix landed:** PR #2668 (same as #2638 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2638.\n\n---\n\n### #2653 — bug: SDK config-set rejects documented config keys accepted by CJS config-set\n- **Drifted:** SDK's `config-mutation.ts` had a hand-maintained `VALID_CONFIG_KEYS` set that had drifted **28 keys** behind CJS's `config-schema.cjs`, so documented commands like `gsd-sdk query config-set planning.sub_repos` were rejected.\n- **Fix landed:** PR #2670 — extracted shared `sdk/src/query/config-schema.ts` module mirroring CJS exactly; added parity test to fail on future drift.\n- **Would have been blocked by:** **manifest data isolation** — the config schema would live in one place (e.g., `sdk/shared/config.manifest.json`), and both CJS and SDK would read it, eliminating the possibility of independent drift.\n\n---\n\n### #2670 — fix(#2653): eliminate SDK↔CJS config-schema drift\n- **Drifted:** Same as #2653 (28-key drift).\n- **Fix landed:** PR #2670 (same as #2653 fix).\n- **Would have been blocked by:** **manifest data isolation** — same as #2653.\n\n---\n\n### #2687 — bug: loadConfig warns on valid dynamic-pattern containers in .planning/config.json\n- **Drifted:** Keys like `review.models.` were registered in `config-schema.cjs`'s `DYNAMIC_KEY_PATTERNS` but absent from the hand-maintained `KNOWN_TOP_LEVEL` set in `core.cjs`, causing false-positive \"unknown key\" warnings.\n- **Fix landed:** PR #2706 — added `topLevel` field to `DYNAMIC_KEY_PATTERNS` entries; derived `KNOWN_TOP_LEVEL` from schema instead of maintaining it manually.\n- **Would have been blocked by:** **per-Module drift lint** — the validator that builds `KNOWN_TOP_LEVEL` would be regenerated from the schema each run, not hand-maintained.\n\n---\n\n### #2706 — fix(#2687): loadConfig no longer warns on valid dynamic-pattern containers\n- **Drifted:** Same as #2687 (false warnings on valid dynamic keys).\n- **Fix landed:** PR #2706 (same as #2687 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2687.\n\n---\n\n### #2798 — context_window missing from VALID_CONFIG_KEYS\n- **Drifted:** `context_window` was documented in workflows and read in SDK runtime (`init.js:190`, `validate.js:575`), but missing from allowlists in both `config-mutation.ts` and `config-schema.cjs`, so writes were rejected.\n- **Fix landed:** PR #2816 — added `context_window` to `VALID_CONFIG_KEYS` in both SDK and CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every key read at runtime must be in the allowlist.\n\n---\n\n### #2816 — fix(#2798): add context_window to VALID_CONFIG_KEYS allowlist\n- **Drifted:** Same as #2798 (missing from allowlists).\n- **Fix landed:** PR #2816 (same as #2798 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2798.\n\n---\n\n### #3055 — bug: top-level branching_strategy silently becomes \"none\"\n- **Drifted:** `.planning/config.json` with top-level `branching_strategy: \"phase\"` was flagged as unknown and dropped by validator, causing `loadConfig` to fall back to the `\"none\"` default, so phase commits landed on the operator's current branch instead of creating `gsd/phase-{N}` branches.\n- **Fix landed:** PR #3116 — SDK-side only; added legacy normalization in `mergeDefaults()` to graft top-level value into canonical `git.branching_strategy` slot before validation.\n- **Would have been blocked by:** **per-Module drift lint** — the canonical location for `branching_strategy` would be codified in schema; validator would not strip the value before migrations had a chance to run, or CJS and SDK would share the same migration code.\n\n---\n\n### #3116 — fix: normalize legacy top-level branching_strategy into git config\n- **Drifted:** Same as #3055 (legacy top-level shape not normalized before validator strips it).\n- **Fix landed:** PR #3116 (SDK-side normalization in `mergeDefaults()`).\n- **Would have been blocked by:** **per-Module drift lint** — same as #3055, but SDK-side fix would be shared with CJS via seam layer instead of being ported separately.\n\n---\n\n### #3523 — bug: CJS loadConfig warns top-level branching_strategy 'will be ignored', but actively reads it\n- **Drifted:** After PR #3116 fixed the SDK side, the CJS path still emitted false \"will be ignored\" warnings on the same legacy top-level key, because `KNOWN_TOP_LEVEL` derivation extracted top-level names from `VALID_CONFIG_KEYS` (which contains `'git.branching_strategy'` but not `'branching_strategy'`), and the warning was factually incorrect — `core.cjs:485` does read the legacy value via fallback logic.\n- **Fix landed:** PR #3527 — added `'branching_strategy'` to the `KNOWN_TOP_LEVEL` hand-maintained list under the deprecated-keys bucket, suppressing the false warning.\n- **Would have been blocked by:** **runtime-bridge delegation** — if CJS and SDK config loading shared a common normalization routine (via `executeForCjs` or a shared seam module), the SDK fix in #3116 would automatically apply to CJS; no separate CJS-side warning would be possible.\n\n---\n\n## Surprises\n\nNone. All 15 bugs are genuine CJS↔SDK schema/validation drift, exactly the class the seam migration prevents.\n\n## Phase 6 Enforcement Summary\n\nThe seam migration introduces these layers:\n\n1. **handsync lint** (`scripts/lint-shared-module-handsync.cjs`) — Forbids parallel hand-authored validator modules; catches #1535, #2047, #2798.\n2. **freshness check** (`sdk/scripts/check--fresh.mjs`) — Regenerates config validators from schema each run; catches #2687, #3055.\n3. **manifest data isolation** (`sdk/shared/*.manifest.json`) — Single source-of-truth for schema; catches #2653.\n4. **per-Module drift lint** — Combination of freshness checks and schema-derived allowlists; catches #2638, #2687, #3055.\n5. **runtime-bridge delegation** (`executeForCjs` + shared seam modules) — Eliminates parallel CJS/SDK implementations; catches #3523 by preventing separate CJS warning logic.\n\nTogether, these layers eliminate the 15-bug class by enforcing single sources of truth at each decision point.\n\n---\n\n## Guide: Adding a new Shared Module\n\nUse this when you want to extract a new piece of data or logic that both CJS and SDK currently duplicate hand-by-hand. Phase 1's `state-document` migration is the worked example.\n\n**Step 1 — Create the source-of-truth file**\n\n```text\nsdk/src//index.ts\n```\n\nThis is the canonical definition. It may export a schema, a set of keys, a type, or a data object. It must not import from CJS or from generated files.\n\n**Step 2 — Write the generator script**\n\n```text\nsdk/scripts/gen-.mjs\n```\n\nThe generator reads `sdk/src//index.ts` (or `sdk/shared/.manifest.json` for pure-data manifests), produces a generated output file (either `sdk/src/.generated.ts` or `get-shit-done/bin/lib/.generated.cjs`), and exits 0. It must be idempotent: running it twice produces the same output.\n\n**Step 3 — Write the freshness check**\n\n```text\nsdk/scripts/check--fresh.mjs\n```\n\nThe freshness check re-runs the generator into a temp location, diffs against the committed file, and exits 1 with a clear message if they diverge. This is what CI runs.\n\n**Step 4 — Write the parity test** (optional but recommended)\n\n```text\ntests/-parity.test.cjs\n```\n\nAssert that the CJS Adapter and the SDK source-of-truth agree on every field that matters (key sets, defaults, schema shape). This test catches generator bugs that the freshness check cannot.\n\n**Step 5 — Wire CI**\n\nAdd a step in `.github/workflows/test.yml` after the existing freshness-check block (before \"Run tests with coverage\"), gated on `matrix.os == 'ubuntu-latest' && matrix.node-version == 24`:\n\n```yaml\n- name: SDK generated artifact drift check\n if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24\n shell: bash\n run: node sdk/scripts/check--fresh.mjs\n```\n\n**Step 6 — Run inventory regen**\n\nIf the module affects `CONTEXT.md`'s module inventory, update that section. Also update `scripts/shared-module-handsync-allowlist.json`: move any matching entry from `migrateMeBacklog` to `cooperatingSiblings` (or remove it entirely if the CJS hand-copy is now deleted).\n\n**Step 7 — Update CODEOWNERS**\n\nAdd the new source-of-truth path to `.github/CODEOWNERS` under the Phase 6 block to make the architectural ownership explicit.\n\n**Reference:** Phase 1 PR [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) — `state-document` migration.\n\n---\n\n## Guide: Adding a new canonical command\n\nUse this when adding a new `gsd-sdk query .` that should be handled natively in the SDK (not delegated to CJS). Phase 5.1's `state.update` migration (PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574)) is the worked example.\n\n**Step 1 — Declare in the command manifest**\n\nAdd the command definition to `sdk/src/query/command-manifest..ts`. Include the full argument schema and a `handler` reference.\n\n**Step 2 — Implement the SDK handler**\n\nWrite the handler in `sdk/src/query/.ts` (or inline in the manifest file for simple cases). The handler receives validated args and the runtime context; it must not shell out to CJS.\n\n**Step 3 — Add CJS router delegate (Phase 5.1+ pattern)**\n\nIn the family's CJS command router (e.g. `get-shit-done/bin/lib/state-command-router.cjs`), add a delegate case that calls `executeForCjs(subcommand, args)` from `cjs-command-router-adapter.cjs`. This ensures the CJS binary dispatches to the SDK native handler rather than re-implementing the logic.\n\n**Step 4 — Add a golden parity test**\n\nAdd a test in `tests/-command-router.test.cjs` (or a new file if the family has no test yet) that:\n1. Invokes the command via the SDK query path.\n2. Invokes the command via the CJS router path.\n3. Asserts both produce identical output.\n\nThis test enforces that the delegate and the native handler stay aligned.\n\n**Reference:** Phase 5.1 PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) — `state.update` delegation.\n\n---\n\n## Phase 6 Final Completion Summary\n\nPhase 6 (issue #3575, PR #3577) is feature-complete. The migration is done.\n\n**What shipped in Phase 6:**\n\n- **Shared Modules migrated (5 total in Phase 6):** `plan-scan`, `secrets`, `schema-detect`, `decisions`, `workstream-name-policy`. Each follows the full pattern: SDK source-of-truth, generator (`gen-.mjs`), freshness check (`check--fresh.mjs`), generated CJS artifact (`.generated.cjs`), CJS shim re-export, parity test, CI step, pre-commit hook, CODEOWNERS entry.\n- **Workstream native support:** The sync bridge worker now correctly threads `workstream` through to `registry.dispatch()`. `GSDTransport` no longer forces subprocess for workstream-scoped requests. Workstream-scoped state commands execute natively.\n- **State parity divergences resolved:** `state.record-metric` and `state.prune` SDK handlers now match CJS semantics exactly.\n- **MIGRATE_ME pairs resolved:** `decisions` and `workstream-name-policy` migrated from `migrateMeBacklog` to `cooperatingSiblings` as ADAPTER-OVER-MODULE.\n- **Lint final state:** 22 cooperating siblings, 0 backlog pairs.\n\n**Decisions migration specifics (B1):**\n- SDK `decisions.ts` regex aligned to CJS: `D-([A-Za-z0-9_-]+)` (alphanumeric IDs like `D-INFRA-01` accepted).\n- SDK returns richer `{id, text, category, tags, trackable}`; CJS callers using only `{id, text}` safely ignore extras.\n- Parity test: `tests/decisions-generator.test.cjs` (15 tests covering numeric IDs, alphanumeric IDs, richer schema fields).\n\n**Workstream-name-policy migration specifics (B2):**\n- Added `hasInvalidPathSegment` and `isValidActiveWorkstreamName` to SDK `workstream-name-policy.ts`.\n- `validateWorkstreamName` is now an alias for `isValidActiveWorkstreamName` (consistent with CJS semantics).\n- Parity test: `tests/workstream-name-policy-generator.test.cjs` (19 tests covering all four exports).\n\n---\n\n## Open follow-ups\n\nNo migration items remain. The following are future quality candidates, not defects:\n\n- **`config.cjs` / `sdk/src/config.ts`** — These files are CJS-CLI-ONLY (per allowlist classification). The `config.cjs` file contains only CLI command handlers that use sync CJS APIs; `sdk/src/config.ts` provides the async SDK layer. They serve disjoint surfaces. A future migration would require converting the CLI handlers to async + SDK patterns, which is a larger refactor out of scope for this migration cycle.\n- **`intel.cjs` / `sdk/src/query/intel.ts`** — Intentional architectural divergence (different file naming conventions between CJS and SDK; documented in allowlist). A future migration would require reconciling INTEL_FILES naming, which is a breaking change for existing consumers.\n- **`model-catalog.cjs` / `sdk/src/model-catalog.ts`** — Both sides read from `sdk/shared/model-catalog.json` independently (ADAPTER-OVER-MODULE pattern). This is intentional; the shared JSON is the source-of-truth. No duplication of logic between CJS and SDK consumers.\n","docs/agents/domain.md":"# Domain Docs\n\nHow engineering skills consume this repo's domain documentation.\n\n## Layout: single-context\n\n```\n/\n├── CONTEXT.md ← domain glossary + recurring PR rules + workflow learnings\n├── docs/adr/ ← architectural decisions\n│ ├── 0001-dispatch-policy-module.md\n│ └── 0002-command-contract-validation-module.md\n└── ...\n```\n\n## Before exploring, read these\n\n1. **`CONTEXT.md`** at the repo root — domain terms, module names, recurring PR mistakes, workflow learnings. Read in full before naming anything or proposing architecture changes.\n2. **`docs/adr/`** — read ADRs relevant to the area you're working in before proposing structural changes. If your output contradicts an ADR, surface it explicitly:\n > *Contradicts ADR-0002 — but worth reopening because…*\n\nIf either file doesn't exist yet, proceed silently.\n\n## Use the glossary's vocabulary\n\nWhen naming modules, writing issue titles, test descriptions, or commit messages — use terms as defined in `CONTEXT.md`. Don't drift to synonyms. If you need a concept that isn't in the glossary, note it for `/grill-with-docs` rather than inventing language.\n\n## CONTEXT.md sections\n\n- **Domain terms** — canonical module names and seam vocabulary (Dispatch Policy Module, Command Contract Validation Module, etc.)\n- **Recurring PR mistakes** — CodeRabbit findings that recur; check before writing tests, shell scripts, changesets, or docs\n- **Workflow learnings** — patterns learned from triage + PR cycles; check before writing new command/workflow files or test paths\n","docs/agents/issue-tracker.md":"# Issue tracker: GitHub\n\nIssues for this repo live in **GitHub Issues** at `gsd-build/get-shit-done`.\n\n## Auth\n\nUse the configured GitHub CLI session for this checkout. Do not require a\nrepo-local `.envrc` before running `gh`.\n\n## Conventions\n\n- **Create**: `gh issue create --repo gsd-build/get-shit-done --title \"...\" --body \"...\"`\n- **Read**: `gh issue view --repo gsd-build/get-shit-done --comments`\n- **List**: `gh issue list --repo gsd-build/get-shit-done --state open --json number,title,labels --jq '...'`\n- **Comment**: `gh issue comment --repo gsd-build/get-shit-done --body \"...\"`\n- **Label**: `gh issue edit --repo gsd-build/get-shit-done --add-label \"...\" --remove-label \"...\"`\n- **Close**: `gh issue close --repo gsd-build/get-shit-done --comment \"...\"`\n\nAlways pass `--repo gsd-build/get-shit-done` explicitly — the local clone has multiple remotes and `gh` may resolve to the wrong one.\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a GitHub issue at `gsd-build/get-shit-done`.\n\n## When a skill says \"fetch the relevant ticket\"\n\nRun `gh issue view --repo gsd-build/get-shit-done --comments`.\n","docs/agents/triage-labels.md":"# Triage Labels\n\nMaps the five canonical triage roles to the actual label strings in `gsd-build/get-shit-done`.\n\n| Canonical role | Label in this repo | Notes |\n|-------------------|--------------------------|----------------------------------------------------------------|\n| `needs-triage` | `needs-triage` | Auto-applied by GitHub Action on every new issue |\n| `needs-info` | `needs-reproduction` | Waiting on reporter — cannot reproduce, more info required |\n| `ready-for-agent` | `confirmed` | Bug verified + fully specified — AFK agent can pick up |\n| `ready-for-human` | `approved-enhancement` / `approved-feature` | Enhancement/feature approved by maintainer — human codes it |\n| `wontfix` | `wontfix` | Will not be actioned |\n\n## Notes on this repo's label model\n\n- `confirmed` is the AFK-agent-ready signal for **bugs**. It means \"verified to exist and reproducible.\"\n- For **enhancements** and **features**, maintainer approval is `approved-enhancement` / `approved-feature` respectively. A contributor (human or agent) may not write code until one of these is applied.\n- There is no separate \"ready-for-human\" vs \"ready-for-agent\" distinction for enhancements — both flow through the same `approved-*` labels. If the work requires human judgment (design decisions, external access), note it in the issue body.\n- `needs-triage` is removed when any other state label is applied.\n- `needs-reproduction` is used instead of the generic `needs-info` — be specific in triage comments about what reproduction steps or information are missing.\n","docs/skills/discovery-contract.md":"# Skill Discovery Contract\n\n> Canonical rules for scanning, inventorying, and rendering GSD skills.\n\n## Root Categories\n\n### Project Roots\n\nScan these roots relative to the project root:\n\n- `.claude/skills/`\n- `.agents/skills/`\n- `.cursor/skills/`\n- `.github/skills/`\n- `./.codex/skills/`\n\nThese roots are used for project-specific skills and for the project `CLAUDE.md` skills section.\n\n### Managed Global Roots\n\nScan these roots relative to the user home directory:\n\n- `~/.claude/skills/`\n- `~/.codex/skills/`\n\nThese roots are used for managed runtime installs and inventory reporting.\n\n### Deprecated Import-Only Root\n\n- `~/.claude/get-shit-done/skills/`\n\nThis root is kept for legacy migration only. Inventory code may report it, but new installs should not write here.\n\n### Legacy Claude Commands\n\n- `~/.claude/commands/gsd/`\n\nThis is not a skills root. Discovery code only checks whether it exists so inventory can report legacy Claude installs.\n\n## Normalization Rules\n\n- Scan only subdirectories that contain `SKILL.md`.\n- Read `name` and `description` from YAML frontmatter.\n- Use the directory name when `name` is missing.\n- Extract trigger hints from body lines that match `TRIGGER when: ...`.\n- Treat `gsd-*` directories as installed framework skills.\n- Treat `~/.claude/get-shit-done/skills/` entries as deprecated/import-only.\n- Treat `~/.claude/commands/gsd/` as legacy command installation metadata, not skills.\n\n## Scanner Behavior\n\n### `sdk/src/query/skills.ts`\n\n- Returns a de-duplicated list of discovered skill names.\n- Scans project roots plus managed global roots.\n- Does not scan the deprecated import-only root.\n\n### `get-shit-done/bin/lib/profile-output.cjs`\n\n- Builds the project `CLAUDE.md` skills section.\n- Scans project roots only.\n- Skips `gsd-*` directories so the project section stays focused on user/project skills.\n- Adds `.codex/skills/` to the project discovery set.\n\n### `get-shit-done/bin/lib/init.cjs`\n\n- Generates the skill inventory object for `skill-manifest`.\n- Reports `skills`, `roots`, `installation`, and `counts`.\n- Marks `gsd_skills_installed` when any discovered skill name starts with `gsd-`.\n- Marks `legacy_claude_commands_installed` when `~/.claude/commands/gsd/` contains `.md` command files.\n\n## Inventory Shape\n\n`skill-manifest` returns a JSON object with:\n\n- `skills`: normalized skill entries\n- `roots`: the canonical roots that were checked\n- `installation`: summary booleans for installed GSD skills and legacy Claude commands\n- `counts`: small inventory counts for downstream consumers\n\nEach skill entry includes:\n\n- `name`\n- `description`\n- `triggers`\n- `path`\n- `file_path`\n- `root`\n- `scope`\n- `installed`\n- `deprecated`\n\n","docs/zh-CN/references/checkpoints.md":"# 检查点\n\n计划自主执行。检查点用于规范化需要人工验证或决策的交互点。\n\n**核心原则：** Claude 用 CLI/API 自动化一切。检查点用于验证和决策，而非手动工作。\n\n**黄金法则：**\n1. **如果 Claude 能运行，Claude 就运行** - 绝不让用户执行 CLI 命令、启动服务器或运行构建\n2. **Claude 设置验证环境** - 启动开发服务器、填充数据库、配置环境变量\n3. **用户只做需要人工判断的事** - 视觉检查、UX 评估、\"这个感觉对吗？\"\n4. **密钥来自用户，自动化来自 Claude** - 询问 API 密钥，然后 Claude 通过 CLI 使用它们\n5. **自动模式绕过验证/决策检查点** — 当 config 中 `workflow._auto_chain_active` 或 `workflow.auto_advance` 为 true 时：human-verify 自动批准，decision 自动选择第一个选项，human-action 仍会停止（认证门控无法自动化）\n\n## 检查点类型\n\n### checkpoint:human-verify（最常见 - 90%）\n\n**何时使用：** Claude 完成自动化工作，人工确认其正常工作。\n\n**用于：**\n- 视觉 UI 检查（布局、样式、响应式）\n- 交互流程（点击向导、测试用户流程）\n- 功能验证（功能按预期工作）\n- 音频/视频播放质量\n- 动画流畅度\n- 无障碍测试\n\n**结构：**\n```xml\n\n [Claude 自动化并部署/构建的内容]\n \n [测试的确切步骤 - URL、命令、预期行为]\n \n [如何继续 - \"approved\"、\"yes\" 或描述问题]\n\n```\n\n**示例：UI 组件（展示关键模式：Claude 在检查点之前启动服务器）**\n```xml\n\n 构建响应式仪表板布局\n src/components/Dashboard.tsx, src/app/dashboard/page.tsx\n 创建带侧边栏、标题和内容区域的仪表板。使用 Tailwind 响应式类处理移动端。\n npm run build 成功，无 TypeScript 错误\n 仪表板组件构建无错误\n\n\n\n 启动开发服务器用于验证\n 在后台运行 `npm run dev`，等待 \"ready\" 消息，捕获端口\n curl http://localhost:3000 返回 200\n 开发服务器运行于 http://localhost:3000\n\n\n\n 响应式仪表板布局 - 开发服务器运行于 http://localhost:3000\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 桌面端 (>1024px): 左侧边栏，右侧内容，顶部标题\n 2. 平板端 (768px): 侧边栏折叠为汉堡菜单\n 3. 移动端 (375px): 单列布局，出现底部导航\n 4. 任何尺寸无布局偏移或水平滚动\n \n 输入 \"approved\" 或描述布局问题\n\n```\n\n### checkpoint:decision（9%）\n\n**何时使用：** 人工必须做出影响实现方向的选择。\n\n**用于：**\n- 技术选型（哪个认证提供商、哪个数据库）\n- 架构决策（monorepo 还是独立仓库）\n- 设计选择（配色方案、布局方式）\n- 功能优先级（构建哪个变体）\n- 数据模型决策（模式结构）\n\n**结构：**\n```xml\n\n [正在决策的内容]\n [为什么这个决策重要]\n \n \n \n \n [如何表明选择]\n\n```\n\n**示例：认证提供商选择**\n```xml\n\n 选择认证提供商\n \n 应用需要用户认证。三个可靠选项各有权衡。\n \n \n \n \n \n \n 选择：supabase、clerk 或 nextauth\n\n```\n\n### checkpoint:human-action（1% - 罕见）\n\n**何时使用：** 操作没有 CLI/API 且需要仅人工交互，或者 Claude 在自动化过程中遇到认证门控。\n\n**仅用于：**\n- **认证门控** - Claude 尝试了 CLI/API 但需要凭证（这不是失败）\n- 邮箱验证链接（点击邮件）\n- 短信两步验证码（手机验证）\n- 人工账户审批（平台需要人工审核）\n- 信用卡 3D Secure 流程（基于 Web 的支付授权）\n- OAuth 应用审批（基于 Web 的审批）\n\n**不要用于预定的手动工作：**\n- 部署（使用 CLI - 如需要则认证门控）\n- 创建 webhooks/数据库（使用 API/CLI - 如需要则认证门控）\n- 运行构建/测试（使用 Bash 工具）\n- 创建文件（使用 Write 工具）\n\n**结构：**\n```xml\n\n [人工必须做什么 - Claude 已完成所有可自动化的]\n \n [Claude 已自动化的内容]\n [需要人工操作的一件事]\n \n [Claude 之后可以检查的内容]\n [如何继续]\n\n```\n\n**示例：认证门控（动态检查点）**\n```xml\n\n 部署到 Vercel\n .vercel/, vercel.json\n 运行 `vercel --yes` 进行部署\n vercel ls 显示部署，curl 返回 200\n\n\n\n\n\n 认证 Vercel CLI 以便我继续部署\n \n 我尝试部署但收到认证错误。\n 运行：vercel login\n 这将打开你的浏览器 - 完成认证流程。\n \n vercel whoami 返回你的账户邮箱\n 认证完成后输入 \"done\"\n\n\n\n\n\n 重试 Vercel 部署\n 运行 `vercel --yes`（已认证）\n vercel ls 显示部署，curl 返回 200\n\n```\n\n**关键区别：** 认证门控是 Claude 遇到认证错误时动态创建的。不是预定的 — Claude 先自动化，只有在被阻止时才请求凭证。\n\n## 执行协议\n\n当 Claude 遇到 `type=\"checkpoint:*\"` 时：\n\n1. **立即停止** - 不继续下一个任务\n2. **清晰显示检查点** 使用下面的格式\n3. **等待用户响应** - 不幻想完成\n4. **如可能则验证** - 检查文件、运行测试、任何指定的内容\n5. **恢复执行** - 仅在确认后继续下一个任务\n\n**对于 checkpoint:human-verify:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要验证 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 5/8 任务完成\n任务: 响应式仪表板布局\n\n已构建: /dashboard 的响应式仪表板\n\n如何验证:\n 1. 访问: http://localhost:3000/dashboard\n 2. 桌面端 (>1024px): 侧边栏可见，内容填充剩余空间\n 3. 平板端 (768px): 侧边栏折叠为图标\n 4. 移动端 (375px): 侧边栏隐藏，出现汉堡菜单\n\n────────────────────────────────────────────────────────\n→ 你的操作: 输入 \"approved\" 或描述问题\n────────────────────────────────────────────────────────\n```\n\n**对于 checkpoint:decision:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要决策 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 2/6 任务完成\n任务: 选择认证提供商\n\n决策: 我们应该使用哪个认证提供商？\n\n上下文: 需要用户认证。三个选项各有权衡。\n\n选项:\n 1. supabase - 与我们的数据库内置集成，免费额度\n 优点: 行级安全集成，慷慨的免费额度\n 缺点: UI 定制性较差，生态锁定\n\n 2. clerk - 最佳 DX，10k 用户后付费\n 优点: 精美的预构建 UI，优秀文档\n 缺点: 供应商锁定，规模化时价格问题\n\n 3. nextauth - 自托管，最大控制权\n 优点: 免费，无供应商锁定，广泛采用\n 缺点: 更多设置工作，自行 DIY 安全更新\n\n────────────────────────────────────────────────────────\n→ 你的操作: 选择 supabase、clerk 或 nextauth\n────────────────────────────────────────────────────────\n```\n\n## 认证门控\n\n**认证门控 = Claude 尝试了 CLI/API，收到认证错误。** 不是失败 — 是需要人工输入来解除阻止的门控。\n\n**模式：** Claude 尝试自动化 → 认证错误 → 创建 checkpoint:human-action → 用户认证 → Claude 重试 → 继续\n\n**门控协议：**\n1. 认识到这不是失败 - 缺少认证是正常的\n2. 停止当前任务 - 不要反复重试\n3. 动态创建 checkpoint:human-action\n4. 提供确切的认证步骤\n5. 验证认证有效\n6. 重试原始任务\n7. 正常继续\n\n**关键区别：**\n- 预定的检查点：\"我需要你做 X\"（错误 - Claude 应该自动化）\n- 认证门控：\"我尝试自动化 X 但需要凭证\"（正确 - 解除自动化阻止）\n\n## 自动化参考\n\n**规则：** 如果有 CLI/API，Claude 就做。绝不让人工执行可自动化的工作。\n\n### 服务 CLI 参考\n\n| 服务 | CLI/API | 关键命令 | 认证门控 |\n|------|---------|----------|----------|\n| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |\n| Railway | `railway` | `init`, `up`, `variables set` | `railway login` |\n| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` |\n| Stripe | `stripe` + API | `listen`, `trigger`, API 调用 | .env 中的 API key |\n| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` |\n| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` |\n| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` |\n| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |\n| Node | `npm`/`pnpm` | `install`, `run build`, `test`, `run dev` | N/A |\n| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |\n| Convex | `npx convex` | `dev`, `deploy`, `env set`, `env get` | `npx convex login` |\n\n### 环境变量自动化\n\n**Env 文件：** 使用 Write/Edit 工具。绝不让用户手动创建 .env。\n\n**通过 CLI 的仪表板环境变量：**\n\n| 平台 | CLI 命令 | 示例 |\n|------|----------|------|\n| Convex | `npx convex env set` | `npx convex env set OPENAI_API_KEY sk-...` |\n| Vercel | `vercel env add` | `vercel env add STRIPE_KEY production` |\n| Railway | `railway variables set` | `railway variables set API_KEY=value` |\n| Fly | `fly secrets set` | `fly secrets set DATABASE_URL=...` |\n| Supabase | `supabase secrets set` | `supabase secrets set MY_SECRET=value` |\n\n### 开发服务器自动化\n\n| 框架 | 启动命令 | 就绪信号 | 默认 URL |\n|------|----------|----------|----------|\n| Next.js | `npm run dev` | \"Ready in\" 或 \"started server\" | http://localhost:3000 |\n| Vite | `npm run dev` | \"ready in\" | http://localhost:5173 |\n| Convex | `npx convex dev` | \"Convex functions ready\" | N/A（仅后端）|\n| Express | `npm start` | \"listening on port\" | http://localhost:3000 |\n| Django | `python manage.py runserver` | \"Starting development server\" | http://localhost:8000 |\n\n**服务器生命周期：**\n```bash\n# 后台运行，捕获 PID\nnpm run dev &\nDEV_SERVER_PID=$!\n\n# 等待就绪（最多 30s）\ntimeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'\n```\n\n**端口冲突：** 终止陈旧进程（`lsof -ti:3000 | xargs kill`）或使用备用端口（`--port 3001`）。\n\n**服务器保持运行** 直到检查点结束。仅在计划完成、切换到生产环境或端口需要用于不同服务时终止。\n\n### CLI 安装处理\n\n| CLI | 自动安装？ | 命令 |\n|-----|------------|------|\n| npm/pnpm/yarn | 否 - 询问用户 | 用户选择包管理器 |\n| vercel | 是 | `npm i -g vercel` |\n| gh (GitHub) | 是 | `brew install gh` (macOS) 或 `apt install gh` (Linux) |\n| stripe | 是 | `npm i -g stripe` |\n| supabase | 是 | `npm i -g supabase` |\n| convex | 否 - 使用 npx | `npx convex`（无需安装）|\n| fly | 是 | `brew install flyctl` 或 curl 安装器 |\n| railway | 是 | `npm i -g @railway/cli` |\n\n**协议：** 尝试命令 → \"command not found\" → 可自动安装？→ 是：静默安装，重试 → 否：检查点请求用户安装。\n\n## 检查点前自动化失败处理\n\n| 失败 | 响应 |\n|------|------|\n| 服务器无法启动 | 检查错误，修复问题，重试（不进入检查点）|\n| 端口被占用 | 终止陈旧进程或使用备用端口 |\n| 缺少依赖 | 运行 `npm install`，重试 |\n| 构建错误 | 先修复错误（是 bug，不是检查点问题）|\n| 认证错误 | 创建认证门控检查点 |\n| 网络超时 | 带退避重试，如果持续则检查点 |\n\n**绝不呈现验证环境损坏的检查点。** 如果 `curl localhost:3000` 失败，不要让用户\"访问 localhost:3000\"。\n\n## 可自动化快速参考\n\n| 操作 | 可自动化？| Claude 做？|\n|------|------------|------------|\n| 部署到 Vercel | 是 (`vercel`) | 是 |\n| 创建 Stripe webhook | 是 (API) | 是 |\n| 写入 .env 文件 | 是 (Write 工具) | 是 |\n| 创建 Upstash DB | 是 (`upstash`) | 是 |\n| 运行测试 | 是 (`npm test`) | 是 |\n| 启动开发服务器 | 是 (`npm run dev`) | 是 |\n| 添加环境变量到 Convex | 是 (`npx convex env set`) | 是 |\n| 添加环境变量到 Vercel | 是 (`vercel env add`) | 是 |\n| 填充数据库 | 是 (CLI/API) | 是 |\n| 点击邮件验证链接 | 否 | 否 |\n| 输入带 3DS 的信用卡 | 否 | 否 |\n| 在浏览器中完成 OAuth | 否 | 否 |\n| 视觉验证 UI 是否正确 | 否 | 否 |\n| 测试交互式用户流程 | 否 | 否 |\n\n## 反模式\n\n### ❌ 错误：让用户启动开发服务器\n```xml\n\n 仪表板组件\n \n 1. 运行: npm run dev\n 2. 访问: http://localhost:3000/dashboard\n 3. 检查布局是否正确\n \n\n```\n**为什么错误：** Claude 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。\n\n### ✅ 正确：Claude 启动服务器，用户访问\n```xml\n\n 启动开发服务器\n 在后台运行 `npm run dev`\n curl localhost:3000 返回 200\n\n\n\n http://localhost:3000/dashboard 的仪表板（服务器运行中）\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 布局匹配设计\n 2. 无控制台错误\n \n\n```\n\n### ❌ 错误：让用户部署 / ✅ 正确：Claude 自动化\n```xml\n\n\n 部署到 Vercel\n 访问 vercel.com/new → 导入仓库 → 点击部署 → 复制 URL\n\n\n\n\n 部署到 Vercel\n 运行 `vercel --yes`。捕获 URL。\n vercel ls 显示部署，curl 返回 200\n\n\n\n 已部署到 {url}\n 访问 {url}，检查首页加载\n 输入 \"approved\"\n\n```\n\n## 摘要\n\n检查点规范化人工介入点用于验证和决策，而非手动工作。\n\n**黄金法则：** 如果 Claude 能自动化它，Claude 就必须自动化它。\n\n**检查点优先级：**\n1. **checkpoint:human-verify**（90%）- Claude 自动化一切，人工确认视觉/功能正确性\n2. **checkpoint:decision**（9%）- 人工做出架构/技术选择\n3. **checkpoint:human-action**（1%）- 真正无法避免的、没有 API/CLI 的手动步骤\n\n**何时不用检查点：**\n- Claude 可以编程验证的事情（测试、构建）\n- 文件操作（Claude 可以读取文件）\n- 代码正确性（测试和静态分析）\n- 任何可通过 CLI/API 自动化的内容","docs/zh-CN/references/continuation-format.md":"# 续接格式\n\n完成命令或工作流后展示下一步的标准格式。\n\n## 核心结构\n\n```\n---\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `{备选项 1}` — 描述\n- `{备选项 2}` — 描述\n\n---\n```\n\n## 格式规则\n\n1. **始终展示它是什么** — 名称 + 描述，绝不仅仅是一个命令路径\n2. **从源文件拉取上下文** — ROADMAP.md 用于阶段，PLAN.md `` 用于计划\n3. **命令用内联代码** — 反引号，易于复制粘贴，渲染为可点击链接\n4. **`/clear` 说明** — 始终包含，保持简洁但解释原因\n5. **用\"也可选\"而非\"其他选项\"** — 听起来更像应用\n6. **视觉分隔符** — 上下用 `---` 使其突出\n\n## 变体\n\n### 执行下一个计划\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- 执行前审查计划\n- `/gsd-discuss-phase --assumptions 2` — 检查假设\n\n---\n```\n\n### 执行阶段中最后一个计划\n\n添加注释说明这是最后一个计划以及接下来是什么：\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n阶段 2 的最后一个计划\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**完成后：**\n- 阶段 2 → 阶段 3 过渡\n- 下一步：**阶段 3: 核心功能** — 用户仪表板和设置\n\n---\n```\n\n### 规划阶段\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程\n\n`/gsd-plan-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 2` — 先收集上下文\n- `/gsd-plan-phase --research-phase 2` — 调查未知项\n- 审查路线图\n\n---\n```\n\n### 阶段完成，准备下一步\n\n在下一步操作前显示完成状态：\n\n```\n---\n\n## ✓ 阶段 2 完成\n\n3/3 计划已执行\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n`/gsd-plan-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 3` — 先收集上下文\n- `/gsd-plan-phase --research-phase 3` — 调查未知项\n- 回顾阶段 2 构建的内容\n\n---\n```\n\n### 多个同等选项\n\n当没有明确的主要操作时：\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n**直接规划：** `/gsd-plan-phase 3`\n\n**先讨论上下文：** `/gsd-discuss-phase 3`\n\n**研究未知项：** `/gsd-plan-phase --research-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n### 里程碑完成\n\n```\n---\n\n## 🎉 里程碑 v1.0 完成\n\n全部 4 个阶段已发布\n\n## ▶ 下一步\n\n**开始 v1.1** — 提问 → 研究 → 需求 → 路线图\n\n`/gsd-new-milestone`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n## 拉取上下文\n\n### 用于阶段（从 ROADMAP.md）：\n\n```markdown\n### 阶段 2: 认证\n**目标**: 带刷新令牌的 JWT 登录流程\n```\n\n提取：`**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程`\n\n### 用于计划（从 ROADMAP.md）：\n\n```markdown\n计划:\n- [ ] 02-03: 添加刷新令牌轮换\n```\n\n或从 PLAN.md ``：\n\n```xml\n\n添加带滑动过期窗口的刷新令牌轮换。\n\n目的: 在不影响安全性的前提下延长会话生命周期。\n\n```\n\n提取：`**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh`\n\n## 反模式\n\n### 不要：仅命令（无上下文）\n\n```\n## 继续\n\n运行 `/clear`，然后粘贴：\n/gsd-execute-phase 2\n```\n\n用户不知道 02-03 是关于什么的。\n\n### 不要：缺少 /clear 说明\n\n```\n`/gsd-plan-phase 3`\n\n先运行 /clear。\n```\n\n没有解释原因。用户可能跳过。\n\n### 不要：\"其他选项\" 措辞\n\n```\n其他选项：\n- 审查路线图\n```\n\n听起来像是事后补充。用\"也可选：\"替代。\n\n### 不要：用围栏代码块展示命令\n\n```\n```\n/gsd-plan-phase 3\n```\n```\n\n模板内的围栏代码块会造成嵌套歧义。用内联反引号替代。","docs/zh-CN/references/decimal-phase-calculation.md":"# 小数阶段计算\n\n为紧急插入计算下一个小数阶段编号。\n\n## 使用 gsd-sdk query\n\n```bash\n# 获取阶段 6 之后的下一个小数阶段\ngsd-sdk query phase.next-decimal 6\n```\n\n输出：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.1\",\n \"existing\": []\n}\n```\n\n已有小数时：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.3\",\n \"existing\": [\"06.1\", \"06.2\"]\n}\n```\n\n## 提取值\n\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick next)\nBASE_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick base_phase)\n```\n\n或使用 --raw 标志：\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --raw)\n# 返回: 06.1\n```\n\n## 示例\n\n| 已有阶段 | 下一个阶段 |\n|----------|------------|\n| 仅 06 | 06.1 |\n| 06, 06.1 | 06.2 |\n| 06, 06.1, 06.2 | 06.3 |\n| 06, 06.1, 06.3（有空缺）| 06.4 |\n\n## 目录命名\n\n小数阶段目录使用完整的小数编号：\n\n```bash\nSLUG=$(gsd-sdk query generate-slug \"$DESCRIPTION\" --raw)\nPHASE_DIR=\".planning/phases/${DECIMAL_PHASE}-${SLUG}\"\nmkdir -p \"$PHASE_DIR\"\n```\n\n示例：`.planning/phases/06.1-fix-critical-auth-bug/`\n","docs/zh-CN/references/git-integration.md":"\nGSD 框架的 Git 集成。\n\n\n\n\n**提交结果，而非过程。**\n\ngit 日志应该读起来像是发布内容的变更日志，而不是规划活动的日记。\n\n\n\n\n| 事件 | 提交? | 原因 |\n| ----------------------- | ------- | ------------------------------------------------ |\n| BRIEF + ROADMAP 创建 | 是 | 项目初始化 |\n| PLAN.md 创建 | 否 | 中间产物 - 与计划完成一起提交 |\n| RESEARCH.md 创建 | 否 | 中间产物 |\n| DISCOVERY.md 创建 | 否 | 中间产物 |\n| **任务完成** | 是 | 原子工作单元（每个任务 1 个提交） |\n| **计划完成** | 是 | 元数据提交（SUMMARY + STATE + ROADMAP） |\n| 交接创建 | 是 | WIP 状态保留 |\n\n\n\n\n\n```bash\n[ -d .git ] && echo \"GIT_EXISTS\" || echo \"NO_GIT\"\n```\n\n如果 NO_GIT：静默运行 `git init`。GSD 项目总是有自己的仓库。\n\n\n\n\n\n## 项目初始化（brief + roadmap 一起）\n\n```\ndocs: initialize [project-name] ([N] phases)\n\n[PROJECT.md 中的一句话描述]\n\nPhases:\n1. [phase-name]: [goal]\n2. [phase-name]: [goal]\n3. [phase-name]: [goal]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs: initialize [project-name] ([N] phases)\" --files .planning/\n```\n\n\n\n\n## 任务完成（计划执行期间）\n\n每个任务在完成后立即获得自己的提交。\n\n```\n{type}({phase}-{plan}): {task-name}\n\n- [关键变更 1]\n- [关键变更 2]\n- [关键变更 3]\n```\n\n**提交类型：**\n- `feat` - 新功能/功能\n- `fix` - Bug 修复\n- `test` - 仅测试（TDD RED 阶段）\n- `refactor` - 代码清理（TDD REFACTOR 阶段）\n- `perf` - 性能改进\n- `chore` - 依赖、配置、工具\n\n**示例：**\n\n```bash\n# 标准任务\ngit add src/api/auth.ts src/types/user.ts\ngit commit -m \"feat(08-02): create user registration endpoint\n\n- POST /auth/register validates email and password\n- Checks for duplicate users\n- Returns JWT token on success\n\"\n\n# TDD 任务 - RED 阶段\ngit add src/__tests__/jwt.test.ts\ngit commit -m \"test(07-02): add failing test for JWT generation\n\n- Tests token contains user ID claim\n- Tests token expires in 1 hour\n- Tests signature verification\n\"\n\n# TDD 任务 - GREEN 阶段\ngit add src/utils/jwt.ts\ngit commit -m \"feat(07-02): implement JWT generation\n\n- Uses jose library for signing\n- Includes user ID and expiry claims\n- Signs with HS256 algorithm\n\"\n```\n\n\n\n\n## 计划完成（所有任务完成后）\n\n所有任务提交后，最后一个元数据提交捕获计划完成。\n\n```\ndocs({phase}-{plan}): complete [plan-name] plan\n\nTasks completed: [N]/[N]\n- [Task 1 name]\n- [Task 2 name]\n- [Task 3 name]\n\nSUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs({phase}-{plan}): complete [plan-name] plan\" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md\n```\n\n**注意：** 代码文件不包含 - 已按任务提交。\n\n\n\n\n## 交接（WIP）\n\n```\nwip: [phase-name] paused at task [X]/[Y]\n\nCurrent: [task name]\n[如果阻塞:] Blocked: [reason]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"wip: [phase-name] paused at task [X]/[Y]\" --files .planning/\n```\n\n\n\n\n\n\n**旧方法（每个计划提交）：**\n```\na7f2d1 feat(checkout): Stripe payments with webhook verification\n3e9c4b feat(products): catalog with search, filters, and pagination\n8a1b2c feat(auth): JWT with refresh rotation using jose\n5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold\n2f4a8d docs: initialize ecommerce-app (5 phases)\n```\n\n**新方法（每个任务提交）：**\n```\n# Phase 04 - Checkout\n1a2b3c docs(04-01): complete checkout flow plan\n4d5e6f feat(04-01): add webhook signature verification\n7g8h9i feat(04-01): implement payment session creation\n0j1k2l feat(04-01): create checkout page component\n\n# Phase 03 - Products\n3m4n5o docs(03-02): complete product listing plan\n6p7q8r feat(03-02): add pagination controls\n9s0t1u feat(03-02): implement search and filters\n2v3w4x feat(03-01): create product catalog schema\n\n# Phase 02 - Auth\n5y6z7a docs(02-02): complete token refresh plan\n8b9c0d feat(02-02): implement refresh token rotation\n1e2f3g test(02-02): add failing test for token refresh\n4h5i6j docs(02-01): complete JWT setup plan\n7k8l9m feat(02-01): add JWT generation and validation\n0n1o2p chore(02-01): install jose library\n\n# Phase 01 - Foundation\n3q4r5s docs(01-01): complete scaffold plan\n6t7u8v feat(01-01): configure Tailwind and globals\n9w0x1y feat(01-01): set up Prisma with database\n2z3a4b feat(01-01): create Next.js 15 project\n\n# Initialization\n5c6d7e docs: initialize ecommerce-app (5 phases)\n```\n\n每个计划产生 2-4 个提交（任务 + 元数据）。清晰、细粒度、可 bisect。\n\n\n\n\n\n**仍不要提交（中间产物）：**\n- PLAN.md 创建（与计划完成一起提交）\n- RESEARCH.md（中间产物）\n- DISCOVERY.md（中间产物）\n- 小的规划调整\n- \"Fixed typo in roadmap\"\n\n**要提交（结果）：**\n- 每个任务完成（feat/fix/test/refactor）\n- 计划完成元数据（docs）\n- 项目初始化（docs）\n\n**关键原则：** 提交可工作的代码和已发布的结果，而非规划过程。\n\n\n\n\n\n## 为什么使用每任务提交？\n\n**AI 上下文工程：**\n- Git 历史成为未来 Claude 会话的主要上下文源\n- `git log --grep=\"{phase}-{plan}\"` 显示计划的所有工作\n- `git diff ^..` 显示每个任务的确切变更\n- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作\n\n**失败恢复：**\n- 任务 1 已提交 ✅，任务 2 失败 ❌\n- 下次会话中的 Claude：看到任务 1 完成，可以重试任务 2\n- 可以 `git reset --hard` 到最后一个成功的任务\n\n**调试：**\n- `git bisect` 找到确切的失败任务，而不仅仅是失败计划\n- `git blame` 将行追溯到特定任务上下文\n- 每个提交独立可回滚\n\n**可观察性：**\n- 独立开发者 + Claude 工作流受益于细粒度归因\n- 原子提交是 git 最佳实践\n- 当消费者是 Claude 而非人类时，\"提交噪音\"无关紧要\n\n","docs/zh-CN/references/git-planning-commit.md":"# Git 规划提交\n\n通过 `gsd-sdk query commit` 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态（与旧版 `gsd-tools.cjs commit` 行为相同）。\n\n## 通过 CLI 提交\n\n先传提交说明，然后用 `--files` 显式传入文件路径。`commit` 与 `commit-to-subrepo` 都应使用 `--files` 来声明要提交的路径。\n\n对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查：\n\n```bash\ngsd-sdk query commit \"docs({scope}): {description}\" --files .planning/STATE.md .planning/ROADMAP.md\n```\n\n如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。\n\n## 修改上次提交\n\n将 `.planning/` 文件变更合并到上次提交：\n\n```bash\ngsd-sdk query commit \"\" --files .planning/codebase/*.md --amend\n```\n\n## 提交消息模式\n\n| 命令 | 范围 | 示例 |\n|------|------|------|\n| plan-phase | phase | `docs(phase-03): create authentication plans` |\n| execute-phase | phase | `docs(phase-03): complete authentication phase` |\n| new-milestone | milestone | `docs: start milestone v1.1` |\n| remove-phase | chore | `chore: remove phase 17 (dashboard)` |\n| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |\n| add-phase | phase | `docs: add phase 07 (settings page)` |\n\n## 何时跳过\n\n- config 中 `commit_docs: false`\n- `.planning/` 被 gitignore\n- 无变更可提交（用 `git status --porcelain .planning/` 检查）\n","docs/zh-CN/references/model-profile-resolution.md":"# 模型配置解析\n\n在编排开始时解析一次模型配置，然后在所有 Task 生成时使用。\n\n## 解析模式\n\n```bash\nMODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '\"model_profile\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | grep -o '\"[^\"]*\"$' | tr -d '\"' || echo \"balanced\")\n```\n\n默认值：未设置或缺少 config 时为 `balanced`。\n\n## 查找表\n\n@~/.claude/get-shit-done/references/model-profiles.md\n\n在表中查找已解析配置对应的代理。将 model 参数传递给 Task 调用：\n\n```\nTask(\n prompt=\"...\",\n subagent_type=\"gsd-planner\",\n model=\"{resolved_model}\" # \"inherit\"、\"sonnet\" 或 \"haiku\"\n)\n```\n\n**注意：** Opus 级代理解析为 `\"inherit\"`（而非 `\"opus\"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。\n\n## 使用方法\n\n1. 在编排开始时解析一次\n2. 存储 profile 值\n3. 生成时在表中查找每个代理的模型\n4. 将 model 参数传递给每个 Task 调用（值：`\"inherit\"`、`\"sonnet\"`、`\"haiku\"`）","docs/zh-CN/references/model-profiles.md":"# 模型配置\n\n模型配置控制每个 GSD 代理使用哪个 Claude 模型。这允许平衡质量和 token 消耗。\n\n## 配置定义\n\n| 代理 | `quality` | `balanced` | `budget` |\n|-------|-----------|------------|----------|\n| gsd-planner | opus | opus | sonnet |\n| gsd-roadmapper | opus | sonnet | sonnet |\n| gsd-executor | opus | sonnet | sonnet |\n| gsd-phase-researcher | opus | sonnet | haiku |\n| gsd-project-researcher | opus | sonnet | haiku |\n| gsd-research-synthesizer | sonnet | sonnet | haiku |\n| gsd-debugger | opus | sonnet | sonnet |\n| gsd-codebase-mapper | sonnet | haiku | haiku |\n| gsd-verifier | sonnet | sonnet | haiku |\n| gsd-plan-checker | sonnet | sonnet | haiku |\n| gsd-integration-checker | sonnet | sonnet | haiku |\n| gsd-nyquist-auditor | sonnet | sonnet | haiku |\n\n## 配置理念\n\n**quality** - 最大推理能力\n- 所有决策代理使用 Opus\n- 只读验证使用 Sonnet\n- 适用场景：有配额可用、关键架构工作\n\n**balanced**（默认）- 智能分配\n- 仅规划（架构决策发生的地方）使用 Opus\n- 执行和研究使用 Sonnet（遵循明确指令）\n- 验证使用 Sonnet（需要推理，不仅仅是模式匹配）\n- 适用场景：正常开发、质量与成本的良好平衡\n\n**budget** - 最小化 Opus 使用\n- 编写代码的使用 Sonnet\n- 研究和验证使用 Haiku\n- 适用场景：节省配额、大量工作、不太关键的阶段\n\n## 解析逻辑\n\n编排器在生成代理前解析模型：\n\n```\n1. 读取 .planning/config.json\n2. 检查 model_overrides 是否有代理特定覆盖\n3. 如果没有覆盖，在配置表中查找代理\n4. 将 model 参数传递给 Task 调用\n```\n\n## 单代理覆盖\n\n覆盖特定代理而不更改整个配置：\n\n```json\n{\n \"model_profile\": \"balanced\",\n \"model_overrides\": {\n \"gsd-executor\": \"opus\",\n \"gsd-planner\": \"haiku\"\n }\n}\n```\n\n覆盖优先于配置。有效值：`opus`、`sonnet`、`haiku`。\n\n## 切换配置\n\n在 `.planning/config.json` 中设置 `model_profile` 键以更改配置文件。\n\n项目默认值：在 `.planning/config.json` 中设置：\n```json\n{\n \"model_profile\": \"balanced\"\n}\n```\n\n## 设计理由\n\n**为什么 gsd-planner 使用 Opus？**\n规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。\n\n**为什么 gsd-executor 使用 Sonnet？**\n执行者遵循明确的 PLAN.md 指令。计划已包含推理；执行只是实现。\n\n**为什么 balanced 中验证器使用 Sonnet（而非 Haiku）？**\n验证需要目标回溯推理 —— 检查代码是否**交付**了阶段承诺的内容，而不仅仅是模式匹配。Sonnet 处理得很好；Haiku 可能会遗漏细微的差距。\n\n**为什么 gsd-codebase-mapper 使用 Haiku？**\n只读探索和模式提取。不需要推理，只需从文件内容输出结构化结果。\n\n**为什么用 `inherit` 而不是直接传递 `opus`？**\nClaude Code 的 `\"opus\"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。GSD 为 opus 级代理返回 `\"inherit\"`，使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。","docs/zh-CN/references/phase-argument-parsing.md":"# 阶段参数解析\n\n为操作阶段的命令解析和规范化阶段参数。\n\n## 提取\n\n从 `$ARGUMENTS` 中：\n- 提取阶段编号（第一个数字参数）\n- 提取标志（以 `--` 为前缀）\n- 剩余文本为描述（用于 insert/add 命令）\n\n## 使用 gsd-tools\n\n`find-phase` 命令一步完成规范化和验证：\n\n```bash\nPHASE_INFO=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\")\n```\n\n返回 JSON 包含：\n- `found`: true/false\n- `directory`: 阶段目录的完整路径\n- `phase_number`: 规范化的编号（如 \"06\"、\"06.1\"）\n- `phase_name`: 名称部分（如 \"foundation\"）\n- `plans`: PLAN.md 文件数组\n- `summaries`: SUMMARY.md 文件数组\n\n## 手动规范化（遗留）\n\n将整数阶段补零到 2 位。保留小数后缀。\n\n```bash\n# 规范化阶段编号\nif [[ \"$PHASE\" =~ ^[0-9]+$ ]]; then\n # 整数: 8 → 08\n PHASE=$(printf \"%02d\" \"$PHASE\")\nelif [[ \"$PHASE\" =~ ^([0-9]+)\\.([0-9]+)$ ]]; then\n # 小数: 2.1 → 02.1\n PHASE=$(printf \"%02d.%s\" \"${BASH_REMATCH[1]}\" \"${BASH_REMATCH[2]}\")\nfi\n```\n\n## 验证\n\n使用 `roadmap get-phase` 验证阶段存在：\n\n```bash\nPHASE_CHECK=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" roadmap get-phase \"${PHASE}\")\nif [ \"$(printf '%s\\n' \"$PHASE_CHECK\" | jq -r '.found')\" = \"false\" ]; then\n echo \"ERROR: Phase ${PHASE} not found in roadmap\"\n exit 1\nfi\n```\n\n## 目录查找\n\n使用 `find-phase` 进行目录查找：\n\n```bash\nPHASE_DIR=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\" --raw)\n```","docs/zh-CN/references/planning-config.md":"\n\n`.planning/` 目录行为的配置选项。\n\n\n```json\n\"planning\": {\n \"commit_docs\": true,\n \"search_gitignored\": false\n},\n\"git\": {\n \"branching_strategy\": \"none\",\n \"phase_branch_template\": \"gsd/phase-{phase}-{slug}\",\n \"milestone_branch_template\": \"gsd/{milestone}-{slug}\"\n}\n```\n\n| 选项 | 默认值 | 描述 |\n|--------|---------|-------------|\n| `commit_docs` | `true` | 是否将规划工件提交到 git |\n| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` |\n| `git.branching_strategy` | `\"none\"` | Git 分支策略：`\"none\"`、`\"phase\"` 或 `\"milestone\"` |\n| `git.phase_branch_template` | `\"gsd/phase-{phase}-{slug}\"` | 阶段策略的分支模板 |\n| `git.milestone_branch_template` | `\"gsd/{milestone}-{slug}\"` | 里程碑策略的分支模板 |\n\n\n\n\n**当 `commit_docs: true`（默认）：**\n- 规划文件正常提交\n- SUMMARY.md、STATE.md、ROADMAP.md 在 git 中跟踪\n- 规划决策的完整历史保留\n\n**当 `commit_docs: false`：**\n- 跳过 `.planning/` 文件的所有 `git add`/`git commit`\n- 用户必须将 `.planning/` 添加到 `.gitignore`\n- 适用于：OSS 贡献、客户项目、保持规划私有\n\n**使用 `gsd-sdk query`（推荐）：**\n\n```bash\n# 提交时自动检查 commit_docs + gitignore：\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n\n# 通过 state load 加载配置（返回 JSON）：\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 在 JSON 输出中可用\n\n# 或使用包含 commit_docs 的 init 命令：\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 包含在所有 init 命令输出中\n```\n\n**自动检测：** 如果 `.planning/` 被 gitignore，无论 config.json 如何，`commit_docs` 自动为 `false`。这防止用户在 `.gitignore` 中有 `.planning/` 时出现 git 错误。\n\n**通过 CLI 提交（自动处理检查）：**\n\n```bash\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n```\n\nCLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。\n\n\n\n\n\n**当 `search_gitignored: false`（默认）：**\n- 标准 rg 行为（尊重 .gitignore）\n- 直接路径搜索有效：`rg \"pattern\" .planning/` 找到文件\n- 广泛搜索跳过 gitignored：`rg \"pattern\"` 跳过 `.planning/`\n\n**当 `search_gitignored: true`:**\n- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore`\n- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要\n\n**注意：** 大多数 GSD 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都有效。\n\n\n\n\n\n使用未提交模式：\n\n1. **设置配置：**\n ```json\n \"planning\": {\n \"commit_docs\": false,\n \"search_gitignored\": true\n }\n ```\n\n2. **添加到 .gitignore：**\n ```\n .planning/\n ```\n\n3. **已存在的跟踪文件：** 如果 `.planning/` 之前被跟踪：\n ```bash\n git rm -r --cached .planning/\n git commit -m \"chore: stop tracking planning docs\"\n ```\n\n4. **分支合并：** 当使用 `branching_strategy: phase` 或 `milestone` 时，`complete-milestone` 工作流在 `commit_docs: false` 时自动从暂存区移除 `.planning/` 文件，然后才进行合并提交。\n\n\n\n\n\n**分支策略：**\n\n| 策略 | 创建分支时机 | 分支范围 | 合并点 |\n|----------|---------------------|--------------|-------------|\n| `none` | 从不 | N/A | N/A |\n| `phase` | `execute-phase` 开始时 | 单个阶段 | 阶段后用户手动合并 |\n| `milestone` | 里程碑第一个 `execute-phase` | 整个里程碑 | `complete-milestone` 时 |\n\n**当 `git.branching_strategy: \"none\"`（默认）：**\n- 所有工作提交到当前分支\n- 标准 GSD 行为\n\n**当 `git.branching_strategy: \"phase\"`：**\n- `execute-phase` 在执行前创建/切换到分支\n- 分支名来自 `phase_branch_template`（如 `gsd/phase-03-authentication`）\n- 所有计划提交到该分支\n- 阶段完成后用户手动合并分支\n- `complete-milestone` 提供合并所有阶段分支的选项\n\n**当 `git.branching_strategy: \"milestone\"`：**\n- 里程碑的第一个 `execute-phase` 创建里程碑分支\n- 分支名来自 `milestone_branch_template`（如 `gsd/v1.0-mvp`）\n- 里程碑中所有阶段提交到同一分支\n- `complete-milestone` 提供将里程碑分支合并到 main 的选项\n\n**模板变量：**\n\n| 变量 | 可用于 | 描述 |\n|----------|--------------|-------------|\n| `{phase}` | phase_branch_template | 零填充阶段号（如 \"03\"） |\n| `{slug}` | 两者 | 小写、连字符名称 |\n| `{milestone}` | milestone_branch_template | 里程碑版本（如 \"v1.0\"） |\n\n**检查配置：**\n\n使用 `init execute-phase` 返回所有配置为 JSON：\n```bash\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n或使用 `state load` 获取配置值：\n```bash\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n**分支创建：**\n\n```bash\n# 阶段策略\nif [ \"$BRANCHING_STRATEGY\" = \"phase\" ]; then\n PHASE_SLUG=$(echo \"$PHASE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$PHASE_BRANCH_TEMPLATE\" | sed \"s/{phase}/$PADDED_PHASE/g\" | sed \"s/{slug}/$PHASE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n\n# 里程碑策略\nif [ \"$BRANCHING_STRATEGY\" = \"milestone\" ]; then\n MILESTONE_SLUG=$(echo \"$MILESTONE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$MILESTONE_BRANCH_TEMPLATE\" | sed \"s/{milestone}/$MILESTONE_VERSION/g\" | sed \"s/{slug}/$MILESTONE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n```\n\n**complete-milestone 时的合并选项：**\n\n| 选项 | Git 命令 | 结果 |\n|--------|-------------|--------|\n| Squash 合并（推荐） | `git merge --squash` | 每个分支单个干净提交 |\n| 带历史合并 | `git merge --no-ff` | 保留所有单独提交 |\n| 不合并直接删除 | `git branch -D` | 丢弃分支工作 |\n| 保留分支 | （无） | 后续手动处理 |\n\n推荐 Squash 合并 —— 保持 main 分支历史干净，同时在分支中保留完整开发历史（直到删除）。\n\n**使用场景：**\n\n| 策略 | 最适合 |\n|----------|----------|\n| `none` | 独立开发、简单项目 |\n| `phase` | 每阶段代码审查、细粒度回滚、团队协作 |\n| `milestone` | 发布分支、预发布环境、每个版本一个 PR |\n\n\n\n","docs/zh-CN/references/questioning.md":"# 提问指南\n\n项目初始化是梦想提取，而非需求收集。你在帮助用户发现和表达他们想构建的内容。这不是合同谈判 —— 是协作思考。\n\n## 理念\n\n**你是思考伙伴，不是面试官。**\n\n用户通常有一个模糊的想法。你的工作是帮助他们将其锐化。问一些让他们思考\"哦，我没想到那个\"或\"是的，这正是我的意思\"的问题。\n\n不要审问。协作。不要照本宣科。顺藤摸瓜。\n\n## 目标\n\n到提问结束时，你需要足够的清晰度来编写下游阶段可执行的 PROJECT.md：\n\n- **研究** 需要：研究什么领域、用户已知什么、存在哪些未知\n- **需求** 需要：足够清晰的愿景来界定 v1 功能\n- **路线图** 需要：足够清晰的愿景来分解为阶段、\"完成\"是什么样子\n- **plan-phase** 需要：可分解为任务的具体需求、实现选择的上下文\n- **execute-phase** 需要：可验证的成功标准、需求背后的\"为什么\"\n\n模糊的 PROJECT.md 会让每个下游阶段都在猜测。成本会叠加。\n\n## 如何提问\n\n**开放开始。** 让他们倾倒心理模型。不要用结构打断。\n\n**跟随能量。** 无论他们强调什么，深入那个。什么让他们兴奋？什么问题引发了这一切？\n\n**挑战模糊。** 绝不接受模糊回答。\"好\"意味着什么？\"用户\"指谁？\"简单\"是怎么简单？\n\n**让抽象具体。**\"带我走一遍使用这个。\"\"那实际看起来是什么样？\"\n\n**澄清歧义。**\"你说 Z 时，是指 A 还是 B？\"\"你提到了 X —— 跟我多说说。\"\n\n**知道何时停止。** 当你理解他们想要什么、为什么想要、给谁用、完成是什么样 —— 提议继续。\n\n## 问题类型\n\n以此作为灵感，不是清单。选择与话题相关的。\n\n**动机 —— 为什么存在：**\n- \"什么引发了这一切？\"\n- \"你今天在做什么会被这个替代？\"\n- \"如果这个存在，你会做什么？\"\n\n**具体性 —— 它实际是什么：**\n- \"带我走一遍使用这个\"\n- \"你说 X —— 那实际看起来是什么样？\"\n- \"给我一个例子\"\n\n**澄清 —— 他们什么意思：**\n- \"你说 Z 时，是指 A 还是 B？\"\n- \"你提到了 X —— 跟我多说说那个\"\n\n**成功 —— 你怎么知道它在工作：**\n- \"你怎么知道这个在工作？\"\n- \"完成是什么样子？\"\n\n## 使用 AskUserQuestion\n\n用 AskUserQuestion 帮助用户思考，通过呈现具体的选项供他们反应。\n\n**好选项：**\n- 他们可能意思的解读\n- 确认或否认的具体例子\n- 揭示优先级的具体选择\n\n**坏选项：**\n- 泛泛的类别（\"技术\"、\"业务\"、\"其他\"）\n- 预设答案的引导性选项\n- 选项太多（2-4 个理想）\n- 超过 12 个字符的标题（硬限制 —— 验证会拒绝）\n\n**示例 —— 模糊回答：**\n用户说\"它应该快\"\n\n- header: \"快\"\n- question: \"快是指？\"\n- options: [\"亚秒响应\", \"处理大数据集\", \"快速构建\", \"让我解释\"]\n\n**示例 —— 跟随话题：**\n用户提到\"对当前工具感到沮丧\"\n\n- header: \"沮丧\"\n- question: \"具体什么让你沮丧？\"\n- options: [\"点击太多\", \"缺少功能\", \"不可靠\", \"让我解释\"]\n\n**给用户的提示 —— 修改选项：**\n想要稍微修改某个选项版本的用户可以选择\"Other\"并通过编号引用选项：`#1 但仅用于指关节` 或 `#2 禁用分页`。这避免重新输入完整选项文本。\n\n## 自由格式规则\n\n**当用户想自由解释时，停止使用 AskUserQuestion。**\n\n如果用户选择\"Other\"且他们的回应表明他们想用自己的话描述（如\"让我描述一下\"、\"我来解释\"、\"别的\"、或任何非选择/修改现有选项的开放式回复），你必须：\n\n1. **用纯文本问你的追问** — 不通过 AskUserQuestion\n2. **等待他们在正常提示符下输入**\n3. **仅在处理他们的自由格式回应后恢复 AskUserQuestion**\n\n同样适用于如果你包含一个表明自由格式的选项（如\"让我解释\"或\"详细描述\"）且用户选择了它。\n\n**错误：** 用户说\"让我描述一下\" → AskUserQuestion(\"什么功能？\", [\"功能 A\", \"功能 B\", \"详细描述\"])\n**正确：** 用户说\"让我描述一下\" → \"请讲 —— 你在想什么？\"\n\n## 上下文清单\n\n以此作为**背景清单**，而非对话结构。进行时在脑中检查这些。如果还有缺口，自然地穿插问题。\n\n- [ ] 他们在构建什么（足够具体可以向陌生人解释）\n- [ ] 为什么它需要存在（驱动它的问题或渴望）\n- [ ] 给谁用的（即使只是他们自己）\n- [ ] \"完成\"是什么样子（可观察的结果）\n\n四件事。如果他们主动提供更多，捕获它。\n\n## 决策门控\n\n当你能写出清晰的 PROJECT.md 时，提议继续：\n\n- header: \"准备好了？\"\n- question: \"我想我理解你想要什么了。准备创建 PROJECT.md 吗？\"\n- options:\n - \"创建 PROJECT.md\" — 让我们继续\n - \"继续探索\" — 我想分享更多 / 再问我\n\n如果\"继续探索\" —— 问他们想添加什么或识别缺口并自然探查。\n\n循环直到选择\"创建 PROJECT.md\"。\n\n## 反模式\n\n- **走清单** — 不管他们说什么都按领域走\n- **套话问题** — \"你的核心价值是什么？\"\"什么超出范围？\"不管上下文\n- **企业腔** — \"你的成功标准是什么？\"\"你的利益相关者是谁？\"\n- **审问** — 不基于回答构建就连续发问\n- **急于求成** — 最小化问题以开始\"实际工作\"\n- **浅层接受** — 不探查就接受模糊回答\n- **过早约束** — 还不理解想法就问技术栈\n- **用户技能** — 绝不问用户的技术经验。Claude 来构建。","docs/zh-CN/references/tdd.md":"\nTDD 关乎设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现前思考行为，从而产生更清晰的接口和更可测试的代码。\n\n**原则：** 如果在编写 `fn` 之前能用 `expect(fn(input)).toBe(output)` 描述行为，TDD 会改善结果。\n\n**关键洞察：** TDD 工作本质上比标准任务更重 —— 它需要 2-3 个执行周期（RED → GREEN → REFACTOR），每个周期都涉及文件读取、测试运行和可能的调试。TDD 功能获得专门的计划，以确保整个周期内有完整的上下文可用。\n\n\n\n## 何时 TDD 提高质量\n\n**TDD 候选（创建 TDD 计划）：**\n- 有明确输入/输出的业务逻辑\n- 有请求/响应契约的 API 端点\n- 数据转换、解析、格式化\n- 验证规则和约束\n- 有可测试行为的算法\n- 状态机和工作流\n- 有清晰规格的工具函数\n\n**跳过 TDD（使用带 `type=\"auto\"` 任务的标准计划）：**\n- UI 布局、样式、视觉组件\n- 配置更改\n- 连接现有组件的胶水代码\n- 一次性脚本和迁移\n- 无业务逻辑的简单 CRUD\n- 探索性原型\n\n**启发式：** 能在编写 `fn` 之前写 `expect(fn(input)).toBe(output)` 吗？\n→ 能：创建 TDD 计划\n→ 不能：使用标准计划，事后添加测试（如需要）\n\n\n\n## TDD 计划结构\n\n每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 循环实现**一个功能**。\n\n```markdown\n---\nphase: XX-name\nplan: NN\ntype: tdd\n---\n\n\n[什么功能以及为什么]\nPurpose: [该功能 TDD 的设计收益]\nOutput: [可工作的、已测试的功能]\n\n\n\n@.planning/PROJECT.md\n@.planning/ROADMAP.md\n@relevant/source/files.ts\n\n\n\n [功能名称]\n [源文件, 测试文件]\n \n [可测试术语描述的预期行为]\n Cases: 输入 → 预期输出\n \n [测试通过后如何实现]\n\n\n\n[证明功能有效的测试命令]\n\n\n\n- 失败测试已编写并提交\n- 实现通过测试\n- 重构完成（如需要）\n- 所有 2-3 个提交都存在\n\n\n\n完成后，创建包含以下内容的 SUMMARY.md：\n- RED: 编写了什么测试，为什么失败\n- GREEN: 什么实现让它通过\n- REFACTOR: 做了什么清理（如有）\n- Commits: 生成的提交列表\n\n```\n\n**每个 TDD 计划一个功能。** 如果功能足够简单可以批量处理，那就足够简单可以跳过 TDD —— 使用标准计划，事后添加测试。\n\n\n\n## 红-绿-重构循环\n\n**RED - 编写失败测试：**\n1. 按项目约定创建测试文件\n2. 编写描述预期行为的测试（来自 `` 元素）\n3. 运行测试 - 必须**失败**\n4. 如果测试通过：功能已存在或测试有误。调查。\n5. 提交：`test({phase}-{plan}): add failing test for [feature]`\n\n**GREEN - 实现使其通过：**\n1. 编写使测试通过的最小代码\n2. 不耍小聪明，不优化 - 只让它工作\n3. 运行测试 - 必须**通过**\n4. 提交：`feat({phase}-{plan}): implement [feature]`\n\n**REFACTOR（如需要）：**\n1. 如果存在明显的改进，清理实现\n2. 运行测试 - 必须**仍然通过**\n3. 仅在做出更改时提交：`refactor({phase}-{plan}): clean up [feature]`\n\n**结果：** 每个 TDD 计划产生 2-3 个原子提交。\n\n\n\n## 好测试 vs 坏测试\n\n**测试行为，而非实现：**\n- 好：\"返回格式化的日期字符串\"\n- 坏：\"用正确参数调用 formatDate 辅助函数\"\n- 测试应该能经受重构\n\n**每个测试一个概念：**\n- 好：分别为有效输入、空输入、畸形输入编写测试\n- 坏：用多个断言检查所有边缘情况的单个测试\n\n**描述性名称：**\n- 好：\"should reject empty email\"、\"returns null for invalid ID\"\n- 坏：\"test1\"、\"handles error\"、\"works correctly\"\n\n**不包含实现细节：**\n- 好：测试公共 API、可观察行为\n- 坏：Mock 内部实现、测试私有方法、断言内部状态\n\n\n\n## 测试框架设置（如不存在）\n\n当执行 TDD 计划但没有配置测试框架时，作为 RED 阶段的一部分进行设置：\n\n**1. 检测项目类型：**\n```bash\n# JavaScript/TypeScript\nif [ -f package.json ]; then echo \"node\"; fi\n\n# Python\nif [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo \"python\"; fi\n\n# Go\nif [ -f go.mod ]; then echo \"go\"; fi\n\n# Rust\nif [ -f Cargo.toml ]; then echo \"rust\"; fi\n```\n\n**2. 安装最小框架：**\n| 项目 | 框架 | 安装 |\n|---------|-----------|---------|\n| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |\n| Node.js (Vite) | Vitest | `npm install -D vitest` |\n| Python | pytest | `pip install pytest` |\n| Go | testing | 内置 |\n| Rust | cargo test | 内置 |\n\n**3. 按需创建配置：**\n- Jest: 带 ts-jest preset 的 `jest.config.js`\n- Vitest: 带测试全局变量的 `vitest.config.ts`\n- pytest: `pytest.ini` 或 `pyproject.toml` 部分\n\n**4. 验证设置：**\n```bash\n# 运行空测试套件 - 应该以 0 个测试通过\nnpm test # Node\npytest # Python\ngo test ./... # Go\ncargo test # Rust\n```\n\n**5. 创建第一个测试文件：**\n遵循项目约定的测试位置：\n- 源文件旁边的 `*.test.ts` / `*.spec.ts`\n- `__tests__/` 目录\n- 根目录的 `tests/` 目录\n\n框架设置是第一个 TDD 计划 RED 阶段的一次性成本。\n\n\n\n## 错误处理\n\n**测试在 RED 阶段没有失败：**\n- 功能可能已存在 - 调查\n- 测试可能有误（没测试你以为的东西）\n- 前进前修复\n\n**测试在 GREEN 阶段没有通过：**\n- 调试实现\n- 不要跳到重构\n- 持续迭代直到绿色\n\n**测试在 REFACTOR 阶段失败：**\n- 撤销重构\n- 提交过早\n- 用更小的步骤重构\n\n**不相关的测试失败：**\n- 停下来调查\n- 可能表明耦合问题\n- 前进前修复\n\n\n\n## TDD 计划的提交模式\n\nTDD 计划产生 2-3 个原子提交（每个阶段一个）：\n\n```\ntest(08-02): add failing test for email validation\n\n- Tests valid email formats accepted\n- Tests invalid formats rejected\n- Tests empty input handling\n\nfeat(08-02): implement email validation\n\n- Regex pattern matches RFC 5322\n- Returns boolean for validity\n- Handles edge cases (empty, null)\n\nrefactor(08-02): extract regex to constant (optional)\n\n- Moved pattern to EMAIL_REGEX constant\n- No behavior changes\n- Tests still pass\n```\n\n**与标准计划对比：**\n- 标准计划：每个任务 1 个提交，每个计划 2-4 个提交\n- TDD 计划：单个功能 2-3 个提交\n\n两者遵循相同格式：`{type}({phase}-{plan}): {description}`\n\n**好处：**\n- 每个提交独立可回滚\n- Git bisect 在提交级别工作\n- 显示 TDD 纪律的清晰历史\n- 与整体提交策略一致\n\n\n\n## 上下文预算\n\nTDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。\n\n为什么更低：\n- RED 阶段：编写测试、运行测试、可能调试为什么没有失败\n- GREEN 阶段：实现、运行测试、可能对失败进行迭代\n- REFACTOR 阶段：修改代码、运行测试、验证无回归\n\n每个阶段涉及读取文件、运行命令、分析输出。来回往复本质上比线性任务执行更重。\n\n单一功能聚焦确保整个周期保持完整质量。\n","docs/zh-CN/references/ui-brand.md":"# UI 品牌规范\n\n面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。\n\n## 阶段横幅\n\n用于主要工作流过渡。\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► {阶段名称}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**阶段名称（大写）：**\n- `QUESTIONING`（提问）\n- `RESEARCHING`（研究）\n- `DEFINING REQUIREMENTS`（定义需求）\n- `CREATING ROADMAP`（创建路线图）\n- `PLANNING PHASE {N}`（规划阶段 {N}）\n- `EXECUTING WAVE {N}`（执行波次 {N}）\n- `VERIFYING`（验证）\n- `PHASE {N} COMPLETE ✓`（阶段 {N} 完成）\n- `MILESTONE COMPLETE 🎉`（里程碑完成）\n\n---\n\n## 检查点框\n\n需要用户操作。62 字符宽度。\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ CHECKPOINT: {类型} ║\n╚══════════════════════════════════════════════════════════════╝\n\n{内容}\n\n──────────────────────────────────────────────────────────────\n→ {操作提示}\n──────────────────────────────────────────────────────────────\n```\n\n**类型：**\n- `CHECKPOINT: 需要验证` → `→ 输入 \"approved\" 或描述问题`\n- `CHECKPOINT: 需要决策` → `→ 选择: option-a / option-b`\n- `CHECKPOINT: 需要操作` → `→ 完成后输入 \"done\"`\n\n---\n\n## 状态符号\n\n```\n✓ 完成 / 通过 / 已验证\n✗ 失败 / 缺失 / 阻塞\n◆ 进行中\n○ 待处理\n⚡ 自动批准\n⚠ 警告\n🎉 里程碑完成（仅在横幅中）\n```\n\n---\n\n## 进度显示\n\n**阶段/里程碑级别：**\n```\n进度: ████████░░ 80%\n```\n\n**任务级别：**\n```\n任务: 2/4 完成\n```\n\n**计划级别：**\n```\n计划: 3/5 完成\n```\n\n---\n\n## 生成指示器\n\n```\n◆ 正在生成研究员...\n\n◆ 并行生成 4 个研究员...\n → 技术栈研究\n → 功能研究\n → 架构研究\n → 陷阱研究\n\n✓ 研究员完成: STACK.md 已写入\n```\n\n---\n\n## 下一步区块\n\n始终在主要完成后。\n\n```\n───────────────────────────────────────────────────────────────\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n───────────────────────────────────────────────────────────────\n\n**也可选：**\n- (根据工作流选填可选命令，例如 `/gsd-progress --next`)\n\n───────────────────────────────────────────────────────────────\n```\n\n---\n\n## 错误框\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ ERROR ║\n╚══════════════════════════════════════════════════════════════╝\n\n{错误描述}\n\n**修复方法:** {解决步骤}\n```\n\n---\n\n## 表格\n\n```\n| 阶段 | 状态 | 计划 | 进度 |\n|------|------|------|------|\n| 1 | ✓ | 3/3 | 100% |\n| 2 | ◆ | 1/4 | 25% |\n| 3 | ○ | 0/2 | 0% |\n```\n\n---\n\n## 反模式\n\n- 变化的框/横幅宽度\n- 混合横幅样式（`===`、`---`、`***`）\n- 横幅中缺少 `GSD ►` 前缀\n- 随机 emoji（`🚀`、`✨`、`💫`）\n- 完成后缺少下一步区块","docs/zh-CN/references/verification-patterns.md":"# 验证模式\n\n如何验证不同类型的工件是真实实现，而非存根或占位符。\n\n\n**存在 ≠ 实现**\n\n文件存在并不意味着功能有效。验证必须检查：\n1. **存在** - 文件在预期路径\n2. **实质性** - 内容是真实实现，非占位符\n3. **已连接** - 已连接到系统的其他部分\n4. **功能性** - 调用时实际工作\n\n级别 1-3 可以编程检查。级别 4 通常需要人工验证。\n\n\n\n\n## 通用存根模式\n\n这些模式表明占位符代码，无论文件类型：\n\n**基于注释的存根：**\n```bash\n# 存根注释的 Grep 模式\ngrep -E \"(TODO|FIXME|XXX|HACK|PLACEHOLDER)\" \"$file\"\ngrep -E \"implement|add later|coming soon|will be\" \"$file\" -i\ngrep -E \"// \\.\\.\\.|/\\* \\.\\.\\. \\*/|# \\.\\.\\.\" \"$file\"\n```\n\n**输出中的占位符文本：**\n```bash\n# UI 占位符模式\ngrep -E \"placeholder|lorem ipsum|coming soon|under construction\" \"$file\" -i\ngrep -E \"sample|example|test data|dummy\" \"$file\" -i\ngrep -E \"\\[.*\\]|<.*>|\\{.*\\}\" \"$file\" # 模板括号未移除\n```\n\n**空或琐碎实现：**\n```bash\n# 什么都不做的函数\ngrep -E \"return null|return undefined|return \\{\\}|return \\[\\]\" \"$file\"\ngrep -E \"pass$|\\.\\.\\.|\\bnothing\\b\" \"$file\"\ngrep -E \"console\\.(log|warn|error).*only\" \"$file\" # 仅日志函数\n```\n\n**预期动态但硬编码的值：**\n```bash\n# 硬编码 ID、计数或内容\ngrep -E \"id.*=.*['\\\"].*['\\\"]\" \"$file\" # 硬编码字符串 ID\ngrep -E \"count.*=.*\\d+|length.*=.*\\d+\" \"$file\" # 硬编码计数\ngrep -E \"\\\\\\$\\d+\\.\\d{2}|\\d+ items\" \"$file\" # 硬编码显示值\n```\n\n\n\n\n\n## React/Next.js 组件\n\n**存在检查：**\n```bash\n# 文件存在且导出组件\n[ -f \"$component_path\" ] && grep -E \"export (default |)function|export const.*=.*\\(\" \"$component_path\"\n```\n\n**实质性检查：**\n```bash\n# 返回实际 JSX，非占位符\ngrep -E \"return.*<\" \"$component_path\" | grep -v \"return.*null\" | grep -v \"placeholder\" -i\n\n# 有有意义的内容（不仅仅是包装 div）\ngrep -E \"<[A-Z][a-zA-Z]+|className=|onClick=|onChange=\" \"$component_path\"\n\n# 使用 props 或 state（非静态）\ngrep -E \"props\\.|useState|useEffect|useContext|\\{.*\\}\" \"$component_path\"\n```\n\n**React 特有的存根模式：**\n```javascript\n// 危险信号 - 这些是存根：\nreturn
Component
\nreturn
Placeholder
\nreturn
{/* TODO */}
\nreturn

Coming soon

\nreturn null\nreturn <>\n\n// 也是存根 - 空处理器：\nonClick={() => {}}\nonChange={() => console.log('clicked')}\nonSubmit={(e) => e.preventDefault()} // 仅阻止默认，什么都不做\n```\n\n**连接检查：**\n```bash\n# 组件导入它需要的东西\ngrep -E \"^import.*from\" \"$component_path\"\n\n# Props 实际被使用（不仅仅是接收）\n# 查找解构或 props.X 用法\ngrep -E \"\\{ .* \\}.*props|\\bprops\\.[a-zA-Z]+\" \"$component_path\"\n\n# API 调用存在（对于数据获取组件）\ngrep -E \"fetch\\(|axios\\.|useSWR|useQuery|getServerSideProps|getStaticProps\" \"$component_path\"\n```\n\n**功能验证（需要人工）：**\n- 组件是否渲染可见内容？\n- 交互元素是否响应点击？\n- 数据是否加载并显示？\n- 错误状态是否适当显示？\n\n\n\n\n\n## API 路由（Next.js App Router / Express 等）\n\n**存在检查：**\n```bash\n# 路由文件存在\n[ -f \"$route_path\" ]\n\n# 导出 HTTP 方法处理器（Next.js App Router）\ngrep -E \"export (async )?(function|const) (GET|POST|PUT|PATCH|DELETE)\" \"$route_path\"\n\n# 或 Express 风格处理器\ngrep -E \"\\.(get|post|put|patch|delete)\\(\" \"$route_path\"\n```\n\n**实质性检查：**\n```bash\n# 有实际逻辑，不仅仅是 return 语句\nwc -l \"$route_path\" # 超过 10-15 行表明真实实现\n\n# 与数据源交互\ngrep -E \"prisma\\.|db\\.|mongoose\\.|sql|query|find|create|update|delete\" \"$route_path\" -i\n\n# 有错误处理\ngrep -E \"try|catch|throw|error|Error\" \"$route_path\"\n\n# 返回有意义的响应\ngrep -E \"Response\\.json|res\\.json|res\\.send|return.*\\{\" \"$route_path\" | grep -v \"message.*not implemented\" -i\n```\n\n**API 路由特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport async function POST() {\n return Response.json({ message: \"Not implemented\" })\n}\n\nexport async function GET() {\n return Response.json([]) // 空 array 无数据库查询\n}\n\nexport async function PUT() {\n return new Response() // 空响应\n}\n\n// 仅控制台日志：\nexport async function POST(req) {\n console.log(await req.json())\n return Response.json({ ok: true })\n}\n```\n\n**连接检查：**\n```bash\n# 导入数据库/服务客户端\ngrep -E \"^import.*prisma|^import.*db|^import.*client\" \"$route_path\"\n\n# 实际使用请求体（对于 POST/PUT）\ngrep -E \"req\\.json\\(\\)|req\\.body|request\\.json\\(\\)\" \"$route_path\"\n\n# 验证输入（不仅仅信任请求）\ngrep -E \"schema\\.parse|validate|zod|yup|joi\" \"$route_path\"\n```\n\n**功能验证（人工或自动化）：**\n- GET 是否从数据库返回真实数据？\n- POST 是否实际创建记录？\n- 错误响应是否有正确的状态码？\n- 认证检查是否实际执行？\n\n\n\n\n\n## 数据库模式（Prisma / Drizzle / SQL）\n\n**存在检查：**\n```bash\n# 模式文件存在\n[ -f \"prisma/schema.prisma\" ] || [ -f \"drizzle/schema.ts\" ] || [ -f \"src/db/schema.sql\" ]\n\n# 模型/表已定义\ngrep -E \"^model $model_name|CREATE TABLE $table_name|export const $table_name\" \"$schema_path\"\n```\n\n**实质性检查：**\n```bash\n# 有预期字段（不仅仅是 id）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"^\\s+\\w+\\s+\\w+\"\n\n# 有预期关系\ngrep -E \"@relation|REFERENCES|FOREIGN KEY\" \"$schema_path\"\n\n# 有适当的字段类型（不全是 String）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"Int|DateTime|Boolean|Float|Decimal|Json\"\n```\n\n**模式特有的存根模式：**\n```prisma\n// 危险信号 - 这些是存根：\nmodel User {\n id String @id\n // TODO: add fields\n}\n\nmodel Message {\n id String @id\n content String // 只有一个真实字段\n}\n\n// 缺少关键字段：\nmodel Order {\n id String @id\n // 缺少: userId, items, total, status, createdAt\n}\n```\n\n**连接检查：**\n```bash\n# 迁移存在且已应用\nls prisma/migrations/ 2>/dev/null | wc -l # 应该 > 0\nnpx prisma migrate status 2>/dev/null | grep -v \"pending\"\n\n# 客户端已生成\n[ -d \"node_modules/.prisma/client\" ]\n```\n\n**功能验证：**\n```bash\n# 可以查询表（自动化）\nnpx prisma db execute --stdin <<< \"SELECT COUNT(*) FROM $table_name\"\n```\n\n\n\n\n\n## 自定义 Hooks 和工具\n\n**存在检查：**\n```bash\n# 文件存在且导出函数\n[ -f \"$hook_path\" ] && grep -E \"export (default )?(function|const)\" \"$hook_path\"\n```\n\n**实质性检查：**\n```bash\n# Hook 使用 React hooks（对于自定义 hooks）\ngrep -E \"useState|useEffect|useCallback|useMemo|useRef|useContext\" \"$hook_path\"\n\n# 有有意义的返回值\ngrep -E \"return \\{|return \\[\" \"$hook_path\"\n\n# 超过琐碎长度\n[ $(wc -l < \"$hook_path\") -gt 10 ]\n```\n\n**Hooks 特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport function useAuth() {\n return { user: null, login: () => {}, logout: () => {} }\n}\n\nexport function useCart() {\n const [items, setItems] = useState([])\n return { items, addItem: () => console.log('add'), removeItem: () => {} }\n}\n\n// 硬编码返回：\nexport function useUser() {\n return { name: \"Test User\", email: \"test@example.com\" }\n}\n```\n\n**连接检查：**\n```bash\n# Hook 实际在某处被导入\ngrep -r \"import.*$hook_name\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n\n# Hook 实际被调用\ngrep -r \"$hook_name()\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n```\n\n\n\n\n\n## 环境变量和配置\n\n**存在检查：**\n```bash\n# .env 文件存在\n[ -f \".env\" ] || [ -f \".env.local\" ]\n\n# 必需变量已定义\ngrep -E \"^$VAR_NAME=\" .env .env.local 2>/dev/null\n```\n\n**实质性检查：**\n```bash\n# 变量有实际值（非占位符）\ngrep -E \"^$VAR_NAME=.+\" .env .env.local 2>/dev/null | grep -v \"your-.*-here|xxx|placeholder|TODO\" -i\n\n# 值对类型看起来有效：\n# - URL 应以 http 开头\n# - 密钥应足够长\n# - 布尔值应为 true/false\n```\n\n**环境变量特有的存根模式：**\n```bash\n# 危险信号 - 这些是存根：\nDATABASE_URL=your-database-url-here\nSTRIPE_SECRET_KEY=sk_test_xxx\nAPI_KEY=placeholder\nNEXT_PUBLIC_API_URL=http://localhost:3000 # 生产环境仍指向 localhost\n```\n\n**连接检查：**\n```bash\n# 变量实际在代码中使用\ngrep -r \"process\\.env\\.$VAR_NAME|env\\.$VAR_NAME\" src/ --include=\"*.ts\" --include=\"*.tsx\"\n\n# 变量在验证模式中（如果使用 zod 等验证 env）\ngrep -E \"$VAR_NAME\" src/env.ts src/env.mjs 2>/dev/null\n```\n\n\n\n\n\n## 连接验证模式\n\n连接验证检查组件是否实际通信。这是大多数存根隐藏的地方。\n\n### 模式：组件 → API\n\n**检查：** 组件是否实际调用 API？\n\n```bash\n# 查找 fetch/axios 调用\ngrep -E \"fetch\\(['\\\"].*$api_path|axios\\.(get|post).*$api_path\" \"$component_path\"\n\n# 验证未被注释掉\ngrep -E \"fetch\\(|axios\\.\" \"$component_path\" | grep -v \"^.*//.*fetch\"\n\n# 检查响应被使用\ngrep -E \"await.*fetch|\\.then\\(|setData|setState\" \"$component_path\"\n```\n\n**危险信号：**\n```typescript\n// Fetch 存在但响应被忽略：\nfetch('/api/messages') // 无 await，无 .then，无赋值\n\n// Fetch 在注释中：\n// fetch('/api/messages').then(r => r.json()).then(setMessages)\n\n// Fetch 到错误的端点：\nfetch('/api/message') // 拼写错误 - 应该是 /api/messages\n```\n\n### 模式：API → 数据库\n\n**检查：** API 路由是否实际查询数据库？\n\n```bash\n# 查找数据库调用\ngrep -E \"prisma\\.$model|db\\.query|Model\\.find\" \"$route_path\"\n\n# 验证被 await\ngrep -E \"await.*prisma|await.*db\\.\" \"$route_path\"\n\n# 检查结果被返回\ngrep -E \"return.*json.*data|res\\.json.*result\" \"$route_path\"\n```\n\n**危险信号：**\n```typescript\n// 查询存在但结果未返回：\nawait prisma.message.findMany()\nreturn Response.json({ ok: true }) // 返回静态值，非查询结果\n\n// 查询未被 await：\nconst messages = prisma.message.findMany() // 缺少 await\nreturn Response.json(messages) // 返回 Promise，非数据\n```\n\n### 模式：表单 → 处理器\n\n**检查：** 表单提交是否实际做些什么？\n\n```bash\n# 查找 onSubmit 处理器\ngrep -E \"onSubmit=\\{|handleSubmit\" \"$component_path\"\n\n# 检查处理器有内容\ngrep -A 10 \"onSubmit.*=\" \"$component_path\" | grep -E \"fetch|axios|mutate|dispatch\"\n\n# 验证不仅仅是 preventDefault\ngrep -A 5 \"onSubmit\" \"$component_path\" | grep -v \"only.*preventDefault\" -i\n```\n\n**危险信号：**\n```typescript\n// 处理器仅阻止默认：\nonSubmit={(e) => e.preventDefault()}\n\n// 处理器仅日志：\nconst handleSubmit = (data) => {\n console.log(data)\n}\n\n// 处理器为空：\nonSubmit={() => {}}\n```\n\n### 模式：状态 → 渲染\n\n**检查：** 组件是否渲染状态，而非硬编码内容？\n\n```bash\n# 查找 JSX 中的状态使用\ngrep -E \"\\{.*messages.*\\}|\\{.*data.*\\}|\\{.*items.*\\}\" \"$component_path\"\n\n# 检查状态的 map/render\ngrep -E \"\\.map\\(|\\.filter\\(|\\.reduce\\(\" \"$component_path\"\n\n# 验证动态内容\ngrep -E \"\\{[a-zA-Z_]+\\.\" \"$component_path\" # 变量插值\n```\n\n**危险信号：**\n```tsx\n// 硬编码而非状态：\nreturn
\n

Message 1

\n

Message 2

\n
\n\n// 状态存在但未渲染：\nconst [messages, setMessages] = useState([])\nreturn
No messages
// 总是显示 \"no messages\"\n\n// 渲染错误的状态：\nconst [messages, setMessages] = useState([])\nreturn
{otherData.map(...)}
// 使用不同数据\n```\n\n\n\n\n\n## 快速验证清单\n\n对于每种工件类型，运行此清单：\n\n### 组件清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数/const 组件\n- [ ] 返回 JSX（非 null/空）\n- [ ] 渲染中无占位符文本\n- [ ] 使用 props 或 state（非静态）\n- [ ] 事件处理器有真实实现\n- [ ] 导入正确解析\n- [ ] 在应用某处被使用\n\n### API 路由清单\n- [ ] 文件存在于预期路径\n- [ ] 导出 HTTP 方法处理器\n- [ ] 处理器超过 5 行\n- [ ] 查询数据库或服务\n- [ ] 返回有意义的响应（非空/占位符）\n- [ ] 有错误处理\n- [ ] 验证输入\n- [ ] 从前端调用\n\n### 模式清单\n- [ ] 模型/表已定义\n- [ ] 有所有预期字段\n- [ ] 字段有适当类型\n- [ ] 如需要关系已定义\n- [ ] 迁移存在且已应用\n- [ ] 客户端已生成\n\n### Hook/工具清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数\n- [ ] 有有意义的实现（非空返回）\n- [ ] 在应用某处被使用\n- [ ] 返回值被消费\n\n### 连接清单\n- [ ] 组件 → API: fetch/axios 调用存在且使用响应\n- [ ] API → 数据库: 查询存在且结果返回\n- [ ] 表单 → 处理器: onSubmit 调用 API/mutation\n- [ ] 状态 → 渲染: 状态变量出现在 JSX 中\n\n\n\n\n\n## 自动化验证方法\n\n对于验证子代理，使用此模式：\n\n```bash\n# 1. 检查存在\ncheck_exists() {\n [ -f \"$1\" ] && echo \"EXISTS: $1\" || echo \"MISSING: $1\"\n}\n\n# 2. 检查存根模式\ncheck_stubs() {\n local file=\"$1\"\n local stubs=$(grep -c -E \"TODO|FIXME|placeholder|not implemented\" \"$file\" 2>/dev/null || echo 0)\n [ \"$stubs\" -gt 0 ] && echo \"STUB_PATTERNS: $stubs in $file\"\n}\n\n# 3. 检查连接（组件调用 API）\ncheck_wiring() {\n local component=\"$1\"\n local api_path=\"$2\"\n grep -q \"$api_path\" \"$component\" && echo \"WIRED: $component → $api_path\" || echo \"NOT_WIRED: $component → $api_path\"\n}\n\n# 4. 检查实质性（超过 N 行，有预期模式）\ncheck_substantive() {\n local file=\"$1\"\n local min_lines=\"$2\"\n local pattern=\"$3\"\n local lines=$(wc -l < \"$file\" 2>/dev/null || echo 0)\n local has_pattern=$(grep -c -E \"$pattern\" \"$file\" 2>/dev/null || echo 0)\n [ \"$lines\" -ge \"$min_lines\" ] && [ \"$has_pattern\" -gt 0 ] && echo \"SUBSTANTIVE: $file\" || echo \"THIN: $file ($lines lines, $has_pattern matches)\"\n}\n```\n\n对每个必须有工件运行这些检查。汇总结果到 VERIFICATION.md。\n\n\n\n\n\n## 何时需要人工验证\n\n有些事情无法编程验证。标记这些需要人工测试：\n\n**始终人工：**\n- 视觉外观（看起来对吗？）\n- 用户流程完成（能实际做那件事吗？）\n- 实时行为（WebSocket、SSE）\n- 外部服务集成（Stripe、邮件发送）\n- 错误消息清晰度（消息有帮助吗？）\n- 性能感觉（感觉快吗？）\n\n**如不确定则人工：**\n- grep 无法追踪的复杂连接\n- 依赖状态的动态行为\n- 边缘情况和错误状态\n- 移动端响应式\n- 无障碍性\n\n**人工验证请求格式：**\n```markdown\n## 需要人工验证\n\n### 1. 聊天消息发送\n**测试：** 输入消息并点击发送\n**预期：** 消息出现在列表中，输入框清空\n**检查：** 刷新后消息是否持久？\n\n### 2. 错误处理\n**测试：** 断开网络，尝试发送\n**预期：** 错误消息出现，消息未丢失\n**检查：** 重连后能重试吗？\n```\n\n\n\n\n\n## 检查点前自动化\n\n关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议，请参阅：\n\n**@~/.claude/get-shit-done/references/checkpoints.md** → `` 部分\n\n关键原则：\n- Claude 在呈现检查点**之前**设置验证环境\n- 用户从不运行 CLI 命令（仅访问 URL）\n- 服务器生命周期：检查点前启动、处理端口冲突、持续运行\n- CLI 安装：安全处自动安装，否则检查点让用户选择\n- 错误处理：检查点前修复损坏环境，绝不呈现有失败设置的检查点\n\n","get-shit-done/references/sketch-theme-system.md":"# Shared Theme System\n\nAll sketches share a CSS variable theme so design decisions compound across sketches.\n\n## Setup\n\nOn the first sketch, create `.planning/sketches/themes/` with a default theme:\n\n```\n.planning/sketches/\n themes/\n default.css <- all sketches link to this\n 001-dashboard-layout/\n index.html <- links to ../themes/default.css\n```\n\n## Theme File Structure\n\nEach theme defines CSS custom properties only — no component styles, no layout rules. Just the visual vocabulary:\n\n```css\n:root {\n /* Colors */\n --color-bg: #fafafa;\n --color-surface: #ffffff;\n --color-border: #e5e5e5;\n --color-text: #1a1a1a;\n --color-text-muted: #6b6b6b;\n --color-primary: #2563eb;\n --color-primary-hover: #1d4ed8;\n --color-accent: #f59e0b;\n --color-danger: #ef4444;\n --color-success: #22c55e;\n\n /* Typography */\n --font-sans: 'Inter', system-ui, sans-serif;\n --font-mono: 'JetBrains Mono', monospace;\n --text-xs: 0.75rem;\n --text-sm: 0.875rem;\n --text-base: 1rem;\n --text-lg: 1.125rem;\n --text-xl: 1.25rem;\n --text-2xl: 1.5rem;\n --text-3xl: 1.875rem;\n\n /* Spacing */\n --space-1: 4px;\n --space-2: 8px;\n --space-3: 12px;\n --space-4: 16px;\n --space-6: 24px;\n --space-8: 32px;\n --space-12: 48px;\n\n /* Shapes */\n --radius-sm: 4px;\n --radius-md: 8px;\n --radius-lg: 12px;\n --radius-full: 9999px;\n\n /* Shadows */\n --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);\n --shadow-md: 0 4px 6px rgba(0,0,0,0.07);\n --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);\n}\n```\n\nAdapt the default theme to match the mood/direction established during intake. The values above are a starting point — change colors, fonts, spacing, and shapes to match the agreed aesthetic.\n\n## Linking\n\nEvery sketch links to the theme:\n\n```html\n\n```\n\n## Creating New Themes\n\nWhen a sketch reveals an aesthetic fork (\"should this feel clinical or warm?\"), create both as theme files rather than arguing about it. The user can switch and feel the difference.\n\nName themes descriptively: `midnight.css`, `warm-minimal.css`, `brutalist.css`.\n\n## Theme Switcher\n\nInclude in every sketch (part of the sketch toolbar):\n\n```html\n\n```\n\nDynamically populate options by listing available theme files, or hardcode the known themes.\n","get-shit-done/templates/copilot-instructions.md":"# Instructions for GSD\n\n- Use the get-shit-done skill when the user asks for GSD or uses a `gsd-*` command.\n- Treat `/gsd-...` or `gsd-...` as command invocations and load the matching file from `.github/skills/gsd-*`.\n- When a command says to spawn a subagent, prefer a matching custom agent from `.github/agents`.\n- Do not apply GSD workflows unless the user explicitly asks for them.\n- After completing any `gsd-*` command (or any deliverable it triggers: feature, bug fix, tests, docs, etc.), ALWAYS: (1) offer the user the next step by prompting via `ask_user`; repeat this feedback loop until the user explicitly indicates they are done.\n"},"files":{"AGENTS.md":"# Repository Guidelines\n\n## Active Discussions\n\nFor current work on **Grok Build compatibility** and multi-runtime synchronization across Grok Build, Claude Code, Gemini CLI, and Codex, see:\n\n- `docs/discussions/grok-build-support-2026-05.md`\n\n## Project Structure & Module Organization\n\nThis repository ships GSD as a Node.js CLI and SDK. Root package entry points live in `bin/`, scripts in `scripts/`, runtime hooks in `hooks/`, command definitions in `commands/gsd/`, and workflow/template content in `get-shit-done/`. Agent role files are in `agents/`; docs are in `docs/`; logos and terminal images are in `assets/`. Root tests are in `tests/*.test.cjs`. The TypeScript SDK is isolated under `sdk/`, with source and Vitest tests in `sdk/src/`.\n\n## Build, Test, and Development Commands\n\nUse Node.js `>=22`.\n\n- `npm install`: install root dependencies.\n- `npm test`: builds the SDK first, then runs root `node:test` suites via `scripts/run-tests.cjs`.\n- `npm run test:coverage`: runs root tests with `c8` and enforces 70% line coverage for included CommonJS library files.\n- `npm run build:hooks`: rebuilds generated hook artifacts.\n- `npm run build:sdk`: installs SDK dependencies and builds TypeScript.\n- `cd sdk && npm test`: runs SDK Vitest unit and integration projects.\n- `cd sdk && npm run build`: type-checks and emits `sdk/dist/`.\n\n## Coding Style & Naming Conventions\n\nMatch the existing style in the edited area. Root JavaScript is CommonJS, generally strict-mode, two-space indentation, semicolons, `const`/`let`, and `node:` imports for built-ins. SDK code is strict TypeScript using ESM/`NodeNext`. Keep command, workflow, and test filenames kebab-case, for example `commands/gsd/plan-phase.md` and `tests/bug-2396-makefile-test-priority.test.cjs`. Agent files use `gsd-*.md`. Avoid unrelated formatting and unnecessary dependencies.\n\n## Testing Guidelines\n\nRoot tests use Node’s built-in `node:test` and `node:assert/strict`; do not add Jest, Mocha, or Chai. Prefer helpers from `tests/helpers.cjs` for temporary projects, cleanup, and CLI execution. Name root tests `*.test.cjs`; run one with `node --test tests/name.test.cjs`. SDK tests use Vitest with `*.test.ts` for unit tests and `*.integration.test.ts` for integration tests.\n\n## Commit & Pull Request Guidelines\n\nRecent history follows Conventional Commit prefixes such as `fix:`, `feat:`, and `ci:`, often with issue references: `fix(#2623): resolve parent .planning root...`. Keep commits scoped and descriptive.\n\nEvery PR must link an approved or confirmed issue with `Closes #123`, `Fixes #123`, or `Resolves #123`. Use the matching template in `.github/PULL_REQUEST_TEMPLATE/`. Include behavior changes, root cause when relevant, test evidence, affected platforms/runtimes, and update `CHANGELOG.md` or docs for user-facing changes.\n\n## Security & Configuration Tips\n\nDo not commit secrets, local config, or generated worktree artifacts. Before release-facing changes, run the relevant scan scripts in `scripts/`, especially `secret-scan.sh`, `base64-scan.sh`, and `prompt-injection-scan.sh`.\n","commands/gsd/milestone-summary.md":"---\ntype: prompt\nname: gsd:milestone-summary\ndescription: Generate a comprehensive project summary from milestone artifacts for team onboarding and review\nargument-hint: \"[version]\"\nallowed-tools:\n - Read\n - Write\n - Bash\n - Grep\n - Glob\n---\n\n\nGenerate a structured milestone summary for team onboarding and project review. Reads completed milestone artifacts (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION files) and produces a human-friendly overview of what was built, how, and why.\n\nPurpose: Enable new team members to understand a completed project by reading one document and asking follow-up questions.\nOutput: MILESTONE_SUMMARY written to `.planning/reports/`, presented inline, optional interactive Q&A.\n\n\n\n@~/.claude/get-shit-done/workflows/milestone-summary.md\n\n\n\n**Project files:**\n- `.planning/ROADMAP.md`\n- `.planning/PROJECT.md`\n- `.planning/STATE.md`\n- `.planning/RETROSPECTIVE.md`\n- `.planning/milestones/v{version}-ROADMAP.md` (if archived)\n- `.planning/milestones/v{version}-REQUIREMENTS.md` (if archived)\n- `.planning/phases/*-*/` (SUMMARY.md, VERIFICATION.md, CONTEXT.md, RESEARCH.md)\n\n**User input:**\n- Version: $ARGUMENTS (optional — defaults to current/latest milestone)\n\n\n\nExecute end-to-end.\n\n\n\n- Milestone version resolved (from args, STATE.md, or archive scan)\n- All available artifacts read (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION, RESEARCH, RETROSPECTIVE)\n- Summary document written to `.planning/reports/MILESTONE_SUMMARY-v{version}.md`\n- All 7 sections generated (Overview, Architecture, Phases, Decisions, Requirements, Tech Debt, Getting Started)\n- Summary presented inline to user\n- Interactive Q&A offered\n- STATE.md updated\n\n","docs/AGENTS.md":"# GSD Agent Reference\n\n> Full role cards for 21 primary agents plus concise stubs for 12 advanced/specialized agents (33 shipped agents total). The `agents/` directory and [`docs/INVENTORY.md`](INVENTORY.md) are the authoritative roster; see [Architecture](ARCHITECTURE.md) for context.\n\n---\n\n## Overview\n\nGSD uses a multi-agent architecture where thin orchestrators (workflow files) spawn specialized agents with fresh context windows. Each agent has a focused role, limited tool access, and produces specific artifacts.\n\n### Agent Categories\n\n> The table below covers the **21 primary agents** detailed in this section. Twelve additional shipped agents (pattern-mapper, debug-session-manager, code-reviewer, code-fixer, ai-researcher, domain-researcher, eval-planner, eval-auditor, framework-selector, intel-updater, doc-classifier, doc-synthesizer) have concise stubs in the [Advanced and Specialized Agents](#advanced-and-specialized-agents) section below. For the authoritative 33-agent roster, see [`docs/INVENTORY.md`](INVENTORY.md) and the `agents/` directory.\n\n| Category | Count | Agents |\n|----------|-------|--------|\n| Researchers | 3 | project-researcher, phase-researcher, ui-researcher |\n| Analyzers | 2 | assumptions-analyzer, advisor-researcher |\n| Synthesizers | 1 | research-synthesizer |\n| Planners | 1 | planner |\n| Roadmappers | 1 | roadmapper |\n| Executors | 1 | executor |\n| Checkers | 3 | plan-checker, integration-checker, ui-checker |\n| Verifiers | 1 | verifier |\n| Auditors | 3 | nyquist-auditor, ui-auditor, security-auditor |\n| Mappers | 1 | codebase-mapper |\n| Debuggers | 1 | debugger |\n| Doc Writers | 2 | doc-writer, doc-verifier |\n| Profilers | 1 | user-profiler |\n\n---\n\n## Agent Details\n\n### gsd-project-researcher\n\n**Role:** Researches domain ecosystem before roadmap creation.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project`, `/gsd-new-milestone` |\n| **Parallelism** | 4 instances (stack, features, architecture, pitfalls) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |\n\n**Capabilities:**\n- Web search for current ecosystem information\n- Context7 MCP integration for library documentation\n- Writes research documents directly to disk (reduces orchestrator context load)\n\n---\n\n### gsd-phase-researcher\n\n**Role:** Researches how to implement a specific phase before planning.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` |\n| **Parallelism** | 4 instances (same focus areas as project researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `{phase}-RESEARCH.md` |\n\n**Capabilities:**\n- Reads CONTEXT.md to focus research on user's decisions\n- Investigates implementation patterns for the specific phase domain\n- Detects test infrastructure for Nyquist validation mapping\n\n---\n\n### gsd-ui-researcher\n\n**Role:** Produces UI design contracts for frontend phases.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#E879F9` (fuchsia) |\n| **Produces** | `{phase}-UI-SPEC.md` |\n\n**Capabilities:**\n- Detects design system state (shadcn components.json, Tailwind config, existing tokens)\n- Offers shadcn initialization for React/Next.js/Vite projects\n- Asks only unanswered design contract questions\n- Enforces registry safety gate for third-party components\n\n---\n\n### gsd-assumptions-analyzer\n\n**Role:** Deeply analyzes codebase for a phase and returns structured assumptions with evidence, confidence levels, and consequences if wrong.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase-assumptions` workflow (when `workflow.discuss_mode = 'assumptions'`) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | Structured assumptions with decision statements, evidence file paths, confidence levels |\n\n**Key behaviors:**\n- Reads ROADMAP.md phase description and prior CONTEXT.md files\n- Searches codebase for files related to the phase (components, patterns, similar features)\n- Reads 5-15 most relevant source files to form evidence-based assumptions\n- Classifies confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways)\n- Flags topics that need external research (library compatibility, ecosystem best practices)\n- Output calibrated by tier: full_maturity (3-5 areas), standard (3-4), minimal_decisive (2-3)\n\n---\n\n### gsd-advisor-researcher\n\n**Role:** Researches a single gray area decision during discuss-phase advisor mode and returns a structured comparison table.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase` workflow (when ADVISOR_MODE = true) |\n| **Parallelism** | Multiple instances (one per gray area) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | 5-column comparison table (Option / Pros / Cons / Complexity / Recommendation) with rationale paragraph |\n\n**Key behaviors:**\n- Researches a single assigned gray area using Claude's knowledge, Context7, and web search\n- Produces genuinely viable options — no padding with filler alternatives\n- Complexity column uses impact surface + risk (never time estimates)\n- Recommendations are conditional (\"Rec if X\", \"Rec if Y\") — never single-winner ranking\n- Output calibrated by tier: full_maturity (3-5 options with maturity signals), standard (2-4), minimal_decisive (2 options, decisive recommendation)\n\n---\n\n### gsd-research-synthesizer\n\n**Role:** Combines outputs from parallel researchers into a unified summary.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` (after 4 researchers complete) |\n| **Parallelism** | Single instance (sequential after researchers) |\n| **Tools** | Read, Write, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `.planning/research/SUMMARY.md` |\n\n---\n\n### gsd-planner\n\n**Role:** Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase`, `/gsd-quick` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep, WebFetch, mcp (context7) |\n| **Model (balanced)** | Opus |\n| **Color** | Green |\n| **Produces** | `{phase}-{N}-PLAN.md` files |\n\n**Key behaviors:**\n- Reads PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md\n- Creates 2-3 atomic task plans sized for single context windows\n- Uses XML structure with `` elements\n- Includes `read_first` and `acceptance_criteria` sections\n- Groups plans into dependency waves\n- Performs reachability check to validate plan steps reference accessible files and APIs (v1.32)\n\n---\n\n### gsd-roadmapper\n\n**Role:** Creates project roadmaps with phase breakdown and requirement mapping.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `ROADMAP.md` |\n\n**Key behaviors:**\n- Maps requirements to phases (traceability)\n- Derives success criteria from requirements\n- Respects granularity setting for phase count\n- Validates coverage (every v1 requirement mapped to a phase)\n\n---\n\n### gsd-executor\n\n**Role:** Executes GSD plans with atomic commits, deviation handling, and checkpoint protocols.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase`, `/gsd-quick` |\n| **Parallelism** | Multiple (parallel within waves, sequential across waves) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Yellow |\n| **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` |\n\n**Key behaviors:**\n- Fresh 200K context window per plan\n- Follows XML task instructions precisely\n- Atomic git commit per completed task\n- Handles checkpoint types: auto, human-verify, decision, human-action\n- Reports deviations from plan in SUMMARY.md\n- Invokes node repair on verification failure\n\n---\n\n### gsd-plan-checker\n\n**Role:** Verifies plans will achieve phase goals before execution.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (verification loop, max 3 iterations) |\n| **Parallelism** | Single instance (iterative) |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | PASS/FAIL verdict with specific feedback |\n\n**8 Verification Dimensions:**\n1. Requirement coverage\n2. Task atomicity\n3. Dependency ordering\n4. File scope\n5. Verification commands\n6. Context fit\n7. Gap detection\n8. Nyquist compliance (when enabled)\n\n---\n\n### gsd-integration-checker\n\n**Role:** Verifies cross-phase integration and end-to-end flows.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-audit-milestone` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Blue |\n| **Produces** | Integration verification report |\n\n---\n\n### gsd-ui-checker\n\n**Role:** Validates UI-SPEC.md design contracts against quality dimensions.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` (validation loop, max 2 iterations) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#22D3EE` (cyan) |\n| **Produces** | BLOCK/FLAG/PASS verdict |\n\n---\n\n### gsd-verifier\n\n**Role:** Verifies phase goal achievement through goal-backward analysis.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase` (after all executors complete) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | `{phase}-VERIFICATION.md` |\n\n**Key behaviors:**\n- Checks codebase against phase goals, not just task completion\n- PASS/FAIL with specific evidence\n- Logs issues for `/gsd-verify-work` to address\n- Milestone scope filtering: gaps addressed in later phases are marked as \"deferred\", not reported as failures (v1.32)\n- **Test quality audit** (v1.32): verifies that tests prove what they claim by checking for disabled/skipped tests on requirements, circular test patterns (system generating its own expected values), assertion strength (existence vs. value vs. behavioral), and expected value provenance. Blockers from test quality audit override an otherwise passing verification\n\n---\n\n### gsd-nyquist-auditor\n\n**Role:** Fills Nyquist validation gaps by generating tests.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-validate-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Produces** | Test files, updated `VALIDATION.md` |\n\n**Key behaviors:**\n- Never modifies implementation code — only test files\n- Max 3 attempts per gap\n- Flags implementation bugs as escalations for user\n\n---\n\n### gsd-ui-auditor\n\n**Role:** Retroactive 6-pillar visual audit of implemented frontend code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F472B6` (pink) |\n| **Produces** | `{phase}-UI-REVIEW.md` with scores |\n\n**6 Audit Pillars (scored 1-4):**\n1. Copywriting\n2. Visuals\n3. Color\n4. Typography\n5. Spacing\n6. Experience Design\n\n---\n\n### gsd-codebase-mapper\n\n**Role:** Explores codebase and writes structured analysis documents.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase`, post-execute drift gate in `/gsd-execute-phase` |\n| **Parallelism** | 4 instances (tech, architecture, quality, concerns) |\n| **Tools** | Read, Bash, Grep, Glob, Write |\n| **Model (balanced)** | Haiku |\n| **Color** | Cyan |\n| **Produces** | `.planning/codebase/*.md` (7 documents, with `last_mapped_commit` frontmatter) |\n\n**Key behaviors:**\n- Read-only exploration + structured output\n- Writes documents directly to disk\n- No reasoning required — pattern extraction from file contents\n\n**`--paths ` scope hint (#2003):**\nAccepts an optional `--paths` directive in its prompt. When present, the\nmapper restricts Glob/Grep/Bash exploration to the listed repo-relative path\nprefixes — this is the incremental-remap path used by the post-execute\ncodebase-drift gate. Path values that contain `..`, start with `/`, or\ninclude shell metacharacters are rejected. Without the hint, the mapper\nruns its default whole-repo scan.\n\n---\n\n### gsd-debugger\n\n**Role:** Investigates bugs using scientific method with persistent state.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug`, `/gsd-verify-work` (for failures) |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | `.planning/debug/*.md`, knowledge-base updates |\n\n**Debug Session Lifecycle:**\n`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved`\n\n**Key behaviors:**\n- Tracks hypotheses, evidence, and eliminated theories\n- State persists across context resets\n- Requires human verification before marking resolved\n- Appends to persistent knowledge base on resolution\n- Consults knowledge base on new sessions\n\n---\n\n### gsd-user-profiler\n\n**Role:** Analyzes session messages across 8 behavioral dimensions to produce a scored developer profile.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-profile-user` |\n| **Parallelism** | Single instance |\n| **Tools** | Read |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `USER-PROFILE.md`, `CLAUDE.md` profile section |\n\n**Behavioral Dimensions:**\nCommunication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth.\n\n**Key behaviors:**\n- Read-only agent — analyzes extracted session data, does not modify files\n- Produces scored dimensions with confidence levels and evidence citations\n- Questionnaire fallback when session history is unavailable\n\n---\n\n### gsd-doc-writer\n\n**Role:** Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode, and project context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` |\n| **Parallelism** | Multiple instances (one per doc type) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | Project documentation files (README, architecture, API docs, etc.) |\n\n**Key behaviors:**\n- Supports modes: create, update, supplement, fix\n- Handles doc types: readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing, custom\n- Monorepo-aware: can generate per-package READMEs\n- Fix mode accepts failure objects from gsd-doc-verifier for targeted corrections\n- Writes directly to disk — does not return content to orchestrator\n\n---\n\n### gsd-doc-verifier\n\n**Role:** Verifies factual claims in generated documentation against the live codebase.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` (after doc-writer completes) |\n| **Parallelism** | Multiple instances (one per doc file) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Structured JSON verification results per doc |\n\n**Key behaviors:**\n- Extracts checkable claims (file paths, function names, CLI commands, config keys)\n- Verifies each claim against filesystem using tools only — no assumptions\n- Writes structured JSON result file for orchestrator to process\n- Failed claims feed back to doc-writer in fix mode\n\n---\n\n### gsd-security-auditor\n\n**Role:** Verifies threat mitigations from PLAN.md threat model exist in implemented code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-secure-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `{phase}-SECURITY.md` |\n\n**Key behaviors:**\n- Verifies each threat by its declared disposition (mitigate / accept / transfer)\n- Does NOT scan blindly for new vulnerabilities — verifies declared mitigations only\n- Implementation files are read-only — never patches implementation code\n- Unmitigated threats reported as OPEN_THREATS or ESCALATE\n- Supports ASVS levels 1/2/3 for verification depth\n\n---\n\n## Advanced and Specialized Agents\n\nTwelve additional agents ship under `agents/gsd-*.md` and are used by specialty workflows (`/gsd-ai-integration-phase`, `/gsd-eval-review`, `/gsd-code-review`, `/gsd-code-review --fix`, `/gsd-debug`, `/gsd-map-codebase --query`, `/gsd-ingest-docs`) and by the planner pipeline. Each carries full frontmatter in its agent file; the stubs below are concise by design. The authoritative roster (with spawner and primary-doc status per agent) lives in [`docs/INVENTORY.md`](INVENTORY.md).\n\n### gsd-pattern-mapper\n\n**Role:** Read-only codebase analysis that maps files-to-be-created or modified to their closest existing analogs, producing `PATTERNS.md` for the planner to consume.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (between research and planning) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep, Write |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `PATTERNS.md` in the phase directory |\n\n**Key behaviors:**\n- Extracts file list from CONTEXT.md and RESEARCH.md; classifies each by role (controller, component, service, model, middleware, utility, config, test) and data flow (CRUD, streaming, file I/O, event-driven, request-response)\n- Searches for the closest existing analog per file and extracts concrete code excerpts (imports, auth patterns, core pattern, error handling)\n- Strictly read-only against source; only writes `PATTERNS.md`\n\n---\n\n### gsd-debug-session-manager\n\n**Role:** Runs the full `/gsd-debug` checkpoint-and-continuation loop in an isolated context so the orchestrator's main context stays lean; spawns `gsd-debugger` agents, dispatches specialist skills, and handles user checkpoints via AskUserQuestion.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug` |\n| **Parallelism** | Single instance (interactive, stateful) |\n| **Tools** | Read, Write, Bash, Grep, Glob, Task, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Compact summary returned to main context; evolves the `.planning/debug/{slug}.md` session file |\n\n**Key behaviors:**\n- Reads the debug session file first; passes file paths (not inlined contents) to spawned agents to respect context budget\n- Treats all user-supplied AskUserQuestion content as data-only, wrapped in DATA_START/DATA_END markers\n- Coordinates TDD gates and reasoning checkpoints introduced in v1.36.0\n\n---\n\n### gsd-code-reviewer\n\n**Role:** Reviews source files for bugs, security vulnerabilities, and code-quality problems; produces a structured `REVIEW.md` with severity-classified findings.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review` |\n| **Parallelism** | Typically single instance per review scope |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | `REVIEW.md` in the phase directory |\n\n**Key behaviors:**\n- Detects bugs (logic errors, null/undefined checks, off-by-one, type mismatches, unreachable code), security issues (injection, XSS, hardcoded secrets, insecure crypto), and quality issues\n- Honors `CLAUDE.md` project conventions and `.claude/skills/` / `.agents/skills/` rules when present\n- Read-only against implementation source — never modifies code under review\n\n---\n\n### gsd-code-fixer\n\n**Role:** Applies fixes to findings from `REVIEW.md` with intelligent (non-blind) patching and atomic per-fix commits; produces `REVIEW-FIX.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review --fix` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Edit, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#10B981` (emerald) |\n| **Produces** | `REVIEW-FIX.md`; one atomic git commit per applied fix |\n\n**Key behaviors:**\n- Treats `REVIEW.md` suggestions as guidance, not a patch to apply literally\n- Commits each fix atomically so review and rollback stay granular\n- Honors `CLAUDE.md` and project-skill rules during fixes\n\n---\n\n### gsd-ai-researcher\n\n**Role:** Researches a chosen AI/LLM framework's official documentation and distills it into implementation-ready guidance — framework quick reference, patterns, and pitfalls — for the Section 3–4b body of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential with domain-researcher / eval-planner) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#34D399` (green) |\n| **Produces** | Sections 3–4b of `AI-SPEC.md` (framework quick reference + implementation guidance) |\n\n**Key behaviors:**\n- Uses Context7 MCP when available; falls back to the `ctx7` CLI via Bash when MCP tools are stripped from the agent\n- Anchors guidance to the specific use case, not generic framework overviews\n\n---\n\n### gsd-domain-researcher\n\n**Role:** Surfaces the business-domain and real-world evaluation context for an AI system — expert rubric ingredients, failure modes, regulatory context — before the eval-planner turns it into measurable rubrics. Writes Section 1b of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#A78BFA` (violet) |\n| **Produces** | Section 1b of `AI-SPEC.md` |\n\n**Key behaviors:**\n- Researches the domain, not the technical framework — its output feeds the eval-planner downstream\n- Produces rubric ingredients that downstream evaluators can turn into measurable criteria\n\n---\n\n### gsd-eval-planner\n\n**Role:** Designs the structured evaluation strategy for an AI phase — failure modes, eval dimensions with rubrics, tooling, reference dataset, guardrails, production monitoring. Writes Sections 5–7 of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential after domain-researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | Sections 5–7 of `AI-SPEC.md` (Evaluation Strategy, Guardrails, Production Monitoring) |\n\n**Required reading:** `get-shit-done/references/ai-evals.md` (evaluation framework).\n\n**Key behaviors:**\n- Turns domain-researcher rubric ingredients into measurable, tooled evaluation criteria\n- Does not re-derive domain context — reads Section 1 and 1b of `AI-SPEC.md` as established input\n\n---\n\n### gsd-eval-auditor\n\n**Role:** Retroactive audit of an implemented AI phase's evaluation coverage against its planned `AI-SPEC.md` eval strategy. Scores each eval dimension `COVERED` / `PARTIAL` / `MISSING` and produces `EVAL-REVIEW.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-eval-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `EVAL-REVIEW.md` with dimension scores, findings, and remediation guidance |\n\n**Required reading:** `get-shit-done/references/ai-evals.md`.\n\n**Key behaviors:**\n- Compares the implemented codebase against the planned eval strategy — never re-plans\n- Reads implementation files incrementally to respect context budget\n\n---\n\n### gsd-framework-selector\n\n**Role:** Interactive decision-matrix agent that runs a ≤6-question interview, scores candidate AI/LLM frameworks, and returns a ranked recommendation with rationale.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#38BDF8` (sky blue) |\n| **Produces** | Scored ranked recommendation (structured return to orchestrator) |\n\n**Required reading:** `get-shit-done/references/ai-frameworks.md` (decision matrix).\n\n**Key behaviors:**\n- Scans `package.json`, `pyproject.toml`, `requirements*.txt` for existing AI libraries before the interview to avoid recommending a rejected framework\n- Asks only what the codebase scan and CONTEXT.md have not already answered\n\n---\n\n### gsd-intel-updater\n\n**Role:** Reads project source and writes structured intel (JSON + Markdown) into `.planning/intel/`, building a queryable codebase knowledge base that other agents use instead of performing expensive fresh exploration.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase --query` (refresh / update flows) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | `.planning/intel/*.json` (and companion Markdown) consumed by `gsd-sdk query intel` |\n\n**Key behaviors:**\n- Writes current state only — no temporal language, every claim references an actual file path\n- Uses Glob / Read / Grep for cross-platform correctness; Bash is reserved for `gsd-sdk query intel` CLI calls\n\n---\n\n### gsd-doc-classifier\n\n**Role:** Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN. Extracts title, scope summary, and cross-references. Writes a JSON classification file used by `gsd-doc-synthesizer` to build a consolidated context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (parallel fan-out over the doc corpus) |\n| **Parallelism** | One instance per input document |\n| **Tools** | Read, Write, Grep, Glob |\n| **Model (balanced)** | Haiku |\n| **Color** | Yellow |\n| **Produces** | One JSON classification file per input doc (type, title, scope, refs) |\n\n**Key behaviors:**\n- Single-doc scope — never synthesizes or resolves conflicts (that is the synthesizer's job)\n- Heuristic-first classification; returns UNKNOWN when the doc lacks type signals rather than guessing\n\n---\n\n### gsd-doc-synthesizer\n\n**Role:** Synthesizes classified planning docs into a single consolidated context. Applies precedence rules, detects cross-reference cycles, enforces LOCKED-vs-LOCKED hard-blocks, and writes `INGEST-CONFLICTS.md` with three buckets (auto-resolved, competing-variants, unresolved-blockers).\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (after classifier fan-in) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Grep, Glob, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Consolidated context for `.planning/` plus `INGEST-CONFLICTS.md` report |\n\n**Key behaviors:**\n- Hard-blocks on LOCKED-vs-LOCKED ADR contradictions instead of silently picking a winner\n- Follows the `references/doc-conflict-engine.md` contract so `/gsd-import` and `/gsd-ingest-docs` produce consistent conflict reports\n\n---\n\n## Agent Tool Permissions Summary\n\n> **Scope:** this table covers the 21 primary agents only. The 12 advanced/specialized agents listed above carry their own tool surfaces in their `agents/gsd-*.md` frontmatter (summarized in the per-agent stubs above and in [`docs/INVENTORY.md`](INVENTORY.md)).\n\n| Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |\n|-------|------|-------|------|------|------|------|-----------|----------|-----|\n| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | |\n| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| research-synthesizer | ✓ | ✓ | | ✓ | | | | | |\n| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |\n| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |\n| user-profiler | ✓ | | | | | | | | |\n| doc-writer | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| doc-verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| security-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n\n**Principle of Least Privilege:**\n- Checkers are read-only (no Write/Edit) — they evaluate, never modify\n- Researchers have web access — they need current ecosystem information\n- Executors have Edit — they modify code but not web access\n- Mappers have Write — they write analysis documents but not Edit (no code changes)\n","docs/ARCHITECTURE.md":"# GSD Architecture\n\n> System architecture for contributors and advanced users. For user-facing documentation, see [Feature Reference](FEATURES.md) or [User Guide](USER-GUIDE.md).\n\n---\n\n## Table of Contents\n\n- [System Overview](#system-overview)\n- [Design Principles](#design-principles)\n- [Component Architecture](#component-architecture)\n- [Agent Model](#agent-model)\n- [Data Flow](#data-flow)\n- [File System Layout](#file-system-layout)\n- [Installer Architecture](#installer-architecture)\n- [Hook System](#hook-system)\n- [CLI Tools Layer](#cli-tools-layer)\n- [Runtime Abstraction](#runtime-abstraction)\n\n---\n\n## System Overview\n\nGSD is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:\n\n1. **Context engineering** — Structured artifacts that give the AI everything it needs per task\n2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows\n3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline\n4. **State management** — Persistent project memory across sessions and context resets\n\n```\n┌──────────────────────────────────────────────────────┐\n│ USER │\n│ /gsd-command [args] │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ COMMAND LAYER │\n│ commands/gsd/*.md — Prompt-based command files │\n│ (Claude Code custom commands / Codex skills) │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ WORKFLOW LAYER │\n│ get-shit-done/workflows/*.md — Orchestration logic │\n│ (Reads references, spawns agents, manages state) │\n└──────┬──────────────┬─────────────────┬──────────────┘\n │ │ │\n┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐\n│ AGENT │ │ AGENT │ │ AGENT │\n│ (fresh │ │ (fresh │ │ (fresh │\n│ context) │ │ context)│ │ context) │\n└──────┬──────┘ └─────┬─────┘ └────────┬───────┘\n │ │ │\n┌──────▼──────────────▼─────────────────▼──────────────┐\n│ CLI TOOLS LAYER │\n│ gsd-sdk query (sdk/src/query) + gsd-tools.cjs │\n│ Programmatic SDK bridge: GSDTools/query-runtime-bridge.ts │\n└──────────────────────┬───────────────────────────────┘\n │\n┌──────────────────────▼───────────────────────────────┐\n│ FILE SYSTEM (.planning/) │\n│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │\n│ STATE.md | config.json | phases/ | research/ │\n└──────────────────────────────────────────────────────┘\n```\n\n---\n\n## Design Principles\n\n### 1. Fresh Context Per Agent\n\nEvery agent spawned by an orchestrator gets a clean context window (up to 200K tokens). This eliminates context rot — the quality degradation that happens as an AI fills its context window with accumulated conversation.\n\n### 2. Thin Orchestrators\n\nWorkflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:\n\n- Load context via `gsd-sdk query init.` (or legacy `gsd-tools.cjs init `)\n- Spawn specialized agents with focused prompts\n- Collect results and route to the next step\n- Update state between steps\n\n### 3. File-Based State\n\nAll state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means:\n\n- State survives context resets (`/clear`)\n- State is inspectable by both humans and agents\n- State can be committed to git for team visibility\n\n### 4. Absent = Enabled\n\nWorkflow feature flags follow the **absent = enabled** pattern. If a key is missing from `config.json`, it defaults to `true`. Users explicitly disable features; they don't need to enable defaults.\n\n### 5. Defense in Depth\n\nMultiple layers prevent common failure modes:\n\n- Plans are verified before execution (plan-checker agent)\n- Execution produces atomic commits per task\n- Post-execution verification checks against phase goals\n- UAT provides human verification as final gate\n\n---\n\n## Component Architecture\n\n### Commands (`commands/gsd/*.md`)\n\nUser-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as:\n\n- **Claude Code:** Custom slash commands (hyphen form, `/gsd-command-name`)\n- **OpenCode / Kilo:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Codex:** Skills (`$gsd-command-name`)\n- **Copilot:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Gemini CLI:** Slash commands under the `gsd:` namespace (colon form, `/gsd:command-name`) — Gemini namespaces all custom commands under their plugin id, so the install path rewrites every body-text reference to colon form\n- **Antigravity:** Skills\n\n**Total commands:** see [`docs/INVENTORY.md`](INVENTORY.md#commands) for the authoritative count and full roster.\n\n#### Two-stage hierarchical routing (v1.40, [#2792](https://github.com/gsd-build/get-shit-done/issues/2792))\n\nTo keep the eager skill-listing token cost low, v1.40 introduces six namespace **meta-skills** (`gsd-workflow`, `gsd-project`, `gsd-quality`, `gsd-context`, `gsd-manage`, `gsd-ideate` — sourced from `commands/gsd/ns-*.md`, but the invocable `name:` is the bare form shown here) layered above the concrete sub-skills. The model sees 6 namespace routers (~120 tokens) instead of a flat 86-skill listing (~2,150 tokens), selects a namespace, then routes to the concrete sub-skill via a routing table embedded in the namespace router's body. Namespace skills are **additive** — every concrete command is still directly invocable.\n\nThe router descriptions use pipe-separated keyword tags (≤ 60 chars) per the Tool Attention research showing keyword-dense tags outperform prose for routing at ~40 % the token cost.\n\n#### MCP token-budget interaction\n\nThe eager skill listing is one of two recurring per-turn token costs. The other is the MCP tool schema injected by every enabled MCP server in `.claude/settings.json`. Heavyweight MCP servers (browser/playwright, Mac-tools, Windows-tools) can each cost 20 k+ tokens per turn — often dwarfing what `model_profile` tuning saves. The toggle lives in the Claude Code harness (`enabledMcpjsonServers` / `disabledMcpjsonServers` in `.claude/settings.json`) and is **not** a GSD concern. Together, the two-stage routing layer (#2792) and disciplined MCP enablement are the largest cost levers per turn. See [`docs/USER-GUIDE.md`](USER-GUIDE.md) and `references/context-budget.md` for the audit checklist.\n\n### Workflows (`get-shit-done/workflows/*.md`)\n\nOrchestration logic that commands reference. Contains the step-by-step process including:\n\n- Context loading via `gsd-sdk query` init handlers (or legacy `gsd-tools.cjs init`)\n- Agent spawn instructions with model resolution\n- Gate/checkpoint definitions\n- State update patterns\n- Error handling and recovery\n\n**Total workflows:** see [`docs/INVENTORY.md`](INVENTORY.md#workflows) for the authoritative count and full roster.\n\n#### Progressive disclosure for workflows\n\nWorkflow files are loaded verbatim into Claude's context every time the\ncorresponding `/gsd-*` command is invoked. To keep that cost bounded, the\nworkflow size budget enforced by `tests/workflow-size-budget.test.cjs`\nmirrors the agent budget from #2361:\n\n| Tier | Per-file line limit |\n|-----------|--------------------|\n| `XL` | 1700 — top-level orchestrators (`execute-phase`, `plan-phase`, `new-project`) |\n| `LARGE` | 1500 — multi-step planners and large feature workflows |\n| `DEFAULT` | 1000 — focused single-purpose workflows (the target tier) |\n\n`workflows/discuss-phase.md` is held to a stricter <500-line ceiling per\nissue #2551. When a workflow grows beyond its tier, extract per-mode bodies\ninto `workflows//modes/.md`, templates into\n`workflows//templates/`, and shared knowledge into\n`get-shit-done/references/`. The parent file becomes a thin dispatcher that\nReads only the mode and template files needed for the current invocation.\n\n`workflows/discuss-phase/` is the canonical example of this pattern —\nparent dispatches, modes/ holds per-flag behavior (`power.md`, `all.md`,\n`auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`,\n`advisor.md`), and templates/ holds CONTEXT.md, DISCUSSION-LOG.md, and\ncheckpoint.json schemas that are read only when the corresponding output\nfile is being written.\n\n### Agents (`agents/*.md`)\n\nSpecialized agent definitions with frontmatter specifying:\n\n- `name` — Agent identifier\n- `description` — Role and purpose\n- `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)\n- `color` — Terminal output color for visual distinction\n\n**Total agents:** 33\n\n### References (`get-shit-done/references/*.md`)\n\nShared knowledge documents that workflows and agents `@-reference` (see [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) for the authoritative count and full roster):\n\n**Core references:**\n\n- `checkpoints.md` — Checkpoint type definitions and interaction patterns\n- `gates.md` — 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier\n- `model-profiles.md` — Per-agent model tier assignments\n- `model-profile-resolution.md` — Model resolution algorithm documentation\n- `verification-patterns.md` — How to verify different artifact types\n- `verification-overrides.md` — Per-artifact verification override rules\n- `planning-config.md` — Full config schema and behavior\n- `git-integration.md` — Git commit, branching, and history patterns\n- `git-planning-commit.md` — Planning directory commit conventions\n- `questioning.md` — Dream extraction philosophy for project initialization\n- `tdd.md` — Test-driven development integration patterns\n- `ui-brand.md` — Visual output formatting patterns\n- `common-bug-patterns.md` — Common bug patterns for code review and verification\n\n**Workflow references:**\n\n- `agent-contracts.md` — Formal interface between orchestrators and agents\n- `context-budget.md` — Context window budget allocation rules\n- `continuation-format.md` — Session continuation/resume format\n- `domain-probes.md` — Domain-specific probing questions for discuss-phase\n- `gate-prompts.md` — Gate/checkpoint prompt templates\n- `revision-loop.md` — Plan revision iteration patterns\n- `universal-anti-patterns.md` — Common anti-patterns to detect and avoid\n- `artifact-types.md` — Planning artifact type definitions\n- `phase-argument-parsing.md` — Phase argument parsing conventions\n- `decimal-phase-calculation.md` — Decimal sub-phase numbering rules\n- `workstream-flag.md` — Workstream active pointer conventions\n- `user-profiling.md` — User behavioral profiling methodology\n- `thinking-partner.md` — Conditional thinking partner activation at decision points\n\n**Thinking model references:**\n\nReferences for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows:\n\n- `thinking-models-debug.md` — Thinking model patterns for debugging workflows\n- `thinking-models-execution.md` — Thinking model patterns for execution agents\n- `thinking-models-planning.md` — Thinking model patterns for planning agents\n- `thinking-models-research.md` — Thinking model patterns for research agents\n- `thinking-models-verification.md` — Thinking model patterns for verification agents\n\n**Modular planner decomposition:**\n\nThe planner agent (`agents/gsd-planner.md`) was decomposed from a single monolithic file into a core agent plus reference modules to stay under the 50K character limit imposed by some runtimes:\n\n- `planner-gap-closure.md` — Gap closure mode behavior (reads VERIFICATION.md, targeted replanning)\n- `planner-reviews.md` — Cross-AI review integration (reads REVIEWS.md from `/gsd-review`)\n- `planner-revision.md` — Plan revision patterns for iterative refinement\n\n### Templates (`get-shit-done/templates/`)\n\nMarkdown templates for all planning artifacts. Used by `gsd-sdk query template.fill` / `phase.scaffold` (and legacy `gsd-tools.cjs template fill` / top-level `scaffold`) to create pre-structured files:\n- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files\n- `phase-prompt.md` — Phase execution prompt template\n- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates\n- `DEBUG.md` — Debug session tracking template\n- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Specialized verification templates\n- `discussion-log.md` — Discussion audit trail template\n- `codebase/` — Brownfield mapping templates (stack, architecture, conventions, concerns, structure, testing, integrations)\n- `research-project/` — Research output templates (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)\n\n### Hooks (`hooks/`)\n\nRuntime hooks that integrate with the host AI agent:\n\n| Hook | Event | Purpose |\n|------|-------|---------|\n| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar |\n| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining |\n| `gsd-check-update.js` | `SessionStart` | Foreground trigger for the background update check |\n| `gsd-check-update-worker.js` | (helper) | Background worker spawned by `gsd-check-update.js`; no direct event registration |\n| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) |\n| `gsd-read-injection-scanner.js` | `PostToolUse` | Scans Read tool output for injected instructions in untrusted content |\n| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |\n| `gsd-read-guard.js` | `PreToolUse` | Advisory guard preventing Edit/Write on files not yet read in the session |\n| `gsd-session-state.sh` | `PostToolUse` | Session state tracking for shell-based runtimes |\n| `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional commit enforcement |\n| `gsd-phase-boundary.sh` | `PostToolUse` | Phase boundary detection for workflow transitions |\n\nSee [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 11-hook roster.\n\n### SDK Runtime Bridge Module (`sdk/src/query-runtime-bridge.ts`)\n\nProgrammatic SDK callers (`GSDTools`) route through one seam that owns query dispatch policy:\n\n- Native registry dispatch preference\n- Explicit subprocess fallback policy (`allowFallbackToSubprocess`)\n- Strict SDK mode (`strictSdk`) for fail-fast native-only enforcement\n- Structured dispatch observability (`onDispatchEvent`) with mode, reason, duration, and outcome\n\nThis keeps callers thin adapters and centralizes transport decisions for SDK publishability.\n\n### Command Routing Hub (`get-shit-done/bin/lib/command-routing-hub.cjs`)\n\nCJS command family routers migrate to dispatch through `CommandRoutingHub` incrementally. `phase-command-router.cjs` is the first migration (issue #3788); remaining routers (`phases-command-router.cjs`, `roadmap-command-router.cjs`, etc.) continue using `routeCjsCommandFamily` until migrated in follow-up issues. The hub owns three cross-cutting concerns that each router previously duplicated: (1) mode selection (`sdk` when `tryLoadSdk()` succeeds and no `GSD_WORKSTREAM` is active, `cjs` otherwise), set once at construction; (2) a no-throw pure-result contract (`hub.dispatch()` catches all exceptions and returns `{ ok: false, errorKind, message, details }` instead of propagating); and (3) a closed six-value `errorKind` enum exported as the frozen `ERROR_KINDS` object. Router adapters remain thin CLI translators — they build the hub, call `dispatch`, then map the Result to `output()`/`error()` calls. No transparent SDK→CJS fallback: an SDK-mode hub that encounters a load or dispatch failure returns `SdkLoadFailed` or `SdkDispatchFailed` without retrying via CJS. See `docs/adr/0012-command-routing-hub.md`.\n\n### CLI Tools (`get-shit-done/bin/`)\n\nNode.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) for the authoritative roster):\n\n\n| Module | Responsibility |\n| ---------------------- | --------------------------------------------------------------------------------------------------- |\n| `core.cjs` | Error handling, output formatting, shared utilities; compatibility re-exports for planning helpers |\n| `planning-workspace.cjs` | Planning seam (`planningDir`, `planningPaths`, active workstream routing, `.planning/.lock`) |\n| `state.cjs` | STATE.md parsing, updating, progression, metrics |\n| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |\n| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |\n| `config.cjs` | config.json read/write, section initialization |\n| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |\n| `template.cjs` | Template selection and filling with variable substitution |\n| `frontmatter.cjs` | YAML frontmatter CRUD operations |\n| `init.cjs` | Compound context loading for each workflow type |\n| `milestone.cjs` | Milestone archival, requirements marking |\n| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |\n| `model-profiles.cjs` | Model profile resolution table |\n| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |\n| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |\n| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |\n| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |\n| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |\n| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |\n| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |\n\n\n---\n\n## Agent Model\n\n### Orchestrator → Agent Pattern\n\n```\nOrchestrator (workflow .md)\n │\n ├── Load context: gsd-sdk query init. (or legacy gsd-tools.cjs init)\n │ Returns JSON with: project info, config, state, phase details\n │\n ├── Resolve model: gsd-sdk query resolve-model \n │ Returns: opus | sonnet | haiku | inherit\n │\n ├── Spawn Agent (Task/SubAgent call)\n │ ├── Agent prompt (agents/*.md)\n │ ├── Context payload (init JSON)\n │ ├── Model assignment\n │ └── Tool permissions\n │\n ├── Collect result\n │\n └── Update state: gsd-sdk query state.update / state.patch / state.advance-plan (or legacy gsd-tools.cjs)\n```\n\n### Primary Agent Spawn Categories\n\nConceptual spawn-pattern taxonomy for the 21 primary agents. For the authoritative 31-agent roster (including the 10 advanced/specialized agents such as `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), see [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped).\n\n\n| Category | Agents | Parallelism |\n| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |\n| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |\n| **Planners** | gsd-planner, gsd-roadmapper | Sequential |\n| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |\n| **Executors** | gsd-executor | Parallel within waves, sequential across waves |\n| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |\n| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |\n| **Debuggers** | gsd-debugger | Sequential (interactive) |\n| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |\n| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |\n| **Profilers** | gsd-user-profiler | Sequential |\n| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |\n\n\n### Wave Execution Model\n\nDuring `execute-phase`, plans are grouped into dependency waves:\n\n```\nWave Analysis:\n Plan 01 (no deps) ─┐\n Plan 02 (no deps) ─┤── Wave 1 (parallel)\n Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1)\n Plan 04 (depends: 02) ─┘\n Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)\n```\n\nEach executor gets:\n\n- Fresh 200K context window (or up to 1M for models that support it)\n- The specific PLAN.md to execute\n- Project context (PROJECT.md, STATE.md)\n- Phase context (CONTEXT.md, RESEARCH.md if available)\n\n### Adaptive Context Enrichment (1M Models)\n\nWhen the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4.6), subagent prompts are automatically enriched with additional context that would not fit in standard 200K windows:\n\n- **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase\n- **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification\n\nThe orchestrator reads `context_window` from config (`gsd-sdk query config-get context_window`, or legacy `gsd-tools.cjs config-get`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.\n\n#### Parallel Commit Safety\n\nWhen multiple executors run within the same wave, two mechanisms prevent conflicts:\n\n1. `--no-verify` commits — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.\n2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter.\n\n---\n\n## Data Flow\n\n### New Project Flow\n\n```\nUser input (idea description)\n │\n ▼\nQuestions (questioning.md philosophy)\n │\n ▼\n4x Project Researchers (parallel)\n ├── Stack → STACK.md\n ├── Features → FEATURES.md\n ├── Architecture → ARCHITECTURE.md\n └── Pitfalls → PITFALLS.md\n │\n ▼\nResearch Synthesizer → SUMMARY.md\n │\n ▼\nRequirements extraction → REQUIREMENTS.md\n │\n ▼\nRoadmapper → ROADMAP.md\n │\n ▼\nUser approval → STATE.md initialized\n```\n\n### Phase Execution Flow\n\n```\ndiscuss-phase → CONTEXT.md (user preferences)\n │\n ▼\nui-phase → UI-SPEC.md (design contract, optional)\n │\n ▼\nplan-phase\n ├── Research gate (blocks if RESEARCH.md has unresolved open questions)\n ├── Phase Researcher → RESEARCH.md\n │ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,\n │ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md\n ├── Planner (with reachability check) → PLAN.md files\n │ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;\n │ T-{phase}-SC STRIDE row added for install-bearing plans\n ├── Plan Checker → Verify loop (max 3x)\n ├── Requirements coverage gate (REQ-IDs → plans)\n └── Decision coverage gate (CONTEXT.md `` → plans, BLOCKING — #2492)\n │\n ▼\nstate planned-phase → STATE.md (Planned/Ready to execute)\n │\n ▼\nexecute-phase (context reduction: truncated prompts, cache-friendly ordering)\n ├── Wave analysis (dependency grouping)\n ├── Executor per plan → code + atomic commits\n ├── SUMMARY.md per plan\n └── Verifier → VERIFICATION.md\n └── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)\n │\n ▼\nverify-work → UAT.md (user acceptance testing)\n │\n ▼\nui-review → UI-REVIEW.md (visual audit, optional)\n```\n\n### Context Propagation\n\nEach workflow stage produces artifacts that feed into subsequent stages:\n\n```\nPROJECT.md ────────────────────────────────────────────► All agents\nREQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor\nROADMAP.md ────────────────────────────────────────────► Orchestrators\nSTATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)\nCONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor\nRESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker\nPLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker\nSUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking\nUI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor\n```\n\n---\n\n## File System Layout\n\n### Installation Files\n\n```\n~/.claude/ # Claude Code (global install)\n├── skills/gsd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)\n├── commands/gsd/*.md # Local Claude installs use slash commands instead of global skills\n├── get-shit-done/\n│ ├── bin/gsd-tools.cjs # CLI utility\n│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)\n│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)\n│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)\n│ └── templates/ # Planning artifact templates\n├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)\n├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)\n├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)\n├── settings.json # Hook registrations\n└── VERSION # Installed version number\n```\n\nEquivalent paths for other runtimes:\n\n- **OpenCode:** `~/.config/opencode/` global or `./.opencode/` local\n- **Kilo:** `~/.config/kilo/` global or `./.kilo/` local\n- **Gemini CLI:** `~/.gemini/` global or `./.gemini/` local\n- **Codex:** `~/.codex/` global or `./.codex/` local\n- **Copilot:** `~/.copilot/` global or `./.github/` local\n- **Antigravity:** `~/.gemini/antigravity/` global or `./.agent/` local\n- **Cursor:** `~/.cursor/` global or `./.cursor/` local\n- **Windsurf:** `~/.codeium/windsurf/` global or `./.windsurf/` local\n- **Augment Code:** `~/.augment/` global or `./.augment/` local\n- **Trae:** `~/.trae/` global or `./.trae/` local\n- **Qwen Code:** `~/.qwen/` global or `./.qwen/` local\n- **Hermes Agent:** `~/.hermes/` global or `./.hermes/` local\n- **CodeBuddy:** `~/.codebuddy/` global or `./.codebuddy/` local\n- **Cline:** `~/.cline/` global or project-root `.clinerules` local\n\n### Project Files (`.planning/`)\n\n```\n.planning/\n├── PROJECT.md # Project vision, constraints, decisions, evolution rules\n├── REQUIREMENTS.md # Scoped requirements (v1/v2/out-of-scope)\n├── ROADMAP.md # Phase breakdown with status tracking\n├── STATE.md # Living memory: position, decisions, blockers, metrics\n├── config.json # Workflow configuration\n├── MILESTONES.md # Completed milestone archive\n├── research/ # Domain research from /gsd-new-project\n│ ├── SUMMARY.md\n│ ├── STACK.md\n│ ├── FEATURES.md\n│ ├── ARCHITECTURE.md\n│ └── PITFALLS.md\n├── codebase/ # Brownfield mapping (from /gsd-map-codebase)\n│ ├── STACK.md # YAML frontmatter carries `last_mapped_commit`\n│ ├── ARCHITECTURE.md # for the post-execute drift gate (#2003)\n│ ├── CONVENTIONS.md\n│ ├── CONCERNS.md\n│ ├── STRUCTURE.md\n│ ├── TESTING.md\n│ └── INTEGRATIONS.md\n├── phases/\n│ └── XX-phase-name/\n│ ├── XX-CONTEXT.md # User preferences (from discuss-phase)\n│ ├── XX-RESEARCH.md # Ecosystem research (from plan-phase)\n│ ├── XX-YY-PLAN.md # Execution plans\n│ ├── XX-YY-SUMMARY.md # Execution outcomes\n│ ├── XX-VERIFICATION.md # Post-execution verification\n│ ├── XX-VALIDATION.md # Nyquist test coverage mapping\n│ ├── XX-UI-SPEC.md # UI design contract (from ui-phase)\n│ ├── XX-UI-REVIEW.md # Visual audit scores (from ui-review)\n│ └── XX-UAT.md # User acceptance test results\n├── quick/ # Quick task tracking\n│ └── YYMMDD-xxx-slug/\n│ ├── PLAN.md\n│ └── SUMMARY.md\n├── todos/\n│ ├── pending/ # Captured ideas\n│ └── done/ # Completed todos\n├── threads/ # Persistent context threads (from /gsd-thread)\n├── seeds/ # Forward-looking ideas (from /gsd-capture --seed)\n├── debug/ # Active debug sessions\n│ ├── *.md # Active sessions\n│ ├── resolved/ # Archived sessions\n│ └── knowledge-base.md # Persistent debug learnings\n├── ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)\n└── continue-here.md # Context handoff (from pause-work)\n```\n\n### Post-Execute Codebase Drift Gate (#2003)\n\nAfter the last wave of `/gsd-execute-phase` commits, the workflow runs a\nnon-blocking `codebase_drift_gate` step (between `schema_drift_gate` and\n`verify_phase_goal`). It compares the diff `last_mapped_commit..HEAD`\nagainst `.planning/codebase/STRUCTURE.md` and counts four kinds of\nstructural elements:\n\n1. New directories outside mapped paths\n2. New barrel exports at `(packages|apps)//src/index.*`\n3. New migration files\n4. New route modules under `routes/` or `api/`\n\nIf the count meets `workflow.drift_threshold` (default 3), the gate either\n**warns** (default) with the suggested `/gsd-map-codebase --paths …` command,\nor **auto-remaps** (`workflow.drift_action = auto-remap`) by spawning\n`gsd-codebase-mapper` scoped to the affected paths. Any error in detection\nor remap is logged and the phase continues — drift detection cannot fail\nverification.\n\n`last_mapped_commit` lives in YAML frontmatter at the top of each\n`.planning/codebase/*.md` file; `bin/lib/drift.cjs` provides\n`readMappedCommit` and `writeMappedCommit` round-trip helpers.\n\n---\n\n## Installer Architecture\n\nThe installer (`bin/install.js`, ~10,700 lines) handles:\n\n1. **Runtime detection** — Interactive prompt or CLI flags (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--augment`, `--trae`, `--qwen`, `--hermes`, `--codebuddy`, `--cline`, `--all`)\n2. **Location selection** — Global (`--global`) or local (`--local`)\n3. **File deployment** — Copies commands, skills, workflows, references, templates, agents, and hooks\n4. **Runtime adaptation** — Transforms file content per runtime:\n - Claude Code: Uses as-is\n - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format\n - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths\n - Codex: Generates TOML config + skills from commands\n - Copilot: Maps tool names (Read→read, Bash→execute, etc.)\n - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)\n - Antigravity: Skills-first with Google model equivalents\n - Cursor: Skills-first with Cursor rule references\n - Windsurf: Skills-first with Windsurf rule references\n - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration\n - Qwen Code: Skills-first with Qwen-branded path and prompt rewrites\n - Hermes Agent: Category-based skills under `skills/gsd/`\n - CodeBuddy: Skills-first with CodeBuddy path and prompt rewrites\n - Cline: Writes `.clinerules` for rule-based integration\n - Augment Code: Skills-first with full skill conversion and config management\n5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths\n6. **Settings integration** — Registers hooks in runtime's `settings.json`\n7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-update --reapply`\n8. **Manifest tracking** — Writes `gsd-file-manifest.json` for clean uninstall\n9. **Uninstall mode** — `--uninstall` removes all GSD files, hooks, and settings\n\nInstall-time file moves, stale-artifact cleanup, config rewrites, and user-data\npreservation are governed by the Installer Migration Module. See\n[Installer Migrations](installer-migrations.md) and\n[ADR 0008](adr/0008-installer-migration-module.md).\nThe migration module also owns the gated first-time baseline scan for legacy\ninstalls, classifying known runtime install surfaces before later migrations\nremove or rewrite anything.\n\n### Platform Handling\n\n- **Windows:** `windowsHide` on child processes, EPERM/EACCES protection on protected directories, path separator normalization\n- **WSL:** Detects Windows Node.js running on WSL and warns about path mismatches\n- **Docker/CI:** Supports `CLAUDE_CONFIG_DIR` env var for custom config directory locations\n\n---\n\n## Hook System\n\n### Architecture\n\n```\nRuntime Engine (Claude Code / Gemini CLI)\n │\n ├── statusLine event ──► gsd-statusline.js\n │ Reads: stdin (session JSON)\n │ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)\n │\n ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js\n │ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)\n │ Writes: stdout (hookSpecificOutput with additionalContext warning)\n │\n └── SessionStart event ──► gsd-check-update.js\n Reads: VERSION file\n Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)\n```\n\n### Context Monitor Thresholds\n\n\n| Remaining Context | Level | Agent Behavior |\n| ----------------- | -------- | --------------------------------------- |\n| > 35% | Normal | No warning injected |\n| ≤ 35% | WARNING | \"Avoid starting new complex work\" |\n| ≤ 25% | CRITICAL | \"Context nearly exhausted, inform user\" |\n\n\nDebounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce.\n\n### Safety Properties\n\n- All hooks wrap in try/catch, exit silently on error\n- stdin timeout guard (3s) prevents hanging on pipe issues\n- Stale metrics (>60s old) are ignored\n- Missing bridge files handled gracefully (subagents, fresh sessions)\n- Context monitor is advisory — never issues imperative commands that override user preferences\n\n### Package Legitimacy Gate (v1.42.1)\n\nThe researcher → planner → executor pipeline includes a supply-chain gate against slopsquatting (AI-hallucinated package names pre-registered with malicious post-install scripts).\n\n**Threat model:** GSD automates the full path from \"researcher names a package\" to \"executor runs `npm install`\". A hallucinated name that passes `npm view` (proving only registration, not legitimacy) would previously flow through undetected. ~20% of AI-generated package references are hallucinated; ~43% of those names recur consistently across prompts, making pre-registration economically viable for attackers.\n\n**Gate layers:**\n\n| Layer | Component | Action |\n|-------|-----------|--------|\n| Research | `gsd-phase-researcher` | Runs `slopcheck install --json`; writes `## Package Legitimacy Audit` table to RESEARCH.md; strips `[SLOP]` packages before RESEARCH.md is written |\n| Planning | `gsd-planner` | Reads Audit table; inserts `checkpoint:human-verify` before any `[ASSUMED]` or `[SUS]` install task; adds `T-{phase}-SC` STRIDE supply-chain row to `` |\n| Execution | `gsd-executor` | RULE 3 excludes package installation from auto-fix scope; failed installs surface as checkpoints, never silent substitutions |\n\n**Claim provenance integration:** Package names discovered via WebSearch are tagged `[ASSUMED]` (not `[VERIFIED]`) regardless of `npm view` result. This extends the existing `[ASSUMED]` / `[VERIFIED]` / `[CITED]` provenance system by enforcing the provenance tag as a hard gate at the install boundary — `[ASSUMED]` always generates a `checkpoint:human-verify` in PLAN.md.\n\n**Ecosystem coverage:** The researcher uses registry-specific verification commands — `npm view` (Node), `pip index versions` (Python), `cargo search` (Rust) — rather than a single generic check. This catches cross-ecosystem hallucination (~9% rate documented in 2025 USENIX research).\n\n**Graceful degradation:** If `slopcheck` is unavailable, every recommended package is tagged `[ASSUMED]` and gated with a checkpoint. Research and planning proceed; the system never hard-fails on a missing tool dependency.\n\n**External dependency:** `slopcheck` (MIT, pip-installable). If abandoned, the `[ASSUMED]`-gate fallback maintains human-checkpoint coverage.\n\n---\n\n### Security Hooks (v1.27)\n\n**Prompt Guard** (`gsd-prompt-guard.js`):\n\n- Triggers on Write/Edit to `.planning/` files\n- Scans content for prompt injection patterns (role override, instruction bypass, system tag injection)\n- Advisory-only — logs detection, does not block\n- Patterns are inlined (subset of `security.cjs`) for hook independence\n\n**Workflow Guard** (`gsd-workflow-guard.js`):\n\n- Triggers on Write/Edit to non-`.planning/` files\n- Detects edits outside GSD workflow context (no active `/gsd-` command or Task subagent)\n- Advises using `/gsd-quick` or `/gsd-fast` for state-tracked changes\n- Opt-in via `hooks.workflow_guard: true` (default: false)\n\n---\n\n## Runtime Abstraction\n\nGSD supports multiple AI coding runtimes through a unified command/workflow architecture:\n\n### Runtime Install Contract Matrix\n\nThis matrix describes the runtime surfaces the installer materializes today.\nThe migration-specific ownership and source snapshots live in\n[Installer Migrations](installer-migrations.md#runtime-configuration-contract-registry).\n\n| Runtime | Global root | Local root | Invocation surface | Agent surface | Config and hooks |\n| --- | --- | --- | --- | --- | --- |\n| Claude Code | `~/.claude` | `./.claude` | Global `skills/gsd-*/SKILL.md`; local `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` hook and statusLine entries |\n| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` or `opencode.jsonc`; no GSD hooks |\n| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` or `kilo.jsonc`; no GSD hooks |\n| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` feature flag, hooks, and statusline |\n| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | `agents/` source markdown plus per-agent TOML | `config.toml` `[agents.gsd-*]`, `[features].hooks` (canonical; legacy alias `codex_hooks` is recognized and migrated forward on reinstall, #3566), and hook tables |\n| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` and `copilot-instructions.md` | `.agent.md` files | No GSD hooks or statusline |\n| Antigravity | `~/.gemini/antigravity` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Gemini-style `settings.json` hook entries when installed by GSD |\n| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | No GSD hooks or statusline |\n| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` plus `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Cline | `~/.cline` | project root | `.clinerules` | Rules only | No GSD hooks or statusline |\n\n### Upstream Contract Sources\n\nRuntime install expectations are checked against primary documentation where\navailable. The current source snapshot is 2026-05-11:\n\n- Claude Code: Anthropic slash commands, settings, hooks, and subagents docs.\n- OpenCode and Kilo: OpenCode config docs and Kilo custom subagent docs.\n- Gemini CLI and Qwen Code: command/config docs; Qwen command docs were last\n updated 2026-05-06.\n- Codex: OpenAI Codex docs and `config-schema.json`; the installer also carries\n Codex 0.124.0 compatibility for agent table shape.\n- Copilot, Cursor, Cline, Augment, Hermes, and CodeBuddy: vendor docs for\n custom instructions, rules, skills, or config.\n- Antigravity, Windsurf, and Trae: source-limited rows. The installer documents\n current compatibility shims, and migrations must refresh those sources before\n rewriting their config.\n\n### Abstraction Points\n\n1. **Tool name mapping** — Each runtime has its own tool names (e.g., Claude's `Bash` → Copilot's `execute`)\n2. **Hook event names** — Claude uses `PostToolUse`, Gemini uses `AfterTool`\n3. **Agent frontmatter** — Each runtime has its own agent definition format\n4. **Path conventions** — Each runtime stores config in different directories\n5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection\n\nThe installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.\n","docs/agents/cjs-sdk-seam.md":"# CJS↔SDK Hard-Seam Migration: Complete Reference\n## Issue #3575 (Parent: #3524)\n\n---\n\n## Migration overview\n\nThe CJS↔SDK hard-seam migration (#3524) eliminates a class of config-schema drift bugs by introducing single sources of truth at every decision point where CJS and SDK code previously diverged. The migration proceeded in six phases:\n\n| Phase | PR | Summary |\n|-------|----|---------|\n| Phase 1 | [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) | `state-document` Shared Module — source-of-truth at `sdk/src/state-document/`, generator, freshness check, CJS Adapter (`state-document.generated.cjs`). Worked example for the pattern. |\n| Phase 2 | [#3540](https://github.com/gsd-build/get-shit-done/pull/3540) | `configuration` Shared Module — `sdk/shared/config-schema.manifest.json` + `sdk/shared/config-defaults.manifest.json` as data manifests; generator + freshness check + CJS Adapter. |\n| Phase 3 | [#3548](https://github.com/gsd-build/get-shit-done/pull/3548) | `workstream-inventory` Shared Module — source-of-truth at `sdk/src/workstream-inventory/`, builder, generator, freshness check, CJS Adapter. |\n| Phase 4 | [#3554](https://github.com/gsd-build/get-shit-done/pull/3554) | `project-root` Shared Module — source-of-truth at `sdk/src/project-root/`, generator, freshness check, CJS Adapter. |\n| Phase 5.0 | [#3558](https://github.com/gsd-build/get-shit-done/pull/3558) | `runtime-bridge-sync` worker — enables CJS-side execution of SDK native handlers; state.* family initial router delegation via `executeForCjs`. |\n| Phase 5.1 | [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) | `state.*` router delegation complete — all known state subcommands delegated via `executeForCjs`; Phase 5.0 worker bug fix. |\n| Phase 6 | [#3577](https://github.com/gsd-build/get-shit-done/pull/3577) (closes [#3575](https://github.com/gsd-build/get-shit-done/issues/3575)) | Enforcement hardening + Final completion — hand-sync drift lint, CODEOWNERS, 6 family-router migrations, 5 Shared Module migrations (plan-scan, secrets, schema-detect, decisions, workstream-name-policy), workstream native support, parity fixes. Migration feature-complete: 22 cooperating siblings, 0 backlog pairs. |\n\n---\n\n## Phase 6 Retrospective: 15 config-schema drift bugs\n\nThis section captures 15 recurring config-schema drift bugs that motivated the migration. For each, we record what drifted, the surgical fix, and which Phase 6 enforcement layer would have prevented it.\n\n---\n\n### #1535 — Silent failure on unrecognized config.json keys\n- **Drifted:** `loadConfig` silently ignored any top-level key in `.planning/config.json` not in `VALID_CONFIG_KEYS`, giving users no feedback when hand-edited or external-tool-added keys had no effect.\n- **Fix landed:** PR #1542 — added stderr warning listing unrecognized keys.\n- **Would have been blocked by:** **handsync lint** — a seam-aware linter would forbid having parallel hand-authored config validators (CJS `config.cjs` and SDK `config-mutation.ts`) that could silently diverge.\n\n---\n\n### #1542 — fix(config): warn on unrecognized keys in config.json instead of silent drop\n- **Drifted:** No drift in this bug itself; it *fixed* #1535's silent-drop behavior by adding the warning.\n- **Fix landed:** PR #1542 — merged as the direct fix for #1535.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check on config validation) — both CJS and SDK config paths would be regenerated from a single source-of-truth schema module, eliminating the silent-drop risk.\n\n---\n\n### #2047 — bug: config-set rejects intel.enabled despite being a documented config key\n- **Drifted:** `intel.enabled` was documented in workflows and gated in runtime code (`intel.cjs:58`), but missing from `VALID_CONFIG_KEYS` in `config.cjs`, so `config-set` rejected it.\n- **Fix landed:** PR #2021 — added `intel.enabled` to `VALID_CONFIG_KEYS` in CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every config key gated in runtime code or documented in workflows must appear in the validator allowlist.\n\n---\n\n### #2052 — fix(config): add intel.enabled to VALID_CONFIG_KEYS\n- **Drifted:** Same as #2047 (missing from allowlist).\n- **Fix landed:** PR #2021 (same PR as #2047 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2047.\n\n---\n\n### #2638 — bug: loadConfig writes sub_repos to top-level, then warns it's unknown\n- **Drifted:** After #2561 canonicalized `sub_repos` to `planning.sub_repos`, the legacy migration and filesystem auto-sync in `loadConfig` still wrote to top-level `parsed.sub_repos`, which was then flagged as unknown.\n- **Fix landed:** PR #2668 — rewrote both paths to target `parsed.planning.sub_repos` and deleted stale top-level copy.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check for config shape) — the canonical location for `sub_repos` would be codified in a schema, and any code path writing to it would be verified against that schema at lint time.\n\n---\n\n### #2655 — fix(core): write sub_repos to planning.sub_repos, not top-level\n- **Drifted:** Same as #2638.\n- **Fix landed:** PR #2668 (same as #2638 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2638.\n\n---\n\n### #2653 — bug: SDK config-set rejects documented config keys accepted by CJS config-set\n- **Drifted:** SDK's `config-mutation.ts` had a hand-maintained `VALID_CONFIG_KEYS` set that had drifted **28 keys** behind CJS's `config-schema.cjs`, so documented commands like `gsd-sdk query config-set planning.sub_repos` were rejected.\n- **Fix landed:** PR #2670 — extracted shared `sdk/src/query/config-schema.ts` module mirroring CJS exactly; added parity test to fail on future drift.\n- **Would have been blocked by:** **manifest data isolation** — the config schema would live in one place (e.g., `sdk/shared/config.manifest.json`), and both CJS and SDK would read it, eliminating the possibility of independent drift.\n\n---\n\n### #2670 — fix(#2653): eliminate SDK↔CJS config-schema drift\n- **Drifted:** Same as #2653 (28-key drift).\n- **Fix landed:** PR #2670 (same as #2653 fix).\n- **Would have been blocked by:** **manifest data isolation** — same as #2653.\n\n---\n\n### #2687 — bug: loadConfig warns on valid dynamic-pattern containers in .planning/config.json\n- **Drifted:** Keys like `review.models.` were registered in `config-schema.cjs`'s `DYNAMIC_KEY_PATTERNS` but absent from the hand-maintained `KNOWN_TOP_LEVEL` set in `core.cjs`, causing false-positive \"unknown key\" warnings.\n- **Fix landed:** PR #2706 — added `topLevel` field to `DYNAMIC_KEY_PATTERNS` entries; derived `KNOWN_TOP_LEVEL` from schema instead of maintaining it manually.\n- **Would have been blocked by:** **per-Module drift lint** — the validator that builds `KNOWN_TOP_LEVEL` would be regenerated from the schema each run, not hand-maintained.\n\n---\n\n### #2706 — fix(#2687): loadConfig no longer warns on valid dynamic-pattern containers\n- **Drifted:** Same as #2687 (false warnings on valid dynamic keys).\n- **Fix landed:** PR #2706 (same as #2687 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2687.\n\n---\n\n### #2798 — context_window missing from VALID_CONFIG_KEYS\n- **Drifted:** `context_window` was documented in workflows and read in SDK runtime (`init.js:190`, `validate.js:575`), but missing from allowlists in both `config-mutation.ts` and `config-schema.cjs`, so writes were rejected.\n- **Fix landed:** PR #2816 — added `context_window` to `VALID_CONFIG_KEYS` in both SDK and CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every key read at runtime must be in the allowlist.\n\n---\n\n### #2816 — fix(#2798): add context_window to VALID_CONFIG_KEYS allowlist\n- **Drifted:** Same as #2798 (missing from allowlists).\n- **Fix landed:** PR #2816 (same as #2798 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2798.\n\n---\n\n### #3055 — bug: top-level branching_strategy silently becomes \"none\"\n- **Drifted:** `.planning/config.json` with top-level `branching_strategy: \"phase\"` was flagged as unknown and dropped by validator, causing `loadConfig` to fall back to the `\"none\"` default, so phase commits landed on the operator's current branch instead of creating `gsd/phase-{N}` branches.\n- **Fix landed:** PR #3116 — SDK-side only; added legacy normalization in `mergeDefaults()` to graft top-level value into canonical `git.branching_strategy` slot before validation.\n- **Would have been blocked by:** **per-Module drift lint** — the canonical location for `branching_strategy` would be codified in schema; validator would not strip the value before migrations had a chance to run, or CJS and SDK would share the same migration code.\n\n---\n\n### #3116 — fix: normalize legacy top-level branching_strategy into git config\n- **Drifted:** Same as #3055 (legacy top-level shape not normalized before validator strips it).\n- **Fix landed:** PR #3116 (SDK-side normalization in `mergeDefaults()`).\n- **Would have been blocked by:** **per-Module drift lint** — same as #3055, but SDK-side fix would be shared with CJS via seam layer instead of being ported separately.\n\n---\n\n### #3523 — bug: CJS loadConfig warns top-level branching_strategy 'will be ignored', but actively reads it\n- **Drifted:** After PR #3116 fixed the SDK side, the CJS path still emitted false \"will be ignored\" warnings on the same legacy top-level key, because `KNOWN_TOP_LEVEL` derivation extracted top-level names from `VALID_CONFIG_KEYS` (which contains `'git.branching_strategy'` but not `'branching_strategy'`), and the warning was factually incorrect — `core.cjs:485` does read the legacy value via fallback logic.\n- **Fix landed:** PR #3527 — added `'branching_strategy'` to the `KNOWN_TOP_LEVEL` hand-maintained list under the deprecated-keys bucket, suppressing the false warning.\n- **Would have been blocked by:** **runtime-bridge delegation** — if CJS and SDK config loading shared a common normalization routine (via `executeForCjs` or a shared seam module), the SDK fix in #3116 would automatically apply to CJS; no separate CJS-side warning would be possible.\n\n---\n\n## Surprises\n\nNone. All 15 bugs are genuine CJS↔SDK schema/validation drift, exactly the class the seam migration prevents.\n\n## Phase 6 Enforcement Summary\n\nThe seam migration introduces these layers:\n\n1. **handsync lint** (`scripts/lint-shared-module-handsync.cjs`) — Forbids parallel hand-authored validator modules; catches #1535, #2047, #2798.\n2. **freshness check** (`sdk/scripts/check--fresh.mjs`) — Regenerates config validators from schema each run; catches #2687, #3055.\n3. **manifest data isolation** (`sdk/shared/*.manifest.json`) — Single source-of-truth for schema; catches #2653.\n4. **per-Module drift lint** — Combination of freshness checks and schema-derived allowlists; catches #2638, #2687, #3055.\n5. **runtime-bridge delegation** (`executeForCjs` + shared seam modules) — Eliminates parallel CJS/SDK implementations; catches #3523 by preventing separate CJS warning logic.\n\nTogether, these layers eliminate the 15-bug class by enforcing single sources of truth at each decision point.\n\n---\n\n## Guide: Adding a new Shared Module\n\nUse this when you want to extract a new piece of data or logic that both CJS and SDK currently duplicate hand-by-hand. Phase 1's `state-document` migration is the worked example.\n\n**Step 1 — Create the source-of-truth file**\n\n```text\nsdk/src//index.ts\n```\n\nThis is the canonical definition. It may export a schema, a set of keys, a type, or a data object. It must not import from CJS or from generated files.\n\n**Step 2 — Write the generator script**\n\n```text\nsdk/scripts/gen-.mjs\n```\n\nThe generator reads `sdk/src//index.ts` (or `sdk/shared/.manifest.json` for pure-data manifests), produces a generated output file (either `sdk/src/.generated.ts` or `get-shit-done/bin/lib/.generated.cjs`), and exits 0. It must be idempotent: running it twice produces the same output.\n\n**Step 3 — Write the freshness check**\n\n```text\nsdk/scripts/check--fresh.mjs\n```\n\nThe freshness check re-runs the generator into a temp location, diffs against the committed file, and exits 1 with a clear message if they diverge. This is what CI runs.\n\n**Step 4 — Write the parity test** (optional but recommended)\n\n```text\ntests/-parity.test.cjs\n```\n\nAssert that the CJS Adapter and the SDK source-of-truth agree on every field that matters (key sets, defaults, schema shape). This test catches generator bugs that the freshness check cannot.\n\n**Step 5 — Wire CI**\n\nAdd a step in `.github/workflows/test.yml` after the existing freshness-check block (before \"Run tests with coverage\"), gated on `matrix.os == 'ubuntu-latest' && matrix.node-version == 24`:\n\n```yaml\n- name: SDK generated artifact drift check\n if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24\n shell: bash\n run: node sdk/scripts/check--fresh.mjs\n```\n\n**Step 6 — Run inventory regen**\n\nIf the module affects `CONTEXT.md`'s module inventory, update that section. Also update `scripts/shared-module-handsync-allowlist.json`: move any matching entry from `migrateMeBacklog` to `cooperatingSiblings` (or remove it entirely if the CJS hand-copy is now deleted).\n\n**Step 7 — Update CODEOWNERS**\n\nAdd the new source-of-truth path to `.github/CODEOWNERS` under the Phase 6 block to make the architectural ownership explicit.\n\n**Reference:** Phase 1 PR [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) — `state-document` migration.\n\n---\n\n## Guide: Adding a new canonical command\n\nUse this when adding a new `gsd-sdk query .` that should be handled natively in the SDK (not delegated to CJS). Phase 5.1's `state.update` migration (PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574)) is the worked example.\n\n**Step 1 — Declare in the command manifest**\n\nAdd the command definition to `sdk/src/query/command-manifest..ts`. Include the full argument schema and a `handler` reference.\n\n**Step 2 — Implement the SDK handler**\n\nWrite the handler in `sdk/src/query/.ts` (or inline in the manifest file for simple cases). The handler receives validated args and the runtime context; it must not shell out to CJS.\n\n**Step 3 — Add CJS router delegate (Phase 5.1+ pattern)**\n\nIn the family's CJS command router (e.g. `get-shit-done/bin/lib/state-command-router.cjs`), add a delegate case that calls `executeForCjs(subcommand, args)` from `cjs-command-router-adapter.cjs`. This ensures the CJS binary dispatches to the SDK native handler rather than re-implementing the logic.\n\n**Step 4 — Add a golden parity test**\n\nAdd a test in `tests/-command-router.test.cjs` (or a new file if the family has no test yet) that:\n1. Invokes the command via the SDK query path.\n2. Invokes the command via the CJS router path.\n3. Asserts both produce identical output.\n\nThis test enforces that the delegate and the native handler stay aligned.\n\n**Reference:** Phase 5.1 PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) — `state.update` delegation.\n\n---\n\n## Phase 6 Final Completion Summary\n\nPhase 6 (issue #3575, PR #3577) is feature-complete. The migration is done.\n\n**What shipped in Phase 6:**\n\n- **Shared Modules migrated (5 total in Phase 6):** `plan-scan`, `secrets`, `schema-detect`, `decisions`, `workstream-name-policy`. Each follows the full pattern: SDK source-of-truth, generator (`gen-.mjs`), freshness check (`check--fresh.mjs`), generated CJS artifact (`.generated.cjs`), CJS shim re-export, parity test, CI step, pre-commit hook, CODEOWNERS entry.\n- **Workstream native support:** The sync bridge worker now correctly threads `workstream` through to `registry.dispatch()`. `GSDTransport` no longer forces subprocess for workstream-scoped requests. Workstream-scoped state commands execute natively.\n- **State parity divergences resolved:** `state.record-metric` and `state.prune` SDK handlers now match CJS semantics exactly.\n- **MIGRATE_ME pairs resolved:** `decisions` and `workstream-name-policy` migrated from `migrateMeBacklog` to `cooperatingSiblings` as ADAPTER-OVER-MODULE.\n- **Lint final state:** 22 cooperating siblings, 0 backlog pairs.\n\n**Decisions migration specifics (B1):**\n- SDK `decisions.ts` regex aligned to CJS: `D-([A-Za-z0-9_-]+)` (alphanumeric IDs like `D-INFRA-01` accepted).\n- SDK returns richer `{id, text, category, tags, trackable}`; CJS callers using only `{id, text}` safely ignore extras.\n- Parity test: `tests/decisions-generator.test.cjs` (15 tests covering numeric IDs, alphanumeric IDs, richer schema fields).\n\n**Workstream-name-policy migration specifics (B2):**\n- Added `hasInvalidPathSegment` and `isValidActiveWorkstreamName` to SDK `workstream-name-policy.ts`.\n- `validateWorkstreamName` is now an alias for `isValidActiveWorkstreamName` (consistent with CJS semantics).\n- Parity test: `tests/workstream-name-policy-generator.test.cjs` (19 tests covering all four exports).\n\n---\n\n## Open follow-ups\n\nNo migration items remain. The following are future quality candidates, not defects:\n\n- **`config.cjs` / `sdk/src/config.ts`** — These files are CJS-CLI-ONLY (per allowlist classification). The `config.cjs` file contains only CLI command handlers that use sync CJS APIs; `sdk/src/config.ts` provides the async SDK layer. They serve disjoint surfaces. A future migration would require converting the CLI handlers to async + SDK patterns, which is a larger refactor out of scope for this migration cycle.\n- **`intel.cjs` / `sdk/src/query/intel.ts`** — Intentional architectural divergence (different file naming conventions between CJS and SDK; documented in allowlist). A future migration would require reconciling INTEL_FILES naming, which is a breaking change for existing consumers.\n- **`model-catalog.cjs` / `sdk/src/model-catalog.ts`** — Both sides read from `sdk/shared/model-catalog.json` independently (ADAPTER-OVER-MODULE pattern). This is intentional; the shared JSON is the source-of-truth. No duplication of logic between CJS and SDK consumers.\n","docs/agents/domain.md":"# Domain Docs\n\nHow engineering skills consume this repo's domain documentation.\n\n## Layout: single-context\n\n```\n/\n├── CONTEXT.md ← domain glossary + recurring PR rules + workflow learnings\n├── docs/adr/ ← architectural decisions\n│ ├── 0001-dispatch-policy-module.md\n│ └── 0002-command-contract-validation-module.md\n└── ...\n```\n\n## Before exploring, read these\n\n1. **`CONTEXT.md`** at the repo root — domain terms, module names, recurring PR mistakes, workflow learnings. Read in full before naming anything or proposing architecture changes.\n2. **`docs/adr/`** — read ADRs relevant to the area you're working in before proposing structural changes. If your output contradicts an ADR, surface it explicitly:\n > *Contradicts ADR-0002 — but worth reopening because…*\n\nIf either file doesn't exist yet, proceed silently.\n\n## Use the glossary's vocabulary\n\nWhen naming modules, writing issue titles, test descriptions, or commit messages — use terms as defined in `CONTEXT.md`. Don't drift to synonyms. If you need a concept that isn't in the glossary, note it for `/grill-with-docs` rather than inventing language.\n\n## CONTEXT.md sections\n\n- **Domain terms** — canonical module names and seam vocabulary (Dispatch Policy Module, Command Contract Validation Module, etc.)\n- **Recurring PR mistakes** — CodeRabbit findings that recur; check before writing tests, shell scripts, changesets, or docs\n- **Workflow learnings** — patterns learned from triage + PR cycles; check before writing new command/workflow files or test paths\n","docs/agents/issue-tracker.md":"# Issue tracker: GitHub\n\nIssues for this repo live in **GitHub Issues** at `gsd-build/get-shit-done`.\n\n## Auth\n\nUse the configured GitHub CLI session for this checkout. Do not require a\nrepo-local `.envrc` before running `gh`.\n\n## Conventions\n\n- **Create**: `gh issue create --repo gsd-build/get-shit-done --title \"...\" --body \"...\"`\n- **Read**: `gh issue view --repo gsd-build/get-shit-done --comments`\n- **List**: `gh issue list --repo gsd-build/get-shit-done --state open --json number,title,labels --jq '...'`\n- **Comment**: `gh issue comment --repo gsd-build/get-shit-done --body \"...\"`\n- **Label**: `gh issue edit --repo gsd-build/get-shit-done --add-label \"...\" --remove-label \"...\"`\n- **Close**: `gh issue close --repo gsd-build/get-shit-done --comment \"...\"`\n\nAlways pass `--repo gsd-build/get-shit-done` explicitly — the local clone has multiple remotes and `gh` may resolve to the wrong one.\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a GitHub issue at `gsd-build/get-shit-done`.\n\n## When a skill says \"fetch the relevant ticket\"\n\nRun `gh issue view --repo gsd-build/get-shit-done --comments`.\n","docs/agents/triage-labels.md":"# Triage Labels\n\nMaps the five canonical triage roles to the actual label strings in `gsd-build/get-shit-done`.\n\n| Canonical role | Label in this repo | Notes |\n|-------------------|--------------------------|----------------------------------------------------------------|\n| `needs-triage` | `needs-triage` | Auto-applied by GitHub Action on every new issue |\n| `needs-info` | `needs-reproduction` | Waiting on reporter — cannot reproduce, more info required |\n| `ready-for-agent` | `confirmed` | Bug verified + fully specified — AFK agent can pick up |\n| `ready-for-human` | `approved-enhancement` / `approved-feature` | Enhancement/feature approved by maintainer — human codes it |\n| `wontfix` | `wontfix` | Will not be actioned |\n\n## Notes on this repo's label model\n\n- `confirmed` is the AFK-agent-ready signal for **bugs**. It means \"verified to exist and reproducible.\"\n- For **enhancements** and **features**, maintainer approval is `approved-enhancement` / `approved-feature` respectively. A contributor (human or agent) may not write code until one of these is applied.\n- There is no separate \"ready-for-human\" vs \"ready-for-agent\" distinction for enhancements — both flow through the same `approved-*` labels. If the work requires human judgment (design decisions, external access), note it in the issue body.\n- `needs-triage` is removed when any other state label is applied.\n- `needs-reproduction` is used instead of the generic `needs-info` — be specific in triage comments about what reproduction steps or information are missing.\n","docs/skills/discovery-contract.md":"# Skill Discovery Contract\n\n> Canonical rules for scanning, inventorying, and rendering GSD skills.\n\n## Root Categories\n\n### Project Roots\n\nScan these roots relative to the project root:\n\n- `.claude/skills/`\n- `.agents/skills/`\n- `.cursor/skills/`\n- `.github/skills/`\n- `./.codex/skills/`\n\nThese roots are used for project-specific skills and for the project `CLAUDE.md` skills section.\n\n### Managed Global Roots\n\nScan these roots relative to the user home directory:\n\n- `~/.claude/skills/`\n- `~/.codex/skills/`\n\nThese roots are used for managed runtime installs and inventory reporting.\n\n### Deprecated Import-Only Root\n\n- `~/.claude/get-shit-done/skills/`\n\nThis root is kept for legacy migration only. Inventory code may report it, but new installs should not write here.\n\n### Legacy Claude Commands\n\n- `~/.claude/commands/gsd/`\n\nThis is not a skills root. Discovery code only checks whether it exists so inventory can report legacy Claude installs.\n\n## Normalization Rules\n\n- Scan only subdirectories that contain `SKILL.md`.\n- Read `name` and `description` from YAML frontmatter.\n- Use the directory name when `name` is missing.\n- Extract trigger hints from body lines that match `TRIGGER when: ...`.\n- Treat `gsd-*` directories as installed framework skills.\n- Treat `~/.claude/get-shit-done/skills/` entries as deprecated/import-only.\n- Treat `~/.claude/commands/gsd/` as legacy command installation metadata, not skills.\n\n## Scanner Behavior\n\n### `sdk/src/query/skills.ts`\n\n- Returns a de-duplicated list of discovered skill names.\n- Scans project roots plus managed global roots.\n- Does not scan the deprecated import-only root.\n\n### `get-shit-done/bin/lib/profile-output.cjs`\n\n- Builds the project `CLAUDE.md` skills section.\n- Scans project roots only.\n- Skips `gsd-*` directories so the project section stays focused on user/project skills.\n- Adds `.codex/skills/` to the project discovery set.\n\n### `get-shit-done/bin/lib/init.cjs`\n\n- Generates the skill inventory object for `skill-manifest`.\n- Reports `skills`, `roots`, `installation`, and `counts`.\n- Marks `gsd_skills_installed` when any discovered skill name starts with `gsd-`.\n- Marks `legacy_claude_commands_installed` when `~/.claude/commands/gsd/` contains `.md` command files.\n\n## Inventory Shape\n\n`skill-manifest` returns a JSON object with:\n\n- `skills`: normalized skill entries\n- `roots`: the canonical roots that were checked\n- `installation`: summary booleans for installed GSD skills and legacy Claude commands\n- `counts`: small inventory counts for downstream consumers\n\nEach skill entry includes:\n\n- `name`\n- `description`\n- `triggers`\n- `path`\n- `file_path`\n- `root`\n- `scope`\n- `installed`\n- `deprecated`\n\n","docs/zh-CN/references/checkpoints.md":"# 检查点\n\n计划自主执行。检查点用于规范化需要人工验证或决策的交互点。\n\n**核心原则：** Claude 用 CLI/API 自动化一切。检查点用于验证和决策，而非手动工作。\n\n**黄金法则：**\n1. **如果 Claude 能运行，Claude 就运行** - 绝不让用户执行 CLI 命令、启动服务器或运行构建\n2. **Claude 设置验证环境** - 启动开发服务器、填充数据库、配置环境变量\n3. **用户只做需要人工判断的事** - 视觉检查、UX 评估、\"这个感觉对吗？\"\n4. **密钥来自用户，自动化来自 Claude** - 询问 API 密钥，然后 Claude 通过 CLI 使用它们\n5. **自动模式绕过验证/决策检查点** — 当 config 中 `workflow._auto_chain_active` 或 `workflow.auto_advance` 为 true 时：human-verify 自动批准，decision 自动选择第一个选项，human-action 仍会停止（认证门控无法自动化）\n\n## 检查点类型\n\n### checkpoint:human-verify（最常见 - 90%）\n\n**何时使用：** Claude 完成自动化工作，人工确认其正常工作。\n\n**用于：**\n- 视觉 UI 检查（布局、样式、响应式）\n- 交互流程（点击向导、测试用户流程）\n- 功能验证（功能按预期工作）\n- 音频/视频播放质量\n- 动画流畅度\n- 无障碍测试\n\n**结构：**\n```xml\n\n [Claude 自动化并部署/构建的内容]\n \n [测试的确切步骤 - URL、命令、预期行为]\n \n [如何继续 - \"approved\"、\"yes\" 或描述问题]\n\n```\n\n**示例：UI 组件（展示关键模式：Claude 在检查点之前启动服务器）**\n```xml\n\n 构建响应式仪表板布局\n src/components/Dashboard.tsx, src/app/dashboard/page.tsx\n 创建带侧边栏、标题和内容区域的仪表板。使用 Tailwind 响应式类处理移动端。\n npm run build 成功，无 TypeScript 错误\n 仪表板组件构建无错误\n\n\n\n 启动开发服务器用于验证\n 在后台运行 `npm run dev`，等待 \"ready\" 消息，捕获端口\n curl http://localhost:3000 返回 200\n 开发服务器运行于 http://localhost:3000\n\n\n\n 响应式仪表板布局 - 开发服务器运行于 http://localhost:3000\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 桌面端 (>1024px): 左侧边栏，右侧内容，顶部标题\n 2. 平板端 (768px): 侧边栏折叠为汉堡菜单\n 3. 移动端 (375px): 单列布局，出现底部导航\n 4. 任何尺寸无布局偏移或水平滚动\n \n 输入 \"approved\" 或描述布局问题\n\n```\n\n### checkpoint:decision（9%）\n\n**何时使用：** 人工必须做出影响实现方向的选择。\n\n**用于：**\n- 技术选型（哪个认证提供商、哪个数据库）\n- 架构决策（monorepo 还是独立仓库）\n- 设计选择（配色方案、布局方式）\n- 功能优先级（构建哪个变体）\n- 数据模型决策（模式结构）\n\n**结构：**\n```xml\n\n [正在决策的内容]\n [为什么这个决策重要]\n \n \n \n \n [如何表明选择]\n\n```\n\n**示例：认证提供商选择**\n```xml\n\n 选择认证提供商\n \n 应用需要用户认证。三个可靠选项各有权衡。\n \n \n \n \n \n \n 选择：supabase、clerk 或 nextauth\n\n```\n\n### checkpoint:human-action（1% - 罕见）\n\n**何时使用：** 操作没有 CLI/API 且需要仅人工交互，或者 Claude 在自动化过程中遇到认证门控。\n\n**仅用于：**\n- **认证门控** - Claude 尝试了 CLI/API 但需要凭证（这不是失败）\n- 邮箱验证链接（点击邮件）\n- 短信两步验证码（手机验证）\n- 人工账户审批（平台需要人工审核）\n- 信用卡 3D Secure 流程（基于 Web 的支付授权）\n- OAuth 应用审批（基于 Web 的审批）\n\n**不要用于预定的手动工作：**\n- 部署（使用 CLI - 如需要则认证门控）\n- 创建 webhooks/数据库（使用 API/CLI - 如需要则认证门控）\n- 运行构建/测试（使用 Bash 工具）\n- 创建文件（使用 Write 工具）\n\n**结构：**\n```xml\n\n [人工必须做什么 - Claude 已完成所有可自动化的]\n \n [Claude 已自动化的内容]\n [需要人工操作的一件事]\n \n [Claude 之后可以检查的内容]\n [如何继续]\n\n```\n\n**示例：认证门控（动态检查点）**\n```xml\n\n 部署到 Vercel\n .vercel/, vercel.json\n 运行 `vercel --yes` 进行部署\n vercel ls 显示部署，curl 返回 200\n\n\n\n\n\n 认证 Vercel CLI 以便我继续部署\n \n 我尝试部署但收到认证错误。\n 运行：vercel login\n 这将打开你的浏览器 - 完成认证流程。\n \n vercel whoami 返回你的账户邮箱\n 认证完成后输入 \"done\"\n\n\n\n\n\n 重试 Vercel 部署\n 运行 `vercel --yes`（已认证）\n vercel ls 显示部署，curl 返回 200\n\n```\n\n**关键区别：** 认证门控是 Claude 遇到认证错误时动态创建的。不是预定的 — Claude 先自动化，只有在被阻止时才请求凭证。\n\n## 执行协议\n\n当 Claude 遇到 `type=\"checkpoint:*\"` 时：\n\n1. **立即停止** - 不继续下一个任务\n2. **清晰显示检查点** 使用下面的格式\n3. **等待用户响应** - 不幻想完成\n4. **如可能则验证** - 检查文件、运行测试、任何指定的内容\n5. **恢复执行** - 仅在确认后继续下一个任务\n\n**对于 checkpoint:human-verify:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要验证 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 5/8 任务完成\n任务: 响应式仪表板布局\n\n已构建: /dashboard 的响应式仪表板\n\n如何验证:\n 1. 访问: http://localhost:3000/dashboard\n 2. 桌面端 (>1024px): 侧边栏可见，内容填充剩余空间\n 3. 平板端 (768px): 侧边栏折叠为图标\n 4. 移动端 (375px): 侧边栏隐藏，出现汉堡菜单\n\n────────────────────────────────────────────────────────\n→ 你的操作: 输入 \"approved\" 或描述问题\n────────────────────────────────────────────────────────\n```\n\n**对于 checkpoint:decision:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要决策 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 2/6 任务完成\n任务: 选择认证提供商\n\n决策: 我们应该使用哪个认证提供商？\n\n上下文: 需要用户认证。三个选项各有权衡。\n\n选项:\n 1. supabase - 与我们的数据库内置集成，免费额度\n 优点: 行级安全集成，慷慨的免费额度\n 缺点: UI 定制性较差，生态锁定\n\n 2. clerk - 最佳 DX，10k 用户后付费\n 优点: 精美的预构建 UI，优秀文档\n 缺点: 供应商锁定，规模化时价格问题\n\n 3. nextauth - 自托管，最大控制权\n 优点: 免费，无供应商锁定，广泛采用\n 缺点: 更多设置工作，自行 DIY 安全更新\n\n────────────────────────────────────────────────────────\n→ 你的操作: 选择 supabase、clerk 或 nextauth\n────────────────────────────────────────────────────────\n```\n\n## 认证门控\n\n**认证门控 = Claude 尝试了 CLI/API，收到认证错误。** 不是失败 — 是需要人工输入来解除阻止的门控。\n\n**模式：** Claude 尝试自动化 → 认证错误 → 创建 checkpoint:human-action → 用户认证 → Claude 重试 → 继续\n\n**门控协议：**\n1. 认识到这不是失败 - 缺少认证是正常的\n2. 停止当前任务 - 不要反复重试\n3. 动态创建 checkpoint:human-action\n4. 提供确切的认证步骤\n5. 验证认证有效\n6. 重试原始任务\n7. 正常继续\n\n**关键区别：**\n- 预定的检查点：\"我需要你做 X\"（错误 - Claude 应该自动化）\n- 认证门控：\"我尝试自动化 X 但需要凭证\"（正确 - 解除自动化阻止）\n\n## 自动化参考\n\n**规则：** 如果有 CLI/API，Claude 就做。绝不让人工执行可自动化的工作。\n\n### 服务 CLI 参考\n\n| 服务 | CLI/API | 关键命令 | 认证门控 |\n|------|---------|----------|----------|\n| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |\n| Railway | `railway` | `init`, `up`, `variables set` | `railway login` |\n| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` |\n| Stripe | `stripe` + API | `listen`, `trigger`, API 调用 | .env 中的 API key |\n| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` |\n| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` |\n| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` |\n| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |\n| Node | `npm`/`pnpm` | `install`, `run build`, `test`, `run dev` | N/A |\n| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |\n| Convex | `npx convex` | `dev`, `deploy`, `env set`, `env get` | `npx convex login` |\n\n### 环境变量自动化\n\n**Env 文件：** 使用 Write/Edit 工具。绝不让用户手动创建 .env。\n\n**通过 CLI 的仪表板环境变量：**\n\n| 平台 | CLI 命令 | 示例 |\n|------|----------|------|\n| Convex | `npx convex env set` | `npx convex env set OPENAI_API_KEY sk-...` |\n| Vercel | `vercel env add` | `vercel env add STRIPE_KEY production` |\n| Railway | `railway variables set` | `railway variables set API_KEY=value` |\n| Fly | `fly secrets set` | `fly secrets set DATABASE_URL=...` |\n| Supabase | `supabase secrets set` | `supabase secrets set MY_SECRET=value` |\n\n### 开发服务器自动化\n\n| 框架 | 启动命令 | 就绪信号 | 默认 URL |\n|------|----------|----------|----------|\n| Next.js | `npm run dev` | \"Ready in\" 或 \"started server\" | http://localhost:3000 |\n| Vite | `npm run dev` | \"ready in\" | http://localhost:5173 |\n| Convex | `npx convex dev` | \"Convex functions ready\" | N/A（仅后端）|\n| Express | `npm start` | \"listening on port\" | http://localhost:3000 |\n| Django | `python manage.py runserver` | \"Starting development server\" | http://localhost:8000 |\n\n**服务器生命周期：**\n```bash\n# 后台运行，捕获 PID\nnpm run dev &\nDEV_SERVER_PID=$!\n\n# 等待就绪（最多 30s）\ntimeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'\n```\n\n**端口冲突：** 终止陈旧进程（`lsof -ti:3000 | xargs kill`）或使用备用端口（`--port 3001`）。\n\n**服务器保持运行** 直到检查点结束。仅在计划完成、切换到生产环境或端口需要用于不同服务时终止。\n\n### CLI 安装处理\n\n| CLI | 自动安装？ | 命令 |\n|-----|------------|------|\n| npm/pnpm/yarn | 否 - 询问用户 | 用户选择包管理器 |\n| vercel | 是 | `npm i -g vercel` |\n| gh (GitHub) | 是 | `brew install gh` (macOS) 或 `apt install gh` (Linux) |\n| stripe | 是 | `npm i -g stripe` |\n| supabase | 是 | `npm i -g supabase` |\n| convex | 否 - 使用 npx | `npx convex`（无需安装）|\n| fly | 是 | `brew install flyctl` 或 curl 安装器 |\n| railway | 是 | `npm i -g @railway/cli` |\n\n**协议：** 尝试命令 → \"command not found\" → 可自动安装？→ 是：静默安装，重试 → 否：检查点请求用户安装。\n\n## 检查点前自动化失败处理\n\n| 失败 | 响应 |\n|------|------|\n| 服务器无法启动 | 检查错误，修复问题，重试（不进入检查点）|\n| 端口被占用 | 终止陈旧进程或使用备用端口 |\n| 缺少依赖 | 运行 `npm install`，重试 |\n| 构建错误 | 先修复错误（是 bug，不是检查点问题）|\n| 认证错误 | 创建认证门控检查点 |\n| 网络超时 | 带退避重试，如果持续则检查点 |\n\n**绝不呈现验证环境损坏的检查点。** 如果 `curl localhost:3000` 失败，不要让用户\"访问 localhost:3000\"。\n\n## 可自动化快速参考\n\n| 操作 | 可自动化？| Claude 做？|\n|------|------------|------------|\n| 部署到 Vercel | 是 (`vercel`) | 是 |\n| 创建 Stripe webhook | 是 (API) | 是 |\n| 写入 .env 文件 | 是 (Write 工具) | 是 |\n| 创建 Upstash DB | 是 (`upstash`) | 是 |\n| 运行测试 | 是 (`npm test`) | 是 |\n| 启动开发服务器 | 是 (`npm run dev`) | 是 |\n| 添加环境变量到 Convex | 是 (`npx convex env set`) | 是 |\n| 添加环境变量到 Vercel | 是 (`vercel env add`) | 是 |\n| 填充数据库 | 是 (CLI/API) | 是 |\n| 点击邮件验证链接 | 否 | 否 |\n| 输入带 3DS 的信用卡 | 否 | 否 |\n| 在浏览器中完成 OAuth | 否 | 否 |\n| 视觉验证 UI 是否正确 | 否 | 否 |\n| 测试交互式用户流程 | 否 | 否 |\n\n## 反模式\n\n### ❌ 错误：让用户启动开发服务器\n```xml\n\n 仪表板组件\n \n 1. 运行: npm run dev\n 2. 访问: http://localhost:3000/dashboard\n 3. 检查布局是否正确\n \n\n```\n**为什么错误：** Claude 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。\n\n### ✅ 正确：Claude 启动服务器，用户访问\n```xml\n\n 启动开发服务器\n 在后台运行 `npm run dev`\n curl localhost:3000 返回 200\n\n\n\n http://localhost:3000/dashboard 的仪表板（服务器运行中）\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 布局匹配设计\n 2. 无控制台错误\n \n\n```\n\n### ❌ 错误：让用户部署 / ✅ 正确：Claude 自动化\n```xml\n\n\n 部署到 Vercel\n 访问 vercel.com/new → 导入仓库 → 点击部署 → 复制 URL\n\n\n\n\n 部署到 Vercel\n 运行 `vercel --yes`。捕获 URL。\n vercel ls 显示部署，curl 返回 200\n\n\n\n 已部署到 {url}\n 访问 {url}，检查首页加载\n 输入 \"approved\"\n\n```\n\n## 摘要\n\n检查点规范化人工介入点用于验证和决策，而非手动工作。\n\n**黄金法则：** 如果 Claude 能自动化它，Claude 就必须自动化它。\n\n**检查点优先级：**\n1. **checkpoint:human-verify**（90%）- Claude 自动化一切，人工确认视觉/功能正确性\n2. **checkpoint:decision**（9%）- 人工做出架构/技术选择\n3. **checkpoint:human-action**（1%）- 真正无法避免的、没有 API/CLI 的手动步骤\n\n**何时不用检查点：**\n- Claude 可以编程验证的事情（测试、构建）\n- 文件操作（Claude 可以读取文件）\n- 代码正确性（测试和静态分析）\n- 任何可通过 CLI/API 自动化的内容","docs/zh-CN/references/continuation-format.md":"# 续接格式\n\n完成命令或工作流后展示下一步的标准格式。\n\n## 核心结构\n\n```\n---\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `{备选项 1}` — 描述\n- `{备选项 2}` — 描述\n\n---\n```\n\n## 格式规则\n\n1. **始终展示它是什么** — 名称 + 描述，绝不仅仅是一个命令路径\n2. **从源文件拉取上下文** — ROADMAP.md 用于阶段，PLAN.md `` 用于计划\n3. **命令用内联代码** — 反引号，易于复制粘贴，渲染为可点击链接\n4. **`/clear` 说明** — 始终包含，保持简洁但解释原因\n5. **用\"也可选\"而非\"其他选项\"** — 听起来更像应用\n6. **视觉分隔符** — 上下用 `---` 使其突出\n\n## 变体\n\n### 执行下一个计划\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- 执行前审查计划\n- `/gsd-discuss-phase --assumptions 2` — 检查假设\n\n---\n```\n\n### 执行阶段中最后一个计划\n\n添加注释说明这是最后一个计划以及接下来是什么：\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n阶段 2 的最后一个计划\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**完成后：**\n- 阶段 2 → 阶段 3 过渡\n- 下一步：**阶段 3: 核心功能** — 用户仪表板和设置\n\n---\n```\n\n### 规划阶段\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程\n\n`/gsd-plan-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 2` — 先收集上下文\n- `/gsd-plan-phase --research-phase 2` — 调查未知项\n- 审查路线图\n\n---\n```\n\n### 阶段完成，准备下一步\n\n在下一步操作前显示完成状态：\n\n```\n---\n\n## ✓ 阶段 2 完成\n\n3/3 计划已执行\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n`/gsd-plan-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 3` — 先收集上下文\n- `/gsd-plan-phase --research-phase 3` — 调查未知项\n- 回顾阶段 2 构建的内容\n\n---\n```\n\n### 多个同等选项\n\n当没有明确的主要操作时：\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n**直接规划：** `/gsd-plan-phase 3`\n\n**先讨论上下文：** `/gsd-discuss-phase 3`\n\n**研究未知项：** `/gsd-plan-phase --research-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n### 里程碑完成\n\n```\n---\n\n## 🎉 里程碑 v1.0 完成\n\n全部 4 个阶段已发布\n\n## ▶ 下一步\n\n**开始 v1.1** — 提问 → 研究 → 需求 → 路线图\n\n`/gsd-new-milestone`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n## 拉取上下文\n\n### 用于阶段（从 ROADMAP.md）：\n\n```markdown\n### 阶段 2: 认证\n**目标**: 带刷新令牌的 JWT 登录流程\n```\n\n提取：`**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程`\n\n### 用于计划（从 ROADMAP.md）：\n\n```markdown\n计划:\n- [ ] 02-03: 添加刷新令牌轮换\n```\n\n或从 PLAN.md ``：\n\n```xml\n\n添加带滑动过期窗口的刷新令牌轮换。\n\n目的: 在不影响安全性的前提下延长会话生命周期。\n\n```\n\n提取：`**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh`\n\n## 反模式\n\n### 不要：仅命令（无上下文）\n\n```\n## 继续\n\n运行 `/clear`，然后粘贴：\n/gsd-execute-phase 2\n```\n\n用户不知道 02-03 是关于什么的。\n\n### 不要：缺少 /clear 说明\n\n```\n`/gsd-plan-phase 3`\n\n先运行 /clear。\n```\n\n没有解释原因。用户可能跳过。\n\n### 不要：\"其他选项\" 措辞\n\n```\n其他选项：\n- 审查路线图\n```\n\n听起来像是事后补充。用\"也可选：\"替代。\n\n### 不要：用围栏代码块展示命令\n\n```\n```\n/gsd-plan-phase 3\n```\n```\n\n模板内的围栏代码块会造成嵌套歧义。用内联反引号替代。","docs/zh-CN/references/decimal-phase-calculation.md":"# 小数阶段计算\n\n为紧急插入计算下一个小数阶段编号。\n\n## 使用 gsd-sdk query\n\n```bash\n# 获取阶段 6 之后的下一个小数阶段\ngsd-sdk query phase.next-decimal 6\n```\n\n输出：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.1\",\n \"existing\": []\n}\n```\n\n已有小数时：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.3\",\n \"existing\": [\"06.1\", \"06.2\"]\n}\n```\n\n## 提取值\n\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick next)\nBASE_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick base_phase)\n```\n\n或使用 --raw 标志：\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --raw)\n# 返回: 06.1\n```\n\n## 示例\n\n| 已有阶段 | 下一个阶段 |\n|----------|------------|\n| 仅 06 | 06.1 |\n| 06, 06.1 | 06.2 |\n| 06, 06.1, 06.2 | 06.3 |\n| 06, 06.1, 06.3（有空缺）| 06.4 |\n\n## 目录命名\n\n小数阶段目录使用完整的小数编号：\n\n```bash\nSLUG=$(gsd-sdk query generate-slug \"$DESCRIPTION\" --raw)\nPHASE_DIR=\".planning/phases/${DECIMAL_PHASE}-${SLUG}\"\nmkdir -p \"$PHASE_DIR\"\n```\n\n示例：`.planning/phases/06.1-fix-critical-auth-bug/`\n","docs/zh-CN/references/git-integration.md":"\nGSD 框架的 Git 集成。\n\n\n\n\n**提交结果，而非过程。**\n\ngit 日志应该读起来像是发布内容的变更日志，而不是规划活动的日记。\n\n\n\n\n| 事件 | 提交? | 原因 |\n| ----------------------- | ------- | ------------------------------------------------ |\n| BRIEF + ROADMAP 创建 | 是 | 项目初始化 |\n| PLAN.md 创建 | 否 | 中间产物 - 与计划完成一起提交 |\n| RESEARCH.md 创建 | 否 | 中间产物 |\n| DISCOVERY.md 创建 | 否 | 中间产物 |\n| **任务完成** | 是 | 原子工作单元（每个任务 1 个提交） |\n| **计划完成** | 是 | 元数据提交（SUMMARY + STATE + ROADMAP） |\n| 交接创建 | 是 | WIP 状态保留 |\n\n\n\n\n\n```bash\n[ -d .git ] && echo \"GIT_EXISTS\" || echo \"NO_GIT\"\n```\n\n如果 NO_GIT：静默运行 `git init`。GSD 项目总是有自己的仓库。\n\n\n\n\n\n## 项目初始化（brief + roadmap 一起）\n\n```\ndocs: initialize [project-name] ([N] phases)\n\n[PROJECT.md 中的一句话描述]\n\nPhases:\n1. [phase-name]: [goal]\n2. [phase-name]: [goal]\n3. [phase-name]: [goal]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs: initialize [project-name] ([N] phases)\" --files .planning/\n```\n\n\n\n\n## 任务完成（计划执行期间）\n\n每个任务在完成后立即获得自己的提交。\n\n```\n{type}({phase}-{plan}): {task-name}\n\n- [关键变更 1]\n- [关键变更 2]\n- [关键变更 3]\n```\n\n**提交类型：**\n- `feat` - 新功能/功能\n- `fix` - Bug 修复\n- `test` - 仅测试（TDD RED 阶段）\n- `refactor` - 代码清理（TDD REFACTOR 阶段）\n- `perf` - 性能改进\n- `chore` - 依赖、配置、工具\n\n**示例：**\n\n```bash\n# 标准任务\ngit add src/api/auth.ts src/types/user.ts\ngit commit -m \"feat(08-02): create user registration endpoint\n\n- POST /auth/register validates email and password\n- Checks for duplicate users\n- Returns JWT token on success\n\"\n\n# TDD 任务 - RED 阶段\ngit add src/__tests__/jwt.test.ts\ngit commit -m \"test(07-02): add failing test for JWT generation\n\n- Tests token contains user ID claim\n- Tests token expires in 1 hour\n- Tests signature verification\n\"\n\n# TDD 任务 - GREEN 阶段\ngit add src/utils/jwt.ts\ngit commit -m \"feat(07-02): implement JWT generation\n\n- Uses jose library for signing\n- Includes user ID and expiry claims\n- Signs with HS256 algorithm\n\"\n```\n\n\n\n\n## 计划完成（所有任务完成后）\n\n所有任务提交后，最后一个元数据提交捕获计划完成。\n\n```\ndocs({phase}-{plan}): complete [plan-name] plan\n\nTasks completed: [N]/[N]\n- [Task 1 name]\n- [Task 2 name]\n- [Task 3 name]\n\nSUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs({phase}-{plan}): complete [plan-name] plan\" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md\n```\n\n**注意：** 代码文件不包含 - 已按任务提交。\n\n\n\n\n## 交接（WIP）\n\n```\nwip: [phase-name] paused at task [X]/[Y]\n\nCurrent: [task name]\n[如果阻塞:] Blocked: [reason]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"wip: [phase-name] paused at task [X]/[Y]\" --files .planning/\n```\n\n\n\n\n\n\n**旧方法（每个计划提交）：**\n```\na7f2d1 feat(checkout): Stripe payments with webhook verification\n3e9c4b feat(products): catalog with search, filters, and pagination\n8a1b2c feat(auth): JWT with refresh rotation using jose\n5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold\n2f4a8d docs: initialize ecommerce-app (5 phases)\n```\n\n**新方法（每个任务提交）：**\n```\n# Phase 04 - Checkout\n1a2b3c docs(04-01): complete checkout flow plan\n4d5e6f feat(04-01): add webhook signature verification\n7g8h9i feat(04-01): implement payment session creation\n0j1k2l feat(04-01): create checkout page component\n\n# Phase 03 - Products\n3m4n5o docs(03-02): complete product listing plan\n6p7q8r feat(03-02): add pagination controls\n9s0t1u feat(03-02): implement search and filters\n2v3w4x feat(03-01): create product catalog schema\n\n# Phase 02 - Auth\n5y6z7a docs(02-02): complete token refresh plan\n8b9c0d feat(02-02): implement refresh token rotation\n1e2f3g test(02-02): add failing test for token refresh\n4h5i6j docs(02-01): complete JWT setup plan\n7k8l9m feat(02-01): add JWT generation and validation\n0n1o2p chore(02-01): install jose library\n\n# Phase 01 - Foundation\n3q4r5s docs(01-01): complete scaffold plan\n6t7u8v feat(01-01): configure Tailwind and globals\n9w0x1y feat(01-01): set up Prisma with database\n2z3a4b feat(01-01): create Next.js 15 project\n\n# Initialization\n5c6d7e docs: initialize ecommerce-app (5 phases)\n```\n\n每个计划产生 2-4 个提交（任务 + 元数据）。清晰、细粒度、可 bisect。\n\n\n\n\n\n**仍不要提交（中间产物）：**\n- PLAN.md 创建（与计划完成一起提交）\n- RESEARCH.md（中间产物）\n- DISCOVERY.md（中间产物）\n- 小的规划调整\n- \"Fixed typo in roadmap\"\n\n**要提交（结果）：**\n- 每个任务完成（feat/fix/test/refactor）\n- 计划完成元数据（docs）\n- 项目初始化（docs）\n\n**关键原则：** 提交可工作的代码和已发布的结果，而非规划过程。\n\n\n\n\n\n## 为什么使用每任务提交？\n\n**AI 上下文工程：**\n- Git 历史成为未来 Claude 会话的主要上下文源\n- `git log --grep=\"{phase}-{plan}\"` 显示计划的所有工作\n- `git diff ^..` 显示每个任务的确切变更\n- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作\n\n**失败恢复：**\n- 任务 1 已提交 ✅，任务 2 失败 ❌\n- 下次会话中的 Claude：看到任务 1 完成，可以重试任务 2\n- 可以 `git reset --hard` 到最后一个成功的任务\n\n**调试：**\n- `git bisect` 找到确切的失败任务，而不仅仅是失败计划\n- `git blame` 将行追溯到特定任务上下文\n- 每个提交独立可回滚\n\n**可观察性：**\n- 独立开发者 + Claude 工作流受益于细粒度归因\n- 原子提交是 git 最佳实践\n- 当消费者是 Claude 而非人类时，\"提交噪音\"无关紧要\n\n","docs/zh-CN/references/git-planning-commit.md":"# Git 规划提交\n\n通过 `gsd-sdk query commit` 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态（与旧版 `gsd-tools.cjs commit` 行为相同）。\n\n## 通过 CLI 提交\n\n先传提交说明，然后用 `--files` 显式传入文件路径。`commit` 与 `commit-to-subrepo` 都应使用 `--files` 来声明要提交的路径。\n\n对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查：\n\n```bash\ngsd-sdk query commit \"docs({scope}): {description}\" --files .planning/STATE.md .planning/ROADMAP.md\n```\n\n如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。\n\n## 修改上次提交\n\n将 `.planning/` 文件变更合并到上次提交：\n\n```bash\ngsd-sdk query commit \"\" --files .planning/codebase/*.md --amend\n```\n\n## 提交消息模式\n\n| 命令 | 范围 | 示例 |\n|------|------|------|\n| plan-phase | phase | `docs(phase-03): create authentication plans` |\n| execute-phase | phase | `docs(phase-03): complete authentication phase` |\n| new-milestone | milestone | `docs: start milestone v1.1` |\n| remove-phase | chore | `chore: remove phase 17 (dashboard)` |\n| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |\n| add-phase | phase | `docs: add phase 07 (settings page)` |\n\n## 何时跳过\n\n- config 中 `commit_docs: false`\n- `.planning/` 被 gitignore\n- 无变更可提交（用 `git status --porcelain .planning/` 检查）\n","docs/zh-CN/references/model-profile-resolution.md":"# 模型配置解析\n\n在编排开始时解析一次模型配置，然后在所有 Task 生成时使用。\n\n## 解析模式\n\n```bash\nMODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '\"model_profile\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | grep -o '\"[^\"]*\"$' | tr -d '\"' || echo \"balanced\")\n```\n\n默认值：未设置或缺少 config 时为 `balanced`。\n\n## 查找表\n\n@~/.claude/get-shit-done/references/model-profiles.md\n\n在表中查找已解析配置对应的代理。将 model 参数传递给 Task 调用：\n\n```\nTask(\n prompt=\"...\",\n subagent_type=\"gsd-planner\",\n model=\"{resolved_model}\" # \"inherit\"、\"sonnet\" 或 \"haiku\"\n)\n```\n\n**注意：** Opus 级代理解析为 `\"inherit\"`（而非 `\"opus\"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。\n\n## 使用方法\n\n1. 在编排开始时解析一次\n2. 存储 profile 值\n3. 生成时在表中查找每个代理的模型\n4. 将 model 参数传递给每个 Task 调用（值：`\"inherit\"`、`\"sonnet\"`、`\"haiku\"`）","docs/zh-CN/references/model-profiles.md":"# 模型配置\n\n模型配置控制每个 GSD 代理使用哪个 Claude 模型。这允许平衡质量和 token 消耗。\n\n## 配置定义\n\n| 代理 | `quality` | `balanced` | `budget` |\n|-------|-----------|------------|----------|\n| gsd-planner | opus | opus | sonnet |\n| gsd-roadmapper | opus | sonnet | sonnet |\n| gsd-executor | opus | sonnet | sonnet |\n| gsd-phase-researcher | opus | sonnet | haiku |\n| gsd-project-researcher | opus | sonnet | haiku |\n| gsd-research-synthesizer | sonnet | sonnet | haiku |\n| gsd-debugger | opus | sonnet | sonnet |\n| gsd-codebase-mapper | sonnet | haiku | haiku |\n| gsd-verifier | sonnet | sonnet | haiku |\n| gsd-plan-checker | sonnet | sonnet | haiku |\n| gsd-integration-checker | sonnet | sonnet | haiku |\n| gsd-nyquist-auditor | sonnet | sonnet | haiku |\n\n## 配置理念\n\n**quality** - 最大推理能力\n- 所有决策代理使用 Opus\n- 只读验证使用 Sonnet\n- 适用场景：有配额可用、关键架构工作\n\n**balanced**（默认）- 智能分配\n- 仅规划（架构决策发生的地方）使用 Opus\n- 执行和研究使用 Sonnet（遵循明确指令）\n- 验证使用 Sonnet（需要推理，不仅仅是模式匹配）\n- 适用场景：正常开发、质量与成本的良好平衡\n\n**budget** - 最小化 Opus 使用\n- 编写代码的使用 Sonnet\n- 研究和验证使用 Haiku\n- 适用场景：节省配额、大量工作、不太关键的阶段\n\n## 解析逻辑\n\n编排器在生成代理前解析模型：\n\n```\n1. 读取 .planning/config.json\n2. 检查 model_overrides 是否有代理特定覆盖\n3. 如果没有覆盖，在配置表中查找代理\n4. 将 model 参数传递给 Task 调用\n```\n\n## 单代理覆盖\n\n覆盖特定代理而不更改整个配置：\n\n```json\n{\n \"model_profile\": \"balanced\",\n \"model_overrides\": {\n \"gsd-executor\": \"opus\",\n \"gsd-planner\": \"haiku\"\n }\n}\n```\n\n覆盖优先于配置。有效值：`opus`、`sonnet`、`haiku`。\n\n## 切换配置\n\n在 `.planning/config.json` 中设置 `model_profile` 键以更改配置文件。\n\n项目默认值：在 `.planning/config.json` 中设置：\n```json\n{\n \"model_profile\": \"balanced\"\n}\n```\n\n## 设计理由\n\n**为什么 gsd-planner 使用 Opus？**\n规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。\n\n**为什么 gsd-executor 使用 Sonnet？**\n执行者遵循明确的 PLAN.md 指令。计划已包含推理；执行只是实现。\n\n**为什么 balanced 中验证器使用 Sonnet（而非 Haiku）？**\n验证需要目标回溯推理 —— 检查代码是否**交付**了阶段承诺的内容，而不仅仅是模式匹配。Sonnet 处理得很好；Haiku 可能会遗漏细微的差距。\n\n**为什么 gsd-codebase-mapper 使用 Haiku？**\n只读探索和模式提取。不需要推理，只需从文件内容输出结构化结果。\n\n**为什么用 `inherit` 而不是直接传递 `opus`？**\nClaude Code 的 `\"opus\"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。GSD 为 opus 级代理返回 `\"inherit\"`，使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。","docs/zh-CN/references/phase-argument-parsing.md":"# 阶段参数解析\n\n为操作阶段的命令解析和规范化阶段参数。\n\n## 提取\n\n从 `$ARGUMENTS` 中：\n- 提取阶段编号（第一个数字参数）\n- 提取标志（以 `--` 为前缀）\n- 剩余文本为描述（用于 insert/add 命令）\n\n## 使用 gsd-tools\n\n`find-phase` 命令一步完成规范化和验证：\n\n```bash\nPHASE_INFO=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\")\n```\n\n返回 JSON 包含：\n- `found`: true/false\n- `directory`: 阶段目录的完整路径\n- `phase_number`: 规范化的编号（如 \"06\"、\"06.1\"）\n- `phase_name`: 名称部分（如 \"foundation\"）\n- `plans`: PLAN.md 文件数组\n- `summaries`: SUMMARY.md 文件数组\n\n## 手动规范化（遗留）\n\n将整数阶段补零到 2 位。保留小数后缀。\n\n```bash\n# 规范化阶段编号\nif [[ \"$PHASE\" =~ ^[0-9]+$ ]]; then\n # 整数: 8 → 08\n PHASE=$(printf \"%02d\" \"$PHASE\")\nelif [[ \"$PHASE\" =~ ^([0-9]+)\\.([0-9]+)$ ]]; then\n # 小数: 2.1 → 02.1\n PHASE=$(printf \"%02d.%s\" \"${BASH_REMATCH[1]}\" \"${BASH_REMATCH[2]}\")\nfi\n```\n\n## 验证\n\n使用 `roadmap get-phase` 验证阶段存在：\n\n```bash\nPHASE_CHECK=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" roadmap get-phase \"${PHASE}\")\nif [ \"$(printf '%s\\n' \"$PHASE_CHECK\" | jq -r '.found')\" = \"false\" ]; then\n echo \"ERROR: Phase ${PHASE} not found in roadmap\"\n exit 1\nfi\n```\n\n## 目录查找\n\n使用 `find-phase` 进行目录查找：\n\n```bash\nPHASE_DIR=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\" --raw)\n```","docs/zh-CN/references/planning-config.md":"\n\n`.planning/` 目录行为的配置选项。\n\n\n```json\n\"planning\": {\n \"commit_docs\": true,\n \"search_gitignored\": false\n},\n\"git\": {\n \"branching_strategy\": \"none\",\n \"phase_branch_template\": \"gsd/phase-{phase}-{slug}\",\n \"milestone_branch_template\": \"gsd/{milestone}-{slug}\"\n}\n```\n\n| 选项 | 默认值 | 描述 |\n|--------|---------|-------------|\n| `commit_docs` | `true` | 是否将规划工件提交到 git |\n| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` |\n| `git.branching_strategy` | `\"none\"` | Git 分支策略：`\"none\"`、`\"phase\"` 或 `\"milestone\"` |\n| `git.phase_branch_template` | `\"gsd/phase-{phase}-{slug}\"` | 阶段策略的分支模板 |\n| `git.milestone_branch_template` | `\"gsd/{milestone}-{slug}\"` | 里程碑策略的分支模板 |\n\n\n\n\n**当 `commit_docs: true`（默认）：**\n- 规划文件正常提交\n- SUMMARY.md、STATE.md、ROADMAP.md 在 git 中跟踪\n- 规划决策的完整历史保留\n\n**当 `commit_docs: false`：**\n- 跳过 `.planning/` 文件的所有 `git add`/`git commit`\n- 用户必须将 `.planning/` 添加到 `.gitignore`\n- 适用于：OSS 贡献、客户项目、保持规划私有\n\n**使用 `gsd-sdk query`（推荐）：**\n\n```bash\n# 提交时自动检查 commit_docs + gitignore：\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n\n# 通过 state load 加载配置（返回 JSON）：\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 在 JSON 输出中可用\n\n# 或使用包含 commit_docs 的 init 命令：\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 包含在所有 init 命令输出中\n```\n\n**自动检测：** 如果 `.planning/` 被 gitignore，无论 config.json 如何，`commit_docs` 自动为 `false`。这防止用户在 `.gitignore` 中有 `.planning/` 时出现 git 错误。\n\n**通过 CLI 提交（自动处理检查）：**\n\n```bash\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n```\n\nCLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。\n\n\n\n\n\n**当 `search_gitignored: false`（默认）：**\n- 标准 rg 行为（尊重 .gitignore）\n- 直接路径搜索有效：`rg \"pattern\" .planning/` 找到文件\n- 广泛搜索跳过 gitignored：`rg \"pattern\"` 跳过 `.planning/`\n\n**当 `search_gitignored: true`:**\n- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore`\n- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要\n\n**注意：** 大多数 GSD 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都有效。\n\n\n\n\n\n使用未提交模式：\n\n1. **设置配置：**\n ```json\n \"planning\": {\n \"commit_docs\": false,\n \"search_gitignored\": true\n }\n ```\n\n2. **添加到 .gitignore：**\n ```\n .planning/\n ```\n\n3. **已存在的跟踪文件：** 如果 `.planning/` 之前被跟踪：\n ```bash\n git rm -r --cached .planning/\n git commit -m \"chore: stop tracking planning docs\"\n ```\n\n4. **分支合并：** 当使用 `branching_strategy: phase` 或 `milestone` 时，`complete-milestone` 工作流在 `commit_docs: false` 时自动从暂存区移除 `.planning/` 文件，然后才进行合并提交。\n\n\n\n\n\n**分支策略：**\n\n| 策略 | 创建分支时机 | 分支范围 | 合并点 |\n|----------|---------------------|--------------|-------------|\n| `none` | 从不 | N/A | N/A |\n| `phase` | `execute-phase` 开始时 | 单个阶段 | 阶段后用户手动合并 |\n| `milestone` | 里程碑第一个 `execute-phase` | 整个里程碑 | `complete-milestone` 时 |\n\n**当 `git.branching_strategy: \"none\"`（默认）：**\n- 所有工作提交到当前分支\n- 标准 GSD 行为\n\n**当 `git.branching_strategy: \"phase\"`：**\n- `execute-phase` 在执行前创建/切换到分支\n- 分支名来自 `phase_branch_template`（如 `gsd/phase-03-authentication`）\n- 所有计划提交到该分支\n- 阶段完成后用户手动合并分支\n- `complete-milestone` 提供合并所有阶段分支的选项\n\n**当 `git.branching_strategy: \"milestone\"`：**\n- 里程碑的第一个 `execute-phase` 创建里程碑分支\n- 分支名来自 `milestone_branch_template`（如 `gsd/v1.0-mvp`）\n- 里程碑中所有阶段提交到同一分支\n- `complete-milestone` 提供将里程碑分支合并到 main 的选项\n\n**模板变量：**\n\n| 变量 | 可用于 | 描述 |\n|----------|--------------|-------------|\n| `{phase}` | phase_branch_template | 零填充阶段号（如 \"03\"） |\n| `{slug}` | 两者 | 小写、连字符名称 |\n| `{milestone}` | milestone_branch_template | 里程碑版本（如 \"v1.0\"） |\n\n**检查配置：**\n\n使用 `init execute-phase` 返回所有配置为 JSON：\n```bash\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n或使用 `state load` 获取配置值：\n```bash\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n**分支创建：**\n\n```bash\n# 阶段策略\nif [ \"$BRANCHING_STRATEGY\" = \"phase\" ]; then\n PHASE_SLUG=$(echo \"$PHASE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$PHASE_BRANCH_TEMPLATE\" | sed \"s/{phase}/$PADDED_PHASE/g\" | sed \"s/{slug}/$PHASE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n\n# 里程碑策略\nif [ \"$BRANCHING_STRATEGY\" = \"milestone\" ]; then\n MILESTONE_SLUG=$(echo \"$MILESTONE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$MILESTONE_BRANCH_TEMPLATE\" | sed \"s/{milestone}/$MILESTONE_VERSION/g\" | sed \"s/{slug}/$MILESTONE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n```\n\n**complete-milestone 时的合并选项：**\n\n| 选项 | Git 命令 | 结果 |\n|--------|-------------|--------|\n| Squash 合并（推荐） | `git merge --squash` | 每个分支单个干净提交 |\n| 带历史合并 | `git merge --no-ff` | 保留所有单独提交 |\n| 不合并直接删除 | `git branch -D` | 丢弃分支工作 |\n| 保留分支 | （无） | 后续手动处理 |\n\n推荐 Squash 合并 —— 保持 main 分支历史干净，同时在分支中保留完整开发历史（直到删除）。\n\n**使用场景：**\n\n| 策略 | 最适合 |\n|----------|----------|\n| `none` | 独立开发、简单项目 |\n| `phase` | 每阶段代码审查、细粒度回滚、团队协作 |\n| `milestone` | 发布分支、预发布环境、每个版本一个 PR |\n\n\n\n","docs/zh-CN/references/questioning.md":"# 提问指南\n\n项目初始化是梦想提取，而非需求收集。你在帮助用户发现和表达他们想构建的内容。这不是合同谈判 —— 是协作思考。\n\n## 理念\n\n**你是思考伙伴，不是面试官。**\n\n用户通常有一个模糊的想法。你的工作是帮助他们将其锐化。问一些让他们思考\"哦，我没想到那个\"或\"是的，这正是我的意思\"的问题。\n\n不要审问。协作。不要照本宣科。顺藤摸瓜。\n\n## 目标\n\n到提问结束时，你需要足够的清晰度来编写下游阶段可执行的 PROJECT.md：\n\n- **研究** 需要：研究什么领域、用户已知什么、存在哪些未知\n- **需求** 需要：足够清晰的愿景来界定 v1 功能\n- **路线图** 需要：足够清晰的愿景来分解为阶段、\"完成\"是什么样子\n- **plan-phase** 需要：可分解为任务的具体需求、实现选择的上下文\n- **execute-phase** 需要：可验证的成功标准、需求背后的\"为什么\"\n\n模糊的 PROJECT.md 会让每个下游阶段都在猜测。成本会叠加。\n\n## 如何提问\n\n**开放开始。** 让他们倾倒心理模型。不要用结构打断。\n\n**跟随能量。** 无论他们强调什么，深入那个。什么让他们兴奋？什么问题引发了这一切？\n\n**挑战模糊。** 绝不接受模糊回答。\"好\"意味着什么？\"用户\"指谁？\"简单\"是怎么简单？\n\n**让抽象具体。**\"带我走一遍使用这个。\"\"那实际看起来是什么样？\"\n\n**澄清歧义。**\"你说 Z 时，是指 A 还是 B？\"\"你提到了 X —— 跟我多说说。\"\n\n**知道何时停止。** 当你理解他们想要什么、为什么想要、给谁用、完成是什么样 —— 提议继续。\n\n## 问题类型\n\n以此作为灵感，不是清单。选择与话题相关的。\n\n**动机 —— 为什么存在：**\n- \"什么引发了这一切？\"\n- \"你今天在做什么会被这个替代？\"\n- \"如果这个存在，你会做什么？\"\n\n**具体性 —— 它实际是什么：**\n- \"带我走一遍使用这个\"\n- \"你说 X —— 那实际看起来是什么样？\"\n- \"给我一个例子\"\n\n**澄清 —— 他们什么意思：**\n- \"你说 Z 时，是指 A 还是 B？\"\n- \"你提到了 X —— 跟我多说说那个\"\n\n**成功 —— 你怎么知道它在工作：**\n- \"你怎么知道这个在工作？\"\n- \"完成是什么样子？\"\n\n## 使用 AskUserQuestion\n\n用 AskUserQuestion 帮助用户思考，通过呈现具体的选项供他们反应。\n\n**好选项：**\n- 他们可能意思的解读\n- 确认或否认的具体例子\n- 揭示优先级的具体选择\n\n**坏选项：**\n- 泛泛的类别（\"技术\"、\"业务\"、\"其他\"）\n- 预设答案的引导性选项\n- 选项太多（2-4 个理想）\n- 超过 12 个字符的标题（硬限制 —— 验证会拒绝）\n\n**示例 —— 模糊回答：**\n用户说\"它应该快\"\n\n- header: \"快\"\n- question: \"快是指？\"\n- options: [\"亚秒响应\", \"处理大数据集\", \"快速构建\", \"让我解释\"]\n\n**示例 —— 跟随话题：**\n用户提到\"对当前工具感到沮丧\"\n\n- header: \"沮丧\"\n- question: \"具体什么让你沮丧？\"\n- options: [\"点击太多\", \"缺少功能\", \"不可靠\", \"让我解释\"]\n\n**给用户的提示 —— 修改选项：**\n想要稍微修改某个选项版本的用户可以选择\"Other\"并通过编号引用选项：`#1 但仅用于指关节` 或 `#2 禁用分页`。这避免重新输入完整选项文本。\n\n## 自由格式规则\n\n**当用户想自由解释时，停止使用 AskUserQuestion。**\n\n如果用户选择\"Other\"且他们的回应表明他们想用自己的话描述（如\"让我描述一下\"、\"我来解释\"、\"别的\"、或任何非选择/修改现有选项的开放式回复），你必须：\n\n1. **用纯文本问你的追问** — 不通过 AskUserQuestion\n2. **等待他们在正常提示符下输入**\n3. **仅在处理他们的自由格式回应后恢复 AskUserQuestion**\n\n同样适用于如果你包含一个表明自由格式的选项（如\"让我解释\"或\"详细描述\"）且用户选择了它。\n\n**错误：** 用户说\"让我描述一下\" → AskUserQuestion(\"什么功能？\", [\"功能 A\", \"功能 B\", \"详细描述\"])\n**正确：** 用户说\"让我描述一下\" → \"请讲 —— 你在想什么？\"\n\n## 上下文清单\n\n以此作为**背景清单**，而非对话结构。进行时在脑中检查这些。如果还有缺口，自然地穿插问题。\n\n- [ ] 他们在构建什么（足够具体可以向陌生人解释）\n- [ ] 为什么它需要存在（驱动它的问题或渴望）\n- [ ] 给谁用的（即使只是他们自己）\n- [ ] \"完成\"是什么样子（可观察的结果）\n\n四件事。如果他们主动提供更多，捕获它。\n\n## 决策门控\n\n当你能写出清晰的 PROJECT.md 时，提议继续：\n\n- header: \"准备好了？\"\n- question: \"我想我理解你想要什么了。准备创建 PROJECT.md 吗？\"\n- options:\n - \"创建 PROJECT.md\" — 让我们继续\n - \"继续探索\" — 我想分享更多 / 再问我\n\n如果\"继续探索\" —— 问他们想添加什么或识别缺口并自然探查。\n\n循环直到选择\"创建 PROJECT.md\"。\n\n## 反模式\n\n- **走清单** — 不管他们说什么都按领域走\n- **套话问题** — \"你的核心价值是什么？\"\"什么超出范围？\"不管上下文\n- **企业腔** — \"你的成功标准是什么？\"\"你的利益相关者是谁？\"\n- **审问** — 不基于回答构建就连续发问\n- **急于求成** — 最小化问题以开始\"实际工作\"\n- **浅层接受** — 不探查就接受模糊回答\n- **过早约束** — 还不理解想法就问技术栈\n- **用户技能** — 绝不问用户的技术经验。Claude 来构建。","docs/zh-CN/references/tdd.md":"\nTDD 关乎设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现前思考行为，从而产生更清晰的接口和更可测试的代码。\n\n**原则：** 如果在编写 `fn` 之前能用 `expect(fn(input)).toBe(output)` 描述行为，TDD 会改善结果。\n\n**关键洞察：** TDD 工作本质上比标准任务更重 —— 它需要 2-3 个执行周期（RED → GREEN → REFACTOR），每个周期都涉及文件读取、测试运行和可能的调试。TDD 功能获得专门的计划，以确保整个周期内有完整的上下文可用。\n\n\n\n## 何时 TDD 提高质量\n\n**TDD 候选（创建 TDD 计划）：**\n- 有明确输入/输出的业务逻辑\n- 有请求/响应契约的 API 端点\n- 数据转换、解析、格式化\n- 验证规则和约束\n- 有可测试行为的算法\n- 状态机和工作流\n- 有清晰规格的工具函数\n\n**跳过 TDD（使用带 `type=\"auto\"` 任务的标准计划）：**\n- UI 布局、样式、视觉组件\n- 配置更改\n- 连接现有组件的胶水代码\n- 一次性脚本和迁移\n- 无业务逻辑的简单 CRUD\n- 探索性原型\n\n**启发式：** 能在编写 `fn` 之前写 `expect(fn(input)).toBe(output)` 吗？\n→ 能：创建 TDD 计划\n→ 不能：使用标准计划，事后添加测试（如需要）\n\n\n\n## TDD 计划结构\n\n每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 循环实现**一个功能**。\n\n```markdown\n---\nphase: XX-name\nplan: NN\ntype: tdd\n---\n\n\n[什么功能以及为什么]\nPurpose: [该功能 TDD 的设计收益]\nOutput: [可工作的、已测试的功能]\n\n\n\n@.planning/PROJECT.md\n@.planning/ROADMAP.md\n@relevant/source/files.ts\n\n\n\n [功能名称]\n [源文件, 测试文件]\n \n [可测试术语描述的预期行为]\n Cases: 输入 → 预期输出\n \n [测试通过后如何实现]\n\n\n\n[证明功能有效的测试命令]\n\n\n\n- 失败测试已编写并提交\n- 实现通过测试\n- 重构完成（如需要）\n- 所有 2-3 个提交都存在\n\n\n\n完成后，创建包含以下内容的 SUMMARY.md：\n- RED: 编写了什么测试，为什么失败\n- GREEN: 什么实现让它通过\n- REFACTOR: 做了什么清理（如有）\n- Commits: 生成的提交列表\n\n```\n\n**每个 TDD 计划一个功能。** 如果功能足够简单可以批量处理，那就足够简单可以跳过 TDD —— 使用标准计划，事后添加测试。\n\n\n\n## 红-绿-重构循环\n\n**RED - 编写失败测试：**\n1. 按项目约定创建测试文件\n2. 编写描述预期行为的测试（来自 `` 元素）\n3. 运行测试 - 必须**失败**\n4. 如果测试通过：功能已存在或测试有误。调查。\n5. 提交：`test({phase}-{plan}): add failing test for [feature]`\n\n**GREEN - 实现使其通过：**\n1. 编写使测试通过的最小代码\n2. 不耍小聪明，不优化 - 只让它工作\n3. 运行测试 - 必须**通过**\n4. 提交：`feat({phase}-{plan}): implement [feature]`\n\n**REFACTOR（如需要）：**\n1. 如果存在明显的改进，清理实现\n2. 运行测试 - 必须**仍然通过**\n3. 仅在做出更改时提交：`refactor({phase}-{plan}): clean up [feature]`\n\n**结果：** 每个 TDD 计划产生 2-3 个原子提交。\n\n\n\n## 好测试 vs 坏测试\n\n**测试行为，而非实现：**\n- 好：\"返回格式化的日期字符串\"\n- 坏：\"用正确参数调用 formatDate 辅助函数\"\n- 测试应该能经受重构\n\n**每个测试一个概念：**\n- 好：分别为有效输入、空输入、畸形输入编写测试\n- 坏：用多个断言检查所有边缘情况的单个测试\n\n**描述性名称：**\n- 好：\"should reject empty email\"、\"returns null for invalid ID\"\n- 坏：\"test1\"、\"handles error\"、\"works correctly\"\n\n**不包含实现细节：**\n- 好：测试公共 API、可观察行为\n- 坏：Mock 内部实现、测试私有方法、断言内部状态\n\n\n\n## 测试框架设置（如不存在）\n\n当执行 TDD 计划但没有配置测试框架时，作为 RED 阶段的一部分进行设置：\n\n**1. 检测项目类型：**\n```bash\n# JavaScript/TypeScript\nif [ -f package.json ]; then echo \"node\"; fi\n\n# Python\nif [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo \"python\"; fi\n\n# Go\nif [ -f go.mod ]; then echo \"go\"; fi\n\n# Rust\nif [ -f Cargo.toml ]; then echo \"rust\"; fi\n```\n\n**2. 安装最小框架：**\n| 项目 | 框架 | 安装 |\n|---------|-----------|---------|\n| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |\n| Node.js (Vite) | Vitest | `npm install -D vitest` |\n| Python | pytest | `pip install pytest` |\n| Go | testing | 内置 |\n| Rust | cargo test | 内置 |\n\n**3. 按需创建配置：**\n- Jest: 带 ts-jest preset 的 `jest.config.js`\n- Vitest: 带测试全局变量的 `vitest.config.ts`\n- pytest: `pytest.ini` 或 `pyproject.toml` 部分\n\n**4. 验证设置：**\n```bash\n# 运行空测试套件 - 应该以 0 个测试通过\nnpm test # Node\npytest # Python\ngo test ./... # Go\ncargo test # Rust\n```\n\n**5. 创建第一个测试文件：**\n遵循项目约定的测试位置：\n- 源文件旁边的 `*.test.ts` / `*.spec.ts`\n- `__tests__/` 目录\n- 根目录的 `tests/` 目录\n\n框架设置是第一个 TDD 计划 RED 阶段的一次性成本。\n\n\n\n## 错误处理\n\n**测试在 RED 阶段没有失败：**\n- 功能可能已存在 - 调查\n- 测试可能有误（没测试你以为的东西）\n- 前进前修复\n\n**测试在 GREEN 阶段没有通过：**\n- 调试实现\n- 不要跳到重构\n- 持续迭代直到绿色\n\n**测试在 REFACTOR 阶段失败：**\n- 撤销重构\n- 提交过早\n- 用更小的步骤重构\n\n**不相关的测试失败：**\n- 停下来调查\n- 可能表明耦合问题\n- 前进前修复\n\n\n\n## TDD 计划的提交模式\n\nTDD 计划产生 2-3 个原子提交（每个阶段一个）：\n\n```\ntest(08-02): add failing test for email validation\n\n- Tests valid email formats accepted\n- Tests invalid formats rejected\n- Tests empty input handling\n\nfeat(08-02): implement email validation\n\n- Regex pattern matches RFC 5322\n- Returns boolean for validity\n- Handles edge cases (empty, null)\n\nrefactor(08-02): extract regex to constant (optional)\n\n- Moved pattern to EMAIL_REGEX constant\n- No behavior changes\n- Tests still pass\n```\n\n**与标准计划对比：**\n- 标准计划：每个任务 1 个提交，每个计划 2-4 个提交\n- TDD 计划：单个功能 2-3 个提交\n\n两者遵循相同格式：`{type}({phase}-{plan}): {description}`\n\n**好处：**\n- 每个提交独立可回滚\n- Git bisect 在提交级别工作\n- 显示 TDD 纪律的清晰历史\n- 与整体提交策略一致\n\n\n\n## 上下文预算\n\nTDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。\n\n为什么更低：\n- RED 阶段：编写测试、运行测试、可能调试为什么没有失败\n- GREEN 阶段：实现、运行测试、可能对失败进行迭代\n- REFACTOR 阶段：修改代码、运行测试、验证无回归\n\n每个阶段涉及读取文件、运行命令、分析输出。来回往复本质上比线性任务执行更重。\n\n单一功能聚焦确保整个周期保持完整质量。\n","docs/zh-CN/references/ui-brand.md":"# UI 品牌规范\n\n面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。\n\n## 阶段横幅\n\n用于主要工作流过渡。\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► {阶段名称}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**阶段名称（大写）：**\n- `QUESTIONING`（提问）\n- `RESEARCHING`（研究）\n- `DEFINING REQUIREMENTS`（定义需求）\n- `CREATING ROADMAP`（创建路线图）\n- `PLANNING PHASE {N}`（规划阶段 {N}）\n- `EXECUTING WAVE {N}`（执行波次 {N}）\n- `VERIFYING`（验证）\n- `PHASE {N} COMPLETE ✓`（阶段 {N} 完成）\n- `MILESTONE COMPLETE 🎉`（里程碑完成）\n\n---\n\n## 检查点框\n\n需要用户操作。62 字符宽度。\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ CHECKPOINT: {类型} ║\n╚══════════════════════════════════════════════════════════════╝\n\n{内容}\n\n──────────────────────────────────────────────────────────────\n→ {操作提示}\n──────────────────────────────────────────────────────────────\n```\n\n**类型：**\n- `CHECKPOINT: 需要验证` → `→ 输入 \"approved\" 或描述问题`\n- `CHECKPOINT: 需要决策` → `→ 选择: option-a / option-b`\n- `CHECKPOINT: 需要操作` → `→ 完成后输入 \"done\"`\n\n---\n\n## 状态符号\n\n```\n✓ 完成 / 通过 / 已验证\n✗ 失败 / 缺失 / 阻塞\n◆ 进行中\n○ 待处理\n⚡ 自动批准\n⚠ 警告\n🎉 里程碑完成（仅在横幅中）\n```\n\n---\n\n## 进度显示\n\n**阶段/里程碑级别：**\n```\n进度: ████████░░ 80%\n```\n\n**任务级别：**\n```\n任务: 2/4 完成\n```\n\n**计划级别：**\n```\n计划: 3/5 完成\n```\n\n---\n\n## 生成指示器\n\n```\n◆ 正在生成研究员...\n\n◆ 并行生成 4 个研究员...\n → 技术栈研究\n → 功能研究\n → 架构研究\n → 陷阱研究\n\n✓ 研究员完成: STACK.md 已写入\n```\n\n---\n\n## 下一步区块\n\n始终在主要完成后。\n\n```\n───────────────────────────────────────────────────────────────\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n───────────────────────────────────────────────────────────────\n\n**也可选：**\n- (根据工作流选填可选命令，例如 `/gsd-progress --next`)\n\n───────────────────────────────────────────────────────────────\n```\n\n---\n\n## 错误框\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ ERROR ║\n╚══════════════════════════════════════════════════════════════╝\n\n{错误描述}\n\n**修复方法:** {解决步骤}\n```\n\n---\n\n## 表格\n\n```\n| 阶段 | 状态 | 计划 | 进度 |\n|------|------|------|------|\n| 1 | ✓ | 3/3 | 100% |\n| 2 | ◆ | 1/4 | 25% |\n| 3 | ○ | 0/2 | 0% |\n```\n\n---\n\n## 反模式\n\n- 变化的框/横幅宽度\n- 混合横幅样式（`===`、`---`、`***`）\n- 横幅中缺少 `GSD ►` 前缀\n- 随机 emoji（`🚀`、`✨`、`💫`）\n- 完成后缺少下一步区块","docs/zh-CN/references/verification-patterns.md":"# 验证模式\n\n如何验证不同类型的工件是真实实现，而非存根或占位符。\n\n\n**存在 ≠ 实现**\n\n文件存在并不意味着功能有效。验证必须检查：\n1. **存在** - 文件在预期路径\n2. **实质性** - 内容是真实实现，非占位符\n3. **已连接** - 已连接到系统的其他部分\n4. **功能性** - 调用时实际工作\n\n级别 1-3 可以编程检查。级别 4 通常需要人工验证。\n\n\n\n\n## 通用存根模式\n\n这些模式表明占位符代码，无论文件类型：\n\n**基于注释的存根：**\n```bash\n# 存根注释的 Grep 模式\ngrep -E \"(TODO|FIXME|XXX|HACK|PLACEHOLDER)\" \"$file\"\ngrep -E \"implement|add later|coming soon|will be\" \"$file\" -i\ngrep -E \"// \\.\\.\\.|/\\* \\.\\.\\. \\*/|# \\.\\.\\.\" \"$file\"\n```\n\n**输出中的占位符文本：**\n```bash\n# UI 占位符模式\ngrep -E \"placeholder|lorem ipsum|coming soon|under construction\" \"$file\" -i\ngrep -E \"sample|example|test data|dummy\" \"$file\" -i\ngrep -E \"\\[.*\\]|<.*>|\\{.*\\}\" \"$file\" # 模板括号未移除\n```\n\n**空或琐碎实现：**\n```bash\n# 什么都不做的函数\ngrep -E \"return null|return undefined|return \\{\\}|return \\[\\]\" \"$file\"\ngrep -E \"pass$|\\.\\.\\.|\\bnothing\\b\" \"$file\"\ngrep -E \"console\\.(log|warn|error).*only\" \"$file\" # 仅日志函数\n```\n\n**预期动态但硬编码的值：**\n```bash\n# 硬编码 ID、计数或内容\ngrep -E \"id.*=.*['\\\"].*['\\\"]\" \"$file\" # 硬编码字符串 ID\ngrep -E \"count.*=.*\\d+|length.*=.*\\d+\" \"$file\" # 硬编码计数\ngrep -E \"\\\\\\$\\d+\\.\\d{2}|\\d+ items\" \"$file\" # 硬编码显示值\n```\n\n\n\n\n\n## React/Next.js 组件\n\n**存在检查：**\n```bash\n# 文件存在且导出组件\n[ -f \"$component_path\" ] && grep -E \"export (default |)function|export const.*=.*\\(\" \"$component_path\"\n```\n\n**实质性检查：**\n```bash\n# 返回实际 JSX，非占位符\ngrep -E \"return.*<\" \"$component_path\" | grep -v \"return.*null\" | grep -v \"placeholder\" -i\n\n# 有有意义的内容（不仅仅是包装 div）\ngrep -E \"<[A-Z][a-zA-Z]+|className=|onClick=|onChange=\" \"$component_path\"\n\n# 使用 props 或 state（非静态）\ngrep -E \"props\\.|useState|useEffect|useContext|\\{.*\\}\" \"$component_path\"\n```\n\n**React 特有的存根模式：**\n```javascript\n// 危险信号 - 这些是存根：\nreturn
Component
\nreturn
Placeholder
\nreturn
{/* TODO */}
\nreturn

Coming soon

\nreturn null\nreturn <>\n\n// 也是存根 - 空处理器：\nonClick={() => {}}\nonChange={() => console.log('clicked')}\nonSubmit={(e) => e.preventDefault()} // 仅阻止默认，什么都不做\n```\n\n**连接检查：**\n```bash\n# 组件导入它需要的东西\ngrep -E \"^import.*from\" \"$component_path\"\n\n# Props 实际被使用（不仅仅是接收）\n# 查找解构或 props.X 用法\ngrep -E \"\\{ .* \\}.*props|\\bprops\\.[a-zA-Z]+\" \"$component_path\"\n\n# API 调用存在（对于数据获取组件）\ngrep -E \"fetch\\(|axios\\.|useSWR|useQuery|getServerSideProps|getStaticProps\" \"$component_path\"\n```\n\n**功能验证（需要人工）：**\n- 组件是否渲染可见内容？\n- 交互元素是否响应点击？\n- 数据是否加载并显示？\n- 错误状态是否适当显示？\n\n\n\n\n\n## API 路由（Next.js App Router / Express 等）\n\n**存在检查：**\n```bash\n# 路由文件存在\n[ -f \"$route_path\" ]\n\n# 导出 HTTP 方法处理器（Next.js App Router）\ngrep -E \"export (async )?(function|const) (GET|POST|PUT|PATCH|DELETE)\" \"$route_path\"\n\n# 或 Express 风格处理器\ngrep -E \"\\.(get|post|put|patch|delete)\\(\" \"$route_path\"\n```\n\n**实质性检查：**\n```bash\n# 有实际逻辑，不仅仅是 return 语句\nwc -l \"$route_path\" # 超过 10-15 行表明真实实现\n\n# 与数据源交互\ngrep -E \"prisma\\.|db\\.|mongoose\\.|sql|query|find|create|update|delete\" \"$route_path\" -i\n\n# 有错误处理\ngrep -E \"try|catch|throw|error|Error\" \"$route_path\"\n\n# 返回有意义的响应\ngrep -E \"Response\\.json|res\\.json|res\\.send|return.*\\{\" \"$route_path\" | grep -v \"message.*not implemented\" -i\n```\n\n**API 路由特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport async function POST() {\n return Response.json({ message: \"Not implemented\" })\n}\n\nexport async function GET() {\n return Response.json([]) // 空 array 无数据库查询\n}\n\nexport async function PUT() {\n return new Response() // 空响应\n}\n\n// 仅控制台日志：\nexport async function POST(req) {\n console.log(await req.json())\n return Response.json({ ok: true })\n}\n```\n\n**连接检查：**\n```bash\n# 导入数据库/服务客户端\ngrep -E \"^import.*prisma|^import.*db|^import.*client\" \"$route_path\"\n\n# 实际使用请求体（对于 POST/PUT）\ngrep -E \"req\\.json\\(\\)|req\\.body|request\\.json\\(\\)\" \"$route_path\"\n\n# 验证输入（不仅仅信任请求）\ngrep -E \"schema\\.parse|validate|zod|yup|joi\" \"$route_path\"\n```\n\n**功能验证（人工或自动化）：**\n- GET 是否从数据库返回真实数据？\n- POST 是否实际创建记录？\n- 错误响应是否有正确的状态码？\n- 认证检查是否实际执行？\n\n\n\n\n\n## 数据库模式（Prisma / Drizzle / SQL）\n\n**存在检查：**\n```bash\n# 模式文件存在\n[ -f \"prisma/schema.prisma\" ] || [ -f \"drizzle/schema.ts\" ] || [ -f \"src/db/schema.sql\" ]\n\n# 模型/表已定义\ngrep -E \"^model $model_name|CREATE TABLE $table_name|export const $table_name\" \"$schema_path\"\n```\n\n**实质性检查：**\n```bash\n# 有预期字段（不仅仅是 id）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"^\\s+\\w+\\s+\\w+\"\n\n# 有预期关系\ngrep -E \"@relation|REFERENCES|FOREIGN KEY\" \"$schema_path\"\n\n# 有适当的字段类型（不全是 String）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"Int|DateTime|Boolean|Float|Decimal|Json\"\n```\n\n**模式特有的存根模式：**\n```prisma\n// 危险信号 - 这些是存根：\nmodel User {\n id String @id\n // TODO: add fields\n}\n\nmodel Message {\n id String @id\n content String // 只有一个真实字段\n}\n\n// 缺少关键字段：\nmodel Order {\n id String @id\n // 缺少: userId, items, total, status, createdAt\n}\n```\n\n**连接检查：**\n```bash\n# 迁移存在且已应用\nls prisma/migrations/ 2>/dev/null | wc -l # 应该 > 0\nnpx prisma migrate status 2>/dev/null | grep -v \"pending\"\n\n# 客户端已生成\n[ -d \"node_modules/.prisma/client\" ]\n```\n\n**功能验证：**\n```bash\n# 可以查询表（自动化）\nnpx prisma db execute --stdin <<< \"SELECT COUNT(*) FROM $table_name\"\n```\n\n\n\n\n\n## 自定义 Hooks 和工具\n\n**存在检查：**\n```bash\n# 文件存在且导出函数\n[ -f \"$hook_path\" ] && grep -E \"export (default )?(function|const)\" \"$hook_path\"\n```\n\n**实质性检查：**\n```bash\n# Hook 使用 React hooks（对于自定义 hooks）\ngrep -E \"useState|useEffect|useCallback|useMemo|useRef|useContext\" \"$hook_path\"\n\n# 有有意义的返回值\ngrep -E \"return \\{|return \\[\" \"$hook_path\"\n\n# 超过琐碎长度\n[ $(wc -l < \"$hook_path\") -gt 10 ]\n```\n\n**Hooks 特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport function useAuth() {\n return { user: null, login: () => {}, logout: () => {} }\n}\n\nexport function useCart() {\n const [items, setItems] = useState([])\n return { items, addItem: () => console.log('add'), removeItem: () => {} }\n}\n\n// 硬编码返回：\nexport function useUser() {\n return { name: \"Test User\", email: \"test@example.com\" }\n}\n```\n\n**连接检查：**\n```bash\n# Hook 实际在某处被导入\ngrep -r \"import.*$hook_name\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n\n# Hook 实际被调用\ngrep -r \"$hook_name()\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n```\n\n\n\n\n\n## 环境变量和配置\n\n**存在检查：**\n```bash\n# .env 文件存在\n[ -f \".env\" ] || [ -f \".env.local\" ]\n\n# 必需变量已定义\ngrep -E \"^$VAR_NAME=\" .env .env.local 2>/dev/null\n```\n\n**实质性检查：**\n```bash\n# 变量有实际值（非占位符）\ngrep -E \"^$VAR_NAME=.+\" .env .env.local 2>/dev/null | grep -v \"your-.*-here|xxx|placeholder|TODO\" -i\n\n# 值对类型看起来有效：\n# - URL 应以 http 开头\n# - 密钥应足够长\n# - 布尔值应为 true/false\n```\n\n**环境变量特有的存根模式：**\n```bash\n# 危险信号 - 这些是存根：\nDATABASE_URL=your-database-url-here\nSTRIPE_SECRET_KEY=sk_test_xxx\nAPI_KEY=placeholder\nNEXT_PUBLIC_API_URL=http://localhost:3000 # 生产环境仍指向 localhost\n```\n\n**连接检查：**\n```bash\n# 变量实际在代码中使用\ngrep -r \"process\\.env\\.$VAR_NAME|env\\.$VAR_NAME\" src/ --include=\"*.ts\" --include=\"*.tsx\"\n\n# 变量在验证模式中（如果使用 zod 等验证 env）\ngrep -E \"$VAR_NAME\" src/env.ts src/env.mjs 2>/dev/null\n```\n\n\n\n\n\n## 连接验证模式\n\n连接验证检查组件是否实际通信。这是大多数存根隐藏的地方。\n\n### 模式：组件 → API\n\n**检查：** 组件是否实际调用 API？\n\n```bash\n# 查找 fetch/axios 调用\ngrep -E \"fetch\\(['\\\"].*$api_path|axios\\.(get|post).*$api_path\" \"$component_path\"\n\n# 验证未被注释掉\ngrep -E \"fetch\\(|axios\\.\" \"$component_path\" | grep -v \"^.*//.*fetch\"\n\n# 检查响应被使用\ngrep -E \"await.*fetch|\\.then\\(|setData|setState\" \"$component_path\"\n```\n\n**危险信号：**\n```typescript\n// Fetch 存在但响应被忽略：\nfetch('/api/messages') // 无 await，无 .then，无赋值\n\n// Fetch 在注释中：\n// fetch('/api/messages').then(r => r.json()).then(setMessages)\n\n// Fetch 到错误的端点：\nfetch('/api/message') // 拼写错误 - 应该是 /api/messages\n```\n\n### 模式：API → 数据库\n\n**检查：** API 路由是否实际查询数据库？\n\n```bash\n# 查找数据库调用\ngrep -E \"prisma\\.$model|db\\.query|Model\\.find\" \"$route_path\"\n\n# 验证被 await\ngrep -E \"await.*prisma|await.*db\\.\" \"$route_path\"\n\n# 检查结果被返回\ngrep -E \"return.*json.*data|res\\.json.*result\" \"$route_path\"\n```\n\n**危险信号：**\n```typescript\n// 查询存在但结果未返回：\nawait prisma.message.findMany()\nreturn Response.json({ ok: true }) // 返回静态值，非查询结果\n\n// 查询未被 await：\nconst messages = prisma.message.findMany() // 缺少 await\nreturn Response.json(messages) // 返回 Promise，非数据\n```\n\n### 模式：表单 → 处理器\n\n**检查：** 表单提交是否实际做些什么？\n\n```bash\n# 查找 onSubmit 处理器\ngrep -E \"onSubmit=\\{|handleSubmit\" \"$component_path\"\n\n# 检查处理器有内容\ngrep -A 10 \"onSubmit.*=\" \"$component_path\" | grep -E \"fetch|axios|mutate|dispatch\"\n\n# 验证不仅仅是 preventDefault\ngrep -A 5 \"onSubmit\" \"$component_path\" | grep -v \"only.*preventDefault\" -i\n```\n\n**危险信号：**\n```typescript\n// 处理器仅阻止默认：\nonSubmit={(e) => e.preventDefault()}\n\n// 处理器仅日志：\nconst handleSubmit = (data) => {\n console.log(data)\n}\n\n// 处理器为空：\nonSubmit={() => {}}\n```\n\n### 模式：状态 → 渲染\n\n**检查：** 组件是否渲染状态，而非硬编码内容？\n\n```bash\n# 查找 JSX 中的状态使用\ngrep -E \"\\{.*messages.*\\}|\\{.*data.*\\}|\\{.*items.*\\}\" \"$component_path\"\n\n# 检查状态的 map/render\ngrep -E \"\\.map\\(|\\.filter\\(|\\.reduce\\(\" \"$component_path\"\n\n# 验证动态内容\ngrep -E \"\\{[a-zA-Z_]+\\.\" \"$component_path\" # 变量插值\n```\n\n**危险信号：**\n```tsx\n// 硬编码而非状态：\nreturn
\n

Message 1

\n

Message 2

\n
\n\n// 状态存在但未渲染：\nconst [messages, setMessages] = useState([])\nreturn
No messages
// 总是显示 \"no messages\"\n\n// 渲染错误的状态：\nconst [messages, setMessages] = useState([])\nreturn
{otherData.map(...)}
// 使用不同数据\n```\n\n\n\n\n\n## 快速验证清单\n\n对于每种工件类型，运行此清单：\n\n### 组件清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数/const 组件\n- [ ] 返回 JSX（非 null/空）\n- [ ] 渲染中无占位符文本\n- [ ] 使用 props 或 state（非静态）\n- [ ] 事件处理器有真实实现\n- [ ] 导入正确解析\n- [ ] 在应用某处被使用\n\n### API 路由清单\n- [ ] 文件存在于预期路径\n- [ ] 导出 HTTP 方法处理器\n- [ ] 处理器超过 5 行\n- [ ] 查询数据库或服务\n- [ ] 返回有意义的响应（非空/占位符）\n- [ ] 有错误处理\n- [ ] 验证输入\n- [ ] 从前端调用\n\n### 模式清单\n- [ ] 模型/表已定义\n- [ ] 有所有预期字段\n- [ ] 字段有适当类型\n- [ ] 如需要关系已定义\n- [ ] 迁移存在且已应用\n- [ ] 客户端已生成\n\n### Hook/工具清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数\n- [ ] 有有意义的实现（非空返回）\n- [ ] 在应用某处被使用\n- [ ] 返回值被消费\n\n### 连接清单\n- [ ] 组件 → API: fetch/axios 调用存在且使用响应\n- [ ] API → 数据库: 查询存在且结果返回\n- [ ] 表单 → 处理器: onSubmit 调用 API/mutation\n- [ ] 状态 → 渲染: 状态变量出现在 JSX 中\n\n\n\n\n\n## 自动化验证方法\n\n对于验证子代理，使用此模式：\n\n```bash\n# 1. 检查存在\ncheck_exists() {\n [ -f \"$1\" ] && echo \"EXISTS: $1\" || echo \"MISSING: $1\"\n}\n\n# 2. 检查存根模式\ncheck_stubs() {\n local file=\"$1\"\n local stubs=$(grep -c -E \"TODO|FIXME|placeholder|not implemented\" \"$file\" 2>/dev/null || echo 0)\n [ \"$stubs\" -gt 0 ] && echo \"STUB_PATTERNS: $stubs in $file\"\n}\n\n# 3. 检查连接（组件调用 API）\ncheck_wiring() {\n local component=\"$1\"\n local api_path=\"$2\"\n grep -q \"$api_path\" \"$component\" && echo \"WIRED: $component → $api_path\" || echo \"NOT_WIRED: $component → $api_path\"\n}\n\n# 4. 检查实质性（超过 N 行，有预期模式）\ncheck_substantive() {\n local file=\"$1\"\n local min_lines=\"$2\"\n local pattern=\"$3\"\n local lines=$(wc -l < \"$file\" 2>/dev/null || echo 0)\n local has_pattern=$(grep -c -E \"$pattern\" \"$file\" 2>/dev/null || echo 0)\n [ \"$lines\" -ge \"$min_lines\" ] && [ \"$has_pattern\" -gt 0 ] && echo \"SUBSTANTIVE: $file\" || echo \"THIN: $file ($lines lines, $has_pattern matches)\"\n}\n```\n\n对每个必须有工件运行这些检查。汇总结果到 VERIFICATION.md。\n\n\n\n\n\n## 何时需要人工验证\n\n有些事情无法编程验证。标记这些需要人工测试：\n\n**始终人工：**\n- 视觉外观（看起来对吗？）\n- 用户流程完成（能实际做那件事吗？）\n- 实时行为（WebSocket、SSE）\n- 外部服务集成（Stripe、邮件发送）\n- 错误消息清晰度（消息有帮助吗？）\n- 性能感觉（感觉快吗？）\n\n**如不确定则人工：**\n- grep 无法追踪的复杂连接\n- 依赖状态的动态行为\n- 边缘情况和错误状态\n- 移动端响应式\n- 无障碍性\n\n**人工验证请求格式：**\n```markdown\n## 需要人工验证\n\n### 1. 聊天消息发送\n**测试：** 输入消息并点击发送\n**预期：** 消息出现在列表中，输入框清空\n**检查：** 刷新后消息是否持久？\n\n### 2. 错误处理\n**测试：** 断开网络，尝试发送\n**预期：** 错误消息出现，消息未丢失\n**检查：** 重连后能重试吗？\n```\n\n\n\n\n\n## 检查点前自动化\n\n关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议，请参阅：\n\n**@~/.claude/get-shit-done/references/checkpoints.md** → `` 部分\n\n关键原则：\n- Claude 在呈现检查点**之前**设置验证环境\n- 用户从不运行 CLI 命令（仅访问 URL）\n- 服务器生命周期：检查点前启动、处理端口冲突、持续运行\n- CLI 安装：安全处自动安装，否则检查点让用户选择\n- 错误处理：检查点前修复损坏环境，绝不呈现有失败设置的检查点\n\n","get-shit-done/references/sketch-theme-system.md":"# Shared Theme System\n\nAll sketches share a CSS variable theme so design decisions compound across sketches.\n\n## Setup\n\nOn the first sketch, create `.planning/sketches/themes/` with a default theme:\n\n```\n.planning/sketches/\n themes/\n default.css <- all sketches link to this\n 001-dashboard-layout/\n index.html <- links to ../themes/default.css\n```\n\n## Theme File Structure\n\nEach theme defines CSS custom properties only — no component styles, no layout rules. Just the visual vocabulary:\n\n```css\n:root {\n /* Colors */\n --color-bg: #fafafa;\n --color-surface: #ffffff;\n --color-border: #e5e5e5;\n --color-text: #1a1a1a;\n --color-text-muted: #6b6b6b;\n --color-primary: #2563eb;\n --color-primary-hover: #1d4ed8;\n --color-accent: #f59e0b;\n --color-danger: #ef4444;\n --color-success: #22c55e;\n\n /* Typography */\n --font-sans: 'Inter', system-ui, sans-serif;\n --font-mono: 'JetBrains Mono', monospace;\n --text-xs: 0.75rem;\n --text-sm: 0.875rem;\n --text-base: 1rem;\n --text-lg: 1.125rem;\n --text-xl: 1.25rem;\n --text-2xl: 1.5rem;\n --text-3xl: 1.875rem;\n\n /* Spacing */\n --space-1: 4px;\n --space-2: 8px;\n --space-3: 12px;\n --space-4: 16px;\n --space-6: 24px;\n --space-8: 32px;\n --space-12: 48px;\n\n /* Shapes */\n --radius-sm: 4px;\n --radius-md: 8px;\n --radius-lg: 12px;\n --radius-full: 9999px;\n\n /* Shadows */\n --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);\n --shadow-md: 0 4px 6px rgba(0,0,0,0.07);\n --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);\n}\n```\n\nAdapt the default theme to match the mood/direction established during intake. The values above are a starting point — change colors, fonts, spacing, and shapes to match the agreed aesthetic.\n\n## Linking\n\nEvery sketch links to the theme:\n\n```html\n\n```\n\n## Creating New Themes\n\nWhen a sketch reveals an aesthetic fork (\"should this feel clinical or warm?\"), create both as theme files rather than arguing about it. The user can switch and feel the difference.\n\nName themes descriptively: `midnight.css`, `warm-minimal.css`, `brutalist.css`.\n\n## Theme Switcher\n\nInclude in every sketch (part of the sketch toolbar):\n\n```html\n\n```\n\nDynamically populate options by listing available theme files, or hardcode the known themes.\n","get-shit-done/templates/copilot-instructions.md":"# Instructions for GSD\n\n- Use the get-shit-done skill when the user asks for GSD or uses a `gsd-*` command.\n- Treat `/gsd-...` or `gsd-...` as command invocations and load the matching file from `.github/skills/gsd-*`.\n- When a command says to spawn a subagent, prefer a matching custom agent from `.github/agents`.\n- Do not apply GSD workflows unless the user explicitly asks for them.\n- After completing any `gsd-*` command (or any deliverable it triggers: feature, bug fix, tests, docs, etc.), ALWAYS: (1) offer the user the next step by prompting via `ask_user`; repeat this feedback loop until the user explicitly indicates they are done.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Repository Guidelines\n\n## Active Discussions\n\nFor current work on **Grok Build compatibility** and multi-runtime synchronization across Grok Build, Claude Code, Gemini CLI, and Codex, see:\n\n- `docs/discussions/grok-build-support-2026-05.md`\n\n## Project Structure & Module Organization\n\nThis repository ships GSD as a Node.js CLI and SDK. Root package entry points live in `bin/`, scripts in `scripts/`, runtime hooks in `hooks/`, command definitions in `commands/gsd/`, and workflow/template content in `get-shit-done/`. Agent role files are in `agents/`; docs are in `docs/`; logos and terminal images are in `assets/`. Root tests are in `tests/*.test.cjs`. The TypeScript SDK is isolated under `sdk/`, with source and Vitest tests in `sdk/src/`.\n\n## Build, Test, and Development Commands\n\nUse Node.js `>=22`.\n\n- `npm install`: install root dependencies.\n- `npm test`: builds the SDK first, then runs root `node:test` suites via `scripts/run-tests.cjs`.\n- `npm run test:coverage`: runs root tests with `c8` and enforces 70% line coverage for included CommonJS library files.\n- `npm run build:hooks`: rebuilds generated hook artifacts.\n- `npm run build:sdk`: installs SDK dependencies and builds TypeScript.\n- `cd sdk && npm test`: runs SDK Vitest unit and integration projects.\n- `cd sdk && npm run build`: type-checks and emits `sdk/dist/`.\n\n## Coding Style & Naming Conventions\n\nMatch the existing style in the edited area. Root JavaScript is CommonJS, generally strict-mode, two-space indentation, semicolons, `const`/`let`, and `node:` imports for built-ins. SDK code is strict TypeScript using ESM/`NodeNext`. Keep command, workflow, and test filenames kebab-case, for example `commands/gsd/plan-phase.md` and `tests/bug-2396-makefile-test-priority.test.cjs`. Agent files use `gsd-*.md`. Avoid unrelated formatting and unnecessary dependencies.\n\n## Testing Guidelines\n\nRoot tests use Node’s built-in `node:test` and `node:assert/strict`; do not add Jest, Mocha, or Chai. Prefer helpers from `tests/helpers.cjs` for temporary projects, cleanup, and CLI execution. Name root tests `*.test.cjs`; run one with `node --test tests/name.test.cjs`. SDK tests use Vitest with `*.test.ts` for unit tests and `*.integration.test.ts` for integration tests.\n\n## Commit & Pull Request Guidelines\n\nRecent history follows Conventional Commit prefixes such as `fix:`, `feat:`, and `ci:`, often with issue references: `fix(#2623): resolve parent .planning root...`. Keep commits scoped and descriptive.\n\nEvery PR must link an approved or confirmed issue with `Closes #123`, `Fixes #123`, or `Resolves #123`. Use the matching template in `.github/PULL_REQUEST_TEMPLATE/`. Include behavior changes, root cause when relevant, test evidence, affected platforms/runtimes, and update `CHANGELOG.md` or docs for user-facing changes.\n\n## Security & Configuration Tips\n\nDo not commit secrets, local config, or generated worktree artifacts. Before release-facing changes, run the relevant scan scripts in `scripts/`, especially `secret-scan.sh`, `base64-scan.sh`, and `prompt-injection-scan.sh`.\n","isInternal":false,"tokens":733,"sizeBytes":3078},{"name":"AGENTS.md","path":"docs/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/AGENTS.md","title":"docs - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# GSD Agent Reference\n\n> Full role cards for 21 primary agents plus concise stubs for 12 advanced/specialized agents (33 shipped agents total). The `agents/` directory and [`docs/INVENTORY.md`](INVENTORY.md) are the authoritative roster; see [Architecture](ARCHITECTURE.md) for context.\n\n---\n\n## Overview\n\nGSD uses a multi-agent architecture where thin orchestrators (workflow files) spawn specialized agents with fresh context windows. Each agent has a focused role, limited tool access, and produces specific artifacts.\n\n### Agent Categories\n\n> The table below covers the **21 primary agents** detailed in this section. Twelve additional shipped agents (pattern-mapper, debug-session-manager, code-reviewer, code-fixer, ai-researcher, domain-researcher, eval-planner, eval-auditor, framework-selector, intel-updater, doc-classifier, doc-synthesizer) have concise stubs in the [Advanced and Specialized Agents](#advanced-and-specialized-agents) section below. For the authoritative 33-agent roster, see [`docs/INVENTORY.md`](INVENTORY.md) and the `agents/` directory.\n\n| Category | Count | Agents |\n|----------|-------|--------|\n| Researchers | 3 | project-researcher, phase-researcher, ui-researcher |\n| Analyzers | 2 | assumptions-analyzer, advisor-researcher |\n| Synthesizers | 1 | research-synthesizer |\n| Planners | 1 | planner |\n| Roadmappers | 1 | roadmapper |\n| Executors | 1 | executor |\n| Checkers | 3 | plan-checker, integration-checker, ui-checker |\n| Verifiers | 1 | verifier |\n| Auditors | 3 | nyquist-auditor, ui-auditor, security-auditor |\n| Mappers | 1 | codebase-mapper |\n| Debuggers | 1 | debugger |\n| Doc Writers | 2 | doc-writer, doc-verifier |\n| Profilers | 1 | user-profiler |\n\n---\n\n## Agent Details\n\n### gsd-project-researcher\n\n**Role:** Researches domain ecosystem before roadmap creation.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project`, `/gsd-new-milestone` |\n| **Parallelism** | 4 instances (stack, features, architecture, pitfalls) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |\n\n**Capabilities:**\n- Web search for current ecosystem information\n- Context7 MCP integration for library documentation\n- Writes research documents directly to disk (reduces orchestrator context load)\n\n---\n\n### gsd-phase-researcher\n\n**Role:** Researches how to implement a specific phase before planning.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` |\n| **Parallelism** | 4 instances (same focus areas as project researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `{phase}-RESEARCH.md` |\n\n**Capabilities:**\n- Reads CONTEXT.md to focus research on user's decisions\n- Investigates implementation patterns for the specific phase domain\n- Detects test infrastructure for Nyquist validation mapping\n\n---\n\n### gsd-ui-researcher\n\n**Role:** Produces UI design contracts for frontend phases.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#E879F9` (fuchsia) |\n| **Produces** | `{phase}-UI-SPEC.md` |\n\n**Capabilities:**\n- Detects design system state (shadcn components.json, Tailwind config, existing tokens)\n- Offers shadcn initialization for React/Next.js/Vite projects\n- Asks only unanswered design contract questions\n- Enforces registry safety gate for third-party components\n\n---\n\n### gsd-assumptions-analyzer\n\n**Role:** Deeply analyzes codebase for a phase and returns structured assumptions with evidence, confidence levels, and consequences if wrong.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase-assumptions` workflow (when `workflow.discuss_mode = 'assumptions'`) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | Structured assumptions with decision statements, evidence file paths, confidence levels |\n\n**Key behaviors:**\n- Reads ROADMAP.md phase description and prior CONTEXT.md files\n- Searches codebase for files related to the phase (components, patterns, similar features)\n- Reads 5-15 most relevant source files to form evidence-based assumptions\n- Classifies confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways)\n- Flags topics that need external research (library compatibility, ecosystem best practices)\n- Output calibrated by tier: full_maturity (3-5 areas), standard (3-4), minimal_decisive (2-3)\n\n---\n\n### gsd-advisor-researcher\n\n**Role:** Researches a single gray area decision during discuss-phase advisor mode and returns a structured comparison table.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase` workflow (when ADVISOR_MODE = true) |\n| **Parallelism** | Multiple instances (one per gray area) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | 5-column comparison table (Option / Pros / Cons / Complexity / Recommendation) with rationale paragraph |\n\n**Key behaviors:**\n- Researches a single assigned gray area using Claude's knowledge, Context7, and web search\n- Produces genuinely viable options — no padding with filler alternatives\n- Complexity column uses impact surface + risk (never time estimates)\n- Recommendations are conditional (\"Rec if X\", \"Rec if Y\") — never single-winner ranking\n- Output calibrated by tier: full_maturity (3-5 options with maturity signals), standard (2-4), minimal_decisive (2 options, decisive recommendation)\n\n---\n\n### gsd-research-synthesizer\n\n**Role:** Combines outputs from parallel researchers into a unified summary.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` (after 4 researchers complete) |\n| **Parallelism** | Single instance (sequential after researchers) |\n| **Tools** | Read, Write, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `.planning/research/SUMMARY.md` |\n\n---\n\n### gsd-planner\n\n**Role:** Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase`, `/gsd-quick` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep, WebFetch, mcp (context7) |\n| **Model (balanced)** | Opus |\n| **Color** | Green |\n| **Produces** | `{phase}-{N}-PLAN.md` files |\n\n**Key behaviors:**\n- Reads PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md\n- Creates 2-3 atomic task plans sized for single context windows\n- Uses XML structure with `` elements\n- Includes `read_first` and `acceptance_criteria` sections\n- Groups plans into dependency waves\n- Performs reachability check to validate plan steps reference accessible files and APIs (v1.32)\n\n---\n\n### gsd-roadmapper\n\n**Role:** Creates project roadmaps with phase breakdown and requirement mapping.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `ROADMAP.md` |\n\n**Key behaviors:**\n- Maps requirements to phases (traceability)\n- Derives success criteria from requirements\n- Respects granularity setting for phase count\n- Validates coverage (every v1 requirement mapped to a phase)\n\n---\n\n### gsd-executor\n\n**Role:** Executes GSD plans with atomic commits, deviation handling, and checkpoint protocols.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase`, `/gsd-quick` |\n| **Parallelism** | Multiple (parallel within waves, sequential across waves) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Yellow |\n| **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` |\n\n**Key behaviors:**\n- Fresh 200K context window per plan\n- Follows XML task instructions precisely\n- Atomic git commit per completed task\n- Handles checkpoint types: auto, human-verify, decision, human-action\n- Reports deviations from plan in SUMMARY.md\n- Invokes node repair on verification failure\n\n---\n\n### gsd-plan-checker\n\n**Role:** Verifies plans will achieve phase goals before execution.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (verification loop, max 3 iterations) |\n| **Parallelism** | Single instance (iterative) |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | PASS/FAIL verdict with specific feedback |\n\n**8 Verification Dimensions:**\n1. Requirement coverage\n2. Task atomicity\n3. Dependency ordering\n4. File scope\n5. Verification commands\n6. Context fit\n7. Gap detection\n8. Nyquist compliance (when enabled)\n\n---\n\n### gsd-integration-checker\n\n**Role:** Verifies cross-phase integration and end-to-end flows.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-audit-milestone` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Blue |\n| **Produces** | Integration verification report |\n\n---\n\n### gsd-ui-checker\n\n**Role:** Validates UI-SPEC.md design contracts against quality dimensions.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` (validation loop, max 2 iterations) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#22D3EE` (cyan) |\n| **Produces** | BLOCK/FLAG/PASS verdict |\n\n---\n\n### gsd-verifier\n\n**Role:** Verifies phase goal achievement through goal-backward analysis.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase` (after all executors complete) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | `{phase}-VERIFICATION.md` |\n\n**Key behaviors:**\n- Checks codebase against phase goals, not just task completion\n- PASS/FAIL with specific evidence\n- Logs issues for `/gsd-verify-work` to address\n- Milestone scope filtering: gaps addressed in later phases are marked as \"deferred\", not reported as failures (v1.32)\n- **Test quality audit** (v1.32): verifies that tests prove what they claim by checking for disabled/skipped tests on requirements, circular test patterns (system generating its own expected values), assertion strength (existence vs. value vs. behavioral), and expected value provenance. Blockers from test quality audit override an otherwise passing verification\n\n---\n\n### gsd-nyquist-auditor\n\n**Role:** Fills Nyquist validation gaps by generating tests.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-validate-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Produces** | Test files, updated `VALIDATION.md` |\n\n**Key behaviors:**\n- Never modifies implementation code — only test files\n- Max 3 attempts per gap\n- Flags implementation bugs as escalations for user\n\n---\n\n### gsd-ui-auditor\n\n**Role:** Retroactive 6-pillar visual audit of implemented frontend code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F472B6` (pink) |\n| **Produces** | `{phase}-UI-REVIEW.md` with scores |\n\n**6 Audit Pillars (scored 1-4):**\n1. Copywriting\n2. Visuals\n3. Color\n4. Typography\n5. Spacing\n6. Experience Design\n\n---\n\n### gsd-codebase-mapper\n\n**Role:** Explores codebase and writes structured analysis documents.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase`, post-execute drift gate in `/gsd-execute-phase` |\n| **Parallelism** | 4 instances (tech, architecture, quality, concerns) |\n| **Tools** | Read, Bash, Grep, Glob, Write |\n| **Model (balanced)** | Haiku |\n| **Color** | Cyan |\n| **Produces** | `.planning/codebase/*.md` (7 documents, with `last_mapped_commit` frontmatter) |\n\n**Key behaviors:**\n- Read-only exploration + structured output\n- Writes documents directly to disk\n- No reasoning required — pattern extraction from file contents\n\n**`--paths ` scope hint (#2003):**\nAccepts an optional `--paths` directive in its prompt. When present, the\nmapper restricts Glob/Grep/Bash exploration to the listed repo-relative path\nprefixes — this is the incremental-remap path used by the post-execute\ncodebase-drift gate. Path values that contain `..`, start with `/`, or\ninclude shell metacharacters are rejected. Without the hint, the mapper\nruns its default whole-repo scan.\n\n---\n\n### gsd-debugger\n\n**Role:** Investigates bugs using scientific method with persistent state.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug`, `/gsd-verify-work` (for failures) |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | `.planning/debug/*.md`, knowledge-base updates |\n\n**Debug Session Lifecycle:**\n`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved`\n\n**Key behaviors:**\n- Tracks hypotheses, evidence, and eliminated theories\n- State persists across context resets\n- Requires human verification before marking resolved\n- Appends to persistent knowledge base on resolution\n- Consults knowledge base on new sessions\n\n---\n\n### gsd-user-profiler\n\n**Role:** Analyzes session messages across 8 behavioral dimensions to produce a scored developer profile.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-profile-user` |\n| **Parallelism** | Single instance |\n| **Tools** | Read |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `USER-PROFILE.md`, `CLAUDE.md` profile section |\n\n**Behavioral Dimensions:**\nCommunication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth.\n\n**Key behaviors:**\n- Read-only agent — analyzes extracted session data, does not modify files\n- Produces scored dimensions with confidence levels and evidence citations\n- Questionnaire fallback when session history is unavailable\n\n---\n\n### gsd-doc-writer\n\n**Role:** Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode, and project context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` |\n| **Parallelism** | Multiple instances (one per doc type) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | Project documentation files (README, architecture, API docs, etc.) |\n\n**Key behaviors:**\n- Supports modes: create, update, supplement, fix\n- Handles doc types: readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing, custom\n- Monorepo-aware: can generate per-package READMEs\n- Fix mode accepts failure objects from gsd-doc-verifier for targeted corrections\n- Writes directly to disk — does not return content to orchestrator\n\n---\n\n### gsd-doc-verifier\n\n**Role:** Verifies factual claims in generated documentation against the live codebase.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` (after doc-writer completes) |\n| **Parallelism** | Multiple instances (one per doc file) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Structured JSON verification results per doc |\n\n**Key behaviors:**\n- Extracts checkable claims (file paths, function names, CLI commands, config keys)\n- Verifies each claim against filesystem using tools only — no assumptions\n- Writes structured JSON result file for orchestrator to process\n- Failed claims feed back to doc-writer in fix mode\n\n---\n\n### gsd-security-auditor\n\n**Role:** Verifies threat mitigations from PLAN.md threat model exist in implemented code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-secure-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `{phase}-SECURITY.md` |\n\n**Key behaviors:**\n- Verifies each threat by its declared disposition (mitigate / accept / transfer)\n- Does NOT scan blindly for new vulnerabilities — verifies declared mitigations only\n- Implementation files are read-only — never patches implementation code\n- Unmitigated threats reported as OPEN_THREATS or ESCALATE\n- Supports ASVS levels 1/2/3 for verification depth\n\n---\n\n## Advanced and Specialized Agents\n\nTwelve additional agents ship under `agents/gsd-*.md` and are used by specialty workflows (`/gsd-ai-integration-phase`, `/gsd-eval-review`, `/gsd-code-review`, `/gsd-code-review --fix`, `/gsd-debug`, `/gsd-map-codebase --query`, `/gsd-ingest-docs`) and by the planner pipeline. Each carries full frontmatter in its agent file; the stubs below are concise by design. The authoritative roster (with spawner and primary-doc status per agent) lives in [`docs/INVENTORY.md`](INVENTORY.md).\n\n### gsd-pattern-mapper\n\n**Role:** Read-only codebase analysis that maps files-to-be-created or modified to their closest existing analogs, producing `PATTERNS.md` for the planner to consume.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (between research and planning) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep, Write |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `PATTERNS.md` in the phase directory |\n\n**Key behaviors:**\n- Extracts file list from CONTEXT.md and RESEARCH.md; classifies each by role (controller, component, service, model, middleware, utility, config, test) and data flow (CRUD, streaming, file I/O, event-driven, request-response)\n- Searches for the closest existing analog per file and extracts concrete code excerpts (imports, auth patterns, core pattern, error handling)\n- Strictly read-only against source; only writes `PATTERNS.md`\n\n---\n\n### gsd-debug-session-manager\n\n**Role:** Runs the full `/gsd-debug` checkpoint-and-continuation loop in an isolated context so the orchestrator's main context stays lean; spawns `gsd-debugger` agents, dispatches specialist skills, and handles user checkpoints via AskUserQuestion.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug` |\n| **Parallelism** | Single instance (interactive, stateful) |\n| **Tools** | Read, Write, Bash, Grep, Glob, Task, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Compact summary returned to main context; evolves the `.planning/debug/{slug}.md` session file |\n\n**Key behaviors:**\n- Reads the debug session file first; passes file paths (not inlined contents) to spawned agents to respect context budget\n- Treats all user-supplied AskUserQuestion content as data-only, wrapped in DATA_START/DATA_END markers\n- Coordinates TDD gates and reasoning checkpoints introduced in v1.36.0\n\n---\n\n### gsd-code-reviewer\n\n**Role:** Reviews source files for bugs, security vulnerabilities, and code-quality problems; produces a structured `REVIEW.md` with severity-classified findings.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review` |\n| **Parallelism** | Typically single instance per review scope |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | `REVIEW.md` in the phase directory |\n\n**Key behaviors:**\n- Detects bugs (logic errors, null/undefined checks, off-by-one, type mismatches, unreachable code), security issues (injection, XSS, hardcoded secrets, insecure crypto), and quality issues\n- Honors `CLAUDE.md` project conventions and `.claude/skills/` / `.agents/skills/` rules when present\n- Read-only against implementation source — never modifies code under review\n\n---\n\n### gsd-code-fixer\n\n**Role:** Applies fixes to findings from `REVIEW.md` with intelligent (non-blind) patching and atomic per-fix commits; produces `REVIEW-FIX.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review --fix` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Edit, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#10B981` (emerald) |\n| **Produces** | `REVIEW-FIX.md`; one atomic git commit per applied fix |\n\n**Key behaviors:**\n- Treats `REVIEW.md` suggestions as guidance, not a patch to apply literally\n- Commits each fix atomically so review and rollback stay granular\n- Honors `CLAUDE.md` and project-skill rules during fixes\n\n---\n\n### gsd-ai-researcher\n\n**Role:** Researches a chosen AI/LLM framework's official documentation and distills it into implementation-ready guidance — framework quick reference, patterns, and pitfalls — for the Section 3–4b body of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential with domain-researcher / eval-planner) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#34D399` (green) |\n| **Produces** | Sections 3–4b of `AI-SPEC.md` (framework quick reference + implementation guidance) |\n\n**Key behaviors:**\n- Uses Context7 MCP when available; falls back to the `ctx7` CLI via Bash when MCP tools are stripped from the agent\n- Anchors guidance to the specific use case, not generic framework overviews\n\n---\n\n### gsd-domain-researcher\n\n**Role:** Surfaces the business-domain and real-world evaluation context for an AI system — expert rubric ingredients, failure modes, regulatory context — before the eval-planner turns it into measurable rubrics. Writes Section 1b of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#A78BFA` (violet) |\n| **Produces** | Section 1b of `AI-SPEC.md` |\n\n**Key behaviors:**\n- Researches the domain, not the technical framework — its output feeds the eval-planner downstream\n- Produces rubric ingredients that downstream evaluators can turn into measurable criteria\n\n---\n\n### gsd-eval-planner\n\n**Role:** Designs the structured evaluation strategy for an AI phase — failure modes, eval dimensions with rubrics, tooling, reference dataset, guardrails, production monitoring. Writes Sections 5–7 of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential after domain-researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | Sections 5–7 of `AI-SPEC.md` (Evaluation Strategy, Guardrails, Production Monitoring) |\n\n**Required reading:** `get-shit-done/references/ai-evals.md` (evaluation framework).\n\n**Key behaviors:**\n- Turns domain-researcher rubric ingredients into measurable, tooled evaluation criteria\n- Does not re-derive domain context — reads Section 1 and 1b of `AI-SPEC.md` as established input\n\n---\n\n### gsd-eval-auditor\n\n**Role:** Retroactive audit of an implemented AI phase's evaluation coverage against its planned `AI-SPEC.md` eval strategy. Scores each eval dimension `COVERED` / `PARTIAL` / `MISSING` and produces `EVAL-REVIEW.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-eval-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `EVAL-REVIEW.md` with dimension scores, findings, and remediation guidance |\n\n**Required reading:** `get-shit-done/references/ai-evals.md`.\n\n**Key behaviors:**\n- Compares the implemented codebase against the planned eval strategy — never re-plans\n- Reads implementation files incrementally to respect context budget\n\n---\n\n### gsd-framework-selector\n\n**Role:** Interactive decision-matrix agent that runs a ≤6-question interview, scores candidate AI/LLM frameworks, and returns a ranked recommendation with rationale.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#38BDF8` (sky blue) |\n| **Produces** | Scored ranked recommendation (structured return to orchestrator) |\n\n**Required reading:** `get-shit-done/references/ai-frameworks.md` (decision matrix).\n\n**Key behaviors:**\n- Scans `package.json`, `pyproject.toml`, `requirements*.txt` for existing AI libraries before the interview to avoid recommending a rejected framework\n- Asks only what the codebase scan and CONTEXT.md have not already answered\n\n---\n\n### gsd-intel-updater\n\n**Role:** Reads project source and writes structured intel (JSON + Markdown) into `.planning/intel/`, building a queryable codebase knowledge base that other agents use instead of performing expensive fresh exploration.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase --query` (refresh / update flows) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | `.planning/intel/*.json` (and companion Markdown) consumed by `gsd-sdk query intel` |\n\n**Key behaviors:**\n- Writes current state only — no temporal language, every claim references an actual file path\n- Uses Glob / Read / Grep for cross-platform correctness; Bash is reserved for `gsd-sdk query intel` CLI calls\n\n---\n\n### gsd-doc-classifier\n\n**Role:** Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN. Extracts title, scope summary, and cross-references. Writes a JSON classification file used by `gsd-doc-synthesizer` to build a consolidated context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (parallel fan-out over the doc corpus) |\n| **Parallelism** | One instance per input document |\n| **Tools** | Read, Write, Grep, Glob |\n| **Model (balanced)** | Haiku |\n| **Color** | Yellow |\n| **Produces** | One JSON classification file per input doc (type, title, scope, refs) |\n\n**Key behaviors:**\n- Single-doc scope — never synthesizes or resolves conflicts (that is the synthesizer's job)\n- Heuristic-first classification; returns UNKNOWN when the doc lacks type signals rather than guessing\n\n---\n\n### gsd-doc-synthesizer\n\n**Role:** Synthesizes classified planning docs into a single consolidated context. Applies precedence rules, detects cross-reference cycles, enforces LOCKED-vs-LOCKED hard-blocks, and writes `INGEST-CONFLICTS.md` with three buckets (auto-resolved, competing-variants, unresolved-blockers).\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (after classifier fan-in) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Grep, Glob, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Consolidated context for `.planning/` plus `INGEST-CONFLICTS.md` report |\n\n**Key behaviors:**\n- Hard-blocks on LOCKED-vs-LOCKED ADR contradictions instead of silently picking a winner\n- Follows the `references/doc-conflict-engine.md` contract so `/gsd-import` and `/gsd-ingest-docs` produce consistent conflict reports\n\n---\n\n## Agent Tool Permissions Summary\n\n> **Scope:** this table covers the 21 primary agents only. The 12 advanced/specialized agents listed above carry their own tool surfaces in their `agents/gsd-*.md` frontmatter (summarized in the per-agent stubs above and in [`docs/INVENTORY.md`](INVENTORY.md)).\n\n| Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |\n|-------|------|-------|------|------|------|------|-----------|----------|-----|\n| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | |\n| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| research-synthesizer | ✓ | ✓ | | ✓ | | | | | |\n| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |\n| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |\n| user-profiler | ✓ | | | | | | | | |\n| doc-writer | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| doc-verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| security-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n\n**Principle of Least Privilege:**\n- Checkers are read-only (no Write/Edit) — they evaluate, never modify\n- Researchers have web access — they need current ecosystem information\n- Executors have Edit — they modify code but not web access\n- Mappers have Write — they write analysis documents but not Edit (no code changes)\n","isInternal":false,"tokens":7692,"sizeBytes":30307},{"name":"copilot-instructions.md","path":"get-shit-done/templates/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/get-shit-done/templates/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Instructions for GSD\n\n- Use the get-shit-done skill when the user asks for GSD or uses a `gsd-*` command.\n- Treat `/gsd-...` or `gsd-...` as command invocations and load the matching file from `.github/skills/gsd-*`.\n- When a command says to spawn a subagent, prefer a matching custom agent from `.github/agents`.\n- Do not apply GSD workflows unless the user explicitly asks for them.\n- After completing any `gsd-*` command (or any deliverable it triggers: feature, bug fix, tests, docs, etc.), ALWAYS: (1) offer the user the next step by prompting via `ask_user`; repeat this feedback loop until the user explicitly indicates they are done.\n","isInternal":false,"tokens":161,"sizeBytes":644},{"name":"discovery-contract.md","path":"docs/skills/discovery-contract.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/skills/discovery-contract.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Skill Discovery Contract\n\n> Canonical rules for scanning, inventorying, and rendering GSD skills.\n\n## Root Categories\n\n### Project Roots\n\nScan these roots relative to the project root:\n\n- `.claude/skills/`\n- `.agents/skills/`\n- `.cursor/skills/`\n- `.github/skills/`\n- `./.codex/skills/`\n\nThese roots are used for project-specific skills and for the project `CLAUDE.md` skills section.\n\n### Managed Global Roots\n\nScan these roots relative to the user home directory:\n\n- `~/.claude/skills/`\n- `~/.codex/skills/`\n\nThese roots are used for managed runtime installs and inventory reporting.\n\n### Deprecated Import-Only Root\n\n- `~/.claude/get-shit-done/skills/`\n\nThis root is kept for legacy migration only. Inventory code may report it, but new installs should not write here.\n\n### Legacy Claude Commands\n\n- `~/.claude/commands/gsd/`\n\nThis is not a skills root. Discovery code only checks whether it exists so inventory can report legacy Claude installs.\n\n## Normalization Rules\n\n- Scan only subdirectories that contain `SKILL.md`.\n- Read `name` and `description` from YAML frontmatter.\n- Use the directory name when `name` is missing.\n- Extract trigger hints from body lines that match `TRIGGER when: ...`.\n- Treat `gsd-*` directories as installed framework skills.\n- Treat `~/.claude/get-shit-done/skills/` entries as deprecated/import-only.\n- Treat `~/.claude/commands/gsd/` as legacy command installation metadata, not skills.\n\n## Scanner Behavior\n\n### `sdk/src/query/skills.ts`\n\n- Returns a de-duplicated list of discovered skill names.\n- Scans project roots plus managed global roots.\n- Does not scan the deprecated import-only root.\n\n### `get-shit-done/bin/lib/profile-output.cjs`\n\n- Builds the project `CLAUDE.md` skills section.\n- Scans project roots only.\n- Skips `gsd-*` directories so the project section stays focused on user/project skills.\n- Adds `.codex/skills/` to the project discovery set.\n\n### `get-shit-done/bin/lib/init.cjs`\n\n- Generates the skill inventory object for `skill-manifest`.\n- Reports `skills`, `roots`, `installation`, and `counts`.\n- Marks `gsd_skills_installed` when any discovered skill name starts with `gsd-`.\n- Marks `legacy_claude_commands_installed` when `~/.claude/commands/gsd/` contains `.md` command files.\n\n## Inventory Shape\n\n`skill-manifest` returns a JSON object with:\n\n- `skills`: normalized skill entries\n- `roots`: the canonical roots that were checked\n- `installation`: summary booleans for installed GSD skills and legacy Claude commands\n- `counts`: small inventory counts for downstream consumers\n\nEach skill entry includes:\n\n- `name`\n- `description`\n- `triggers`\n- `path`\n- `file_path`\n- `root`\n- `scope`\n- `installed`\n- `deprecated`\n\n","isInternal":false,"tokens":648,"sizeBytes":2690},{"name":"checkpoints.md","path":"docs/zh-CN/references/checkpoints.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/checkpoints.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 检查点\n\n计划自主执行。检查点用于规范化需要人工验证或决策的交互点。\n\n**核心原则：** Claude 用 CLI/API 自动化一切。检查点用于验证和决策，而非手动工作。\n\n**黄金法则：**\n1. **如果 Claude 能运行，Claude 就运行** - 绝不让用户执行 CLI 命令、启动服务器或运行构建\n2. **Claude 设置验证环境** - 启动开发服务器、填充数据库、配置环境变量\n3. **用户只做需要人工判断的事** - 视觉检查、UX 评估、\"这个感觉对吗？\"\n4. **密钥来自用户，自动化来自 Claude** - 询问 API 密钥，然后 Claude 通过 CLI 使用它们\n5. **自动模式绕过验证/决策检查点** — 当 config 中 `workflow._auto_chain_active` 或 `workflow.auto_advance` 为 true 时：human-verify 自动批准，decision 自动选择第一个选项，human-action 仍会停止（认证门控无法自动化）\n\n## 检查点类型\n\n### checkpoint:human-verify（最常见 - 90%）\n\n**何时使用：** Claude 完成自动化工作，人工确认其正常工作。\n\n**用于：**\n- 视觉 UI 检查（布局、样式、响应式）\n- 交互流程（点击向导、测试用户流程）\n- 功能验证（功能按预期工作）\n- 音频/视频播放质量\n- 动画流畅度\n- 无障碍测试\n\n**结构：**\n```xml\n\n [Claude 自动化并部署/构建的内容]\n \n [测试的确切步骤 - URL、命令、预期行为]\n \n [如何继续 - \"approved\"、\"yes\" 或描述问题]\n\n```\n\n**示例：UI 组件（展示关键模式：Claude 在检查点之前启动服务器）**\n```xml\n\n 构建响应式仪表板布局\n src/components/Dashboard.tsx, src/app/dashboard/page.tsx\n 创建带侧边栏、标题和内容区域的仪表板。使用 Tailwind 响应式类处理移动端。\n npm run build 成功，无 TypeScript 错误\n 仪表板组件构建无错误\n\n\n\n 启动开发服务器用于验证\n 在后台运行 `npm run dev`，等待 \"ready\" 消息，捕获端口\n curl http://localhost:3000 返回 200\n 开发服务器运行于 http://localhost:3000\n\n\n\n 响应式仪表板布局 - 开发服务器运行于 http://localhost:3000\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 桌面端 (>1024px): 左侧边栏，右侧内容，顶部标题\n 2. 平板端 (768px): 侧边栏折叠为汉堡菜单\n 3. 移动端 (375px): 单列布局，出现底部导航\n 4. 任何尺寸无布局偏移或水平滚动\n \n 输入 \"approved\" 或描述布局问题\n\n```\n\n### checkpoint:decision（9%）\n\n**何时使用：** 人工必须做出影响实现方向的选择。\n\n**用于：**\n- 技术选型（哪个认证提供商、哪个数据库）\n- 架构决策（monorepo 还是独立仓库）\n- 设计选择（配色方案、布局方式）\n- 功能优先级（构建哪个变体）\n- 数据模型决策（模式结构）\n\n**结构：**\n```xml\n\n [正在决策的内容]\n [为什么这个决策重要]\n \n \n \n \n [如何表明选择]\n\n```\n\n**示例：认证提供商选择**\n```xml\n\n 选择认证提供商\n \n 应用需要用户认证。三个可靠选项各有权衡。\n \n \n \n \n \n \n 选择：supabase、clerk 或 nextauth\n\n```\n\n### checkpoint:human-action（1% - 罕见）\n\n**何时使用：** 操作没有 CLI/API 且需要仅人工交互，或者 Claude 在自动化过程中遇到认证门控。\n\n**仅用于：**\n- **认证门控** - Claude 尝试了 CLI/API 但需要凭证（这不是失败）\n- 邮箱验证链接（点击邮件）\n- 短信两步验证码（手机验证）\n- 人工账户审批（平台需要人工审核）\n- 信用卡 3D Secure 流程（基于 Web 的支付授权）\n- OAuth 应用审批（基于 Web 的审批）\n\n**不要用于预定的手动工作：**\n- 部署（使用 CLI - 如需要则认证门控）\n- 创建 webhooks/数据库（使用 API/CLI - 如需要则认证门控）\n- 运行构建/测试（使用 Bash 工具）\n- 创建文件（使用 Write 工具）\n\n**结构：**\n```xml\n\n [人工必须做什么 - Claude 已完成所有可自动化的]\n \n [Claude 已自动化的内容]\n [需要人工操作的一件事]\n \n [Claude 之后可以检查的内容]\n [如何继续]\n\n```\n\n**示例：认证门控（动态检查点）**\n```xml\n\n 部署到 Vercel\n .vercel/, vercel.json\n 运行 `vercel --yes` 进行部署\n vercel ls 显示部署，curl 返回 200\n\n\n\n\n\n 认证 Vercel CLI 以便我继续部署\n \n 我尝试部署但收到认证错误。\n 运行：vercel login\n 这将打开你的浏览器 - 完成认证流程。\n \n vercel whoami 返回你的账户邮箱\n 认证完成后输入 \"done\"\n\n\n\n\n\n 重试 Vercel 部署\n 运行 `vercel --yes`（已认证）\n vercel ls 显示部署，curl 返回 200\n\n```\n\n**关键区别：** 认证门控是 Claude 遇到认证错误时动态创建的。不是预定的 — Claude 先自动化，只有在被阻止时才请求凭证。\n\n## 执行协议\n\n当 Claude 遇到 `type=\"checkpoint:*\"` 时：\n\n1. **立即停止** - 不继续下一个任务\n2. **清晰显示检查点** 使用下面的格式\n3. **等待用户响应** - 不幻想完成\n4. **如可能则验证** - 检查文件、运行测试、任何指定的内容\n5. **恢复执行** - 仅在确认后继续下一个任务\n\n**对于 checkpoint:human-verify:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要验证 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 5/8 任务完成\n任务: 响应式仪表板布局\n\n已构建: /dashboard 的响应式仪表板\n\n如何验证:\n 1. 访问: http://localhost:3000/dashboard\n 2. 桌面端 (>1024px): 侧边栏可见，内容填充剩余空间\n 3. 平板端 (768px): 侧边栏折叠为图标\n 4. 移动端 (375px): 侧边栏隐藏，出现汉堡菜单\n\n────────────────────────────────────────────────────────\n→ 你的操作: 输入 \"approved\" 或描述问题\n────────────────────────────────────────────────────────\n```\n\n**对于 checkpoint:decision:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要决策 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 2/6 任务完成\n任务: 选择认证提供商\n\n决策: 我们应该使用哪个认证提供商？\n\n上下文: 需要用户认证。三个选项各有权衡。\n\n选项:\n 1. supabase - 与我们的数据库内置集成，免费额度\n 优点: 行级安全集成，慷慨的免费额度\n 缺点: UI 定制性较差，生态锁定\n\n 2. clerk - 最佳 DX，10k 用户后付费\n 优点: 精美的预构建 UI，优秀文档\n 缺点: 供应商锁定，规模化时价格问题\n\n 3. nextauth - 自托管，最大控制权\n 优点: 免费，无供应商锁定，广泛采用\n 缺点: 更多设置工作，自行 DIY 安全更新\n\n────────────────────────────────────────────────────────\n→ 你的操作: 选择 supabase、clerk 或 nextauth\n────────────────────────────────────────────────────────\n```\n\n## 认证门控\n\n**认证门控 = Claude 尝试了 CLI/API，收到认证错误。** 不是失败 — 是需要人工输入来解除阻止的门控。\n\n**模式：** Claude 尝试自动化 → 认证错误 → 创建 checkpoint:human-action → 用户认证 → Claude 重试 → 继续\n\n**门控协议：**\n1. 认识到这不是失败 - 缺少认证是正常的\n2. 停止当前任务 - 不要反复重试\n3. 动态创建 checkpoint:human-action\n4. 提供确切的认证步骤\n5. 验证认证有效\n6. 重试原始任务\n7. 正常继续\n\n**关键区别：**\n- 预定的检查点：\"我需要你做 X\"（错误 - Claude 应该自动化）\n- 认证门控：\"我尝试自动化 X 但需要凭证\"（正确 - 解除自动化阻止）\n\n## 自动化参考\n\n**规则：** 如果有 CLI/API，Claude 就做。绝不让人工执行可自动化的工作。\n\n### 服务 CLI 参考\n\n| 服务 | CLI/API | 关键命令 | 认证门控 |\n|------|---------|----------|----------|\n| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |\n| Railway | `railway` | `init`, `up`, `variables set` | `railway login` |\n| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` |\n| Stripe | `stripe` + API | `listen`, `trigger`, API 调用 | .env 中的 API key |\n| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` |\n| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` |\n| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` |\n| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |\n| Node | `npm`/`pnpm` | `install`, `run build`, `test`, `run dev` | N/A |\n| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |\n| Convex | `npx convex` | `dev`, `deploy`, `env set`, `env get` | `npx convex login` |\n\n### 环境变量自动化\n\n**Env 文件：** 使用 Write/Edit 工具。绝不让用户手动创建 .env。\n\n**通过 CLI 的仪表板环境变量：**\n\n| 平台 | CLI 命令 | 示例 |\n|------|----------|------|\n| Convex | `npx convex env set` | `npx convex env set OPENAI_API_KEY sk-...` |\n| Vercel | `vercel env add` | `vercel env add STRIPE_KEY production` |\n| Railway | `railway variables set` | `railway variables set API_KEY=value` |\n| Fly | `fly secrets set` | `fly secrets set DATABASE_URL=...` |\n| Supabase | `supabase secrets set` | `supabase secrets set MY_SECRET=value` |\n\n### 开发服务器自动化\n\n| 框架 | 启动命令 | 就绪信号 | 默认 URL |\n|------|----------|----------|----------|\n| Next.js | `npm run dev` | \"Ready in\" 或 \"started server\" | http://localhost:3000 |\n| Vite | `npm run dev` | \"ready in\" | http://localhost:5173 |\n| Convex | `npx convex dev` | \"Convex functions ready\" | N/A（仅后端）|\n| Express | `npm start` | \"listening on port\" | http://localhost:3000 |\n| Django | `python manage.py runserver` | \"Starting development server\" | http://localhost:8000 |\n\n**服务器生命周期：**\n```bash\n# 后台运行，捕获 PID\nnpm run dev &\nDEV_SERVER_PID=$!\n\n# 等待就绪（最多 30s）\ntimeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'\n```\n\n**端口冲突：** 终止陈旧进程（`lsof -ti:3000 | xargs kill`）或使用备用端口（`--port 3001`）。\n\n**服务器保持运行** 直到检查点结束。仅在计划完成、切换到生产环境或端口需要用于不同服务时终止。\n\n### CLI 安装处理\n\n| CLI | 自动安装？ | 命令 |\n|-----|------------|------|\n| npm/pnpm/yarn | 否 - 询问用户 | 用户选择包管理器 |\n| vercel | 是 | `npm i -g vercel` |\n| gh (GitHub) | 是 | `brew install gh` (macOS) 或 `apt install gh` (Linux) |\n| stripe | 是 | `npm i -g stripe` |\n| supabase | 是 | `npm i -g supabase` |\n| convex | 否 - 使用 npx | `npx convex`（无需安装）|\n| fly | 是 | `brew install flyctl` 或 curl 安装器 |\n| railway | 是 | `npm i -g @railway/cli` |\n\n**协议：** 尝试命令 → \"command not found\" → 可自动安装？→ 是：静默安装，重试 → 否：检查点请求用户安装。\n\n## 检查点前自动化失败处理\n\n| 失败 | 响应 |\n|------|------|\n| 服务器无法启动 | 检查错误，修复问题，重试（不进入检查点）|\n| 端口被占用 | 终止陈旧进程或使用备用端口 |\n| 缺少依赖 | 运行 `npm install`，重试 |\n| 构建错误 | 先修复错误（是 bug，不是检查点问题）|\n| 认证错误 | 创建认证门控检查点 |\n| 网络超时 | 带退避重试，如果持续则检查点 |\n\n**绝不呈现验证环境损坏的检查点。** 如果 `curl localhost:3000` 失败，不要让用户\"访问 localhost:3000\"。\n\n## 可自动化快速参考\n\n| 操作 | 可自动化？| Claude 做？|\n|------|------------|------------|\n| 部署到 Vercel | 是 (`vercel`) | 是 |\n| 创建 Stripe webhook | 是 (API) | 是 |\n| 写入 .env 文件 | 是 (Write 工具) | 是 |\n| 创建 Upstash DB | 是 (`upstash`) | 是 |\n| 运行测试 | 是 (`npm test`) | 是 |\n| 启动开发服务器 | 是 (`npm run dev`) | 是 |\n| 添加环境变量到 Convex | 是 (`npx convex env set`) | 是 |\n| 添加环境变量到 Vercel | 是 (`vercel env add`) | 是 |\n| 填充数据库 | 是 (CLI/API) | 是 |\n| 点击邮件验证链接 | 否 | 否 |\n| 输入带 3DS 的信用卡 | 否 | 否 |\n| 在浏览器中完成 OAuth | 否 | 否 |\n| 视觉验证 UI 是否正确 | 否 | 否 |\n| 测试交互式用户流程 | 否 | 否 |\n\n## 反模式\n\n### ❌ 错误：让用户启动开发服务器\n```xml\n\n 仪表板组件\n \n 1. 运行: npm run dev\n 2. 访问: http://localhost:3000/dashboard\n 3. 检查布局是否正确\n \n\n```\n**为什么错误：** Claude 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。\n\n### ✅ 正确：Claude 启动服务器，用户访问\n```xml\n\n 启动开发服务器\n 在后台运行 `npm run dev`\n curl localhost:3000 返回 200\n\n\n\n http://localhost:3000/dashboard 的仪表板（服务器运行中）\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 布局匹配设计\n 2. 无控制台错误\n \n\n```\n\n### ❌ 错误：让用户部署 / ✅ 正确：Claude 自动化\n```xml\n\n\n 部署到 Vercel\n 访问 vercel.com/new → 导入仓库 → 点击部署 → 复制 URL\n\n\n\n\n 部署到 Vercel\n 运行 `vercel --yes`。捕获 URL。\n vercel ls 显示部署，curl 返回 200\n\n\n\n 已部署到 {url}\n 访问 {url}，检查首页加载\n 输入 \"approved\"\n\n```\n\n## 摘要\n\n检查点规范化人工介入点用于验证和决策，而非手动工作。\n\n**黄金法则：** 如果 Claude 能自动化它，Claude 就必须自动化它。\n\n**检查点优先级：**\n1. **checkpoint:human-verify**（90%）- Claude 自动化一切，人工确认视觉/功能正确性\n2. **checkpoint:decision**（9%）- 人工做出架构/技术选择\n3. **checkpoint:human-action**（1%）- 真正无法避免的、没有 API/CLI 的手动步骤\n\n**何时不用检查点：**\n- Claude 可以编程验证的事情（测试、构建）\n- 文件操作（Claude 可以读取文件）\n- 代码正确性（测试和静态分析）\n- 任何可通过 CLI/API 自动化的内容","isInternal":false,"tokens":5925,"sizeBytes":18073},{"name":"continuation-format.md","path":"docs/zh-CN/references/continuation-format.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/continuation-format.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 续接格式\n\n完成命令或工作流后展示下一步的标准格式。\n\n## 核心结构\n\n```\n---\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `{备选项 1}` — 描述\n- `{备选项 2}` — 描述\n\n---\n```\n\n## 格式规则\n\n1. **始终展示它是什么** — 名称 + 描述，绝不仅仅是一个命令路径\n2. **从源文件拉取上下文** — ROADMAP.md 用于阶段，PLAN.md `` 用于计划\n3. **命令用内联代码** — 反引号，易于复制粘贴，渲染为可点击链接\n4. **`/clear` 说明** — 始终包含，保持简洁但解释原因\n5. **用\"也可选\"而非\"其他选项\"** — 听起来更像应用\n6. **视觉分隔符** — 上下用 `---` 使其突出\n\n## 变体\n\n### 执行下一个计划\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- 执行前审查计划\n- `/gsd-discuss-phase --assumptions 2` — 检查假设\n\n---\n```\n\n### 执行阶段中最后一个计划\n\n添加注释说明这是最后一个计划以及接下来是什么：\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n阶段 2 的最后一个计划\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**完成后：**\n- 阶段 2 → 阶段 3 过渡\n- 下一步：**阶段 3: 核心功能** — 用户仪表板和设置\n\n---\n```\n\n### 规划阶段\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程\n\n`/gsd-plan-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 2` — 先收集上下文\n- `/gsd-plan-phase --research-phase 2` — 调查未知项\n- 审查路线图\n\n---\n```\n\n### 阶段完成，准备下一步\n\n在下一步操作前显示完成状态：\n\n```\n---\n\n## ✓ 阶段 2 完成\n\n3/3 计划已执行\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n`/gsd-plan-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 3` — 先收集上下文\n- `/gsd-plan-phase --research-phase 3` — 调查未知项\n- 回顾阶段 2 构建的内容\n\n---\n```\n\n### 多个同等选项\n\n当没有明确的主要操作时：\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n**直接规划：** `/gsd-plan-phase 3`\n\n**先讨论上下文：** `/gsd-discuss-phase 3`\n\n**研究未知项：** `/gsd-plan-phase --research-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n### 里程碑完成\n\n```\n---\n\n## 🎉 里程碑 v1.0 完成\n\n全部 4 个阶段已发布\n\n## ▶ 下一步\n\n**开始 v1.1** — 提问 → 研究 → 需求 → 路线图\n\n`/gsd-new-milestone`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n## 拉取上下文\n\n### 用于阶段（从 ROADMAP.md）：\n\n```markdown\n### 阶段 2: 认证\n**目标**: 带刷新令牌的 JWT 登录流程\n```\n\n提取：`**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程`\n\n### 用于计划（从 ROADMAP.md）：\n\n```markdown\n计划:\n- [ ] 02-03: 添加刷新令牌轮换\n```\n\n或从 PLAN.md ``：\n\n```xml\n\n添加带滑动过期窗口的刷新令牌轮换。\n\n目的: 在不影响安全性的前提下延长会话生命周期。\n\n```\n\n提取：`**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh`\n\n## 反模式\n\n### 不要：仅命令（无上下文）\n\n```\n## 继续\n\n运行 `/clear`，然后粘贴：\n/gsd-execute-phase 2\n```\n\n用户不知道 02-03 是关于什么的。\n\n### 不要：缺少 /clear 说明\n\n```\n`/gsd-plan-phase 3`\n\n先运行 /clear。\n```\n\n没有解释原因。用户可能跳过。\n\n### 不要：\"其他选项\" 措辞\n\n```\n其他选项：\n- 审查路线图\n```\n\n听起来像是事后补充。用\"也可选：\"替代。\n\n### 不要：用围栏代码块展示命令\n\n```\n```\n/gsd-plan-phase 3\n```\n```\n\n模板内的围栏代码块会造成嵌套歧义。用内联反引号替代。","isInternal":false,"tokens":1655,"sizeBytes":4282},{"name":"decimal-phase-calculation.md","path":"docs/zh-CN/references/decimal-phase-calculation.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/decimal-phase-calculation.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 小数阶段计算\n\n为紧急插入计算下一个小数阶段编号。\n\n## 使用 gsd-sdk query\n\n```bash\n# 获取阶段 6 之后的下一个小数阶段\ngsd-sdk query phase.next-decimal 6\n```\n\n输出：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.1\",\n \"existing\": []\n}\n```\n\n已有小数时：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.3\",\n \"existing\": [\"06.1\", \"06.2\"]\n}\n```\n\n## 提取值\n\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick next)\nBASE_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick base_phase)\n```\n\n或使用 --raw 标志：\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --raw)\n# 返回: 06.1\n```\n\n## 示例\n\n| 已有阶段 | 下一个阶段 |\n|----------|------------|\n| 仅 06 | 06.1 |\n| 06, 06.1 | 06.2 |\n| 06, 06.1, 06.2 | 06.3 |\n| 06, 06.1, 06.3（有空缺）| 06.4 |\n\n## 目录命名\n\n小数阶段目录使用完整的小数编号：\n\n```bash\nSLUG=$(gsd-sdk query generate-slug \"$DESCRIPTION\" --raw)\nPHASE_DIR=\".planning/phases/${DECIMAL_PHASE}-${SLUG}\"\nmkdir -p \"$PHASE_DIR\"\n```\n\n示例：`.planning/phases/06.1-fix-critical-auth-bug/`\n","isInternal":false,"tokens":430,"sizeBytes":1182},{"name":"git-integration.md","path":"docs/zh-CN/references/git-integration.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/git-integration.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"\nGSD 框架的 Git 集成。\n\n\n\n\n**提交结果，而非过程。**\n\ngit 日志应该读起来像是发布内容的变更日志，而不是规划活动的日记。\n\n\n\n\n| 事件 | 提交? | 原因 |\n| ----------------------- | ------- | ------------------------------------------------ |\n| BRIEF + ROADMAP 创建 | 是 | 项目初始化 |\n| PLAN.md 创建 | 否 | 中间产物 - 与计划完成一起提交 |\n| RESEARCH.md 创建 | 否 | 中间产物 |\n| DISCOVERY.md 创建 | 否 | 中间产物 |\n| **任务完成** | 是 | 原子工作单元（每个任务 1 个提交） |\n| **计划完成** | 是 | 元数据提交（SUMMARY + STATE + ROADMAP） |\n| 交接创建 | 是 | WIP 状态保留 |\n\n\n\n\n\n```bash\n[ -d .git ] && echo \"GIT_EXISTS\" || echo \"NO_GIT\"\n```\n\n如果 NO_GIT：静默运行 `git init`。GSD 项目总是有自己的仓库。\n\n\n\n\n\n## 项目初始化（brief + roadmap 一起）\n\n```\ndocs: initialize [project-name] ([N] phases)\n\n[PROJECT.md 中的一句话描述]\n\nPhases:\n1. [phase-name]: [goal]\n2. [phase-name]: [goal]\n3. [phase-name]: [goal]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs: initialize [project-name] ([N] phases)\" --files .planning/\n```\n\n\n\n\n## 任务完成（计划执行期间）\n\n每个任务在完成后立即获得自己的提交。\n\n```\n{type}({phase}-{plan}): {task-name}\n\n- [关键变更 1]\n- [关键变更 2]\n- [关键变更 3]\n```\n\n**提交类型：**\n- `feat` - 新功能/功能\n- `fix` - Bug 修复\n- `test` - 仅测试（TDD RED 阶段）\n- `refactor` - 代码清理（TDD REFACTOR 阶段）\n- `perf` - 性能改进\n- `chore` - 依赖、配置、工具\n\n**示例：**\n\n```bash\n# 标准任务\ngit add src/api/auth.ts src/types/user.ts\ngit commit -m \"feat(08-02): create user registration endpoint\n\n- POST /auth/register validates email and password\n- Checks for duplicate users\n- Returns JWT token on success\n\"\n\n# TDD 任务 - RED 阶段\ngit add src/__tests__/jwt.test.ts\ngit commit -m \"test(07-02): add failing test for JWT generation\n\n- Tests token contains user ID claim\n- Tests token expires in 1 hour\n- Tests signature verification\n\"\n\n# TDD 任务 - GREEN 阶段\ngit add src/utils/jwt.ts\ngit commit -m \"feat(07-02): implement JWT generation\n\n- Uses jose library for signing\n- Includes user ID and expiry claims\n- Signs with HS256 algorithm\n\"\n```\n\n\n\n\n## 计划完成（所有任务完成后）\n\n所有任务提交后，最后一个元数据提交捕获计划完成。\n\n```\ndocs({phase}-{plan}): complete [plan-name] plan\n\nTasks completed: [N]/[N]\n- [Task 1 name]\n- [Task 2 name]\n- [Task 3 name]\n\nSUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs({phase}-{plan}): complete [plan-name] plan\" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md\n```\n\n**注意：** 代码文件不包含 - 已按任务提交。\n\n\n\n\n## 交接（WIP）\n\n```\nwip: [phase-name] paused at task [X]/[Y]\n\nCurrent: [task name]\n[如果阻塞:] Blocked: [reason]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"wip: [phase-name] paused at task [X]/[Y]\" --files .planning/\n```\n\n\n\n\n\n\n**旧方法（每个计划提交）：**\n```\na7f2d1 feat(checkout): Stripe payments with webhook verification\n3e9c4b feat(products): catalog with search, filters, and pagination\n8a1b2c feat(auth): JWT with refresh rotation using jose\n5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold\n2f4a8d docs: initialize ecommerce-app (5 phases)\n```\n\n**新方法（每个任务提交）：**\n```\n# Phase 04 - Checkout\n1a2b3c docs(04-01): complete checkout flow plan\n4d5e6f feat(04-01): add webhook signature verification\n7g8h9i feat(04-01): implement payment session creation\n0j1k2l feat(04-01): create checkout page component\n\n# Phase 03 - Products\n3m4n5o docs(03-02): complete product listing plan\n6p7q8r feat(03-02): add pagination controls\n9s0t1u feat(03-02): implement search and filters\n2v3w4x feat(03-01): create product catalog schema\n\n# Phase 02 - Auth\n5y6z7a docs(02-02): complete token refresh plan\n8b9c0d feat(02-02): implement refresh token rotation\n1e2f3g test(02-02): add failing test for token refresh\n4h5i6j docs(02-01): complete JWT setup plan\n7k8l9m feat(02-01): add JWT generation and validation\n0n1o2p chore(02-01): install jose library\n\n# Phase 01 - Foundation\n3q4r5s docs(01-01): complete scaffold plan\n6t7u8v feat(01-01): configure Tailwind and globals\n9w0x1y feat(01-01): set up Prisma with database\n2z3a4b feat(01-01): create Next.js 15 project\n\n# Initialization\n5c6d7e docs: initialize ecommerce-app (5 phases)\n```\n\n每个计划产生 2-4 个提交（任务 + 元数据）。清晰、细粒度、可 bisect。\n\n\n\n\n\n**仍不要提交（中间产物）：**\n- PLAN.md 创建（与计划完成一起提交）\n- RESEARCH.md（中间产物）\n- DISCOVERY.md（中间产物）\n- 小的规划调整\n- \"Fixed typo in roadmap\"\n\n**要提交（结果）：**\n- 每个任务完成（feat/fix/test/refactor）\n- 计划完成元数据（docs）\n- 项目初始化（docs）\n\n**关键原则：** 提交可工作的代码和已发布的结果，而非规划过程。\n\n\n\n\n\n## 为什么使用每任务提交？\n\n**AI 上下文工程：**\n- Git 历史成为未来 Claude 会话的主要上下文源\n- `git log --grep=\"{phase}-{plan}\"` 显示计划的所有工作\n- `git diff ^..` 显示每个任务的确切变更\n- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作\n\n**失败恢复：**\n- 任务 1 已提交 ✅，任务 2 失败 ❌\n- 下次会话中的 Claude：看到任务 1 完成，可以重试任务 2\n- 可以 `git reset --hard` 到最后一个成功的任务\n\n**调试：**\n- `git bisect` 找到确切的失败任务，而不仅仅是失败计划\n- `git blame` 将行追溯到特定任务上下文\n- 每个提交独立可回滚\n\n**可观察性：**\n- 独立开发者 + Claude 工作流受益于细粒度归因\n- 原子提交是 git 最佳实践\n- 当消费者是 Claude 而非人类时，\"提交噪音\"无关紧要\n\n","isInternal":false,"tokens":2080,"sizeBytes":6450},{"name":"git-planning-commit.md","path":"docs/zh-CN/references/git-planning-commit.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/git-planning-commit.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Git 规划提交\n\n通过 `gsd-sdk query commit` 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态（与旧版 `gsd-tools.cjs commit` 行为相同）。\n\n## 通过 CLI 提交\n\n先传提交说明，然后用 `--files` 显式传入文件路径。`commit` 与 `commit-to-subrepo` 都应使用 `--files` 来声明要提交的路径。\n\n对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查：\n\n```bash\ngsd-sdk query commit \"docs({scope}): {description}\" --files .planning/STATE.md .planning/ROADMAP.md\n```\n\n如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。\n\n## 修改上次提交\n\n将 `.planning/` 文件变更合并到上次提交：\n\n```bash\ngsd-sdk query commit \"\" --files .planning/codebase/*.md --amend\n```\n\n## 提交消息模式\n\n| 命令 | 范围 | 示例 |\n|------|------|------|\n| plan-phase | phase | `docs(phase-03): create authentication plans` |\n| execute-phase | phase | `docs(phase-03): complete authentication phase` |\n| new-milestone | milestone | `docs: start milestone v1.1` |\n| remove-phase | chore | `chore: remove phase 17 (dashboard)` |\n| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |\n| add-phase | phase | `docs: add phase 07 (settings page)` |\n\n## 何时跳过\n\n- config 中 `commit_docs: false`\n- `.planning/` 被 gitignore\n- 无变更可提交（用 `git status --porcelain .planning/` 检查）\n","isInternal":false,"tokens":466,"sizeBytes":1508},{"name":"model-profile-resolution.md","path":"docs/zh-CN/references/model-profile-resolution.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/model-profile-resolution.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 模型配置解析\n\n在编排开始时解析一次模型配置，然后在所有 Task 生成时使用。\n\n## 解析模式\n\n```bash\nMODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '\"model_profile\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | grep -o '\"[^\"]*\"$' | tr -d '\"' || echo \"balanced\")\n```\n\n默认值：未设置或缺少 config 时为 `balanced`。\n\n## 查找表\n\n@~/.claude/get-shit-done/references/model-profiles.md\n\n在表中查找已解析配置对应的代理。将 model 参数传递给 Task 调用：\n\n```\nTask(\n prompt=\"...\",\n subagent_type=\"gsd-planner\",\n model=\"{resolved_model}\" # \"inherit\"、\"sonnet\" 或 \"haiku\"\n)\n```\n\n**注意：** Opus 级代理解析为 `\"inherit\"`（而非 `\"opus\"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。\n\n## 使用方法\n\n1. 在编排开始时解析一次\n2. 存储 profile 值\n3. 生成时在表中查找每个代理的模型\n4. 将 model 参数传递给每个 Task 调用（值：`\"inherit\"`、`\"sonnet\"`、`\"haiku\"`）","isInternal":false,"tokens":357,"sizeBytes":1047},{"name":"model-profiles.md","path":"docs/zh-CN/references/model-profiles.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/model-profiles.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 模型配置\n\n模型配置控制每个 GSD 代理使用哪个 Claude 模型。这允许平衡质量和 token 消耗。\n\n## 配置定义\n\n| 代理 | `quality` | `balanced` | `budget` |\n|-------|-----------|------------|----------|\n| gsd-planner | opus | opus | sonnet |\n| gsd-roadmapper | opus | sonnet | sonnet |\n| gsd-executor | opus | sonnet | sonnet |\n| gsd-phase-researcher | opus | sonnet | haiku |\n| gsd-project-researcher | opus | sonnet | haiku |\n| gsd-research-synthesizer | sonnet | sonnet | haiku |\n| gsd-debugger | opus | sonnet | sonnet |\n| gsd-codebase-mapper | sonnet | haiku | haiku |\n| gsd-verifier | sonnet | sonnet | haiku |\n| gsd-plan-checker | sonnet | sonnet | haiku |\n| gsd-integration-checker | sonnet | sonnet | haiku |\n| gsd-nyquist-auditor | sonnet | sonnet | haiku |\n\n## 配置理念\n\n**quality** - 最大推理能力\n- 所有决策代理使用 Opus\n- 只读验证使用 Sonnet\n- 适用场景：有配额可用、关键架构工作\n\n**balanced**（默认）- 智能分配\n- 仅规划（架构决策发生的地方）使用 Opus\n- 执行和研究使用 Sonnet（遵循明确指令）\n- 验证使用 Sonnet（需要推理，不仅仅是模式匹配）\n- 适用场景：正常开发、质量与成本的良好平衡\n\n**budget** - 最小化 Opus 使用\n- 编写代码的使用 Sonnet\n- 研究和验证使用 Haiku\n- 适用场景：节省配额、大量工作、不太关键的阶段\n\n## 解析逻辑\n\n编排器在生成代理前解析模型：\n\n```\n1. 读取 .planning/config.json\n2. 检查 model_overrides 是否有代理特定覆盖\n3. 如果没有覆盖，在配置表中查找代理\n4. 将 model 参数传递给 Task 调用\n```\n\n## 单代理覆盖\n\n覆盖特定代理而不更改整个配置：\n\n```json\n{\n \"model_profile\": \"balanced\",\n \"model_overrides\": {\n \"gsd-executor\": \"opus\",\n \"gsd-planner\": \"haiku\"\n }\n}\n```\n\n覆盖优先于配置。有效值：`opus`、`sonnet`、`haiku`。\n\n## 切换配置\n\n在 `.planning/config.json` 中设置 `model_profile` 键以更改配置文件。\n\n项目默认值：在 `.planning/config.json` 中设置：\n```json\n{\n \"model_profile\": \"balanced\"\n}\n```\n\n## 设计理由\n\n**为什么 gsd-planner 使用 Opus？**\n规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。\n\n**为什么 gsd-executor 使用 Sonnet？**\n执行者遵循明确的 PLAN.md 指令。计划已包含推理；执行只是实现。\n\n**为什么 balanced 中验证器使用 Sonnet（而非 Haiku）？**\n验证需要目标回溯推理 —— 检查代码是否**交付**了阶段承诺的内容，而不仅仅是模式匹配。Sonnet 处理得很好；Haiku 可能会遗漏细微的差距。\n\n**为什么 gsd-codebase-mapper 使用 Haiku？**\n只读探索和模式提取。不需要推理，只需从文件内容输出结构化结果。\n\n**为什么用 `inherit` 而不是直接传递 `opus`？**\nClaude Code 的 `\"opus\"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。GSD 为 opus 级代理返回 `\"inherit\"`，使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。","isInternal":false,"tokens":1118,"sizeBytes":3149},{"name":"phase-argument-parsing.md","path":"docs/zh-CN/references/phase-argument-parsing.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/phase-argument-parsing.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 阶段参数解析\n\n为操作阶段的命令解析和规范化阶段参数。\n\n## 提取\n\n从 `$ARGUMENTS` 中：\n- 提取阶段编号（第一个数字参数）\n- 提取标志（以 `--` 为前缀）\n- 剩余文本为描述（用于 insert/add 命令）\n\n## 使用 gsd-tools\n\n`find-phase` 命令一步完成规范化和验证：\n\n```bash\nPHASE_INFO=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\")\n```\n\n返回 JSON 包含：\n- `found`: true/false\n- `directory`: 阶段目录的完整路径\n- `phase_number`: 规范化的编号（如 \"06\"、\"06.1\"）\n- `phase_name`: 名称部分（如 \"foundation\"）\n- `plans`: PLAN.md 文件数组\n- `summaries`: SUMMARY.md 文件数组\n\n## 手动规范化（遗留）\n\n将整数阶段补零到 2 位。保留小数后缀。\n\n```bash\n# 规范化阶段编号\nif [[ \"$PHASE\" =~ ^[0-9]+$ ]]; then\n # 整数: 8 → 08\n PHASE=$(printf \"%02d\" \"$PHASE\")\nelif [[ \"$PHASE\" =~ ^([0-9]+)\\.([0-9]+)$ ]]; then\n # 小数: 2.1 → 02.1\n PHASE=$(printf \"%02d.%s\" \"${BASH_REMATCH[1]}\" \"${BASH_REMATCH[2]}\")\nfi\n```\n\n## 验证\n\n使用 `roadmap get-phase` 验证阶段存在：\n\n```bash\nPHASE_CHECK=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" roadmap get-phase \"${PHASE}\")\nif [ \"$(printf '%s\\n' \"$PHASE_CHECK\" | jq -r '.found')\" = \"false\" ]; then\n echo \"ERROR: Phase ${PHASE} not found in roadmap\"\n exit 1\nfi\n```\n\n## 目录查找\n\n使用 `find-phase` 进行目录查找：\n\n```bash\nPHASE_DIR=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\" --raw)\n```","isInternal":false,"tokens":554,"sizeBytes":1543},{"name":"planning-config.md","path":"docs/zh-CN/references/planning-config.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/planning-config.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"\n\n`.planning/` 目录行为的配置选项。\n\n\n```json\n\"planning\": {\n \"commit_docs\": true,\n \"search_gitignored\": false\n},\n\"git\": {\n \"branching_strategy\": \"none\",\n \"phase_branch_template\": \"gsd/phase-{phase}-{slug}\",\n \"milestone_branch_template\": \"gsd/{milestone}-{slug}\"\n}\n```\n\n| 选项 | 默认值 | 描述 |\n|--------|---------|-------------|\n| `commit_docs` | `true` | 是否将规划工件提交到 git |\n| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` |\n| `git.branching_strategy` | `\"none\"` | Git 分支策略：`\"none\"`、`\"phase\"` 或 `\"milestone\"` |\n| `git.phase_branch_template` | `\"gsd/phase-{phase}-{slug}\"` | 阶段策略的分支模板 |\n| `git.milestone_branch_template` | `\"gsd/{milestone}-{slug}\"` | 里程碑策略的分支模板 |\n\n\n\n\n**当 `commit_docs: true`（默认）：**\n- 规划文件正常提交\n- SUMMARY.md、STATE.md、ROADMAP.md 在 git 中跟踪\n- 规划决策的完整历史保留\n\n**当 `commit_docs: false`：**\n- 跳过 `.planning/` 文件的所有 `git add`/`git commit`\n- 用户必须将 `.planning/` 添加到 `.gitignore`\n- 适用于：OSS 贡献、客户项目、保持规划私有\n\n**使用 `gsd-sdk query`（推荐）：**\n\n```bash\n# 提交时自动检查 commit_docs + gitignore：\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n\n# 通过 state load 加载配置（返回 JSON）：\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 在 JSON 输出中可用\n\n# 或使用包含 commit_docs 的 init 命令：\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 包含在所有 init 命令输出中\n```\n\n**自动检测：** 如果 `.planning/` 被 gitignore，无论 config.json 如何，`commit_docs` 自动为 `false`。这防止用户在 `.gitignore` 中有 `.planning/` 时出现 git 错误。\n\n**通过 CLI 提交（自动处理检查）：**\n\n```bash\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n```\n\nCLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。\n\n\n\n\n\n**当 `search_gitignored: false`（默认）：**\n- 标准 rg 行为（尊重 .gitignore）\n- 直接路径搜索有效：`rg \"pattern\" .planning/` 找到文件\n- 广泛搜索跳过 gitignored：`rg \"pattern\"` 跳过 `.planning/`\n\n**当 `search_gitignored: true`:**\n- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore`\n- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要\n\n**注意：** 大多数 GSD 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都有效。\n\n\n\n\n\n使用未提交模式：\n\n1. **设置配置：**\n ```json\n \"planning\": {\n \"commit_docs\": false,\n \"search_gitignored\": true\n }\n ```\n\n2. **添加到 .gitignore：**\n ```\n .planning/\n ```\n\n3. **已存在的跟踪文件：** 如果 `.planning/` 之前被跟踪：\n ```bash\n git rm -r --cached .planning/\n git commit -m \"chore: stop tracking planning docs\"\n ```\n\n4. **分支合并：** 当使用 `branching_strategy: phase` 或 `milestone` 时，`complete-milestone` 工作流在 `commit_docs: false` 时自动从暂存区移除 `.planning/` 文件，然后才进行合并提交。\n\n\n\n\n\n**分支策略：**\n\n| 策略 | 创建分支时机 | 分支范围 | 合并点 |\n|----------|---------------------|--------------|-------------|\n| `none` | 从不 | N/A | N/A |\n| `phase` | `execute-phase` 开始时 | 单个阶段 | 阶段后用户手动合并 |\n| `milestone` | 里程碑第一个 `execute-phase` | 整个里程碑 | `complete-milestone` 时 |\n\n**当 `git.branching_strategy: \"none\"`（默认）：**\n- 所有工作提交到当前分支\n- 标准 GSD 行为\n\n**当 `git.branching_strategy: \"phase\"`：**\n- `execute-phase` 在执行前创建/切换到分支\n- 分支名来自 `phase_branch_template`（如 `gsd/phase-03-authentication`）\n- 所有计划提交到该分支\n- 阶段完成后用户手动合并分支\n- `complete-milestone` 提供合并所有阶段分支的选项\n\n**当 `git.branching_strategy: \"milestone\"`：**\n- 里程碑的第一个 `execute-phase` 创建里程碑分支\n- 分支名来自 `milestone_branch_template`（如 `gsd/v1.0-mvp`）\n- 里程碑中所有阶段提交到同一分支\n- `complete-milestone` 提供将里程碑分支合并到 main 的选项\n\n**模板变量：**\n\n| 变量 | 可用于 | 描述 |\n|----------|--------------|-------------|\n| `{phase}` | phase_branch_template | 零填充阶段号（如 \"03\"） |\n| `{slug}` | 两者 | 小写、连字符名称 |\n| `{milestone}` | milestone_branch_template | 里程碑版本（如 \"v1.0\"） |\n\n**检查配置：**\n\n使用 `init execute-phase` 返回所有配置为 JSON：\n```bash\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n或使用 `state load` 获取配置值：\n```bash\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n**分支创建：**\n\n```bash\n# 阶段策略\nif [ \"$BRANCHING_STRATEGY\" = \"phase\" ]; then\n PHASE_SLUG=$(echo \"$PHASE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$PHASE_BRANCH_TEMPLATE\" | sed \"s/{phase}/$PADDED_PHASE/g\" | sed \"s/{slug}/$PHASE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n\n# 里程碑策略\nif [ \"$BRANCHING_STRATEGY\" = \"milestone\" ]; then\n MILESTONE_SLUG=$(echo \"$MILESTONE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$MILESTONE_BRANCH_TEMPLATE\" | sed \"s/{milestone}/$MILESTONE_VERSION/g\" | sed \"s/{slug}/$MILESTONE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n```\n\n**complete-milestone 时的合并选项：**\n\n| 选项 | Git 命令 | 结果 |\n|--------|-------------|--------|\n| Squash 合并（推荐） | `git merge --squash` | 每个分支单个干净提交 |\n| 带历史合并 | `git merge --no-ff` | 保留所有单独提交 |\n| 不合并直接删除 | `git branch -D` | 丢弃分支工作 |\n| 保留分支 | （无） | 后续手动处理 |\n\n推荐 Squash 合并 —— 保持 main 分支历史干净，同时在分支中保留完整开发历史（直到删除）。\n\n**使用场景：**\n\n| 策略 | 最适合 |\n|----------|----------|\n| `none` | 独立开发、简单项目 |\n| `phase` | 每阶段代码审查、细粒度回滚、团队协作 |\n| `milestone` | 发布分支、预发布环境、每个版本一个 PR |\n\n\n\n","isInternal":false,"tokens":2338,"sizeBytes":7081},{"name":"questioning.md","path":"docs/zh-CN/references/questioning.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/questioning.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 提问指南\n\n项目初始化是梦想提取，而非需求收集。你在帮助用户发现和表达他们想构建的内容。这不是合同谈判 —— 是协作思考。\n\n## 理念\n\n**你是思考伙伴，不是面试官。**\n\n用户通常有一个模糊的想法。你的工作是帮助他们将其锐化。问一些让他们思考\"哦，我没想到那个\"或\"是的，这正是我的意思\"的问题。\n\n不要审问。协作。不要照本宣科。顺藤摸瓜。\n\n## 目标\n\n到提问结束时，你需要足够的清晰度来编写下游阶段可执行的 PROJECT.md：\n\n- **研究** 需要：研究什么领域、用户已知什么、存在哪些未知\n- **需求** 需要：足够清晰的愿景来界定 v1 功能\n- **路线图** 需要：足够清晰的愿景来分解为阶段、\"完成\"是什么样子\n- **plan-phase** 需要：可分解为任务的具体需求、实现选择的上下文\n- **execute-phase** 需要：可验证的成功标准、需求背后的\"为什么\"\n\n模糊的 PROJECT.md 会让每个下游阶段都在猜测。成本会叠加。\n\n## 如何提问\n\n**开放开始。** 让他们倾倒心理模型。不要用结构打断。\n\n**跟随能量。** 无论他们强调什么，深入那个。什么让他们兴奋？什么问题引发了这一切？\n\n**挑战模糊。** 绝不接受模糊回答。\"好\"意味着什么？\"用户\"指谁？\"简单\"是怎么简单？\n\n**让抽象具体。**\"带我走一遍使用这个。\"\"那实际看起来是什么样？\"\n\n**澄清歧义。**\"你说 Z 时，是指 A 还是 B？\"\"你提到了 X —— 跟我多说说。\"\n\n**知道何时停止。** 当你理解他们想要什么、为什么想要、给谁用、完成是什么样 —— 提议继续。\n\n## 问题类型\n\n以此作为灵感，不是清单。选择与话题相关的。\n\n**动机 —— 为什么存在：**\n- \"什么引发了这一切？\"\n- \"你今天在做什么会被这个替代？\"\n- \"如果这个存在，你会做什么？\"\n\n**具体性 —— 它实际是什么：**\n- \"带我走一遍使用这个\"\n- \"你说 X —— 那实际看起来是什么样？\"\n- \"给我一个例子\"\n\n**澄清 —— 他们什么意思：**\n- \"你说 Z 时，是指 A 还是 B？\"\n- \"你提到了 X —— 跟我多说说那个\"\n\n**成功 —— 你怎么知道它在工作：**\n- \"你怎么知道这个在工作？\"\n- \"完成是什么样子？\"\n\n## 使用 AskUserQuestion\n\n用 AskUserQuestion 帮助用户思考，通过呈现具体的选项供他们反应。\n\n**好选项：**\n- 他们可能意思的解读\n- 确认或否认的具体例子\n- 揭示优先级的具体选择\n\n**坏选项：**\n- 泛泛的类别（\"技术\"、\"业务\"、\"其他\"）\n- 预设答案的引导性选项\n- 选项太多（2-4 个理想）\n- 超过 12 个字符的标题（硬限制 —— 验证会拒绝）\n\n**示例 —— 模糊回答：**\n用户说\"它应该快\"\n\n- header: \"快\"\n- question: \"快是指？\"\n- options: [\"亚秒响应\", \"处理大数据集\", \"快速构建\", \"让我解释\"]\n\n**示例 —— 跟随话题：**\n用户提到\"对当前工具感到沮丧\"\n\n- header: \"沮丧\"\n- question: \"具体什么让你沮丧？\"\n- options: [\"点击太多\", \"缺少功能\", \"不可靠\", \"让我解释\"]\n\n**给用户的提示 —— 修改选项：**\n想要稍微修改某个选项版本的用户可以选择\"Other\"并通过编号引用选项：`#1 但仅用于指关节` 或 `#2 禁用分页`。这避免重新输入完整选项文本。\n\n## 自由格式规则\n\n**当用户想自由解释时，停止使用 AskUserQuestion。**\n\n如果用户选择\"Other\"且他们的回应表明他们想用自己的话描述（如\"让我描述一下\"、\"我来解释\"、\"别的\"、或任何非选择/修改现有选项的开放式回复），你必须：\n\n1. **用纯文本问你的追问** — 不通过 AskUserQuestion\n2. **等待他们在正常提示符下输入**\n3. **仅在处理他们的自由格式回应后恢复 AskUserQuestion**\n\n同样适用于如果你包含一个表明自由格式的选项（如\"让我解释\"或\"详细描述\"）且用户选择了它。\n\n**错误：** 用户说\"让我描述一下\" → AskUserQuestion(\"什么功能？\", [\"功能 A\", \"功能 B\", \"详细描述\"])\n**正确：** 用户说\"让我描述一下\" → \"请讲 —— 你在想什么？\"\n\n## 上下文清单\n\n以此作为**背景清单**，而非对话结构。进行时在脑中检查这些。如果还有缺口，自然地穿插问题。\n\n- [ ] 他们在构建什么（足够具体可以向陌生人解释）\n- [ ] 为什么它需要存在（驱动它的问题或渴望）\n- [ ] 给谁用的（即使只是他们自己）\n- [ ] \"完成\"是什么样子（可观察的结果）\n\n四件事。如果他们主动提供更多，捕获它。\n\n## 决策门控\n\n当你能写出清晰的 PROJECT.md 时，提议继续：\n\n- header: \"准备好了？\"\n- question: \"我想我理解你想要什么了。准备创建 PROJECT.md 吗？\"\n- options:\n - \"创建 PROJECT.md\" — 让我们继续\n - \"继续探索\" — 我想分享更多 / 再问我\n\n如果\"继续探索\" —— 问他们想添加什么或识别缺口并自然探查。\n\n循环直到选择\"创建 PROJECT.md\"。\n\n## 反模式\n\n- **走清单** — 不管他们说什么都按领域走\n- **套话问题** — \"你的核心价值是什么？\"\"什么超出范围？\"不管上下文\n- **企业腔** — \"你的成功标准是什么？\"\"你的利益相关者是谁？\"\n- **审问** — 不基于回答构建就连续发问\n- **急于求成** — 最小化问题以开始\"实际工作\"\n- **浅层接受** — 不探查就接受模糊回答\n- **过早约束** — 还不理解想法就问技术栈\n- **用户技能** — 绝不问用户的技术经验。Claude 来构建。","isInternal":false,"tokens":2173,"sizeBytes":5685},{"name":"tdd.md","path":"docs/zh-CN/references/tdd.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/tdd.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"\nTDD 关乎设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现前思考行为，从而产生更清晰的接口和更可测试的代码。\n\n**原则：** 如果在编写 `fn` 之前能用 `expect(fn(input)).toBe(output)` 描述行为，TDD 会改善结果。\n\n**关键洞察：** TDD 工作本质上比标准任务更重 —— 它需要 2-3 个执行周期（RED → GREEN → REFACTOR），每个周期都涉及文件读取、测试运行和可能的调试。TDD 功能获得专门的计划，以确保整个周期内有完整的上下文可用。\n\n\n\n## 何时 TDD 提高质量\n\n**TDD 候选（创建 TDD 计划）：**\n- 有明确输入/输出的业务逻辑\n- 有请求/响应契约的 API 端点\n- 数据转换、解析、格式化\n- 验证规则和约束\n- 有可测试行为的算法\n- 状态机和工作流\n- 有清晰规格的工具函数\n\n**跳过 TDD（使用带 `type=\"auto\"` 任务的标准计划）：**\n- UI 布局、样式、视觉组件\n- 配置更改\n- 连接现有组件的胶水代码\n- 一次性脚本和迁移\n- 无业务逻辑的简单 CRUD\n- 探索性原型\n\n**启发式：** 能在编写 `fn` 之前写 `expect(fn(input)).toBe(output)` 吗？\n→ 能：创建 TDD 计划\n→ 不能：使用标准计划，事后添加测试（如需要）\n\n\n\n## TDD 计划结构\n\n每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 循环实现**一个功能**。\n\n```markdown\n---\nphase: XX-name\nplan: NN\ntype: tdd\n---\n\n\n[什么功能以及为什么]\nPurpose: [该功能 TDD 的设计收益]\nOutput: [可工作的、已测试的功能]\n\n\n\n@.planning/PROJECT.md\n@.planning/ROADMAP.md\n@relevant/source/files.ts\n\n\n\n [功能名称]\n [源文件, 测试文件]\n \n [可测试术语描述的预期行为]\n Cases: 输入 → 预期输出\n \n [测试通过后如何实现]\n\n\n\n[证明功能有效的测试命令]\n\n\n\n- 失败测试已编写并提交\n- 实现通过测试\n- 重构完成（如需要）\n- 所有 2-3 个提交都存在\n\n\n\n完成后，创建包含以下内容的 SUMMARY.md：\n- RED: 编写了什么测试，为什么失败\n- GREEN: 什么实现让它通过\n- REFACTOR: 做了什么清理（如有）\n- Commits: 生成的提交列表\n\n```\n\n**每个 TDD 计划一个功能。** 如果功能足够简单可以批量处理，那就足够简单可以跳过 TDD —— 使用标准计划，事后添加测试。\n\n\n\n## 红-绿-重构循环\n\n**RED - 编写失败测试：**\n1. 按项目约定创建测试文件\n2. 编写描述预期行为的测试（来自 `` 元素）\n3. 运行测试 - 必须**失败**\n4. 如果测试通过：功能已存在或测试有误。调查。\n5. 提交：`test({phase}-{plan}): add failing test for [feature]`\n\n**GREEN - 实现使其通过：**\n1. 编写使测试通过的最小代码\n2. 不耍小聪明，不优化 - 只让它工作\n3. 运行测试 - 必须**通过**\n4. 提交：`feat({phase}-{plan}): implement [feature]`\n\n**REFACTOR（如需要）：**\n1. 如果存在明显的改进，清理实现\n2. 运行测试 - 必须**仍然通过**\n3. 仅在做出更改时提交：`refactor({phase}-{plan}): clean up [feature]`\n\n**结果：** 每个 TDD 计划产生 2-3 个原子提交。\n\n\n\n## 好测试 vs 坏测试\n\n**测试行为，而非实现：**\n- 好：\"返回格式化的日期字符串\"\n- 坏：\"用正确参数调用 formatDate 辅助函数\"\n- 测试应该能经受重构\n\n**每个测试一个概念：**\n- 好：分别为有效输入、空输入、畸形输入编写测试\n- 坏：用多个断言检查所有边缘情况的单个测试\n\n**描述性名称：**\n- 好：\"should reject empty email\"、\"returns null for invalid ID\"\n- 坏：\"test1\"、\"handles error\"、\"works correctly\"\n\n**不包含实现细节：**\n- 好：测试公共 API、可观察行为\n- 坏：Mock 内部实现、测试私有方法、断言内部状态\n\n\n\n## 测试框架设置（如不存在）\n\n当执行 TDD 计划但没有配置测试框架时，作为 RED 阶段的一部分进行设置：\n\n**1. 检测项目类型：**\n```bash\n# JavaScript/TypeScript\nif [ -f package.json ]; then echo \"node\"; fi\n\n# Python\nif [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo \"python\"; fi\n\n# Go\nif [ -f go.mod ]; then echo \"go\"; fi\n\n# Rust\nif [ -f Cargo.toml ]; then echo \"rust\"; fi\n```\n\n**2. 安装最小框架：**\n| 项目 | 框架 | 安装 |\n|---------|-----------|---------|\n| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |\n| Node.js (Vite) | Vitest | `npm install -D vitest` |\n| Python | pytest | `pip install pytest` |\n| Go | testing | 内置 |\n| Rust | cargo test | 内置 |\n\n**3. 按需创建配置：**\n- Jest: 带 ts-jest preset 的 `jest.config.js`\n- Vitest: 带测试全局变量的 `vitest.config.ts`\n- pytest: `pytest.ini` 或 `pyproject.toml` 部分\n\n**4. 验证设置：**\n```bash\n# 运行空测试套件 - 应该以 0 个测试通过\nnpm test # Node\npytest # Python\ngo test ./... # Go\ncargo test # Rust\n```\n\n**5. 创建第一个测试文件：**\n遵循项目约定的测试位置：\n- 源文件旁边的 `*.test.ts` / `*.spec.ts`\n- `__tests__/` 目录\n- 根目录的 `tests/` 目录\n\n框架设置是第一个 TDD 计划 RED 阶段的一次性成本。\n\n\n\n## 错误处理\n\n**测试在 RED 阶段没有失败：**\n- 功能可能已存在 - 调查\n- 测试可能有误（没测试你以为的东西）\n- 前进前修复\n\n**测试在 GREEN 阶段没有通过：**\n- 调试实现\n- 不要跳到重构\n- 持续迭代直到绿色\n\n**测试在 REFACTOR 阶段失败：**\n- 撤销重构\n- 提交过早\n- 用更小的步骤重构\n\n**不相关的测试失败：**\n- 停下来调查\n- 可能表明耦合问题\n- 前进前修复\n\n\n\n## TDD 计划的提交模式\n\nTDD 计划产生 2-3 个原子提交（每个阶段一个）：\n\n```\ntest(08-02): add failing test for email validation\n\n- Tests valid email formats accepted\n- Tests invalid formats rejected\n- Tests empty input handling\n\nfeat(08-02): implement email validation\n\n- Regex pattern matches RFC 5322\n- Returns boolean for validity\n- Handles edge cases (empty, null)\n\nrefactor(08-02): extract regex to constant (optional)\n\n- Moved pattern to EMAIL_REGEX constant\n- No behavior changes\n- Tests still pass\n```\n\n**与标准计划对比：**\n- 标准计划：每个任务 1 个提交，每个计划 2-4 个提交\n- TDD 计划：单个功能 2-3 个提交\n\n两者遵循相同格式：`{type}({phase}-{plan}): {description}`\n\n**好处：**\n- 每个提交独立可回滚\n- Git bisect 在提交级别工作\n- 显示 TDD 纪律的清晰历史\n- 与整体提交策略一致\n\n\n\n## 上下文预算\n\nTDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。\n\n为什么更低：\n- RED 阶段：编写测试、运行测试、可能调试为什么没有失败\n- GREEN 阶段：实现、运行测试、可能对失败进行迭代\n- REFACTOR 阶段：修改代码、运行测试、验证无回归\n\n每个阶段涉及读取文件、运行命令、分析输出。来回往复本质上比线性任务执行更重。\n\n单一功能聚焦确保整个周期保持完整质量。\n","isInternal":false,"tokens":2567,"sizeBytes":7533},{"name":"ui-brand.md","path":"docs/zh-CN/references/ui-brand.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/ui-brand.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# UI 品牌规范\n\n面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。\n\n## 阶段横幅\n\n用于主要工作流过渡。\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► {阶段名称}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**阶段名称（大写）：**\n- `QUESTIONING`（提问）\n- `RESEARCHING`（研究）\n- `DEFINING REQUIREMENTS`（定义需求）\n- `CREATING ROADMAP`（创建路线图）\n- `PLANNING PHASE {N}`（规划阶段 {N}）\n- `EXECUTING WAVE {N}`（执行波次 {N}）\n- `VERIFYING`（验证）\n- `PHASE {N} COMPLETE ✓`（阶段 {N} 完成）\n- `MILESTONE COMPLETE 🎉`（里程碑完成）\n\n---\n\n## 检查点框\n\n需要用户操作。62 字符宽度。\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ CHECKPOINT: {类型} ║\n╚══════════════════════════════════════════════════════════════╝\n\n{内容}\n\n──────────────────────────────────────────────────────────────\n→ {操作提示}\n──────────────────────────────────────────────────────────────\n```\n\n**类型：**\n- `CHECKPOINT: 需要验证` → `→ 输入 \"approved\" 或描述问题`\n- `CHECKPOINT: 需要决策` → `→ 选择: option-a / option-b`\n- `CHECKPOINT: 需要操作` → `→ 完成后输入 \"done\"`\n\n---\n\n## 状态符号\n\n```\n✓ 完成 / 通过 / 已验证\n✗ 失败 / 缺失 / 阻塞\n◆ 进行中\n○ 待处理\n⚡ 自动批准\n⚠ 警告\n🎉 里程碑完成（仅在横幅中）\n```\n\n---\n\n## 进度显示\n\n**阶段/里程碑级别：**\n```\n进度: ████████░░ 80%\n```\n\n**任务级别：**\n```\n任务: 2/4 完成\n```\n\n**计划级别：**\n```\n计划: 3/5 完成\n```\n\n---\n\n## 生成指示器\n\n```\n◆ 正在生成研究员...\n\n◆ 并行生成 4 个研究员...\n → 技术栈研究\n → 功能研究\n → 架构研究\n → 陷阱研究\n\n✓ 研究员完成: STACK.md 已写入\n```\n\n---\n\n## 下一步区块\n\n始终在主要完成后。\n\n```\n───────────────────────────────────────────────────────────────\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n───────────────────────────────────────────────────────────────\n\n**也可选：**\n- (根据工作流选填可选命令，例如 `/gsd-progress --next`)\n\n───────────────────────────────────────────────────────────────\n```\n\n---\n\n## 错误框\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ ERROR ║\n╚══════════════════════════════════════════════════════════════╝\n\n{错误描述}\n\n**修复方法:** {解决步骤}\n```\n\n---\n\n## 表格\n\n```\n| 阶段 | 状态 | 计划 | 进度 |\n|------|------|------|------|\n| 1 | ✓ | 3/3 | 100% |\n| 2 | ◆ | 1/4 | 25% |\n| 3 | ○ | 0/2 | 0% |\n```\n\n---\n\n## 反模式\n\n- 变化的框/横幅宽度\n- 混合横幅样式（`===`、`---`、`***`）\n- 横幅中缺少 `GSD ►` 前缀\n- 随机 emoji（`🚀`、`✨`、`💫`）\n- 完成后缺少下一步区块","isInternal":false,"tokens":1219,"sizeBytes":4456},{"name":"verification-patterns.md","path":"docs/zh-CN/references/verification-patterns.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/zh-CN/references/verification-patterns.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# 验证模式\n\n如何验证不同类型的工件是真实实现，而非存根或占位符。\n\n\n**存在 ≠ 实现**\n\n文件存在并不意味着功能有效。验证必须检查：\n1. **存在** - 文件在预期路径\n2. **实质性** - 内容是真实实现，非占位符\n3. **已连接** - 已连接到系统的其他部分\n4. **功能性** - 调用时实际工作\n\n级别 1-3 可以编程检查。级别 4 通常需要人工验证。\n\n\n\n\n## 通用存根模式\n\n这些模式表明占位符代码，无论文件类型：\n\n**基于注释的存根：**\n```bash\n# 存根注释的 Grep 模式\ngrep -E \"(TODO|FIXME|XXX|HACK|PLACEHOLDER)\" \"$file\"\ngrep -E \"implement|add later|coming soon|will be\" \"$file\" -i\ngrep -E \"// \\.\\.\\.|/\\* \\.\\.\\. \\*/|# \\.\\.\\.\" \"$file\"\n```\n\n**输出中的占位符文本：**\n```bash\n# UI 占位符模式\ngrep -E \"placeholder|lorem ipsum|coming soon|under construction\" \"$file\" -i\ngrep -E \"sample|example|test data|dummy\" \"$file\" -i\ngrep -E \"\\[.*\\]|<.*>|\\{.*\\}\" \"$file\" # 模板括号未移除\n```\n\n**空或琐碎实现：**\n```bash\n# 什么都不做的函数\ngrep -E \"return null|return undefined|return \\{\\}|return \\[\\]\" \"$file\"\ngrep -E \"pass$|\\.\\.\\.|\\bnothing\\b\" \"$file\"\ngrep -E \"console\\.(log|warn|error).*only\" \"$file\" # 仅日志函数\n```\n\n**预期动态但硬编码的值：**\n```bash\n# 硬编码 ID、计数或内容\ngrep -E \"id.*=.*['\\\"].*['\\\"]\" \"$file\" # 硬编码字符串 ID\ngrep -E \"count.*=.*\\d+|length.*=.*\\d+\" \"$file\" # 硬编码计数\ngrep -E \"\\\\\\$\\d+\\.\\d{2}|\\d+ items\" \"$file\" # 硬编码显示值\n```\n\n\n\n\n\n## React/Next.js 组件\n\n**存在检查：**\n```bash\n# 文件存在且导出组件\n[ -f \"$component_path\" ] && grep -E \"export (default |)function|export const.*=.*\\(\" \"$component_path\"\n```\n\n**实质性检查：**\n```bash\n# 返回实际 JSX，非占位符\ngrep -E \"return.*<\" \"$component_path\" | grep -v \"return.*null\" | grep -v \"placeholder\" -i\n\n# 有有意义的内容（不仅仅是包装 div）\ngrep -E \"<[A-Z][a-zA-Z]+|className=|onClick=|onChange=\" \"$component_path\"\n\n# 使用 props 或 state（非静态）\ngrep -E \"props\\.|useState|useEffect|useContext|\\{.*\\}\" \"$component_path\"\n```\n\n**React 特有的存根模式：**\n```javascript\n// 危险信号 - 这些是存根：\nreturn
Component
\nreturn
Placeholder
\nreturn
{/* TODO */}
\nreturn

Coming soon

\nreturn null\nreturn <>\n\n// 也是存根 - 空处理器：\nonClick={() => {}}\nonChange={() => console.log('clicked')}\nonSubmit={(e) => e.preventDefault()} // 仅阻止默认，什么都不做\n```\n\n**连接检查：**\n```bash\n# 组件导入它需要的东西\ngrep -E \"^import.*from\" \"$component_path\"\n\n# Props 实际被使用（不仅仅是接收）\n# 查找解构或 props.X 用法\ngrep -E \"\\{ .* \\}.*props|\\bprops\\.[a-zA-Z]+\" \"$component_path\"\n\n# API 调用存在（对于数据获取组件）\ngrep -E \"fetch\\(|axios\\.|useSWR|useQuery|getServerSideProps|getStaticProps\" \"$component_path\"\n```\n\n**功能验证（需要人工）：**\n- 组件是否渲染可见内容？\n- 交互元素是否响应点击？\n- 数据是否加载并显示？\n- 错误状态是否适当显示？\n\n\n\n\n\n## API 路由（Next.js App Router / Express 等）\n\n**存在检查：**\n```bash\n# 路由文件存在\n[ -f \"$route_path\" ]\n\n# 导出 HTTP 方法处理器（Next.js App Router）\ngrep -E \"export (async )?(function|const) (GET|POST|PUT|PATCH|DELETE)\" \"$route_path\"\n\n# 或 Express 风格处理器\ngrep -E \"\\.(get|post|put|patch|delete)\\(\" \"$route_path\"\n```\n\n**实质性检查：**\n```bash\n# 有实际逻辑，不仅仅是 return 语句\nwc -l \"$route_path\" # 超过 10-15 行表明真实实现\n\n# 与数据源交互\ngrep -E \"prisma\\.|db\\.|mongoose\\.|sql|query|find|create|update|delete\" \"$route_path\" -i\n\n# 有错误处理\ngrep -E \"try|catch|throw|error|Error\" \"$route_path\"\n\n# 返回有意义的响应\ngrep -E \"Response\\.json|res\\.json|res\\.send|return.*\\{\" \"$route_path\" | grep -v \"message.*not implemented\" -i\n```\n\n**API 路由特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport async function POST() {\n return Response.json({ message: \"Not implemented\" })\n}\n\nexport async function GET() {\n return Response.json([]) // 空 array 无数据库查询\n}\n\nexport async function PUT() {\n return new Response() // 空响应\n}\n\n// 仅控制台日志：\nexport async function POST(req) {\n console.log(await req.json())\n return Response.json({ ok: true })\n}\n```\n\n**连接检查：**\n```bash\n# 导入数据库/服务客户端\ngrep -E \"^import.*prisma|^import.*db|^import.*client\" \"$route_path\"\n\n# 实际使用请求体（对于 POST/PUT）\ngrep -E \"req\\.json\\(\\)|req\\.body|request\\.json\\(\\)\" \"$route_path\"\n\n# 验证输入（不仅仅信任请求）\ngrep -E \"schema\\.parse|validate|zod|yup|joi\" \"$route_path\"\n```\n\n**功能验证（人工或自动化）：**\n- GET 是否从数据库返回真实数据？\n- POST 是否实际创建记录？\n- 错误响应是否有正确的状态码？\n- 认证检查是否实际执行？\n\n\n\n\n\n## 数据库模式（Prisma / Drizzle / SQL）\n\n**存在检查：**\n```bash\n# 模式文件存在\n[ -f \"prisma/schema.prisma\" ] || [ -f \"drizzle/schema.ts\" ] || [ -f \"src/db/schema.sql\" ]\n\n# 模型/表已定义\ngrep -E \"^model $model_name|CREATE TABLE $table_name|export const $table_name\" \"$schema_path\"\n```\n\n**实质性检查：**\n```bash\n# 有预期字段（不仅仅是 id）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"^\\s+\\w+\\s+\\w+\"\n\n# 有预期关系\ngrep -E \"@relation|REFERENCES|FOREIGN KEY\" \"$schema_path\"\n\n# 有适当的字段类型（不全是 String）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"Int|DateTime|Boolean|Float|Decimal|Json\"\n```\n\n**模式特有的存根模式：**\n```prisma\n// 危险信号 - 这些是存根：\nmodel User {\n id String @id\n // TODO: add fields\n}\n\nmodel Message {\n id String @id\n content String // 只有一个真实字段\n}\n\n// 缺少关键字段：\nmodel Order {\n id String @id\n // 缺少: userId, items, total, status, createdAt\n}\n```\n\n**连接检查：**\n```bash\n# 迁移存在且已应用\nls prisma/migrations/ 2>/dev/null | wc -l # 应该 > 0\nnpx prisma migrate status 2>/dev/null | grep -v \"pending\"\n\n# 客户端已生成\n[ -d \"node_modules/.prisma/client\" ]\n```\n\n**功能验证：**\n```bash\n# 可以查询表（自动化）\nnpx prisma db execute --stdin <<< \"SELECT COUNT(*) FROM $table_name\"\n```\n\n\n\n\n\n## 自定义 Hooks 和工具\n\n**存在检查：**\n```bash\n# 文件存在且导出函数\n[ -f \"$hook_path\" ] && grep -E \"export (default )?(function|const)\" \"$hook_path\"\n```\n\n**实质性检查：**\n```bash\n# Hook 使用 React hooks（对于自定义 hooks）\ngrep -E \"useState|useEffect|useCallback|useMemo|useRef|useContext\" \"$hook_path\"\n\n# 有有意义的返回值\ngrep -E \"return \\{|return \\[\" \"$hook_path\"\n\n# 超过琐碎长度\n[ $(wc -l < \"$hook_path\") -gt 10 ]\n```\n\n**Hooks 特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport function useAuth() {\n return { user: null, login: () => {}, logout: () => {} }\n}\n\nexport function useCart() {\n const [items, setItems] = useState([])\n return { items, addItem: () => console.log('add'), removeItem: () => {} }\n}\n\n// 硬编码返回：\nexport function useUser() {\n return { name: \"Test User\", email: \"test@example.com\" }\n}\n```\n\n**连接检查：**\n```bash\n# Hook 实际在某处被导入\ngrep -r \"import.*$hook_name\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n\n# Hook 实际被调用\ngrep -r \"$hook_name()\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n```\n\n\n\n\n\n## 环境变量和配置\n\n**存在检查：**\n```bash\n# .env 文件存在\n[ -f \".env\" ] || [ -f \".env.local\" ]\n\n# 必需变量已定义\ngrep -E \"^$VAR_NAME=\" .env .env.local 2>/dev/null\n```\n\n**实质性检查：**\n```bash\n# 变量有实际值（非占位符）\ngrep -E \"^$VAR_NAME=.+\" .env .env.local 2>/dev/null | grep -v \"your-.*-here|xxx|placeholder|TODO\" -i\n\n# 值对类型看起来有效：\n# - URL 应以 http 开头\n# - 密钥应足够长\n# - 布尔值应为 true/false\n```\n\n**环境变量特有的存根模式：**\n```bash\n# 危险信号 - 这些是存根：\nDATABASE_URL=your-database-url-here\nSTRIPE_SECRET_KEY=sk_test_xxx\nAPI_KEY=placeholder\nNEXT_PUBLIC_API_URL=http://localhost:3000 # 生产环境仍指向 localhost\n```\n\n**连接检查：**\n```bash\n# 变量实际在代码中使用\ngrep -r \"process\\.env\\.$VAR_NAME|env\\.$VAR_NAME\" src/ --include=\"*.ts\" --include=\"*.tsx\"\n\n# 变量在验证模式中（如果使用 zod 等验证 env）\ngrep -E \"$VAR_NAME\" src/env.ts src/env.mjs 2>/dev/null\n```\n\n\n\n\n\n## 连接验证模式\n\n连接验证检查组件是否实际通信。这是大多数存根隐藏的地方。\n\n### 模式：组件 → API\n\n**检查：** 组件是否实际调用 API？\n\n```bash\n# 查找 fetch/axios 调用\ngrep -E \"fetch\\(['\\\"].*$api_path|axios\\.(get|post).*$api_path\" \"$component_path\"\n\n# 验证未被注释掉\ngrep -E \"fetch\\(|axios\\.\" \"$component_path\" | grep -v \"^.*//.*fetch\"\n\n# 检查响应被使用\ngrep -E \"await.*fetch|\\.then\\(|setData|setState\" \"$component_path\"\n```\n\n**危险信号：**\n```typescript\n// Fetch 存在但响应被忽略：\nfetch('/api/messages') // 无 await，无 .then，无赋值\n\n// Fetch 在注释中：\n// fetch('/api/messages').then(r => r.json()).then(setMessages)\n\n// Fetch 到错误的端点：\nfetch('/api/message') // 拼写错误 - 应该是 /api/messages\n```\n\n### 模式：API → 数据库\n\n**检查：** API 路由是否实际查询数据库？\n\n```bash\n# 查找数据库调用\ngrep -E \"prisma\\.$model|db\\.query|Model\\.find\" \"$route_path\"\n\n# 验证被 await\ngrep -E \"await.*prisma|await.*db\\.\" \"$route_path\"\n\n# 检查结果被返回\ngrep -E \"return.*json.*data|res\\.json.*result\" \"$route_path\"\n```\n\n**危险信号：**\n```typescript\n// 查询存在但结果未返回：\nawait prisma.message.findMany()\nreturn Response.json({ ok: true }) // 返回静态值，非查询结果\n\n// 查询未被 await：\nconst messages = prisma.message.findMany() // 缺少 await\nreturn Response.json(messages) // 返回 Promise，非数据\n```\n\n### 模式：表单 → 处理器\n\n**检查：** 表单提交是否实际做些什么？\n\n```bash\n# 查找 onSubmit 处理器\ngrep -E \"onSubmit=\\{|handleSubmit\" \"$component_path\"\n\n# 检查处理器有内容\ngrep -A 10 \"onSubmit.*=\" \"$component_path\" | grep -E \"fetch|axios|mutate|dispatch\"\n\n# 验证不仅仅是 preventDefault\ngrep -A 5 \"onSubmit\" \"$component_path\" | grep -v \"only.*preventDefault\" -i\n```\n\n**危险信号：**\n```typescript\n// 处理器仅阻止默认：\nonSubmit={(e) => e.preventDefault()}\n\n// 处理器仅日志：\nconst handleSubmit = (data) => {\n console.log(data)\n}\n\n// 处理器为空：\nonSubmit={() => {}}\n```\n\n### 模式：状态 → 渲染\n\n**检查：** 组件是否渲染状态，而非硬编码内容？\n\n```bash\n# 查找 JSX 中的状态使用\ngrep -E \"\\{.*messages.*\\}|\\{.*data.*\\}|\\{.*items.*\\}\" \"$component_path\"\n\n# 检查状态的 map/render\ngrep -E \"\\.map\\(|\\.filter\\(|\\.reduce\\(\" \"$component_path\"\n\n# 验证动态内容\ngrep -E \"\\{[a-zA-Z_]+\\.\" \"$component_path\" # 变量插值\n```\n\n**危险信号：**\n```tsx\n// 硬编码而非状态：\nreturn
\n

Message 1

\n

Message 2

\n
\n\n// 状态存在但未渲染：\nconst [messages, setMessages] = useState([])\nreturn
No messages
// 总是显示 \"no messages\"\n\n// 渲染错误的状态：\nconst [messages, setMessages] = useState([])\nreturn
{otherData.map(...)}
// 使用不同数据\n```\n\n\n\n\n\n## 快速验证清单\n\n对于每种工件类型，运行此清单：\n\n### 组件清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数/const 组件\n- [ ] 返回 JSX（非 null/空）\n- [ ] 渲染中无占位符文本\n- [ ] 使用 props 或 state（非静态）\n- [ ] 事件处理器有真实实现\n- [ ] 导入正确解析\n- [ ] 在应用某处被使用\n\n### API 路由清单\n- [ ] 文件存在于预期路径\n- [ ] 导出 HTTP 方法处理器\n- [ ] 处理器超过 5 行\n- [ ] 查询数据库或服务\n- [ ] 返回有意义的响应（非空/占位符）\n- [ ] 有错误处理\n- [ ] 验证输入\n- [ ] 从前端调用\n\n### 模式清单\n- [ ] 模型/表已定义\n- [ ] 有所有预期字段\n- [ ] 字段有适当类型\n- [ ] 如需要关系已定义\n- [ ] 迁移存在且已应用\n- [ ] 客户端已生成\n\n### Hook/工具清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数\n- [ ] 有有意义的实现（非空返回）\n- [ ] 在应用某处被使用\n- [ ] 返回值被消费\n\n### 连接清单\n- [ ] 组件 → API: fetch/axios 调用存在且使用响应\n- [ ] API → 数据库: 查询存在且结果返回\n- [ ] 表单 → 处理器: onSubmit 调用 API/mutation\n- [ ] 状态 → 渲染: 状态变量出现在 JSX 中\n\n\n\n\n\n## 自动化验证方法\n\n对于验证子代理，使用此模式：\n\n```bash\n# 1. 检查存在\ncheck_exists() {\n [ -f \"$1\" ] && echo \"EXISTS: $1\" || echo \"MISSING: $1\"\n}\n\n# 2. 检查存根模式\ncheck_stubs() {\n local file=\"$1\"\n local stubs=$(grep -c -E \"TODO|FIXME|placeholder|not implemented\" \"$file\" 2>/dev/null || echo 0)\n [ \"$stubs\" -gt 0 ] && echo \"STUB_PATTERNS: $stubs in $file\"\n}\n\n# 3. 检查连接（组件调用 API）\ncheck_wiring() {\n local component=\"$1\"\n local api_path=\"$2\"\n grep -q \"$api_path\" \"$component\" && echo \"WIRED: $component → $api_path\" || echo \"NOT_WIRED: $component → $api_path\"\n}\n\n# 4. 检查实质性（超过 N 行，有预期模式）\ncheck_substantive() {\n local file=\"$1\"\n local min_lines=\"$2\"\n local pattern=\"$3\"\n local lines=$(wc -l < \"$file\" 2>/dev/null || echo 0)\n local has_pattern=$(grep -c -E \"$pattern\" \"$file\" 2>/dev/null || echo 0)\n [ \"$lines\" -ge \"$min_lines\" ] && [ \"$has_pattern\" -gt 0 ] && echo \"SUBSTANTIVE: $file\" || echo \"THIN: $file ($lines lines, $has_pattern matches)\"\n}\n```\n\n对每个必须有工件运行这些检查。汇总结果到 VERIFICATION.md。\n\n\n\n\n\n## 何时需要人工验证\n\n有些事情无法编程验证。标记这些需要人工测试：\n\n**始终人工：**\n- 视觉外观（看起来对吗？）\n- 用户流程完成（能实际做那件事吗？）\n- 实时行为（WebSocket、SSE）\n- 外部服务集成（Stripe、邮件发送）\n- 错误消息清晰度（消息有帮助吗？）\n- 性能感觉（感觉快吗？）\n\n**如不确定则人工：**\n- grep 无法追踪的复杂连接\n- 依赖状态的动态行为\n- 边缘情况和错误状态\n- 移动端响应式\n- 无障碍性\n\n**人工验证请求格式：**\n```markdown\n## 需要人工验证\n\n### 1. 聊天消息发送\n**测试：** 输入消息并点击发送\n**预期：** 消息出现在列表中，输入框清空\n**检查：** 刷新后消息是否持久？\n\n### 2. 错误处理\n**测试：** 断开网络，尝试发送\n**预期：** 错误消息出现，消息未丢失\n**检查：** 重连后能重试吗？\n```\n\n\n\n\n\n## 检查点前自动化\n\n关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议，请参阅：\n\n**@~/.claude/get-shit-done/references/checkpoints.md** → `` 部分\n\n关键原则：\n- Claude 在呈现检查点**之前**设置验证环境\n- 用户从不运行 CLI 命令（仅访问 URL）\n- 服务器生命周期：检查点前启动、处理端口冲突、持续运行\n- CLI 安装：安全处自动安装，否则检查点让用户选择\n- 错误处理：检查点前修复损坏环境，绝不呈现有失败设置的检查点\n\n","isInternal":false,"tokens":5373,"sizeBytes":15923},{"name":"sketch-theme-system.md","path":"get-shit-done/references/sketch-theme-system.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/get-shit-done/references/sketch-theme-system.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Shared Theme System\n\nAll sketches share a CSS variable theme so design decisions compound across sketches.\n\n## Setup\n\nOn the first sketch, create `.planning/sketches/themes/` with a default theme:\n\n```\n.planning/sketches/\n themes/\n default.css <- all sketches link to this\n 001-dashboard-layout/\n index.html <- links to ../themes/default.css\n```\n\n## Theme File Structure\n\nEach theme defines CSS custom properties only — no component styles, no layout rules. Just the visual vocabulary:\n\n```css\n:root {\n /* Colors */\n --color-bg: #fafafa;\n --color-surface: #ffffff;\n --color-border: #e5e5e5;\n --color-text: #1a1a1a;\n --color-text-muted: #6b6b6b;\n --color-primary: #2563eb;\n --color-primary-hover: #1d4ed8;\n --color-accent: #f59e0b;\n --color-danger: #ef4444;\n --color-success: #22c55e;\n\n /* Typography */\n --font-sans: 'Inter', system-ui, sans-serif;\n --font-mono: 'JetBrains Mono', monospace;\n --text-xs: 0.75rem;\n --text-sm: 0.875rem;\n --text-base: 1rem;\n --text-lg: 1.125rem;\n --text-xl: 1.25rem;\n --text-2xl: 1.5rem;\n --text-3xl: 1.875rem;\n\n /* Spacing */\n --space-1: 4px;\n --space-2: 8px;\n --space-3: 12px;\n --space-4: 16px;\n --space-6: 24px;\n --space-8: 32px;\n --space-12: 48px;\n\n /* Shapes */\n --radius-sm: 4px;\n --radius-md: 8px;\n --radius-lg: 12px;\n --radius-full: 9999px;\n\n /* Shadows */\n --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);\n --shadow-md: 0 4px 6px rgba(0,0,0,0.07);\n --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);\n}\n```\n\nAdapt the default theme to match the mood/direction established during intake. The values above are a starting point — change colors, fonts, spacing, and shapes to match the agreed aesthetic.\n\n## Linking\n\nEvery sketch links to the theme:\n\n```html\n\n```\n\n## Creating New Themes\n\nWhen a sketch reveals an aesthetic fork (\"should this feel clinical or warm?\"), create both as theme files rather than arguing about it. The user can switch and feel the difference.\n\nName themes descriptively: `midnight.css`, `warm-minimal.css`, `brutalist.css`.\n\n## Theme Switcher\n\nInclude in every sketch (part of the sketch toolbar):\n\n```html\n\n```\n\nDynamically populate options by listing available theme files, or hardcode the known themes.\n","isInternal":false,"tokens":756,"sizeBytes":2446},{"name":"cjs-sdk-seam.md","path":"docs/agents/cjs-sdk-seam.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/agents/cjs-sdk-seam.md","title":"Subagent: cjs-sdk-seam","category":"subagent-persona","format":"markdown","content":"# CJS↔SDK Hard-Seam Migration: Complete Reference\n## Issue #3575 (Parent: #3524)\n\n---\n\n## Migration overview\n\nThe CJS↔SDK hard-seam migration (#3524) eliminates a class of config-schema drift bugs by introducing single sources of truth at every decision point where CJS and SDK code previously diverged. The migration proceeded in six phases:\n\n| Phase | PR | Summary |\n|-------|----|---------|\n| Phase 1 | [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) | `state-document` Shared Module — source-of-truth at `sdk/src/state-document/`, generator, freshness check, CJS Adapter (`state-document.generated.cjs`). Worked example for the pattern. |\n| Phase 2 | [#3540](https://github.com/gsd-build/get-shit-done/pull/3540) | `configuration` Shared Module — `sdk/shared/config-schema.manifest.json` + `sdk/shared/config-defaults.manifest.json` as data manifests; generator + freshness check + CJS Adapter. |\n| Phase 3 | [#3548](https://github.com/gsd-build/get-shit-done/pull/3548) | `workstream-inventory` Shared Module — source-of-truth at `sdk/src/workstream-inventory/`, builder, generator, freshness check, CJS Adapter. |\n| Phase 4 | [#3554](https://github.com/gsd-build/get-shit-done/pull/3554) | `project-root` Shared Module — source-of-truth at `sdk/src/project-root/`, generator, freshness check, CJS Adapter. |\n| Phase 5.0 | [#3558](https://github.com/gsd-build/get-shit-done/pull/3558) | `runtime-bridge-sync` worker — enables CJS-side execution of SDK native handlers; state.* family initial router delegation via `executeForCjs`. |\n| Phase 5.1 | [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) | `state.*` router delegation complete — all known state subcommands delegated via `executeForCjs`; Phase 5.0 worker bug fix. |\n| Phase 6 | [#3577](https://github.com/gsd-build/get-shit-done/pull/3577) (closes [#3575](https://github.com/gsd-build/get-shit-done/issues/3575)) | Enforcement hardening + Final completion — hand-sync drift lint, CODEOWNERS, 6 family-router migrations, 5 Shared Module migrations (plan-scan, secrets, schema-detect, decisions, workstream-name-policy), workstream native support, parity fixes. Migration feature-complete: 22 cooperating siblings, 0 backlog pairs. |\n\n---\n\n## Phase 6 Retrospective: 15 config-schema drift bugs\n\nThis section captures 15 recurring config-schema drift bugs that motivated the migration. For each, we record what drifted, the surgical fix, and which Phase 6 enforcement layer would have prevented it.\n\n---\n\n### #1535 — Silent failure on unrecognized config.json keys\n- **Drifted:** `loadConfig` silently ignored any top-level key in `.planning/config.json` not in `VALID_CONFIG_KEYS`, giving users no feedback when hand-edited or external-tool-added keys had no effect.\n- **Fix landed:** PR #1542 — added stderr warning listing unrecognized keys.\n- **Would have been blocked by:** **handsync lint** — a seam-aware linter would forbid having parallel hand-authored config validators (CJS `config.cjs` and SDK `config-mutation.ts`) that could silently diverge.\n\n---\n\n### #1542 — fix(config): warn on unrecognized keys in config.json instead of silent drop\n- **Drifted:** No drift in this bug itself; it *fixed* #1535's silent-drop behavior by adding the warning.\n- **Fix landed:** PR #1542 — merged as the direct fix for #1535.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check on config validation) — both CJS and SDK config paths would be regenerated from a single source-of-truth schema module, eliminating the silent-drop risk.\n\n---\n\n### #2047 — bug: config-set rejects intel.enabled despite being a documented config key\n- **Drifted:** `intel.enabled` was documented in workflows and gated in runtime code (`intel.cjs:58`), but missing from `VALID_CONFIG_KEYS` in `config.cjs`, so `config-set` rejected it.\n- **Fix landed:** PR #2021 — added `intel.enabled` to `VALID_CONFIG_KEYS` in CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every config key gated in runtime code or documented in workflows must appear in the validator allowlist.\n\n---\n\n### #2052 — fix(config): add intel.enabled to VALID_CONFIG_KEYS\n- **Drifted:** Same as #2047 (missing from allowlist).\n- **Fix landed:** PR #2021 (same PR as #2047 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2047.\n\n---\n\n### #2638 — bug: loadConfig writes sub_repos to top-level, then warns it's unknown\n- **Drifted:** After #2561 canonicalized `sub_repos` to `planning.sub_repos`, the legacy migration and filesystem auto-sync in `loadConfig` still wrote to top-level `parsed.sub_repos`, which was then flagged as unknown.\n- **Fix landed:** PR #2668 — rewrote both paths to target `parsed.planning.sub_repos` and deleted stale top-level copy.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check for config shape) — the canonical location for `sub_repos` would be codified in a schema, and any code path writing to it would be verified against that schema at lint time.\n\n---\n\n### #2655 — fix(core): write sub_repos to planning.sub_repos, not top-level\n- **Drifted:** Same as #2638.\n- **Fix landed:** PR #2668 (same as #2638 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2638.\n\n---\n\n### #2653 — bug: SDK config-set rejects documented config keys accepted by CJS config-set\n- **Drifted:** SDK's `config-mutation.ts` had a hand-maintained `VALID_CONFIG_KEYS` set that had drifted **28 keys** behind CJS's `config-schema.cjs`, so documented commands like `gsd-sdk query config-set planning.sub_repos` were rejected.\n- **Fix landed:** PR #2670 — extracted shared `sdk/src/query/config-schema.ts` module mirroring CJS exactly; added parity test to fail on future drift.\n- **Would have been blocked by:** **manifest data isolation** — the config schema would live in one place (e.g., `sdk/shared/config.manifest.json`), and both CJS and SDK would read it, eliminating the possibility of independent drift.\n\n---\n\n### #2670 — fix(#2653): eliminate SDK↔CJS config-schema drift\n- **Drifted:** Same as #2653 (28-key drift).\n- **Fix landed:** PR #2670 (same as #2653 fix).\n- **Would have been blocked by:** **manifest data isolation** — same as #2653.\n\n---\n\n### #2687 — bug: loadConfig warns on valid dynamic-pattern containers in .planning/config.json\n- **Drifted:** Keys like `review.models.` were registered in `config-schema.cjs`'s `DYNAMIC_KEY_PATTERNS` but absent from the hand-maintained `KNOWN_TOP_LEVEL` set in `core.cjs`, causing false-positive \"unknown key\" warnings.\n- **Fix landed:** PR #2706 — added `topLevel` field to `DYNAMIC_KEY_PATTERNS` entries; derived `KNOWN_TOP_LEVEL` from schema instead of maintaining it manually.\n- **Would have been blocked by:** **per-Module drift lint** — the validator that builds `KNOWN_TOP_LEVEL` would be regenerated from the schema each run, not hand-maintained.\n\n---\n\n### #2706 — fix(#2687): loadConfig no longer warns on valid dynamic-pattern containers\n- **Drifted:** Same as #2687 (false warnings on valid dynamic keys).\n- **Fix landed:** PR #2706 (same as #2687 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2687.\n\n---\n\n### #2798 — context_window missing from VALID_CONFIG_KEYS\n- **Drifted:** `context_window` was documented in workflows and read in SDK runtime (`init.js:190`, `validate.js:575`), but missing from allowlists in both `config-mutation.ts` and `config-schema.cjs`, so writes were rejected.\n- **Fix landed:** PR #2816 — added `context_window` to `VALID_CONFIG_KEYS` in both SDK and CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every key read at runtime must be in the allowlist.\n\n---\n\n### #2816 — fix(#2798): add context_window to VALID_CONFIG_KEYS allowlist\n- **Drifted:** Same as #2798 (missing from allowlists).\n- **Fix landed:** PR #2816 (same as #2798 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2798.\n\n---\n\n### #3055 — bug: top-level branching_strategy silently becomes \"none\"\n- **Drifted:** `.planning/config.json` with top-level `branching_strategy: \"phase\"` was flagged as unknown and dropped by validator, causing `loadConfig` to fall back to the `\"none\"` default, so phase commits landed on the operator's current branch instead of creating `gsd/phase-{N}` branches.\n- **Fix landed:** PR #3116 — SDK-side only; added legacy normalization in `mergeDefaults()` to graft top-level value into canonical `git.branching_strategy` slot before validation.\n- **Would have been blocked by:** **per-Module drift lint** — the canonical location for `branching_strategy` would be codified in schema; validator would not strip the value before migrations had a chance to run, or CJS and SDK would share the same migration code.\n\n---\n\n### #3116 — fix: normalize legacy top-level branching_strategy into git config\n- **Drifted:** Same as #3055 (legacy top-level shape not normalized before validator strips it).\n- **Fix landed:** PR #3116 (SDK-side normalization in `mergeDefaults()`).\n- **Would have been blocked by:** **per-Module drift lint** — same as #3055, but SDK-side fix would be shared with CJS via seam layer instead of being ported separately.\n\n---\n\n### #3523 — bug: CJS loadConfig warns top-level branching_strategy 'will be ignored', but actively reads it\n- **Drifted:** After PR #3116 fixed the SDK side, the CJS path still emitted false \"will be ignored\" warnings on the same legacy top-level key, because `KNOWN_TOP_LEVEL` derivation extracted top-level names from `VALID_CONFIG_KEYS` (which contains `'git.branching_strategy'` but not `'branching_strategy'`), and the warning was factually incorrect — `core.cjs:485` does read the legacy value via fallback logic.\n- **Fix landed:** PR #3527 — added `'branching_strategy'` to the `KNOWN_TOP_LEVEL` hand-maintained list under the deprecated-keys bucket, suppressing the false warning.\n- **Would have been blocked by:** **runtime-bridge delegation** — if CJS and SDK config loading shared a common normalization routine (via `executeForCjs` or a shared seam module), the SDK fix in #3116 would automatically apply to CJS; no separate CJS-side warning would be possible.\n\n---\n\n## Surprises\n\nNone. All 15 bugs are genuine CJS↔SDK schema/validation drift, exactly the class the seam migration prevents.\n\n## Phase 6 Enforcement Summary\n\nThe seam migration introduces these layers:\n\n1. **handsync lint** (`scripts/lint-shared-module-handsync.cjs`) — Forbids parallel hand-authored validator modules; catches #1535, #2047, #2798.\n2. **freshness check** (`sdk/scripts/check--fresh.mjs`) — Regenerates config validators from schema each run; catches #2687, #3055.\n3. **manifest data isolation** (`sdk/shared/*.manifest.json`) — Single source-of-truth for schema; catches #2653.\n4. **per-Module drift lint** — Combination of freshness checks and schema-derived allowlists; catches #2638, #2687, #3055.\n5. **runtime-bridge delegation** (`executeForCjs` + shared seam modules) — Eliminates parallel CJS/SDK implementations; catches #3523 by preventing separate CJS warning logic.\n\nTogether, these layers eliminate the 15-bug class by enforcing single sources of truth at each decision point.\n\n---\n\n## Guide: Adding a new Shared Module\n\nUse this when you want to extract a new piece of data or logic that both CJS and SDK currently duplicate hand-by-hand. Phase 1's `state-document` migration is the worked example.\n\n**Step 1 — Create the source-of-truth file**\n\n```text\nsdk/src//index.ts\n```\n\nThis is the canonical definition. It may export a schema, a set of keys, a type, or a data object. It must not import from CJS or from generated files.\n\n**Step 2 — Write the generator script**\n\n```text\nsdk/scripts/gen-.mjs\n```\n\nThe generator reads `sdk/src//index.ts` (or `sdk/shared/.manifest.json` for pure-data manifests), produces a generated output file (either `sdk/src/.generated.ts` or `get-shit-done/bin/lib/.generated.cjs`), and exits 0. It must be idempotent: running it twice produces the same output.\n\n**Step 3 — Write the freshness check**\n\n```text\nsdk/scripts/check--fresh.mjs\n```\n\nThe freshness check re-runs the generator into a temp location, diffs against the committed file, and exits 1 with a clear message if they diverge. This is what CI runs.\n\n**Step 4 — Write the parity test** (optional but recommended)\n\n```text\ntests/-parity.test.cjs\n```\n\nAssert that the CJS Adapter and the SDK source-of-truth agree on every field that matters (key sets, defaults, schema shape). This test catches generator bugs that the freshness check cannot.\n\n**Step 5 — Wire CI**\n\nAdd a step in `.github/workflows/test.yml` after the existing freshness-check block (before \"Run tests with coverage\"), gated on `matrix.os == 'ubuntu-latest' && matrix.node-version == 24`:\n\n```yaml\n- name: SDK generated artifact drift check\n if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24\n shell: bash\n run: node sdk/scripts/check--fresh.mjs\n```\n\n**Step 6 — Run inventory regen**\n\nIf the module affects `CONTEXT.md`'s module inventory, update that section. Also update `scripts/shared-module-handsync-allowlist.json`: move any matching entry from `migrateMeBacklog` to `cooperatingSiblings` (or remove it entirely if the CJS hand-copy is now deleted).\n\n**Step 7 — Update CODEOWNERS**\n\nAdd the new source-of-truth path to `.github/CODEOWNERS` under the Phase 6 block to make the architectural ownership explicit.\n\n**Reference:** Phase 1 PR [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) — `state-document` migration.\n\n---\n\n## Guide: Adding a new canonical command\n\nUse this when adding a new `gsd-sdk query .` that should be handled natively in the SDK (not delegated to CJS). Phase 5.1's `state.update` migration (PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574)) is the worked example.\n\n**Step 1 — Declare in the command manifest**\n\nAdd the command definition to `sdk/src/query/command-manifest..ts`. Include the full argument schema and a `handler` reference.\n\n**Step 2 — Implement the SDK handler**\n\nWrite the handler in `sdk/src/query/.ts` (or inline in the manifest file for simple cases). The handler receives validated args and the runtime context; it must not shell out to CJS.\n\n**Step 3 — Add CJS router delegate (Phase 5.1+ pattern)**\n\nIn the family's CJS command router (e.g. `get-shit-done/bin/lib/state-command-router.cjs`), add a delegate case that calls `executeForCjs(subcommand, args)` from `cjs-command-router-adapter.cjs`. This ensures the CJS binary dispatches to the SDK native handler rather than re-implementing the logic.\n\n**Step 4 — Add a golden parity test**\n\nAdd a test in `tests/-command-router.test.cjs` (or a new file if the family has no test yet) that:\n1. Invokes the command via the SDK query path.\n2. Invokes the command via the CJS router path.\n3. Asserts both produce identical output.\n\nThis test enforces that the delegate and the native handler stay aligned.\n\n**Reference:** Phase 5.1 PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) — `state.update` delegation.\n\n---\n\n## Phase 6 Final Completion Summary\n\nPhase 6 (issue #3575, PR #3577) is feature-complete. The migration is done.\n\n**What shipped in Phase 6:**\n\n- **Shared Modules migrated (5 total in Phase 6):** `plan-scan`, `secrets`, `schema-detect`, `decisions`, `workstream-name-policy`. Each follows the full pattern: SDK source-of-truth, generator (`gen-.mjs`), freshness check (`check--fresh.mjs`), generated CJS artifact (`.generated.cjs`), CJS shim re-export, parity test, CI step, pre-commit hook, CODEOWNERS entry.\n- **Workstream native support:** The sync bridge worker now correctly threads `workstream` through to `registry.dispatch()`. `GSDTransport` no longer forces subprocess for workstream-scoped requests. Workstream-scoped state commands execute natively.\n- **State parity divergences resolved:** `state.record-metric` and `state.prune` SDK handlers now match CJS semantics exactly.\n- **MIGRATE_ME pairs resolved:** `decisions` and `workstream-name-policy` migrated from `migrateMeBacklog` to `cooperatingSiblings` as ADAPTER-OVER-MODULE.\n- **Lint final state:** 22 cooperating siblings, 0 backlog pairs.\n\n**Decisions migration specifics (B1):**\n- SDK `decisions.ts` regex aligned to CJS: `D-([A-Za-z0-9_-]+)` (alphanumeric IDs like `D-INFRA-01` accepted).\n- SDK returns richer `{id, text, category, tags, trackable}`; CJS callers using only `{id, text}` safely ignore extras.\n- Parity test: `tests/decisions-generator.test.cjs` (15 tests covering numeric IDs, alphanumeric IDs, richer schema fields).\n\n**Workstream-name-policy migration specifics (B2):**\n- Added `hasInvalidPathSegment` and `isValidActiveWorkstreamName` to SDK `workstream-name-policy.ts`.\n- `validateWorkstreamName` is now an alias for `isValidActiveWorkstreamName` (consistent with CJS semantics).\n- Parity test: `tests/workstream-name-policy-generator.test.cjs` (19 tests covering all four exports).\n\n---\n\n## Open follow-ups\n\nNo migration items remain. The following are future quality candidates, not defects:\n\n- **`config.cjs` / `sdk/src/config.ts`** — These files are CJS-CLI-ONLY (per allowlist classification). The `config.cjs` file contains only CLI command handlers that use sync CJS APIs; `sdk/src/config.ts` provides the async SDK layer. They serve disjoint surfaces. A future migration would require converting the CLI handlers to async + SDK patterns, which is a larger refactor out of scope for this migration cycle.\n- **`intel.cjs` / `sdk/src/query/intel.ts`** — Intentional architectural divergence (different file naming conventions between CJS and SDK; documented in allowlist). A future migration would require reconciling INTEL_FILES naming, which is a breaking change for existing consumers.\n- **`model-catalog.cjs` / `sdk/src/model-catalog.ts`** — Both sides read from `sdk/shared/model-catalog.json` independently (ADAPTER-OVER-MODULE pattern). This is intentional; the shared JSON is the source-of-truth. No duplication of logic between CJS and SDK consumers.\n","isInternal":false,"tokens":4535,"sizeBytes":18288},{"name":"domain.md","path":"docs/agents/domain.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/agents/domain.md","title":"Subagent: domain","category":"subagent-persona","format":"markdown","content":"# Domain Docs\n\nHow engineering skills consume this repo's domain documentation.\n\n## Layout: single-context\n\n```\n/\n├── CONTEXT.md ← domain glossary + recurring PR rules + workflow learnings\n├── docs/adr/ ← architectural decisions\n│ ├── 0001-dispatch-policy-module.md\n│ └── 0002-command-contract-validation-module.md\n└── ...\n```\n\n## Before exploring, read these\n\n1. **`CONTEXT.md`** at the repo root — domain terms, module names, recurring PR mistakes, workflow learnings. Read in full before naming anything or proposing architecture changes.\n2. **`docs/adr/`** — read ADRs relevant to the area you're working in before proposing structural changes. If your output contradicts an ADR, surface it explicitly:\n > *Contradicts ADR-0002 — but worth reopening because…*\n\nIf either file doesn't exist yet, proceed silently.\n\n## Use the glossary's vocabulary\n\nWhen naming modules, writing issue titles, test descriptions, or commit messages — use terms as defined in `CONTEXT.md`. Don't drift to synonyms. If you need a concept that isn't in the glossary, note it for `/grill-with-docs` rather than inventing language.\n\n## CONTEXT.md sections\n\n- **Domain terms** — canonical module names and seam vocabulary (Dispatch Policy Module, Command Contract Validation Module, etc.)\n- **Recurring PR mistakes** — CodeRabbit findings that recur; check before writing tests, shell scripts, changesets, or docs\n- **Workflow learnings** — patterns learned from triage + PR cycles; check before writing new command/workflow files or test paths\n","isInternal":false,"tokens":355,"sizeBytes":1602},{"name":"issue-tracker.md","path":"docs/agents/issue-tracker.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/agents/issue-tracker.md","title":"Subagent: issue-tracker","category":"subagent-persona","format":"markdown","content":"# Issue tracker: GitHub\n\nIssues for this repo live in **GitHub Issues** at `gsd-build/get-shit-done`.\n\n## Auth\n\nUse the configured GitHub CLI session for this checkout. Do not require a\nrepo-local `.envrc` before running `gh`.\n\n## Conventions\n\n- **Create**: `gh issue create --repo gsd-build/get-shit-done --title \"...\" --body \"...\"`\n- **Read**: `gh issue view --repo gsd-build/get-shit-done --comments`\n- **List**: `gh issue list --repo gsd-build/get-shit-done --state open --json number,title,labels --jq '...'`\n- **Comment**: `gh issue comment --repo gsd-build/get-shit-done --body \"...\"`\n- **Label**: `gh issue edit --repo gsd-build/get-shit-done --add-label \"...\" --remove-label \"...\"`\n- **Close**: `gh issue close --repo gsd-build/get-shit-done --comment \"...\"`\n\nAlways pass `--repo gsd-build/get-shit-done` explicitly — the local clone has multiple remotes and `gh` may resolve to the wrong one.\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a GitHub issue at `gsd-build/get-shit-done`.\n\n## When a skill says \"fetch the relevant ticket\"\n\nRun `gh issue view --repo gsd-build/get-shit-done --comments`.\n","isInternal":false,"tokens":307,"sizeBytes":1170},{"name":"triage-labels.md","path":"docs/agents/triage-labels.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/agents/triage-labels.md","title":"Subagent: triage-labels","category":"subagent-persona","format":"markdown","content":"# Triage Labels\n\nMaps the five canonical triage roles to the actual label strings in `gsd-build/get-shit-done`.\n\n| Canonical role | Label in this repo | Notes |\n|-------------------|--------------------------|----------------------------------------------------------------|\n| `needs-triage` | `needs-triage` | Auto-applied by GitHub Action on every new issue |\n| `needs-info` | `needs-reproduction` | Waiting on reporter — cannot reproduce, more info required |\n| `ready-for-agent` | `confirmed` | Bug verified + fully specified — AFK agent can pick up |\n| `ready-for-human` | `approved-enhancement` / `approved-feature` | Enhancement/feature approved by maintainer — human codes it |\n| `wontfix` | `wontfix` | Will not be actioned |\n\n## Notes on this repo's label model\n\n- `confirmed` is the AFK-agent-ready signal for **bugs**. It means \"verified to exist and reproducible.\"\n- For **enhancements** and **features**, maintainer approval is `approved-enhancement` / `approved-feature` respectively. A contributor (human or agent) may not write code until one of these is applied.\n- There is no separate \"ready-for-human\" vs \"ready-for-agent\" distinction for enhancements — both flow through the same `approved-*` labels. If the work requires human judgment (design decisions, external access), note it in the issue body.\n- `needs-triage` is removed when any other state label is applied.\n- `needs-reproduction` is used instead of the generic `needs-info` — be specific in triage comments about what reproduction steps or information are missing.\n","isInternal":false,"tokens":359,"sizeBytes":1749},{"name":"milestone-summary.md","path":"commands/gsd/milestone-summary.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/commands/gsd/milestone-summary.md","title":"gsd:milestone-summary","category":"command-prompt","format":"markdown","content":"---\ntype: prompt\nname: gsd:milestone-summary\ndescription: Generate a comprehensive project summary from milestone artifacts for team onboarding and review\nargument-hint: \"[version]\"\nallowed-tools:\n - Read\n - Write\n - Bash\n - Grep\n - Glob\n---\n\n\nGenerate a structured milestone summary for team onboarding and project review. Reads completed milestone artifacts (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION files) and produces a human-friendly overview of what was built, how, and why.\n\nPurpose: Enable new team members to understand a completed project by reading one document and asking follow-up questions.\nOutput: MILESTONE_SUMMARY written to `.planning/reports/`, presented inline, optional interactive Q&A.\n\n\n\n@~/.claude/get-shit-done/workflows/milestone-summary.md\n\n\n\n**Project files:**\n- `.planning/ROADMAP.md`\n- `.planning/PROJECT.md`\n- `.planning/STATE.md`\n- `.planning/RETROSPECTIVE.md`\n- `.planning/milestones/v{version}-ROADMAP.md` (if archived)\n- `.planning/milestones/v{version}-REQUIREMENTS.md` (if archived)\n- `.planning/phases/*-*/` (SUMMARY.md, VERIFICATION.md, CONTEXT.md, RESEARCH.md)\n\n**User input:**\n- Version: $ARGUMENTS (optional — defaults to current/latest milestone)\n\n\n\nExecute end-to-end.\n\n\n\n- Milestone version resolved (from args, STATE.md, or archive scan)\n- All available artifacts read (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION, RESEARCH, RETROSPECTIVE)\n- Summary document written to `.planning/reports/MILESTONE_SUMMARY-v{version}.md`\n- All 7 sections generated (Overview, Architecture, Phases, Decisions, Requirements, Tech Debt, Getting Started)\n- Summary presented inline to user\n- Interactive Q&A offered\n- STATE.md updated\n\n","frontmatter":{"type":"prompt","name":"gsd:milestone-summary","description":"Generate a comprehensive project summary from milestone artifacts for team onboarding and review","argument-hint":"[version]","allowed-tools":["Read","Write","Bash","Grep","Glob"],"allowedTools":["Read","Write","Bash","Grep","Glob"]},"allowedTools":["Read","Write","Bash","Grep","Glob"],"isInternal":false,"tokens":443,"sizeBytes":1829},{"name":"ARCHITECTURE.md","path":"docs/ARCHITECTURE.md","rawUrl":"https://raw.githubusercontent.com/gsd-build/get-shit-done/HEAD/docs/ARCHITECTURE.md","title":"docs - System Architecture & Module Boundaries","category":"project-spec","format":"markdown","content":"# GSD Architecture\n\n> System architecture for contributors and advanced users. For user-facing documentation, see [Feature Reference](FEATURES.md) or [User Guide](USER-GUIDE.md).\n\n---\n\n## Table of Contents\n\n- [System Overview](#system-overview)\n- [Design Principles](#design-principles)\n- [Component Architecture](#component-architecture)\n- [Agent Model](#agent-model)\n- [Data Flow](#data-flow)\n- [File System Layout](#file-system-layout)\n- [Installer Architecture](#installer-architecture)\n- [Hook System](#hook-system)\n- [CLI Tools Layer](#cli-tools-layer)\n- [Runtime Abstraction](#runtime-abstraction)\n\n---\n\n## System Overview\n\nGSD is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:\n\n1. **Context engineering** — Structured artifacts that give the AI everything it needs per task\n2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows\n3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline\n4. **State management** — Persistent project memory across sessions and context resets\n\n```\n┌──────────────────────────────────────────────────────┐\n│ USER │\n│ /gsd-command [args] │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ COMMAND LAYER │\n│ commands/gsd/*.md — Prompt-based command files │\n│ (Claude Code custom commands / Codex skills) │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ WORKFLOW LAYER │\n│ get-shit-done/workflows/*.md — Orchestration logic │\n│ (Reads references, spawns agents, manages state) │\n└──────┬──────────────┬─────────────────┬──────────────┘\n │ │ │\n┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐\n│ AGENT │ │ AGENT │ │ AGENT │\n│ (fresh │ │ (fresh │ │ (fresh │\n│ context) │ │ context)│ │ context) │\n└──────┬──────┘ └─────┬─────┘ └────────┬───────┘\n │ │ │\n┌──────▼──────────────▼─────────────────▼──────────────┐\n│ CLI TOOLS LAYER │\n│ gsd-sdk query (sdk/src/query) + gsd-tools.cjs │\n│ Programmatic SDK bridge: GSDTools/query-runtime-bridge.ts │\n└──────────────────────┬───────────────────────────────┘\n │\n┌──────────────────────▼───────────────────────────────┐\n│ FILE SYSTEM (.planning/) │\n│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │\n│ STATE.md | config.json | phases/ | research/ │\n└──────────────────────────────────────────────────────┘\n```\n\n---\n\n## Design Principles\n\n### 1. Fresh Context Per Agent\n\nEvery agent spawned by an orchestrator gets a clean context window (up to 200K tokens). This eliminates context rot — the quality degradation that happens as an AI fills its context window with accumulated conversation.\n\n### 2. Thin Orchestrators\n\nWorkflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:\n\n- Load context via `gsd-sdk query init.` (or legacy `gsd-tools.cjs init `)\n- Spawn specialized agents with focused prompts\n- Collect results and route to the next step\n- Update state between steps\n\n### 3. File-Based State\n\nAll state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means:\n\n- State survives context resets (`/clear`)\n- State is inspectable by both humans and agents\n- State can be committed to git for team visibility\n\n### 4. Absent = Enabled\n\nWorkflow feature flags follow the **absent = enabled** pattern. If a key is missing from `config.json`, it defaults to `true`. Users explicitly disable features; they don't need to enable defaults.\n\n### 5. Defense in Depth\n\nMultiple layers prevent common failure modes:\n\n- Plans are verified before execution (plan-checker agent)\n- Execution produces atomic commits per task\n- Post-execution verification checks against phase goals\n- UAT provides human verification as final gate\n\n---\n\n## Component Architecture\n\n### Commands (`commands/gsd/*.md`)\n\nUser-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as:\n\n- **Claude Code:** Custom slash commands (hyphen form, `/gsd-command-name`)\n- **OpenCode / Kilo:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Codex:** Skills (`$gsd-command-name`)\n- **Copilot:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Gemini CLI:** Slash commands under the `gsd:` namespace (colon form, `/gsd:command-name`) — Gemini namespaces all custom commands under their plugin id, so the install path rewrites every body-text reference to colon form\n- **Antigravity:** Skills\n\n**Total commands:** see [`docs/INVENTORY.md`](INVENTORY.md#commands) for the authoritative count and full roster.\n\n#### Two-stage hierarchical routing (v1.40, [#2792](https://github.com/gsd-build/get-shit-done/issues/2792))\n\nTo keep the eager skill-listing token cost low, v1.40 introduces six namespace **meta-skills** (`gsd-workflow`, `gsd-project`, `gsd-quality`, `gsd-context`, `gsd-manage`, `gsd-ideate` — sourced from `commands/gsd/ns-*.md`, but the invocable `name:` is the bare form shown here) layered above the concrete sub-skills. The model sees 6 namespace routers (~120 tokens) instead of a flat 86-skill listing (~2,150 tokens), selects a namespace, then routes to the concrete sub-skill via a routing table embedded in the namespace router's body. Namespace skills are **additive** — every concrete command is still directly invocable.\n\nThe router descriptions use pipe-separated keyword tags (≤ 60 chars) per the Tool Attention research showing keyword-dense tags outperform prose for routing at ~40 % the token cost.\n\n#### MCP token-budget interaction\n\nThe eager skill listing is one of two recurring per-turn token costs. The other is the MCP tool schema injected by every enabled MCP server in `.claude/settings.json`. Heavyweight MCP servers (browser/playwright, Mac-tools, Windows-tools) can each cost 20 k+ tokens per turn — often dwarfing what `model_profile` tuning saves. The toggle lives in the Claude Code harness (`enabledMcpjsonServers` / `disabledMcpjsonServers` in `.claude/settings.json`) and is **not** a GSD concern. Together, the two-stage routing layer (#2792) and disciplined MCP enablement are the largest cost levers per turn. See [`docs/USER-GUIDE.md`](USER-GUIDE.md) and `references/context-budget.md` for the audit checklist.\n\n### Workflows (`get-shit-done/workflows/*.md`)\n\nOrchestration logic that commands reference. Contains the step-by-step process including:\n\n- Context loading via `gsd-sdk query` init handlers (or legacy `gsd-tools.cjs init`)\n- Agent spawn instructions with model resolution\n- Gate/checkpoint definitions\n- State update patterns\n- Error handling and recovery\n\n**Total workflows:** see [`docs/INVENTORY.md`](INVENTORY.md#workflows) for the authoritative count and full roster.\n\n#### Progressive disclosure for workflows\n\nWorkflow files are loaded verbatim into Claude's context every time the\ncorresponding `/gsd-*` command is invoked. To keep that cost bounded, the\nworkflow size budget enforced by `tests/workflow-size-budget.test.cjs`\nmirrors the agent budget from #2361:\n\n| Tier | Per-file line limit |\n|-----------|--------------------|\n| `XL` | 1700 — top-level orchestrators (`execute-phase`, `plan-phase`, `new-project`) |\n| `LARGE` | 1500 — multi-step planners and large feature workflows |\n| `DEFAULT` | 1000 — focused single-purpose workflows (the target tier) |\n\n`workflows/discuss-phase.md` is held to a stricter <500-line ceiling per\nissue #2551. When a workflow grows beyond its tier, extract per-mode bodies\ninto `workflows//modes/.md`, templates into\n`workflows//templates/`, and shared knowledge into\n`get-shit-done/references/`. The parent file becomes a thin dispatcher that\nReads only the mode and template files needed for the current invocation.\n\n`workflows/discuss-phase/` is the canonical example of this pattern —\nparent dispatches, modes/ holds per-flag behavior (`power.md`, `all.md`,\n`auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`,\n`advisor.md`), and templates/ holds CONTEXT.md, DISCUSSION-LOG.md, and\ncheckpoint.json schemas that are read only when the corresponding output\nfile is being written.\n\n### Agents (`agents/*.md`)\n\nSpecialized agent definitions with frontmatter specifying:\n\n- `name` — Agent identifier\n- `description` — Role and purpose\n- `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)\n- `color` — Terminal output color for visual distinction\n\n**Total agents:** 33\n\n### References (`get-shit-done/references/*.md`)\n\nShared knowledge documents that workflows and agents `@-reference` (see [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) for the authoritative count and full roster):\n\n**Core references:**\n\n- `checkpoints.md` — Checkpoint type definitions and interaction patterns\n- `gates.md` — 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier\n- `model-profiles.md` — Per-agent model tier assignments\n- `model-profile-resolution.md` — Model resolution algorithm documentation\n- `verification-patterns.md` — How to verify different artifact types\n- `verification-overrides.md` — Per-artifact verification override rules\n- `planning-config.md` — Full config schema and behavior\n- `git-integration.md` — Git commit, branching, and history patterns\n- `git-planning-commit.md` — Planning directory commit conventions\n- `questioning.md` — Dream extraction philosophy for project initialization\n- `tdd.md` — Test-driven development integration patterns\n- `ui-brand.md` — Visual output formatting patterns\n- `common-bug-patterns.md` — Common bug patterns for code review and verification\n\n**Workflow references:**\n\n- `agent-contracts.md` — Formal interface between orchestrators and agents\n- `context-budget.md` — Context window budget allocation rules\n- `continuation-format.md` — Session continuation/resume format\n- `domain-probes.md` — Domain-specific probing questions for discuss-phase\n- `gate-prompts.md` — Gate/checkpoint prompt templates\n- `revision-loop.md` — Plan revision iteration patterns\n- `universal-anti-patterns.md` — Common anti-patterns to detect and avoid\n- `artifact-types.md` — Planning artifact type definitions\n- `phase-argument-parsing.md` — Phase argument parsing conventions\n- `decimal-phase-calculation.md` — Decimal sub-phase numbering rules\n- `workstream-flag.md` — Workstream active pointer conventions\n- `user-profiling.md` — User behavioral profiling methodology\n- `thinking-partner.md` — Conditional thinking partner activation at decision points\n\n**Thinking model references:**\n\nReferences for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows:\n\n- `thinking-models-debug.md` — Thinking model patterns for debugging workflows\n- `thinking-models-execution.md` — Thinking model patterns for execution agents\n- `thinking-models-planning.md` — Thinking model patterns for planning agents\n- `thinking-models-research.md` — Thinking model patterns for research agents\n- `thinking-models-verification.md` — Thinking model patterns for verification agents\n\n**Modular planner decomposition:**\n\nThe planner agent (`agents/gsd-planner.md`) was decomposed from a single monolithic file into a core agent plus reference modules to stay under the 50K character limit imposed by some runtimes:\n\n- `planner-gap-closure.md` — Gap closure mode behavior (reads VERIFICATION.md, targeted replanning)\n- `planner-reviews.md` — Cross-AI review integration (reads REVIEWS.md from `/gsd-review`)\n- `planner-revision.md` — Plan revision patterns for iterative refinement\n\n### Templates (`get-shit-done/templates/`)\n\nMarkdown templates for all planning artifacts. Used by `gsd-sdk query template.fill` / `phase.scaffold` (and legacy `gsd-tools.cjs template fill` / top-level `scaffold`) to create pre-structured files:\n- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files\n- `phase-prompt.md` — Phase execution prompt template\n- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates\n- `DEBUG.md` — Debug session tracking template\n- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Specialized verification templates\n- `discussion-log.md` — Discussion audit trail template\n- `codebase/` — Brownfield mapping templates (stack, architecture, conventions, concerns, structure, testing, integrations)\n- `research-project/` — Research output templates (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)\n\n### Hooks (`hooks/`)\n\nRuntime hooks that integrate with the host AI agent:\n\n| Hook | Event | Purpose |\n|------|-------|---------|\n| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar |\n| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining |\n| `gsd-check-update.js` | `SessionStart` | Foreground trigger for the background update check |\n| `gsd-check-update-worker.js` | (helper) | Background worker spawned by `gsd-check-update.js`; no direct event registration |\n| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) |\n| `gsd-read-injection-scanner.js` | `PostToolUse` | Scans Read tool output for injected instructions in untrusted content |\n| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |\n| `gsd-read-guard.js` | `PreToolUse` | Advisory guard preventing Edit/Write on files not yet read in the session |\n| `gsd-session-state.sh` | `PostToolUse` | Session state tracking for shell-based runtimes |\n| `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional commit enforcement |\n| `gsd-phase-boundary.sh` | `PostToolUse` | Phase boundary detection for workflow transitions |\n\nSee [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 11-hook roster.\n\n### SDK Runtime Bridge Module (`sdk/src/query-runtime-bridge.ts`)\n\nProgrammatic SDK callers (`GSDTools`) route through one seam that owns query dispatch policy:\n\n- Native registry dispatch preference\n- Explicit subprocess fallback policy (`allowFallbackToSubprocess`)\n- Strict SDK mode (`strictSdk`) for fail-fast native-only enforcement\n- Structured dispatch observability (`onDispatchEvent`) with mode, reason, duration, and outcome\n\nThis keeps callers thin adapters and centralizes transport decisions for SDK publishability.\n\n### Command Routing Hub (`get-shit-done/bin/lib/command-routing-hub.cjs`)\n\nCJS command family routers migrate to dispatch through `CommandRoutingHub` incrementally. `phase-command-router.cjs` is the first migration (issue #3788); remaining routers (`phases-command-router.cjs`, `roadmap-command-router.cjs`, etc.) continue using `routeCjsCommandFamily` until migrated in follow-up issues. The hub owns three cross-cutting concerns that each router previously duplicated: (1) mode selection (`sdk` when `tryLoadSdk()` succeeds and no `GSD_WORKSTREAM` is active, `cjs` otherwise), set once at construction; (2) a no-throw pure-result contract (`hub.dispatch()` catches all exceptions and returns `{ ok: false, errorKind, message, details }` instead of propagating); and (3) a closed six-value `errorKind` enum exported as the frozen `ERROR_KINDS` object. Router adapters remain thin CLI translators — they build the hub, call `dispatch`, then map the Result to `output()`/`error()` calls. No transparent SDK→CJS fallback: an SDK-mode hub that encounters a load or dispatch failure returns `SdkLoadFailed` or `SdkDispatchFailed` without retrying via CJS. See `docs/adr/0012-command-routing-hub.md`.\n\n### CLI Tools (`get-shit-done/bin/`)\n\nNode.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) for the authoritative roster):\n\n\n| Module | Responsibility |\n| ---------------------- | --------------------------------------------------------------------------------------------------- |\n| `core.cjs` | Error handling, output formatting, shared utilities; compatibility re-exports for planning helpers |\n| `planning-workspace.cjs` | Planning seam (`planningDir`, `planningPaths`, active workstream routing, `.planning/.lock`) |\n| `state.cjs` | STATE.md parsing, updating, progression, metrics |\n| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |\n| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |\n| `config.cjs` | config.json read/write, section initialization |\n| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |\n| `template.cjs` | Template selection and filling with variable substitution |\n| `frontmatter.cjs` | YAML frontmatter CRUD operations |\n| `init.cjs` | Compound context loading for each workflow type |\n| `milestone.cjs` | Milestone archival, requirements marking |\n| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |\n| `model-profiles.cjs` | Model profile resolution table |\n| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |\n| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |\n| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |\n| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |\n| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |\n| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |\n| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |\n\n\n---\n\n## Agent Model\n\n### Orchestrator → Agent Pattern\n\n```\nOrchestrator (workflow .md)\n │\n ├── Load context: gsd-sdk query init. (or legacy gsd-tools.cjs init)\n │ Returns JSON with: project info, config, state, phase details\n │\n ├── Resolve model: gsd-sdk query resolve-model \n │ Returns: opus | sonnet | haiku | inherit\n │\n ├── Spawn Agent (Task/SubAgent call)\n │ ├── Agent prompt (agents/*.md)\n │ ├── Context payload (init JSON)\n │ ├── Model assignment\n │ └── Tool permissions\n │\n ├── Collect result\n │\n └── Update state: gsd-sdk query state.update / state.patch / state.advance-plan (or legacy gsd-tools.cjs)\n```\n\n### Primary Agent Spawn Categories\n\nConceptual spawn-pattern taxonomy for the 21 primary agents. For the authoritative 31-agent roster (including the 10 advanced/specialized agents such as `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), see [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped).\n\n\n| Category | Agents | Parallelism |\n| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |\n| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |\n| **Planners** | gsd-planner, gsd-roadmapper | Sequential |\n| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |\n| **Executors** | gsd-executor | Parallel within waves, sequential across waves |\n| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |\n| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |\n| **Debuggers** | gsd-debugger | Sequential (interactive) |\n| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |\n| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |\n| **Profilers** | gsd-user-profiler | Sequential |\n| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |\n\n\n### Wave Execution Model\n\nDuring `execute-phase`, plans are grouped into dependency waves:\n\n```\nWave Analysis:\n Plan 01 (no deps) ─┐\n Plan 02 (no deps) ─┤── Wave 1 (parallel)\n Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1)\n Plan 04 (depends: 02) ─┘\n Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)\n```\n\nEach executor gets:\n\n- Fresh 200K context window (or up to 1M for models that support it)\n- The specific PLAN.md to execute\n- Project context (PROJECT.md, STATE.md)\n- Phase context (CONTEXT.md, RESEARCH.md if available)\n\n### Adaptive Context Enrichment (1M Models)\n\nWhen the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4.6), subagent prompts are automatically enriched with additional context that would not fit in standard 200K windows:\n\n- **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase\n- **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification\n\nThe orchestrator reads `context_window` from config (`gsd-sdk query config-get context_window`, or legacy `gsd-tools.cjs config-get`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.\n\n#### Parallel Commit Safety\n\nWhen multiple executors run within the same wave, two mechanisms prevent conflicts:\n\n1. `--no-verify` commits — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.\n2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter.\n\n---\n\n## Data Flow\n\n### New Project Flow\n\n```\nUser input (idea description)\n │\n ▼\nQuestions (questioning.md philosophy)\n │\n ▼\n4x Project Researchers (parallel)\n ├── Stack → STACK.md\n ├── Features → FEATURES.md\n ├── Architecture → ARCHITECTURE.md\n └── Pitfalls → PITFALLS.md\n │\n ▼\nResearch Synthesizer → SUMMARY.md\n │\n ▼\nRequirements extraction → REQUIREMENTS.md\n │\n ▼\nRoadmapper → ROADMAP.md\n │\n ▼\nUser approval → STATE.md initialized\n```\n\n### Phase Execution Flow\n\n```\ndiscuss-phase → CONTEXT.md (user preferences)\n │\n ▼\nui-phase → UI-SPEC.md (design contract, optional)\n │\n ▼\nplan-phase\n ├── Research gate (blocks if RESEARCH.md has unresolved open questions)\n ├── Phase Researcher → RESEARCH.md\n │ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,\n │ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md\n ├── Planner (with reachability check) → PLAN.md files\n │ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;\n │ T-{phase}-SC STRIDE row added for install-bearing plans\n ├── Plan Checker → Verify loop (max 3x)\n ├── Requirements coverage gate (REQ-IDs → plans)\n └── Decision coverage gate (CONTEXT.md `` → plans, BLOCKING — #2492)\n │\n ▼\nstate planned-phase → STATE.md (Planned/Ready to execute)\n │\n ▼\nexecute-phase (context reduction: truncated prompts, cache-friendly ordering)\n ├── Wave analysis (dependency grouping)\n ├── Executor per plan → code + atomic commits\n ├── SUMMARY.md per plan\n └── Verifier → VERIFICATION.md\n └── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)\n │\n ▼\nverify-work → UAT.md (user acceptance testing)\n │\n ▼\nui-review → UI-REVIEW.md (visual audit, optional)\n```\n\n### Context Propagation\n\nEach workflow stage produces artifacts that feed into subsequent stages:\n\n```\nPROJECT.md ────────────────────────────────────────────► All agents\nREQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor\nROADMAP.md ────────────────────────────────────────────► Orchestrators\nSTATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)\nCONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor\nRESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker\nPLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker\nSUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking\nUI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor\n```\n\n---\n\n## File System Layout\n\n### Installation Files\n\n```\n~/.claude/ # Claude Code (global install)\n├── skills/gsd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)\n├── commands/gsd/*.md # Local Claude installs use slash commands instead of global skills\n├── get-shit-done/\n│ ├── bin/gsd-tools.cjs # CLI utility\n│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)\n│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)\n│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)\n│ └── templates/ # Planning artifact templates\n├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)\n├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)\n├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)\n├── settings.json # Hook registrations\n└── VERSION # Installed version number\n```\n\nEquivalent paths for other runtimes:\n\n- **OpenCode:** `~/.config/opencode/` global or `./.opencode/` local\n- **Kilo:** `~/.config/kilo/` global or `./.kilo/` local\n- **Gemini CLI:** `~/.gemini/` global or `./.gemini/` local\n- **Codex:** `~/.codex/` global or `./.codex/` local\n- **Copilot:** `~/.copilot/` global or `./.github/` local\n- **Antigravity:** `~/.gemini/antigravity/` global or `./.agent/` local\n- **Cursor:** `~/.cursor/` global or `./.cursor/` local\n- **Windsurf:** `~/.codeium/windsurf/` global or `./.windsurf/` local\n- **Augment Code:** `~/.augment/` global or `./.augment/` local\n- **Trae:** `~/.trae/` global or `./.trae/` local\n- **Qwen Code:** `~/.qwen/` global or `./.qwen/` local\n- **Hermes Agent:** `~/.hermes/` global or `./.hermes/` local\n- **CodeBuddy:** `~/.codebuddy/` global or `./.codebuddy/` local\n- **Cline:** `~/.cline/` global or project-root `.clinerules` local\n\n### Project Files (`.planning/`)\n\n```\n.planning/\n├── PROJECT.md # Project vision, constraints, decisions, evolution rules\n├── REQUIREMENTS.md # Scoped requirements (v1/v2/out-of-scope)\n├── ROADMAP.md # Phase breakdown with status tracking\n├── STATE.md # Living memory: position, decisions, blockers, metrics\n├── config.json # Workflow configuration\n├── MILESTONES.md # Completed milestone archive\n├── research/ # Domain research from /gsd-new-project\n│ ├── SUMMARY.md\n│ ├── STACK.md\n│ ├── FEATURES.md\n│ ├── ARCHITECTURE.md\n│ └── PITFALLS.md\n├── codebase/ # Brownfield mapping (from /gsd-map-codebase)\n│ ├── STACK.md # YAML frontmatter carries `last_mapped_commit`\n│ ├── ARCHITECTURE.md # for the post-execute drift gate (#2003)\n│ ├── CONVENTIONS.md\n│ ├── CONCERNS.md\n│ ├── STRUCTURE.md\n│ ├── TESTING.md\n│ └── INTEGRATIONS.md\n├── phases/\n│ └── XX-phase-name/\n│ ├── XX-CONTEXT.md # User preferences (from discuss-phase)\n│ ├── XX-RESEARCH.md # Ecosystem research (from plan-phase)\n│ ├── XX-YY-PLAN.md # Execution plans\n│ ├── XX-YY-SUMMARY.md # Execution outcomes\n│ ├── XX-VERIFICATION.md # Post-execution verification\n│ ├── XX-VALIDATION.md # Nyquist test coverage mapping\n│ ├── XX-UI-SPEC.md # UI design contract (from ui-phase)\n│ ├── XX-UI-REVIEW.md # Visual audit scores (from ui-review)\n│ └── XX-UAT.md # User acceptance test results\n├── quick/ # Quick task tracking\n│ └── YYMMDD-xxx-slug/\n│ ├── PLAN.md\n│ └── SUMMARY.md\n├── todos/\n│ ├── pending/ # Captured ideas\n│ └── done/ # Completed todos\n├── threads/ # Persistent context threads (from /gsd-thread)\n├── seeds/ # Forward-looking ideas (from /gsd-capture --seed)\n├── debug/ # Active debug sessions\n│ ├── *.md # Active sessions\n│ ├── resolved/ # Archived sessions\n│ └── knowledge-base.md # Persistent debug learnings\n├── ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)\n└── continue-here.md # Context handoff (from pause-work)\n```\n\n### Post-Execute Codebase Drift Gate (#2003)\n\nAfter the last wave of `/gsd-execute-phase` commits, the workflow runs a\nnon-blocking `codebase_drift_gate` step (between `schema_drift_gate` and\n`verify_phase_goal`). It compares the diff `last_mapped_commit..HEAD`\nagainst `.planning/codebase/STRUCTURE.md` and counts four kinds of\nstructural elements:\n\n1. New directories outside mapped paths\n2. New barrel exports at `(packages|apps)//src/index.*`\n3. New migration files\n4. New route modules under `routes/` or `api/`\n\nIf the count meets `workflow.drift_threshold` (default 3), the gate either\n**warns** (default) with the suggested `/gsd-map-codebase --paths …` command,\nor **auto-remaps** (`workflow.drift_action = auto-remap`) by spawning\n`gsd-codebase-mapper` scoped to the affected paths. Any error in detection\nor remap is logged and the phase continues — drift detection cannot fail\nverification.\n\n`last_mapped_commit` lives in YAML frontmatter at the top of each\n`.planning/codebase/*.md` file; `bin/lib/drift.cjs` provides\n`readMappedCommit` and `writeMappedCommit` round-trip helpers.\n\n---\n\n## Installer Architecture\n\nThe installer (`bin/install.js`, ~10,700 lines) handles:\n\n1. **Runtime detection** — Interactive prompt or CLI flags (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--augment`, `--trae`, `--qwen`, `--hermes`, `--codebuddy`, `--cline`, `--all`)\n2. **Location selection** — Global (`--global`) or local (`--local`)\n3. **File deployment** — Copies commands, skills, workflows, references, templates, agents, and hooks\n4. **Runtime adaptation** — Transforms file content per runtime:\n - Claude Code: Uses as-is\n - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format\n - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths\n - Codex: Generates TOML config + skills from commands\n - Copilot: Maps tool names (Read→read, Bash→execute, etc.)\n - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)\n - Antigravity: Skills-first with Google model equivalents\n - Cursor: Skills-first with Cursor rule references\n - Windsurf: Skills-first with Windsurf rule references\n - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration\n - Qwen Code: Skills-first with Qwen-branded path and prompt rewrites\n - Hermes Agent: Category-based skills under `skills/gsd/`\n - CodeBuddy: Skills-first with CodeBuddy path and prompt rewrites\n - Cline: Writes `.clinerules` for rule-based integration\n - Augment Code: Skills-first with full skill conversion and config management\n5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths\n6. **Settings integration** — Registers hooks in runtime's `settings.json`\n7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-update --reapply`\n8. **Manifest tracking** — Writes `gsd-file-manifest.json` for clean uninstall\n9. **Uninstall mode** — `--uninstall` removes all GSD files, hooks, and settings\n\nInstall-time file moves, stale-artifact cleanup, config rewrites, and user-data\npreservation are governed by the Installer Migration Module. See\n[Installer Migrations](installer-migrations.md) and\n[ADR 0008](adr/0008-installer-migration-module.md).\nThe migration module also owns the gated first-time baseline scan for legacy\ninstalls, classifying known runtime install surfaces before later migrations\nremove or rewrite anything.\n\n### Platform Handling\n\n- **Windows:** `windowsHide` on child processes, EPERM/EACCES protection on protected directories, path separator normalization\n- **WSL:** Detects Windows Node.js running on WSL and warns about path mismatches\n- **Docker/CI:** Supports `CLAUDE_CONFIG_DIR` env var for custom config directory locations\n\n---\n\n## Hook System\n\n### Architecture\n\n```\nRuntime Engine (Claude Code / Gemini CLI)\n │\n ├── statusLine event ──► gsd-statusline.js\n │ Reads: stdin (session JSON)\n │ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)\n │\n ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js\n │ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)\n │ Writes: stdout (hookSpecificOutput with additionalContext warning)\n │\n └── SessionStart event ──► gsd-check-update.js\n Reads: VERSION file\n Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)\n```\n\n### Context Monitor Thresholds\n\n\n| Remaining Context | Level | Agent Behavior |\n| ----------------- | -------- | --------------------------------------- |\n| > 35% | Normal | No warning injected |\n| ≤ 35% | WARNING | \"Avoid starting new complex work\" |\n| ≤ 25% | CRITICAL | \"Context nearly exhausted, inform user\" |\n\n\nDebounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce.\n\n### Safety Properties\n\n- All hooks wrap in try/catch, exit silently on error\n- stdin timeout guard (3s) prevents hanging on pipe issues\n- Stale metrics (>60s old) are ignored\n- Missing bridge files handled gracefully (subagents, fresh sessions)\n- Context monitor is advisory — never issues imperative commands that override user preferences\n\n### Package Legitimacy Gate (v1.42.1)\n\nThe researcher → planner → executor pipeline includes a supply-chain gate against slopsquatting (AI-hallucinated package names pre-registered with malicious post-install scripts).\n\n**Threat model:** GSD automates the full path from \"researcher names a package\" to \"executor runs `npm install`\". A hallucinated name that passes `npm view` (proving only registration, not legitimacy) would previously flow through undetected. ~20% of AI-generated package references are hallucinated; ~43% of those names recur consistently across prompts, making pre-registration economically viable for attackers.\n\n**Gate layers:**\n\n| Layer | Component | Action |\n|-------|-----------|--------|\n| Research | `gsd-phase-researcher` | Runs `slopcheck install --json`; writes `## Package Legitimacy Audit` table to RESEARCH.md; strips `[SLOP]` packages before RESEARCH.md is written |\n| Planning | `gsd-planner` | Reads Audit table; inserts `checkpoint:human-verify` before any `[ASSUMED]` or `[SUS]` install task; adds `T-{phase}-SC` STRIDE supply-chain row to `` |\n| Execution | `gsd-executor` | RULE 3 excludes package installation from auto-fix scope; failed installs surface as checkpoints, never silent substitutions |\n\n**Claim provenance integration:** Package names discovered via WebSearch are tagged `[ASSUMED]` (not `[VERIFIED]`) regardless of `npm view` result. This extends the existing `[ASSUMED]` / `[VERIFIED]` / `[CITED]` provenance system by enforcing the provenance tag as a hard gate at the install boundary — `[ASSUMED]` always generates a `checkpoint:human-verify` in PLAN.md.\n\n**Ecosystem coverage:** The researcher uses registry-specific verification commands — `npm view` (Node), `pip index versions` (Python), `cargo search` (Rust) — rather than a single generic check. This catches cross-ecosystem hallucination (~9% rate documented in 2025 USENIX research).\n\n**Graceful degradation:** If `slopcheck` is unavailable, every recommended package is tagged `[ASSUMED]` and gated with a checkpoint. Research and planning proceed; the system never hard-fails on a missing tool dependency.\n\n**External dependency:** `slopcheck` (MIT, pip-installable). If abandoned, the `[ASSUMED]`-gate fallback maintains human-checkpoint coverage.\n\n---\n\n### Security Hooks (v1.27)\n\n**Prompt Guard** (`gsd-prompt-guard.js`):\n\n- Triggers on Write/Edit to `.planning/` files\n- Scans content for prompt injection patterns (role override, instruction bypass, system tag injection)\n- Advisory-only — logs detection, does not block\n- Patterns are inlined (subset of `security.cjs`) for hook independence\n\n**Workflow Guard** (`gsd-workflow-guard.js`):\n\n- Triggers on Write/Edit to non-`.planning/` files\n- Detects edits outside GSD workflow context (no active `/gsd-` command or Task subagent)\n- Advises using `/gsd-quick` or `/gsd-fast` for state-tracked changes\n- Opt-in via `hooks.workflow_guard: true` (default: false)\n\n---\n\n## Runtime Abstraction\n\nGSD supports multiple AI coding runtimes through a unified command/workflow architecture:\n\n### Runtime Install Contract Matrix\n\nThis matrix describes the runtime surfaces the installer materializes today.\nThe migration-specific ownership and source snapshots live in\n[Installer Migrations](installer-migrations.md#runtime-configuration-contract-registry).\n\n| Runtime | Global root | Local root | Invocation surface | Agent surface | Config and hooks |\n| --- | --- | --- | --- | --- | --- |\n| Claude Code | `~/.claude` | `./.claude` | Global `skills/gsd-*/SKILL.md`; local `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` hook and statusLine entries |\n| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` or `opencode.jsonc`; no GSD hooks |\n| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` or `kilo.jsonc`; no GSD hooks |\n| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` feature flag, hooks, and statusline |\n| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | `agents/` source markdown plus per-agent TOML | `config.toml` `[agents.gsd-*]`, `[features].hooks` (canonical; legacy alias `codex_hooks` is recognized and migrated forward on reinstall, #3566), and hook tables |\n| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` and `copilot-instructions.md` | `.agent.md` files | No GSD hooks or statusline |\n| Antigravity | `~/.gemini/antigravity` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Gemini-style `settings.json` hook entries when installed by GSD |\n| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | No GSD hooks or statusline |\n| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` plus `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Cline | `~/.cline` | project root | `.clinerules` | Rules only | No GSD hooks or statusline |\n\n### Upstream Contract Sources\n\nRuntime install expectations are checked against primary documentation where\navailable. The current source snapshot is 2026-05-11:\n\n- Claude Code: Anthropic slash commands, settings, hooks, and subagents docs.\n- OpenCode and Kilo: OpenCode config docs and Kilo custom subagent docs.\n- Gemini CLI and Qwen Code: command/config docs; Qwen command docs were last\n updated 2026-05-06.\n- Codex: OpenAI Codex docs and `config-schema.json`; the installer also carries\n Codex 0.124.0 compatibility for agent table shape.\n- Copilot, Cursor, Cline, Augment, Hermes, and CodeBuddy: vendor docs for\n custom instructions, rules, skills, or config.\n- Antigravity, Windsurf, and Trae: source-limited rows. The installer documents\n current compatibility shims, and migrations must refresh those sources before\n rewriting their config.\n\n### Abstraction Points\n\n1. **Tool name mapping** — Each runtime has its own tool names (e.g., Claude's `Bash` → Copilot's `execute`)\n2. **Hook event names** — Claude uses `PostToolUse`, Gemini uses `AfterTool`\n3. **Agent frontmatter** — Each runtime has its own agent definition format\n4. **Path conventions** — Each runtime stores config in different directories\n5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection\n\nThe installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.\n","isInternal":false,"tokens":10817,"sizeBytes":48290}],"systemPromptSnippet":"\n\n# Repository Guidelines\n\n## Active Discussions\n\nFor current work on **Grok Build compatibility** and multi-runtime synchronization across Grok Build, Claude Code, Gemini CLI, and Codex, see:\n\n- `docs/discussions/grok-build-support-2026-05.md`\n\n## Project Structure & Module Organization\n\nThis repository ships GSD as a Node.js CLI and SDK. Root package entry points live in `bin/`, scripts in `scripts/`, runtime hooks in `hooks/`, command definitions in `commands/gsd/`, and workflow/template content in `get-shit-done/`. Agent role files are in `agents/`; docs are in `docs/`; logos and terminal images are in `assets/`. Root tests are in `tests/*.test.cjs`. The TypeScript SDK is isolated under `sdk/`, with source and Vitest tests in `sdk/src/`.\n\n## Build, Test, and Development Commands\n\nUse Node.js `>=22`.\n\n- `npm install`: install root dependencies.\n- `npm test`: builds the SDK first, then runs root `node:test` suites via `scripts/run-tests.cjs`.\n- `npm run test:coverage`: runs root tests with `c8` and enforces 70% line coverage for included CommonJS library files.\n- `npm run build:hooks`: rebuilds generated hook artifacts.\n- `npm run build:sdk`: installs SDK dependencies and builds TypeScript.\n- `cd sdk && npm test`: runs SDK Vitest unit and integration projects.\n- `cd sdk && npm run build`: type-checks and emits `sdk/dist/`.\n\n## Coding Style & Naming Conventions\n\nMatch the existing style in the edited area. Root JavaScript is CommonJS, generally strict-mode, two-space indentation, semicolons, `const`/`let`, and `node:` imports for built-ins. SDK code is strict TypeScript using ESM/`NodeNext`. Keep command, workflow, and test filenames kebab-case, for example `commands/gsd/plan-phase.md` and `tests/bug-2396-makefile-test-priority.test.cjs`. Agent files use `gsd-*.md`. Avoid unrelated formatting and unnecessary dependencies.\n\n## Testing Guidelines\n\nRoot tests use Node’s built-in `node:test` and `node:assert/strict`; do not add Jest, Mocha, or Chai. Prefer helpers from `tests/helpers.cjs` for temporary projects, cleanup, and CLI execution. Name root tests `*.test.cjs`; run one with `node --test tests/name.test.cjs`. SDK tests use Vitest with `*.test.ts` for unit tests and `*.integration.test.ts` for integration tests.\n\n## Commit & Pull Request Guidelines\n\nRecent history follows Conventional Commit prefixes such as `fix:`, `feat:`, and `ci:`, often with issue references: `fix(#2623): resolve parent .planning root...`. Keep commits scoped and descriptive.\n\nEvery PR must link an approved or confirmed issue with `Closes #123`, `Fixes #123`, or `Resolves #123`. Use the matching template in `.github/PULL_REQUEST_TEMPLATE/`. Include behavior changes, root cause when relevant, test evidence, affected platforms/runtimes, and update `CHANGELOG.md` or docs for user-facing changes.\n\n## Security & Configuration Tips\n\nDo not commit secrets, local config, or generated worktree artifacts. Before release-facing changes, run the relevant scan scripts in `scripts/`, especially `secret-scan.sh`, `base64-scan.sh`, and `prompt-injection-scan.sh`.\n\n\n# GSD Agent Reference\n\n> Full role cards for 21 primary agents plus concise stubs for 12 advanced/specialized agents (33 shipped agents total). The `agents/` directory and [`docs/INVENTORY.md`](INVENTORY.md) are the authoritative roster; see [Architecture](ARCHITECTURE.md) for context.\n\n---\n\n## Overview\n\nGSD uses a multi-agent architecture where thin orchestrators (workflow files) spawn specialized agents with fresh context windows. Each agent has a focused role, limited tool access, and produces specific artifacts.\n\n### Agent Categories\n\n> The table below covers the **21 primary agents** detailed in this section. Twelve additional shipped agents (pattern-mapper, debug-session-manager, code-reviewer, code-fixer, ai-researcher, domain-researcher, eval-planner, eval-auditor, framework-selector, intel-updater, doc-classifier, doc-synthesizer) have concise stubs in the [Advanced and Specialized Agents](#advanced-and-specialized-agents) section below. For the authoritative 33-agent roster, see [`docs/INVENTORY.md`](INVENTORY.md) and the `agents/` directory.\n\n| Category | Count | Agents |\n|----------|-------|--------|\n| Researchers | 3 | project-researcher, phase-researcher, ui-researcher |\n| Analyzers | 2 | assumptions-analyzer, advisor-researcher |\n| Synthesizers | 1 | research-synthesizer |\n| Planners | 1 | planner |\n| Roadmappers | 1 | roadmapper |\n| Executors | 1 | executor |\n| Checkers | 3 | plan-checker, integration-checker, ui-checker |\n| Verifiers | 1 | verifier |\n| Auditors | 3 | nyquist-auditor, ui-auditor, security-auditor |\n| Mappers | 1 | codebase-mapper |\n| Debuggers | 1 | debugger |\n| Doc Writers | 2 | doc-writer, doc-verifier |\n| Profilers | 1 | user-profiler |\n\n---\n\n## Agent Details\n\n### gsd-project-researcher\n\n**Role:** Researches domain ecosystem before roadmap creation.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project`, `/gsd-new-milestone` |\n| **Parallelism** | 4 instances (stack, features, architecture, pitfalls) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |\n\n**Capabilities:**\n- Web search for current ecosystem information\n- Context7 MCP integration for library documentation\n- Writes research documents directly to disk (reduces orchestrator context load)\n\n---\n\n### gsd-phase-researcher\n\n**Role:** Researches how to implement a specific phase before planning.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` |\n| **Parallelism** | 4 instances (same focus areas as project researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Produces** | `{phase}-RESEARCH.md` |\n\n**Capabilities:**\n- Reads CONTEXT.md to focus research on user's decisions\n- Investigates implementation patterns for the specific phase domain\n- Detects test infrastructure for Nyquist validation mapping\n\n---\n\n### gsd-ui-researcher\n\n**Role:** Produces UI design contracts for frontend phases.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#E879F9` (fuchsia) |\n| **Produces** | `{phase}-UI-SPEC.md` |\n\n**Capabilities:**\n- Detects design system state (shadcn components.json, Tailwind config, existing tokens)\n- Offers shadcn initialization for React/Next.js/Vite projects\n- Asks only unanswered design contract questions\n- Enforces registry safety gate for third-party components\n\n---\n\n### gsd-assumptions-analyzer\n\n**Role:** Deeply analyzes codebase for a phase and returns structured assumptions with evidence, confidence levels, and consequences if wrong.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase-assumptions` workflow (when `workflow.discuss_mode = 'assumptions'`) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | Structured assumptions with decision statements, evidence file paths, confidence levels |\n\n**Key behaviors:**\n- Reads ROADMAP.md phase description and prior CONTEXT.md files\n- Searches codebase for files related to the phase (components, patterns, similar features)\n- Reads 5-15 most relevant source files to form evidence-based assumptions\n- Classifies confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways)\n- Flags topics that need external research (library compatibility, ecosystem best practices)\n- Output calibrated by tier: full_maturity (3-5 areas), standard (3-4), minimal_decisive (2-3)\n\n---\n\n### gsd-advisor-researcher\n\n**Role:** Researches a single gray area decision during discuss-phase advisor mode and returns a structured comparison table.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `discuss-phase` workflow (when ADVISOR_MODE = true) |\n| **Parallelism** | Multiple instances (one per gray area) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | 5-column comparison table (Option / Pros / Cons / Complexity / Recommendation) with rationale paragraph |\n\n**Key behaviors:**\n- Researches a single assigned gray area using Claude's knowledge, Context7, and web search\n- Produces genuinely viable options — no padding with filler alternatives\n- Complexity column uses impact surface + risk (never time estimates)\n- Recommendations are conditional (\"Rec if X\", \"Rec if Y\") — never single-winner ranking\n- Output calibrated by tier: full_maturity (3-5 options with maturity signals), standard (2-4), minimal_decisive (2 options, decisive recommendation)\n\n---\n\n### gsd-research-synthesizer\n\n**Role:** Combines outputs from parallel researchers into a unified summary.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` (after 4 researchers complete) |\n| **Parallelism** | Single instance (sequential after researchers) |\n| **Tools** | Read, Write, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `.planning/research/SUMMARY.md` |\n\n---\n\n### gsd-planner\n\n**Role:** Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase`, `/gsd-quick` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep, WebFetch, mcp (context7) |\n| **Model (balanced)** | Opus |\n| **Color** | Green |\n| **Produces** | `{phase}-{N}-PLAN.md` files |\n\n**Key behaviors:**\n- Reads PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md\n- Creates 2-3 atomic task plans sized for single context windows\n- Uses XML structure with `` elements\n- Includes `read_first` and `acceptance_criteria` sections\n- Groups plans into dependency waves\n- Performs reachability check to validate plan steps reference accessible files and APIs (v1.32)\n\n---\n\n### gsd-roadmapper\n\n**Role:** Creates project roadmaps with phase breakdown and requirement mapping.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-new-project` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | `ROADMAP.md` |\n\n**Key behaviors:**\n- Maps requirements to phases (traceability)\n- Derives success criteria from requirements\n- Respects granularity setting for phase count\n- Validates coverage (every v1 requirement mapped to a phase)\n\n---\n\n### gsd-executor\n\n**Role:** Executes GSD plans with atomic commits, deviation handling, and checkpoint protocols.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase`, `/gsd-quick` |\n| **Parallelism** | Multiple (parallel within waves, sequential across waves) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Yellow |\n| **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` |\n\n**Key behaviors:**\n- Fresh 200K context window per plan\n- Follows XML task instructions precisely\n- Atomic git commit per completed task\n- Handles checkpoint types: auto, human-verify, decision, human-action\n- Reports deviations from plan in SUMMARY.md\n- Invokes node repair on verification failure\n\n---\n\n### gsd-plan-checker\n\n**Role:** Verifies plans will achieve phase goals before execution.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (verification loop, max 3 iterations) |\n| **Parallelism** | Single instance (iterative) |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | PASS/FAIL verdict with specific feedback |\n\n**8 Verification Dimensions:**\n1. Requirement coverage\n2. Task atomicity\n3. Dependency ordering\n4. File scope\n5. Verification commands\n6. Context fit\n7. Gap detection\n8. Nyquist compliance (when enabled)\n\n---\n\n### gsd-integration-checker\n\n**Role:** Verifies cross-phase integration and end-to-end flows.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-audit-milestone` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Blue |\n| **Produces** | Integration verification report |\n\n---\n\n### gsd-ui-checker\n\n**Role:** Validates UI-SPEC.md design contracts against quality dimensions.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-phase` (validation loop, max 2 iterations) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#22D3EE` (cyan) |\n| **Produces** | BLOCK/FLAG/PASS verdict |\n\n---\n\n### gsd-verifier\n\n**Role:** Verifies phase goal achievement through goal-backward analysis.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-execute-phase` (after all executors complete) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Green |\n| **Produces** | `{phase}-VERIFICATION.md` |\n\n**Key behaviors:**\n- Checks codebase against phase goals, not just task completion\n- PASS/FAIL with specific evidence\n- Logs issues for `/gsd-verify-work` to address\n- Milestone scope filtering: gaps addressed in later phases are marked as \"deferred\", not reported as failures (v1.32)\n- **Test quality audit** (v1.32): verifies that tests prove what they claim by checking for disabled/skipped tests on requirements, circular test patterns (system generating its own expected values), assertion strength (existence vs. value vs. behavioral), and expected value provenance. Blockers from test quality audit override an otherwise passing verification\n\n---\n\n### gsd-nyquist-auditor\n\n**Role:** Fills Nyquist validation gaps by generating tests.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-validate-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Produces** | Test files, updated `VALIDATION.md` |\n\n**Key behaviors:**\n- Never modifies implementation code — only test files\n- Max 3 attempts per gap\n- Flags implementation bugs as escalations for user\n\n---\n\n### gsd-ui-auditor\n\n**Role:** Retroactive 6-pillar visual audit of implemented frontend code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ui-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F472B6` (pink) |\n| **Produces** | `{phase}-UI-REVIEW.md` with scores |\n\n**6 Audit Pillars (scored 1-4):**\n1. Copywriting\n2. Visuals\n3. Color\n4. Typography\n5. Spacing\n6. Experience Design\n\n---\n\n### gsd-codebase-mapper\n\n**Role:** Explores codebase and writes structured analysis documents.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase`, post-execute drift gate in `/gsd-execute-phase` |\n| **Parallelism** | 4 instances (tech, architecture, quality, concerns) |\n| **Tools** | Read, Bash, Grep, Glob, Write |\n| **Model (balanced)** | Haiku |\n| **Color** | Cyan |\n| **Produces** | `.planning/codebase/*.md` (7 documents, with `last_mapped_commit` frontmatter) |\n\n**Key behaviors:**\n- Read-only exploration + structured output\n- Writes documents directly to disk\n- No reasoning required — pattern extraction from file contents\n\n**`--paths ` scope hint (#2003):**\nAccepts an optional `--paths` directive in its prompt. When present, the\nmapper restricts Glob/Grep/Bash exploration to the listed repo-relative path\nprefixes — this is the incremental-remap path used by the post-execute\ncodebase-drift gate. Path values that contain `..`, start with `/`, or\ninclude shell metacharacters are rejected. Without the hint, the mapper\nruns its default whole-repo scan.\n\n---\n\n### gsd-debugger\n\n**Role:** Investigates bugs using scientific method with persistent state.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug`, `/gsd-verify-work` (for failures) |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | `.planning/debug/*.md`, knowledge-base updates |\n\n**Debug Session Lifecycle:**\n`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved`\n\n**Key behaviors:**\n- Tracks hypotheses, evidence, and eliminated theories\n- State persists across context resets\n- Requires human verification before marking resolved\n- Appends to persistent knowledge base on resolution\n- Consults knowledge base on new sessions\n\n---\n\n### gsd-user-profiler\n\n**Role:** Analyzes session messages across 8 behavioral dimensions to produce a scored developer profile.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-profile-user` |\n| **Parallelism** | Single instance |\n| **Tools** | Read |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `USER-PROFILE.md`, `CLAUDE.md` profile section |\n\n**Behavioral Dimensions:**\nCommunication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth.\n\n**Key behaviors:**\n- Read-only agent — analyzes extracted session data, does not modify files\n- Produces scored dimensions with confidence levels and evidence citations\n- Questionnaire fallback when session history is unavailable\n\n---\n\n### gsd-doc-writer\n\n**Role:** Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode, and project context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` |\n| **Parallelism** | Multiple instances (one per doc type) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Purple |\n| **Produces** | Project documentation files (README, architecture, API docs, etc.) |\n\n**Key behaviors:**\n- Supports modes: create, update, supplement, fix\n- Handles doc types: readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing, custom\n- Monorepo-aware: can generate per-package READMEs\n- Fix mode accepts failure objects from gsd-doc-verifier for targeted corrections\n- Writes directly to disk — does not return content to orchestrator\n\n---\n\n### gsd-doc-verifier\n\n**Role:** Verifies factual claims in generated documentation against the live codebase.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-docs-update` (after doc-writer completes) |\n| **Parallelism** | Multiple instances (one per doc file) |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Structured JSON verification results per doc |\n\n**Key behaviors:**\n- Extracts checkable claims (file paths, function names, CLI commands, config keys)\n- Verifies each claim against filesystem using tools only — no assumptions\n- Writes structured JSON result file for orchestrator to process\n- Failed claims feed back to doc-writer in fix mode\n\n---\n\n### gsd-security-auditor\n\n**Role:** Verifies threat mitigations from PLAN.md threat model exist in implemented code.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-secure-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Edit, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `{phase}-SECURITY.md` |\n\n**Key behaviors:**\n- Verifies each threat by its declared disposition (mitigate / accept / transfer)\n- Does NOT scan blindly for new vulnerabilities — verifies declared mitigations only\n- Implementation files are read-only — never patches implementation code\n- Unmitigated threats reported as OPEN_THREATS or ESCALATE\n- Supports ASVS levels 1/2/3 for verification depth\n\n---\n\n## Advanced and Specialized Agents\n\nTwelve additional agents ship under `agents/gsd-*.md` and are used by specialty workflows (`/gsd-ai-integration-phase`, `/gsd-eval-review`, `/gsd-code-review`, `/gsd-code-review --fix`, `/gsd-debug`, `/gsd-map-codebase --query`, `/gsd-ingest-docs`) and by the planner pipeline. Each carries full frontmatter in its agent file; the stubs below are concise by design. The authoritative roster (with spawner and primary-doc status per agent) lives in [`docs/INVENTORY.md`](INVENTORY.md).\n\n### gsd-pattern-mapper\n\n**Role:** Read-only codebase analysis that maps files-to-be-created or modified to their closest existing analogs, producing `PATTERNS.md` for the planner to consume.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-plan-phase` (between research and planning) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Bash, Glob, Grep, Write |\n| **Model (balanced)** | Sonnet |\n| **Color** | Magenta |\n| **Produces** | `PATTERNS.md` in the phase directory |\n\n**Key behaviors:**\n- Extracts file list from CONTEXT.md and RESEARCH.md; classifies each by role (controller, component, service, model, middleware, utility, config, test) and data flow (CRUD, streaming, file I/O, event-driven, request-response)\n- Searches for the closest existing analog per file and extracts concrete code excerpts (imports, auth patterns, core pattern, error handling)\n- Strictly read-only against source; only writes `PATTERNS.md`\n\n---\n\n### gsd-debug-session-manager\n\n**Role:** Runs the full `/gsd-debug` checkpoint-and-continuation loop in an isolated context so the orchestrator's main context stays lean; spawns `gsd-debugger` agents, dispatches specialist skills, and handles user checkpoints via AskUserQuestion.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-debug` |\n| **Parallelism** | Single instance (interactive, stateful) |\n| **Tools** | Read, Write, Bash, Grep, Glob, Task, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Compact summary returned to main context; evolves the `.planning/debug/{slug}.md` session file |\n\n**Key behaviors:**\n- Reads the debug session file first; passes file paths (not inlined contents) to spawned agents to respect context budget\n- Treats all user-supplied AskUserQuestion content as data-only, wrapped in DATA_START/DATA_END markers\n- Coordinates TDD gates and reasoning checkpoints introduced in v1.36.0\n\n---\n\n### gsd-code-reviewer\n\n**Role:** Reviews source files for bugs, security vulnerabilities, and code-quality problems; produces a structured `REVIEW.md` with severity-classified findings.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review` |\n| **Parallelism** | Typically single instance per review scope |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | `REVIEW.md` in the phase directory |\n\n**Key behaviors:**\n- Detects bugs (logic errors, null/undefined checks, off-by-one, type mismatches, unreachable code), security issues (injection, XSS, hardcoded secrets, insecure crypto), and quality issues\n- Honors `CLAUDE.md` project conventions and `.claude/skills/` / `.agents/skills/` rules when present\n- Read-only against implementation source — never modifies code under review\n\n---\n\n### gsd-code-fixer\n\n**Role:** Applies fixes to findings from `REVIEW.md` with intelligent (non-blind) patching and atomic per-fix commits; produces `REVIEW-FIX.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-code-review --fix` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Edit, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#10B981` (emerald) |\n| **Produces** | `REVIEW-FIX.md`; one atomic git commit per applied fix |\n\n**Key behaviors:**\n- Treats `REVIEW.md` suggestions as guidance, not a patch to apply literally\n- Commits each fix atomically so review and rollback stay granular\n- Honors `CLAUDE.md` and project-skill rules during fixes\n\n---\n\n### gsd-ai-researcher\n\n**Role:** Researches a chosen AI/LLM framework's official documentation and distills it into implementation-ready guidance — framework quick reference, patterns, and pitfalls — for the Section 3–4b body of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential with domain-researcher / eval-planner) |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#34D399` (green) |\n| **Produces** | Sections 3–4b of `AI-SPEC.md` (framework quick reference + implementation guidance) |\n\n**Key behaviors:**\n- Uses Context7 MCP when available; falls back to the `ctx7` CLI via Bash when MCP tools are stripped from the agent\n- Anchors guidance to the specific use case, not generic framework overviews\n\n---\n\n### gsd-domain-researcher\n\n**Role:** Surfaces the business-domain and real-world evaluation context for an AI system — expert rubric ingredients, failure modes, regulatory context — before the eval-planner turns it into measurable rubrics. Writes Section 1b of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#A78BFA` (violet) |\n| **Produces** | Section 1b of `AI-SPEC.md` |\n\n**Key behaviors:**\n- Researches the domain, not the technical framework — its output feeds the eval-planner downstream\n- Produces rubric ingredients that downstream evaluators can turn into measurable criteria\n\n---\n\n### gsd-eval-planner\n\n**Role:** Designs the structured evaluation strategy for an AI phase — failure modes, eval dimensions with rubrics, tooling, reference dataset, guardrails, production monitoring. Writes Sections 5–7 of `AI-SPEC.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (sequential after domain-researcher) |\n| **Tools** | Read, Write, Bash, Grep, Glob, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#F59E0B` (amber) |\n| **Produces** | Sections 5–7 of `AI-SPEC.md` (Evaluation Strategy, Guardrails, Production Monitoring) |\n\n**Required reading:** `get-shit-done/references/ai-evals.md` (evaluation framework).\n\n**Key behaviors:**\n- Turns domain-researcher rubric ingredients into measurable, tooled evaluation criteria\n- Does not re-derive domain context — reads Section 1 and 1b of `AI-SPEC.md` as established input\n\n---\n\n### gsd-eval-auditor\n\n**Role:** Retroactive audit of an implemented AI phase's evaluation coverage against its planned `AI-SPEC.md` eval strategy. Scores each eval dimension `COVERED` / `PARTIAL` / `MISSING` and produces `EVAL-REVIEW.md`.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-eval-review` |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Grep, Glob |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#EF4444` (red) |\n| **Produces** | `EVAL-REVIEW.md` with dimension scores, findings, and remediation guidance |\n\n**Required reading:** `get-shit-done/references/ai-evals.md`.\n\n**Key behaviors:**\n- Compares the implemented codebase against the planned eval strategy — never re-plans\n- Reads implementation files incrementally to respect context budget\n\n---\n\n### gsd-framework-selector\n\n**Role:** Interactive decision-matrix agent that runs a ≤6-question interview, scores candidate AI/LLM frameworks, and returns a ranked recommendation with rationale.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ai-integration-phase` |\n| **Parallelism** | Single instance (interactive) |\n| **Tools** | Read, Bash, Grep, Glob, WebSearch, AskUserQuestion |\n| **Model (balanced)** | Sonnet |\n| **Color** | `#38BDF8` (sky blue) |\n| **Produces** | Scored ranked recommendation (structured return to orchestrator) |\n\n**Required reading:** `get-shit-done/references/ai-frameworks.md` (decision matrix).\n\n**Key behaviors:**\n- Scans `package.json`, `pyproject.toml`, `requirements*.txt` for existing AI libraries before the interview to avoid recommending a rejected framework\n- Asks only what the codebase scan and CONTEXT.md have not already answered\n\n---\n\n### gsd-intel-updater\n\n**Role:** Reads project source and writes structured intel (JSON + Markdown) into `.planning/intel/`, building a queryable codebase knowledge base that other agents use instead of performing expensive fresh exploration.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-map-codebase --query` (refresh / update flows) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Bash, Glob, Grep |\n| **Model (balanced)** | Sonnet |\n| **Color** | Cyan |\n| **Produces** | `.planning/intel/*.json` (and companion Markdown) consumed by `gsd-sdk query intel` |\n\n**Key behaviors:**\n- Writes current state only — no temporal language, every claim references an actual file path\n- Uses Glob / Read / Grep for cross-platform correctness; Bash is reserved for `gsd-sdk query intel` CLI calls\n\n---\n\n### gsd-doc-classifier\n\n**Role:** Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN. Extracts title, scope summary, and cross-references. Writes a JSON classification file used by `gsd-doc-synthesizer` to build a consolidated context.\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (parallel fan-out over the doc corpus) |\n| **Parallelism** | One instance per input document |\n| **Tools** | Read, Write, Grep, Glob |\n| **Model (balanced)** | Haiku |\n| **Color** | Yellow |\n| **Produces** | One JSON classification file per input doc (type, title, scope, refs) |\n\n**Key behaviors:**\n- Single-doc scope — never synthesizes or resolves conflicts (that is the synthesizer's job)\n- Heuristic-first classification; returns UNKNOWN when the doc lacks type signals rather than guessing\n\n---\n\n### gsd-doc-synthesizer\n\n**Role:** Synthesizes classified planning docs into a single consolidated context. Applies precedence rules, detects cross-reference cycles, enforces LOCKED-vs-LOCKED hard-blocks, and writes `INGEST-CONFLICTS.md` with three buckets (auto-resolved, competing-variants, unresolved-blockers).\n\n| Property | Value |\n|----------|-------|\n| **Spawned by** | `/gsd-ingest-docs` (after classifier fan-in) |\n| **Parallelism** | Single instance |\n| **Tools** | Read, Write, Grep, Glob, Bash |\n| **Model (balanced)** | Sonnet |\n| **Color** | Orange |\n| **Produces** | Consolidated context for `.planning/` plus `INGEST-CONFLICTS.md` report |\n\n**Key behaviors:**\n- Hard-blocks on LOCKED-vs-LOCKED ADR contradictions instead of silently picking a winner\n- Follows the `references/doc-conflict-engine.md` contract so `/gsd-import` and `/gsd-ingest-docs` produce consistent conflict reports\n\n---\n\n## Agent Tool Permissions Summary\n\n> **Scope:** this table covers the 21 primary agents only. The 12 advanced/specialized agents listed above carry their own tool surfaces in their `agents/gsd-*.md` frontmatter (summarized in the per-agent stubs above and in [`docs/INVENTORY.md`](INVENTORY.md)).\n\n| Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |\n|-------|------|-------|------|------|------|------|-----------|----------|-----|\n| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | |\n| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| research-synthesizer | ✓ | ✓ | | ✓ | | | | | |\n| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |\n| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |\n| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |\n| user-profiler | ✓ | | | | | | | | |\n| doc-writer | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| doc-verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |\n| security-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |\n\n**Principle of Least Privilege:**\n- Checkers are read-only (no Write/Edit) — they evaluate, never modify\n- Researchers have web access — they need current ecosystem information\n- Executors have Edit — they modify code but not web access\n- Mappers have Write — they write analysis documents but not Edit (no code changes)\n\n\n# Instructions for GSD\n\n- Use the get-shit-done skill when the user asks for GSD or uses a `gsd-*` command.\n- Treat `/gsd-...` or `gsd-...` as command invocations and load the matching file from `.github/skills/gsd-*`.\n- When a command says to spawn a subagent, prefer a matching custom agent from `.github/agents`.\n- Do not apply GSD workflows unless the user explicitly asks for them.\n- After completing any `gsd-*` command (or any deliverable it triggers: feature, bug fix, tests, docs, etc.), ALWAYS: (1) offer the user the next step by prompting via `ask_user`; repeat this feedback loop until the user explicitly indicates they are done.\n\n\n# Skill Discovery Contract\n\n> Canonical rules for scanning, inventorying, and rendering GSD skills.\n\n## Root Categories\n\n### Project Roots\n\nScan these roots relative to the project root:\n\n- `.claude/skills/`\n- `.agents/skills/`\n- `.cursor/skills/`\n- `.github/skills/`\n- `./.codex/skills/`\n\nThese roots are used for project-specific skills and for the project `CLAUDE.md` skills section.\n\n### Managed Global Roots\n\nScan these roots relative to the user home directory:\n\n- `~/.claude/skills/`\n- `~/.codex/skills/`\n\nThese roots are used for managed runtime installs and inventory reporting.\n\n### Deprecated Import-Only Root\n\n- `~/.claude/get-shit-done/skills/`\n\nThis root is kept for legacy migration only. Inventory code may report it, but new installs should not write here.\n\n### Legacy Claude Commands\n\n- `~/.claude/commands/gsd/`\n\nThis is not a skills root. Discovery code only checks whether it exists so inventory can report legacy Claude installs.\n\n## Normalization Rules\n\n- Scan only subdirectories that contain `SKILL.md`.\n- Read `name` and `description` from YAML frontmatter.\n- Use the directory name when `name` is missing.\n- Extract trigger hints from body lines that match `TRIGGER when: ...`.\n- Treat `gsd-*` directories as installed framework skills.\n- Treat `~/.claude/get-shit-done/skills/` entries as deprecated/import-only.\n- Treat `~/.claude/commands/gsd/` as legacy command installation metadata, not skills.\n\n## Scanner Behavior\n\n### `sdk/src/query/skills.ts`\n\n- Returns a de-duplicated list of discovered skill names.\n- Scans project roots plus managed global roots.\n- Does not scan the deprecated import-only root.\n\n### `get-shit-done/bin/lib/profile-output.cjs`\n\n- Builds the project `CLAUDE.md` skills section.\n- Scans project roots only.\n- Skips `gsd-*` directories so the project section stays focused on user/project skills.\n- Adds `.codex/skills/` to the project discovery set.\n\n### `get-shit-done/bin/lib/init.cjs`\n\n- Generates the skill inventory object for `skill-manifest`.\n- Reports `skills`, `roots`, `installation`, and `counts`.\n- Marks `gsd_skills_installed` when any discovered skill name starts with `gsd-`.\n- Marks `legacy_claude_commands_installed` when `~/.claude/commands/gsd/` contains `.md` command files.\n\n## Inventory Shape\n\n`skill-manifest` returns a JSON object with:\n\n- `skills`: normalized skill entries\n- `roots`: the canonical roots that were checked\n- `installation`: summary booleans for installed GSD skills and legacy Claude commands\n- `counts`: small inventory counts for downstream consumers\n\nEach skill entry includes:\n\n- `name`\n- `description`\n- `triggers`\n- `path`\n- `file_path`\n- `root`\n- `scope`\n- `installed`\n- `deprecated`\n\n\n# 检查点\n\n计划自主执行。检查点用于规范化需要人工验证或决策的交互点。\n\n**核心原则：** Claude 用 CLI/API 自动化一切。检查点用于验证和决策，而非手动工作。\n\n**黄金法则：**\n1. **如果 Claude 能运行，Claude 就运行** - 绝不让用户执行 CLI 命令、启动服务器或运行构建\n2. **Claude 设置验证环境** - 启动开发服务器、填充数据库、配置环境变量\n3. **用户只做需要人工判断的事** - 视觉检查、UX 评估、\"这个感觉对吗？\"\n4. **密钥来自用户，自动化来自 Claude** - 询问 API 密钥，然后 Claude 通过 CLI 使用它们\n5. **自动模式绕过验证/决策检查点** — 当 config 中 `workflow._auto_chain_active` 或 `workflow.auto_advance` 为 true 时：human-verify 自动批准，decision 自动选择第一个选项，human-action 仍会停止（认证门控无法自动化）\n\n## 检查点类型\n\n### checkpoint:human-verify（最常见 - 90%）\n\n**何时使用：** Claude 完成自动化工作，人工确认其正常工作。\n\n**用于：**\n- 视觉 UI 检查（布局、样式、响应式）\n- 交互流程（点击向导、测试用户流程）\n- 功能验证（功能按预期工作）\n- 音频/视频播放质量\n- 动画流畅度\n- 无障碍测试\n\n**结构：**\n```xml\n\n [Claude 自动化并部署/构建的内容]\n \n [测试的确切步骤 - URL、命令、预期行为]\n \n [如何继续 - \"approved\"、\"yes\" 或描述问题]\n\n```\n\n**示例：UI 组件（展示关键模式：Claude 在检查点之前启动服务器）**\n```xml\n\n 构建响应式仪表板布局\n src/components/Dashboard.tsx, src/app/dashboard/page.tsx\n 创建带侧边栏、标题和内容区域的仪表板。使用 Tailwind 响应式类处理移动端。\n npm run build 成功，无 TypeScript 错误\n 仪表板组件构建无错误\n\n\n\n 启动开发服务器用于验证\n 在后台运行 `npm run dev`，等待 \"ready\" 消息，捕获端口\n curl http://localhost:3000 返回 200\n 开发服务器运行于 http://localhost:3000\n\n\n\n 响应式仪表板布局 - 开发服务器运行于 http://localhost:3000\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 桌面端 (>1024px): 左侧边栏，右侧内容，顶部标题\n 2. 平板端 (768px): 侧边栏折叠为汉堡菜单\n 3. 移动端 (375px): 单列布局，出现底部导航\n 4. 任何尺寸无布局偏移或水平滚动\n \n 输入 \"approved\" 或描述布局问题\n\n```\n\n### checkpoint:decision（9%）\n\n**何时使用：** 人工必须做出影响实现方向的选择。\n\n**用于：**\n- 技术选型（哪个认证提供商、哪个数据库）\n- 架构决策（monorepo 还是独立仓库）\n- 设计选择（配色方案、布局方式）\n- 功能优先级（构建哪个变体）\n- 数据模型决策（模式结构）\n\n**结构：**\n```xml\n\n [正在决策的内容]\n [为什么这个决策重要]\n \n \n \n \n [如何表明选择]\n\n```\n\n**示例：认证提供商选择**\n```xml\n\n 选择认证提供商\n \n 应用需要用户认证。三个可靠选项各有权衡。\n \n \n \n \n \n \n 选择：supabase、clerk 或 nextauth\n\n```\n\n### checkpoint:human-action（1% - 罕见）\n\n**何时使用：** 操作没有 CLI/API 且需要仅人工交互，或者 Claude 在自动化过程中遇到认证门控。\n\n**仅用于：**\n- **认证门控** - Claude 尝试了 CLI/API 但需要凭证（这不是失败）\n- 邮箱验证链接（点击邮件）\n- 短信两步验证码（手机验证）\n- 人工账户审批（平台需要人工审核）\n- 信用卡 3D Secure 流程（基于 Web 的支付授权）\n- OAuth 应用审批（基于 Web 的审批）\n\n**不要用于预定的手动工作：**\n- 部署（使用 CLI - 如需要则认证门控）\n- 创建 webhooks/数据库（使用 API/CLI - 如需要则认证门控）\n- 运行构建/测试（使用 Bash 工具）\n- 创建文件（使用 Write 工具）\n\n**结构：**\n```xml\n\n [人工必须做什么 - Claude 已完成所有可自动化的]\n \n [Claude 已自动化的内容]\n [需要人工操作的一件事]\n \n [Claude 之后可以检查的内容]\n [如何继续]\n\n```\n\n**示例：认证门控（动态检查点）**\n```xml\n\n 部署到 Vercel\n .vercel/, vercel.json\n 运行 `vercel --yes` 进行部署\n vercel ls 显示部署，curl 返回 200\n\n\n\n\n\n 认证 Vercel CLI 以便我继续部署\n \n 我尝试部署但收到认证错误。\n 运行：vercel login\n 这将打开你的浏览器 - 完成认证流程。\n \n vercel whoami 返回你的账户邮箱\n 认证完成后输入 \"done\"\n\n\n\n\n\n 重试 Vercel 部署\n 运行 `vercel --yes`（已认证）\n vercel ls 显示部署，curl 返回 200\n\n```\n\n**关键区别：** 认证门控是 Claude 遇到认证错误时动态创建的。不是预定的 — Claude 先自动化，只有在被阻止时才请求凭证。\n\n## 执行协议\n\n当 Claude 遇到 `type=\"checkpoint:*\"` 时：\n\n1. **立即停止** - 不继续下一个任务\n2. **清晰显示检查点** 使用下面的格式\n3. **等待用户响应** - 不幻想完成\n4. **如可能则验证** - 检查文件、运行测试、任何指定的内容\n5. **恢复执行** - 仅在确认后继续下一个任务\n\n**对于 checkpoint:human-verify:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要验证 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 5/8 任务完成\n任务: 响应式仪表板布局\n\n已构建: /dashboard 的响应式仪表板\n\n如何验证:\n 1. 访问: http://localhost:3000/dashboard\n 2. 桌面端 (>1024px): 侧边栏可见，内容填充剩余空间\n 3. 平板端 (768px): 侧边栏折叠为图标\n 4. 移动端 (375px): 侧边栏隐藏，出现汉堡菜单\n\n────────────────────────────────────────────────────────\n→ 你的操作: 输入 \"approved\" 或描述问题\n────────────────────────────────────────────────────────\n```\n\n**对于 checkpoint:decision:**\n```\n╔═══════════════════════════════════════════════════════╗\n║ CHECKPOINT: 需要决策 ║\n╚═══════════════════════════════════════════════════════╝\n\n进度: 2/6 任务完成\n任务: 选择认证提供商\n\n决策: 我们应该使用哪个认证提供商？\n\n上下文: 需要用户认证。三个选项各有权衡。\n\n选项:\n 1. supabase - 与我们的数据库内置集成，免费额度\n 优点: 行级安全集成，慷慨的免费额度\n 缺点: UI 定制性较差，生态锁定\n\n 2. clerk - 最佳 DX，10k 用户后付费\n 优点: 精美的预构建 UI，优秀文档\n 缺点: 供应商锁定，规模化时价格问题\n\n 3. nextauth - 自托管，最大控制权\n 优点: 免费，无供应商锁定，广泛采用\n 缺点: 更多设置工作，自行 DIY 安全更新\n\n────────────────────────────────────────────────────────\n→ 你的操作: 选择 supabase、clerk 或 nextauth\n────────────────────────────────────────────────────────\n```\n\n## 认证门控\n\n**认证门控 = Claude 尝试了 CLI/API，收到认证错误。** 不是失败 — 是需要人工输入来解除阻止的门控。\n\n**模式：** Claude 尝试自动化 → 认证错误 → 创建 checkpoint:human-action → 用户认证 → Claude 重试 → 继续\n\n**门控协议：**\n1. 认识到这不是失败 - 缺少认证是正常的\n2. 停止当前任务 - 不要反复重试\n3. 动态创建 checkpoint:human-action\n4. 提供确切的认证步骤\n5. 验证认证有效\n6. 重试原始任务\n7. 正常继续\n\n**关键区别：**\n- 预定的检查点：\"我需要你做 X\"（错误 - Claude 应该自动化）\n- 认证门控：\"我尝试自动化 X 但需要凭证\"（正确 - 解除自动化阻止）\n\n## 自动化参考\n\n**规则：** 如果有 CLI/API，Claude 就做。绝不让人工执行可自动化的工作。\n\n### 服务 CLI 参考\n\n| 服务 | CLI/API | 关键命令 | 认证门控 |\n|------|---------|----------|----------|\n| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |\n| Railway | `railway` | `init`, `up`, `variables set` | `railway login` |\n| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` |\n| Stripe | `stripe` + API | `listen`, `trigger`, API 调用 | .env 中的 API key |\n| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` |\n| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` |\n| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` |\n| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |\n| Node | `npm`/`pnpm` | `install`, `run build`, `test`, `run dev` | N/A |\n| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |\n| Convex | `npx convex` | `dev`, `deploy`, `env set`, `env get` | `npx convex login` |\n\n### 环境变量自动化\n\n**Env 文件：** 使用 Write/Edit 工具。绝不让用户手动创建 .env。\n\n**通过 CLI 的仪表板环境变量：**\n\n| 平台 | CLI 命令 | 示例 |\n|------|----------|------|\n| Convex | `npx convex env set` | `npx convex env set OPENAI_API_KEY sk-...` |\n| Vercel | `vercel env add` | `vercel env add STRIPE_KEY production` |\n| Railway | `railway variables set` | `railway variables set API_KEY=value` |\n| Fly | `fly secrets set` | `fly secrets set DATABASE_URL=...` |\n| Supabase | `supabase secrets set` | `supabase secrets set MY_SECRET=value` |\n\n### 开发服务器自动化\n\n| 框架 | 启动命令 | 就绪信号 | 默认 URL |\n|------|----------|----------|----------|\n| Next.js | `npm run dev` | \"Ready in\" 或 \"started server\" | http://localhost:3000 |\n| Vite | `npm run dev` | \"ready in\" | http://localhost:5173 |\n| Convex | `npx convex dev` | \"Convex functions ready\" | N/A（仅后端）|\n| Express | `npm start` | \"listening on port\" | http://localhost:3000 |\n| Django | `python manage.py runserver` | \"Starting development server\" | http://localhost:8000 |\n\n**服务器生命周期：**\n```bash\n# 后台运行，捕获 PID\nnpm run dev &\nDEV_SERVER_PID=$!\n\n# 等待就绪（最多 30s）\ntimeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'\n```\n\n**端口冲突：** 终止陈旧进程（`lsof -ti:3000 | xargs kill`）或使用备用端口（`--port 3001`）。\n\n**服务器保持运行** 直到检查点结束。仅在计划完成、切换到生产环境或端口需要用于不同服务时终止。\n\n### CLI 安装处理\n\n| CLI | 自动安装？ | 命令 |\n|-----|------------|------|\n| npm/pnpm/yarn | 否 - 询问用户 | 用户选择包管理器 |\n| vercel | 是 | `npm i -g vercel` |\n| gh (GitHub) | 是 | `brew install gh` (macOS) 或 `apt install gh` (Linux) |\n| stripe | 是 | `npm i -g stripe` |\n| supabase | 是 | `npm i -g supabase` |\n| convex | 否 - 使用 npx | `npx convex`（无需安装）|\n| fly | 是 | `brew install flyctl` 或 curl 安装器 |\n| railway | 是 | `npm i -g @railway/cli` |\n\n**协议：** 尝试命令 → \"command not found\" → 可自动安装？→ 是：静默安装，重试 → 否：检查点请求用户安装。\n\n## 检查点前自动化失败处理\n\n| 失败 | 响应 |\n|------|------|\n| 服务器无法启动 | 检查错误，修复问题，重试（不进入检查点）|\n| 端口被占用 | 终止陈旧进程或使用备用端口 |\n| 缺少依赖 | 运行 `npm install`，重试 |\n| 构建错误 | 先修复错误（是 bug，不是检查点问题）|\n| 认证错误 | 创建认证门控检查点 |\n| 网络超时 | 带退避重试，如果持续则检查点 |\n\n**绝不呈现验证环境损坏的检查点。** 如果 `curl localhost:3000` 失败，不要让用户\"访问 localhost:3000\"。\n\n## 可自动化快速参考\n\n| 操作 | 可自动化？| Claude 做？|\n|------|------------|------------|\n| 部署到 Vercel | 是 (`vercel`) | 是 |\n| 创建 Stripe webhook | 是 (API) | 是 |\n| 写入 .env 文件 | 是 (Write 工具) | 是 |\n| 创建 Upstash DB | 是 (`upstash`) | 是 |\n| 运行测试 | 是 (`npm test`) | 是 |\n| 启动开发服务器 | 是 (`npm run dev`) | 是 |\n| 添加环境变量到 Convex | 是 (`npx convex env set`) | 是 |\n| 添加环境变量到 Vercel | 是 (`vercel env add`) | 是 |\n| 填充数据库 | 是 (CLI/API) | 是 |\n| 点击邮件验证链接 | 否 | 否 |\n| 输入带 3DS 的信用卡 | 否 | 否 |\n| 在浏览器中完成 OAuth | 否 | 否 |\n| 视觉验证 UI 是否正确 | 否 | 否 |\n| 测试交互式用户流程 | 否 | 否 |\n\n## 反模式\n\n### ❌ 错误：让用户启动开发服务器\n```xml\n\n 仪表板组件\n \n 1. 运行: npm run dev\n 2. 访问: http://localhost:3000/dashboard\n 3. 检查布局是否正确\n \n\n```\n**为什么错误：** Claude 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。\n\n### ✅ 正确：Claude 启动服务器，用户访问\n```xml\n\n 启动开发服务器\n 在后台运行 `npm run dev`\n curl localhost:3000 返回 200\n\n\n\n http://localhost:3000/dashboard 的仪表板（服务器运行中）\n \n 访问 http://localhost:3000/dashboard 并验证：\n 1. 布局匹配设计\n 2. 无控制台错误\n \n\n```\n\n### ❌ 错误：让用户部署 / ✅ 正确：Claude 自动化\n```xml\n\n\n 部署到 Vercel\n 访问 vercel.com/new → 导入仓库 → 点击部署 → 复制 URL\n\n\n\n\n 部署到 Vercel\n 运行 `vercel --yes`。捕获 URL。\n vercel ls 显示部署，curl 返回 200\n\n\n\n 已部署到 {url}\n 访问 {url}，检查首页加载\n 输入 \"approved\"\n\n```\n\n## 摘要\n\n检查点规范化人工介入点用于验证和决策，而非手动工作。\n\n**黄金法则：** 如果 Claude 能自动化它，Claude 就必须自动化它。\n\n**检查点优先级：**\n1. **checkpoint:human-verify**（90%）- Claude 自动化一切，人工确认视觉/功能正确性\n2. **checkpoint:decision**（9%）- 人工做出架构/技术选择\n3. **checkpoint:human-action**（1%）- 真正无法避免的、没有 API/CLI 的手动步骤\n\n**何时不用检查点：**\n- Claude 可以编程验证的事情（测试、构建）\n- 文件操作（Claude 可以读取文件）\n- 代码正确性（测试和静态分析）\n- 任何可通过 CLI/API 自动化的内容\n\n\n# 续接格式\n\n完成命令或工作流后展示下一步的标准格式。\n\n## 核心结构\n\n```\n---\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `{备选项 1}` — 描述\n- `{备选项 2}` — 描述\n\n---\n```\n\n## 格式规则\n\n1. **始终展示它是什么** — 名称 + 描述，绝不仅仅是一个命令路径\n2. **从源文件拉取上下文** — ROADMAP.md 用于阶段，PLAN.md `` 用于计划\n3. **命令用内联代码** — 反引号，易于复制粘贴，渲染为可点击链接\n4. **`/clear` 说明** — 始终包含，保持简洁但解释原因\n5. **用\"也可选\"而非\"其他选项\"** — 听起来更像应用\n6. **视觉分隔符** — 上下用 `---` 使其突出\n\n## 变体\n\n### 执行下一个计划\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- 执行前审查计划\n- `/gsd-discuss-phase --assumptions 2` — 检查假设\n\n---\n```\n\n### 执行阶段中最后一个计划\n\n添加注释说明这是最后一个计划以及接下来是什么：\n\n```\n---\n\n## ▶ 下一步\n\n**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh\n阶段 2 的最后一个计划\n\n`/gsd-execute-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**完成后：**\n- 阶段 2 → 阶段 3 过渡\n- 下一步：**阶段 3: 核心功能** — 用户仪表板和设置\n\n---\n```\n\n### 规划阶段\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程\n\n`/gsd-plan-phase 2`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 2` — 先收集上下文\n- `/gsd-plan-phase --research-phase 2` — 调查未知项\n- 审查路线图\n\n---\n```\n\n### 阶段完成，准备下一步\n\n在下一步操作前显示完成状态：\n\n```\n---\n\n## ✓ 阶段 2 完成\n\n3/3 计划已执行\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n`/gsd-plan-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n\n**也可选：**\n- `/gsd-discuss-phase 3` — 先收集上下文\n- `/gsd-plan-phase --research-phase 3` — 调查未知项\n- 回顾阶段 2 构建的内容\n\n---\n```\n\n### 多个同等选项\n\n当没有明确的主要操作时：\n\n```\n---\n\n## ▶ 下一步\n\n**阶段 3: 核心功能** — 用户仪表板、设置和数据导出\n\n**直接规划：** `/gsd-plan-phase 3`\n\n**先讨论上下文：** `/gsd-discuss-phase 3`\n\n**研究未知项：** `/gsd-plan-phase --research-phase 3`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n### 里程碑完成\n\n```\n---\n\n## 🎉 里程碑 v1.0 完成\n\n全部 4 个阶段已发布\n\n## ▶ 下一步\n\n**开始 v1.1** — 提问 → 研究 → 需求 → 路线图\n\n`/gsd-new-milestone`\n\n`/clear` 优先 → 全新上下文窗口\n\n---\n```\n\n## 拉取上下文\n\n### 用于阶段（从 ROADMAP.md）：\n\n```markdown\n### 阶段 2: 认证\n**目标**: 带刷新令牌的 JWT 登录流程\n```\n\n提取：`**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程`\n\n### 用于计划（从 ROADMAP.md）：\n\n```markdown\n计划:\n- [ ] 02-03: 添加刷新令牌轮换\n```\n\n或从 PLAN.md ``：\n\n```xml\n\n添加带滑动过期窗口的刷新令牌轮换。\n\n目的: 在不影响安全性的前提下延长会话生命周期。\n\n```\n\n提取：`**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh`\n\n## 反模式\n\n### 不要：仅命令（无上下文）\n\n```\n## 继续\n\n运行 `/clear`，然后粘贴：\n/gsd-execute-phase 2\n```\n\n用户不知道 02-03 是关于什么的。\n\n### 不要：缺少 /clear 说明\n\n```\n`/gsd-plan-phase 3`\n\n先运行 /clear。\n```\n\n没有解释原因。用户可能跳过。\n\n### 不要：\"其他选项\" 措辞\n\n```\n其他选项：\n- 审查路线图\n```\n\n听起来像是事后补充。用\"也可选：\"替代。\n\n### 不要：用围栏代码块展示命令\n\n```\n```\n/gsd-plan-phase 3\n```\n```\n\n模板内的围栏代码块会造成嵌套歧义。用内联反引号替代。\n\n\n# 小数阶段计算\n\n为紧急插入计算下一个小数阶段编号。\n\n## 使用 gsd-sdk query\n\n```bash\n# 获取阶段 6 之后的下一个小数阶段\ngsd-sdk query phase.next-decimal 6\n```\n\n输出：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.1\",\n \"existing\": []\n}\n```\n\n已有小数时：\n```json\n{\n \"found\": true,\n \"base_phase\": \"06\",\n \"next\": \"06.3\",\n \"existing\": [\"06.1\", \"06.2\"]\n}\n```\n\n## 提取值\n\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick next)\nBASE_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --pick base_phase)\n```\n\n或使用 --raw 标志：\n```bash\nDECIMAL_PHASE=$(gsd-sdk query phase.next-decimal \"${AFTER_PHASE}\" --raw)\n# 返回: 06.1\n```\n\n## 示例\n\n| 已有阶段 | 下一个阶段 |\n|----------|------------|\n| 仅 06 | 06.1 |\n| 06, 06.1 | 06.2 |\n| 06, 06.1, 06.2 | 06.3 |\n| 06, 06.1, 06.3（有空缺）| 06.4 |\n\n## 目录命名\n\n小数阶段目录使用完整的小数编号：\n\n```bash\nSLUG=$(gsd-sdk query generate-slug \"$DESCRIPTION\" --raw)\nPHASE_DIR=\".planning/phases/${DECIMAL_PHASE}-${SLUG}\"\nmkdir -p \"$PHASE_DIR\"\n```\n\n示例：`.planning/phases/06.1-fix-critical-auth-bug/`\n\n\n\nGSD 框架的 Git 集成。\n\n\n\n\n**提交结果，而非过程。**\n\ngit 日志应该读起来像是发布内容的变更日志，而不是规划活动的日记。\n\n\n\n\n| 事件 | 提交? | 原因 |\n| ----------------------- | ------- | ------------------------------------------------ |\n| BRIEF + ROADMAP 创建 | 是 | 项目初始化 |\n| PLAN.md 创建 | 否 | 中间产物 - 与计划完成一起提交 |\n| RESEARCH.md 创建 | 否 | 中间产物 |\n| DISCOVERY.md 创建 | 否 | 中间产物 |\n| **任务完成** | 是 | 原子工作单元（每个任务 1 个提交） |\n| **计划完成** | 是 | 元数据提交（SUMMARY + STATE + ROADMAP） |\n| 交接创建 | 是 | WIP 状态保留 |\n\n\n\n\n\n```bash\n[ -d .git ] && echo \"GIT_EXISTS\" || echo \"NO_GIT\"\n```\n\n如果 NO_GIT：静默运行 `git init`。GSD 项目总是有自己的仓库。\n\n\n\n\n\n## 项目初始化（brief + roadmap 一起）\n\n```\ndocs: initialize [project-name] ([N] phases)\n\n[PROJECT.md 中的一句话描述]\n\nPhases:\n1. [phase-name]: [goal]\n2. [phase-name]: [goal]\n3. [phase-name]: [goal]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs: initialize [project-name] ([N] phases)\" --files .planning/\n```\n\n\n\n\n## 任务完成（计划执行期间）\n\n每个任务在完成后立即获得自己的提交。\n\n```\n{type}({phase}-{plan}): {task-name}\n\n- [关键变更 1]\n- [关键变更 2]\n- [关键变更 3]\n```\n\n**提交类型：**\n- `feat` - 新功能/功能\n- `fix` - Bug 修复\n- `test` - 仅测试（TDD RED 阶段）\n- `refactor` - 代码清理（TDD REFACTOR 阶段）\n- `perf` - 性能改进\n- `chore` - 依赖、配置、工具\n\n**示例：**\n\n```bash\n# 标准任务\ngit add src/api/auth.ts src/types/user.ts\ngit commit -m \"feat(08-02): create user registration endpoint\n\n- POST /auth/register validates email and password\n- Checks for duplicate users\n- Returns JWT token on success\n\"\n\n# TDD 任务 - RED 阶段\ngit add src/__tests__/jwt.test.ts\ngit commit -m \"test(07-02): add failing test for JWT generation\n\n- Tests token contains user ID claim\n- Tests token expires in 1 hour\n- Tests signature verification\n\"\n\n# TDD 任务 - GREEN 阶段\ngit add src/utils/jwt.ts\ngit commit -m \"feat(07-02): implement JWT generation\n\n- Uses jose library for signing\n- Includes user ID and expiry claims\n- Signs with HS256 algorithm\n\"\n```\n\n\n\n\n## 计划完成（所有任务完成后）\n\n所有任务提交后，最后一个元数据提交捕获计划完成。\n\n```\ndocs({phase}-{plan}): complete [plan-name] plan\n\nTasks completed: [N]/[N]\n- [Task 1 name]\n- [Task 2 name]\n- [Task 3 name]\n\nSUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"docs({phase}-{plan}): complete [plan-name] plan\" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md\n```\n\n**注意：** 代码文件不包含 - 已按任务提交。\n\n\n\n\n## 交接（WIP）\n\n```\nwip: [phase-name] paused at task [X]/[Y]\n\nCurrent: [task name]\n[如果阻塞:] Blocked: [reason]\n```\n\n提交内容：\n\n```bash\ngsd-sdk query commit \"wip: [phase-name] paused at task [X]/[Y]\" --files .planning/\n```\n\n\n\n\n\n\n**旧方法（每个计划提交）：**\n```\na7f2d1 feat(checkout): Stripe payments with webhook verification\n3e9c4b feat(products): catalog with search, filters, and pagination\n8a1b2c feat(auth): JWT with refresh rotation using jose\n5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold\n2f4a8d docs: initialize ecommerce-app (5 phases)\n```\n\n**新方法（每个任务提交）：**\n```\n# Phase 04 - Checkout\n1a2b3c docs(04-01): complete checkout flow plan\n4d5e6f feat(04-01): add webhook signature verification\n7g8h9i feat(04-01): implement payment session creation\n0j1k2l feat(04-01): create checkout page component\n\n# Phase 03 - Products\n3m4n5o docs(03-02): complete product listing plan\n6p7q8r feat(03-02): add pagination controls\n9s0t1u feat(03-02): implement search and filters\n2v3w4x feat(03-01): create product catalog schema\n\n# Phase 02 - Auth\n5y6z7a docs(02-02): complete token refresh plan\n8b9c0d feat(02-02): implement refresh token rotation\n1e2f3g test(02-02): add failing test for token refresh\n4h5i6j docs(02-01): complete JWT setup plan\n7k8l9m feat(02-01): add JWT generation and validation\n0n1o2p chore(02-01): install jose library\n\n# Phase 01 - Foundation\n3q4r5s docs(01-01): complete scaffold plan\n6t7u8v feat(01-01): configure Tailwind and globals\n9w0x1y feat(01-01): set up Prisma with database\n2z3a4b feat(01-01): create Next.js 15 project\n\n# Initialization\n5c6d7e docs: initialize ecommerce-app (5 phases)\n```\n\n每个计划产生 2-4 个提交（任务 + 元数据）。清晰、细粒度、可 bisect。\n\n\n\n\n\n**仍不要提交（中间产物）：**\n- PLAN.md 创建（与计划完成一起提交）\n- RESEARCH.md（中间产物）\n- DISCOVERY.md（中间产物）\n- 小的规划调整\n- \"Fixed typo in roadmap\"\n\n**要提交（结果）：**\n- 每个任务完成（feat/fix/test/refactor）\n- 计划完成元数据（docs）\n- 项目初始化（docs）\n\n**关键原则：** 提交可工作的代码和已发布的结果，而非规划过程。\n\n\n\n\n\n## 为什么使用每任务提交？\n\n**AI 上下文工程：**\n- Git 历史成为未来 Claude 会话的主要上下文源\n- `git log --grep=\"{phase}-{plan}\"` 显示计划的所有工作\n- `git diff ^..` 显示每个任务的确切变更\n- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作\n\n**失败恢复：**\n- 任务 1 已提交 ✅，任务 2 失败 ❌\n- 下次会话中的 Claude：看到任务 1 完成，可以重试任务 2\n- 可以 `git reset --hard` 到最后一个成功的任务\n\n**调试：**\n- `git bisect` 找到确切的失败任务，而不仅仅是失败计划\n- `git blame` 将行追溯到特定任务上下文\n- 每个提交独立可回滚\n\n**可观察性：**\n- 独立开发者 + Claude 工作流受益于细粒度归因\n- 原子提交是 git 最佳实践\n- 当消费者是 Claude 而非人类时，\"提交噪音\"无关紧要\n\n\n\n\n# Git 规划提交\n\n通过 `gsd-sdk query commit` 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态（与旧版 `gsd-tools.cjs commit` 行为相同）。\n\n## 通过 CLI 提交\n\n先传提交说明，然后用 `--files` 显式传入文件路径。`commit` 与 `commit-to-subrepo` 都应使用 `--files` 来声明要提交的路径。\n\n对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查：\n\n```bash\ngsd-sdk query commit \"docs({scope}): {description}\" --files .planning/STATE.md .planning/ROADMAP.md\n```\n\n如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。\n\n## 修改上次提交\n\n将 `.planning/` 文件变更合并到上次提交：\n\n```bash\ngsd-sdk query commit \"\" --files .planning/codebase/*.md --amend\n```\n\n## 提交消息模式\n\n| 命令 | 范围 | 示例 |\n|------|------|------|\n| plan-phase | phase | `docs(phase-03): create authentication plans` |\n| execute-phase | phase | `docs(phase-03): complete authentication phase` |\n| new-milestone | milestone | `docs: start milestone v1.1` |\n| remove-phase | chore | `chore: remove phase 17 (dashboard)` |\n| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |\n| add-phase | phase | `docs: add phase 07 (settings page)` |\n\n## 何时跳过\n\n- config 中 `commit_docs: false`\n- `.planning/` 被 gitignore\n- 无变更可提交（用 `git status --porcelain .planning/` 检查）\n\n\n# 模型配置解析\n\n在编排开始时解析一次模型配置，然后在所有 Task 生成时使用。\n\n## 解析模式\n\n```bash\nMODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '\"model_profile\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | grep -o '\"[^\"]*\"$' | tr -d '\"' || echo \"balanced\")\n```\n\n默认值：未设置或缺少 config 时为 `balanced`。\n\n## 查找表\n\n@~/.claude/get-shit-done/references/model-profiles.md\n\n在表中查找已解析配置对应的代理。将 model 参数传递给 Task 调用：\n\n```\nTask(\n prompt=\"...\",\n subagent_type=\"gsd-planner\",\n model=\"{resolved_model}\" # \"inherit\"、\"sonnet\" 或 \"haiku\"\n)\n```\n\n**注意：** Opus 级代理解析为 `\"inherit\"`（而非 `\"opus\"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。\n\n## 使用方法\n\n1. 在编排开始时解析一次\n2. 存储 profile 值\n3. 生成时在表中查找每个代理的模型\n4. 将 model 参数传递给每个 Task 调用（值：`\"inherit\"`、`\"sonnet\"`、`\"haiku\"`）\n\n\n# 模型配置\n\n模型配置控制每个 GSD 代理使用哪个 Claude 模型。这允许平衡质量和 token 消耗。\n\n## 配置定义\n\n| 代理 | `quality` | `balanced` | `budget` |\n|-------|-----------|------------|----------|\n| gsd-planner | opus | opus | sonnet |\n| gsd-roadmapper | opus | sonnet | sonnet |\n| gsd-executor | opus | sonnet | sonnet |\n| gsd-phase-researcher | opus | sonnet | haiku |\n| gsd-project-researcher | opus | sonnet | haiku |\n| gsd-research-synthesizer | sonnet | sonnet | haiku |\n| gsd-debugger | opus | sonnet | sonnet |\n| gsd-codebase-mapper | sonnet | haiku | haiku |\n| gsd-verifier | sonnet | sonnet | haiku |\n| gsd-plan-checker | sonnet | sonnet | haiku |\n| gsd-integration-checker | sonnet | sonnet | haiku |\n| gsd-nyquist-auditor | sonnet | sonnet | haiku |\n\n## 配置理念\n\n**quality** - 最大推理能力\n- 所有决策代理使用 Opus\n- 只读验证使用 Sonnet\n- 适用场景：有配额可用、关键架构工作\n\n**balanced**（默认）- 智能分配\n- 仅规划（架构决策发生的地方）使用 Opus\n- 执行和研究使用 Sonnet（遵循明确指令）\n- 验证使用 Sonnet（需要推理，不仅仅是模式匹配）\n- 适用场景：正常开发、质量与成本的良好平衡\n\n**budget** - 最小化 Opus 使用\n- 编写代码的使用 Sonnet\n- 研究和验证使用 Haiku\n- 适用场景：节省配额、大量工作、不太关键的阶段\n\n## 解析逻辑\n\n编排器在生成代理前解析模型：\n\n```\n1. 读取 .planning/config.json\n2. 检查 model_overrides 是否有代理特定覆盖\n3. 如果没有覆盖，在配置表中查找代理\n4. 将 model 参数传递给 Task 调用\n```\n\n## 单代理覆盖\n\n覆盖特定代理而不更改整个配置：\n\n```json\n{\n \"model_profile\": \"balanced\",\n \"model_overrides\": {\n \"gsd-executor\": \"opus\",\n \"gsd-planner\": \"haiku\"\n }\n}\n```\n\n覆盖优先于配置。有效值：`opus`、`sonnet`、`haiku`。\n\n## 切换配置\n\n在 `.planning/config.json` 中设置 `model_profile` 键以更改配置文件。\n\n项目默认值：在 `.planning/config.json` 中设置：\n```json\n{\n \"model_profile\": \"balanced\"\n}\n```\n\n## 设计理由\n\n**为什么 gsd-planner 使用 Opus？**\n规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。\n\n**为什么 gsd-executor 使用 Sonnet？**\n执行者遵循明确的 PLAN.md 指令。计划已包含推理；执行只是实现。\n\n**为什么 balanced 中验证器使用 Sonnet（而非 Haiku）？**\n验证需要目标回溯推理 —— 检查代码是否**交付**了阶段承诺的内容，而不仅仅是模式匹配。Sonnet 处理得很好；Haiku 可能会遗漏细微的差距。\n\n**为什么 gsd-codebase-mapper 使用 Haiku？**\n只读探索和模式提取。不需要推理，只需从文件内容输出结构化结果。\n\n**为什么用 `inherit` 而不是直接传递 `opus`？**\nClaude Code 的 `\"opus\"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。GSD 为 opus 级代理返回 `\"inherit\"`，使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。\n\n\n# 阶段参数解析\n\n为操作阶段的命令解析和规范化阶段参数。\n\n## 提取\n\n从 `$ARGUMENTS` 中：\n- 提取阶段编号（第一个数字参数）\n- 提取标志（以 `--` 为前缀）\n- 剩余文本为描述（用于 insert/add 命令）\n\n## 使用 gsd-tools\n\n`find-phase` 命令一步完成规范化和验证：\n\n```bash\nPHASE_INFO=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\")\n```\n\n返回 JSON 包含：\n- `found`: true/false\n- `directory`: 阶段目录的完整路径\n- `phase_number`: 规范化的编号（如 \"06\"、\"06.1\"）\n- `phase_name`: 名称部分（如 \"foundation\"）\n- `plans`: PLAN.md 文件数组\n- `summaries`: SUMMARY.md 文件数组\n\n## 手动规范化（遗留）\n\n将整数阶段补零到 2 位。保留小数后缀。\n\n```bash\n# 规范化阶段编号\nif [[ \"$PHASE\" =~ ^[0-9]+$ ]]; then\n # 整数: 8 → 08\n PHASE=$(printf \"%02d\" \"$PHASE\")\nelif [[ \"$PHASE\" =~ ^([0-9]+)\\.([0-9]+)$ ]]; then\n # 小数: 2.1 → 02.1\n PHASE=$(printf \"%02d.%s\" \"${BASH_REMATCH[1]}\" \"${BASH_REMATCH[2]}\")\nfi\n```\n\n## 验证\n\n使用 `roadmap get-phase` 验证阶段存在：\n\n```bash\nPHASE_CHECK=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" roadmap get-phase \"${PHASE}\")\nif [ \"$(printf '%s\\n' \"$PHASE_CHECK\" | jq -r '.found')\" = \"false\" ]; then\n echo \"ERROR: Phase ${PHASE} not found in roadmap\"\n exit 1\nfi\n```\n\n## 目录查找\n\n使用 `find-phase` 进行目录查找：\n\n```bash\nPHASE_DIR=$(node \"$HOME/.claude/get-shit-done/bin/gsd-tools.cjs\" find-phase \"${PHASE}\" --raw)\n```\n\n\n\n\n`.planning/` 目录行为的配置选项。\n\n\n```json\n\"planning\": {\n \"commit_docs\": true,\n \"search_gitignored\": false\n},\n\"git\": {\n \"branching_strategy\": \"none\",\n \"phase_branch_template\": \"gsd/phase-{phase}-{slug}\",\n \"milestone_branch_template\": \"gsd/{milestone}-{slug}\"\n}\n```\n\n| 选项 | 默认值 | 描述 |\n|--------|---------|-------------|\n| `commit_docs` | `true` | 是否将规划工件提交到 git |\n| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` |\n| `git.branching_strategy` | `\"none\"` | Git 分支策略：`\"none\"`、`\"phase\"` 或 `\"milestone\"` |\n| `git.phase_branch_template` | `\"gsd/phase-{phase}-{slug}\"` | 阶段策略的分支模板 |\n| `git.milestone_branch_template` | `\"gsd/{milestone}-{slug}\"` | 里程碑策略的分支模板 |\n\n\n\n\n**当 `commit_docs: true`（默认）：**\n- 规划文件正常提交\n- SUMMARY.md、STATE.md、ROADMAP.md 在 git 中跟踪\n- 规划决策的完整历史保留\n\n**当 `commit_docs: false`：**\n- 跳过 `.planning/` 文件的所有 `git add`/`git commit`\n- 用户必须将 `.planning/` 添加到 `.gitignore`\n- 适用于：OSS 贡献、客户项目、保持规划私有\n\n**使用 `gsd-sdk query`（推荐）：**\n\n```bash\n# 提交时自动检查 commit_docs + gitignore：\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n\n# 通过 state load 加载配置（返回 JSON）：\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 在 JSON 输出中可用\n\n# 或使用包含 commit_docs 的 init 命令：\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# commit_docs 包含在所有 init 命令输出中\n```\n\n**自动检测：** 如果 `.planning/` 被 gitignore，无论 config.json 如何，`commit_docs` 自动为 `false`。这防止用户在 `.gitignore` 中有 `.planning/` 时出现 git 错误。\n\n**通过 CLI 提交（自动处理检查）：**\n\n```bash\ngsd-sdk query commit \"docs: update state\" --files .planning/STATE.md\n```\n\nCLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。\n\n\n\n\n\n**当 `search_gitignored: false`（默认）：**\n- 标准 rg 行为（尊重 .gitignore）\n- 直接路径搜索有效：`rg \"pattern\" .planning/` 找到文件\n- 广泛搜索跳过 gitignored：`rg \"pattern\"` 跳过 `.planning/`\n\n**当 `search_gitignored: true`:**\n- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore`\n- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要\n\n**注意：** 大多数 GSD 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都有效。\n\n\n\n\n\n使用未提交模式：\n\n1. **设置配置：**\n ```json\n \"planning\": {\n \"commit_docs\": false,\n \"search_gitignored\": true\n }\n ```\n\n2. **添加到 .gitignore：**\n ```\n .planning/\n ```\n\n3. **已存在的跟踪文件：** 如果 `.planning/` 之前被跟踪：\n ```bash\n git rm -r --cached .planning/\n git commit -m \"chore: stop tracking planning docs\"\n ```\n\n4. **分支合并：** 当使用 `branching_strategy: phase` 或 `milestone` 时，`complete-milestone` 工作流在 `commit_docs: false` 时自动从暂存区移除 `.planning/` 文件，然后才进行合并提交。\n\n\n\n\n\n**分支策略：**\n\n| 策略 | 创建分支时机 | 分支范围 | 合并点 |\n|----------|---------------------|--------------|-------------|\n| `none` | 从不 | N/A | N/A |\n| `phase` | `execute-phase` 开始时 | 单个阶段 | 阶段后用户手动合并 |\n| `milestone` | 里程碑第一个 `execute-phase` | 整个里程碑 | `complete-milestone` 时 |\n\n**当 `git.branching_strategy: \"none\"`（默认）：**\n- 所有工作提交到当前分支\n- 标准 GSD 行为\n\n**当 `git.branching_strategy: \"phase\"`：**\n- `execute-phase` 在执行前创建/切换到分支\n- 分支名来自 `phase_branch_template`（如 `gsd/phase-03-authentication`）\n- 所有计划提交到该分支\n- 阶段完成后用户手动合并分支\n- `complete-milestone` 提供合并所有阶段分支的选项\n\n**当 `git.branching_strategy: \"milestone\"`：**\n- 里程碑的第一个 `execute-phase` 创建里程碑分支\n- 分支名来自 `milestone_branch_template`（如 `gsd/v1.0-mvp`）\n- 里程碑中所有阶段提交到同一分支\n- `complete-milestone` 提供将里程碑分支合并到 main 的选项\n\n**模板变量：**\n\n| 变量 | 可用于 | 描述 |\n|----------|--------------|-------------|\n| `{phase}` | phase_branch_template | 零填充阶段号（如 \"03\"） |\n| `{slug}` | 两者 | 小写、连字符名称 |\n| `{milestone}` | milestone_branch_template | 里程碑版本（如 \"v1.0\"） |\n\n**检查配置：**\n\n使用 `init execute-phase` 返回所有配置为 JSON：\n```bash\nINIT=$(gsd-sdk query init.execute-phase \"1\")\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n或使用 `state load` 获取配置值：\n```bash\nINIT=$(gsd-sdk query state.load)\nif [[ \"$INIT\" == @file:* ]]; then INIT=$(cat \"${INIT#@file:}\"); fi\n# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template\n```\n\n**分支创建：**\n\n```bash\n# 阶段策略\nif [ \"$BRANCHING_STRATEGY\" = \"phase\" ]; then\n PHASE_SLUG=$(echo \"$PHASE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$PHASE_BRANCH_TEMPLATE\" | sed \"s/{phase}/$PADDED_PHASE/g\" | sed \"s/{slug}/$PHASE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n\n# 里程碑策略\nif [ \"$BRANCHING_STRATEGY\" = \"milestone\" ]; then\n MILESTONE_SLUG=$(echo \"$MILESTONE_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')\n BRANCH_NAME=$(echo \"$MILESTONE_BRANCH_TEMPLATE\" | sed \"s/{milestone}/$MILESTONE_VERSION/g\" | sed \"s/{slug}/$MILESTONE_SLUG/g\")\n git checkout -b \"$BRANCH_NAME\" 2>/dev/null || git checkout \"$BRANCH_NAME\"\nfi\n```\n\n**complete-milestone 时的合并选项：**\n\n| 选项 | Git 命令 | 结果 |\n|--------|-------------|--------|\n| Squash 合并（推荐） | `git merge --squash` | 每个分支单个干净提交 |\n| 带历史合并 | `git merge --no-ff` | 保留所有单独提交 |\n| 不合并直接删除 | `git branch -D` | 丢弃分支工作 |\n| 保留分支 | （无） | 后续手动处理 |\n\n推荐 Squash 合并 —— 保持 main 分支历史干净，同时在分支中保留完整开发历史（直到删除）。\n\n**使用场景：**\n\n| 策略 | 最适合 |\n|----------|----------|\n| `none` | 独立开发、简单项目 |\n| `phase` | 每阶段代码审查、细粒度回滚、团队协作 |\n| `milestone` | 发布分支、预发布环境、每个版本一个 PR |\n\n\n\n\n\n\n# 提问指南\n\n项目初始化是梦想提取，而非需求收集。你在帮助用户发现和表达他们想构建的内容。这不是合同谈判 —— 是协作思考。\n\n## 理念\n\n**你是思考伙伴，不是面试官。**\n\n用户通常有一个模糊的想法。你的工作是帮助他们将其锐化。问一些让他们思考\"哦，我没想到那个\"或\"是的，这正是我的意思\"的问题。\n\n不要审问。协作。不要照本宣科。顺藤摸瓜。\n\n## 目标\n\n到提问结束时，你需要足够的清晰度来编写下游阶段可执行的 PROJECT.md：\n\n- **研究** 需要：研究什么领域、用户已知什么、存在哪些未知\n- **需求** 需要：足够清晰的愿景来界定 v1 功能\n- **路线图** 需要：足够清晰的愿景来分解为阶段、\"完成\"是什么样子\n- **plan-phase** 需要：可分解为任务的具体需求、实现选择的上下文\n- **execute-phase** 需要：可验证的成功标准、需求背后的\"为什么\"\n\n模糊的 PROJECT.md 会让每个下游阶段都在猜测。成本会叠加。\n\n## 如何提问\n\n**开放开始。** 让他们倾倒心理模型。不要用结构打断。\n\n**跟随能量。** 无论他们强调什么，深入那个。什么让他们兴奋？什么问题引发了这一切？\n\n**挑战模糊。** 绝不接受模糊回答。\"好\"意味着什么？\"用户\"指谁？\"简单\"是怎么简单？\n\n**让抽象具体。**\"带我走一遍使用这个。\"\"那实际看起来是什么样？\"\n\n**澄清歧义。**\"你说 Z 时，是指 A 还是 B？\"\"你提到了 X —— 跟我多说说。\"\n\n**知道何时停止。** 当你理解他们想要什么、为什么想要、给谁用、完成是什么样 —— 提议继续。\n\n## 问题类型\n\n以此作为灵感，不是清单。选择与话题相关的。\n\n**动机 —— 为什么存在：**\n- \"什么引发了这一切？\"\n- \"你今天在做什么会被这个替代？\"\n- \"如果这个存在，你会做什么？\"\n\n**具体性 —— 它实际是什么：**\n- \"带我走一遍使用这个\"\n- \"你说 X —— 那实际看起来是什么样？\"\n- \"给我一个例子\"\n\n**澄清 —— 他们什么意思：**\n- \"你说 Z 时，是指 A 还是 B？\"\n- \"你提到了 X —— 跟我多说说那个\"\n\n**成功 —— 你怎么知道它在工作：**\n- \"你怎么知道这个在工作？\"\n- \"完成是什么样子？\"\n\n## 使用 AskUserQuestion\n\n用 AskUserQuestion 帮助用户思考，通过呈现具体的选项供他们反应。\n\n**好选项：**\n- 他们可能意思的解读\n- 确认或否认的具体例子\n- 揭示优先级的具体选择\n\n**坏选项：**\n- 泛泛的类别（\"技术\"、\"业务\"、\"其他\"）\n- 预设答案的引导性选项\n- 选项太多（2-4 个理想）\n- 超过 12 个字符的标题（硬限制 —— 验证会拒绝）\n\n**示例 —— 模糊回答：**\n用户说\"它应该快\"\n\n- header: \"快\"\n- question: \"快是指？\"\n- options: [\"亚秒响应\", \"处理大数据集\", \"快速构建\", \"让我解释\"]\n\n**示例 —— 跟随话题：**\n用户提到\"对当前工具感到沮丧\"\n\n- header: \"沮丧\"\n- question: \"具体什么让你沮丧？\"\n- options: [\"点击太多\", \"缺少功能\", \"不可靠\", \"让我解释\"]\n\n**给用户的提示 —— 修改选项：**\n想要稍微修改某个选项版本的用户可以选择\"Other\"并通过编号引用选项：`#1 但仅用于指关节` 或 `#2 禁用分页`。这避免重新输入完整选项文本。\n\n## 自由格式规则\n\n**当用户想自由解释时，停止使用 AskUserQuestion。**\n\n如果用户选择\"Other\"且他们的回应表明他们想用自己的话描述（如\"让我描述一下\"、\"我来解释\"、\"别的\"、或任何非选择/修改现有选项的开放式回复），你必须：\n\n1. **用纯文本问你的追问** — 不通过 AskUserQuestion\n2. **等待他们在正常提示符下输入**\n3. **仅在处理他们的自由格式回应后恢复 AskUserQuestion**\n\n同样适用于如果你包含一个表明自由格式的选项（如\"让我解释\"或\"详细描述\"）且用户选择了它。\n\n**错误：** 用户说\"让我描述一下\" → AskUserQuestion(\"什么功能？\", [\"功能 A\", \"功能 B\", \"详细描述\"])\n**正确：** 用户说\"让我描述一下\" → \"请讲 —— 你在想什么？\"\n\n## 上下文清单\n\n以此作为**背景清单**，而非对话结构。进行时在脑中检查这些。如果还有缺口，自然地穿插问题。\n\n- [ ] 他们在构建什么（足够具体可以向陌生人解释）\n- [ ] 为什么它需要存在（驱动它的问题或渴望）\n- [ ] 给谁用的（即使只是他们自己）\n- [ ] \"完成\"是什么样子（可观察的结果）\n\n四件事。如果他们主动提供更多，捕获它。\n\n## 决策门控\n\n当你能写出清晰的 PROJECT.md 时，提议继续：\n\n- header: \"准备好了？\"\n- question: \"我想我理解你想要什么了。准备创建 PROJECT.md 吗？\"\n- options:\n - \"创建 PROJECT.md\" — 让我们继续\n - \"继续探索\" — 我想分享更多 / 再问我\n\n如果\"继续探索\" —— 问他们想添加什么或识别缺口并自然探查。\n\n循环直到选择\"创建 PROJECT.md\"。\n\n## 反模式\n\n- **走清单** — 不管他们说什么都按领域走\n- **套话问题** — \"你的核心价值是什么？\"\"什么超出范围？\"不管上下文\n- **企业腔** — \"你的成功标准是什么？\"\"你的利益相关者是谁？\"\n- **审问** — 不基于回答构建就连续发问\n- **急于求成** — 最小化问题以开始\"实际工作\"\n- **浅层接受** — 不探查就接受模糊回答\n- **过早约束** — 还不理解想法就问技术栈\n- **用户技能** — 绝不问用户的技术经验。Claude 来构建。\n\n\n\nTDD 关乎设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现前思考行为，从而产生更清晰的接口和更可测试的代码。\n\n**原则：** 如果在编写 `fn` 之前能用 `expect(fn(input)).toBe(output)` 描述行为，TDD 会改善结果。\n\n**关键洞察：** TDD 工作本质上比标准任务更重 —— 它需要 2-3 个执行周期（RED → GREEN → REFACTOR），每个周期都涉及文件读取、测试运行和可能的调试。TDD 功能获得专门的计划，以确保整个周期内有完整的上下文可用。\n\n\n\n## 何时 TDD 提高质量\n\n**TDD 候选（创建 TDD 计划）：**\n- 有明确输入/输出的业务逻辑\n- 有请求/响应契约的 API 端点\n- 数据转换、解析、格式化\n- 验证规则和约束\n- 有可测试行为的算法\n- 状态机和工作流\n- 有清晰规格的工具函数\n\n**跳过 TDD（使用带 `type=\"auto\"` 任务的标准计划）：**\n- UI 布局、样式、视觉组件\n- 配置更改\n- 连接现有组件的胶水代码\n- 一次性脚本和迁移\n- 无业务逻辑的简单 CRUD\n- 探索性原型\n\n**启发式：** 能在编写 `fn` 之前写 `expect(fn(input)).toBe(output)` 吗？\n→ 能：创建 TDD 计划\n→ 不能：使用标准计划，事后添加测试（如需要）\n\n\n\n## TDD 计划结构\n\n每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 循环实现**一个功能**。\n\n```markdown\n---\nphase: XX-name\nplan: NN\ntype: tdd\n---\n\n\n[什么功能以及为什么]\nPurpose: [该功能 TDD 的设计收益]\nOutput: [可工作的、已测试的功能]\n\n\n\n@.planning/PROJECT.md\n@.planning/ROADMAP.md\n@relevant/source/files.ts\n\n\n\n [功能名称]\n [源文件, 测试文件]\n \n [可测试术语描述的预期行为]\n Cases: 输入 → 预期输出\n \n [测试通过后如何实现]\n\n\n\n[证明功能有效的测试命令]\n\n\n\n- 失败测试已编写并提交\n- 实现通过测试\n- 重构完成（如需要）\n- 所有 2-3 个提交都存在\n\n\n\n完成后，创建包含以下内容的 SUMMARY.md：\n- RED: 编写了什么测试，为什么失败\n- GREEN: 什么实现让它通过\n- REFACTOR: 做了什么清理（如有）\n- Commits: 生成的提交列表\n\n```\n\n**每个 TDD 计划一个功能。** 如果功能足够简单可以批量处理，那就足够简单可以跳过 TDD —— 使用标准计划，事后添加测试。\n\n\n\n## 红-绿-重构循环\n\n**RED - 编写失败测试：**\n1. 按项目约定创建测试文件\n2. 编写描述预期行为的测试（来自 `` 元素）\n3. 运行测试 - 必须**失败**\n4. 如果测试通过：功能已存在或测试有误。调查。\n5. 提交：`test({phase}-{plan}): add failing test for [feature]`\n\n**GREEN - 实现使其通过：**\n1. 编写使测试通过的最小代码\n2. 不耍小聪明，不优化 - 只让它工作\n3. 运行测试 - 必须**通过**\n4. 提交：`feat({phase}-{plan}): implement [feature]`\n\n**REFACTOR（如需要）：**\n1. 如果存在明显的改进，清理实现\n2. 运行测试 - 必须**仍然通过**\n3. 仅在做出更改时提交：`refactor({phase}-{plan}): clean up [feature]`\n\n**结果：** 每个 TDD 计划产生 2-3 个原子提交。\n\n\n\n## 好测试 vs 坏测试\n\n**测试行为，而非实现：**\n- 好：\"返回格式化的日期字符串\"\n- 坏：\"用正确参数调用 formatDate 辅助函数\"\n- 测试应该能经受重构\n\n**每个测试一个概念：**\n- 好：分别为有效输入、空输入、畸形输入编写测试\n- 坏：用多个断言检查所有边缘情况的单个测试\n\n**描述性名称：**\n- 好：\"should reject empty email\"、\"returns null for invalid ID\"\n- 坏：\"test1\"、\"handles error\"、\"works correctly\"\n\n**不包含实现细节：**\n- 好：测试公共 API、可观察行为\n- 坏：Mock 内部实现、测试私有方法、断言内部状态\n\n\n\n## 测试框架设置（如不存在）\n\n当执行 TDD 计划但没有配置测试框架时，作为 RED 阶段的一部分进行设置：\n\n**1. 检测项目类型：**\n```bash\n# JavaScript/TypeScript\nif [ -f package.json ]; then echo \"node\"; fi\n\n# Python\nif [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo \"python\"; fi\n\n# Go\nif [ -f go.mod ]; then echo \"go\"; fi\n\n# Rust\nif [ -f Cargo.toml ]; then echo \"rust\"; fi\n```\n\n**2. 安装最小框架：**\n| 项目 | 框架 | 安装 |\n|---------|-----------|---------|\n| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |\n| Node.js (Vite) | Vitest | `npm install -D vitest` |\n| Python | pytest | `pip install pytest` |\n| Go | testing | 内置 |\n| Rust | cargo test | 内置 |\n\n**3. 按需创建配置：**\n- Jest: 带 ts-jest preset 的 `jest.config.js`\n- Vitest: 带测试全局变量的 `vitest.config.ts`\n- pytest: `pytest.ini` 或 `pyproject.toml` 部分\n\n**4. 验证设置：**\n```bash\n# 运行空测试套件 - 应该以 0 个测试通过\nnpm test # Node\npytest # Python\ngo test ./... # Go\ncargo test # Rust\n```\n\n**5. 创建第一个测试文件：**\n遵循项目约定的测试位置：\n- 源文件旁边的 `*.test.ts` / `*.spec.ts`\n- `__tests__/` 目录\n- 根目录的 `tests/` 目录\n\n框架设置是第一个 TDD 计划 RED 阶段的一次性成本。\n\n\n\n## 错误处理\n\n**测试在 RED 阶段没有失败：**\n- 功能可能已存在 - 调查\n- 测试可能有误（没测试你以为的东西）\n- 前进前修复\n\n**测试在 GREEN 阶段没有通过：**\n- 调试实现\n- 不要跳到重构\n- 持续迭代直到绿色\n\n**测试在 REFACTOR 阶段失败：**\n- 撤销重构\n- 提交过早\n- 用更小的步骤重构\n\n**不相关的测试失败：**\n- 停下来调查\n- 可能表明耦合问题\n- 前进前修复\n\n\n\n## TDD 计划的提交模式\n\nTDD 计划产生 2-3 个原子提交（每个阶段一个）：\n\n```\ntest(08-02): add failing test for email validation\n\n- Tests valid email formats accepted\n- Tests invalid formats rejected\n- Tests empty input handling\n\nfeat(08-02): implement email validation\n\n- Regex pattern matches RFC 5322\n- Returns boolean for validity\n- Handles edge cases (empty, null)\n\nrefactor(08-02): extract regex to constant (optional)\n\n- Moved pattern to EMAIL_REGEX constant\n- No behavior changes\n- Tests still pass\n```\n\n**与标准计划对比：**\n- 标准计划：每个任务 1 个提交，每个计划 2-4 个提交\n- TDD 计划：单个功能 2-3 个提交\n\n两者遵循相同格式：`{type}({phase}-{plan}): {description}`\n\n**好处：**\n- 每个提交独立可回滚\n- Git bisect 在提交级别工作\n- 显示 TDD 纪律的清晰历史\n- 与整体提交策略一致\n\n\n\n## 上下文预算\n\nTDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。\n\n为什么更低：\n- RED 阶段：编写测试、运行测试、可能调试为什么没有失败\n- GREEN 阶段：实现、运行测试、可能对失败进行迭代\n- REFACTOR 阶段：修改代码、运行测试、验证无回归\n\n每个阶段涉及读取文件、运行命令、分析输出。来回往复本质上比线性任务执行更重。\n\n单一功能聚焦确保整个周期保持完整质量。\n\n\n\n# UI 品牌规范\n\n面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。\n\n## 阶段横幅\n\n用于主要工作流过渡。\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► {阶段名称}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**阶段名称（大写）：**\n- `QUESTIONING`（提问）\n- `RESEARCHING`（研究）\n- `DEFINING REQUIREMENTS`（定义需求）\n- `CREATING ROADMAP`（创建路线图）\n- `PLANNING PHASE {N}`（规划阶段 {N}）\n- `EXECUTING WAVE {N}`（执行波次 {N}）\n- `VERIFYING`（验证）\n- `PHASE {N} COMPLETE ✓`（阶段 {N} 完成）\n- `MILESTONE COMPLETE 🎉`（里程碑完成）\n\n---\n\n## 检查点框\n\n需要用户操作。62 字符宽度。\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ CHECKPOINT: {类型} ║\n╚══════════════════════════════════════════════════════════════╝\n\n{内容}\n\n──────────────────────────────────────────────────────────────\n→ {操作提示}\n──────────────────────────────────────────────────────────────\n```\n\n**类型：**\n- `CHECKPOINT: 需要验证` → `→ 输入 \"approved\" 或描述问题`\n- `CHECKPOINT: 需要决策` → `→ 选择: option-a / option-b`\n- `CHECKPOINT: 需要操作` → `→ 完成后输入 \"done\"`\n\n---\n\n## 状态符号\n\n```\n✓ 完成 / 通过 / 已验证\n✗ 失败 / 缺失 / 阻塞\n◆ 进行中\n○ 待处理\n⚡ 自动批准\n⚠ 警告\n🎉 里程碑完成（仅在横幅中）\n```\n\n---\n\n## 进度显示\n\n**阶段/里程碑级别：**\n```\n进度: ████████░░ 80%\n```\n\n**任务级别：**\n```\n任务: 2/4 完成\n```\n\n**计划级别：**\n```\n计划: 3/5 完成\n```\n\n---\n\n## 生成指示器\n\n```\n◆ 正在生成研究员...\n\n◆ 并行生成 4 个研究员...\n → 技术栈研究\n → 功能研究\n → 架构研究\n → 陷阱研究\n\n✓ 研究员完成: STACK.md 已写入\n```\n\n---\n\n## 下一步区块\n\n始终在主要完成后。\n\n```\n───────────────────────────────────────────────────────────────\n\n## ▶ 下一步\n\n**{标识符}: {名称}** — {单行描述}\n\n`{可复制粘贴的命令}`\n\n`/clear` 优先 → 全新上下文窗口\n\n───────────────────────────────────────────────────────────────\n\n**也可选：**\n- (根据工作流选填可选命令，例如 `/gsd-progress --next`)\n\n───────────────────────────────────────────────────────────────\n```\n\n---\n\n## 错误框\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ ERROR ║\n╚══════════════════════════════════════════════════════════════╝\n\n{错误描述}\n\n**修复方法:** {解决步骤}\n```\n\n---\n\n## 表格\n\n```\n| 阶段 | 状态 | 计划 | 进度 |\n|------|------|------|------|\n| 1 | ✓ | 3/3 | 100% |\n| 2 | ◆ | 1/4 | 25% |\n| 3 | ○ | 0/2 | 0% |\n```\n\n---\n\n## 反模式\n\n- 变化的框/横幅宽度\n- 混合横幅样式（`===`、`---`、`***`）\n- 横幅中缺少 `GSD ►` 前缀\n- 随机 emoji（`🚀`、`✨`、`💫`）\n- 完成后缺少下一步区块\n\n\n# 验证模式\n\n如何验证不同类型的工件是真实实现，而非存根或占位符。\n\n\n**存在 ≠ 实现**\n\n文件存在并不意味着功能有效。验证必须检查：\n1. **存在** - 文件在预期路径\n2. **实质性** - 内容是真实实现，非占位符\n3. **已连接** - 已连接到系统的其他部分\n4. **功能性** - 调用时实际工作\n\n级别 1-3 可以编程检查。级别 4 通常需要人工验证。\n\n\n\n\n## 通用存根模式\n\n这些模式表明占位符代码，无论文件类型：\n\n**基于注释的存根：**\n```bash\n# 存根注释的 Grep 模式\ngrep -E \"(TODO|FIXME|XXX|HACK|PLACEHOLDER)\" \"$file\"\ngrep -E \"implement|add later|coming soon|will be\" \"$file\" -i\ngrep -E \"// \\.\\.\\.|/\\* \\.\\.\\. \\*/|# \\.\\.\\.\" \"$file\"\n```\n\n**输出中的占位符文本：**\n```bash\n# UI 占位符模式\ngrep -E \"placeholder|lorem ipsum|coming soon|under construction\" \"$file\" -i\ngrep -E \"sample|example|test data|dummy\" \"$file\" -i\ngrep -E \"\\[.*\\]|<.*>|\\{.*\\}\" \"$file\" # 模板括号未移除\n```\n\n**空或琐碎实现：**\n```bash\n# 什么都不做的函数\ngrep -E \"return null|return undefined|return \\{\\}|return \\[\\]\" \"$file\"\ngrep -E \"pass$|\\.\\.\\.|\\bnothing\\b\" \"$file\"\ngrep -E \"console\\.(log|warn|error).*only\" \"$file\" # 仅日志函数\n```\n\n**预期动态但硬编码的值：**\n```bash\n# 硬编码 ID、计数或内容\ngrep -E \"id.*=.*['\\\"].*['\\\"]\" \"$file\" # 硬编码字符串 ID\ngrep -E \"count.*=.*\\d+|length.*=.*\\d+\" \"$file\" # 硬编码计数\ngrep -E \"\\\\\\$\\d+\\.\\d{2}|\\d+ items\" \"$file\" # 硬编码显示值\n```\n\n\n\n\n\n## React/Next.js 组件\n\n**存在检查：**\n```bash\n# 文件存在且导出组件\n[ -f \"$component_path\" ] && grep -E \"export (default |)function|export const.*=.*\\(\" \"$component_path\"\n```\n\n**实质性检查：**\n```bash\n# 返回实际 JSX，非占位符\ngrep -E \"return.*<\" \"$component_path\" | grep -v \"return.*null\" | grep -v \"placeholder\" -i\n\n# 有有意义的内容（不仅仅是包装 div）\ngrep -E \"<[A-Z][a-zA-Z]+|className=|onClick=|onChange=\" \"$component_path\"\n\n# 使用 props 或 state（非静态）\ngrep -E \"props\\.|useState|useEffect|useContext|\\{.*\\}\" \"$component_path\"\n```\n\n**React 特有的存根模式：**\n```javascript\n// 危险信号 - 这些是存根：\nreturn
Component
\nreturn
Placeholder
\nreturn
{/* TODO */}
\nreturn

Coming soon

\nreturn null\nreturn <>\n\n// 也是存根 - 空处理器：\nonClick={() => {}}\nonChange={() => console.log('clicked')}\nonSubmit={(e) => e.preventDefault()} // 仅阻止默认，什么都不做\n```\n\n**连接检查：**\n```bash\n# 组件导入它需要的东西\ngrep -E \"^import.*from\" \"$component_path\"\n\n# Props 实际被使用（不仅仅是接收）\n# 查找解构或 props.X 用法\ngrep -E \"\\{ .* \\}.*props|\\bprops\\.[a-zA-Z]+\" \"$component_path\"\n\n# API 调用存在（对于数据获取组件）\ngrep -E \"fetch\\(|axios\\.|useSWR|useQuery|getServerSideProps|getStaticProps\" \"$component_path\"\n```\n\n**功能验证（需要人工）：**\n- 组件是否渲染可见内容？\n- 交互元素是否响应点击？\n- 数据是否加载并显示？\n- 错误状态是否适当显示？\n\n\n\n\n\n## API 路由（Next.js App Router / Express 等）\n\n**存在检查：**\n```bash\n# 路由文件存在\n[ -f \"$route_path\" ]\n\n# 导出 HTTP 方法处理器（Next.js App Router）\ngrep -E \"export (async )?(function|const) (GET|POST|PUT|PATCH|DELETE)\" \"$route_path\"\n\n# 或 Express 风格处理器\ngrep -E \"\\.(get|post|put|patch|delete)\\(\" \"$route_path\"\n```\n\n**实质性检查：**\n```bash\n# 有实际逻辑，不仅仅是 return 语句\nwc -l \"$route_path\" # 超过 10-15 行表明真实实现\n\n# 与数据源交互\ngrep -E \"prisma\\.|db\\.|mongoose\\.|sql|query|find|create|update|delete\" \"$route_path\" -i\n\n# 有错误处理\ngrep -E \"try|catch|throw|error|Error\" \"$route_path\"\n\n# 返回有意义的响应\ngrep -E \"Response\\.json|res\\.json|res\\.send|return.*\\{\" \"$route_path\" | grep -v \"message.*not implemented\" -i\n```\n\n**API 路由特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport async function POST() {\n return Response.json({ message: \"Not implemented\" })\n}\n\nexport async function GET() {\n return Response.json([]) // 空 array 无数据库查询\n}\n\nexport async function PUT() {\n return new Response() // 空响应\n}\n\n// 仅控制台日志：\nexport async function POST(req) {\n console.log(await req.json())\n return Response.json({ ok: true })\n}\n```\n\n**连接检查：**\n```bash\n# 导入数据库/服务客户端\ngrep -E \"^import.*prisma|^import.*db|^import.*client\" \"$route_path\"\n\n# 实际使用请求体（对于 POST/PUT）\ngrep -E \"req\\.json\\(\\)|req\\.body|request\\.json\\(\\)\" \"$route_path\"\n\n# 验证输入（不仅仅信任请求）\ngrep -E \"schema\\.parse|validate|zod|yup|joi\" \"$route_path\"\n```\n\n**功能验证（人工或自动化）：**\n- GET 是否从数据库返回真实数据？\n- POST 是否实际创建记录？\n- 错误响应是否有正确的状态码？\n- 认证检查是否实际执行？\n\n\n\n\n\n## 数据库模式（Prisma / Drizzle / SQL）\n\n**存在检查：**\n```bash\n# 模式文件存在\n[ -f \"prisma/schema.prisma\" ] || [ -f \"drizzle/schema.ts\" ] || [ -f \"src/db/schema.sql\" ]\n\n# 模型/表已定义\ngrep -E \"^model $model_name|CREATE TABLE $table_name|export const $table_name\" \"$schema_path\"\n```\n\n**实质性检查：**\n```bash\n# 有预期字段（不仅仅是 id）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"^\\s+\\w+\\s+\\w+\"\n\n# 有预期关系\ngrep -E \"@relation|REFERENCES|FOREIGN KEY\" \"$schema_path\"\n\n# 有适当的字段类型（不全是 String）\ngrep -A 20 \"model $model_name\" \"$schema_path\" | grep -E \"Int|DateTime|Boolean|Float|Decimal|Json\"\n```\n\n**模式特有的存根模式：**\n```prisma\n// 危险信号 - 这些是存根：\nmodel User {\n id String @id\n // TODO: add fields\n}\n\nmodel Message {\n id String @id\n content String // 只有一个真实字段\n}\n\n// 缺少关键字段：\nmodel Order {\n id String @id\n // 缺少: userId, items, total, status, createdAt\n}\n```\n\n**连接检查：**\n```bash\n# 迁移存在且已应用\nls prisma/migrations/ 2>/dev/null | wc -l # 应该 > 0\nnpx prisma migrate status 2>/dev/null | grep -v \"pending\"\n\n# 客户端已生成\n[ -d \"node_modules/.prisma/client\" ]\n```\n\n**功能验证：**\n```bash\n# 可以查询表（自动化）\nnpx prisma db execute --stdin <<< \"SELECT COUNT(*) FROM $table_name\"\n```\n\n\n\n\n\n## 自定义 Hooks 和工具\n\n**存在检查：**\n```bash\n# 文件存在且导出函数\n[ -f \"$hook_path\" ] && grep -E \"export (default )?(function|const)\" \"$hook_path\"\n```\n\n**实质性检查：**\n```bash\n# Hook 使用 React hooks（对于自定义 hooks）\ngrep -E \"useState|useEffect|useCallback|useMemo|useRef|useContext\" \"$hook_path\"\n\n# 有有意义的返回值\ngrep -E \"return \\{|return \\[\" \"$hook_path\"\n\n# 超过琐碎长度\n[ $(wc -l < \"$hook_path\") -gt 10 ]\n```\n\n**Hooks 特有的存根模式：**\n```typescript\n// 危险信号 - 这些是存根：\nexport function useAuth() {\n return { user: null, login: () => {}, logout: () => {} }\n}\n\nexport function useCart() {\n const [items, setItems] = useState([])\n return { items, addItem: () => console.log('add'), removeItem: () => {} }\n}\n\n// 硬编码返回：\nexport function useUser() {\n return { name: \"Test User\", email: \"test@example.com\" }\n}\n```\n\n**连接检查：**\n```bash\n# Hook 实际在某处被导入\ngrep -r \"import.*$hook_name\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n\n# Hook 实际被调用\ngrep -r \"$hook_name()\" src/ --include=\"*.tsx\" --include=\"*.ts\" | grep -v \"$hook_path\"\n```\n\n\n\n\n\n## 环境变量和配置\n\n**存在检查：**\n```bash\n# .env 文件存在\n[ -f \".env\" ] || [ -f \".env.local\" ]\n\n# 必需变量已定义\ngrep -E \"^$VAR_NAME=\" .env .env.local 2>/dev/null\n```\n\n**实质性检查：**\n```bash\n# 变量有实际值（非占位符）\ngrep -E \"^$VAR_NAME=.+\" .env .env.local 2>/dev/null | grep -v \"your-.*-here|xxx|placeholder|TODO\" -i\n\n# 值对类型看起来有效：\n# - URL 应以 http 开头\n# - 密钥应足够长\n# - 布尔值应为 true/false\n```\n\n**环境变量特有的存根模式：**\n```bash\n# 危险信号 - 这些是存根：\nDATABASE_URL=your-database-url-here\nSTRIPE_SECRET_KEY=sk_test_xxx\nAPI_KEY=placeholder\nNEXT_PUBLIC_API_URL=http://localhost:3000 # 生产环境仍指向 localhost\n```\n\n**连接检查：**\n```bash\n# 变量实际在代码中使用\ngrep -r \"process\\.env\\.$VAR_NAME|env\\.$VAR_NAME\" src/ --include=\"*.ts\" --include=\"*.tsx\"\n\n# 变量在验证模式中（如果使用 zod 等验证 env）\ngrep -E \"$VAR_NAME\" src/env.ts src/env.mjs 2>/dev/null\n```\n\n\n\n\n\n## 连接验证模式\n\n连接验证检查组件是否实际通信。这是大多数存根隐藏的地方。\n\n### 模式：组件 → API\n\n**检查：** 组件是否实际调用 API？\n\n```bash\n# 查找 fetch/axios 调用\ngrep -E \"fetch\\(['\\\"].*$api_path|axios\\.(get|post).*$api_path\" \"$component_path\"\n\n# 验证未被注释掉\ngrep -E \"fetch\\(|axios\\.\" \"$component_path\" | grep -v \"^.*//.*fetch\"\n\n# 检查响应被使用\ngrep -E \"await.*fetch|\\.then\\(|setData|setState\" \"$component_path\"\n```\n\n**危险信号：**\n```typescript\n// Fetch 存在但响应被忽略：\nfetch('/api/messages') // 无 await，无 .then，无赋值\n\n// Fetch 在注释中：\n// fetch('/api/messages').then(r => r.json()).then(setMessages)\n\n// Fetch 到错误的端点：\nfetch('/api/message') // 拼写错误 - 应该是 /api/messages\n```\n\n### 模式：API → 数据库\n\n**检查：** API 路由是否实际查询数据库？\n\n```bash\n# 查找数据库调用\ngrep -E \"prisma\\.$model|db\\.query|Model\\.find\" \"$route_path\"\n\n# 验证被 await\ngrep -E \"await.*prisma|await.*db\\.\" \"$route_path\"\n\n# 检查结果被返回\ngrep -E \"return.*json.*data|res\\.json.*result\" \"$route_path\"\n```\n\n**危险信号：**\n```typescript\n// 查询存在但结果未返回：\nawait prisma.message.findMany()\nreturn Response.json({ ok: true }) // 返回静态值，非查询结果\n\n// 查询未被 await：\nconst messages = prisma.message.findMany() // 缺少 await\nreturn Response.json(messages) // 返回 Promise，非数据\n```\n\n### 模式：表单 → 处理器\n\n**检查：** 表单提交是否实际做些什么？\n\n```bash\n# 查找 onSubmit 处理器\ngrep -E \"onSubmit=\\{|handleSubmit\" \"$component_path\"\n\n# 检查处理器有内容\ngrep -A 10 \"onSubmit.*=\" \"$component_path\" | grep -E \"fetch|axios|mutate|dispatch\"\n\n# 验证不仅仅是 preventDefault\ngrep -A 5 \"onSubmit\" \"$component_path\" | grep -v \"only.*preventDefault\" -i\n```\n\n**危险信号：**\n```typescript\n// 处理器仅阻止默认：\nonSubmit={(e) => e.preventDefault()}\n\n// 处理器仅日志：\nconst handleSubmit = (data) => {\n console.log(data)\n}\n\n// 处理器为空：\nonSubmit={() => {}}\n```\n\n### 模式：状态 → 渲染\n\n**检查：** 组件是否渲染状态，而非硬编码内容？\n\n```bash\n# 查找 JSX 中的状态使用\ngrep -E \"\\{.*messages.*\\}|\\{.*data.*\\}|\\{.*items.*\\}\" \"$component_path\"\n\n# 检查状态的 map/render\ngrep -E \"\\.map\\(|\\.filter\\(|\\.reduce\\(\" \"$component_path\"\n\n# 验证动态内容\ngrep -E \"\\{[a-zA-Z_]+\\.\" \"$component_path\" # 变量插值\n```\n\n**危险信号：**\n```tsx\n// 硬编码而非状态：\nreturn
\n

Message 1

\n

Message 2

\n
\n\n// 状态存在但未渲染：\nconst [messages, setMessages] = useState([])\nreturn
No messages
// 总是显示 \"no messages\"\n\n// 渲染错误的状态：\nconst [messages, setMessages] = useState([])\nreturn
{otherData.map(...)}
// 使用不同数据\n```\n\n\n\n\n\n## 快速验证清单\n\n对于每种工件类型，运行此清单：\n\n### 组件清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数/const 组件\n- [ ] 返回 JSX（非 null/空）\n- [ ] 渲染中无占位符文本\n- [ ] 使用 props 或 state（非静态）\n- [ ] 事件处理器有真实实现\n- [ ] 导入正确解析\n- [ ] 在应用某处被使用\n\n### API 路由清单\n- [ ] 文件存在于预期路径\n- [ ] 导出 HTTP 方法处理器\n- [ ] 处理器超过 5 行\n- [ ] 查询数据库或服务\n- [ ] 返回有意义的响应（非空/占位符）\n- [ ] 有错误处理\n- [ ] 验证输入\n- [ ] 从前端调用\n\n### 模式清单\n- [ ] 模型/表已定义\n- [ ] 有所有预期字段\n- [ ] 字段有适当类型\n- [ ] 如需要关系已定义\n- [ ] 迁移存在且已应用\n- [ ] 客户端已生成\n\n### Hook/工具清单\n- [ ] 文件存在于预期路径\n- [ ] 导出函数\n- [ ] 有有意义的实现（非空返回）\n- [ ] 在应用某处被使用\n- [ ] 返回值被消费\n\n### 连接清单\n- [ ] 组件 → API: fetch/axios 调用存在且使用响应\n- [ ] API → 数据库: 查询存在且结果返回\n- [ ] 表单 → 处理器: onSubmit 调用 API/mutation\n- [ ] 状态 → 渲染: 状态变量出现在 JSX 中\n\n\n\n\n\n## 自动化验证方法\n\n对于验证子代理，使用此模式：\n\n```bash\n# 1. 检查存在\ncheck_exists() {\n [ -f \"$1\" ] && echo \"EXISTS: $1\" || echo \"MISSING: $1\"\n}\n\n# 2. 检查存根模式\ncheck_stubs() {\n local file=\"$1\"\n local stubs=$(grep -c -E \"TODO|FIXME|placeholder|not implemented\" \"$file\" 2>/dev/null || echo 0)\n [ \"$stubs\" -gt 0 ] && echo \"STUB_PATTERNS: $stubs in $file\"\n}\n\n# 3. 检查连接（组件调用 API）\ncheck_wiring() {\n local component=\"$1\"\n local api_path=\"$2\"\n grep -q \"$api_path\" \"$component\" && echo \"WIRED: $component → $api_path\" || echo \"NOT_WIRED: $component → $api_path\"\n}\n\n# 4. 检查实质性（超过 N 行，有预期模式）\ncheck_substantive() {\n local file=\"$1\"\n local min_lines=\"$2\"\n local pattern=\"$3\"\n local lines=$(wc -l < \"$file\" 2>/dev/null || echo 0)\n local has_pattern=$(grep -c -E \"$pattern\" \"$file\" 2>/dev/null || echo 0)\n [ \"$lines\" -ge \"$min_lines\" ] && [ \"$has_pattern\" -gt 0 ] && echo \"SUBSTANTIVE: $file\" || echo \"THIN: $file ($lines lines, $has_pattern matches)\"\n}\n```\n\n对每个必须有工件运行这些检查。汇总结果到 VERIFICATION.md。\n\n\n\n\n\n## 何时需要人工验证\n\n有些事情无法编程验证。标记这些需要人工测试：\n\n**始终人工：**\n- 视觉外观（看起来对吗？）\n- 用户流程完成（能实际做那件事吗？）\n- 实时行为（WebSocket、SSE）\n- 外部服务集成（Stripe、邮件发送）\n- 错误消息清晰度（消息有帮助吗？）\n- 性能感觉（感觉快吗？）\n\n**如不确定则人工：**\n- grep 无法追踪的复杂连接\n- 依赖状态的动态行为\n- 边缘情况和错误状态\n- 移动端响应式\n- 无障碍性\n\n**人工验证请求格式：**\n```markdown\n## 需要人工验证\n\n### 1. 聊天消息发送\n**测试：** 输入消息并点击发送\n**预期：** 消息出现在列表中，输入框清空\n**检查：** 刷新后消息是否持久？\n\n### 2. 错误处理\n**测试：** 断开网络，尝试发送\n**预期：** 错误消息出现，消息未丢失\n**检查：** 重连后能重试吗？\n```\n\n\n\n\n\n## 检查点前自动化\n\n关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议，请参阅：\n\n**@~/.claude/get-shit-done/references/checkpoints.md** → `` 部分\n\n关键原则：\n- Claude 在呈现检查点**之前**设置验证环境\n- 用户从不运行 CLI 命令（仅访问 URL）\n- 服务器生命周期：检查点前启动、处理端口冲突、持续运行\n- CLI 安装：安全处自动安装，否则检查点让用户选择\n- 错误处理：检查点前修复损坏环境，绝不呈现有失败设置的检查点\n\n\n\n\n# Shared Theme System\n\nAll sketches share a CSS variable theme so design decisions compound across sketches.\n\n## Setup\n\nOn the first sketch, create `.planning/sketches/themes/` with a default theme:\n\n```\n.planning/sketches/\n themes/\n default.css <- all sketches link to this\n 001-dashboard-layout/\n index.html <- links to ../themes/default.css\n```\n\n## Theme File Structure\n\nEach theme defines CSS custom properties only — no component styles, no layout rules. Just the visual vocabulary:\n\n```css\n:root {\n /* Colors */\n --color-bg: #fafafa;\n --color-surface: #ffffff;\n --color-border: #e5e5e5;\n --color-text: #1a1a1a;\n --color-text-muted: #6b6b6b;\n --color-primary: #2563eb;\n --color-primary-hover: #1d4ed8;\n --color-accent: #f59e0b;\n --color-danger: #ef4444;\n --color-success: #22c55e;\n\n /* Typography */\n --font-sans: 'Inter', system-ui, sans-serif;\n --font-mono: 'JetBrains Mono', monospace;\n --text-xs: 0.75rem;\n --text-sm: 0.875rem;\n --text-base: 1rem;\n --text-lg: 1.125rem;\n --text-xl: 1.25rem;\n --text-2xl: 1.5rem;\n --text-3xl: 1.875rem;\n\n /* Spacing */\n --space-1: 4px;\n --space-2: 8px;\n --space-3: 12px;\n --space-4: 16px;\n --space-6: 24px;\n --space-8: 32px;\n --space-12: 48px;\n\n /* Shapes */\n --radius-sm: 4px;\n --radius-md: 8px;\n --radius-lg: 12px;\n --radius-full: 9999px;\n\n /* Shadows */\n --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);\n --shadow-md: 0 4px 6px rgba(0,0,0,0.07);\n --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);\n}\n```\n\nAdapt the default theme to match the mood/direction established during intake. The values above are a starting point — change colors, fonts, spacing, and shapes to match the agreed aesthetic.\n\n## Linking\n\nEvery sketch links to the theme:\n\n```html\n\n```\n\n## Creating New Themes\n\nWhen a sketch reveals an aesthetic fork (\"should this feel clinical or warm?\"), create both as theme files rather than arguing about it. The user can switch and feel the difference.\n\nName themes descriptively: `midnight.css`, `warm-minimal.css`, `brutalist.css`.\n\n## Theme Switcher\n\nInclude in every sketch (part of the sketch toolbar):\n\n```html\n\n```\n\nDynamically populate options by listing available theme files, or hardcode the known themes.\n\n\n# CJS↔SDK Hard-Seam Migration: Complete Reference\n## Issue #3575 (Parent: #3524)\n\n---\n\n## Migration overview\n\nThe CJS↔SDK hard-seam migration (#3524) eliminates a class of config-schema drift bugs by introducing single sources of truth at every decision point where CJS and SDK code previously diverged. The migration proceeded in six phases:\n\n| Phase | PR | Summary |\n|-------|----|---------|\n| Phase 1 | [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) | `state-document` Shared Module — source-of-truth at `sdk/src/state-document/`, generator, freshness check, CJS Adapter (`state-document.generated.cjs`). Worked example for the pattern. |\n| Phase 2 | [#3540](https://github.com/gsd-build/get-shit-done/pull/3540) | `configuration` Shared Module — `sdk/shared/config-schema.manifest.json` + `sdk/shared/config-defaults.manifest.json` as data manifests; generator + freshness check + CJS Adapter. |\n| Phase 3 | [#3548](https://github.com/gsd-build/get-shit-done/pull/3548) | `workstream-inventory` Shared Module — source-of-truth at `sdk/src/workstream-inventory/`, builder, generator, freshness check, CJS Adapter. |\n| Phase 4 | [#3554](https://github.com/gsd-build/get-shit-done/pull/3554) | `project-root` Shared Module — source-of-truth at `sdk/src/project-root/`, generator, freshness check, CJS Adapter. |\n| Phase 5.0 | [#3558](https://github.com/gsd-build/get-shit-done/pull/3558) | `runtime-bridge-sync` worker — enables CJS-side execution of SDK native handlers; state.* family initial router delegation via `executeForCjs`. |\n| Phase 5.1 | [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) | `state.*` router delegation complete — all known state subcommands delegated via `executeForCjs`; Phase 5.0 worker bug fix. |\n| Phase 6 | [#3577](https://github.com/gsd-build/get-shit-done/pull/3577) (closes [#3575](https://github.com/gsd-build/get-shit-done/issues/3575)) | Enforcement hardening + Final completion — hand-sync drift lint, CODEOWNERS, 6 family-router migrations, 5 Shared Module migrations (plan-scan, secrets, schema-detect, decisions, workstream-name-policy), workstream native support, parity fixes. Migration feature-complete: 22 cooperating siblings, 0 backlog pairs. |\n\n---\n\n## Phase 6 Retrospective: 15 config-schema drift bugs\n\nThis section captures 15 recurring config-schema drift bugs that motivated the migration. For each, we record what drifted, the surgical fix, and which Phase 6 enforcement layer would have prevented it.\n\n---\n\n### #1535 — Silent failure on unrecognized config.json keys\n- **Drifted:** `loadConfig` silently ignored any top-level key in `.planning/config.json` not in `VALID_CONFIG_KEYS`, giving users no feedback when hand-edited or external-tool-added keys had no effect.\n- **Fix landed:** PR #1542 — added stderr warning listing unrecognized keys.\n- **Would have been blocked by:** **handsync lint** — a seam-aware linter would forbid having parallel hand-authored config validators (CJS `config.cjs` and SDK `config-mutation.ts`) that could silently diverge.\n\n---\n\n### #1542 — fix(config): warn on unrecognized keys in config.json instead of silent drop\n- **Drifted:** No drift in this bug itself; it *fixed* #1535's silent-drop behavior by adding the warning.\n- **Fix landed:** PR #1542 — merged as the direct fix for #1535.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check on config validation) — both CJS and SDK config paths would be regenerated from a single source-of-truth schema module, eliminating the silent-drop risk.\n\n---\n\n### #2047 — bug: config-set rejects intel.enabled despite being a documented config key\n- **Drifted:** `intel.enabled` was documented in workflows and gated in runtime code (`intel.cjs:58`), but missing from `VALID_CONFIG_KEYS` in `config.cjs`, so `config-set` rejected it.\n- **Fix landed:** PR #2021 — added `intel.enabled` to `VALID_CONFIG_KEYS` in CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every config key gated in runtime code or documented in workflows must appear in the validator allowlist.\n\n---\n\n### #2052 — fix(config): add intel.enabled to VALID_CONFIG_KEYS\n- **Drifted:** Same as #2047 (missing from allowlist).\n- **Fix landed:** PR #2021 (same PR as #2047 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2047.\n\n---\n\n### #2638 — bug: loadConfig writes sub_repos to top-level, then warns it's unknown\n- **Drifted:** After #2561 canonicalized `sub_repos` to `planning.sub_repos`, the legacy migration and filesystem auto-sync in `loadConfig` still wrote to top-level `parsed.sub_repos`, which was then flagged as unknown.\n- **Fix landed:** PR #2668 — rewrote both paths to target `parsed.planning.sub_repos` and deleted stale top-level copy.\n- **Would have been blocked by:** **per-Module drift lint** (freshness check for config shape) — the canonical location for `sub_repos` would be codified in a schema, and any code path writing to it would be verified against that schema at lint time.\n\n---\n\n### #2655 — fix(core): write sub_repos to planning.sub_repos, not top-level\n- **Drifted:** Same as #2638.\n- **Fix landed:** PR #2668 (same as #2638 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2638.\n\n---\n\n### #2653 — bug: SDK config-set rejects documented config keys accepted by CJS config-set\n- **Drifted:** SDK's `config-mutation.ts` had a hand-maintained `VALID_CONFIG_KEYS` set that had drifted **28 keys** behind CJS's `config-schema.cjs`, so documented commands like `gsd-sdk query config-set planning.sub_repos` were rejected.\n- **Fix landed:** PR #2670 — extracted shared `sdk/src/query/config-schema.ts` module mirroring CJS exactly; added parity test to fail on future drift.\n- **Would have been blocked by:** **manifest data isolation** — the config schema would live in one place (e.g., `sdk/shared/config.manifest.json`), and both CJS and SDK would read it, eliminating the possibility of independent drift.\n\n---\n\n### #2670 — fix(#2653): eliminate SDK↔CJS config-schema drift\n- **Drifted:** Same as #2653 (28-key drift).\n- **Fix landed:** PR #2670 (same as #2653 fix).\n- **Would have been blocked by:** **manifest data isolation** — same as #2653.\n\n---\n\n### #2687 — bug: loadConfig warns on valid dynamic-pattern containers in .planning/config.json\n- **Drifted:** Keys like `review.models.` were registered in `config-schema.cjs`'s `DYNAMIC_KEY_PATTERNS` but absent from the hand-maintained `KNOWN_TOP_LEVEL` set in `core.cjs`, causing false-positive \"unknown key\" warnings.\n- **Fix landed:** PR #2706 — added `topLevel` field to `DYNAMIC_KEY_PATTERNS` entries; derived `KNOWN_TOP_LEVEL` from schema instead of maintaining it manually.\n- **Would have been blocked by:** **per-Module drift lint** — the validator that builds `KNOWN_TOP_LEVEL` would be regenerated from the schema each run, not hand-maintained.\n\n---\n\n### #2706 — fix(#2687): loadConfig no longer warns on valid dynamic-pattern containers\n- **Drifted:** Same as #2687 (false warnings on valid dynamic keys).\n- **Fix landed:** PR #2706 (same as #2687 fix).\n- **Would have been blocked by:** **per-Module drift lint** — same as #2687.\n\n---\n\n### #2798 — context_window missing from VALID_CONFIG_KEYS\n- **Drifted:** `context_window` was documented in workflows and read in SDK runtime (`init.js:190`, `validate.js:575`), but missing from allowlists in both `config-mutation.ts` and `config-schema.cjs`, so writes were rejected.\n- **Fix landed:** PR #2816 — added `context_window` to `VALID_CONFIG_KEYS` in both SDK and CJS.\n- **Would have been blocked by:** **handsync lint** — linter would enforce that every key read at runtime must be in the allowlist.\n\n---\n\n### #2816 — fix(#2798): add context_window to VALID_CONFIG_KEYS allowlist\n- **Drifted:** Same as #2798 (missing from allowlists).\n- **Fix landed:** PR #2816 (same as #2798 fix).\n- **Would have been blocked by:** **handsync lint** — same as #2798.\n\n---\n\n### #3055 — bug: top-level branching_strategy silently becomes \"none\"\n- **Drifted:** `.planning/config.json` with top-level `branching_strategy: \"phase\"` was flagged as unknown and dropped by validator, causing `loadConfig` to fall back to the `\"none\"` default, so phase commits landed on the operator's current branch instead of creating `gsd/phase-{N}` branches.\n- **Fix landed:** PR #3116 — SDK-side only; added legacy normalization in `mergeDefaults()` to graft top-level value into canonical `git.branching_strategy` slot before validation.\n- **Would have been blocked by:** **per-Module drift lint** — the canonical location for `branching_strategy` would be codified in schema; validator would not strip the value before migrations had a chance to run, or CJS and SDK would share the same migration code.\n\n---\n\n### #3116 — fix: normalize legacy top-level branching_strategy into git config\n- **Drifted:** Same as #3055 (legacy top-level shape not normalized before validator strips it).\n- **Fix landed:** PR #3116 (SDK-side normalization in `mergeDefaults()`).\n- **Would have been blocked by:** **per-Module drift lint** — same as #3055, but SDK-side fix would be shared with CJS via seam layer instead of being ported separately.\n\n---\n\n### #3523 — bug: CJS loadConfig warns top-level branching_strategy 'will be ignored', but actively reads it\n- **Drifted:** After PR #3116 fixed the SDK side, the CJS path still emitted false \"will be ignored\" warnings on the same legacy top-level key, because `KNOWN_TOP_LEVEL` derivation extracted top-level names from `VALID_CONFIG_KEYS` (which contains `'git.branching_strategy'` but not `'branching_strategy'`), and the warning was factually incorrect — `core.cjs:485` does read the legacy value via fallback logic.\n- **Fix landed:** PR #3527 — added `'branching_strategy'` to the `KNOWN_TOP_LEVEL` hand-maintained list under the deprecated-keys bucket, suppressing the false warning.\n- **Would have been blocked by:** **runtime-bridge delegation** — if CJS and SDK config loading shared a common normalization routine (via `executeForCjs` or a shared seam module), the SDK fix in #3116 would automatically apply to CJS; no separate CJS-side warning would be possible.\n\n---\n\n## Surprises\n\nNone. All 15 bugs are genuine CJS↔SDK schema/validation drift, exactly the class the seam migration prevents.\n\n## Phase 6 Enforcement Summary\n\nThe seam migration introduces these layers:\n\n1. **handsync lint** (`scripts/lint-shared-module-handsync.cjs`) — Forbids parallel hand-authored validator modules; catches #1535, #2047, #2798.\n2. **freshness check** (`sdk/scripts/check--fresh.mjs`) — Regenerates config validators from schema each run; catches #2687, #3055.\n3. **manifest data isolation** (`sdk/shared/*.manifest.json`) — Single source-of-truth for schema; catches #2653.\n4. **per-Module drift lint** — Combination of freshness checks and schema-derived allowlists; catches #2638, #2687, #3055.\n5. **runtime-bridge delegation** (`executeForCjs` + shared seam modules) — Eliminates parallel CJS/SDK implementations; catches #3523 by preventing separate CJS warning logic.\n\nTogether, these layers eliminate the 15-bug class by enforcing single sources of truth at each decision point.\n\n---\n\n## Guide: Adding a new Shared Module\n\nUse this when you want to extract a new piece of data or logic that both CJS and SDK currently duplicate hand-by-hand. Phase 1's `state-document` migration is the worked example.\n\n**Step 1 — Create the source-of-truth file**\n\n```text\nsdk/src//index.ts\n```\n\nThis is the canonical definition. It may export a schema, a set of keys, a type, or a data object. It must not import from CJS or from generated files.\n\n**Step 2 — Write the generator script**\n\n```text\nsdk/scripts/gen-.mjs\n```\n\nThe generator reads `sdk/src//index.ts` (or `sdk/shared/.manifest.json` for pure-data manifests), produces a generated output file (either `sdk/src/.generated.ts` or `get-shit-done/bin/lib/.generated.cjs`), and exits 0. It must be idempotent: running it twice produces the same output.\n\n**Step 3 — Write the freshness check**\n\n```text\nsdk/scripts/check--fresh.mjs\n```\n\nThe freshness check re-runs the generator into a temp location, diffs against the committed file, and exits 1 with a clear message if they diverge. This is what CI runs.\n\n**Step 4 — Write the parity test** (optional but recommended)\n\n```text\ntests/-parity.test.cjs\n```\n\nAssert that the CJS Adapter and the SDK source-of-truth agree on every field that matters (key sets, defaults, schema shape). This test catches generator bugs that the freshness check cannot.\n\n**Step 5 — Wire CI**\n\nAdd a step in `.github/workflows/test.yml` after the existing freshness-check block (before \"Run tests with coverage\"), gated on `matrix.os == 'ubuntu-latest' && matrix.node-version == 24`:\n\n```yaml\n- name: SDK generated artifact drift check\n if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24\n shell: bash\n run: node sdk/scripts/check--fresh.mjs\n```\n\n**Step 6 — Run inventory regen**\n\nIf the module affects `CONTEXT.md`'s module inventory, update that section. Also update `scripts/shared-module-handsync-allowlist.json`: move any matching entry from `migrateMeBacklog` to `cooperatingSiblings` (or remove it entirely if the CJS hand-copy is now deleted).\n\n**Step 7 — Update CODEOWNERS**\n\nAdd the new source-of-truth path to `.github/CODEOWNERS` under the Phase 6 block to make the architectural ownership explicit.\n\n**Reference:** Phase 1 PR [#3531](https://github.com/gsd-build/get-shit-done/pull/3531) — `state-document` migration.\n\n---\n\n## Guide: Adding a new canonical command\n\nUse this when adding a new `gsd-sdk query .` that should be handled natively in the SDK (not delegated to CJS). Phase 5.1's `state.update` migration (PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574)) is the worked example.\n\n**Step 1 — Declare in the command manifest**\n\nAdd the command definition to `sdk/src/query/command-manifest..ts`. Include the full argument schema and a `handler` reference.\n\n**Step 2 — Implement the SDK handler**\n\nWrite the handler in `sdk/src/query/.ts` (or inline in the manifest file for simple cases). The handler receives validated args and the runtime context; it must not shell out to CJS.\n\n**Step 3 — Add CJS router delegate (Phase 5.1+ pattern)**\n\nIn the family's CJS command router (e.g. `get-shit-done/bin/lib/state-command-router.cjs`), add a delegate case that calls `executeForCjs(subcommand, args)` from `cjs-command-router-adapter.cjs`. This ensures the CJS binary dispatches to the SDK native handler rather than re-implementing the logic.\n\n**Step 4 — Add a golden parity test**\n\nAdd a test in `tests/-command-router.test.cjs` (or a new file if the family has no test yet) that:\n1. Invokes the command via the SDK query path.\n2. Invokes the command via the CJS router path.\n3. Asserts both produce identical output.\n\nThis test enforces that the delegate and the native handler stay aligned.\n\n**Reference:** Phase 5.1 PR [#3574](https://github.com/gsd-build/get-shit-done/pull/3574) — `state.update` delegation.\n\n---\n\n## Phase 6 Final Completion Summary\n\nPhase 6 (issue #3575, PR #3577) is feature-complete. The migration is done.\n\n**What shipped in Phase 6:**\n\n- **Shared Modules migrated (5 total in Phase 6):** `plan-scan`, `secrets`, `schema-detect`, `decisions`, `workstream-name-policy`. Each follows the full pattern: SDK source-of-truth, generator (`gen-.mjs`), freshness check (`check--fresh.mjs`), generated CJS artifact (`.generated.cjs`), CJS shim re-export, parity test, CI step, pre-commit hook, CODEOWNERS entry.\n- **Workstream native support:** The sync bridge worker now correctly threads `workstream` through to `registry.dispatch()`. `GSDTransport` no longer forces subprocess for workstream-scoped requests. Workstream-scoped state commands execute natively.\n- **State parity divergences resolved:** `state.record-metric` and `state.prune` SDK handlers now match CJS semantics exactly.\n- **MIGRATE_ME pairs resolved:** `decisions` and `workstream-name-policy` migrated from `migrateMeBacklog` to `cooperatingSiblings` as ADAPTER-OVER-MODULE.\n- **Lint final state:** 22 cooperating siblings, 0 backlog pairs.\n\n**Decisions migration specifics (B1):**\n- SDK `decisions.ts` regex aligned to CJS: `D-([A-Za-z0-9_-]+)` (alphanumeric IDs like `D-INFRA-01` accepted).\n- SDK returns richer `{id, text, category, tags, trackable}`; CJS callers using only `{id, text}` safely ignore extras.\n- Parity test: `tests/decisions-generator.test.cjs` (15 tests covering numeric IDs, alphanumeric IDs, richer schema fields).\n\n**Workstream-name-policy migration specifics (B2):**\n- Added `hasInvalidPathSegment` and `isValidActiveWorkstreamName` to SDK `workstream-name-policy.ts`.\n- `validateWorkstreamName` is now an alias for `isValidActiveWorkstreamName` (consistent with CJS semantics).\n- Parity test: `tests/workstream-name-policy-generator.test.cjs` (19 tests covering all four exports).\n\n---\n\n## Open follow-ups\n\nNo migration items remain. The following are future quality candidates, not defects:\n\n- **`config.cjs` / `sdk/src/config.ts`** — These files are CJS-CLI-ONLY (per allowlist classification). The `config.cjs` file contains only CLI command handlers that use sync CJS APIs; `sdk/src/config.ts` provides the async SDK layer. They serve disjoint surfaces. A future migration would require converting the CLI handlers to async + SDK patterns, which is a larger refactor out of scope for this migration cycle.\n- **`intel.cjs` / `sdk/src/query/intel.ts`** — Intentional architectural divergence (different file naming conventions between CJS and SDK; documented in allowlist). A future migration would require reconciling INTEL_FILES naming, which is a breaking change for existing consumers.\n- **`model-catalog.cjs` / `sdk/src/model-catalog.ts`** — Both sides read from `sdk/shared/model-catalog.json` independently (ADAPTER-OVER-MODULE pattern). This is intentional; the shared JSON is the source-of-truth. No duplication of logic between CJS and SDK consumers.\n\n\n# Domain Docs\n\nHow engineering skills consume this repo's domain documentation.\n\n## Layout: single-context\n\n```\n/\n├── CONTEXT.md ← domain glossary + recurring PR rules + workflow learnings\n├── docs/adr/ ← architectural decisions\n│ ├── 0001-dispatch-policy-module.md\n│ └── 0002-command-contract-validation-module.md\n└── ...\n```\n\n## Before exploring, read these\n\n1. **`CONTEXT.md`** at the repo root — domain terms, module names, recurring PR mistakes, workflow learnings. Read in full before naming anything or proposing architecture changes.\n2. **`docs/adr/`** — read ADRs relevant to the area you're working in before proposing structural changes. If your output contradicts an ADR, surface it explicitly:\n > *Contradicts ADR-0002 — but worth reopening because…*\n\nIf either file doesn't exist yet, proceed silently.\n\n## Use the glossary's vocabulary\n\nWhen naming modules, writing issue titles, test descriptions, or commit messages — use terms as defined in `CONTEXT.md`. Don't drift to synonyms. If you need a concept that isn't in the glossary, note it for `/grill-with-docs` rather than inventing language.\n\n## CONTEXT.md sections\n\n- **Domain terms** — canonical module names and seam vocabulary (Dispatch Policy Module, Command Contract Validation Module, etc.)\n- **Recurring PR mistakes** — CodeRabbit findings that recur; check before writing tests, shell scripts, changesets, or docs\n- **Workflow learnings** — patterns learned from triage + PR cycles; check before writing new command/workflow files or test paths\n\n\n# Issue tracker: GitHub\n\nIssues for this repo live in **GitHub Issues** at `gsd-build/get-shit-done`.\n\n## Auth\n\nUse the configured GitHub CLI session for this checkout. Do not require a\nrepo-local `.envrc` before running `gh`.\n\n## Conventions\n\n- **Create**: `gh issue create --repo gsd-build/get-shit-done --title \"...\" --body \"...\"`\n- **Read**: `gh issue view --repo gsd-build/get-shit-done --comments`\n- **List**: `gh issue list --repo gsd-build/get-shit-done --state open --json number,title,labels --jq '...'`\n- **Comment**: `gh issue comment --repo gsd-build/get-shit-done --body \"...\"`\n- **Label**: `gh issue edit --repo gsd-build/get-shit-done --add-label \"...\" --remove-label \"...\"`\n- **Close**: `gh issue close --repo gsd-build/get-shit-done --comment \"...\"`\n\nAlways pass `--repo gsd-build/get-shit-done` explicitly — the local clone has multiple remotes and `gh` may resolve to the wrong one.\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a GitHub issue at `gsd-build/get-shit-done`.\n\n## When a skill says \"fetch the relevant ticket\"\n\nRun `gh issue view --repo gsd-build/get-shit-done --comments`.\n\n\n# Triage Labels\n\nMaps the five canonical triage roles to the actual label strings in `gsd-build/get-shit-done`.\n\n| Canonical role | Label in this repo | Notes |\n|-------------------|--------------------------|----------------------------------------------------------------|\n| `needs-triage` | `needs-triage` | Auto-applied by GitHub Action on every new issue |\n| `needs-info` | `needs-reproduction` | Waiting on reporter — cannot reproduce, more info required |\n| `ready-for-agent` | `confirmed` | Bug verified + fully specified — AFK agent can pick up |\n| `ready-for-human` | `approved-enhancement` / `approved-feature` | Enhancement/feature approved by maintainer — human codes it |\n| `wontfix` | `wontfix` | Will not be actioned |\n\n## Notes on this repo's label model\n\n- `confirmed` is the AFK-agent-ready signal for **bugs**. It means \"verified to exist and reproducible.\"\n- For **enhancements** and **features**, maintainer approval is `approved-enhancement` / `approved-feature` respectively. A contributor (human or agent) may not write code until one of these is applied.\n- There is no separate \"ready-for-human\" vs \"ready-for-agent\" distinction for enhancements — both flow through the same `approved-*` labels. If the work requires human judgment (design decisions, external access), note it in the issue body.\n- `needs-triage` is removed when any other state label is applied.\n- `needs-reproduction` is used instead of the generic `needs-info` — be specific in triage comments about what reproduction steps or information are missing.\n\n\n---\ntype: prompt\nname: gsd:milestone-summary\ndescription: Generate a comprehensive project summary from milestone artifacts for team onboarding and review\nargument-hint: \"[version]\"\nallowed-tools:\n - Read\n - Write\n - Bash\n - Grep\n - Glob\n---\n\n\nGenerate a structured milestone summary for team onboarding and project review. Reads completed milestone artifacts (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION files) and produces a human-friendly overview of what was built, how, and why.\n\nPurpose: Enable new team members to understand a completed project by reading one document and asking follow-up questions.\nOutput: MILESTONE_SUMMARY written to `.planning/reports/`, presented inline, optional interactive Q&A.\n\n\n\n@~/.claude/get-shit-done/workflows/milestone-summary.md\n\n\n\n**Project files:**\n- `.planning/ROADMAP.md`\n- `.planning/PROJECT.md`\n- `.planning/STATE.md`\n- `.planning/RETROSPECTIVE.md`\n- `.planning/milestones/v{version}-ROADMAP.md` (if archived)\n- `.planning/milestones/v{version}-REQUIREMENTS.md` (if archived)\n- `.planning/phases/*-*/` (SUMMARY.md, VERIFICATION.md, CONTEXT.md, RESEARCH.md)\n\n**User input:**\n- Version: $ARGUMENTS (optional — defaults to current/latest milestone)\n\n\n\nExecute end-to-end.\n\n\n\n- Milestone version resolved (from args, STATE.md, or archive scan)\n- All available artifacts read (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION, RESEARCH, RETROSPECTIVE)\n- Summary document written to `.planning/reports/MILESTONE_SUMMARY-v{version}.md`\n- All 7 sections generated (Overview, Architecture, Phases, Decisions, Requirements, Tech Debt, Getting Started)\n- Summary presented inline to user\n- Interactive Q&A offered\n- STATE.md updated\n\n\n\n# GSD Architecture\n\n> System architecture for contributors and advanced users. For user-facing documentation, see [Feature Reference](FEATURES.md) or [User Guide](USER-GUIDE.md).\n\n---\n\n## Table of Contents\n\n- [System Overview](#system-overview)\n- [Design Principles](#design-principles)\n- [Component Architecture](#component-architecture)\n- [Agent Model](#agent-model)\n- [Data Flow](#data-flow)\n- [File System Layout](#file-system-layout)\n- [Installer Architecture](#installer-architecture)\n- [Hook System](#hook-system)\n- [CLI Tools Layer](#cli-tools-layer)\n- [Runtime Abstraction](#runtime-abstraction)\n\n---\n\n## System Overview\n\nGSD is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:\n\n1. **Context engineering** — Structured artifacts that give the AI everything it needs per task\n2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows\n3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline\n4. **State management** — Persistent project memory across sessions and context resets\n\n```\n┌──────────────────────────────────────────────────────┐\n│ USER │\n│ /gsd-command [args] │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ COMMAND LAYER │\n│ commands/gsd/*.md — Prompt-based command files │\n│ (Claude Code custom commands / Codex skills) │\n└─────────────────────┬────────────────────────────────┘\n │\n┌─────────────────────▼────────────────────────────────┐\n│ WORKFLOW LAYER │\n│ get-shit-done/workflows/*.md — Orchestration logic │\n│ (Reads references, spawns agents, manages state) │\n└──────┬──────────────┬─────────────────┬──────────────┘\n │ │ │\n┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐\n│ AGENT │ │ AGENT │ │ AGENT │\n│ (fresh │ │ (fresh │ │ (fresh │\n│ context) │ │ context)│ │ context) │\n└──────┬──────┘ └─────┬─────┘ └────────┬───────┘\n │ │ │\n┌──────▼──────────────▼─────────────────▼──────────────┐\n│ CLI TOOLS LAYER │\n│ gsd-sdk query (sdk/src/query) + gsd-tools.cjs │\n│ Programmatic SDK bridge: GSDTools/query-runtime-bridge.ts │\n└──────────────────────┬───────────────────────────────┘\n │\n┌──────────────────────▼───────────────────────────────┐\n│ FILE SYSTEM (.planning/) │\n│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │\n│ STATE.md | config.json | phases/ | research/ │\n└──────────────────────────────────────────────────────┘\n```\n\n---\n\n## Design Principles\n\n### 1. Fresh Context Per Agent\n\nEvery agent spawned by an orchestrator gets a clean context window (up to 200K tokens). This eliminates context rot — the quality degradation that happens as an AI fills its context window with accumulated conversation.\n\n### 2. Thin Orchestrators\n\nWorkflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:\n\n- Load context via `gsd-sdk query init.` (or legacy `gsd-tools.cjs init `)\n- Spawn specialized agents with focused prompts\n- Collect results and route to the next step\n- Update state between steps\n\n### 3. File-Based State\n\nAll state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means:\n\n- State survives context resets (`/clear`)\n- State is inspectable by both humans and agents\n- State can be committed to git for team visibility\n\n### 4. Absent = Enabled\n\nWorkflow feature flags follow the **absent = enabled** pattern. If a key is missing from `config.json`, it defaults to `true`. Users explicitly disable features; they don't need to enable defaults.\n\n### 5. Defense in Depth\n\nMultiple layers prevent common failure modes:\n\n- Plans are verified before execution (plan-checker agent)\n- Execution produces atomic commits per task\n- Post-execution verification checks against phase goals\n- UAT provides human verification as final gate\n\n---\n\n## Component Architecture\n\n### Commands (`commands/gsd/*.md`)\n\nUser-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as:\n\n- **Claude Code:** Custom slash commands (hyphen form, `/gsd-command-name`)\n- **OpenCode / Kilo:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Codex:** Skills (`$gsd-command-name`)\n- **Copilot:** Slash commands (hyphen form, `/gsd-command-name`)\n- **Gemini CLI:** Slash commands under the `gsd:` namespace (colon form, `/gsd:command-name`) — Gemini namespaces all custom commands under their plugin id, so the install path rewrites every body-text reference to colon form\n- **Antigravity:** Skills\n\n**Total commands:** see [`docs/INVENTORY.md`](INVENTORY.md#commands) for the authoritative count and full roster.\n\n#### Two-stage hierarchical routing (v1.40, [#2792](https://github.com/gsd-build/get-shit-done/issues/2792))\n\nTo keep the eager skill-listing token cost low, v1.40 introduces six namespace **meta-skills** (`gsd-workflow`, `gsd-project`, `gsd-quality`, `gsd-context`, `gsd-manage`, `gsd-ideate` — sourced from `commands/gsd/ns-*.md`, but the invocable `name:` is the bare form shown here) layered above the concrete sub-skills. The model sees 6 namespace routers (~120 tokens) instead of a flat 86-skill listing (~2,150 tokens), selects a namespace, then routes to the concrete sub-skill via a routing table embedded in the namespace router's body. Namespace skills are **additive** — every concrete command is still directly invocable.\n\nThe router descriptions use pipe-separated keyword tags (≤ 60 chars) per the Tool Attention research showing keyword-dense tags outperform prose for routing at ~40 % the token cost.\n\n#### MCP token-budget interaction\n\nThe eager skill listing is one of two recurring per-turn token costs. The other is the MCP tool schema injected by every enabled MCP server in `.claude/settings.json`. Heavyweight MCP servers (browser/playwright, Mac-tools, Windows-tools) can each cost 20 k+ tokens per turn — often dwarfing what `model_profile` tuning saves. The toggle lives in the Claude Code harness (`enabledMcpjsonServers` / `disabledMcpjsonServers` in `.claude/settings.json`) and is **not** a GSD concern. Together, the two-stage routing layer (#2792) and disciplined MCP enablement are the largest cost levers per turn. See [`docs/USER-GUIDE.md`](USER-GUIDE.md) and `references/context-budget.md` for the audit checklist.\n\n### Workflows (`get-shit-done/workflows/*.md`)\n\nOrchestration logic that commands reference. Contains the step-by-step process including:\n\n- Context loading via `gsd-sdk query` init handlers (or legacy `gsd-tools.cjs init`)\n- Agent spawn instructions with model resolution\n- Gate/checkpoint definitions\n- State update patterns\n- Error handling and recovery\n\n**Total workflows:** see [`docs/INVENTORY.md`](INVENTORY.md#workflows) for the authoritative count and full roster.\n\n#### Progressive disclosure for workflows\n\nWorkflow files are loaded verbatim into Claude's context every time the\ncorresponding `/gsd-*` command is invoked. To keep that cost bounded, the\nworkflow size budget enforced by `tests/workflow-size-budget.test.cjs`\nmirrors the agent budget from #2361:\n\n| Tier | Per-file line limit |\n|-----------|--------------------|\n| `XL` | 1700 — top-level orchestrators (`execute-phase`, `plan-phase`, `new-project`) |\n| `LARGE` | 1500 — multi-step planners and large feature workflows |\n| `DEFAULT` | 1000 — focused single-purpose workflows (the target tier) |\n\n`workflows/discuss-phase.md` is held to a stricter <500-line ceiling per\nissue #2551. When a workflow grows beyond its tier, extract per-mode bodies\ninto `workflows//modes/.md`, templates into\n`workflows//templates/`, and shared knowledge into\n`get-shit-done/references/`. The parent file becomes a thin dispatcher that\nReads only the mode and template files needed for the current invocation.\n\n`workflows/discuss-phase/` is the canonical example of this pattern —\nparent dispatches, modes/ holds per-flag behavior (`power.md`, `all.md`,\n`auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`,\n`advisor.md`), and templates/ holds CONTEXT.md, DISCUSSION-LOG.md, and\ncheckpoint.json schemas that are read only when the corresponding output\nfile is being written.\n\n### Agents (`agents/*.md`)\n\nSpecialized agent definitions with frontmatter specifying:\n\n- `name` — Agent identifier\n- `description` — Role and purpose\n- `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)\n- `color` — Terminal output color for visual distinction\n\n**Total agents:** 33\n\n### References (`get-shit-done/references/*.md`)\n\nShared knowledge documents that workflows and agents `@-reference` (see [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) for the authoritative count and full roster):\n\n**Core references:**\n\n- `checkpoints.md` — Checkpoint type definitions and interaction patterns\n- `gates.md` — 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier\n- `model-profiles.md` — Per-agent model tier assignments\n- `model-profile-resolution.md` — Model resolution algorithm documentation\n- `verification-patterns.md` — How to verify different artifact types\n- `verification-overrides.md` — Per-artifact verification override rules\n- `planning-config.md` — Full config schema and behavior\n- `git-integration.md` — Git commit, branching, and history patterns\n- `git-planning-commit.md` — Planning directory commit conventions\n- `questioning.md` — Dream extraction philosophy for project initialization\n- `tdd.md` — Test-driven development integration patterns\n- `ui-brand.md` — Visual output formatting patterns\n- `common-bug-patterns.md` — Common bug patterns for code review and verification\n\n**Workflow references:**\n\n- `agent-contracts.md` — Formal interface between orchestrators and agents\n- `context-budget.md` — Context window budget allocation rules\n- `continuation-format.md` — Session continuation/resume format\n- `domain-probes.md` — Domain-specific probing questions for discuss-phase\n- `gate-prompts.md` — Gate/checkpoint prompt templates\n- `revision-loop.md` — Plan revision iteration patterns\n- `universal-anti-patterns.md` — Common anti-patterns to detect and avoid\n- `artifact-types.md` — Planning artifact type definitions\n- `phase-argument-parsing.md` — Phase argument parsing conventions\n- `decimal-phase-calculation.md` — Decimal sub-phase numbering rules\n- `workstream-flag.md` — Workstream active pointer conventions\n- `user-profiling.md` — User behavioral profiling methodology\n- `thinking-partner.md` — Conditional thinking partner activation at decision points\n\n**Thinking model references:**\n\nReferences for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows:\n\n- `thinking-models-debug.md` — Thinking model patterns for debugging workflows\n- `thinking-models-execution.md` — Thinking model patterns for execution agents\n- `thinking-models-planning.md` — Thinking model patterns for planning agents\n- `thinking-models-research.md` — Thinking model patterns for research agents\n- `thinking-models-verification.md` — Thinking model patterns for verification agents\n\n**Modular planner decomposition:**\n\nThe planner agent (`agents/gsd-planner.md`) was decomposed from a single monolithic file into a core agent plus reference modules to stay under the 50K character limit imposed by some runtimes:\n\n- `planner-gap-closure.md` — Gap closure mode behavior (reads VERIFICATION.md, targeted replanning)\n- `planner-reviews.md` — Cross-AI review integration (reads REVIEWS.md from `/gsd-review`)\n- `planner-revision.md` — Plan revision patterns for iterative refinement\n\n### Templates (`get-shit-done/templates/`)\n\nMarkdown templates for all planning artifacts. Used by `gsd-sdk query template.fill` / `phase.scaffold` (and legacy `gsd-tools.cjs template fill` / top-level `scaffold`) to create pre-structured files:\n- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files\n- `phase-prompt.md` — Phase execution prompt template\n- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates\n- `DEBUG.md` — Debug session tracking template\n- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Specialized verification templates\n- `discussion-log.md` — Discussion audit trail template\n- `codebase/` — Brownfield mapping templates (stack, architecture, conventions, concerns, structure, testing, integrations)\n- `research-project/` — Research output templates (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)\n\n### Hooks (`hooks/`)\n\nRuntime hooks that integrate with the host AI agent:\n\n| Hook | Event | Purpose |\n|------|-------|---------|\n| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar |\n| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining |\n| `gsd-check-update.js` | `SessionStart` | Foreground trigger for the background update check |\n| `gsd-check-update-worker.js` | (helper) | Background worker spawned by `gsd-check-update.js`; no direct event registration |\n| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) |\n| `gsd-read-injection-scanner.js` | `PostToolUse` | Scans Read tool output for injected instructions in untrusted content |\n| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |\n| `gsd-read-guard.js` | `PreToolUse` | Advisory guard preventing Edit/Write on files not yet read in the session |\n| `gsd-session-state.sh` | `PostToolUse` | Session state tracking for shell-based runtimes |\n| `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional commit enforcement |\n| `gsd-phase-boundary.sh` | `PostToolUse` | Phase boundary detection for workflow transitions |\n\nSee [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 11-hook roster.\n\n### SDK Runtime Bridge Module (`sdk/src/query-runtime-bridge.ts`)\n\nProgrammatic SDK callers (`GSDTools`) route through one seam that owns query dispatch policy:\n\n- Native registry dispatch preference\n- Explicit subprocess fallback policy (`allowFallbackToSubprocess`)\n- Strict SDK mode (`strictSdk`) for fail-fast native-only enforcement\n- Structured dispatch observability (`onDispatchEvent`) with mode, reason, duration, and outcome\n\nThis keeps callers thin adapters and centralizes transport decisions for SDK publishability.\n\n### Command Routing Hub (`get-shit-done/bin/lib/command-routing-hub.cjs`)\n\nCJS command family routers migrate to dispatch through `CommandRoutingHub` incrementally. `phase-command-router.cjs` is the first migration (issue #3788); remaining routers (`phases-command-router.cjs`, `roadmap-command-router.cjs`, etc.) continue using `routeCjsCommandFamily` until migrated in follow-up issues. The hub owns three cross-cutting concerns that each router previously duplicated: (1) mode selection (`sdk` when `tryLoadSdk()` succeeds and no `GSD_WORKSTREAM` is active, `cjs` otherwise), set once at construction; (2) a no-throw pure-result contract (`hub.dispatch()` catches all exceptions and returns `{ ok: false, errorKind, message, details }` instead of propagating); and (3) a closed six-value `errorKind` enum exported as the frozen `ERROR_KINDS` object. Router adapters remain thin CLI translators — they build the hub, call `dispatch`, then map the Result to `output()`/`error()` calls. No transparent SDK→CJS fallback: an SDK-mode hub that encounters a load or dispatch failure returns `SdkLoadFailed` or `SdkDispatchFailed` without retrying via CJS. See `docs/adr/0012-command-routing-hub.md`.\n\n### CLI Tools (`get-shit-done/bin/`)\n\nNode.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) for the authoritative roster):\n\n\n| Module | Responsibility |\n| ---------------------- | --------------------------------------------------------------------------------------------------- |\n| `core.cjs` | Error handling, output formatting, shared utilities; compatibility re-exports for planning helpers |\n| `planning-workspace.cjs` | Planning seam (`planningDir`, `planningPaths`, active workstream routing, `.planning/.lock`) |\n| `state.cjs` | STATE.md parsing, updating, progression, metrics |\n| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |\n| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |\n| `config.cjs` | config.json read/write, section initialization |\n| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |\n| `template.cjs` | Template selection and filling with variable substitution |\n| `frontmatter.cjs` | YAML frontmatter CRUD operations |\n| `init.cjs` | Compound context loading for each workflow type |\n| `milestone.cjs` | Milestone archival, requirements marking |\n| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |\n| `model-profiles.cjs` | Model profile resolution table |\n| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |\n| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |\n| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |\n| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |\n| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |\n| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |\n| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |\n\n\n---\n\n## Agent Model\n\n### Orchestrator → Agent Pattern\n\n```\nOrchestrator (workflow .md)\n │\n ├── Load context: gsd-sdk query init. (or legacy gsd-tools.cjs init)\n │ Returns JSON with: project info, config, state, phase details\n │\n ├── Resolve model: gsd-sdk query resolve-model \n │ Returns: opus | sonnet | haiku | inherit\n │\n ├── Spawn Agent (Task/SubAgent call)\n │ ├── Agent prompt (agents/*.md)\n │ ├── Context payload (init JSON)\n │ ├── Model assignment\n │ └── Tool permissions\n │\n ├── Collect result\n │\n └── Update state: gsd-sdk query state.update / state.patch / state.advance-plan (or legacy gsd-tools.cjs)\n```\n\n### Primary Agent Spawn Categories\n\nConceptual spawn-pattern taxonomy for the 21 primary agents. For the authoritative 31-agent roster (including the 10 advanced/specialized agents such as `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), see [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped).\n\n\n| Category | Agents | Parallelism |\n| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |\n| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |\n| **Planners** | gsd-planner, gsd-roadmapper | Sequential |\n| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |\n| **Executors** | gsd-executor | Parallel within waves, sequential across waves |\n| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |\n| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |\n| **Debuggers** | gsd-debugger | Sequential (interactive) |\n| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |\n| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |\n| **Profilers** | gsd-user-profiler | Sequential |\n| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |\n\n\n### Wave Execution Model\n\nDuring `execute-phase`, plans are grouped into dependency waves:\n\n```\nWave Analysis:\n Plan 01 (no deps) ─┐\n Plan 02 (no deps) ─┤── Wave 1 (parallel)\n Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1)\n Plan 04 (depends: 02) ─┘\n Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)\n```\n\nEach executor gets:\n\n- Fresh 200K context window (or up to 1M for models that support it)\n- The specific PLAN.md to execute\n- Project context (PROJECT.md, STATE.md)\n- Phase context (CONTEXT.md, RESEARCH.md if available)\n\n### Adaptive Context Enrichment (1M Models)\n\nWhen the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4.6), subagent prompts are automatically enriched with additional context that would not fit in standard 200K windows:\n\n- **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase\n- **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification\n\nThe orchestrator reads `context_window` from config (`gsd-sdk query config-get context_window`, or legacy `gsd-tools.cjs config-get`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.\n\n#### Parallel Commit Safety\n\nWhen multiple executors run within the same wave, two mechanisms prevent conflicts:\n\n1. `--no-verify` commits — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.\n2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter.\n\n---\n\n## Data Flow\n\n### New Project Flow\n\n```\nUser input (idea description)\n │\n ▼\nQuestions (questioning.md philosophy)\n │\n ▼\n4x Project Researchers (parallel)\n ├── Stack → STACK.md\n ├── Features → FEATURES.md\n ├── Architecture → ARCHITECTURE.md\n └── Pitfalls → PITFALLS.md\n │\n ▼\nResearch Synthesizer → SUMMARY.md\n │\n ▼\nRequirements extraction → REQUIREMENTS.md\n │\n ▼\nRoadmapper → ROADMAP.md\n │\n ▼\nUser approval → STATE.md initialized\n```\n\n### Phase Execution Flow\n\n```\ndiscuss-phase → CONTEXT.md (user preferences)\n │\n ▼\nui-phase → UI-SPEC.md (design contract, optional)\n │\n ▼\nplan-phase\n ├── Research gate (blocks if RESEARCH.md has unresolved open questions)\n ├── Phase Researcher → RESEARCH.md\n │ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,\n │ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md\n ├── Planner (with reachability check) → PLAN.md files\n │ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;\n │ T-{phase}-SC STRIDE row added for install-bearing plans\n ├── Plan Checker → Verify loop (max 3x)\n ├── Requirements coverage gate (REQ-IDs → plans)\n └── Decision coverage gate (CONTEXT.md `` → plans, BLOCKING — #2492)\n │\n ▼\nstate planned-phase → STATE.md (Planned/Ready to execute)\n │\n ▼\nexecute-phase (context reduction: truncated prompts, cache-friendly ordering)\n ├── Wave analysis (dependency grouping)\n ├── Executor per plan → code + atomic commits\n ├── SUMMARY.md per plan\n └── Verifier → VERIFICATION.md\n └── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)\n │\n ▼\nverify-work → UAT.md (user acceptance testing)\n │\n ▼\nui-review → UI-REVIEW.md (visual audit, optional)\n```\n\n### Context Propagation\n\nEach workflow stage produces artifacts that feed into subsequent stages:\n\n```\nPROJECT.md ────────────────────────────────────────────► All agents\nREQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor\nROADMAP.md ────────────────────────────────────────────► Orchestrators\nSTATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)\nCONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor\nRESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker\nPLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker\nSUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking\nUI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor\n```\n\n---\n\n## File System Layout\n\n### Installation Files\n\n```\n~/.claude/ # Claude Code (global install)\n├── skills/gsd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)\n├── commands/gsd/*.md # Local Claude installs use slash commands instead of global skills\n├── get-shit-done/\n│ ├── bin/gsd-tools.cjs # CLI utility\n│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)\n│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)\n│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)\n│ └── templates/ # Planning artifact templates\n├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)\n├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)\n├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)\n├── settings.json # Hook registrations\n└── VERSION # Installed version number\n```\n\nEquivalent paths for other runtimes:\n\n- **OpenCode:** `~/.config/opencode/` global or `./.opencode/` local\n- **Kilo:** `~/.config/kilo/` global or `./.kilo/` local\n- **Gemini CLI:** `~/.gemini/` global or `./.gemini/` local\n- **Codex:** `~/.codex/` global or `./.codex/` local\n- **Copilot:** `~/.copilot/` global or `./.github/` local\n- **Antigravity:** `~/.gemini/antigravity/` global or `./.agent/` local\n- **Cursor:** `~/.cursor/` global or `./.cursor/` local\n- **Windsurf:** `~/.codeium/windsurf/` global or `./.windsurf/` local\n- **Augment Code:** `~/.augment/` global or `./.augment/` local\n- **Trae:** `~/.trae/` global or `./.trae/` local\n- **Qwen Code:** `~/.qwen/` global or `./.qwen/` local\n- **Hermes Agent:** `~/.hermes/` global or `./.hermes/` local\n- **CodeBuddy:** `~/.codebuddy/` global or `./.codebuddy/` local\n- **Cline:** `~/.cline/` global or project-root `.clinerules` local\n\n### Project Files (`.planning/`)\n\n```\n.planning/\n├── PROJECT.md # Project vision, constraints, decisions, evolution rules\n├── REQUIREMENTS.md # Scoped requirements (v1/v2/out-of-scope)\n├── ROADMAP.md # Phase breakdown with status tracking\n├── STATE.md # Living memory: position, decisions, blockers, metrics\n├── config.json # Workflow configuration\n├── MILESTONES.md # Completed milestone archive\n├── research/ # Domain research from /gsd-new-project\n│ ├── SUMMARY.md\n│ ├── STACK.md\n│ ├── FEATURES.md\n│ ├── ARCHITECTURE.md\n│ └── PITFALLS.md\n├── codebase/ # Brownfield mapping (from /gsd-map-codebase)\n│ ├── STACK.md # YAML frontmatter carries `last_mapped_commit`\n│ ├── ARCHITECTURE.md # for the post-execute drift gate (#2003)\n│ ├── CONVENTIONS.md\n│ ├── CONCERNS.md\n│ ├── STRUCTURE.md\n│ ├── TESTING.md\n│ └── INTEGRATIONS.md\n├── phases/\n│ └── XX-phase-name/\n│ ├── XX-CONTEXT.md # User preferences (from discuss-phase)\n│ ├── XX-RESEARCH.md # Ecosystem research (from plan-phase)\n│ ├── XX-YY-PLAN.md # Execution plans\n│ ├── XX-YY-SUMMARY.md # Execution outcomes\n│ ├── XX-VERIFICATION.md # Post-execution verification\n│ ├── XX-VALIDATION.md # Nyquist test coverage mapping\n│ ├── XX-UI-SPEC.md # UI design contract (from ui-phase)\n│ ├── XX-UI-REVIEW.md # Visual audit scores (from ui-review)\n│ └── XX-UAT.md # User acceptance test results\n├── quick/ # Quick task tracking\n│ └── YYMMDD-xxx-slug/\n│ ├── PLAN.md\n│ └── SUMMARY.md\n├── todos/\n│ ├── pending/ # Captured ideas\n│ └── done/ # Completed todos\n├── threads/ # Persistent context threads (from /gsd-thread)\n├── seeds/ # Forward-looking ideas (from /gsd-capture --seed)\n├── debug/ # Active debug sessions\n│ ├── *.md # Active sessions\n│ ├── resolved/ # Archived sessions\n│ └── knowledge-base.md # Persistent debug learnings\n├── ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)\n└── continue-here.md # Context handoff (from pause-work)\n```\n\n### Post-Execute Codebase Drift Gate (#2003)\n\nAfter the last wave of `/gsd-execute-phase` commits, the workflow runs a\nnon-blocking `codebase_drift_gate` step (between `schema_drift_gate` and\n`verify_phase_goal`). It compares the diff `last_mapped_commit..HEAD`\nagainst `.planning/codebase/STRUCTURE.md` and counts four kinds of\nstructural elements:\n\n1. New directories outside mapped paths\n2. New barrel exports at `(packages|apps)//src/index.*`\n3. New migration files\n4. New route modules under `routes/` or `api/`\n\nIf the count meets `workflow.drift_threshold` (default 3), the gate either\n**warns** (default) with the suggested `/gsd-map-codebase --paths …` command,\nor **auto-remaps** (`workflow.drift_action = auto-remap`) by spawning\n`gsd-codebase-mapper` scoped to the affected paths. Any error in detection\nor remap is logged and the phase continues — drift detection cannot fail\nverification.\n\n`last_mapped_commit` lives in YAML frontmatter at the top of each\n`.planning/codebase/*.md` file; `bin/lib/drift.cjs` provides\n`readMappedCommit` and `writeMappedCommit` round-trip helpers.\n\n---\n\n## Installer Architecture\n\nThe installer (`bin/install.js`, ~10,700 lines) handles:\n\n1. **Runtime detection** — Interactive prompt or CLI flags (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--augment`, `--trae`, `--qwen`, `--hermes`, `--codebuddy`, `--cline`, `--all`)\n2. **Location selection** — Global (`--global`) or local (`--local`)\n3. **File deployment** — Copies commands, skills, workflows, references, templates, agents, and hooks\n4. **Runtime adaptation** — Transforms file content per runtime:\n - Claude Code: Uses as-is\n - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format\n - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths\n - Codex: Generates TOML config + skills from commands\n - Copilot: Maps tool names (Read→read, Bash→execute, etc.)\n - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)\n - Antigravity: Skills-first with Google model equivalents\n - Cursor: Skills-first with Cursor rule references\n - Windsurf: Skills-first with Windsurf rule references\n - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration\n - Qwen Code: Skills-first with Qwen-branded path and prompt rewrites\n - Hermes Agent: Category-based skills under `skills/gsd/`\n - CodeBuddy: Skills-first with CodeBuddy path and prompt rewrites\n - Cline: Writes `.clinerules` for rule-based integration\n - Augment Code: Skills-first with full skill conversion and config management\n5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths\n6. **Settings integration** — Registers hooks in runtime's `settings.json`\n7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-update --reapply`\n8. **Manifest tracking** — Writes `gsd-file-manifest.json` for clean uninstall\n9. **Uninstall mode** — `--uninstall` removes all GSD files, hooks, and settings\n\nInstall-time file moves, stale-artifact cleanup, config rewrites, and user-data\npreservation are governed by the Installer Migration Module. See\n[Installer Migrations](installer-migrations.md) and\n[ADR 0008](adr/0008-installer-migration-module.md).\nThe migration module also owns the gated first-time baseline scan for legacy\ninstalls, classifying known runtime install surfaces before later migrations\nremove or rewrite anything.\n\n### Platform Handling\n\n- **Windows:** `windowsHide` on child processes, EPERM/EACCES protection on protected directories, path separator normalization\n- **WSL:** Detects Windows Node.js running on WSL and warns about path mismatches\n- **Docker/CI:** Supports `CLAUDE_CONFIG_DIR` env var for custom config directory locations\n\n---\n\n## Hook System\n\n### Architecture\n\n```\nRuntime Engine (Claude Code / Gemini CLI)\n │\n ├── statusLine event ──► gsd-statusline.js\n │ Reads: stdin (session JSON)\n │ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)\n │\n ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js\n │ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)\n │ Writes: stdout (hookSpecificOutput with additionalContext warning)\n │\n └── SessionStart event ──► gsd-check-update.js\n Reads: VERSION file\n Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)\n```\n\n### Context Monitor Thresholds\n\n\n| Remaining Context | Level | Agent Behavior |\n| ----------------- | -------- | --------------------------------------- |\n| > 35% | Normal | No warning injected |\n| ≤ 35% | WARNING | \"Avoid starting new complex work\" |\n| ≤ 25% | CRITICAL | \"Context nearly exhausted, inform user\" |\n\n\nDebounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce.\n\n### Safety Properties\n\n- All hooks wrap in try/catch, exit silently on error\n- stdin timeout guard (3s) prevents hanging on pipe issues\n- Stale metrics (>60s old) are ignored\n- Missing bridge files handled gracefully (subagents, fresh sessions)\n- Context monitor is advisory — never issues imperative commands that override user preferences\n\n### Package Legitimacy Gate (v1.42.1)\n\nThe researcher → planner → executor pipeline includes a supply-chain gate against slopsquatting (AI-hallucinated package names pre-registered with malicious post-install scripts).\n\n**Threat model:** GSD automates the full path from \"researcher names a package\" to \"executor runs `npm install`\". A hallucinated name that passes `npm view` (proving only registration, not legitimacy) would previously flow through undetected. ~20% of AI-generated package references are hallucinated; ~43% of those names recur consistently across prompts, making pre-registration economically viable for attackers.\n\n**Gate layers:**\n\n| Layer | Component | Action |\n|-------|-----------|--------|\n| Research | `gsd-phase-researcher` | Runs `slopcheck install --json`; writes `## Package Legitimacy Audit` table to RESEARCH.md; strips `[SLOP]` packages before RESEARCH.md is written |\n| Planning | `gsd-planner` | Reads Audit table; inserts `checkpoint:human-verify` before any `[ASSUMED]` or `[SUS]` install task; adds `T-{phase}-SC` STRIDE supply-chain row to `` |\n| Execution | `gsd-executor` | RULE 3 excludes package installation from auto-fix scope; failed installs surface as checkpoints, never silent substitutions |\n\n**Claim provenance integration:** Package names discovered via WebSearch are tagged `[ASSUMED]` (not `[VERIFIED]`) regardless of `npm view` result. This extends the existing `[ASSUMED]` / `[VERIFIED]` / `[CITED]` provenance system by enforcing the provenance tag as a hard gate at the install boundary — `[ASSUMED]` always generates a `checkpoint:human-verify` in PLAN.md.\n\n**Ecosystem coverage:** The researcher uses registry-specific verification commands — `npm view` (Node), `pip index versions` (Python), `cargo search` (Rust) — rather than a single generic check. This catches cross-ecosystem hallucination (~9% rate documented in 2025 USENIX research).\n\n**Graceful degradation:** If `slopcheck` is unavailable, every recommended package is tagged `[ASSUMED]` and gated with a checkpoint. Research and planning proceed; the system never hard-fails on a missing tool dependency.\n\n**External dependency:** `slopcheck` (MIT, pip-installable). If abandoned, the `[ASSUMED]`-gate fallback maintains human-checkpoint coverage.\n\n---\n\n### Security Hooks (v1.27)\n\n**Prompt Guard** (`gsd-prompt-guard.js`):\n\n- Triggers on Write/Edit to `.planning/` files\n- Scans content for prompt injection patterns (role override, instruction bypass, system tag injection)\n- Advisory-only — logs detection, does not block\n- Patterns are inlined (subset of `security.cjs`) for hook independence\n\n**Workflow Guard** (`gsd-workflow-guard.js`):\n\n- Triggers on Write/Edit to non-`.planning/` files\n- Detects edits outside GSD workflow context (no active `/gsd-` command or Task subagent)\n- Advises using `/gsd-quick` or `/gsd-fast` for state-tracked changes\n- Opt-in via `hooks.workflow_guard: true` (default: false)\n\n---\n\n## Runtime Abstraction\n\nGSD supports multiple AI coding runtimes through a unified command/workflow architecture:\n\n### Runtime Install Contract Matrix\n\nThis matrix describes the runtime surfaces the installer materializes today.\nThe migration-specific ownership and source snapshots live in\n[Installer Migrations](installer-migrations.md#runtime-configuration-contract-registry).\n\n| Runtime | Global root | Local root | Invocation surface | Agent surface | Config and hooks |\n| --- | --- | --- | --- | --- | --- |\n| Claude Code | `~/.claude` | `./.claude` | Global `skills/gsd-*/SKILL.md`; local `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` hook and statusLine entries |\n| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` or `opencode.jsonc`; no GSD hooks |\n| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` or `kilo.jsonc`; no GSD hooks |\n| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` feature flag, hooks, and statusline |\n| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | `agents/` source markdown plus per-agent TOML | `config.toml` `[agents.gsd-*]`, `[features].hooks` (canonical; legacy alias `codex_hooks` is recognized and migrated forward on reinstall, #3566), and hook tables |\n| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` and `copilot-instructions.md` | `.agent.md` files | No GSD hooks or statusline |\n| Antigravity | `~/.gemini/antigravity` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Gemini-style `settings.json` hook entries when installed by GSD |\n| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | No GSD hooks or statusline |\n| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Rule references under `rules/`; no GSD hooks |\n| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` plus `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Common GSD settings and hook entries where supported |\n| Cline | `~/.cline` | project root | `.clinerules` | Rules only | No GSD hooks or statusline |\n\n### Upstream Contract Sources\n\nRuntime install expectations are checked against primary documentation where\navailable. The current source snapshot is 2026-05-11:\n\n- Claude Code: Anthropic slash commands, settings, hooks, and subagents docs.\n- OpenCode and Kilo: OpenCode config docs and Kilo custom subagent docs.\n- Gemini CLI and Qwen Code: command/config docs; Qwen command docs were last\n updated 2026-05-06.\n- Codex: OpenAI Codex docs and `config-schema.json`; the installer also carries\n Codex 0.124.0 compatibility for agent table shape.\n- Copilot, Cursor, Cline, Augment, Hermes, and CodeBuddy: vendor docs for\n custom instructions, rules, skills, or config.\n- Antigravity, Windsurf, and Trae: source-limited rows. The installer documents\n current compatibility shims, and migrations must refresh those sources before\n rewriting their config.\n\n### Abstraction Points\n\n1. **Tool name mapping** — Each runtime has its own tool names (e.g., Claude's `Bash` → Copilot's `execute`)\n2. **Hook event names** — Claude uses `PostToolUse`, Gemini uses `AfterTool`\n3. **Agent frontmatter** — Each runtime has its own agent definition format\n4. **Path conventions** — Each runtime stores config in different directories\n5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection\n\nThe installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.\n"}