Files

Tom Boucher 46f8d3814c fix(#2009 ): load-failed capability gates fail open with a loud warning

Previously a capability that failed to LOAD (e.g. incompatible engines.gsd) but
declared a gate-kind loop hook caused the loop resolver to inject a BLOCKING
synthetic gate (blocking:true, onError:halt) at every declared point, halting
every ship:pre / verify:post project-wide over an unrelated load error, with no
remediation surfaced.

Per maintainer decision (#2009) it now fails OPEN: no gate is injected (the loop
proceeds; --active-cap correctly reports the failed cap inactive) and a loud
warning is emitted — to stderr (the channel host workflows/agents actually see)
and in the envelope 'warnings' array — naming the load reason and the exact
'gsd capability remove <id>' remediation. The loader still records blockedGates;
only the consequence changes from block to warn.

Security (review): capId and reason originate from a third-party manifest /
directory name. capId is validated against the canonical kebab-case id shape
before it is placed in the runnable remediation command (withheld otherwise);
reason is stripped of control chars and backticks. This closes an argument/
prompt-injection vector in the surfaced message.

Docs updated to the fail-open-warning posture (ARCHITECTURE, INVENTORY,
CONFIGURATION, README, capability-overlay-model). Also removes a dead 'before'
import surfaced by lint in the issue-2045 test.

2026-07-07 19:38:01 -04:00

7.5 KiB

Raw Blame History

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
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
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-open load-failure warnings
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

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

7.5 KiB Raw Blame History