GSD (Get Shit Done) — Admin & Developer Guide

This guide is the source-based reference for the architecture, configuration, deployment, security, and internals of GSD (get-shit-done-cc) — a meta-prompting, context-engineering, and spec-driven development system for AI coding agents, authored by TÂCHES and licensed MIT. It is written for the people who operate, extend, debug, or fork GSD: administrators rolling it out across a team's runtimes, developers contributing to the SDK, and architects evaluating how the system holds together.

For task-oriented usage (the slash commands and the phase workflow), see the companion User Guide. This document assumes that material and goes one level deeper.

Important

Archived repository. This guide documents gsd-build/get-shit-done at commit bdcaab2 (version 1.50.0-canary.0), which is now archived. Development continues as GSD Core at github.com/open-gsd/gsd-core. Every fact below is derived from the source at the documented commit. Where the source itself carries transitional naming (the get-shit-done-cc package vs. the @opengsd/get-shit-done-redux package referenced in the bundled docs), both are reported.

Table of Contents

1. Executive Summary
2. System Architecture
3. The Layered Model
4. Agent Orchestration Model
5. The SDK & CLI Tools Layer
6. Requirements & Runtime Support
7. Installation & Deployment
8. Configuration Mastery
9. Filesystem Layout
10. Hook System
11. Security Architecture
12. Operations & Maintenance
13. Versioning & Release Strategy
14. Repository Structure & Internals
15. Testing Strategy
16. Code Quality & Conventions
17. Known Issues & Improvement Areas
18. Quick Reference

Executive Summary

GSD sits between a developer and an AI coding agent and imposes structure on what would otherwise be an unstructured chat. It ships four capabilities:

1. Context engineering — structured .planning/ artifacts give each agent exactly what it needs per task.
2. Multi-agent orchestration — thin Markdown orchestrators spawn ~33 specialized agents, each in a fresh context window.
3. Spec-driven development — a requirements → research → plan → execute → verify pipeline.
4. File-based state management — all state is human-readable Markdown/JSON; no database, server, or external dependency.

Surface area at the documented commit: 67 slash commands, 33 agents, ~90 workflow files, 13 hooks (11 canonical in the shipped roster), a TypeScript SDK (@gsd-build/sdk), and a CJS CLI (gsd-tools.cjs). The installer (bin/install.js, ~485 KB / ~10,700 lines, generated) targets 15 AI runtimes.

Runtime dependencies are deliberately minimal: @anthropic-ai/claude-agent-sdk and ws, plus synckit in the SDK and an optional fallow integration. Node >= 22 is required.

Note

GSD never calls an LLM API directly. It produces prompts and orchestration instructions that the host runtime (Claude Code, Codex, etc.) executes. This is why GSD has no API-key requirement of its own and why "model selection" is really about which tier the host should use for each agent.

System Architecture

