197d6bffe2
* docs(#894): ADR-894 Capability declaration format + registry generation ADR-857 rollout phase 3a (design-only). Resolve ADR-857's deferred open question — the on-disk Capability declaration format — as a reviewable design ADR before any generator code. Specifies: the capabilities/<id>/capability.json folder layout (migration-staged ownership — declarations reference existing stems until the phase-6 move); the capability.json schema for role:feature (skills/agents/hooks/federated config/ loopHooks) and role:runtime (the six closed projection-primitive axes); the 12 named Loop Extension Points; the gen-capability-registry.cjs generator design (validation + cross-capability invariants + --write/--check drift gate, mirroring gen-inventory-manifest); the generated capability-registry.cjs shape (by-id / by-skill / by-loop-point indexes + requires-closure); and a full worked example (the UI capability: ui-phase + ui-review + agents + config + two loop hooks). No code — design artifact only; the generator build, federated config loader (3b), and loop seam (3c) implement against this contract. Closes #894 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(#894): amend ADR-894 with grilled capability declaration format Stress-tested the declaration format before merge; the format changed materially. Amendments: - loopHooks[] -> three typed arrays (steps/contributions/gates), each with its own shape (step: ref+produces/consumes; contribution: fragment+into agent-role; gate: check+blocking). - Add the Loop Host Contract (§3): each step publishes its points, agent roles, and core artifacts so the generator validates hooks against reality, not trusted strings. - requires = capability ids only (host implicit); add tier-monotone invariant; drop the requires:["plan"] error from the example. - Config federation = atomic move: a migrated key leaves the central schema in the same PR; presence in both is a collision (invariant stays). - One registry, role-partitioned indexes (feature indexes vs runtimes index). - Rework the UI worked example to the split-array shape (2 steps + 1 gate) + a contribution illustration. Adds a "Grilling amendments" section recording the six changes. * docs(#894): amend ADR-894 with round-2 grilling (operational reality) Second design-grill round, folded in before merge: - Loop Host Contract is GENERATED from structured workflow markers (<loop-point>/<agent-role>/<loop-artifact>) via gen-loop-host-contract.cjs — it can't drift from the real workflows. - Hook activation `when`: cheap deterministic config-level gating evaluated by loop.render-hooks; deeper phase-context applicability self-gates inside the dispatched skill (no phase-context vocabulary to keep honest). - `tier` is the source of install-profile + cluster membership; profiles and clusters are generated from tier + requires-closure (/gsd:surface operates on capabilities) — collapses ADR-857's multiple toggle systems. - Gate `check` = query | declarative-predicate | agentVerdict; agentVerdict is forced advisory; only deterministic checks may block. - byLoopPoint ordering is materialized in the registry; render-hooks filters the active set + renders. Same-capability hooks degrade gracefully when an entry step self-gates. - Rollout: registry-only until atomic per-feature cutover (no double-execution with still-inlined workflow features). Updates the Grilling amendments / Consequences / Alternatives / Open questions sections; reworks the UI example with `when`. --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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
How-to guides
- Install on your runtime — runtime-specific install steps for all 15 supported runtimes
- Install a minimal GSD and add skills later — install only the core skills, then grow the surface with profiles and
/gsd:surface - Discuss a phase — capture implementation decisions before planning begins
- 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
- 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
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
- 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