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>
Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for GSD.
Each ADR documents one architectural decision: what was decided, why, and what consequences follow. ADRs are append-only. Amendments extend existing ADRs with a dated section rather than replacing them.
Naming Convention
New ADRs use issue#-prefix slug naming:
docs/adr/<issue#>-<kebab-slug>.md
Examples: 3485-adr-prd-naming-convention.md, 3464-review-default-reviewers.md.
Why
Two developers computing "next ADR number" locally against main will independently pick the same integer and both ship. The collision is already on disk — 0010-* exists twice and 0011-* exists three times. GitHub issue numbers are server-assigned and atomic: the moment you open an issue, that number is reserved globally. Two PRs that both edit the ### Fixed block of CHANGELOG.md always conflict on merge — two PRs that each use a distinct issue# as their ADR prefix never collide. Same shape, same solution.
Legacy ADRs
Files 0001-* through 0011-* are preserved as immutable historical record. The duplicate 0010-* and the three-way 0011-* are documented residue of the old local-compute convention — not patterns to imitate. Do not renumber them.
Full process
See CONTRIBUTING.md — "Proposing an ADR or PRD" for the end-to-end workflow: opening the issue, waiting for approval, naming the file, and submitting the PR.
Index
| ADR | Title | Status |
|---|---|---|
| 0001-dispatch-policy-module.md | Dispatch policy module as single seam for query execution outcomes | Accepted |
| 0002-command-contract-validation-module.md | Command Contract Validation Module | Accepted |
| 0003-model-catalog-module.md | Model Catalog Module as single source of truth for agent profiles and runtime tier defaults | Accepted |
| 0004-worktree-workstream-seam-module.md | Planning Workspace Module as single seam for worktree and workstream state | Accepted |
| 0005-sdk-architecture-seam-map.md | SDK Architecture seam map for query/runtime surfaces | Superseded by ADR-0174 |
| 0006-planning-path-projection-module.md | Planning Path Projection Module for SDK query handlers | Accepted |
| 0007-sdk-package-seam-module.md | SDK Package Seam Module owns SDK-to-get-shit-done-redux compatibility | Superseded by ADR-0174 |
| 0008-installer-migration-module.md | Installer Migration Module owns install-time upgrade safety | Accepted |
| 0009-shell-command-projection-module.md | Shell Command Projection Module owns runtime-aware OS command rendering | Accepted |
| 0010-file-operation-engine-module.md | File Operation Engine Module owns safe runtime/config file mutations | Proposed |
| 0010-skill-surface-budget-module.md | Skill Surface Budget Module — earlier draft superseded by ADR-0011 | Superseded by 0011 |
| 0011-skill-surface-budget-module.md | Skill Surface Budget Module owns install-time profile staging and runtime surface control | Accepted |
| 0011-review-default-reviewers.md | Review default-reviewers selection policy for /gsd:review | Accepted |
| 0011-review-default-reviewers-prd.md | PRD for review.default_reviewers feature (#3464) | Reference |
| 0012-command-routing-hub.md | CommandRoutingHub as single dispatch seam for CJS command families | Superseded by ADR-0174 |
| 15-autonomous-cross-ai-convergence.md | Cross-AI plan convergence via existing orchestration commands | Proposed |
| 22-plan-drift-guard.md | Plan-vs-codebase drift guard: defaults and symbol-resolver seam | Proposed |
| 3524-cjs-sdk-hard-seam.md | CJS↔SDK hard seam — single canonical owner per responsibility (#3524) | Superseded by ADR-0174 |
| 3660-runtime-artifact-layout-module.md | Runtime Artifact Layout Module owns per-runtime artifact placement | Proposed |
| 0174-retire-gsd-sdk-package-boundary.md | Retire @opengsd/gsd-sdk package boundary — single-runtime collapse | Accepted |
| 452-eslint-lint-harness.md | Adopt standard ESLint flat-config lint harness; retire homegrown regex scanners | Accepted |
| 456-test-rigor-architecture.md | Test-rigor architecture — deterministic scheduling, antagonistic tier, typed-surface mandate, delete-bad-tests policy | Accepted |
| 457-generated-cjs-single-source.md | Collapse hand-written CJS to generated single-source | Proposed |
| 660-release-from-next-head.md | Release from the head of next; immutable release tags; @next dist-tag as the RC surface | Proposed |
| 58-runtime-install-policy-module.md | Runtime Install Policy Module owns the typed install-plan projection | Accepted |
| 766-claude-code-plugin-manifest-module.md | Claude Code Plugin Manifest Module owns the projection of gsd-core surfaces onto the Claude Code plugin contract | Accepted |
Seam map
ADR 0005 is the top-level SDK seam index. It references per-seam ADRs and states the narrow-waist principle each seam follows. Use it as the entry point for understanding SDK module ownership.
ADR 0006 documents how SDK query handlers project planning paths (cwd → effectiveRoot → .planning/<project>/...). Cross-reference with the Planning Workspace Module (ADR 0004) for workstream pointer policy.
ADR 0008 documents the Installer Migration Module for safe install-time moves, removals, config rewrites, and user-data preservation.
ADR 0009 documents the Shell Command Projection Module seam for runtime-aware projection of installer-owned command text and projection IR.
ADR 0010 documents the File Operation Engine Module seam for converging installer/migration/planning file mutation safety policy, and its relationship to ADR 0009 hook-command ownership policy.
ADR 0011 documents the Skill Surface Budget Module for install-time skill/agent
profile staging (--profile=<name>, .gsd-profile marker, requires: closure)
and the Phase 2 runtime /gsd:surface command for cluster-level enable/disable
without reinstall.