┌──────────────────────────────────────────────────────┐
│                       USER                           │
│               /gsd-command [args]                    │
└────────────────────────┬─────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────┐
│   COMMAND LAYER   commands/gsd/*.md (67 commands)     │
│   Prompt-based command files / skills per runtime     │
└────────────────────────┬─────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────┐
│   WORKFLOW LAYER   get-shit-done/workflows/*.md       │
│   Thin orchestrators: load context, spawn agents,     │
│   manage gates, update state                          │
└──────┬─────────────────┬──────────────────┬──────────┘
       │                 │                  │
┌──────▼─────┐    ┌──────▼─────┐     ┌──────▼─────┐
│  AGENT     │    │  AGENT     │     │  AGENT     │   33 agents,
│ (fresh ctx)│    │ (fresh ctx)│     │ (fresh ctx)│   fresh 200K–1M
└──────┬─────┘    └──────┬─────┘     └──────┬─────┘   windows each
       │                 │                  │
┌──────▼─────────────────▼──────────────────▼──────────┐
│   CLI TOOLS LAYER                                     │
│   gsd-sdk query (sdk/src/query) + gsd-tools.cjs       │
│   Bridged by query-runtime-bridge.ts (GSDTools)       │
└────────────────────────┬─────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────┐
│   FILE SYSTEM  .planning/                             │
│   PROJECT.md | REQUIREMENTS.md | ROADMAP.md           │
│   STATE.md | config.json | phases/ | research/        │
└──────────────────────────────────────────────────────┘

Design principles

The Layered Model

Command layer — commands/gsd/*.md

User-facing entry points. Each file has YAML frontmatter (name, description, allowed-tools, argument-hint) and a prompt body that bootstraps a workflow. The installer materializes these per runtime (Claude slash commands, Codex skills, Gemini colon-namespaced commands, etc.).

Two-stage hierarchical routing (v1.40). Six namespace meta-skills (gsd-workflow, gsd-project, gsd-quality, gsd-context, gsd-manage, gsd-ideate, sourced from commands/gsd/ns-*.md) sit above the concrete commands. The model sees ~6 routers (~120 tokens) instead of a flat ~86-skill listing (~2,150 tokens), selects a namespace, then routes to the concrete sub-skill. Namespace skills are additive — every concrete command remains directly invocable.

Note

Skill description: fields are injected into every session's system prompt, so they are budget-constrained to ≤ 100 chars and lint-enforced by npm run lint:descriptions (and tests/enh-2789-description-budget.test.cjs). This is why descriptions read like keyword-dense tags rather than prose.

Workflow layer — get-shit-done/workflows/*.md

Orchestration logic that commands reference. Workflows load context via gsd-sdk query init.<workflow>, spawn agents with resolved models, enforce gates/checkpoints, update state, and handle recovery.

Workflow files are loaded verbatim into the host context on each invocation, so they carry a line budget (enforced by tests/workflow-size-budget.test.cjs):

When a workflow exceeds its tier, per-mode bodies are extracted to workflows/<workflow>/modes/<mode>.md, templates to workflows/<workflow>/templates/, and shared knowledge to get-shit-done/references/. The canonical example is workflows/discuss-phase/ (held to a stricter < 500-line ceiling), whose parent dispatches to mode files (power.md, all.md, auto.md, chain.md, text.md, batch.md, analyze.md, default.md, advisor.md).

Agent layer — agents/*.md

33 specialized agent definitions. Frontmatter declares name, description, tools (allowed tool access), and color. See Agent Orchestration Model.

References & templates

• get-shit-done/references/*.md — shared knowledge @-referenced by workflows and agents: gates.md (4 canonical gate types), model-profiles.md, model-profile-resolution.md, verification-patterns.md, tdd.md, context-budget.md, the thinking-models-*.md family, and more.
• get-shit-done/templates/ — Markdown templates for every planning artifact (project.md, roadmap.md, state.md, phase-prompt.md, granularity-aware summary*.md, UI-SPEC.md, UAT.md, VALIDATION.md, plus codebase/ and research-project/ subtrees), filled by gsd-sdk query template.fill / phase.scaffold.

Agent Orchestration Model

Orchestrator → agent pattern

Orchestrator (workflow .md)
   │
   ├── Load context:  gsd-sdk query init.<workflow> <phase>   → JSON (project, config, state, phase)
   ├── Resolve model: gsd-sdk query resolve-model <agent>     → opus | sonnet | haiku | inherit
   ├── Spawn agent (Task/SubAgent): prompt + context payload + model + tool permissions
   ├── Collect result
   └── Update state:  gsd-sdk query state.update / state.patch / state.advance-plan

Agent categories

Wave execution model

During execute-phase, plans are grouped into dependency waves:

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 receives a fresh 200K window (or up to 1M), the specific PLAN.md, project context (PROJECT.md, STATE.md), and phase context (CONTEXT.md, RESEARCH.md).

Adaptive context enrichment (1M models). When context_window >= 500000, executor prompts are enriched with prior-wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md; verifier prompts receive all PLAN.md/SUMMARY.md/CONTEXT.md plus REQUIREMENTS.md. For standard 200K windows, prompts use truncated, cache-friendly ordering.

Parallel commit safety

Two mechanisms prevent corruption when multiple executors run in one wave:

1. --no-verify commits — parallel agents skip pre-commit hooks (which can cause build-lock contention, e.g. cargo lock fights). The orchestrator runs git hook run pre-commit once after each wave.
2. STATE.md file locking — all writeStateMd() calls use lockfile mutual exclusion (STATE.md.lock, O_EXCL atomic creation, 10s stale detection, spin-wait with jitter), preventing read-modify-write races between agents.

Warning

If your pre-commit hooks must run on every commit, set parallelization.enabled: false. Otherwise, hooks validate once per wave against the merged result, and per-commit hook side effects will not fire on intermediate commits.

The SDK & CLI Tools Layer

GSD has a dual command surface: a modern TypeScript SDK (@gsd-build/sdk, invoked as gsd-sdk query) and a legacy CJS CLI (gsd-tools.cjs). They are converging — CJS family routers increasingly dispatch into the SDK in-process.

SDK structure (sdk/src/)

The SDK's heart is the query engine (sdk/src/query/, 192 files, ~1.68M chars) — a registry of native query handlers covering init.*, state.*, phase.*, phases.*, roadmap.*, config.*, frontmatter.*, validate.*, milestone.*, and more. Key classes (from sdk/src/):

Sync Runtime Bridge

sdk/src/runtime-bridge-sync/ exposes executeForCjs(input) — a synchronous-friendly entry point on top of the async bridge, letting the CJS dispatcher invoke SDK handlers in-process (no subprocess hop) while preserving the synchronous contract ~21 CJS test files and 100+ consumers depend on. It uses synckit (Atomics.wait on a SharedArrayBuffer in a pooled worker). First-call cost ~80ms (worker startup); steady-state ~0.1ms per call. It maps exceptions to a typed sync result aligned with the dispatch error taxonomy.

Command Routing Hub

get-shit-done/bin/lib/command-routing-hub.cjs centralizes three cross-cutting concerns that each CJS family router previously duplicated: (1) mode selection (sdk when tryLoadSdk() succeeds and no GSD_WORKSTREAM is active, else cjs), fixed at construction; (2) a no-throw pure-result contract (hub.dispatch() returns { ok: false, errorKind, message, details } instead of throwing); and (3) a closed six-value errorKind enum (UnknownCommand, InvalidArgs, HandlerRefusal, HandlerFailure, SdkLoadFailed, SdkDispatchFailed). There is no transparent SDK→CJS fallback: an SDK-mode hub that fails returns SdkLoadFailed/SdkDispatchFailed. phase-command-router.cjs is the first migration (issue #3788); ADR docs/adr/0012-command-routing-hub.md.

Dispatch error taxonomy (ADR-0001)

The canonical error kind set used across dispatch policy: unknown_command, native_failure, native_timeout, fallback_failure, validation_error, internal_error.

Shared CJS/SDK modules (generator pattern)

Several modules exist as a single TypeScript source of truth that is generated into a CJS twin, with check:*-fresh scripts guarding drift in CI: state-document (STATE.md transforms), configuration (config load/normalize/merge/migrate), workstream-inventory-builder, project-root (ancestor-walk root resolution, max depth 10), plan-scan, secrets, schema-detect, decisions, and workstream-name-policy. This structurally eliminates the recurring CJS/SDK drift bug class.

Tip

For automation, prefer gsd-sdk query <subcommand> over gsd-tools.cjs. A few operations remain CJS-only (e.g. graphify, gsd2-import, and the state load shape). The --json-errors mode yields machine-readable failure envelopes (see docs/json-errors.md).

Requirements & Runtime Support

System requirements

Supported runtimes (15)

claude, antigravity, augment, cline, codebuddy, codex, copilot, cursor, gemini, hermes, kilo, opencode, qwen, trae, windsurf.

Runtime install contract matrix

Each runtime also accepts a <RUNTIME>_CONFIG_DIR environment variable to redirect the install path (used for prerelease channels and custom layouts).

Installation & Deployment

Installer architecture (bin/install.js)

The installer is a single generated production file (~485 KB, ~10,700 lines) that handles:

1. Runtime detection — interactive prompt or CLI flags (--claude, --codex, … --all).
2. Location selection — --global or --local.
3. File deployment — copies commands, skills, workflows, references, templates, agents, hooks.
4. Runtime adaptation — transforms file content per runtime: tool-name mapping (Claude Bash → Copilot execute), hook-event renaming (PostToolUse → Gemini AfterTool), command-format conversion (OpenCode flat commands, Codex TOML + skills, Gemini colon namespacing, Cline .clinerules), model-equivalent substitution.
5. Path normalization — replaces ~/.claude/ paths with runtime-specific paths.
6. Settings integration — registers hooks in the runtime's settings.json.
7. Patch backup — backs up locally modified files to gsd-local-patches/ (since v1.17) for /gsd-update --reapply.
8. Manifest tracking — writes gsd-file-manifest.json for clean uninstall.
9. Uninstall — --uninstall removes all GSD files, hooks, and settings.

Install-time file moves, stale-artifact cleanup, config rewrites, and user-data preservation are governed by the Installer Migration Module (ADR-0008; docs/installer-migrations.md), which also runs a gated first-time baseline scan for legacy installs before any migration removes or rewrites anything.

Install profiles & surface budgets

get-shit-done/bin/lib/install-profiles.cjs defines named profiles (core, standard, full), computes the transitive closure over each skill's requires: frontmatter, stages the chosen subset to the runtime config dir, and persists the choice in a .gsd-profile marker. Resolution precedence: explicit --profile= > .gsd-profile marker > full. --minimal/--core-only are back-compat aliases for --profile=core. At runtime, /gsd-surface (backed by surface.cjs + clusters.cjs) enables/disables clusters without reinstall, persisting per-runtime state in .gsd-surface.json. See ADR-0011.

Platform handling

Deployment notes for administrators

• Global vs local. --global writes to the runtime's home config and applies to every project; --local writes to the project directory only. Prefer local for repo-pinned, reproducible toolchains.
• gsd-sdk PATH callability. npx-based installs self-symlink the gsd-sdk shim into ~/.local/bin when needed and verify PATH callability before reporting readiness (issue #2775).
• Uninstall is one pass. npx get-shit-done-cc --uninstall removes scripts, hook registrations, and the update-banner SessionStart entry together.

Configuration Mastery

All project settings live in .planning/config.json, created by /gsd-new-project and edited via /gsd-settings or /gsd-config. Configuration loading is pure (loadConfig(cwd) never writes disk); legacy keys are normalized into their canonical nested locations; defaults come from sdk/shared/config-defaults.manifest.json and the schema from sdk/shared/config-schema.manifest.json.

Full schema (defaults shown)

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "model_overrides": {},
  "models": {},
  "dynamic_routing": null,
  "planning": { "commit_docs": true, "search_gitignored": false, "sub_repos": [] },
  "context": null,
  "workflow": {
    "research": true, "plan_check": true, "verifier": true, "auto_advance": false,
    "nyquist_validation": true, "ui_phase": true, "ui_safety_gate": true, "ui_review": true,
    "node_repair": true, "node_repair_budget": 2, "research_before_questions": false,
    "discuss_mode": "discuss", "max_discuss_passes": 3, "skip_discuss": false,
    "human_verify_mode": "end-of-phase", "tdd_mode": false, "text_mode": false,
    "use_worktrees": true, "code_review": true, "code_review_depth": "standard",
    "plan_bounce": false, "plan_bounce_script": null, "plan_bounce_passes": 2,
    "plan_chunked": false, "code_review_command": null,
    "cross_ai_execution": false, "cross_ai_command": null, "cross_ai_timeout": 300,
    "security_enforcement": true, "security_asvs_level": 1, "security_block_on": "high",
    "post_planning_gaps": true, "build_command": null, "test_command": null
  },
  "code_quality": { "fallow": { "enabled": false, "scope": "phase", "profile": "standard", "mcp": false } },
  "ship": { "pr_body_sections": [] },
  "hooks": { "context_warnings": true, "workflow_guard": false },
  "statusline": { "context_position": "end" },
  "review": { "default_reviewers": null, "models": {} },
  "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", "create_tag": true,
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}", "quick_branch_template": null
  },
  "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 },
  "project_code": null, "agent_skills": {}, "response_language": null,
  "features": { "thinking_partner": false, "global_learnings": false },
  "learnings": { "max_inject": 10 },
  "intel": { "enabled": false },
  "claude_md_path": "./CLAUDE.md"
}

Core settings

Model selection layers (precedence)

From highest to lowest: model_overrides.<agent> > models.<phase_type> > model_profile. When dynamic_routing.enabled is true, agents start at tier_models[default_tier] and escalate one tier on orchestrator-detected soft failure (capped by max_escalations, default 1). For non-Claude runtimes the installer sets resolve_model_ids: "omit" so the runtime picks its own model; model_profile_overrides.<runtime>.<tier> overrides the runtime-aware tier mapping.

Workflow toggles (absent = enabled)

Key toggles (all default true unless noted):

Other namespaces

• planning.* — commit_docs (auto-false if .planning/ is gitignored), search_gitignored, sub_repos (multi-repo project-root resolution; walks ancestors up to depth 10).
• parallelization.* — enabled, max_concurrent_agents (3), min_plans_for_parallel (2), task_level (false).
• git.* — branching_strategy (none/phase/milestone), base_branch (main), create_tag, branch templates.
• gates.* / safety.* — interactive confirmation gates; always_confirm_destructive/always_confirm_external_services default true.
• features.* — thinking_partner, global_learnings (cross-project learnings pipeline). The namespace is a dynamic key pattern; new flags need no schema change.
• intel.enabled, graphify.enabled/build_timeout/auto_update — queryable codebase intel and the knowledge-graph integration (.planning/intel/, .planning/graphs/).
• code_quality.fallow.* — optional structural pre-pass for /gsd-code-review (enabled, scope, profile; mcp is reserved/no-op).
• agent_skills.<agent> — inject project-local SKILL.md files into a given agent's prompt (path-validated, no traversal).
• Integration keys — brave_search, firecrawl, exa_search (masked as ****<last-4> in all output by secrets.cjs; plaintext only on disk), and review.models.<cli> for cross-AI review routing.

Caution

API keys written to .planning/config.json are stored in plaintext — that file is the security boundary. The CLI, logs, and confirmation tables mask them, but if you commit .planning/ to git, you commit those keys. Keep keys in env vars / ~/.gsd/*_api_key files, or set planning.commit_docs: false.

Setting config programmatically

gsd-sdk query config-set features.global_learnings true
gsd-sdk query config-set review.default_reviewers '["gemini","codex"]'
gsd-sdk query config-set agent_skills.gsd-executor '["skills/testing-standards"]'

Filesystem Layout

Installed files (Claude Code global)

~/.claude/
├── skills/gsd-*/SKILL.md        # Global skills
├── commands/gsd/*.md            # (local installs use slash commands)
├── get-shit-done/
│   ├── bin/gsd-tools.cjs        # CJS CLI
│   ├── bin/lib/*.cjs            # Domain modules
│   ├── workflows/*.md           # Orchestration logic
│   ├── references/*.md          # Shared knowledge
│   └── templates/               # Artifact templates
├── agents/*.md                  # 33 agent definitions
├── hooks/*.js, hooks/*.sh       # Runtime hooks
├── settings.json                # Hook registrations
└── VERSION                      # Installed version

Project state (.planning/)

.planning/
├── PROJECT.md            # Vision, constraints, decisions, evolution rules
├── REQUIREMENTS.md       # Scoped requirements (v1/v2/out-of-scope), REQ-IDs
├── ROADMAP.md            # Phase breakdown + status
├── STATE.md              # Living memory (+ YAML frontmatter for the statusline)
├── config.json           # Workflow configuration
├── MILESTONES.md         # Completed-milestone archive
├── research/             # New-project research (SUMMARY/STACK/FEATURES/ARCHITECTURE/PITFALLS)
├── codebase/             # Brownfield mapping (frontmatter carries last_mapped_commit)
├── phases/XX-name/
│   ├── XX-CONTEXT.md  XX-RESEARCH.md  XX-YY-PLAN.md  XX-YY-SUMMARY.md
│   ├── XX-VERIFICATION.md  XX-VALIDATION.md  XX-UI-SPEC.md  XX-UI-REVIEW.md  XX-UAT.md
├── quick/  todos/{pending,done}/  threads/  seeds/  debug/{,resolved}/
├── spikes/  sketches/  intel/  graphs/  ui-reviews/  forensics/  reports/
└── continue-here.md      # Context handoff (from pause-work)

Data-flow summary

PROJECT.md ───────────────────► all agents
REQUIREMENTS.md ──────────────► planner, verifier, auditor
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

Note

The post-execute codebase-drift gate (#2003) compares last_mapped_commit..HEAD against .planning/codebase/STRUCTURE.md, counting new directories, barrel exports, migrations, and route modules. At/above workflow.drift_threshold (3) it either warns or auto-remaps. It is non-blocking — any error is logged and the phase continues.

Hook System

Hooks integrate GSD with the host runtime's event model. The shipped canonical roster is 11 hooks.

The repository also ships gsd-graphify-update.sh (detached graph rebuild after HEAD-advancing git ops when graphify.auto_update=true) and gsd-update-banner.js (opt-in SessionStart update banner).

Context-monitor thresholds

Debounce: 5 tool uses between repeats; severity escalation bypasses debounce.

Safety properties

All hooks wrap in try/catch and exit silently on error; a 3s stdin timeout guard prevents hangs; metrics older than 60s are ignored; missing bridge files are handled gracefully; the context monitor is advisory and never issues imperative overrides. Community hooks (gsd-validate-commit.sh, gsd-session-state.sh, gsd-phase-boundary.sh) are no-ops unless hooks.community: true.

Security Architecture

GSD's threat model recognizes that generated Markdown becomes LLM system-prompt input, so user-controlled text is an indirect-prompt-injection vector, and that an automated research → plan → execute pipeline can carry a hallucinated package all the way to npm install.

Defense-in-depth (v1.27)

• Path-traversal prevention — --text-file/--prd paths are validated to resolve inside the project directory (macOS /var → /private/var symlink handling included).
• Prompt-injection detection — security.cjs scans user-supplied text for role overrides, instruction bypasses, and system-tag injection before it enters planning artifacts.
• Runtime hooks — gsd-prompt-guard.js (always on, advisory) and gsd-workflow-guard.js (opt-in).
• CI scanner — prompt-injection-scan.test.cjs scans all agent/workflow/command files for embedded injection vectors; adversarial fixtures live under tests/fixtures/adversarial/{frontmatter,roadmap,security}/.

Package-legitimacy gate (v1.42.1, anti-slopsquatting)

slopcheck (MIT, pip-installable) checks npm/PyPI/crates.io/RubyGems/Go/Maven/Packagist using registry age, download count, source-repo linkage, and naming distance. WebSearch-sourced names are always tagged [ASSUMED]. If slopcheck is unavailable, every package is [ASSUMED] and gated — the system never silently degrades to pre-v1.42.1 behavior.

Vulnerability reporting

Per SECURITY.md: do not file public issues. Acknowledgment within 48 hours; initial assessment within 1 week; fix targets — Critical 24–48h, High 1 week, Medium/Low next release. In-scope issues are arbitrary code execution, secret/credential exposure, and compromise of generated plan/code integrity.

Operations & Maintenance

Health & integrity

/gsd-health                  # Validate .planning/ integrity
/gsd-health --repair         # Auto-fix recoverable issues
/gsd-health --context        # Probe context-window utilization (warn 60% / critical 70%)
node gsd-tools.cjs state validate     # Detect STATE.md drift
node gsd-tools.cjs state sync         # Reconstruct STATE.md from disk

Diagnostics

/gsd-forensics "<problem>"   # Post-mortem: git anomalies, artifact integrity, state inconsistencies
/gsd-stats                   # Project metrics

Executor stall detection

The execute-phase orchestrator inspects recent commits on a cadence to avoid waiting forever on a silent agent: executor.stall_detect_interval_minutes (default 5) and executor.stall_threshold_minutes (default 10). Background execute-phase runs emit [checkpoint] markers at every wave/plan boundary so the SSE stream never idles into a timeout; grep the transcript for [checkpoint] to find the last confirmed boundary after a partial failure.

Backup, update, rollback

• Local-patch backup — modified GSD files are backed up to gsd-local-patches/; restore with /gsd-update --reapply.
• Manual update — if npm is unreachable, follow docs/manual-update.md.
• Uninstall — npx get-shit-done-cc --uninstall removes files, hooks, and settings in one pass.

Versioning & Release Strategy

GSD follows SemVer 2.0.0 with three tiers mapped to two npm dist-tags.

Only two dist-tags exist: latest (stable) and next (opt-in pre-release). Users never receive pre-releases unless they explicitly request @next. Pre-release progression uses -rc.N for minors and -beta.N for majors. Branch types map to Conventional Commits: fix/ → PATCH, feat/ → MINOR, chore//docs//refactor/ → none. A separate canary stream publishes dev cuts under @canary (the documented version is 1.50.0-canary.0; see docs/CANARY.md).

Note

Release automation lives in GitHub Actions workflows (release.yml, hotfix.yml, release-sdk.yml). Hotfixes branch from the highest prior patch tag and auto-cherry-pick only fix:/chore: commits (never feat:/refactor:), gated by install-smoke cross-platform checks before publishing.

Repository Structure & Internals

get-shit-done/
├── bin/                  install.js (generated), gsd-sdk.js, gsd-tools shim, lib/
├── commands/gsd/         67 slash-command definitions
├── agents/               33 agent definitions
├── get-shit-done/
│   ├── bin/lib/          ~33 CJS domain modules (state, phase, roadmap, config, …)
│   ├── workflows/        ~90 orchestration files (+ modes/, templates/)
│   ├── references/       shared knowledge docs
│   ├── templates/        planning-artifact templates
│   └── contexts/         curated context bundles
├── hooks/                11 canonical hooks (+ lib/)
├── scripts/              lint/build/changeset/test tooling (.cjs)
├── sdk/
│   ├── src/              TypeScript SDK (CLI, query engine, runtime bridge, configuration, …)
│   ├── shared/           config-defaults/-schema manifests (CJS/SDK source of truth)
│   └── prompts/          SDK prompt templates
├── docs/                 ARCHITECTURE, COMMANDS, CONFIGURATION, USER-GUIDE, FEATURES, ADRs, i18n
├── tests/                vitest (SDK) + node CJS suites; adversarial fixtures
└── package.json          name: get-shit-done-cc, bin: get-shit-done-cc / gsd-sdk / gsd-tools

Key CJS domain modules (get-shit-done/bin/lib/)

Important

Several bin/lib/*.cjs files are generated from TypeScript sources (*.generated.cjs, with thin re-export wrappers). Do not hand-edit them — edit the SDK source and regenerate. The check:*-fresh npm scripts fail CI if a generated file drifts from its source.

Testing Strategy

Tests run through node scripts/run-tests.cjs, which exposes suites: unit, integration, install, security, and slow. The SDK uses vitest (vitest.config.ts, projects unit and integration). Coverage is enforced via c8 (--check-coverage --lines 70) on get-shit-done/bin/lib/*.cjs.

A family of lint gates guards systemic quality: lint:descriptions (≤ 100-char skill descriptions), lint:skill-deps, lint:tests (no source-grep in tests), lint:test-file-count, lint:docs, lint:changeset, plus drift guards (check:*-fresh, check:alias-drift). The adversarial corpora (tests/fixtures/adversarial/{frontmatter,roadmap,security}/) feed parser- and injection-hardening tests so the corpus can grow without test-code changes.

Code Quality & Conventions

• Generator pattern for shared logic. Single TypeScript source → generated CJS twin, drift-guarded in CI. This structurally eliminates CJS/SDK divergence (the #3523 bug class).
• Module-as-seam architecture. CONTEXT.md documents the codebase as a glossary of named modules with explicit seams (Dispatch Pipeline, Command Topology, Configuration, Project-Root Resolution, Workstream Inventory, Worktree Safety, etc.), each with a source-of-truth file and typed contracts. Agent briefs cite predicate IDs verbatim rather than paraphrasing.
• No-throw dispatch contract. The Command Routing Hub and Sync Runtime Bridge return typed result objects rather than throwing, with a closed errorKind enum.
• Conventional Commits drive versioning; ADRs under docs/adr/ record architectural decisions (e.g. ADR-0001 error taxonomy, ADR-0008 installer migrations, ADR-0011 surface budgets, ADR-0012 routing hub, ADR-3660 runtime artifact layout).
• Progressive disclosure budgets (workflow line tiers, agent ≤ 50K-char limits handled by reference-module decomposition) keep per-turn token cost bounded.

Tip

When extending GSD, the highest-leverage rule is: add a query handler in sdk/src/query/ rather than new CJS logic, then let the CJS surface route through it via the Sync Runtime Bridge / Command Routing Hub. This keeps the dual surface convergent instead of duplicating handlers.

Known Issues & Improvement Areas

These are drawn from the repository's own issue tracker (all community issues at the documented commit were CLOSED) and source observations. They are useful context for anyone forking or operating GSD.

• Namespace migration (colon → hyphen). A long tail of issues (#3862, #3865, #3868, #3873, #3874) tracked stale /gsd:cmd colon references in workflow templates, completion messages, and shell hooks after the hyphen-form migration. Verify any custom templates use the hyphen form (except Gemini, which uses colon).
• gsd-surface no-op on 1.42.3 (#3879). The surface fix merged to main but was not released to npm on that version — a reminder to validate that /gsd-surface actually toggles on your installed version.
• Read-injection scanner vs extended thinking (#3878). The gsd-read-injection-scanner PostToolUse hook could crash extended-thinking sessions with a 400 "thinking blocks cannot be modified". Confirm hook compatibility with your runtime's thinking mode.
• STATE.md milestone counter corruption (#3880, #3881, #3866). Several edge cases where state planned-phase / state.complete-phase stomped milestone progress counters. If milestone progress looks wrong, run state validate then state sync.
• Codex CLI version floor. Codex < 0.130.0 discovers GSD skills from alternate roots and can show duplicate listings; >= 0.130.0 is the supported floor.
• code_quality.fallow.mcp is reserved and currently a no-op (emits a runtime warning if set true).
• Generated-file discipline. Because bin/lib/*.generated.cjs files are machine-emitted, contributors must regenerate rather than hand-edit; the check:*-fresh gates exist precisely because this is easy to get wrong.

Quick Reference

CLI entry points

Operational commands

Key facts