Files

Tom Boucher 49793465d7 docs(#2915 ): how-to for listing a reviewer lane, and correct the stale listing section (#2917 )

* docs(#2904): how-to for listing a reviewer lane in the registry

#2912 shipped the Reviewer Lane Registry, which lands in 1.9.1. Two docs
consequences.

New: docs/how-to/list-your-reviewer-lane.md. A Diataxis how-to for the
publish task -- which of the three catalogs applies (and why a runtime
carrying a reviewer body lists under its primary install shape instead),
opening the required discussion thread BEFORE the PR, the three fields
that reject entries most often (slug grammar differs from id, flags stay
kebab when the slug is snake, install/uninstall must be copy-pasteable),
regenerate-don't-hand-edit, and register-once-then-Releases. Links the
registry README for the field table rather than duplicating it -- the
spec is reference, this is the task flow.

Corrected: ship-a-reviewer-lane.md said "Listing your lane is not wired
yet" and pointed at #2904 as future work. #2906 merged at 11:25Z and
#2912 at 12:11Z, so that section shipped false the moment the registry
landed. Replaced with the publish pointer.

Indexed the new guide and the generated catalog in docs/README.md, and
added the guide to develop-a-capability.md's ecosystem list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(#2904): caveat credential-bearing configKeys in both the guide and the spec

Isolated security review found the worked entry's `configKeys:
["acme.api_key"]` modelled storing a live credential with no note on
where that value ends up.

Verified: config values are written in plaintext to
.planning/config.json (docs/CONFIGURATION.md:227 -- masking is
display-only, "that file is the security boundary"), and
planning.commit_docs defaults to true (:466). So a credential declared
that way lands in the installing user's git repository unless they have
gitignored .planning/. None of the twelve first-party lanes does this --
they own only review.models.*, host, and prompt-budget keys.

The pattern originates in docs/registries/README.md:221, shipped by
#2912, so the caveat goes on BOTH surfaces rather than only on the copy
that inherited it -- the spec's example is what future authors will read
first.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore(#2915): backfill changeset PR number

pr: 0 -> 2917.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-07-31 09:29:51 -04:00

8.3 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
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
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
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

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

8.3 KiB Raw Blame History