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
• Probe edges in a non-English project — get real edge coverage on a spec written in another language, and tell "no edges here" apart from "the probe could not read it"
• Resolve prohibition findings — turn the spec phase's surfaced must-NOT constraints into resolved, dismissed, or deferred spec decisions
• Resolve an unreachable-workflow finding — wire or fully sweep a shipped workflow that no command, agent, or skill references
• Acknowledge emitted-artifact drift — declare a deliberate emitted-byte ripple or workflow/agent growth in a commit trailer, and migrate an older ack fragment
• Change the STATE.md schema — add, change or remove a STATE.md frontmatter key and keep the template and all five reference documents in step
• Resolve verify-command path findings — fix an <automated> verify command whose target directory does not resolve from the executor's cwd
• State a failing direction — say what output constitutes failure for an <automated> verify command, and migrate a phase planned before the rule
• Resolve a contract-drift finding — bring an agent's completion contract, read-tag gate, or deleted-file test reference back into agreement with the registry
• Resolve unreachable-guard findings — fix shell guards whose fallback arm cannot run, and tell "nothing to report" apart from "could not look"
• Declare a hook's crash policy — terminate a GSD hook with allow/deny/crash, declare its ON_CRASH policy, and tell a hook's own crash apart from a check that could not run at all
• Resolve a skipped capability probe — act on a coverage gate that held your phase for an unestablished scope, or a planning checkpoint that reported skipped instead of a verdict
• Diagnose which gsd-tools is running — tell this package's tool apart from the predecessor's colliding binary and from a gsd-core too old to identify itself
• Resolve an ESLint glob-coverage finding — bring a source file that matches no lint rule under coverage, or record a reasoned exemption
• Resolve a raw-terminator finding — pick runMain/ExitError, terminateNow, or process.exitCode for a local/require-registered-exit finding, and know the two allowlist entries and the rule's documented evasions
• Adopt the v2 exit contract — turn on gsd-tools's versioned exit-code projection, read the code table including what 80 (DEGRADED) means, and migrate a CI gate that treats any non-zero exit as fatal
• Read the statusline freshness marker — turn on state ~N commits back, and tell "STATE.md is fresh" apart from "freshness could not be established"
• Consume the planning snapshot — read planning inspect from a dashboard or harness, and tell "nothing to report" apart from "could not look"
• Consume the state contract — read .planning/state.json from a workbench or editor extension, gate on the contract version, and tell "nothing to show" apart from "could not look"
• Keep planning docs out of a shared repo — make .planning/ local-only, including untracking files git already tracks (the step .gitignore alone cannot do)
• Publish PRs without planning artifacts — keep .planning/ committed locally, so worktrees and /gsd-undo keep working, while planning.pr_strict keeps every planning path out of the branch you push
• Plan a phase — run research, decompose work, and verify plan quality
• Verify a dependency-compatibility claim — act on a compatibility claim the researcher left [ASSUMED], and tell "nothing declared" apart from "a constraint is declared" and "the lookup failed"
• Execute a phase — run plans in parallel waves with fresh-context subagents
• Enable parallel reviewer lanes — cut a multi-reviewer /gsd-review pass toward its slowest lane, and tell a rate-limited lane apart from one that was never selected
• Verify and ship — walk through completed work, diagnose failures, and create the PR
• Catch complexity before it compounds — enable the post-execute refactor hook, read a proposal's score vs. anchor delta, and accept or decline it
• 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
• Control which host runtime GSD reports — read the agent_runtime ladder, understand what host detection looks at, and pin the runtime when detection is not what you want
• Set up cross-AI review — configure a second AI to review code produced by the primary agent
• Scope code review depth by path — escalate /gsd-code-review to deep for sensitive directories while the rest of the repo stays at the default depth
• 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
• Interpret scope-conformance warnings — read the advisory the worktree-wave merge emits when a plan branch commits outside its declared scope
• Interpret install-shadow warnings — read the advisory GSD Core emits when a /gsd-* trigger is installed at both scopes and one silently wins, and tell "nothing to report" apart from "could not look"
• Interpret state validate results — read the scope reason codes and tell "nothing to report" apart from "could not look"
• 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
• Enable live-DOM verification — opt a project into browser-backed UI acceptance checks during execution, handle the browser-profile lock, and tell "nothing to report" apart from "could not look"
• Develop a Capability for GSD 1.5+ — add feature Capabilities, hook fragments, and registry entries
• Ship a reviewer lane in your capability — declare a reviewer body so /gsd-review discovers, invokes, and renders your external review CLI or model endpoint
• List your reviewer lane in the registry — publish a lane you have built to the Reviewer Lane Registry so other people can find and install it
• Take over a capability or EoS integration — assume maintainership of an existing third-party capability, reviewer lane, or EoS host integration through a handoff, an adoption fork, first-party absorption, or a de-listing
• Add or update a host's integration — set a host's documentation-sourced runtime.hostIntegration axes (ADR-1239 Phase A), with the undocumented sentinel rule
• Migrate an install test to the executed plan — convert an fs.existsSync-probing install test group to a value assertion against installRuntimeArtifacts's executed-plan return, and test against a fake fs adapter
• Vendor a dependency — add a third-party package gsd-core/bin/** needs at runtime as a verbatim vendored artifact, keep it out of dependencies, and pick the right upstream bundle
• 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
• JSON error mode — gsd-tools failure channels: faults (stderr, exit 1) vs degraded results (stdout, exit 0), and the reason-code taxonomy
• 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
• Gate predicates — canonical specification of the phase-gate predicate vocabulary
• Capability matrix — generated catalogue of every capability's role, tier, extension points, hook kinds, and engines.gsd
• Exit code reference — generated catalogue of every registered process exit code, its name, meaning, and owning module, plus the reserved bands and the v1/v2 exit contract
• Capability manifest — the full capability.json schema and validation rules
• gsd capability command — install / update / remove / list reference for third-party capabilities
• Workflow fragments — in-file <!-- gsd:section --> marker grammar for fragmentizing workflow markdown at emission time
• Reviewer Lane Registry — generated catalogue of third-party reviewer lanes, with their flags, transport, and install commands

---

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-open load-failure warnings
• Architecture — system architecture, agent model, and data flow
• The Embeddable Orchestration System — one public, versioned contract for embedding GSD across many hosts
• 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

• What's new in 1.7.0 — curated highlights of the 1.7.0 release
• Root README — landing page, quickstart, and documentation overview
• Changelog — release history