* 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>
This commit is contained in:
Tom Boucher
@@ -34,7 +34,7 @@ GSD has done one consolidation pass and shipped one install-time lever:
|
||||
- **Hard 100-char description budget**, enforced in CI by `scripts/lint-descriptions.cjs` and `npm run lint:descriptions`.
|
||||
- **`gsd update` (without `--minimal`)** as the documented upgrade path from minimal → full.
|
||||
|
||||
The 100-char cap means **shrinking descriptions further is not a viable lever** — average is already 72.5 chars and the rare 99-char outliers exist because they earn their length (e.g. `gsd:progress`, `gsd:inbox`). Any future budget relief has to come from **emitting fewer skills**, not shorter ones.
|
||||
The 100-char cap means **shrinking descriptions further is not a viable lever** — average is already 72.5 chars and the rare 99-char outliers exist because they earn their length (e.g. `gsd-progress`, `gsd-inbox`). Any future budget relief has to come from **emitting fewer skills**, not shorter ones.
|
||||
|
||||
## 3. Audit findings
|
||||
|
||||
@@ -54,7 +54,7 @@ Hot nodes (counted by other-skill body references):
|
||||
| 6 | `new-project` | 2 | Bootstrap |
|
||||
| 6 | `plan-phase` | 2 | Main-loop step 2 |
|
||||
|
||||
`phase` and `review` are the two skills whose absence would silently break dozens of others. **`phase` is referenced by 38 other skills but is not in the current minimal allowlist** — a latent gap worth raising. Confirm with a `--minimal` install + a `/gsd:audit-fix` invocation whether it still works.
|
||||
`phase` and `review` are the two skills whose absence would silently break dozens of others. **`phase` is referenced by 38 other skills but is not in the current minimal allowlist** — a latent gap worth raising. Confirm with a `--minimal` install + a `/gsd-audit-fix` invocation whether it still works.
|
||||
|
||||
### 3.2 Functional clusters
|
||||
|
||||
@@ -114,19 +114,19 @@ gsd install --profile=core,audit,ui # composable feature tags
|
||||
|
||||
### Option B — Runtime enable/disable command
|
||||
|
||||
A `/gsd:surface` (or `gsd surface` CLI) command that toggles which skills are visible to the runtime without touching installed files:
|
||||
A `/gsd-surface` (or `gsd surface` CLI) command that toggles which skills are visible to the runtime without touching installed files:
|
||||
|
||||
```
|
||||
/gsd:surface list # show enabled/disabled
|
||||
/gsd:surface disable ui audit # hide a cluster
|
||||
/gsd:surface profile standard # apply a named profile
|
||||
/gsd-surface list # show enabled/disabled
|
||||
/gsd-surface disable ui audit # hide a cluster
|
||||
/gsd-surface profile standard # apply a named profile
|
||||
```
|
||||
|
||||
Implementation: write enable/disable state to `~/.claude/skills/<name>/SKILL.md.disabled` (rename) or maintain a `gsd-surface.json` manifest the installer reads on every `update`.
|
||||
|
||||
| Dimension | Assessment |
|
||||
|---|---|
|
||||
| User UX | Discoverable through `/gsd:help`. Lower commit than reinstall. Mirrors VS Code's enable/disable extension UX. |
|
||||
| User UX | Discoverable through `/gsd-help`. Lower commit than reinstall. Mirrors VS Code's enable/disable extension UX. |
|
||||
| Implementation cost | **Medium.** Need persistent state separate from install files, plus a re-apply loop on `gsd update`. |
|
||||
| Dependency safety | Same manifest requirement as Option A — disabling `phase` should warn that 38 skills depend on it. |
|
||||
| Token savings | High — user-driven; can match Option A's savings. |
|
||||
@@ -207,7 +207,7 @@ Why this ordering:
|
||||
|
||||
1. **A reuses an existing seam.** `install-profiles.cjs` is already the staging point; this is the lowest-risk way to ship meaningful relief in the next release.
|
||||
2. **A is composable.** Naming clusters as profiles is a forcing function for the dependency manifest, which we want anyway for the lint described in 3.1.
|
||||
3. **B follows A naturally.** Once profiles exist, the `/gsd:surface` command is "apply a profile to a live install plus persist deltas." Without A, B has no profiles to apply.
|
||||
3. **B follows A naturally.** Once profiles exist, the `/gsd-surface` command is "apply a profile to a live install plus persist deltas." Without A, B has no profiles to apply.
|
||||
4. **C is independent and orthogonal.** It can happen in parallel as IA cleanup; it should not block A.
|
||||
5. **D and E are platform-level.** GSD ships A regardless; D/E are documented as cooperative asks so Anthropic sees them in context.
|
||||
|
||||
@@ -229,7 +229,7 @@ Drafted for filing at <https://docs.claude.com/feedback> or similar channel; cop
|
||||
|
||||
### Ask 4 — Disable/enable without uninstall
|
||||
|
||||
> Today the only way to remove a skill from the listing is to delete its `SKILL.md`. Proposal: a `.disabled` suffix (e.g. `SKILL.md.disabled`) or a per-skill `enabled: false` frontmatter is treated as "not surfaced" by the harness. This lets plugins ship surface-toggle UIs (like our proposed `/gsd:surface disable`) without touching install state.
|
||||
> Today the only way to remove a skill from the listing is to delete its `SKILL.md`. Proposal: a `.disabled` suffix (e.g. `SKILL.md.disabled`) or a per-skill `enabled: false` frontmatter is treated as "not surfaced" by the harness. This lets plugins ship surface-toggle UIs (like our proposed `/gsd-surface disable`) without touching install state.
|
||||
|
||||
## 7. Implementation sketch (for the ADR)
|
||||
|
||||
@@ -243,7 +243,7 @@ Phase 1 — profiles (ships with ADR-0010):
|
||||
|
||||
Phase 2 — runtime surface command (follow-up ADR or amendment):
|
||||
|
||||
1. `/gsd:surface` command writes to the profile marker and re-runs the staging step for the active runtime.
|
||||
1. `/gsd-surface` command writes to the profile marker and re-runs the staging step for the active runtime.
|
||||
2. Once Anthropic ships Ask 4, switch from file-deletion to `.disabled`-suffix toggling.
|
||||
|
||||
## 8. Follow-ups outside this scope
|
||||
@@ -253,9 +253,9 @@ Phase 2 — runtime surface command (follow-up ADR or amendment):
|
||||
|
||||
## 9. Risks and unknowns
|
||||
|
||||
- **The `phase` dispatcher gap in the existing minimal allowlist.** Confirm whether a fresh `--minimal` install + the documented main loop actually works end-to-end. If `discuss-phase`/`plan-phase`/`execute-phase` silently fall back to `/gsd:phase`, the minimal allowlist is currently broken. Track as a separate bug if confirmed.
|
||||
- **The `phase` dispatcher gap in the existing minimal allowlist.** Confirm whether a fresh `--minimal` install + the documented main loop actually works end-to-end. If `discuss-phase`/`plan-phase`/`execute-phase` silently fall back to `/gsd-phase`, the minimal allowlist is currently broken. Track as a separate bug if confirmed.
|
||||
- **Profile naming bikeshed.** `core` / `standard` / `full` vs. `minimal` / `recommended` / `everything` vs. functional names (`planning`, `audit`, `research`). Settle in the ADR's Open Questions.
|
||||
- **Discoverability of disabled skills.** If `gsd:audit-fix` isn't surfaced, a user asking "audit my project" won't get it suggested. `/gsd:help` should list installed-but-not-surfaced skills with a one-line upgrade hint.
|
||||
- **Discoverability of disabled skills.** If `gsd-audit-fix` isn't surfaced, a user asking "audit my project" won't get it suggested. `/gsd-help` should list installed-but-not-surfaced skills with a one-line upgrade hint.
|
||||
- **Telemetry blind spot.** GSD doesn't currently know which skills users invoke, so "drop the long tail" is theoretical. Survey or self-reporting may be needed before drawing the `standard` profile line.
|
||||
|
||||
## 10. References
|
||||
|
||||
Reference in New Issue
Block a user