ffd5370464
* 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>
128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
# How to install a minimal GSD and add skills later
|
|
|
|
Install GSD Core with a small skill footprint to keep cold-start context low, then grow the surface — live or on reinstall — only when you need more. Use this when context budget matters: large existing projects, constrained models, or runtimes where every description token counts.
|
|
|
|
**What you need:** A supported runtime and the standard installer prerequisites (Node.js 18+ and npx). If you have not installed GSD at all yet, read [Install on your runtime](install-on-your-runtime.md) first — this guide covers the *profile* choice that layers on top of any runtime install.
|
|
|
|
---
|
|
|
|
## Install the minimal profile
|
|
|
|
To install only the core main-loop skills, add `--minimal` to the installer:
|
|
|
|
```bash
|
|
npx @opengsd/gsd-core@latest --claude --global --minimal
|
|
```
|
|
|
|
`--minimal` has two aliases — use whichever reads best to you; they are identical:
|
|
|
|
```bash
|
|
npx @opengsd/gsd-core@latest --claude --global --core-only
|
|
npx @opengsd/gsd-core@latest --claude --global --profile=core
|
|
```
|
|
|
|
A minimal install gives you the eight skills needed to run the core phase loop:
|
|
|
|
- `new-project`
|
|
- `discuss-phase`
|
|
- `plan-phase`
|
|
- `execute-phase`
|
|
- `phase`
|
|
- `help`
|
|
- `update`
|
|
- `surface`
|
|
|
|
No sub-agents are installed, and the skill-description tokens the model carries at cold start drop to roughly 130, against roughly 1,200 for a full install. The chosen profile is recorded in the `.gsd-profile` marker in your runtime config directory and is reapplied automatically every time you run `/gsd-update`, so you stay minimal across upgrades until you decide otherwise.
|
|
|
|
> Do not combine `--minimal` with `--profile=` — the installer treats that as a conflict and exits.
|
|
|
|
---
|
|
|
|
## Choose a profile
|
|
|
|
If `core` is too small, pick a wider profile instead. Pass it with `--profile=<name>`:
|
|
|
|
| Profile | What you get | Approx. description tokens |
|
|
|---------|--------------|--------------------------|
|
|
| `core` | The eight core-loop skills above. No agents. | ~130 desc tokens |
|
|
| `standard` | Everything in `core` plus brownfield onboarding (`onboard`), common management skills — `review`, `config`, `progress`, `resume-work`, `pause-work`, `workspace` — and the sub-agents those skills need. | ~700 desc tokens |
|
|
| `full` | Every skill and every sub-agent. This is the default when you pass no profile flag. | ~1,200 desc tokens |
|
|
|
|
```bash
|
|
# Standard: the core loop plus everyday management commands
|
|
npx @opengsd/gsd-core@latest --claude --global --profile=standard
|
|
```
|
|
|
|
If you want a named profile plus one extra cluster, compose them with a comma. The installer writes the union of both:
|
|
|
|
```bash
|
|
# Core loop plus the audit/review skills, nothing else
|
|
npx @opengsd/gsd-core@latest --claude --global --profile=core,audit
|
|
```
|
|
|
|
---
|
|
|
|
## See what is installed and what is available
|
|
|
|
From inside your runtime, list the current surface, the disabled clusters, and the token cost of each:
|
|
|
|
```bash
|
|
/gsd-surface list
|
|
```
|
|
|
|
The skills are grouped into clusters you can toggle as a unit:
|
|
|
|
`core_loop`, `audit_review`, `milestone`, `research_ideate`, `workspace_state`, `docs`, `ui`, `ai_eval`, `ns_meta`, `utility`
|
|
|
|
---
|
|
|
|
## Add skills later without reinstalling
|
|
|
|
If you installed minimal and now need more, you do not have to re-run the installer. `/gsd-surface` changes the live surface and persists the change in a separate `.gsd-surface.json` file, leaving your install-time profile marker untouched.
|
|
|
|
To switch to a wider profile in place:
|
|
|
|
```bash
|
|
/gsd-surface profile standard
|
|
```
|
|
|
|
To turn on just one cluster while keeping your base profile:
|
|
|
|
```bash
|
|
/gsd-surface enable audit_review
|
|
```
|
|
|
|
To turn a cluster back off, or to discard all your live changes and return to the profile you installed:
|
|
|
|
```bash
|
|
/gsd-surface disable utility
|
|
/gsd-surface reset
|
|
```
|
|
|
|
Surface changes take effect in your next session — restart the runtime to pick them up.
|
|
|
|
---
|
|
|
|
## Add skills by reinstalling
|
|
|
|
`/gsd-surface` is the right tool for occasional, reversible adjustments. If you have decided you want the wider surface permanently, change the install-time profile instead so every future `/gsd-update` keeps it:
|
|
|
|
```bash
|
|
# Re-run the installer without --minimal to record `full` as your profile
|
|
npx @opengsd/gsd-core@latest --claude --global
|
|
|
|
# ...or pin a specific profile
|
|
npx @opengsd/gsd-core@latest --claude --global --profile=standard
|
|
```
|
|
|
|
Running `/gsd-update` re-reads the `.gsd-profile` marker and reinstalls at that profile, so a one-off reinstall at a new profile is all you need — subsequent updates follow it automatically.
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [Install on your runtime](install-on-your-runtime.md)
|
|
- [Update GSD](update-gsd.md)
|
|
- [Configuration](../CONFIGURATION.md)
|
|
- [Docs index](../README.md)
|