msd-core/docs/README.md

GSD Core documentation

Documentation is organised into four quadrants: tutorials help you learn by doing, how-to guides solve specific tasks, reference states authoritative facts, and explanation explores concepts and design decisions.

Language versions: English · Português (pt-BR) · 日本語 · 简体中文

---

Tutorials

• Your first project — install to first shipped phase, one guaranteed path
• Onboarding an existing codebase — bring GSD Core to a brownfield repo
• Build your first capability — author a tiny declarative capability and watch it act in the loop
• Install your first capability — install a third-party capability end-to-end: consent, verify, check for updates, remove

---

How-to guides

• Install on your runtime — runtime-specific install steps for all 16 supported runtimes
• Install a minimal GSD and add skills later — install only the core skills, then grow the surface with profiles and /gsd:surface
• Attach a plugin-provided skill to a GSD agent — use the global:plugin:skill entry form to load Claude Code plugin skills into agent prompts
• Discuss a phase — capture implementation decisions before planning begins
• Resolve edge-coverage findings — turn the spec phase's surfaced domain-boundary edges into covered, dismissed, or backstopped spec decisions
• Resolve prohibition findings — turn the spec phase's surfaced must-NOT constraints into resolved, dismissed, or deferred spec decisions
• Plan a phase — run research, decompose work, and verify plan quality
• Execute a phase — run plans in parallel waves with fresh-context subagents
• Verify and ship — walk through completed work, diagnose failures, and create the PR
• Run phases autonomously — use autonomous mode for unattended phase execution
• Handle quick and fast tasks — use /gsd-quick and /gsd-fast for ad-hoc work outside the phase loop
• Configure model profiles — switch between quality, balanced, and budget model tiers
• Set up cross-AI review — configure a second AI to review code produced by the primary agent
• Work in parallel with workstreams — run independent lines of work simultaneously using workstreams
• Isolate work with workspaces — use workspaces to sandbox experimental or risky changes
• Debug a failed execution — diagnose and recover from broken or incomplete phase execution
• Spike and sketch — use /gsd-spike and /gsd-sketch for exploratory work before committing to a plan
• Design a UI phase — use the UI phase loop for frontend and visual work
• Develop a Capability for GSD 1.5+ — add feature Capabilities, hook fragments, and registry entries
• Turn a capability off (and keep it off) — disable a capability via the surface, or gate individual hooks off without removing the capability
• Drive GSD from a tracker issue — start a phase from a GitHub, Linear, or Jira issue
• Migrate from GSD 2 — upgrade an existing GSD 2 project to GSD Core
• Update GSD — re-run the installer to pick up the latest release
• Clean up get-shit-done-cc — remove leftover old-package artifacts that cause a spurious ⬆ /gsd:update indicator after migrating to @opengsd/gsd-core
• Fix the worktree base-mismatch (exit 42) error — resolve the branch-divergence condition that halts parallel phase execution
• Recover and troubleshoot — fix common problems, rebuild context, and uninstall

---

Reference

• Commands — every command with flags and examples
• Configuration — full config schema, model profiles, git branching strategies
• CLI tools — gsd-tools.cjs programmatic API for workflows and agents
• Features — complete feature index
• Inventory — installed skills and surface map
• STATE.md schema — field-by-field reference for .planning/STATE.md
• CONTEXT.md schema — field-by-field reference for .planning/phases/<N>/CONTEXT.md
• PLAN.md schema — field-by-field reference for .planning/phases/<N>/PLAN.md
• Planning artifacts — all .planning/ files and their roles
• Review and verification capabilities — code review, security, and Nyquist capability ownership and hook contracts
• Capability matrix — generated catalogue of every capability's role, tier, extension points, hook kinds, and engines.gsd
• Capability manifest — the full capability.json schema and validation rules
• gsd capability command — install / update / remove / list reference for third-party capabilities

---

Explanation

• Context engineering — how context rot forms and how GSD Core prevents it
• The phase loop — design rationale for the Discuss → Plan → Execute → Verify → Ship cycle
• Multi-agent orchestration — how subagents are spawned, scoped, and coordinated
• Security model — trust boundaries, permissions, and safe automation
• The capability trust model — why third-party capabilities are gated by consent + integrity + reversibility, not a sandbox
• How overlay capabilities compose — why first-party always wins and how the loader resolves precedence, conflicts, and fail-closed gates
• Architecture — system architecture, agent model, and data flow
• Discuss modes — assumptions mode vs interview mode for /gsd-discuss-phase
• Context monitoring — context window monitoring hook architecture
• Issue-driven orchestration — recipe for driving GSD from a tracker issue using existing primitives

---

Related

• Root README — landing page, quickstart, and documentation overview
• Changelog — release history