bcc5a6d1ba
* fix(#1634): honor capability hook matcher and node-prefix command Capability hook install (applyCapabilitySharedEdits) wrote each settings.json hook entry with no `matcher`, so a tool-scoped hook fired on every tool (a fail-closed guard could then block the whole session), and emitted a bare single-quoted script path so a .js-family hook from a git/tarball source without +x failed with Permission denied on every matching call. - Pass through an optional declared `matcher` (entry-level sibling of `hooks`); absent => omitted (match-all), so existing shipped capabilities are unchanged. - Validate `matcher` in the declaration (non-empty string, no control chars). - Emit `node <quoted-path>` for .js/.cjs/.mjs hooks (mirrors first-party); .sh and others keep the bare quoted path (unchanged). Root cause: the manifest hook schema (validator rule C4) was {event, script} only with no matcher, and applyCapabilitySharedEdits never read or wrote one; the command used shellSingleQuote(absScript) with no node prefix. Regression tests fail-first on both defects (matcher dropped; bare path) and pass after the fix; #1460 command assertions updated for the node prefix. * chore(#1634): backfill changeset pr:1638 * fix(#1634): resolve lint and windows CI failures - validator: replace the control-character range regex with a char-code loop. The literal /[\x00-\x1f\x7f]/ tripped ESLint's no-control-regex rule; char codes are equally precise and lint-clean. Behavior unchanged (still rejects matchers containing ASCII control characters incl. DEL). - test: gate the executable-bit precondition on POSIX. Windows fs does not honor POSIX write modes (a 0o644 write reads back as 0o666), so the precondition is meaningless there and failed the windows-latest lane. The node-prefix assertion — the actual fix — is platform-independent and still runs everywhere. * docs(#1634): amend ADR-894 for optional lifecycle hook matcher The `role: "feature"` `hooks[]` entry now carries an optional `matcher` (settings.json tool-scoping pattern: exact/pipe/wildcard/regex). Document the field in the §2 schema table and record a Grilling-amendments entry: the install path projects a declared matcher onto the emitted settings.json hook entry (absent = match-all, so shipped capabilities are unchanged), and per-runtime matcher projection (ADR-857 D8) stays a separate concern. This amendment ships with the fix that introduced the field rather than as a follow-up. * docs(#1634): record WINDOWS-POSIX-MODE-BIT-ASSERT defect in CONTEXT.md Capture the CI failure pattern from #1634/PR #1638 so it is not repeated: a test that writes a file with a POSIX mode and then asserts statSync().mode & 0o777 === <octal> passes on macOS/Linux but fails on windows-latest (Windows fs does not honor POSIX write modes — reads back 0o666). Added as a machine-greppable DEFECT predicate (symptom/examples/detect/fix-forward/ prevention) next to DEFECT.WINDOWS-TEST-PORTABILITY, with the fix-forward: gate the mode-bit precondition on process.platform !== 'win32' and keep the platform-independent behavioral assertion running everywhere.
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:skillentry 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-quickand/gsd-fastfor 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-spikeand/gsd-sketchfor 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:updateindicator 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.cjsprogrammatic 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.jsonschema and validation rules gsd capabilitycommand — 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