docs/FEATURES.md
Complete feature and function documentation with requirements. For architecture details, see Architecture. For command syntax, see Command Reference.
--to N Flag--power Flag--diagnose Flag--interactive Flag--to N Flag--power Flag--diagnose Flag--interactive FlagCommand: /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:
.planning/PROJECT.md already exists--auto @file.md flag to skip interactive questions and extract from a documentProduces:
| Artifact | Description |
|---|---|
PROJECT.md | Project vision, constraints, technical decisions, evolution rules |
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:
Functional Requirements:
coarse (3-5), standard (5-8), fine (8-12)--auto mode extracts all information from the provided document without interactive questioning/gsd-map-codebase) is loaded if presentCommand: /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:
{phase}-CONTEXT.md with canonical references--auto flag to auto-select recommended defaults--batch flag for grouped question intakeProduces: {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 |
Command: /gsd-ui-phase [N]
Purpose: Lock design decisions before planning so that all components in a phase share consistent visual standards.
Requirements:
components.jsonProduces: {padded_phase}-UI-SPEC.md — Design contract consumed by executors
6 Validation Dimensions:
shadcn Integration:
components.json in React/Next.js/Vite projectsui.shadcn.com/create preset configurationnpx shadcn view and npx shadcn diff before third-party componentsCommand: /gsd-plan-phase [N] [--auto] [--skip-research] [--skip-verify]
Purpose: Research the implementation domain and produce verified, atomic execution plans.
Requirements:
<task> elements containing name, files, action, verify, and done fieldsread_first and acceptance_criteria sections in every plan--skip-verify is set--skip-research flag to bypass research phase/gsd-ui-phase if frontend phase detected and no UI-SPEC.md exists (UI safety gate)workflow.nyquist_validation is enabledProduces:
| 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):
<task type="auto">
<name>Create login endpoint</name>
<files>src/app/api/auth/login/route.ts</files>
<action>
Use jose for JWT. Validate credentials against users table.
Return httpOnly cookie on success.
</action>
<verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
<done>Valid credentials return cookie, invalid return 401</done>
</task>
Plan Checker Verification (8 Dimensions):
Command: /gsd-execute-phase <N>
Purpose: Execute all plans in a phase using wave-based parallelization with fresh context windows per executor.
Requirements:
none, phase, milestone)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:
Executor Capabilities:
--no-verify on commits during parallel execution to avoid build lock contentionauto, checkpoint:human-verify, checkpoint:decision, checkpoint:human-actionParallel Safety:
--no-verify), run once by orchestrator after each waveCommand: /gsd-verify-work [N]
Purpose: User acceptance testing — walk the user through testing each deliverable and auto-diagnose failures.
Requirements:
Produces: {phase}-UAT.md — User acceptance test results, plus fix plans if issues found
Command: /gsd-ship [N] [--draft]
Purpose: Bridge local completion → merged PR. After verification passes, push branch, create PR with auto-generated body from planning artifacts, optionally trigger review, and track in STATE.md.
Requirements:
gh CLI--draft flag for draft PRsPrerequisites: Phase verified, gh CLI installed and authenticated, work on feature branch
Produces: GitHub PR with rich body, STATE.md updated
Command: /gsd-ui-review [N]
Purpose: Retroactive 6-pillar visual audit of implemented frontend code. Works standalone on any project.
Requirements:
.planning/ui-reviews/.gitignore for screenshot directory6 Audit Pillars (scored 1-4):
Produces: {padded_phase}-UI-REVIEW.md — Scores and prioritized fixes
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:
Commands: /gsd-add-phase, /gsd-insert-phase [N], /gsd-remove-phase [N]
Purpose: Dynamic roadmap modification during development.
Requirements:
Command: /gsd-quick [--full] [--discuss] [--research]
Purpose: Ad-hoc task execution with GSD guarantees but a faster path.
Requirements:
--full flag MUST enable plan checking (max 2 iterations) and post-execution verification--discuss flag MUST run lightweight pre-planning discussion--research flag MUST spawn focused research agent before planning--discuss --research --full).planning/quick/YYMMDD-xxx-slug/Command: /gsd-autonomous [--from N]
Purpose: Run all remaining phases autonomously — discuss → plan → execute per phase.
Requirements:
--from N flag MUST start from a specific phase numberCommand: /gsd-do
Purpose: Analyze freeform text and route to the appropriate GSD command.
Requirements:
Command: /gsd-note
Purpose: Zero-friction idea capture without interrupting workflow. Append timestamped notes, list all notes, or promote notes to structured todos.
Requirements:
list subcommand to show all notes from project and global scopespromote N subcommand to convert a note into a structured todo--global flag for global scope operationsCommand: /gsd-next
Purpose: Automatically detect current project state and advance to the next logical workflow step, eliminating the need to remember which phase/step you're on.
Requirements:
/gsd-new-project if no project exists/gsd-complete-milestone when all phases are completeState Detection Logic:
| State | Action |
|---|---|
No .planning/ directory | Suggest /gsd-new-project |
| Phase has no CONTEXT.md | Run /gsd-discuss-phase |
| Phase has no PLAN.md files | Run /gsd-plan-phase |
| Phase has plans but no SUMMARY.md | Run /gsd-execute-phase |
| Phase executed but no VERIFICATION.md | Run /gsd-verify-work |
| All phases complete | Suggest /gsd-complete-milestone |
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:
/gsd-validate-phaseworkflow.nyquist_validation: falseProduces: {phase}-VALIDATION.md — Test coverage contract
Retroactive Validation (/gsd-validate-phase [N]):
Purpose: Goal-backward verification that plans will achieve phase objectives before execution.
Requirements:
workflow.plan_check: falsePurpose: Automated check that the codebase delivers what the phase promised.
Requirements:
/gsd-verify-work to addressworkflow.verifier: falsePurpose: Autonomous recovery when task verification fails during execution.
Requirements:
workflow.node_repair_budget and workflow.node_repairCommand: /gsd-health [--repair]
Purpose: Validate .planning/ directory integrity and auto-repair issues.
Requirements:
--repair flag MUST auto-fix recoverable issuesPurpose: Prevent regressions from compounding across phases by running prior phases' test suites after execution.
Requirements:
When: Runs automatically during /gsd-execute-phase before the verifier step.
Purpose: Ensure all phase requirements are covered by at least one plan before planning completes.
Requirements:
When: Runs automatically at the end of /gsd-plan-phase after the plan checker loop.
Purpose: Prevent context rot by alerting both user and agent when context is running low.
Requirements:
Architecture: Two-part bridge system:
/tmp/claude-ctx-{session}.jsonadditionalContext warningsCommands: /gsd-pause-work, /gsd-resume-work, /gsd-progress
Purpose: Maintain project continuity across context resets and sessions.
Requirements:
continue-here.md and structured HANDOFF.json/clear (context reset)Command: /gsd-session-report
Purpose: Generate a structured post-session summary document capturing work performed, outcomes achieved, and estimated resource usage.
Requirements:
Produces: .planning/reports/SESSION_REPORT.md
Report Sections:
Purpose: Coordinate specialized agents with fresh context windows for each task.
Requirements:
Command: /gsd-set-profile <quality|balanced|budget|inherit>
Purpose: Control which AI model each agent uses, balancing quality vs cost.
Requirements:
quality, balanced, budget, inheritinherit profile MUST defer to runtime's current model selectioninherit profile MUST be used when running non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costsProfile 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 |
Command: /gsd-map-codebase [area]
Purpose: Analyze an existing codebase before starting a new project, so GSD understands what exists.
Requirements:
.planning/codebase//gsd-new-project MUST load codebase mapping and focus questions on what's being added[area] argument MUST scope mapping to a specific areaProduces:
| 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 |
Incremental remap — --paths (#2003): The mapper accepts an optional
--paths <p1,p2,...> scope hint. When provided, it restricts exploration
to the listed repo-relative prefixes instead of scanning the whole tree.
This is the pathway used by the post-execute codebase-drift gate to refresh
only the subtrees the phase actually changed. Each produced document carries
last_mapped_commit in its YAML frontmatter so drift can be measured
against the mapping point, not HEAD.
Introduced by: #2003
Trigger: Runs automatically at the end of every /gsd-execute-phase
Configuration:
workflow.drift_threshold (integer, default 3) — minimum new
structural elements before the gate acts.workflow.drift_action (warn | auto-remap, default warn) —
warn-only or spawn gsd-codebase-mapper with --paths scoped to
affected subtrees.What counts as drift:
(packages|apps)/*/src/index.*routes/ or api/Non-blocking guarantee: any internal failure (missing STRUCTURE.md, git errors, mapper spawn failure) logs a single line and the phase continues. Drift detection cannot fail verification.
Requirements:
git diff --name-status last_mapped_commit..HEADworkflow.drift_thresholdwarn action MUST NOT spawn any agentauto-remap action MUST pass sanitized --paths to the mapper/gsd-execute-phaselast_mapped_commit round-trip through YAML frontmatter
on each .planning/codebase/*.md fileCommand: /gsd-debug [description]
Purpose: Systematic debugging with persistent state across context resets.
Requirements:
.planning/debug/.planning/debug/knowledge-base.mdDebug Session States: gathering → investigating → fixing → verifying → awaiting_human_verify → resolved
Commands: /gsd-add-todo [desc], /gsd-capture --list
Purpose: Capture ideas and tasks during sessions for later work.
Requirements:
.planning/todos/pending/.planning/todos/completed/Command: /gsd-stats
Purpose: Display project metrics — phases, plans, requirements, git history, and timeline.
Requirements:
Command: /gsd-update
Purpose: Update GSD to the latest version with changelog preview.
Requirements:
gsd-local-patches//gsd-update --reapply MUST restore local modifications after updateCommand: /gsd-settings
Purpose: Interactive configuration of workflow toggles and model profile.
Requirements:
.planning/config.json~/.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 |
models.<phase_type> | enum | (none) | Per-phase-type tier override (planning, discuss, research, execution, verification, completion). Values: opus, sonnet, haiku, inherit. Coarse phase-level tuning that wins over model_profile but loses to per-agent model_overrides. See CONFIGURATION.md. Added in v1.40 |
dynamic_routing.enabled | boolean | false | Master switch for failure-tier escalation. When true, agents resolve to tier_models[default_tier] and escalate one tier on orchestrator-detected soft failure. Capped by max_escalations. See CONFIGURATION.md. Added in v1.40 |
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 |
Command: /gsd-add-tests [N]
Purpose: Generate tests for a completed phase based on UAT criteria and implementation.
Requirements:
Purpose: Atomic commits, branching strategies, and clean history management.
Requirements:
type(scope): descriptionnone, phase, milestonecommit_docs setting for .planning/ files.planning/ in .gitignore and skip commitsCommit 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
Purpose: Programmatic utilities for workflows and agents, replacing repetitive inline bash patterns.
Requirements:
init commands that load all context for each workflow--raw flag for machine-readable output--cwd flag for sandboxed subagent operationCommand Categories: State (11 subcommands), Phase (5), Roadmap (3), Verify (8), Template (2), Frontmatter (4), Scaffold (4), Init (12), Validate (2), Progress, Stats, Todo
Purpose: Run GSD across multiple AI coding agent runtimes.
Requirements:
--claude --global) modesRuntime Transformations:
| Aspect | Claude Code | OpenCode | Gemini | Kilo | Codex | Copilot | Antigravity | Trae | Cline | Augment | CodeBuddy | Qwen Code |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Commands | Slash commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills | Skills | Rules | Skills | Skills | Skills |
| Agent format | Claude native | mode: subagent | Claude native | mode: subagent | Skills | Tool mapping | Skills | Skills | Rules | Skills | Skills | Skills |
| Hook events | PostToolUse | N/A | AfterTool | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
| Config | settings.json | opencode.json(c) | settings.json | kilo.json(c) | TOML | Instructions | Config | Config | .clinerules | Config | Config | Config |
Purpose: Runtime event hooks for context monitoring, status display, and update checking.
Requirements:
CLAUDE_CONFIG_DIR env varStatusline Display:
[⬆ /gsd-update │] model │ [current task │] directory [█████░░░░░ 50%]
Color coding: <50% green, <65% yellow, <80% orange, ≥80% red with skull emoji
Update Banner (opt-in, when GSD statusline isn't used):
When the user declines (or keeps a non-GSD) statusline, the installer offers a SessionStart banner that surfaces update availability without occupying statusline real estate. The banner reads ~/.cache/gsd/gsd-update-check.json (written by gsd-check-update-worker.js) and emits one line only when an update is available:
GSD update available: 1.39.0 → 1.40.0. Run /gsd-update.
The banner is silent when up-to-date and rate-limits "check failed" diagnostics to once per 24 hours. Removed cleanly by npx get-shit-done-cc --uninstall or by deleting the SessionStart entry that references gsd-update-banner.js.
Command: /gsd-profile-user [--questionnaire] [--refresh]
Purpose: Analyze Claude Code session history to build behavioral profiles across 8 dimensions, generating artifacts that personalize Claude's responses to the developer's style.
Dimensions:
Generated Artifacts:
USER-PROFILE.md — Full behavioral profile with evidence citations/gsd-dev-preferences command — Load preferences in any sessionCLAUDE.md profile section — Auto-discovered by Claude CodeFlags:
--questionnaire — Interactive questionnaire fallback when session history is unavailable--refresh — Re-analyze sessions and regenerate profilePipeline Modules:
profile-pipeline.cjs — Session scanning, message extraction, samplingprofile-output.cjs — Profile rendering, questionnaire, artifact generationgsd-user-profiler agent — Behavioral analysis from session dataRequirements:
Purpose: Three additive quality improvements to the execution pipeline that catch cross-plan failures before they cascade.
Components:
1. Pre-Wave Dependency Check (execute-phase) Before spawning wave N+1, verify key-links from prior wave artifacts exist and are wired correctly. Catches cross-plan dependency gaps before they cascade into downstream failures.
2. Cross-Plan Data Contracts — Dimension 9 (plan-checker) New analysis dimension that checks plans sharing data pipelines have compatible transformations. Flags when one plan strips data that another plan needs in its original form.
3. Export-Level Spot Check (verify-phase) After Level 3 wiring verification passes, spot-check individual exports for actual usage. Catches dead stores that exist in wired files but are never called.
Requirements:
Command: /gsd-audit-uat
Purpose: Prevent silent loss of UAT/verification items when projects advance past phases with outstanding tests. Surfaces verification debt across all prior phases so items are never forgotten.
Components:
1. Cross-Phase Health Check (progress.md Step 1.6)
Every /gsd-progress call scans ALL phases in the current milestone for outstanding items (pending, skipped, blocked, human_needed). Displays a non-blocking warning section with actionable links.
2. status: partial (verify-work.md, UAT.md)
New UAT status that distinguishes between "session ended" and "all tests resolved". Prevents status: complete when tests are still pending, blocked, or skipped without reason.
3. result: blocked with blocked_by tag (verify-work.md, UAT.md)
New test result type for tests blocked by external dependencies (server, physical device, release build, third-party services). Categorized separately from skipped tests.
4. HUMAN-UAT.md Persistence (execute-phase.md)
When verification returns human_needed, items are persisted as a trackable HUMAN-UAT.md file with status: partial. Feeds into the cross-phase health check and audit systems.
5. Phase Completion Warnings (phase.cjs, transition.md)
phase complete CLI returns verification debt warnings in its JSON output. Transition workflow surfaces outstanding items before confirmation.
Requirements:
/gsd-progressblocked_by tags/gsd-audit-uat MUST scan all phases, categorize items by testability, and produce a human test planCommand: /gsd-fast [task description]
Purpose: Execute trivial tasks inline without spawning subagents or generating PLAN.md files. For tasks too small to justify planning overhead: typo fixes, config changes, small refactors, forgotten commits, simple additions.
Requirements:
.planning/quick/ for state consistencyWhen to use vs /gsd-quick:
/gsd-fast — One-sentence tasks executable in under 2 minutes (typo, config change, small addition)/gsd-quick — Anything needing research, multi-step planning, or verificationCommand: /gsd-review --phase N [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--all]
Purpose: Invoke external AI CLIs (Gemini, Claude, Codex, CodeRabbit, OpenCode, Qwen Code, Cursor) to independently review phase plans. Produces structured REVIEWS.md with per-reviewer feedback.
Requirements:
REVIEWS.md/gsd-plan-phase --reviewsProduces: {phase}-REVIEWS.md — Per-reviewer structured feedback
Commands: /gsd-add-backlog <description>, /gsd-review-backlog, /gsd-plant-seed <idea>
Purpose: Capture ideas that aren't ready for active planning. Backlog items use 999.x numbering to stay outside the active phase sequence. Seeds are forward-looking ideas with trigger conditions that surface automatically at the right milestone.
Requirements:
/gsd-discuss-phase and /gsd-plan-phase work on them/gsd-review-backlog MUST support promote, keep, and remove actions per item/gsd-new-milestone MUST scan seeds and present matchesProduces:
| Artifact | Description |
|---|---|
.planning/phases/999.x-slug/ | Backlog item directory |
.planning/seeds/SEED-NNN-slug.md | Seed with trigger conditions |
Command: /gsd-thread [name | description]
Purpose: Lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. Lighter weight than /gsd-pause-work — no phase state, no plan context.
Requirements:
.planning/threads/ as markdown filesProduces: .planning/threads/{slug}.md — Persistent context thread
Command: /gsd-pr-branch [target branch]
Purpose: Create a clean branch suitable for pull requests by filtering out .planning/ commits. Reviewers see only code changes, not GSD planning artifacts.
Requirements:
.planning/ filesPurpose: Defense-in-depth security for GSD's planning artifacts. Because GSD generates markdown files that become LLM system prompts, user-controlled text flowing into these files is a potential indirect prompt injection vector.
Components:
1. Centralized Security Module (security.cjs)
2. Prompt Injection Guard Hook (gsd-prompt-guard.js)
PreToolUse hook that scans Write/Edit calls targeting .planning/ for injection patterns. Advisory-only — logs detection for awareness without blocking legitimate operations.
3. Workflow Guard Hook (gsd-workflow-guard.js)
PreToolUse hook that detects when Claude attempts file edits outside a GSD workflow context. Advises using /gsd-quick or /gsd-fast instead of direct edits. Configurable via hooks.workflow_guard (default: false).
4. CI-Ready Injection Scanner (prompt-injection-scan.test.cjs)
Test suite that scans all agent, workflow, and command files for embedded injection vectors.
Requirements:
/var → /private/var symlink resolution MUST be handled in path validationPurpose: Auto-detection and project root resolution for monorepos and multi-repo setups. Supports workspaces where .planning/ may need to resolve across repository boundaries.
Requirements:
Purpose: Auto-generate DISCUSSION-LOG.md during /gsd-discuss-phase for full audit trail of decisions made during discussion.
Requirements:
Command: /gsd-forensics [description]
Purpose: Post-mortem investigation of failed or stuck GSD workflows.
Requirements:
.planning/forensics/Produces:
| Artifact | Description |
|---|---|
.planning/forensics/report-{timestamp}.md | Post-mortem investigation report |
Process:
.planning/forensics/Command: /gsd-milestone-summary [version]
Purpose: Generate comprehensive project summary from milestone artifacts for team onboarding.
Requirements:
Produces:
| Artifact | Description |
|---|---|
MILESTONE-SUMMARY.md | Comprehensive navigable summary of milestone artifacts |
Process:
MILESTONE-SUMMARY.md suitable for team onboarding and stakeholder reviewCommand: /gsd-workstreams
Purpose: Parallel workstreams for concurrent work on different milestone areas.
Requirements:
.planning/workstreams/{name}/ directoriesProduces:
| Artifact | Description |
|---|---|
.planning/workstreams/{name}/ | Isolated workstream directory structure |
Process:
.planning/workstreams/{name}/ directoryCommand: /gsd-manager
Purpose: Interactive command center for managing multiple phases from one terminal.
Requirements:
Produces: Interactive terminal output
Process:
Command: /gsd-discuss-phase with workflow.discuss_mode: 'assumptions'
Purpose: Replace interview-style questioning with codebase-first assumption analysis.
Requirements:
Produces:
| Artifact | Description |
|---|---|
{phase}-CONTEXT.md | Same format as default discuss mode |
Process:
{phase}-CONTEXT.md in identical format to default discuss modePart of: /gsd-new-project and /gsd-progress
Purpose: Automatically detect UI-heavy projects and surface /gsd-ui-phase recommendation.
Requirements:
ui_hint when applicable/gsd-ui-phase in next steps for UI-heavy phases/gsd-ui-phase mandatoryProcess:
ui_hint markers to applicable phases in ROADMAP.md/gsd-ui-phase recommendation in next steps for UI-heavy phasesPart of: npx get-shit-done-cc
Purpose: Select multiple runtimes in a single interactive install session.
Requirements:
Process:
Part of: npx get-shit-done-cc
Purpose: Add Windsurf as a supported AI CLI runtime for GSD installation and execution.
Requirements:
Process:
Part of: docs/
Purpose: Provide GSD documentation in Portuguese, Korean, and Japanese.
Requirements:
Process:
Command: Programmatic API (headless)
Purpose: Headless TypeScript SDK for running GSD workflows programmatically without a CLI session.
Requirements:
Process:
Command: Automatic during /gsd-execute-phase
Purpose: Detect when ORM schema files are modified without corresponding migration or push commands, preventing false-positive verification.
Requirements:
GSD_SKIP_SCHEMA_CHECK env var to override detectionProcess:
Config: GSD_SKIP_SCHEMA_CHECK environment variable to bypass detection.
Command: /gsd-secure-phase <N>
Purpose: Threat-model-anchored security verification for phase implementations.
Requirements:
gsd-security-auditor agent for analysisProduces:
| Artifact | Description |
|---|---|
| Security audit report | Threat-model-anchored findings with severity classification |
Process:
gsd-security-auditor to verify against threat modelsecurity_block_on severityConfig:
| Setting | Type | Default | Description |
|---|---|---|---|
security_enforcement | boolean | true | Enable threat-model security verification |
security_asvs_level | number (1-3) | 1 | OWASP ASVS verification level |
security_block_on | string | "high" | Minimum severity to block phase advancement |
Command: /gsd-docs-update
Purpose: Generate and verify project documentation with accuracy checks.
Requirements:
gsd-doc-writer agent to generate documentationgsd-doc-verifier agent to check accuracyProduces:
| Artifact | Description |
|---|---|
| Updated project documentation | Generated and verified documentation files |
Process:
gsd-doc-writer to create or update documentation from implementationgsd-doc-verifier to check documentation accuracy against codebaseFlag: /gsd-discuss-phase <N> --chain
Purpose: Auto-chain discuss, plan, and execute phases in one flow to reduce manual command sequencing.
Requirements:
--chain flag is providedProcess:
Flag: /gsd-autonomous --only N
Purpose: Execute just one phase autonomously instead of all remaining phases.
Requirements:
--only N is providedProcess:
--only N argumentPart of: /gsd-plan-phase
Purpose: Prevent silent requirement dropping during plan generation with three-layer defense.
Requirements:
Process:
Part of: /gsd-plan-phase --research-phase <N>
Purpose: Ensure research claims are tagged with source evidence and assumptions are logged separately.
Requirements:
Process:
Config: workflow.use_worktrees: false
Purpose: Disable git worktree isolation for users who prefer sequential execution.
Requirements:
workflow.use_worktrees setting when deciding isolation strategytrue (worktrees enabled) for backward compatibilityConfig:
| Setting | Type | Default | Description |
|---|---|---|---|
workflow.use_worktrees | boolean | true | When false, disables git worktree isolation |
Config: project_code: "ABC"
Purpose: Prefix phase directory names with a project code for multi-project disambiguation.
Requirements:
ABC-01-setup/)project_code is not setConfig:
| Setting | Type | Default | Description |
|---|---|---|---|
project_code | string | (none) | Prefix for phase directory names |
Part of: npx get-shit-done-cc
Purpose: Migrate GSD commands to Claude Code 2.1.88+ skills format with backward compatibility.
Requirements:
skills/gsd-*/SKILL.md for Claude Code 2.1.88+commands/gsd/ directoryProcess:
skills/gsd-*/SKILL.md files for each GSD commandcommands/gsd/ directory if skills are installedCommands: state validate, state sync [--verify], state planned-phase --phase N --plans N
Purpose: Detect and repair drift between STATE.md and the actual filesystem, preventing cascading errors from stale state.
Requirements:
state validate MUST detect drift between STATE.md fields and filesystem realitystate sync MUST reconstruct STATE.md from actual project state on diskstate sync --verify MUST perform a dry-run showing proposed changes without writingstate planned-phase MUST record the state transition after plan-phase completes (Planned/Ready to execute)Produces:
| Artifact | Description |
|---|---|
Updated STATE.md | Corrected state reflecting filesystem reality |
Process:
--to N FlagFlag: /gsd-autonomous --to N
Purpose: Stop autonomous execution after completing a specific phase, allowing partial autonomous runs.
Requirements:
--to N MUST be combinable with --from N for bounded autonomous rangesProcess:
--to N argumentPart of: /gsd-plan-phase
Purpose: Block planning when RESEARCH.md has unresolved open questions, preventing plans built on incomplete information.
Requirements:
Process:
Part of: /gsd-execute-phase (verifier step)
Purpose: Distinguish between genuine gaps and items deferred to later phases, reducing false negatives in verification.
Requirements:
Process:
Part of: Hooks (PreToolUse)
Purpose: Prevent infinite retry loops in non-Claude runtimes by ensuring files are read before editing.
Requirements:
Part of: GSD SDK prompt assembly
Purpose: Reduce context prompt sizes through markdown truncation and cache-friendly prompt ordering.
Requirements:
description: fields MUST be ≤ 100 chars; enforced by npm run lint:descriptions (see scripts/lint-descriptions.cjs and tests/enh-2789-description-budget.test.cjs)Process:
--power FlagFlag: /gsd-discuss-phase --power
Purpose: File-based bulk question answering for discuss-phase, enabling batch input from a prepared answers file.
Requirements:
--diagnose FlagFlag: /gsd-debug --diagnose
Purpose: Diagnosis-only mode that investigates without attempting fixes.
Requirements:
Command: /gsd-analyze-dependencies
Purpose: Detect phase dependencies and suggest Depends on entries for ROADMAP.md before running /gsd-manager.
Requirements:
Produces: Dependency suggestion table; optionally updates ROADMAP.md Depends on fields
Part of: /gsd-resume-work
Purpose: Mandatory understanding checks at resume with severity-based anti-pattern enforcement.
Requirements:
Part of: Planning artifacts
Purpose: Define consumption mechanisms for methodology documents, ensuring they are consumed correctly by agents.
Requirements:
Part of: /gsd-plan-phase
Purpose: Validate that plan steps are achievable before committing to execution.
Requirements:
Part of: /gsd-verify-work (optional)
Purpose: Automated visual verification using Playwright-MCP during verify-phase.
Requirements:
Part of: /gsd-pause-work
Purpose: Support non-phase contexts with richer handoff data for broader pause-work applicability.
Requirements:
Config: response_language
Purpose: Cross-phase language consistency for non-English users.
Requirements:
response_language setting across all phases and agentsConfig:
| Setting | Type | Default | Description |
|---|---|---|---|
response_language | string | (none) | Language code for agent responses (e.g., "pt", "ko", "ja") |
Part of: docs/manual-update.md
Purpose: Document a manual update path for environments where npx is unavailable or npm publish is experiencing outages.
Requirements:
Part of: npx get-shit-done-cc
Purpose: Extend GSD installation to Trae IDE, Cline, and Augment Code runtimes.
Requirements:
--trae flag for Trae IDE installation.clinerules configuration--interactive FlagFlag: /gsd-autonomous --interactive
Purpose: Lean-context autonomous mode that keeps discuss-phase interactive (user answers questions) while dispatching plan and execute as background agents.
Requirements:
--interactive MUST run discuss-phase inline with interactive questions (not auto-answered)--interactive MUST dispatch plan-phase and execute-phase as background agents for context isolation--interactive MUST enable pipeline parallelism — discuss Phase N+1 while Phase N buildsProcess:
Hook: gsd-commit-docs.js
Purpose: PreToolUse hook that enforces the commit_docs configuration, preventing .planning/ files from being committed when planning.commit_docs is false.
Requirements:
.planning/ files.planning/ files when commit_docs is falsecommit_docs is true or absentHooks: gsd-validate-commit.sh, gsd-session-state.sh, gsd-phase-boundary.sh
Purpose: Optional git and session hooks for GSD projects, gated behind hooks.community: true in config.
Requirements:
hooks.community is true in .planning/config.jsongsd-validate-commit.sh MUST enforce Conventional Commits format on git commit messagesgsd-session-state.sh MUST track session state transitionsgsd-phase-boundary.sh MUST enforce phase boundary checksConfig:
| Setting | Type | Default | Description |
|---|---|---|---|
hooks.community | boolean | false | Enable optional community hooks for commit validation, session state, and phase boundaries |
Commands: Auto-triggered at phase completion; consumed by planner
Config: features.global_learnings
Purpose: Persist cross-session, cross-project learnings in a global store so the planner agent can learn from patterns across the entire project history — not just the current session.
Requirements:
.planning/ to the global store at phase completionlearnings.max_inject to avoid context bloatfeatures.global_learnings: trueConfig:
| Setting | Type | Default | Description |
|---|---|---|---|
features.global_learnings | boolean | false | Enable cross-project learnings pipeline |
learnings.max_inject | number | (system default) | Maximum learnings entries injected into planner |
Command: /gsd-intel [query <term>|status|diff|refresh]
Config: intel.enabled
Purpose: Maintain a queryable JSON index of codebase structure, API surface, dependency graph, file roles, and architecture decisions in .planning/intel/. Enables targeted lookups without reading the entire codebase.
Requirements:
.planning/intel/query mode MUST search across all intel files for a term and group results by filestatus mode MUST report freshness (FRESH/STALE, stale threshold: 24 hours)diff mode MUST compare current intel state to the last snapshotrefresh mode MUST spawn the intel-updater agent to rebuild all filesintel.enabled: trueIntel files produced:
| File | Contents |
|---|---|
stack.json | Technology stack and dependencies |
api-map.json | Exported functions and API surface |
dependency-graph.json | Inter-module dependency relationships |
file-roles.json | Role classification for each source file |
arch-decisions.json | Detected architecture decisions |
Config: context_profile
Purpose: Select a pre-configured execution context (mode, model, workflow settings) tuned for a specific type of work without manually adjusting individual settings.
Requirements:
dev profile MUST optimize for iterative development (balanced model, plan_check enabled)research profile MUST optimize for research-heavy work (higher model tier, research enabled)review profile MUST optimize for code review work (verifier and code_review enabled)Available profiles: dev, research, review
Config:
| Setting | Type | Default | Description |
|---|---|---|---|
context_profile | string | (none) | Execution context preset: dev, research, or review |
References: get-shit-done/references/gates.md
Agents: plan-checker, verifier
Purpose: Define 4 canonical gate types that structure all workflow decision points, enabling plan-checker and verifier agents to apply consistent gate logic.
Gate types:
| Type | Description |
|---|---|
| Confirm | User approves before proceeding (e.g., roadmap review) |
| Quality | Automated quality check must pass (e.g., plan verification loop) |
| Safety | Hard stop on detected risk or policy violation |
| Transition | Phase or milestone boundary acknowledgment |
Requirements:
--auto flagsCommands: /gsd-code-review, /gsd-code-review --fix
Purpose: Structured review of source files changed during a phase, with a separate auto-fix pass that commits each fix atomically.
Requirements:
gsd-code-review MUST scope files to the phase using SUMMARY.md and git diff fallbackquick, standard, deepgsd-code-review --fix MUST read REVIEW.md and fix Critical + Warning findings by default--auto flag MUST enable fix + re-review iteration loop, capped at 3 iterationsworkflow.code_review config flagConfig:
| Setting | Type | Default | Description |
|---|---|---|---|
workflow.code_review | boolean | true | Enable code review commands |
workflow.code_review_depth | string | standard | Default review depth: quick, standard, or deep |
Command: /gsd-explore [topic]
Purpose: Guide a developer through exploring an idea via Socratic probing questions before committing to a plan. Routes outputs to the appropriate GSD artifact: notes, todos, seeds, research questions, requirements updates, or a new phase.
Requirements:
Command: /gsd-undo --last N | --phase NN | --plan NN-MM
Purpose: Roll back GSD phase or plan commits safely using the phase manifest and git log, with dependency checks and a hard confirmation gate before any revert is applied.
Requirements:
--phase mode MUST identify all commits for the phase via manifest and git log fallback--plan mode MUST identify all commits for a specific plan--last N mode MUST display recent GSD commits for interactive selectionCommand: /gsd-import --from <filepath>
Purpose: Ingest an external plan file into the GSD planning system with conflict detection against PROJECT.md decisions, converting it to a valid GSD PLAN.md and validating it through the plan-checker.
Requirements:
gsd-plan-checker validationCommand: /gsd-scan [--focus tech|arch|quality|concerns|tech+arch]
Purpose: Lightweight alternative to /gsd-map-codebase that spawns a single mapper agent for a specific focus area, producing targeted output in .planning/codebase/ without the overhead of 4 parallel agents.
Requirements:
tech, arch, quality, concerns, tech+arch (default).planning/codebase/ in the same format as /gsd-map-codebaseCommand: /gsd-audit-fix [--source <audit>] [--severity high|medium|all] [--max N] [--dry-run]
Purpose: End-to-end pipeline that runs an audit, classifies findings as auto-fixable vs. manual-only, then autonomously fixes auto-fixable issues with test verification and atomic commits.
Requirements:
--dry-run MUST show classification table without applying any fixes--max N MUST limit the number of fixes applied in one run (default: 5)Hook: gsd-prompt-guard.js
Script: scripts/prompt-injection-scan.sh
Purpose: Enhanced detection of prompt injection attempts in planning artifacts, adding invisible Unicode character detection, encoding obfuscation patterns, and entropy-based analysis.
Requirements:
Command: /gsd-plan-phase
Purpose: Detect when the planner revision loop has stalled — producing the same output across multiple iterations — and break the cycle by escalating to a different strategy or exiting with a clear diagnostic.
Requirements:
Command: /gsd-next
Purpose: Prevent /gsd-next from entering runaway loops by adding hard stop safety gates and a consecutive-call guard that interrupts autonomous chaining when repeated identical steps are detected.
Requirements:
/gsd-next MUST track consecutive same-step callsConfig: model_profile: "adaptive"
Purpose: Role-based model assignment that automatically selects the appropriate model tier based on the current agent's role, rather than applying a single tier to all agents.
Requirements:
adaptive preset MUST assign model tiers based on agent role (planner → quality tier, executor → balanced tier, etc.)adaptive MUST be selectable via /gsd-set-profile adaptiveCommand: /gsd-update --reapply
Purpose: After applying local patches post-update, verify that all hunks were actually applied by comparing the expected patch content against the live filesystem. Surface any dropped or partial hunks immediately rather than silently accepting incomplete merges.
Requirements:
Part of: npx get-shit-done-cc
Purpose: Extend GSD installation to Cline, CodeBuddy, and Qwen Code runtimes.
Requirements:
.clinerules to ~/.cline/ (global) or ./.cline/ (local). No custom slash commands — rules-based integration only. Flag: --cline.~/.codebuddy/skills/gsd-*/SKILL.md. Flag: --codebuddy.~/.qwen/skills/gsd-*/SKILL.md, following the open standard used by Claude Code 2.1.88+. QWEN_CONFIG_DIR env var overrides the default path. Flag: --qwen.Runtime summary:
| Runtime | Install Format | Config Path | Flag |
|---|---|---|---|
| Cline | .clinerules | ~/.cline/ or ./.cline/ | --cline |
| CodeBuddy | Skills (SKILL.md) | ~/.codebuddy/skills/ | --codebuddy |
| Qwen Code | Skills (SKILL.md) | ~/.qwen/skills/ | --qwen |
Command: /gsd-from-gsd2 [--dry-run] [--force] [--path <dir>]
Purpose: Migrate a project from GSD-2 format (.gsd/ directory with Milestone→Slice→Task hierarchy) back to the v1 .planning/ format, restoring full compatibility with all GSD v1 commands.
Requirements:
.gsd/ from the specified or current directory.planning/ directory without --force--dry-run MUST preview all changes without writing any filesPROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, and sequential phase directoriesFlags:
| Flag | Description |
|---|---|
--dry-run | Preview migration output without writing files |
--force | Overwrite an existing .planning/ directory |
--path <dir> | Specify the GSD-2 root directory |
Command: /gsd-ai-integration-phase [N]
Purpose: Guide developers through selecting, integrating, and planning evaluation for AI/LLM capabilities in a project phase. Produces a structured AI-SPEC.md that feeds into planning and verification.
Requirements:
{phase}-AI-SPEC.md with framework recommendation, implementation guidance, and evaluation strategyProduces: {phase}-AI-SPEC.md in the phase directory
Command: /gsd-eval-review [N]
Purpose: Retroactively audit an executed AI phase's evaluation coverage against the AI-SPEC.md plan. Identifies gaps between planned and implemented evaluation before the phase is closed.
Requirements:
AI-SPEC.md from the specified phaseEVAL-REVIEW.md MUST be written to the phase directoryProduces: {phase}-EVAL-REVIEW.md with scored eval dimensions, gap analysis, and remediation steps
Command: /gsd-plan-phase N --bounce
Purpose: After plans pass the checker, optionally refine them through an external script (a second AI, a linter, a custom validator). The bounce step backs up each plan, runs the script, validates YAML frontmatter integrity on the result, re-runs the plan checker, and restores the original if anything fails.
Requirements:
--bounce flag or workflow.plan_bounce: true activates the step; --skip-bounce always disables itworkflow.plan_bounce_script must point to a valid executable; missing script produces a warning and skips*-PLAN.pre-bounce.md before the script runsworkflow.plan_bounce_passes (default: 2) controls how many refinement passes the script receivesConfiguration: workflow.plan_bounce, workflow.plan_bounce_script, workflow.plan_bounce_passes
Command: /gsd-ship (enhanced)
Purpose: Before the manual review step in /gsd-ship, automatically run an external code review command if configured. The command receives the diff and phase context via stdin and returns a JSON verdict (APPROVED or REVISE). Falls through to the existing manual review flow regardless of outcome.
Requirements:
workflow.code_review_command must be set to a command string; null means skipBASE_BRANCH with --stat summary includedverdict, confidence, summary, issues fieldsConfiguration: workflow.code_review_command
Command: /gsd-execute-phase N --cross-ai
Purpose: Delegate individual plans to an external AI runtime for execution. Plans with cross_ai: true in their frontmatter (or all plans when --cross-ai is used) are sent to the configured command via stdin. Successfully handled plans are removed from the normal executor queue.
Requirements:
--cross-ai forces all plans through cross-AI; --no-cross-ai disables itworkflow.cross_ai_execution: true and plan frontmatter cross_ai: true required for per-plan activationConfiguration: workflow.cross_ai_execution, workflow.cross_ai_command, workflow.cross_ai_timeout
Command: /gsd-plan-phase (enhanced research step)
Purpose: During phase research, the phase-researcher now maps each capability to its architectural tier owner (browser, frontend server, API, CDN/static, database). The planner cross-references tasks against this map, and the plan-checker enforces tier compliance as Dimension 7c.
Requirements:
Produces: ## Architectural Responsibility Map section in {phase}-RESEARCH.md
Command: /gsd-extract-learnings N
Purpose: Extract structured knowledge from completed phase artifacts. Reads PLAN.md and SUMMARY.md (required) plus VERIFICATION.md, UAT.md, and STATE.md (optional) to produce four categories of learnings: decisions, lessons, patterns, and surprises. Optionally captures each item to an external knowledge base via capture_thought tool.
Requirements:
capture_thought tool is available, captures items with source, project, and phase metadatacapture_thought is unavailable, completes successfully and logs that external capture was skippedLEARNINGS.mdProduces: {phase}-LEARNINGS.md with YAML frontmatter (phase, project, counts per category, missing_artifacts)
Optional integration — capture_thought: capture_thought is a convention, not a bundled tool. GSD does not ship one and does not require one. The workflow checks whether any MCP server in the current session exposes a tool named capture_thought and, if so, calls it once per extracted learning with the signature below. If no such tool is present, the step is skipped silently and LEARNINGS.md remains the primary output.
Expected tool signature:
capture_thought({
category: "decision" | "lesson" | "pattern" | "surprise",
phase: <phase_number>,
content: <learning_text>,
source: <artifact_name>
})
Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style servers, claude-mem, or mem0-style servers) can implement this tool name to have learnings routed into their knowledge base automatically with project, phase, and source metadata. Everyone else can use /gsd-extract-learnings without any extra setup — the LEARNINGS.md artifact is the feature.
Command: gsd-sdk init @prd.md --ws my-workstream
Purpose: Route all SDK .planning/ paths to .planning/workstreams/<name>/, enabling multi-workstream projects without "Project already exists" errors. The --ws flag validates the workstream name and propagates to all subsystems (tools, config, context engine).
Requirements:
--ws <name> routes all .planning/ paths to .planning/workstreams/<name>/--ws, behavior is unchanged (flat mode).planning/config.jsonPurpose: Reduce static prompt overhead by ~40% for models with context windows under 200K tokens. Extended examples and anti-pattern lists are extracted from agent definitions into reference files loaded on demand via @ required_reading.
Requirements:
CONTEXT_WINDOW < 200000, executor and planner agent prompts omit inline examplesreferences/executor-examples.md and references/planner-antipatterns.mdReference files: executor-examples.md, planner-antipatterns.md
Purpose: Allow projects to store their CLAUDE.md in a non-root location. The claude_md_path config key controls where /gsd-profile-user and related commands write the generated CLAUDE.md file.
Requirements:
claude_md_path defaults to ./CLAUDE.mdConfiguration: claude_md_path
Purpose: Opt-in TDD (red-green-refactor) as a first-class phase execution mode. When enabled, the planner aggressively selects type: tdd for eligible tasks and the executor enforces RED/GREEN/REFACTOR gate sequence with fail-fast on unexpected GREEN before RED.
Requirements:
workflow.tdd_mode config key (boolean, default false)references/tdd.md to all eligible tasks (business logic, APIs, validations, algorithms, state machines)type: tdd plans — RED commit (test(...)) must precede GREEN commit (feat(...))## TDD Gate Compliance sectionConfiguration: workflow.tdd_mode
Reference files: tdd.md, checkpoints.md
Command: /gsd-spike [idea] [--quick]
Purpose: Run 2–5 focused feasibility experiments before committing to an implementation approach. Each experiment uses Given/When/Then framing, produces executable code, and returns a VALIDATED / INVALIDATED / PARTIAL verdict. Companion /gsd-spike-wrap-up packages findings into a project-local skill.
Requirements:
.planning/spikes/NNN-experiment-name/ with a README and MANIFEST.md--quick flag skips intake conversation and uses the argument text as the experiment direction/gsd-spike-wrap-up MUST package findings into .claude/skills/spike-findings-[project]/Produces:
| Artifact | Description |
|---|---|
.planning/spikes/NNN-name/README.md | Hypothesis, experiment code, verdict, and evidence |
.planning/spikes/MANIFEST.md | Index of all spikes with verdicts |
.claude/skills/spike-findings-[project]/ | Packaged findings (via /gsd-spike-wrap-up) |
Command: /gsd-sketch [idea] [--quick] [--text]
Purpose: Explore design directions through throwaway HTML mockups before committing to implementation. Produces 2–3 interactive variants per design question, all viewable directly in a browser with no build step. Companion /gsd-sketch-wrap-up packages winning decisions into a project-local skill.
Requirements:
index.html with tab navigationthemes/default.css MUST provide CSS variables adapted to the agreed aesthetic--quick flag skips mood intake; --text flag replaces AskUserQuestion with numbered lists for non-Claude runtimes/gsd-sketch-wrap-up MUST package winning decisions into .claude/skills/sketch-findings-[project]/Produces:
| Artifact | Description |
|---|---|
.planning/sketches/NNN-name/index.html | 2–3 interactive HTML variants |
.planning/sketches/NNN-name/README.md | Design question, variants, winner, what to look for |
.planning/sketches/themes/default.css | Shared CSS theme variables |
.planning/sketches/MANIFEST.md | Index of all sketches with winners |
.claude/skills/sketch-findings-[project]/ | Packaged decisions (via /gsd-sketch-wrap-up) |
Purpose: Keep agent prompt files lean with tiered line-count limits enforced in CI. Oversized agents are caught before they bloat context windows in production.
Requirements:
agents/gsd-*.md files are classified into three tiers: XL (≤ 1 600 lines), Large (≤ 1 000 lines), Default (≤ 500 lines)size: xl | large | default)tests/agent-size-budget.test.cjs enforces limits and fails CI on violationsize frontmatter key default to the Default (500-line) limitTest file: tests/agent-size-budget.test.cjs
Purpose: Reduce duplication across agents by extracting two common boilerplate blocks into shared reference files loaded on demand. Keeps agent files within size budget and makes boilerplate updates a single-file change.
Requirements:
references/mandatory-initial-read.mdreferences/project-skills-discovery.md@ required_readingReference files: references/mandatory-initial-read.md, references/project-skills-discovery.md
Purpose: Build, query, and inspect a lightweight knowledge graph of the project in .planning/graphs/. Opt-in per project. Exposed as the /gsd-graphify user-facing command and the gsd-tools.cjs graphify … programmatic verb family. Complements /gsd-intel (snapshot-oriented) with a graph-oriented view of nodes and edges across commands, agents, workflows, and phases.
Requirements:
graphify.enabled: true in .planning/config.json. When disabled, /gsd-graphify prints an activation hint and stops without writing./gsd-graphify exposes subcommands build, query <term>, status, diff. The programmatic CLI node gsd-tools.cjs graphify … additionally exposes snapshot, which is also invoked automatically as the final step of graphify build.graphify.build_timeout (seconds); exceeding the timeout aborts cleanly without leaving a partial graph.graphify.cjs falls back to graph.links when graph.edges is absent so older graph artifacts keep rendering.gsd-sdk query does not yet register graphify handlers.Configuration: graphify.enabled, graphify.build_timeout
Reference files: commands/gsd/graphify.md, bin/lib/graphify.cjs