Files

Tom Boucher ffd5370464 fix(#2903 ): use the command form that actually works in reader-facing docs (#3047 )

* fix(#2903): use the command form that actually works in reader-facing docs

Docs told readers to type the colon form, which no runtime registers -- 18 of
19 runtimes use slash-hyphen and the 19th uses shell-var -- so anyone copying an
example got an unrecognized command. Swept 178 occurrences across 53 files,
locale mirrors included so they do not re-diverge from English.

The colon form is a source-authoring token, not a user-facing one: install-time
converters key on it to produce the hyphen form runtimes actually register. So
the sweep is scoped, and three things are deliberately left alone:

- ADRs, which are a historical record; editing their prose falsifies what was
  written at the time.
- The legacy release-notes archive, pending a maintainer decision on whether it
  follows the same historical carve-out. Excluding it keeps a later reversal
  additive rather than a revert.
- Source artifacts under commands, workflows and agents, where the colon form is
  load-bearing. Rewriting those would break the installed-skill guarantee across
  every runtime -- the single largest hazard here.

The plugin namespace form is a real, separate token and survives untouched.

Adds a lint enforcing exactly that boundary, since the correct form genuinely
differs by directory and nothing previously caught the drift.

Also fixes a hardcoded colon form in the capability-matrix generator. The sweep
alone would have left the generated matrix disagreeing with the template that
produces it, so the fix is at the source and the output regenerated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#2903): stop the sweep misquoting source frontmatter

Adversarial review caught three lines where the sweep rewrote a citation of the
literal YAML name: key from a source command file. That key genuinely is the
colon form -- this change's own carve-out logic says source-authoring tokens keep
it -- so the docs ended up misquoting the real files. One of the three is an
acceptance-checklist assertion, which the sweep turned into a false statement.

Restored the three citations to match their sources verbatim, surgically: where a
line carried both a name: citation and a real reader-facing slash command, only
the citation reverted and the command stayed corrected.

The guard needed the same distinction, or it would have flagged the restoration
and reddened the build: a gsd:<cmd> token preceded by name: is a citation of a
source token and is now permitted. The exemption is deliberately narrow -- a bare
gsd:<cmd> anywhere else still fails -- with a test pinning that narrowness.

Also makes the detection case-insensitive. Review found /GSD:next slipped through
silently; no such casing exists in the tree today, so this closes a latent gap
rather than fixing a live one.

Swept the whole tree for further corrupted citations: none beyond the three.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#2903): retire the stale-next invariant and sweep next like every other command

Maintainer decision on a genuine conflict between two contracts.

Invariant #3054 banned the literal /gsd-next from user-facing docs because it
named a retired workflow-advance command. But commands/gsd/next.md is a live
command -- the state-aware smart-entry launcher -- and this issue requires docs
to use the hyphen form every runtime actually registers. Both could not hold for
this one command, so docs had been sidestepping the ban by keeping the colon
form, which is exactly the defect this issue exists to remove.

FEATURES.md already recorded the reassignment: the hyphen form "is not the
retired workflow-advance command; it is reserved for the state-aware smart-entry
launcher. Workflow advancement remains under /gsd-progress --next." With that
reassignment the invariant's premise is obsolete and the guard now contradicts
the documented command form, so it is retired with a comment recording why
rather than deleted silently.

next is now swept like every other command, and the earlier exemption added to
the new guard is removed so nothing is special-cased.

Four citations of the literal name: frontmatter key stay in colon form, because
the source file really does carry name: gsd:next and a doc quoting it must
reproduce it verbatim. Two of those lines were reworded to say which side is the
frontmatter key and which is the slash command, since they previously conflated
the two.

Verified the retired scan would now genuinely fail against this tree -- the
conflict was real and resolved, not dodged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#2903): backfill changeset pr number

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

2026-08-04 13:23:44 -04:00

7.7 KiB

Raw Blame History

Turn a capability off (and keep it off)

This guide shows you how to switch a GSD capability off so it stops taking part in the loop — and stays off — and how to switch off a single feature of a capability without disabling the whole thing.

GSD resolves one capability state from three places: whether the capability is installed, whether it is surfaced, and whether each of its hooks is gated in config. "Off" means off across all three. For why the model works this way, see Develop a Capability for GSD 1.6.0+.

First-party vs. installed: pick the right off-switch. The path depends on where the capability came from.

A first-party capability — one that ships with GSD (for example ui, code-review, research) — is turned off with gsd capability disable <id> or gated with gsd capability set <id> --gate …. These verbs validate <id> against the built-in capability registry.

An installed third-party overlay — one you added with gsd capability install … — is not in that build-time registry, so disable/enable/set reject it with unknown capability: "<id>". The off-switch for an installed overlay is gsd capability remove <id> --scope <scope>.

The rest of this guide covers first-party capabilities. For installed overlays, jump to Turn off an installed third-party capability.

The reliable, fully general way to change first-party capability state is the capability command. The /gsd-surface and /gsd-settings slash commands are convenient interactive front-ends, but they operate on skill clusters, not arbitrary capabilities — so reach for the CLI when you want a precise, scriptable, per-capability switch.

Turn a whole first-party capability off

Disable the capability by id:

gsd capability disable <id>

For example, to stop the UI capability:

gsd capability disable ui

This unsurfaces the capability's skills and makes all of its hooks inactive. It is reversible and needs no reinstall — the bundle stays on disk and your hook gates are preserved. gsd capability disable <id> is exactly gsd capability set <id> --off; re-enable with gsd capability enable <id> (i.e. --on).

disable/enable/set only accept ids the built-in registry knows about. Run them against an installed third-party overlay and you get unknown capability: "<id>" — see Turn off an installed third-party capability for that case.

Check the result:

gsd capability state --raw

The capability now reports enabled: false and every hook active: false.

Turn off one feature of a capability

To keep a capability on but switch off a single hook, gate that hook instead of disabling the capability. A gate is a dotted config key declared in the capability's config slice whose boolean value controls whether one of its hooks fires. Set it to false:

gsd capability set code-review --gate workflow.code_review=false

The capability stays enabled; only that hook stops firing. --gate is repeatable, so you can set several gates in one call. See the set reference for the full contract.

Capabilities that own no skills

Some capabilities (for example, research) contribute only hooks and agents — they have no skills to unsurface, so disabling them via the surface has no effect. Switch these off by gating their hooks instead:

gsd capability set research --gate workflow.research=false

If you gate every hook of a capability off while it is still surfaced, gsd capability state flags it as surfaced-but-inactive — a sign you probably meant to disable the capability itself.

Turn off an installed third-party capability

A capability you added with gsd capability install … is an installed overlay, not a first-party capability. It is not present in the build-time registry that disable/enable/set validate against, so those verbs reject it:

gsd capability disable my-overlay
# error: unknown capability: "my-overlay"

Remove it. This is the deactivation path for an installed overlay — it strips the overlay's files and edits for the chosen scope:

gsd capability remove my-overlay --scope global    # default scope is global
gsd capability remove my-overlay --scope project   # for a project-scoped install

--scope defaults to global, so pass --scope project for a project install. Add --purge-data to also delete the overlay's persisted data. If the id is not installed in the chosen scope you get capability "my-overlay" is not installed in <scope> scope. (Trying to remove a first-party id instead reports that it cannot be removed here — use the product uninstaller, gsd --uninstall.)

The /gsd-surface clusters described below are derived from the built-in capability registry, so they cover first-party skill-owning capabilities. For an installed overlay, remove is the off-switch.

See Remove a capability for the full removal flow and gsd capability remove for every flag and output field.

The interactive paths (`/gsd-surface` and `/gsd-settings`)

The slash commands are the interactive equivalents, useful when you are working inside an agent session rather than scripting:

/gsd-surface disable <cluster> toggles a whole skill cluster on or off and re-stages the surface. Its argument is validated against the fixed set of cluster names — one of core_loop, audit_review, milestone, research_ideate, workspace_state, docs, ui, ai_eval, ns_meta, utility (the command rejects anything else and lists these). A few of these names coincide with first-party skill-owning capability ids (for example ui), so /gsd-surface disable ui works — but the command does not accept an arbitrary capability id, including an installed overlay's id. To switch off a specific capability by id, use the CLI (gsd capability disable <id> for first-party, gsd capability remove <id> for an installed overlay). Reverse a cluster with /gsd-surface enable <cluster>.
/gsd-settings is the interactive prompt for GSD's workflow toggles (the workflow.* config keys that gate hooks). Use it to turn workflow features on or off conversationally; it writes the same config keys that gsd capability set … --gate writes.

For anything you want to be exact about — a specific capability id, a single named gate, or a step in a script or CI job — prefer the CLI.

Scripting it

To mutate capability state directly (in scripts or CI), call the command non-interactively. The first three verbs work on first-party ids; the last works on installed overlays:

# Disable a whole first-party capability
gsd capability disable <id>          # equivalently: gsd capability set <id> --off

# Re-enable
gsd capability enable <id>           # equivalently: gsd capability set <id> --on

# Toggle one hook gate
gsd capability set <id> --gate <key>=<true|false>

# Deactivate an installed third-party overlay (disable/set would reject it)
gsd capability remove <id> --scope <global|project>

See the gsd capability command reference for every subcommand, flag, and output shape.

gsd capability command reference — disable, enable, set, and the rest of the family
Develop a Capability for GSD 1.6.0+
Install a minimal GSD and add skills later
docs index

7.7 KiB Raw Blame History