From d20fa8a9f61c13fdce042e324f5464c3dd725489 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 16 Mar 2026 10:55:08 -0400 Subject: [PATCH] docs: add comprehensive feature, architecture, and requirements documentation (#1089) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New documentation suite in docs/: - README.md — Documentation index with audience-targeted links - ARCHITECTURE.md — System architecture: component model, agent patterns, data flow, file system layout, installer architecture, hook system, runtime abstraction, and design principles - FEATURES.md — Complete feature reference with 32 features documented, each with formal requirements (REQ-*), produced artifacts, process descriptions, and functional specifications - COMMANDS.md — Full command reference: all 37 commands with syntax, flags, arguments, prerequisites, produced artifacts, and examples - CONFIGURATION.md — Complete config schema: 40+ settings across core, workflow, planning, parallelization, git branching, gates, safety, model profiles, and environment variables - CLI-TOOLS.md — gsd-tools.cjs programmatic API: all commands across state, phase, roadmap, config, verify, template, frontmatter, scaffold, init, milestone, and utility categories - AGENTS.md — All 15 specialized agents: roles, tool permissions, spawn patterns, model assignments, produced artifacts, key behaviors, and a complete tool permission matrix Coverage derived from: - All 37 command files (commands/gsd/*.md) - All 41 workflow files (get-shit-done/workflows/*.md) - All 15 agent definitions (agents/*.md) - All 13 reference documents (get-shit-done/references/*.md) - Full CLI source (gsd-tools.cjs + 11 lib modules, ~10K lines) - All 3 hooks (statusline, context-monitor, check-update) - Installer (bin/install.js, ~3K lines) - Full CHANGELOG.md (1.0.0 through 1.24.0, ~170 releases) --- docs/AGENTS.md | 356 ++++++++++++++++++++ docs/ARCHITECTURE.md | 498 ++++++++++++++++++++++++++++ docs/CLI-TOOLS.md | 357 ++++++++++++++++++++ docs/COMMANDS.md | 500 ++++++++++++++++++++++++++++ docs/CONFIGURATION.md | 261 +++++++++++++++ docs/FEATURES.md | 756 ++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 25 ++ 7 files changed, 2753 insertions(+) create mode 100644 docs/AGENTS.md create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CLI-TOOLS.md create mode 100644 docs/COMMANDS.md create mode 100644 docs/CONFIGURATION.md create mode 100644 docs/FEATURES.md create mode 100644 docs/README.md diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 000000000..950e7af36 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,356 @@ +# GSD Agent Reference + +> All 15 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md). + +--- + +## Overview + +GSD 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. + +### Agent Categories + +| Category | Count | Agents | +|----------|-------|--------| +| Researchers | 3 | project-researcher, phase-researcher, ui-researcher | +| Synthesizers | 1 | research-synthesizer | +| Planners | 1 | planner | +| Roadmappers | 1 | roadmapper | +| Executors | 1 | executor | +| Checkers | 3 | plan-checker, integration-checker, ui-checker | +| Verifiers | 1 | verifier | +| Auditors | 2 | nyquist-auditor, ui-auditor | +| Mappers | 1 | codebase-mapper | +| Debuggers | 1 | debugger | + +--- + +## Agent Details + +### gsd-project-researcher + +**Role:** Researches domain ecosystem before roadmap creation. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:new-project`, `/gsd:new-milestone` | +| **Parallelism** | 4 instances (stack, features, architecture, pitfalls) | +| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` | + +**Capabilities:** +- Web search for current ecosystem information +- Context7 MCP integration for library documentation +- Writes research documents directly to disk (reduces orchestrator context load) + +--- + +### gsd-phase-researcher + +**Role:** Researches how to implement a specific phase before planning. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:plan-phase` | +| **Parallelism** | 4 instances (same focus areas as project researcher) | +| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Produces** | `{phase}-RESEARCH.md` | + +**Capabilities:** +- Reads CONTEXT.md to focus research on user's decisions +- Investigates implementation patterns for the specific phase domain +- Detects test infrastructure for Nyquist validation mapping + +--- + +### gsd-ui-researcher + +**Role:** Produces UI design contracts for frontend phases. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:ui-phase` | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Color** | `#E879F9` (fuchsia) | +| **Produces** | `{phase}-UI-SPEC.md` | + +**Capabilities:** +- Detects design system state (shadcn components.json, Tailwind config, existing tokens) +- Offers shadcn initialization for React/Next.js/Vite projects +- Asks only unanswered design contract questions +- Enforces registry safety gate for third-party components + +--- + +### gsd-research-synthesizer + +**Role:** Combines outputs from parallel researchers into a unified summary. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:new-project` (after 4 researchers complete) | +| **Parallelism** | Single instance (sequential after researchers) | +| **Tools** | Read, Write, Bash | +| **Model (balanced)** | Sonnet | +| **Color** | Purple | +| **Produces** | `.planning/research/SUMMARY.md` | + +--- + +### gsd-planner + +**Role:** Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:plan-phase`, `/gsd:quick` | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Glob, Grep, WebFetch, mcp (context7) | +| **Model (balanced)** | Opus | +| **Color** | Green | +| **Produces** | `{phase}-{N}-PLAN.md` files | + +**Key behaviors:** +- Reads PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md +- Creates 2-3 atomic task plans sized for single context windows +- Uses XML structure with `` elements +- Includes `read_first` and `acceptance_criteria` sections +- Groups plans into dependency waves + +--- + +### gsd-roadmapper + +**Role:** Creates project roadmaps with phase breakdown and requirement mapping. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:new-project` | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Glob, Grep | +| **Model (balanced)** | Sonnet | +| **Color** | Purple | +| **Produces** | `ROADMAP.md` | + +**Key behaviors:** +- Maps requirements to phases (traceability) +- Derives success criteria from requirements +- Respects granularity setting for phase count +- Validates coverage (every v1 requirement mapped to a phase) + +--- + +### gsd-executor + +**Role:** Executes GSD plans with atomic commits, deviation handling, and checkpoint protocols. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:execute-phase`, `/gsd:quick` | +| **Parallelism** | Multiple (parallel within waves, sequential across waves) | +| **Tools** | Read, Write, Edit, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | Yellow | +| **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` | + +**Key behaviors:** +- Fresh 200K context window per plan +- Follows XML task instructions precisely +- Atomic git commit per completed task +- Handles checkpoint types: auto, human-verify, decision, human-action +- Reports deviations from plan in SUMMARY.md +- Invokes node repair on verification failure + +--- + +### gsd-plan-checker + +**Role:** Verifies plans will achieve phase goals before execution. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:plan-phase` (verification loop, max 3 iterations) | +| **Parallelism** | Single instance (iterative) | +| **Tools** | Read, Bash, Glob, Grep | +| **Model (balanced)** | Sonnet | +| **Color** | Green | +| **Produces** | PASS/FAIL verdict with specific feedback | + +**8 Verification Dimensions:** +1. Requirement coverage +2. Task atomicity +3. Dependency ordering +4. File scope +5. Verification commands +6. Context fit +7. Gap detection +8. Nyquist compliance (when enabled) + +--- + +### gsd-integration-checker + +**Role:** Verifies cross-phase integration and end-to-end flows. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:audit-milestone` | +| **Parallelism** | Single instance | +| **Tools** | Read, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | Blue | +| **Produces** | Integration verification report | + +--- + +### gsd-ui-checker + +**Role:** Validates UI-SPEC.md design contracts against quality dimensions. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:ui-phase` (validation loop, max 2 iterations) | +| **Parallelism** | Single instance | +| **Tools** | Read, Bash, Glob, Grep | +| **Model (balanced)** | Sonnet | +| **Color** | `#22D3EE` (cyan) | +| **Produces** | BLOCK/FLAG/PASS verdict | + +--- + +### gsd-verifier + +**Role:** Verifies phase goal achievement through goal-backward analysis. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:execute-phase` (after all executors complete) | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | Green | +| **Produces** | `{phase}-VERIFICATION.md` | + +**Key behaviors:** +- Checks codebase against phase goals, not just task completion +- PASS/FAIL with specific evidence +- Logs issues for `/gsd:verify-work` to address + +--- + +### gsd-nyquist-auditor + +**Role:** Fills Nyquist validation gaps by generating tests. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:validate-phase` | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Edit, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Produces** | Test files, updated `VALIDATION.md` | + +**Key behaviors:** +- Never modifies implementation code — only test files +- Max 3 attempts per gap +- Flags implementation bugs as escalations for user + +--- + +### gsd-ui-auditor + +**Role:** Retroactive 6-pillar visual audit of implemented frontend code. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:ui-review` | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | `#F472B6` (pink) | +| **Produces** | `{phase}-UI-REVIEW.md` with scores | + +**6 Audit Pillars (scored 1-4):** +1. Copywriting +2. Visuals +3. Color +4. Typography +5. Spacing +6. Experience Design + +--- + +### gsd-codebase-mapper + +**Role:** Explores codebase and writes structured analysis documents. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:map-codebase` | +| **Parallelism** | 4 instances (tech, architecture, quality, concerns) | +| **Tools** | Read, Bash, Grep, Glob, Write | +| **Model (balanced)** | Haiku | +| **Color** | Cyan | +| **Produces** | `.planning/codebase/*.md` (7 documents) | + +**Key behaviors:** +- Read-only exploration + structured output +- Writes documents directly to disk +- No reasoning required — pattern extraction from file contents + +--- + +### gsd-debugger + +**Role:** Investigates bugs using scientific method with persistent state. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd:debug`, `/gsd:verify-work` (for failures) | +| **Parallelism** | Single instance (interactive) | +| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch | +| **Model (balanced)** | Sonnet | +| **Color** | Orange | +| **Produces** | `.planning/debug/*.md`, knowledge-base updates | + +**Debug Session Lifecycle:** +`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +**Key behaviors:** +- Tracks hypotheses, evidence, and eliminated theories +- State persists across context resets +- Requires human verification before marking resolved +- Appends to persistent knowledge base on resolution +- Consults knowledge base on new sessions + +--- + +## Agent Tool Permissions Summary + +| Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP | +|-------|------|-------|------|------|------|------|-----------|----------|-----| +| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| research-synthesizer | ✓ | ✓ | | ✓ | | | | | | +| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ | +| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | + +**Principle of Least Privilege:** +- Checkers are read-only (no Write/Edit) — they evaluate, never modify +- Researchers have web access — they need current ecosystem information +- Executors have Edit — they modify code but not web access +- Mappers have Write — they write analysis documents but not Edit (no code changes) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 000000000..0163b0cc0 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,498 @@ +# GSD Architecture + +> System architecture for contributors and advanced users. For user-facing documentation, see [Feature Reference](FEATURES.md) or [User Guide](USER-GUIDE.md). + +--- + +## Table of Contents + +- [System Overview](#system-overview) +- [Design Principles](#design-principles) +- [Component Architecture](#component-architecture) +- [Agent Model](#agent-model) +- [Data Flow](#data-flow) +- [File System Layout](#file-system-layout) +- [Installer Architecture](#installer-architecture) +- [Hook System](#hook-system) +- [CLI Tools Layer](#cli-tools-layer) +- [Runtime Abstraction](#runtime-abstraction) + +--- + +## System Overview + +GSD is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Codex, Copilot, Antigravity). It provides: + +1. **Context engineering** — Structured artifacts that give the AI everything it needs per task +2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows +3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline +4. **State management** — Persistent project memory across sessions and context resets + +``` +┌──────────────────────────────────────────────────────┐ +│ USER │ +│ /gsd:command [args] │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ COMMAND LAYER │ +│ commands/gsd/*.md — Prompt-based command files │ +│ (Claude Code custom commands / Codex skills) │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ WORKFLOW LAYER │ +│ get-shit-done/workflows/*.md — Orchestration logic │ +│ (Reads references, spawns agents, manages state) │ +└──────┬──────────────┬─────────────────┬──────────────┘ + │ │ │ +┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐ +│ AGENT │ │ AGENT │ │ AGENT │ +│ (fresh │ │ (fresh │ │ (fresh │ +│ context) │ │ context)│ │ context) │ +└──────┬──────┘ └─────┬─────┘ └────────┬───────┘ + │ │ │ +┌──────▼──────────────▼─────────────────▼──────────────┐ +│ CLI TOOLS LAYER │ +│ get-shit-done/bin/gsd-tools.cjs │ +│ (State, config, phase, roadmap, verify, templates) │ +└──────────────────────┬───────────────────────────────┘ + │ +┌──────────────────────▼───────────────────────────────┐ +│ FILE SYSTEM (.planning/) │ +│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │ +│ STATE.md | config.json | phases/ | research/ │ +└──────────────────────────────────────────────────────┘ +``` + +--- + +## Design Principles + +### 1. Fresh Context Per Agent + +Every 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. + +### 2. Thin Orchestrators + +Workflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They: +- Load context via `gsd-tools.cjs init ` +- Spawn specialized agents with focused prompts +- Collect results and route to the next step +- Update state between steps + +### 3. File-Based State + +All state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means: +- State survives context resets (`/clear`) +- State is inspectable by both humans and agents +- State can be committed to git for team visibility + +### 4. Absent = Enabled + +Workflow 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. + +### 5. Defense in Depth + +Multiple layers prevent common failure modes: +- Plans are verified before execution (plan-checker agent) +- Execution produces atomic commits per task +- Post-execution verification checks against phase goals +- UAT provides human verification as final gate + +--- + +## Component Architecture + +### Commands (`commands/gsd/*.md`) + +User-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as: +- **Claude Code:** Custom slash commands (`/gsd:command-name`) +- **OpenCode:** Slash commands (`/gsd-command-name`) +- **Codex:** Skills (`$gsd-command-name`) +- **Copilot:** Slash commands (`/gsd:command-name`) +- **Antigravity:** Skills + +**Total commands:** 37 + +### Workflows (`get-shit-done/workflows/*.md`) + +Orchestration logic that commands reference. Contains the step-by-step process including: +- Context loading via `gsd-tools.cjs init` +- Agent spawn instructions with model resolution +- Gate/checkpoint definitions +- State update patterns +- Error handling and recovery + +**Total workflows:** 41 + +### Agents (`agents/*.md`) + +Specialized agent definitions with frontmatter specifying: +- `name` — Agent identifier +- `description` — Role and purpose +- `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.) +- `color` — Terminal output color for visual distinction + +**Total agents:** 15 + +### References (`get-shit-done/references/*.md`) + +Shared knowledge documents that workflows and agents `@-reference`: +- `checkpoints.md` — Checkpoint type definitions and interaction patterns +- `model-profiles.md` — Per-agent model tier assignments +- `verification-patterns.md` — How to verify different artifact types +- `planning-config.md` — Full config schema and behavior +- `git-integration.md` — Git commit, branching, and history patterns +- `questioning.md` — Dream extraction philosophy for project initialization +- `tdd.md` — Test-driven development integration patterns +- `ui-brand.md` — Visual output formatting patterns + +### Templates (`get-shit-done/templates/`) + +Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template fill` and `scaffold` commands to create pre-structured files: +- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files +- `phase-prompt.md` — Phase execution prompt template +- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates +- `DEBUG.md` — Debug session tracking template +- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Specialized verification templates +- `codebase/` — Brownfield mapping templates (stack, architecture, conventions, concerns, structure, testing, integrations) +- `research-project/` — Research output templates (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS) + +### Hooks (`hooks/`) + +Runtime hooks that integrate with the host AI agent: + +| Hook | Event | Purpose | +|------|-------|---------| +| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar | +| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining | +| `gsd-check-update.js` | `SessionStart` | Background check for new GSD versions | + +### CLI Tools (`get-shit-done/bin/`) + +Node.js CLI utility (`gsd-tools.cjs`) with 11 domain modules: + +| Module | Responsibility | +|--------|---------------| +| `core.cjs` | Error handling, output formatting, shared utilities | +| `state.cjs` | STATE.md parsing, updating, progression, metrics | +| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing | +| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress | +| `config.cjs` | config.json read/write, section initialization | +| `verify.cjs` | Plan structure, phase completeness, reference, commit validation | +| `template.cjs` | Template selection and filling with variable substitution | +| `frontmatter.cjs` | YAML frontmatter CRUD operations | +| `init.cjs` | Compound context loading for each workflow type | +| `milestone.cjs` | Milestone archival, requirements marking | +| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) | +| `model-profiles.cjs` | Model profile resolution table | + +--- + +## Agent Model + +### Orchestrator → Agent Pattern + +``` +Orchestrator (workflow .md) + │ + ├── Load context: gsd-tools.cjs init + │ Returns JSON with: project info, config, state, phase details + │ + ├── Resolve model: gsd-tools.cjs resolve-model + │ Returns: opus | sonnet | haiku | inherit + │ + ├── Spawn Agent (Task/SubAgent call) + │ ├── Agent prompt (agents/*.md) + │ ├── Context payload (init JSON) + │ ├── Model assignment + │ └── Tool permissions + │ + ├── Collect result + │ + └── Update state: gsd-tools.cjs state update/patch/advance-plan +``` + +### Agent Spawn Categories + +| Category | Agents | Parallelism | +|----------|--------|-------------| +| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher | 4 parallel (stack, features, architecture, pitfalls) | +| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) | +| **Planners** | gsd-planner, gsd-roadmapper | Sequential | +| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) | +| **Executors** | gsd-executor | Parallel within waves, sequential across waves | +| **Verifiers** | gsd-verifier | Sequential (after all executors complete) | +| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) | +| **Debuggers** | gsd-debugger | Sequential (interactive) | +| **Auditors** | gsd-ui-auditor | Sequential | + +### Wave Execution Model + +During `execute-phase`, plans are grouped into dependency waves: + +``` +Wave Analysis: + Plan 01 (no deps) ─┐ + Plan 02 (no deps) ─┤── Wave 1 (parallel) + Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1) + Plan 04 (depends: 02) ─┘ + Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2) +``` + +Each executor gets: +- Fresh 200K context window +- The specific PLAN.md to execute +- Project context (PROJECT.md, STATE.md) +- Phase context (CONTEXT.md, RESEARCH.md if available) + +--- + +## Data Flow + +### New Project Flow + +``` +User input (idea description) + │ + ▼ +Questions (questioning.md philosophy) + │ + ▼ +4x Project Researchers (parallel) + ├── Stack → STACK.md + ├── Features → FEATURES.md + ├── Architecture → ARCHITECTURE.md + └── Pitfalls → PITFALLS.md + │ + ▼ +Research Synthesizer → SUMMARY.md + │ + ▼ +Requirements extraction → REQUIREMENTS.md + │ + ▼ +Roadmapper → ROADMAP.md + │ + ▼ +User approval → STATE.md initialized +``` + +### Phase Execution Flow + +``` +discuss-phase → CONTEXT.md (user preferences) + │ + ▼ +ui-phase → UI-SPEC.md (design contract, optional) + │ + ▼ +plan-phase + ├── Phase Researcher → RESEARCH.md + ├── Planner → PLAN.md files + └── Plan Checker → Verify loop (max 3x) + │ + ▼ +execute-phase + ├── Wave analysis (dependency grouping) + ├── Executor per plan → code + atomic commits + ├── SUMMARY.md per plan + └── Verifier → VERIFICATION.md + │ + ▼ +verify-work → UAT.md (user acceptance testing) + │ + ▼ +ui-review → UI-REVIEW.md (visual audit, optional) +``` + +### Context Propagation + +Each workflow stage produces artifacts that feed into subsequent stages: + +``` +PROJECT.md ────────────────────────────────────────────► All agents +REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor +ROADMAP.md ────────────────────────────────────────────► Orchestrators +STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers) +CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor +RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker +PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker +SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking +UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor +``` + +--- + +## File System Layout + +### Installation Files + +``` +~/.claude/ # Claude Code (global install) +├── commands/gsd/*.md # 37 slash commands +├── get-shit-done/ +│ ├── bin/gsd-tools.cjs # CLI utility +│ ├── bin/lib/*.cjs # 11 domain modules +│ ├── workflows/*.md # 41 workflow definitions +│ ├── references/*.md # 13 shared reference docs +│ └── templates/ # Planning artifact templates +├── agents/*.md # 15 agent definitions +├── hooks/ +│ ├── gsd-statusline.js # Statusline hook +│ ├── gsd-context-monitor.js # Context warning hook +│ └── gsd-check-update.js # Update check hook +├── settings.json # Hook registrations +└── VERSION # Installed version number +``` + +Equivalent paths for other runtimes: +- **OpenCode:** `~/.config/opencode/` or `~/.opencode/` +- **Gemini CLI:** `~/.gemini/` +- **Codex:** `~/.codex/` (uses skills instead of commands) +- **Copilot:** `~/.github/` +- **Antigravity:** `~/.gemini/antigravity/` (global) or `./.agent/` (local) + +### Project Files (`.planning/`) + +``` +.planning/ +├── PROJECT.md # Project vision, constraints, decisions +├── REQUIREMENTS.md # Scoped requirements (v1/v2/out-of-scope) +├── ROADMAP.md # Phase breakdown with status tracking +├── STATE.md # Living memory: position, decisions, blockers, metrics +├── config.json # Workflow configuration +├── MILESTONES.md # Completed milestone archive +├── research/ # Domain research from /gsd:new-project +│ ├── SUMMARY.md +│ ├── STACK.md +│ ├── FEATURES.md +│ ├── ARCHITECTURE.md +│ └── PITFALLS.md +├── codebase/ # Brownfield mapping (from /gsd:map-codebase) +│ ├── STACK.md +│ ├── ARCHITECTURE.md +│ ├── CONVENTIONS.md +│ ├── CONCERNS.md +│ ├── STRUCTURE.md +│ ├── TESTING.md +│ └── INTEGRATIONS.md +├── phases/ +│ └── XX-phase-name/ +│ ├── XX-CONTEXT.md # User preferences (from discuss-phase) +│ ├── XX-RESEARCH.md # Ecosystem research (from plan-phase) +│ ├── XX-YY-PLAN.md # Execution plans +│ ├── XX-YY-SUMMARY.md # Execution outcomes +│ ├── XX-VERIFICATION.md # Post-execution verification +│ ├── XX-VALIDATION.md # Nyquist test coverage mapping +│ ├── XX-UI-SPEC.md # UI design contract (from ui-phase) +│ ├── XX-UI-REVIEW.md # Visual audit scores (from ui-review) +│ └── XX-UAT.md # User acceptance test results +├── quick/ # Quick task tracking +│ └── YYMMDD-xxx-slug/ +│ ├── PLAN.md +│ └── SUMMARY.md +├── todos/ +│ ├── pending/ # Captured ideas +│ └── done/ # Completed todos +├── debug/ # Active debug sessions +│ ├── *.md # Active sessions +│ ├── resolved/ # Archived sessions +│ └── knowledge-base.md # Persistent debug learnings +├── ui-reviews/ # Screenshots from /gsd:ui-review (gitignored) +└── continue-here.md # Context handoff (from pause-work) +``` + +--- + +## Installer Architecture + +The installer (`bin/install.js`, ~3,000 lines) handles: + +1. **Runtime detection** — Interactive prompt or CLI flags (`--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, `--antigravity`, `--all`) +2. **Location selection** — Global (`--global`) or local (`--local`) +3. **File deployment** — Copies commands, workflows, references, templates, agents, hooks +4. **Runtime adaptation** — Transforms file content per runtime: + - Claude Code: Uses as-is + - OpenCode: Converts agent frontmatter to `name:`, `model: inherit`, `mode: subagent` + - Codex: Generates TOML config + skills from commands + - Copilot: Maps tool names (Read→read, Bash→execute, etc.) + - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`) + - Antigravity: Skills-first with Google model equivalents +5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths +6. **Settings integration** — Registers hooks in runtime's `settings.json` +7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd:reapply-patches` +8. **Manifest tracking** — Writes `gsd-file-manifest.json` for clean uninstall +9. **Uninstall mode** — `--uninstall` removes all GSD files, hooks, and settings + +### Platform Handling + +- **Windows:** `windowsHide` on child processes, EPERM/EACCES protection on protected directories, path separator normalization +- **WSL:** Detects Windows Node.js running on WSL and warns about path mismatches +- **Docker/CI:** Supports `CLAUDE_CONFIG_DIR` env var for custom config directory locations + +--- + +## Hook System + +### Architecture + +``` +Runtime Engine (Claude Code / Gemini CLI) + │ + ├── statusLine event ──► gsd-statusline.js + │ Reads: stdin (session JSON) + │ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge) + │ + ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js + │ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge) + │ Writes: stdout (hookSpecificOutput with additionalContext warning) + │ + └── SessionStart event ──► gsd-check-update.js + Reads: VERSION file + Writes: ~/.claude/cache/gsd-update-check.json (spawns background process) +``` + +### Context Monitor Thresholds + +| Remaining Context | Level | Agent Behavior | +|-------------------|-------|----------------| +| > 35% | Normal | No warning injected | +| ≤ 35% | WARNING | "Avoid starting new complex work" | +| ≤ 25% | CRITICAL | "Context nearly exhausted, inform user" | + +Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce. + +### Safety Properties + +- All hooks wrap in try/catch, exit silently on error +- stdin timeout guard (3s) prevents hanging on pipe issues +- Stale metrics (>60s old) are ignored +- Missing bridge files handled gracefully (subagents, fresh sessions) +- Context monitor is advisory — never issues imperative commands that override user preferences + +--- + +## Runtime Abstraction + +GSD supports 6 AI coding runtimes through a unified command/workflow architecture: + +| Runtime | Command Format | Agent System | Config Location | +|---------|---------------|--------------|-----------------| +| Claude Code | `/gsd:command` | Task spawning | `~/.claude/` | +| OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` | +| Gemini CLI | `/gsd:command` | Task spawning | `~/.gemini/` | +| Codex | `$gsd-command` | Skills | `~/.codex/` | +| Copilot | `/gsd:command` | Agent delegation | `~/.github/` | +| Antigravity | Skills | Skills | `~/.gemini/antigravity/` | + +### Abstraction Points + +1. **Tool name mapping** — Each runtime has its own tool names (e.g., Claude's `Bash` → Copilot's `execute`) +2. **Hook event names** — Claude uses `PostToolUse`, Gemini uses `AfterTool` +3. **Agent frontmatter** — Each runtime has its own agent definition format +4. **Path conventions** — Each runtime stores config in different directories +5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection + +The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment. diff --git a/docs/CLI-TOOLS.md b/docs/CLI-TOOLS.md new file mode 100644 index 000000000..f0228496b --- /dev/null +++ b/docs/CLI-TOOLS.md @@ -0,0 +1,357 @@ +# GSD CLI Tools Reference + +> Programmatic API reference for `gsd-tools.cjs`. Used by workflows and agents internally. For user-facing commands, see [Command Reference](COMMANDS.md). + +--- + +## Overview + +`gsd-tools.cjs` is a Node.js CLI utility that replaces repetitive inline bash patterns across GSD's ~50 command, workflow, and agent files. It centralizes: config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations. + +**Location:** `get-shit-done/bin/gsd-tools.cjs` +**Modules:** 11 domain modules in `get-shit-done/bin/lib/` + +**Usage:** +```bash +node gsd-tools.cjs [args] [--raw] [--cwd ] +``` + +**Global Flags:** +| Flag | Description | +|------|-------------| +| `--raw` | Machine-readable output (JSON or plain text, no formatting) | +| `--cwd ` | Override working directory (for sandboxed subagents) | + +--- + +## State Commands + +Manage `.planning/STATE.md` — the project's living memory. + +```bash +# Load full project config + state as JSON +node gsd-tools.cjs state load + +# Output STATE.md frontmatter as JSON +node gsd-tools.cjs state json + +# Update a single field +node gsd-tools.cjs state update + +# Get STATE.md content or a specific section +node gsd-tools.cjs state get [section] + +# Batch update multiple fields +node gsd-tools.cjs state patch --field1 val1 --field2 val2 + +# Increment plan counter +node gsd-tools.cjs state advance-plan + +# Record execution metrics +node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N] + +# Recalculate progress bar +node gsd-tools.cjs state update-progress + +# Add a decision +node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."] +# Or from files: +node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path] + +# Add/resolve blockers +node gsd-tools.cjs state add-blocker --text "..." +node gsd-tools.cjs state resolve-blocker --text "..." + +# Record session continuity +node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path] +``` + +### State Snapshot + +Structured parse of the full STATE.md: + +```bash +node gsd-tools.cjs state-snapshot +``` + +Returns JSON with: current position, phase, plan, status, decisions, blockers, metrics, last activity. + +--- + +## Phase Commands + +Manage phases — directories, numbering, and roadmap sync. + +```bash +# Find phase directory by number +node gsd-tools.cjs find-phase + +# Calculate next decimal phase number for insertions +node gsd-tools.cjs phase next-decimal + +# Append new phase to roadmap + create directory +node gsd-tools.cjs phase add + +# Insert decimal phase after existing +node gsd-tools.cjs phase insert + +# Remove phase, renumber subsequent +node gsd-tools.cjs phase remove [--force] + +# Mark phase complete, update state + roadmap +node gsd-tools.cjs phase complete + +# Index plans with waves and status +node gsd-tools.cjs phase-plan-index + +# List phases with filtering +node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived] +``` + +--- + +## Roadmap Commands + +Parse and update `ROADMAP.md`. + +```bash +# Extract phase section from ROADMAP.md +node gsd-tools.cjs roadmap get-phase + +# Full roadmap parse with disk status +node gsd-tools.cjs roadmap analyze + +# Update progress table row from disk +node gsd-tools.cjs roadmap update-plan-progress +``` + +--- + +## Config Commands + +Read and write `.planning/config.json`. + +```bash +# Initialize config.json with defaults +node gsd-tools.cjs config-ensure-section + +# Set a config value (dot notation) +node gsd-tools.cjs config-set + +# Get a config value +node gsd-tools.cjs config-get + +# Set model profile +node gsd-tools.cjs config-set-model-profile +``` + +--- + +## Model Resolution + +```bash +# Get model for agent based on current profile +node gsd-tools.cjs resolve-model +# Returns: opus | sonnet | haiku | inherit +``` + +Agent names: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor` + +--- + +## Verification Commands + +Validate plans, phases, references, and commits. + +```bash +# Verify SUMMARY.md file +node gsd-tools.cjs verify-summary [--check-count N] + +# Check PLAN.md structure + tasks +node gsd-tools.cjs verify plan-structure + +# Check all plans have summaries +node gsd-tools.cjs verify phase-completeness + +# Check @-refs + paths resolve +node gsd-tools.cjs verify references + +# Batch verify commit hashes +node gsd-tools.cjs verify commits [hash2] ... + +# Check must_haves.artifacts +node gsd-tools.cjs verify artifacts + +# Check must_haves.key_links +node gsd-tools.cjs verify key-links +``` + +--- + +## Validation Commands + +Check project integrity. + +```bash +# Check phase numbering, disk/roadmap sync +node gsd-tools.cjs validate consistency + +# Check .planning/ integrity, optionally repair +node gsd-tools.cjs validate health [--repair] +``` + +--- + +## Template Commands + +Template selection and filling. + +```bash +# Select summary template based on granularity +node gsd-tools.cjs template select + +# Fill template with variables +node gsd-tools.cjs template fill --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}'] +``` + +Template types for `fill`: `summary`, `plan`, `verification` + +--- + +## Frontmatter Commands + +YAML frontmatter CRUD operations on any Markdown file. + +```bash +# Extract frontmatter as JSON +node gsd-tools.cjs frontmatter get [--field key] + +# Update single field +node gsd-tools.cjs frontmatter set --field key --value jsonVal + +# Merge JSON into frontmatter +node gsd-tools.cjs frontmatter merge --data '{json}' + +# Validate required fields +node gsd-tools.cjs frontmatter validate --schema plan|summary|verification +``` + +--- + +## Scaffold Commands + +Create pre-structured files and directories. + +```bash +# Create CONTEXT.md template +node gsd-tools.cjs scaffold context --phase N + +# Create UAT.md template +node gsd-tools.cjs scaffold uat --phase N + +# Create VERIFICATION.md template +node gsd-tools.cjs scaffold verification --phase N + +# Create phase directory +node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name" +``` + +--- + +## Init Commands (Compound Context Loading) + +Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data. + +```bash +node gsd-tools.cjs init execute-phase +node gsd-tools.cjs init plan-phase +node gsd-tools.cjs init new-project +node gsd-tools.cjs init new-milestone +node gsd-tools.cjs init quick +node gsd-tools.cjs init resume +node gsd-tools.cjs init verify-work +node gsd-tools.cjs init phase-op +node gsd-tools.cjs init todos [area] +node gsd-tools.cjs init milestone-op +node gsd-tools.cjs init map-codebase +node gsd-tools.cjs init progress +``` + +**Large payload handling:** When output exceeds ~50KB, the CLI writes to a temp file and returns `@file:/tmp/gsd-init-XXXXX.json`. Workflows check for the `@file:` prefix and read from disk: + +```bash +INIT=$(node gsd-tools.cjs init execute-phase "1") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +--- + +## Milestone Commands + +```bash +# Archive milestone +node gsd-tools.cjs milestone complete [--name ] [--archive-phases] + +# Mark requirements as complete +node gsd-tools.cjs requirements mark-complete +# Accepts: REQ-01,REQ-02 or REQ-01 REQ-02 or [REQ-01, REQ-02] +``` + +--- + +## Utility Commands + +```bash +# Convert text to URL-safe slug +node gsd-tools.cjs generate-slug "Some Text Here" +# → some-text-here + +# Get timestamp +node gsd-tools.cjs current-timestamp [full|date|filename] + +# Count and list pending todos +node gsd-tools.cjs list-todos [area] + +# Check file/directory existence +node gsd-tools.cjs verify-path-exists + +# Aggregate all SUMMARY.md data +node gsd-tools.cjs history-digest + +# Extract structured data from SUMMARY.md +node gsd-tools.cjs summary-extract [--fields field1,field2] + +# Project statistics +node gsd-tools.cjs stats [json|table] + +# Progress rendering +node gsd-tools.cjs progress [json|table|bar] + +# Complete a todo +node gsd-tools.cjs todo complete + +# Git commit with config checks +node gsd-tools.cjs commit [--files f1 f2] [--amend] + +# Web search (requires Brave API key) +node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] +``` + +--- + +## Module Architecture + +| Module | File | Exports | +|--------|------|---------| +| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities | +| State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` | +| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` | +| Roadmap | `lib/roadmap.cjs` | Roadmap parsing, phase extraction, progress updates | +| Config | `lib/config.cjs` | Config read/write, section initialization | +| Verify | `lib/verify.cjs` | All verification and validation commands | +| Template | `lib/template.cjs` | Template selection and variable filling | +| Frontmatter | `lib/frontmatter.cjs` | YAML frontmatter CRUD | +| Init | `lib/init.cjs` | Compound context loading for all workflows | +| Milestone | `lib/milestone.cjs` | Milestone archival, requirements marking | +| Commands | `lib/commands.cjs` | Misc: slug, timestamp, todos, scaffold, stats, websearch | +| Model Profiles | `lib/model-profiles.cjs` | Profile resolution table | diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md new file mode 100644 index 000000000..60b30507d --- /dev/null +++ b/docs/COMMANDS.md @@ -0,0 +1,500 @@ +# GSD Command Reference + +> Complete command syntax, flags, options, and examples. For feature details, see [Feature Reference](FEATURES.md). For workflow walkthroughs, see [User Guide](USER-GUIDE.md). + +--- + +## Command Syntax + +- **Claude Code / Gemini / Copilot:** `/gsd:command-name [args]` +- **OpenCode:** `/gsd-command-name [args]` +- **Codex:** `$gsd-command-name [args]` + +--- + +## Core Workflow Commands + +### `/gsd:new-project` + +Initialize a new project with deep context gathering. + +| Flag | Description | +|------|-------------| +| `--auto @file.md` | Auto-extract from document, skip interactive questions | + +**Prerequisites:** No existing `.planning/PROJECT.md` +**Produces:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json`, `research/` + +```bash +/gsd:new-project # Interactive mode +/gsd:new-project --auto @prd.md # Auto-extract from PRD +``` + +--- + +### `/gsd:discuss-phase` + +Capture implementation decisions before planning. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to current phase) | + +| Flag | Description | +|------|-------------| +| `--auto` | Auto-select recommended defaults for all questions | +| `--batch` | Group questions for batch intake instead of one-by-one | + +**Prerequisites:** `.planning/ROADMAP.md` exists +**Produces:** `{phase}-CONTEXT.md` + +```bash +/gsd:discuss-phase 1 # Interactive discussion for phase 1 +/gsd:discuss-phase 3 --auto # Auto-select defaults for phase 3 +/gsd:discuss-phase --batch # Batch mode for current phase +``` + +--- + +### `/gsd:ui-phase` + +Generate UI design contract for frontend phases. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to current phase) | + +**Prerequisites:** `.planning/ROADMAP.md` exists, phase has frontend/UI work +**Produces:** `{phase}-UI-SPEC.md` + +```bash +/gsd:ui-phase 2 # Design contract for phase 2 +``` + +--- + +### `/gsd:plan-phase` + +Research, plan, and verify a phase. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to next unplanned phase) | + +| Flag | Description | +|------|-------------| +| `--auto` | Skip interactive confirmations | +| `--skip-research` | Skip domain research step | +| `--skip-verify` | Skip plan checker verification loop | + +**Prerequisites:** `.planning/ROADMAP.md` exists +**Produces:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md` + +```bash +/gsd:plan-phase 1 # Research + plan + verify phase 1 +/gsd:plan-phase 3 --skip-research # Plan without research (familiar domain) +/gsd:plan-phase --auto # Non-interactive planning +``` + +--- + +### `/gsd:execute-phase` + +Execute all plans in a phase with wave-based parallelization. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | **Yes** | Phase number to execute | + +**Prerequisites:** Phase has PLAN.md files +**Produces:** `{phase}-{N}-SUMMARY.md`, `{phase}-VERIFICATION.md`, git commits + +```bash +/gsd:execute-phase 1 # Execute phase 1 +``` + +--- + +### `/gsd:verify-work` + +User acceptance testing with auto-diagnosis. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to last executed phase) | + +**Prerequisites:** Phase has been executed +**Produces:** `{phase}-UAT.md`, fix plans if issues found + +```bash +/gsd:verify-work 1 # UAT for phase 1 +``` + +--- + +### `/gsd:ui-review` + +Retroactive 6-pillar visual audit of implemented frontend. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to last executed phase) | + +**Prerequisites:** Project has frontend code (works standalone, no GSD project needed) +**Produces:** `{phase}-UI-REVIEW.md`, screenshots in `.planning/ui-reviews/` + +```bash +/gsd:ui-review # Audit current phase +/gsd:ui-review 3 # Audit phase 3 +``` + +--- + +### `/gsd:audit-milestone` + +Verify milestone met its definition of done. + +**Prerequisites:** All phases executed +**Produces:** Audit report with gap analysis + +```bash +/gsd:audit-milestone +``` + +--- + +### `/gsd:complete-milestone` + +Archive milestone, tag release. + +**Prerequisites:** Milestone audit complete (recommended) +**Produces:** `MILESTONES.md` entry, git tag + +```bash +/gsd:complete-milestone +``` + +--- + +### `/gsd:new-milestone` + +Start next version cycle. + +| Argument | Required | Description | +|----------|----------|-------------| +| `name` | No | Milestone name | + +**Prerequisites:** Previous milestone completed +**Produces:** Updated `PROJECT.md`, new `REQUIREMENTS.md`, new `ROADMAP.md` + +```bash +/gsd:new-milestone # Interactive +/gsd:new-milestone "v2.0 Mobile" # Named milestone +``` + +--- + +## Phase Management Commands + +### `/gsd:add-phase` + +Append new phase to roadmap. + +```bash +/gsd:add-phase # Interactive — describe the phase +``` + +### `/gsd:insert-phase` + +Insert urgent work between phases using decimal numbering. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Insert after this phase number | + +```bash +/gsd:insert-phase 3 # Insert between phase 3 and 4 → creates 3.1 +``` + +### `/gsd:remove-phase` + +Remove future phase and renumber subsequent phases. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number to remove | + +```bash +/gsd:remove-phase 7 # Remove phase 7, renumber 8→7, 9→8, etc. +``` + +### `/gsd:list-phase-assumptions` + +Preview Claude's intended approach before planning. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd:list-phase-assumptions 2 # See assumptions for phase 2 +``` + +### `/gsd:plan-milestone-gaps` + +Create phases to close gaps from milestone audit. + +```bash +/gsd:plan-milestone-gaps # Creates phases for each audit gap +``` + +### `/gsd:research-phase` + +Deep ecosystem research only (standalone — usually use `/gsd:plan-phase` instead). + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd:research-phase 4 # Research phase 4 domain +``` + +### `/gsd:validate-phase` + +Retroactively audit and fill Nyquist validation gaps. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd:validate-phase 2 # Audit test coverage for phase 2 +``` + +--- + +## Navigation Commands + +### `/gsd:progress` + +Show status and next steps. + +```bash +/gsd:progress # "Where am I? What's next?" +``` + +### `/gsd:resume-work` + +Restore full context from last session. + +```bash +/gsd:resume-work # After context reset or new session +``` + +### `/gsd:pause-work` + +Save context handoff when stopping mid-phase. + +```bash +/gsd:pause-work # Creates continue-here.md +``` + +### `/gsd:help` + +Show all commands and usage guide. + +```bash +/gsd:help # Quick reference +``` + +--- + +## Utility Commands + +### `/gsd:quick` + +Execute ad-hoc task with GSD guarantees. + +| Flag | Description | +|------|-------------| +| `--full` | Enable plan checking (2 iterations) + post-execution verification | +| `--discuss` | Lightweight pre-planning discussion | +| `--research` | Spawn focused researcher before planning | + +Flags are composable. + +```bash +/gsd:quick # Basic quick task +/gsd:quick --discuss --research # Discussion + research + planning +/gsd:quick --full # With plan checking and verification +/gsd:quick --discuss --research --full # All optional stages +``` + +### `/gsd:autonomous` + +Run all remaining phases autonomously. + +| Flag | Description | +|------|-------------| +| `--from N` | Start from a specific phase number | + +```bash +/gsd:autonomous # Run all remaining phases +/gsd:autonomous --from 3 # Start from phase 3 +``` + +### `/gsd:do` + +Route freeform text to the right GSD command. + +```bash +/gsd:do # Then describe what you want +``` + +### `/gsd:debug` + +Systematic debugging with persistent state. + +| Argument | Required | Description | +|----------|----------|-------------| +| `description` | No | Description of the bug | + +```bash +/gsd:debug "Login button not responding on mobile Safari" +``` + +### `/gsd:add-todo` + +Capture idea or task for later. + +| Argument | Required | Description | +|----------|----------|-------------| +| `description` | No | Todo description | + +```bash +/gsd:add-todo "Consider adding dark mode support" +``` + +### `/gsd:check-todos` + +List pending todos and select one to work on. + +```bash +/gsd:check-todos +``` + +### `/gsd:add-tests` + +Generate tests for a completed phase. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd:add-tests 2 # Generate tests for phase 2 +``` + +### `/gsd:stats` + +Display project statistics. + +```bash +/gsd:stats # Project metrics dashboard +``` + +### `/gsd:health` + +Validate `.planning/` directory integrity. + +| Flag | Description | +|------|-------------| +| `--repair` | Auto-fix recoverable issues | + +```bash +/gsd:health # Check integrity +/gsd:health --repair # Check and fix +``` + +### `/gsd:cleanup` + +Archive accumulated phase directories from completed milestones. + +```bash +/gsd:cleanup +``` + +--- + +## Configuration Commands + +### `/gsd:settings` + +Interactive configuration of workflow toggles and model profile. + +```bash +/gsd:settings # Interactive config +``` + +### `/gsd:set-profile` + +Quick profile switch. + +| Argument | Required | Description | +|----------|----------|-------------| +| `profile` | **Yes** | `quality`, `balanced`, `budget`, or `inherit` | + +```bash +/gsd:set-profile budget # Switch to budget profile +/gsd:set-profile quality # Switch to quality profile +``` + +--- + +## Brownfield Commands + +### `/gsd:map-codebase` + +Analyze existing codebase with parallel mapper agents. + +| Argument | Required | Description | +|----------|----------|-------------| +| `area` | No | Scope mapping to a specific area | + +```bash +/gsd:map-codebase # Full codebase analysis +/gsd:map-codebase auth # Focus on auth area +``` + +--- + +## Update Commands + +### `/gsd:update` + +Update GSD with changelog preview. + +```bash +/gsd:update # Check for updates and install +``` + +### `/gsd:reapply-patches` + +Restore local modifications after a GSD update. + +```bash +/gsd:reapply-patches # Merge back local changes +``` + +--- + +## Community Commands + +### `/gsd:join-discord` + +Open Discord community invite. + +```bash +/gsd:join-discord +``` diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 000000000..b1299242e --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,261 @@ +# GSD Configuration Reference + +> Full configuration schema, workflow toggles, model profiles, and git branching options. For feature context, see [Feature Reference](FEATURES.md). + +--- + +## Configuration File + +GSD stores project settings in `.planning/config.json`. Created during `/gsd:new-project`, updated via `/gsd:settings`. + +### Full Schema + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "model_overrides": {}, + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "auto_advance": false, + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "node_repair": true, + "node_repair_budget": 2 + }, + "parallelization": { + "enabled": true, + "plan_level": true, + "task_level": false, + "skip_checkpoints": true, + "max_concurrent_agents": 3, + "min_plans_for_parallel": 2 + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}" + }, + "gates": { + "confirm_project": true, + "confirm_phases": true, + "confirm_roadmap": true, + "confirm_breakdown": true, + "confirm_plan": true, + "execute_next_plan": true, + "issues_review": true, + "confirm_transition": true + }, + "safety": { + "always_confirm_destructive": true, + "always_confirm_external_services": true + } +} +``` + +--- + +## Core Settings + +| Setting | Type | Options | Default | Description | +|---------|------|---------|---------|-------------| +| `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step | +| `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | Controls phase count: `coarse` (3-5), `standard` (5-8), `fine` (8-12) | +| `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see [Model Profiles](#model-profiles)) | + +> **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated. + +--- + +## Workflow Toggles + +All workflow toggles follow the **absent = enabled** pattern. If a key is missing from config, it defaults to `true`. + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `workflow.research` | boolean | `true` | Domain investigation before planning each phase | +| `workflow.plan_check` | boolean | `true` | Plan verification loop (up to 3 iterations) | +| `workflow.verifier` | boolean | `true` | Post-execution verification against phase goals | +| `workflow.auto_advance` | boolean | `false` | Auto-chain discuss → plan → execute without stopping | +| `workflow.nyquist_validation` | boolean | `true` | Test coverage mapping during plan-phase research | +| `workflow.ui_phase` | boolean | `true` | Generate UI design contracts for frontend phases | +| `workflow.ui_safety_gate` | boolean | `true` | Prompt to run /gsd:ui-phase for frontend phases during plan-phase | +| `workflow.node_repair` | boolean | `true` | Autonomous task repair on verification failure | +| `workflow.node_repair_budget` | number | `2` | Max repair attempts per failed task | + +### Recommended Presets + +| Scenario | mode | granularity | profile | research | plan_check | verifier | +|----------|------|-------------|---------|----------|------------|----------| +| Prototyping | `yolo` | `coarse` | `budget` | `false` | `false` | `false` | +| Normal development | `interactive` | `standard` | `balanced` | `true` | `true` | `true` | +| Production release | `interactive` | `fine` | `quality` | `true` | `true` | `true` | + +--- + +## Planning Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `planning.commit_docs` | boolean | `true` | Whether `.planning/` files are committed to git | +| `planning.search_gitignored` | boolean | `false` | Add `--no-ignore` to broad searches to include `.planning/` | + +### Auto-Detection + +If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors. + +### Private Planning Setup + +To keep planning artifacts out of git: + +1. Set `planning.commit_docs: false` and `planning.search_gitignored: true` +2. Add `.planning/` to `.gitignore` +3. If previously tracked: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"` + +--- + +## Parallelization Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `parallelization.enabled` | boolean | `true` | Run independent plans simultaneously | +| `parallelization.plan_level` | boolean | `true` | Parallelize at plan level | +| `parallelization.task_level` | boolean | `false` | Parallelize tasks within a plan | +| `parallelization.skip_checkpoints` | boolean | `true` | Skip checkpoints during parallel execution | +| `parallelization.max_concurrent_agents` | number | `3` | Maximum simultaneous agents | +| `parallelization.min_plans_for_parallel` | number | `2` | Minimum plans to trigger parallel execution | + +--- + +## Git Branching + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `git.branching_strategy` | enum | `none` | `none`, `phase`, or `milestone` | +| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | Branch name template for phase strategy | +| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | Branch name template for milestone strategy | + +### Strategy Comparison + +| Strategy | Creates Branch | Scope | Merge Point | Best For | +|----------|---------------|-------|-------------|----------| +| `none` | Never | N/A | N/A | Solo development, simple projects | +| `phase` | At `execute-phase` start | One phase | User merges after phase | Code review per phase, granular rollback | +| `milestone` | At first `execute-phase` | All phases in milestone | At `complete-milestone` | Release branches, PR per version | + +### Template Variables + +| Variable | Available In | Example | +|----------|-------------|---------| +| `{phase}` | `phase_branch_template` | `03` (zero-padded) | +| `{slug}` | Both templates | `user-authentication` (lowercase, hyphenated) | +| `{milestone}` | `milestone_branch_template` | `v1.0` | + +### Merge Options at Milestone Completion + +| Option | Git Command | Result | +|--------|-------------|--------| +| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch | +| Merge with history | `git merge --no-ff` | Preserves all individual commits | +| Delete without merging | `git branch -D` | Discard branch work | +| Keep branches | (none) | Manual handling later | + +--- + +## Gate Settings + +Control confirmation prompts during workflows. + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `gates.confirm_project` | boolean | `true` | Confirm project details before finalizing | +| `gates.confirm_phases` | boolean | `true` | Confirm phase breakdown | +| `gates.confirm_roadmap` | boolean | `true` | Confirm roadmap before proceeding | +| `gates.confirm_breakdown` | boolean | `true` | Confirm task breakdown | +| `gates.confirm_plan` | boolean | `true` | Confirm each plan before execution | +| `gates.execute_next_plan` | boolean | `true` | Confirm before executing next plan | +| `gates.issues_review` | boolean | `true` | Review issues before creating fix plans | +| `gates.confirm_transition` | boolean | `true` | Confirm phase transition | + +--- + +## Safety Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `safety.always_confirm_destructive` | boolean | `true` | Confirm destructive operations (deletes, overwrites) | +| `safety.always_confirm_external_services` | boolean | `true` | Confirm external service interactions | + +--- + +## Model Profiles + +### Profile Definitions + +| Agent | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +### Per-Agent Overrides + +Override specific agents without changing the entire profile: + +```json +{ + "model_profile": "balanced", + "model_overrides": { + "gsd-executor": "opus", + "gsd-planner": "haiku" + } +} +``` + +Valid override values: `opus`, `sonnet`, `haiku`, `inherit` + +### Profile Philosophy + +| Profile | Philosophy | When to Use | +|---------|-----------|-------------| +| `quality` | Opus for all decision-making, Sonnet for verification | Quota available, critical architecture work | +| `balanced` | Opus for planning only, Sonnet for everything else | Normal development (default) | +| `budget` | Sonnet for code-writing, Haiku for research/verification | High-volume work, less critical phases | +| `inherit` | All agents use current session model | Dynamic model switching (OpenCode `/model`) | + +--- + +## Environment Variables + +| Variable | Purpose | +|----------|---------| +| `CLAUDE_CONFIG_DIR` | Override default config directory (`~/.claude/`) | +| `GEMINI_API_KEY` | Detected by context monitor to switch hook event name | +| `WSL_DISTRO_NAME` | Detected by installer for WSL path handling | + +--- + +## Global Defaults + +Save settings as global defaults for future projects: + +**Location:** `~/.gsd/defaults.json` + +When `/gsd:new-project` creates a new `config.json`, it reads global defaults and merges them as the starting configuration. Per-project settings always override globals. diff --git a/docs/FEATURES.md b/docs/FEATURES.md new file mode 100644 index 000000000..39ffd3192 --- /dev/null +++ b/docs/FEATURES.md @@ -0,0 +1,756 @@ +# GSD Feature Reference + +> Complete feature and function documentation with requirements. For architecture details, see [Architecture](ARCHITECTURE.md). For command syntax, see [Command Reference](COMMANDS.md). + +--- + +## Table of Contents + +- [Core Features](#core-features) + - [Project Initialization](#1-project-initialization) + - [Phase Discussion](#2-phase-discussion) + - [UI Design Contract](#3-ui-design-contract) + - [Phase Planning](#4-phase-planning) + - [Phase Execution](#5-phase-execution) + - [Work Verification](#6-work-verification) + - [UI Review](#7-ui-review) + - [Milestone Management](#8-milestone-management) +- [Planning Features](#planning-features) + - [Phase Management](#9-phase-management) + - [Quick Mode](#10-quick-mode) + - [Autonomous Mode](#11-autonomous-mode) + - [Freeform Routing](#12-freeform-routing) +- [Quality Assurance Features](#quality-assurance-features) + - [Nyquist Validation](#13-nyquist-validation) + - [Plan Checking](#14-plan-checking) + - [Post-Execution Verification](#15-post-execution-verification) + - [Node Repair](#16-node-repair) + - [Health Validation](#17-health-validation) +- [Context Engineering Features](#context-engineering-features) + - [Context Window Monitoring](#18-context-window-monitoring) + - [Session Management](#19-session-management) + - [Multi-Agent Orchestration](#20-multi-agent-orchestration) + - [Model Profiles](#21-model-profiles) +- [Brownfield Features](#brownfield-features) + - [Codebase Mapping](#22-codebase-mapping) +- [Utility Features](#utility-features) + - [Debug System](#23-debug-system) + - [Todo Management](#24-todo-management) + - [Statistics Dashboard](#25-statistics-dashboard) + - [Update System](#26-update-system) + - [Settings Management](#27-settings-management) + - [Test Generation](#28-test-generation) +- [Infrastructure Features](#infrastructure-features) + - [Git Integration](#29-git-integration) + - [CLI Tools](#30-cli-tools) + - [Multi-Runtime Support](#31-multi-runtime-support) + - [Hook System](#32-hook-system) + +--- + +## Core Features + +### 1. Project Initialization + +**Command:** `/gsd:new-project [--auto @file.md]` + +**Purpose:** Transform a user's idea into a fully structured project with research, scoped requirements, and a phased roadmap. + +**Requirements:** +- REQ-INIT-01: System MUST conduct adaptive questioning until project scope is fully understood +- REQ-INIT-02: System MUST spawn parallel research agents to investigate the domain ecosystem +- REQ-INIT-03: System MUST extract requirements into v1 (must-have), v2 (future), and out-of-scope categories +- REQ-INIT-04: System MUST generate a phased roadmap with requirement traceability +- REQ-INIT-05: System MUST require user approval of the roadmap before proceeding +- REQ-INIT-06: System MUST prevent re-initialization when `.planning/PROJECT.md` already exists +- REQ-INIT-07: System MUST support `--auto @file.md` flag to skip interactive questions and extract from a document + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `PROJECT.md` | Project vision, constraints, technical decisions | +| `REQUIREMENTS.md` | Scoped requirements with unique IDs (REQ-XX) | +| `ROADMAP.md` | Phase breakdown with status tracking and requirement mapping | +| `STATE.md` | Initial project state with position, decisions, metrics | +| `config.json` | Workflow configuration | +| `research/SUMMARY.md` | Synthesized domain research | +| `research/STACK.md` | Technology stack investigation | +| `research/FEATURES.md` | Feature implementation patterns | +| `research/ARCHITECTURE.md` | Architecture patterns and trade-offs | +| `research/PITFALLS.md` | Common failure modes and mitigations | + +**Process:** +1. **Questions** — Adaptive questioning guided by the "dream extraction" philosophy (not requirements gathering) +2. **Research** — 4 parallel researcher agents investigate stack, features, architecture, and pitfalls +3. **Synthesis** — Research synthesizer combines findings into SUMMARY.md +4. **Requirements** — Extracted from user responses + research, categorized by scope +5. **Roadmap** — Phase breakdown mapped to requirements, with granularity setting controlling phase count + +**Functional Requirements:** +- Questions adapt based on detected project type (web app, CLI, mobile, API, etc.) +- Research agents have web search capability for current ecosystem information +- Granularity setting controls phase count: `coarse` (3-5), `standard` (5-8), `fine` (8-12) +- `--auto` mode extracts all information from the provided document without interactive questioning +- Existing codebase context (from `/gsd:map-codebase`) is loaded if present + +--- + +### 2. Phase Discussion + +**Command:** `/gsd:discuss-phase [N] [--auto] [--batch]` + +**Purpose:** Capture user's implementation preferences and decisions before research and planning begin. Eliminates the gray areas that cause AI to guess. + +**Requirements:** +- REQ-DISC-01: System MUST analyze the phase scope and identify decision areas (gray areas) +- REQ-DISC-02: System MUST categorize gray areas by type (visual, API, content, organization, etc.) +- REQ-DISC-03: System MUST ask only questions not already answered in prior CONTEXT.md files +- REQ-DISC-04: System MUST persist decisions in `{phase}-CONTEXT.md` with canonical references +- REQ-DISC-05: System MUST support `--auto` flag to auto-select recommended defaults +- REQ-DISC-06: System MUST support `--batch` flag for grouped question intake +- REQ-DISC-07: System MUST scout relevant source files before identifying gray areas (code-aware discussion) + +**Produces:** `{padded_phase}-CONTEXT.md` — User preferences that feed into research and planning + +**Gray Area Categories:** +| Category | Example Decisions | +|----------|-------------------| +| Visual features | Layout, density, interactions, empty states | +| APIs/CLIs | Response format, flags, error handling, verbosity | +| Content systems | Structure, tone, depth, flow | +| Organization | Grouping criteria, naming, duplicates, exceptions | + +--- + +### 3. UI Design Contract + +**Command:** `/gsd:ui-phase [N]` + +**Purpose:** Lock design decisions before planning so that all components in a phase share consistent visual standards. + +**Requirements:** +- REQ-UI-01: System MUST detect existing design system state (shadcn components.json, Tailwind config, tokens) +- REQ-UI-02: System MUST ask only unanswered design contract questions +- REQ-UI-03: System MUST validate against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety) +- REQ-UI-04: System MUST enter revision loop if validation returns BLOCKED (max 2 iterations) +- REQ-UI-05: System MUST offer shadcn initialization for React/Next.js/Vite projects without `components.json` +- REQ-UI-06: System MUST enforce registry safety gate for third-party shadcn registries + +**Produces:** `{padded_phase}-UI-SPEC.md` — Design contract consumed by executors + +**6 Validation Dimensions:** +1. **Copywriting** — CTA labels, empty states, error messages +2. **Visuals** — Focal points, visual hierarchy, icon accessibility +3. **Color** — Accent usage discipline, 60/30/10 compliance +4. **Typography** — Font size/weight constraint adherence +5. **Spacing** — Grid alignment, token consistency +6. **Registry Safety** — Third-party component inspection requirements + +**shadcn Integration:** +- Detects missing `components.json` in React/Next.js/Vite projects +- Guides user through `ui.shadcn.com/create` preset configuration +- Preset string becomes a planning artifact reproducible across phases +- Safety gate requires `npx shadcn view` and `npx shadcn diff` before third-party components + +--- + +### 4. Phase Planning + +**Command:** `/gsd:plan-phase [N] [--auto] [--skip-research] [--skip-verify]` + +**Purpose:** Research the implementation domain and produce verified, atomic execution plans. + +**Requirements:** +- REQ-PLAN-01: System MUST spawn a phase researcher to investigate implementation approaches +- REQ-PLAN-02: System MUST produce plans with 2-3 tasks each, sized for a single context window +- REQ-PLAN-03: System MUST structure plans as XML with `` elements containing `name`, `files`, `action`, `verify`, and `done` fields +- REQ-PLAN-04: System MUST include `read_first` and `acceptance_criteria` sections in every plan +- REQ-PLAN-05: System MUST run plan checker verification loop (up to 3 iterations) unless `--skip-verify` is set +- REQ-PLAN-06: System MUST support `--skip-research` flag to bypass research phase +- REQ-PLAN-07: System MUST prompt user to run `/gsd:ui-phase` if frontend phase detected and no UI-SPEC.md exists (UI safety gate) +- REQ-PLAN-08: System MUST include Nyquist validation mapping when `workflow.nyquist_validation` is enabled + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `{phase}-RESEARCH.md` | Ecosystem research findings | +| `{phase}-{N}-PLAN.md` | Atomic execution plans (2-3 tasks each) | +| `{phase}-VALIDATION.md` | Test coverage mapping (Nyquist layer) | + +**Plan Structure (XML):** +```xml + + Create login endpoint + src/app/api/auth/login/route.ts + + Use jose for JWT. Validate credentials against users table. + Return httpOnly cookie on success. + + curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie + Valid credentials return cookie, invalid return 401 + +``` + +**Plan Checker Verification (8 Dimensions):** +1. Requirement coverage — Plans address all phase requirements +2. Task atomicity — Each task is independently committable +3. Dependency ordering — Tasks sequence correctly +4. File scope — No excessive file overlap between plans +5. Verification commands — Each task has testable done criteria +6. Context fit — Tasks fit within a single context window +7. Gap detection — No missing implementation steps +8. Nyquist compliance — Tasks have automated verify commands (when enabled) + +--- + +### 5. Phase Execution + +**Command:** `/gsd:execute-phase ` + +**Purpose:** Execute all plans in a phase using wave-based parallelization with fresh context windows per executor. + +**Requirements:** +- REQ-EXEC-01: System MUST analyze plan dependencies and group into execution waves +- REQ-EXEC-02: System MUST spawn independent plans in parallel within each wave +- REQ-EXEC-03: System MUST give each executor a fresh context window (200K tokens) +- REQ-EXEC-04: System MUST produce atomic git commits per task +- REQ-EXEC-05: System MUST produce a SUMMARY.md for each completed plan +- REQ-EXEC-06: System MUST run post-execution verifier to check phase goals were met +- REQ-EXEC-07: System MUST support git branching strategies (`none`, `phase`, `milestone`) +- REQ-EXEC-08: System MUST invoke node repair operator on task verification failure (when enabled) + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `{phase}-{N}-SUMMARY.md` | Execution outcomes per plan | +| `{phase}-VERIFICATION.md` | Post-execution verification report | +| Git commits | Atomic commits per task | + +**Wave Execution:** +- Plans with no dependencies → Wave 1 (parallel) +- Plans depending on Wave 1 → Wave 2 (parallel, waits for Wave 1) +- Continues until all plans complete +- File conflicts force sequential execution within same wave + +**Executor Capabilities:** +- Reads PLAN.md with full task instructions +- Has access to PROJECT.md, STATE.md, CONTEXT.md, RESEARCH.md +- Commits each task atomically with structured commit messages +- Handles checkpoint types: `auto`, `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action` +- Reports deviations from plan in SUMMARY.md + +--- + +### 6. Work Verification + +**Command:** `/gsd:verify-work [N]` + +**Purpose:** User acceptance testing — walk the user through testing each deliverable and auto-diagnose failures. + +**Requirements:** +- REQ-VERIFY-01: System MUST extract testable deliverables from the phase +- REQ-VERIFY-02: System MUST present deliverables one at a time for user confirmation +- REQ-VERIFY-03: System MUST spawn debug agents to diagnose failures automatically +- REQ-VERIFY-04: System MUST create fix plans for identified issues +- REQ-VERIFY-05: System MUST inject cold-start smoke test for phases modifying server/database/seed/startup files +- REQ-VERIFY-06: System MUST produce UAT.md with pass/fail results + +**Produces:** `{phase}-UAT.md` — User acceptance test results, plus fix plans if issues found + +--- + +### 7. UI Review + +**Command:** `/gsd:ui-review [N]` + +**Purpose:** Retroactive 6-pillar visual audit of implemented frontend code. Works standalone on any project. + +**Requirements:** +- REQ-UIREVIEW-01: System MUST score each of the 6 pillars on a 1-4 scale +- REQ-UIREVIEW-02: System MUST capture screenshots via Playwright CLI to `.planning/ui-reviews/` +- REQ-UIREVIEW-03: System MUST create `.gitignore` for screenshot directory +- REQ-UIREVIEW-04: System MUST identify top 3 priority fixes +- REQ-UIREVIEW-05: System MUST work standalone (without UI-SPEC.md) using abstract quality standards + +**6 Audit Pillars (scored 1-4):** +1. **Copywriting** — CTA labels, empty states, error states +2. **Visuals** — Focal points, visual hierarchy, icon accessibility +3. **Color** — Accent usage discipline, 60/30/10 compliance +4. **Typography** — Font size/weight constraint adherence +5. **Spacing** — Grid alignment, token consistency +6. **Experience Design** — Loading/error/empty state coverage + +**Produces:** `{padded_phase}-UI-REVIEW.md` — Scores and prioritized fixes + +--- + +### 8. Milestone Management + +**Commands:** `/gsd:audit-milestone`, `/gsd:complete-milestone`, `/gsd:new-milestone [name]` + +**Purpose:** Verify milestone completion, archive, tag release, and start the next development cycle. + +**Requirements:** +- REQ-MILE-01: Audit MUST verify all milestone requirements are met +- REQ-MILE-02: Audit MUST detect stubs, placeholder implementations, and untested code +- REQ-MILE-03: Audit MUST check Nyquist validation compliance across phases +- REQ-MILE-04: Complete MUST archive milestone data to MILESTONES.md +- REQ-MILE-05: Complete MUST offer git tag creation for the release +- REQ-MILE-06: Complete MUST offer squash merge or merge with history for branching strategies +- REQ-MILE-07: Complete MUST clean up UI review screenshots +- REQ-MILE-08: New milestone MUST follow same flow as new-project (questions → research → requirements → roadmap) +- REQ-MILE-09: New milestone MUST NOT reset existing workflow configuration + +**Gap Closure:** `/gsd:plan-milestone-gaps` creates phases to close gaps identified by audit. + +--- + +## Planning Features + +### 9. Phase Management + +**Commands:** `/gsd:add-phase`, `/gsd:insert-phase [N]`, `/gsd:remove-phase [N]` + +**Purpose:** Dynamic roadmap modification during development. + +**Requirements:** +- REQ-PHASE-01: Add MUST append a new phase to the end of the current roadmap +- REQ-PHASE-02: Insert MUST use decimal numbering (e.g., 3.1) between existing phases +- REQ-PHASE-03: Remove MUST renumber all subsequent phases +- REQ-PHASE-04: Remove MUST prevent removing phases that have been executed +- REQ-PHASE-05: All operations MUST update ROADMAP.md and create/remove phase directories + +--- + +### 10. Quick Mode + +**Command:** `/gsd:quick [--full] [--discuss] [--research]` + +**Purpose:** Ad-hoc task execution with GSD guarantees but a faster path. + +**Requirements:** +- REQ-QUICK-01: System MUST accept freeform task description +- REQ-QUICK-02: System MUST use same planner + executor agents as full workflow +- REQ-QUICK-03: System MUST skip research, plan checker, and verifier by default +- REQ-QUICK-04: `--full` flag MUST enable plan checking (max 2 iterations) and post-execution verification +- REQ-QUICK-05: `--discuss` flag MUST run lightweight pre-planning discussion +- REQ-QUICK-06: `--research` flag MUST spawn focused research agent before planning +- REQ-QUICK-07: Flags MUST be composable (`--discuss --research --full`) +- REQ-QUICK-08: System MUST track quick tasks in `.planning/quick/YYMMDD-xxx-slug/` +- REQ-QUICK-09: System MUST produce atomic commits for quick task execution + +--- + +### 11. Autonomous Mode + +**Command:** `/gsd:autonomous [--from N]` + +**Purpose:** Run all remaining phases autonomously — discuss → plan → execute per phase. + +**Requirements:** +- REQ-AUTO-01: System MUST iterate through all incomplete phases in roadmap order +- REQ-AUTO-02: System MUST run discuss → plan → execute for each phase +- REQ-AUTO-03: System MUST pause for explicit user decisions (gray area acceptance, blockers, validation) +- REQ-AUTO-04: System MUST re-read ROADMAP.md after each phase to catch dynamically inserted phases +- REQ-AUTO-05: `--from N` flag MUST start from a specific phase number + +--- + +### 12. Freeform Routing + +**Command:** `/gsd:do` + +**Purpose:** Analyze freeform text and route to the appropriate GSD command. + +**Requirements:** +- REQ-DO-01: System MUST parse user intent from natural language input +- REQ-DO-02: System MUST map intent to the best matching GSD command +- REQ-DO-03: System MUST confirm the routing with the user before executing +- REQ-DO-04: System MUST handle project-exists vs no-project contexts differently + +--- + +## Quality Assurance Features + +### 13. Nyquist Validation + +**Purpose:** Map automated test coverage to phase requirements before any code is written. Named after the Nyquist sampling theorem — ensures a feedback signal exists for every requirement. + +**Requirements:** +- REQ-NYQ-01: System MUST detect existing test infrastructure during plan-phase research +- REQ-NYQ-02: System MUST map each requirement to a specific test command +- REQ-NYQ-03: System MUST identify Wave 0 tasks (test scaffolding needed before implementation) +- REQ-NYQ-04: Plan checker MUST enforce Nyquist compliance as 8th verification dimension +- REQ-NYQ-05: System MUST support retroactive validation via `/gsd:validate-phase` +- REQ-NYQ-06: System MUST be disableable via `workflow.nyquist_validation: false` + +**Produces:** `{phase}-VALIDATION.md` — Test coverage contract + +**Retroactive Validation (`/gsd:validate-phase [N]`):** +- Scans implementation and maps requirements to tests +- Identifies gaps where requirements lack automated verification +- Spawns auditor to generate tests (max 3 attempts) +- Never modifies implementation code — only test files and VALIDATION.md +- Flags implementation bugs as escalations for user to address + +--- + +### 14. Plan Checking + +**Purpose:** Goal-backward verification that plans will achieve phase objectives before execution. + +**Requirements:** +- REQ-PLANCK-01: System MUST verify plans against 8 quality dimensions +- REQ-PLANCK-02: System MUST loop up to 3 iterations until plans pass +- REQ-PLANCK-03: System MUST produce specific, actionable feedback on failures +- REQ-PLANCK-04: System MUST be disableable via `workflow.plan_check: false` + +--- + +### 15. Post-Execution Verification + +**Purpose:** Automated check that the codebase delivers what the phase promised. + +**Requirements:** +- REQ-POSTVER-01: System MUST check against phase goals, not just task completion +- REQ-POSTVER-02: System MUST produce VERIFICATION.md with pass/fail analysis +- REQ-POSTVER-03: System MUST log issues for `/gsd:verify-work` to address +- REQ-POSTVER-04: System MUST be disableable via `workflow.verifier: false` + +--- + +### 16. Node Repair + +**Purpose:** Autonomous recovery when task verification fails during execution. + +**Requirements:** +- REQ-REPAIR-01: System MUST analyze failure and choose one strategy: RETRY, DECOMPOSE, or PRUNE +- REQ-REPAIR-02: RETRY MUST attempt with a concrete adjustment +- REQ-REPAIR-03: DECOMPOSE MUST break task into smaller verifiable sub-steps +- REQ-REPAIR-04: PRUNE MUST remove unachievable tasks and escalate to user +- REQ-REPAIR-05: System MUST respect repair budget (default: 2 attempts per task) +- REQ-REPAIR-06: System MUST be configurable via `workflow.node_repair_budget` and `workflow.node_repair` + +--- + +### 17. Health Validation + +**Command:** `/gsd:health [--repair]` + +**Purpose:** Validate `.planning/` directory integrity and auto-repair issues. + +**Requirements:** +- REQ-HEALTH-01: System MUST check for missing required files +- REQ-HEALTH-02: System MUST validate configuration consistency +- REQ-HEALTH-03: System MUST detect orphaned plans without summaries +- REQ-HEALTH-04: System MUST check phase numbering and roadmap sync +- REQ-HEALTH-05: `--repair` flag MUST auto-fix recoverable issues + +--- + +## Context Engineering Features + +### 18. Context Window Monitoring + +**Purpose:** Prevent context rot by alerting both user and agent when context is running low. + +**Requirements:** +- REQ-CTX-01: Statusline MUST display context usage percentage to user +- REQ-CTX-02: Context monitor MUST inject agent-facing warnings at ≤35% remaining (WARNING) +- REQ-CTX-03: Context monitor MUST inject agent-facing warnings at ≤25% remaining (CRITICAL) +- REQ-CTX-04: Warnings MUST debounce (5 tool uses between repeated warnings) +- REQ-CTX-05: Severity escalation (WARNING→CRITICAL) MUST bypass debounce +- REQ-CTX-06: Context monitor MUST differentiate GSD-active vs non-GSD-active projects +- REQ-CTX-07: Warnings MUST be advisory, never imperative commands that override user preferences +- REQ-CTX-08: All hooks MUST fail silently and never block tool execution + +**Architecture:** Two-part bridge system: +1. Statusline writes metrics to `/tmp/claude-ctx-{session}.json` +2. Context monitor reads metrics and injects `additionalContext` warnings + +--- + +### 19. Session Management + +**Commands:** `/gsd:pause-work`, `/gsd:resume-work`, `/gsd:progress` + +**Purpose:** Maintain project continuity across context resets and sessions. + +**Requirements:** +- REQ-SESSION-01: Pause MUST save current position and next steps to `continue-here.md` +- REQ-SESSION-02: Resume MUST restore full project context from state files +- REQ-SESSION-03: Progress MUST show current position, next action, and overall completion +- REQ-SESSION-04: Progress MUST read all state files (STATE.md, ROADMAP.md, phase directories) +- REQ-SESSION-05: All session operations MUST work after `/clear` (context reset) + +--- + +### 20. Multi-Agent Orchestration + +**Purpose:** Coordinate specialized agents with fresh context windows for each task. + +**Requirements:** +- REQ-ORCH-01: Each agent MUST receive a fresh context window +- REQ-ORCH-02: Orchestrators MUST be thin — spawn agents, collect results, route next +- REQ-ORCH-03: Context payload MUST include all relevant project artifacts +- REQ-ORCH-04: Parallel agents MUST be truly independent (no shared mutable state) +- REQ-ORCH-05: Agent results MUST be written to disk before orchestrator processes them +- REQ-ORCH-06: Failed agents MUST be detected (spot-check actual output vs reported failure) + +--- + +### 21. Model Profiles + +**Command:** `/gsd:set-profile ` + +**Purpose:** Control which AI model each agent uses, balancing quality vs cost. + +**Requirements:** +- REQ-MODEL-01: System MUST support 4 profiles: `quality`, `balanced`, `budget`, `inherit` +- REQ-MODEL-02: Each profile MUST define model tier per agent (see profile table) +- REQ-MODEL-03: Per-agent overrides MUST take precedence over profile +- REQ-MODEL-04: `inherit` profile MUST defer to runtime's current model selection +- REQ-MODEL-05: Profile switch MUST be programmatic (script, not LLM-driven) +- REQ-MODEL-06: Model resolution MUST happen once per orchestration, not per spawn + +**Profile Assignments:** + +| Agent | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +--- + +## Brownfield Features + +### 22. Codebase Mapping + +**Command:** `/gsd:map-codebase [area]` + +**Purpose:** Analyze an existing codebase before starting a new project, so GSD understands what exists. + +**Requirements:** +- REQ-MAP-01: System MUST spawn parallel mapper agents for each analysis area +- REQ-MAP-02: System MUST produce structured documents in `.planning/codebase/` +- REQ-MAP-03: System MUST detect: tech stack, architecture patterns, coding conventions, concerns +- REQ-MAP-04: Subsequent `/gsd:new-project` MUST load codebase mapping and focus questions on what's being added +- REQ-MAP-05: Optional `[area]` argument MUST scope mapping to a specific area + +**Produces:** +| Document | Content | +|----------|---------| +| `STACK.md` | Languages, frameworks, databases, infrastructure | +| `ARCHITECTURE.md` | Patterns, layers, data flow, boundaries | +| `CONVENTIONS.md` | Naming, file organization, code style, testing patterns | +| `CONCERNS.md` | Technical debt, security issues, performance bottlenecks | +| `STRUCTURE.md` | Directory layout and file organization | +| `TESTING.md` | Test infrastructure, coverage, patterns | +| `INTEGRATIONS.md` | External services, APIs, third-party dependencies | + +--- + +## Utility Features + +### 23. Debug System + +**Command:** `/gsd:debug [description]` + +**Purpose:** Systematic debugging with persistent state across context resets. + +**Requirements:** +- REQ-DEBUG-01: System MUST create debug session file in `.planning/debug/` +- REQ-DEBUG-02: System MUST track hypotheses, evidence, and eliminated theories +- REQ-DEBUG-03: System MUST persist state so debugging survives context resets +- REQ-DEBUG-04: System MUST require human verification before marking resolved +- REQ-DEBUG-05: Resolved sessions MUST append to `.planning/debug/knowledge-base.md` +- REQ-DEBUG-06: Knowledge base MUST be consulted on new debug sessions to prevent re-investigation + +**Debug Session States:** `gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +--- + +### 24. Todo Management + +**Commands:** `/gsd:add-todo [desc]`, `/gsd:check-todos` + +**Purpose:** Capture ideas and tasks during sessions for later work. + +**Requirements:** +- REQ-TODO-01: System MUST capture todo from current conversation context +- REQ-TODO-02: Todos MUST be stored in `.planning/todos/pending/` +- REQ-TODO-03: Completed todos MUST move to `.planning/todos/done/` +- REQ-TODO-04: Check-todos MUST list all pending items with selection to work on one + +--- + +### 25. Statistics Dashboard + +**Command:** `/gsd:stats` + +**Purpose:** Display project metrics — phases, plans, requirements, git history, and timeline. + +**Requirements:** +- REQ-STATS-01: System MUST show phase/plan completion counts +- REQ-STATS-02: System MUST show requirement coverage +- REQ-STATS-03: System MUST show git commit metrics +- REQ-STATS-04: System MUST support multiple output formats (json, table, bar) + +--- + +### 26. Update System + +**Command:** `/gsd:update` + +**Purpose:** Update GSD to the latest version with changelog preview. + +**Requirements:** +- REQ-UPDATE-01: System MUST check for new versions via npm +- REQ-UPDATE-02: System MUST display changelog for new version before updating +- REQ-UPDATE-03: System MUST be runtime-aware and target the correct directory +- REQ-UPDATE-04: System MUST back up locally modified files to `gsd-local-patches/` +- REQ-UPDATE-05: `/gsd:reapply-patches` MUST restore local modifications after update + +--- + +### 27. Settings Management + +**Command:** `/gsd:settings` + +**Purpose:** Interactive configuration of workflow toggles and model profile. + +**Requirements:** +- REQ-SETTINGS-01: System MUST present current settings with toggle options +- REQ-SETTINGS-02: System MUST update `.planning/config.json` +- REQ-SETTINGS-03: System MUST support saving as global defaults (`~/.gsd/defaults.json`) + +**Configurable Settings:** +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `mode` | enum | `interactive` | `interactive` or `yolo` (auto-approve) | +| `granularity` | enum | `standard` | `coarse`, `standard`, or `fine` | +| `model_profile` | enum | `balanced` | `quality`, `balanced`, `budget`, or `inherit` | +| `workflow.research` | boolean | `true` | Domain research before planning | +| `workflow.plan_check` | boolean | `true` | Plan verification loop | +| `workflow.verifier` | boolean | `true` | Post-execution verification | +| `workflow.auto_advance` | boolean | `false` | Auto-chain discuss→plan→execute | +| `workflow.nyquist_validation` | boolean | `true` | Nyquist test coverage mapping | +| `workflow.ui_phase` | boolean | `true` | UI design contract generation | +| `workflow.ui_safety_gate` | boolean | `true` | Prompt for ui-phase on frontend phases | +| `workflow.node_repair` | boolean | `true` | Autonomous task repair | +| `workflow.node_repair_budget` | number | `2` | Max repair attempts per task | +| `planning.commit_docs` | boolean | `true` | Commit `.planning/` files to git | +| `planning.search_gitignored` | boolean | `false` | Include gitignored files in searches | +| `parallelization.enabled` | boolean | `true` | Run independent plans simultaneously | +| `git.branching_strategy` | enum | `none` | `none`, `phase`, or `milestone` | + +--- + +### 28. Test Generation + +**Command:** `/gsd:add-tests [N]` + +**Purpose:** Generate tests for a completed phase based on UAT criteria and implementation. + +**Requirements:** +- REQ-TEST-01: System MUST analyze completed phase implementation +- REQ-TEST-02: System MUST generate tests based on UAT criteria and acceptance criteria +- REQ-TEST-03: System MUST use existing test infrastructure patterns + +--- + +## Infrastructure Features + +### 29. Git Integration + +**Purpose:** Atomic commits, branching strategies, and clean history management. + +**Requirements:** +- REQ-GIT-01: Each task MUST get its own atomic commit +- REQ-GIT-02: Commit messages MUST follow structured format: `type(scope): description` +- REQ-GIT-03: System MUST support 3 branching strategies: `none`, `phase`, `milestone` +- REQ-GIT-04: Phase strategy MUST create one branch per phase +- REQ-GIT-05: Milestone strategy MUST create one branch per milestone +- REQ-GIT-06: Complete-milestone MUST offer squash merge (recommended) or merge with history +- REQ-GIT-07: System MUST respect `commit_docs` setting for `.planning/` files +- REQ-GIT-08: System MUST auto-detect `.planning/` in `.gitignore` and skip commits + +**Commit Format:** +``` +type(phase-plan): description + +# Examples: +docs(08-02): complete user registration plan +feat(08-02): add email confirmation flow +fix(03-01): correct auth token expiry +``` + +--- + +### 30. CLI Tools + +**Purpose:** Programmatic utilities for workflows and agents, replacing repetitive inline bash patterns. + +**Requirements:** +- REQ-CLI-01: System MUST provide atomic commands for state, config, phase, roadmap operations +- REQ-CLI-02: System MUST provide compound `init` commands that load all context for each workflow +- REQ-CLI-03: System MUST support `--raw` flag for machine-readable output +- REQ-CLI-04: System MUST support `--cwd` flag for sandboxed subagent operation +- REQ-CLI-05: All operations MUST use forward-slash paths on Windows + +**Command Categories:** State (11 subcommands), Phase (5), Roadmap (3), Verify (8), Template (2), Frontmatter (4), Scaffold (4), Init (12), Validate (2), Progress, Stats, Todo + +--- + +### 31. Multi-Runtime Support + +**Purpose:** Run GSD across 6 different AI coding agent runtimes. + +**Requirements:** +- REQ-RUNTIME-01: System MUST support Claude Code, OpenCode, Gemini CLI, Codex, Copilot, Antigravity +- REQ-RUNTIME-02: Installer MUST transform content per runtime (tool names, paths, frontmatter) +- REQ-RUNTIME-03: Installer MUST support interactive and non-interactive (`--claude --global`) modes +- REQ-RUNTIME-04: Installer MUST support both global and local installation +- REQ-RUNTIME-05: Uninstall MUST cleanly remove all GSD files without affecting other configurations +- REQ-RUNTIME-06: Installer MUST handle platform differences (Windows, macOS, Linux, WSL, Docker) + +**Runtime Transformations:** + +| Aspect | Claude Code | OpenCode | Gemini | Codex | Copilot | Antigravity | +|--------|------------|----------|--------|-------|---------|-------------| +| Commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills | +| Agent format | Claude native | `mode: subagent` | Claude native | Skills | Tool mapping | Skills | +| Hook events | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | +| Config | `settings.json` | `opencode.json(c)` | `settings.json` | TOML | Instructions | Config | + +--- + +### 32. Hook System + +**Purpose:** Runtime event hooks for context monitoring, status display, and update checking. + +**Requirements:** +- REQ-HOOK-01: Statusline MUST display model, current task, directory, and context usage +- REQ-HOOK-02: Context monitor MUST inject agent-facing warnings at threshold levels +- REQ-HOOK-03: Update checker MUST run in background on session start +- REQ-HOOK-04: All hooks MUST respect `CLAUDE_CONFIG_DIR` env var +- REQ-HOOK-05: All hooks MUST include 3-second stdin timeout guard +- REQ-HOOK-06: All hooks MUST fail silently on any error +- REQ-HOOK-07: Context usage MUST normalize for autocompact buffer (16.5% reserved) + +**Statusline Display:** +``` +[⬆ /gsd:update │] model │ [current task │] directory [█████░░░░░ 50%] +``` + +Color coding: <50% green, <65% yellow, <80% orange, ≥80% red with skull emoji diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..821778766 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,25 @@ +# GSD Documentation + +Comprehensive documentation for the Get Shit Done (GSD) framework — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. + +## Documentation Index + +| Document | Audience | Description | +|----------|----------|-------------| +| [Architecture](ARCHITECTURE.md) | Contributors, advanced users | System architecture, agent model, data flow, and internal design | +| [Feature Reference](FEATURES.md) | All users | Complete feature and function documentation with requirements | +| [Command Reference](COMMANDS.md) | All users | Every command with syntax, flags, options, and examples | +| [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching | +| [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents | +| [Agent Reference](AGENTS.md) | Contributors, advanced users | All 15 specialized agents — roles, tools, spawn patterns | +| [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery | +| [Context Monitor](context-monitor.md) | All users | Context window monitoring hook architecture | + +## Quick Links + +- **Getting started:** [README](../README.md) → install → `/gsd:new-project` +- **Full workflow walkthrough:** [User Guide](USER-GUIDE.md) +- **All commands at a glance:** [Command Reference](COMMANDS.md) +- **Configuring GSD:** [Configuration Reference](CONFIGURATION.md) +- **How the system works internally:** [Architecture](ARCHITECTURE.md) +- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)