refactor: hard-fork GSD -> MSD (Make Software Done)
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
Jakub Zych
@@ -1,6 +1,6 @@
|
||||
# Build Your First Capability
|
||||
|
||||
In this tutorial you will build a tiny, fully declarative GSD capability from scratch and watch it act inside your project's loop. By the end you will have a working capability installed, visible in `gsd capability list`, and firing at the `plan:pre` extension point.
|
||||
In this tutorial you will build a tiny, fully declarative MSD capability from scratch and watch it act inside your project's loop. By the end you will have a working capability installed, visible in `msd capability list`, and firing at the `plan:pre` extension point.
|
||||
|
||||
No code is required. Declarative capabilities — those that own only prompt fragments and hook declarations, with no executable hook scripts or MCP servers — require no trust prompt at install time.
|
||||
|
||||
@@ -12,12 +12,12 @@ We will build a capability called `hello-note`. It registers a `contribution` at
|
||||
|
||||
You need:
|
||||
|
||||
- GSD 1.6.0 or later (`gsd --version`).
|
||||
- MSD 1.6.0 or later (`msd --version`).
|
||||
- A throwaway project directory. Create one now:
|
||||
|
||||
```bash
|
||||
mkdir ~/hello-demo && cd ~/hello-demo
|
||||
gsd init
|
||||
msd init
|
||||
```
|
||||
|
||||
You will work inside `~/hello-demo` for the rest of this tutorial.
|
||||
@@ -36,7 +36,7 @@ Your project tree now looks like this:
|
||||
|
||||
```text
|
||||
~/hello-demo/
|
||||
.gsd/
|
||||
.msd/
|
||||
capabilities/
|
||||
hello-note/
|
||||
fragments/ ← prompt fragments live here
|
||||
@@ -74,7 +74,7 @@ Create the manifest at `capabilities/hello-note/capability.json`:
|
||||
"description": "Injects a greeting note at plan:pre and produces HELLO.md.",
|
||||
"tier": "standard",
|
||||
"requires": [],
|
||||
"engines": { "gsd": ">=1.6.0" },
|
||||
"engines": { "msd": ">=1.6.0" },
|
||||
"runtimeCompat": { "supported": ["*"], "unsupported": [] },
|
||||
"skills": [],
|
||||
"agents": [],
|
||||
@@ -97,14 +97,14 @@ Create the manifest at `capabilities/hello-note/capability.json`:
|
||||
A few things to notice:
|
||||
|
||||
- `version` is required in 1.6.0. Use semver.
|
||||
- `engines.gsd` is a hard gate: GSD will refuse to install or load this capability on any version older than 1.6.0.
|
||||
- `engines.msd` is a hard gate: MSD will refuse to install or load this capability on any version older than 1.6.0.
|
||||
- `role: "feature"` means this capability adds optional behaviour to the loop — it is not a runtime descriptor. A `feature` capability must declare `runtimeCompat`; `{ "supported": ["*"] }` means "every runtime".
|
||||
- This is a **contribution**, not a **step**. A contribution injects a prompt fragment into a named agent role (`into`) and needs no dispatch target. A step, by contrast, *must* carry a `ref` with exactly one of `skill`, `agent`, or `command` — so a fragment-only injection is always a contribution. That is why `steps` is left empty here.
|
||||
- `into: "planner"` names the agent role that receives the fragment. `planner` is one of the roles published by the `plan:pre` extension point (alongside `researcher` and `checker`); the value must be a role that point publishes or the manifest fails validation.
|
||||
- `produces` tells the registry that this contribution writes `HELLO.md`, which lets the registry order hooks and detect unsatisfied dependencies in more complex setups.
|
||||
- `onError: "skip"` means the loop continues even if this contribution fails. For a first capability that is the safe choice.
|
||||
|
||||
The fragment is referenced by `path`. At load time GSD reads the file and inlines its text into the registry, so the contribution carries the materialised content wherever the loop renders it. This keeps the capability completely declarative — no executable code is involved.
|
||||
The fragment is referenced by `path`. At load time MSD reads the file and inlines its text into the registry, so the contribution carries the materialised content wherever the loop renders it. This keeps the capability completely declarative — no executable code is involved.
|
||||
|
||||
---
|
||||
|
||||
@@ -113,7 +113,7 @@ The fragment is referenced by `path`. At load time GSD reads the file and inline
|
||||
Install from the local path with `--scope project` so it is scoped only to this demo project:
|
||||
|
||||
```bash
|
||||
gsd capability install ./capabilities/hello-note --scope project
|
||||
msd capability install ./capabilities/hello-note --scope project
|
||||
```
|
||||
|
||||
The command emits a JSON result:
|
||||
@@ -130,17 +130,17 @@ The command emits a JSON result:
|
||||
}
|
||||
```
|
||||
|
||||
GSD copies the bundle into `.gsd/capabilities/hello-note/` and records it in the project ledger at `.gsd-capabilities.json`. Because `hello-note` declares no executable surfaces (no hook scripts, no MCP servers, no command modules) it installs without a consent prompt — the `disclosure` line confirms there was no runnable code to review. That is intentional: declarative capabilities are safe to install without reviewing executable code.
|
||||
MSD copies the bundle into `.msd/capabilities/hello-note/` and records it in the project ledger at `.msd-capabilities.json`. Because `hello-note` declares no executable surfaces (no hook scripts, no MCP servers, no command modules) it installs without a consent prompt — the `disclosure` line confirms there was no runnable code to review. That is intentional: declarative capabilities are safe to install without reviewing executable code.
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Confirm the installation
|
||||
|
||||
```bash
|
||||
gsd capability list
|
||||
msd capability list
|
||||
```
|
||||
|
||||
`list` emits a JSON array of every capability GSD can see — the first-party ones that ship with GSD, plus any you have installed. Your `hello-note` entry appears at the end:
|
||||
`list` emits a JSON array of every capability MSD can see — the first-party ones that ship with MSD, plus any you have installed. Your `hello-note` entry appears at the end:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -156,12 +156,12 @@ gsd capability list
|
||||
}
|
||||
```
|
||||
|
||||
`status` is `active` — the capability is installed, compatible with your GSD version, and will fire. (The other status values are `incompatible`, when the host GSD version is outside the capability's `engines.gsd` range, and `inactive`, when a project-scoped capability has not been consented on this machine.)
|
||||
`status` is `active` — the capability is installed, compatible with your MSD version, and will fire. (The other status values are `incompatible`, when the host MSD version is outside the capability's `engines.msd` range, and `inactive`, when a project-scoped capability has not been consented on this machine.)
|
||||
|
||||
You can also query the active hook set for the `plan:pre` point:
|
||||
|
||||
```bash
|
||||
gsd loop render-hooks plan:pre --raw
|
||||
msd loop render-hooks plan:pre --raw
|
||||
```
|
||||
|
||||
The envelope is `{ point, activeHooks, rendered }`. Your contribution appears in `activeHooks` (alongside any first-party hooks active at this point):
|
||||
@@ -180,26 +180,26 @@ The envelope is `{ point, activeHooks, rendered }`. Your contribution appears in
|
||||
}
|
||||
```
|
||||
|
||||
Notice that `fragment.inline` now holds the materialised text from `fragments/plan-pre.md` — GSD inlined it at load time, while keeping the original `path` for reference. The top-level `rendered` field is an unfiltered diagnostic digest across kinds and roles; planner hosts do not paste it. They read `activeHooks` in registry order and inject only active `kind: "contribution"` entries whose `into` is `planner`, using each entry's `fragment.inline` and resolved `configValues`.
|
||||
Notice that `fragment.inline` now holds the materialised text from `fragments/plan-pre.md` — MSD inlined it at load time, while keeping the original `path` for reference. The top-level `rendered` field is an unfiltered diagnostic digest across kinds and roles; planner hosts do not paste it. They read `activeHooks` in registry order and inject only active `kind: "contribution"` entries whose `into` is `planner`, using each entry's `fragment.inline` and resolved `configValues`.
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — See the contribution reach the planner
|
||||
|
||||
Planning is driven by a slash command, not a `gsd` subcommand. In your AI assistant, start a planning session for a phase with:
|
||||
Planning is driven by a slash command, not a `msd` subcommand. In your AI assistant, start a planning session for a phase with:
|
||||
|
||||
```text
|
||||
/gsd-plan-phase
|
||||
/msd-plan-phase
|
||||
```
|
||||
|
||||
When the planner runs — whether from `/gsd-plan-phase` or `/gsd-quick` — the active planner-targeted `plan:pre` contributions are injected into its prompt, so it receives `hello-note` and, following the fragment's instruction, records a one-line note in `HELLO.md`. In `/gsd-quick --full` and `/gsd-quick --validate`, the same rendered hook snapshot is reused if the plan checker sends the plan back to the planner for revision.
|
||||
When the planner runs — whether from `/msd-plan-phase` or `/msd-quick` — the active planner-targeted `plan:pre` contributions are injected into its prompt, so it receives `hello-note` and, following the fragment's instruction, records a one-line note in `HELLO.md`. In `/msd-quick --full` and `/msd-quick --validate`, the same rendered hook snapshot is reused if the plan checker sends the plan back to the planner for revision.
|
||||
|
||||
The first-party security capability is enabled by default and also contributes at `plan:pre` into the planner role. Its guidance requires generated plans to include `<threat_model>` blocks and carries the configured ASVS level and blocking threshold. Disable `workflow.security_enforcement` if that behavior is not wanted. Contributions targeting any non-planner role are not inserted into Quick's planner prompts.
|
||||
|
||||
You do not need to run a full planning session to confirm the wiring, though. The `loop render-hooks` command shows exactly what the loop would hand the planner — the same output you saw in Step 5:
|
||||
|
||||
```bash
|
||||
gsd loop render-hooks plan:pre --raw
|
||||
msd loop render-hooks plan:pre --raw
|
||||
```
|
||||
|
||||
Find `hello-note` in `activeHooks` and inspect its `fragment.inline`, `into`, and optional `configValues`. Those are the fields the planner host filters and injects. The unfiltered top-level `rendered` digest is useful for inspection, but it is not the planner prompt. This confirms the capability is wired into the loop without dispatching an agent.
|
||||
@@ -211,7 +211,7 @@ Find `hello-note` in `activeHooks` and inspect its `fragment.inline`, `into`, an
|
||||
When you want to stop the contribution from firing, remove the capability from the project:
|
||||
|
||||
```bash
|
||||
gsd capability remove hello-note --scope project
|
||||
msd capability remove hello-note --scope project
|
||||
```
|
||||
|
||||
This emits a JSON result describing what was removed:
|
||||
@@ -222,14 +222,14 @@ This emits a JSON result describing what was removed:
|
||||
"id": "hello-note",
|
||||
"scope": "project",
|
||||
"removedFiles": [
|
||||
".gsd/capabilities/hello-note"
|
||||
".msd/capabilities/hello-note"
|
||||
],
|
||||
"strippedEdits": 0,
|
||||
"dataPreserved": true
|
||||
}
|
||||
```
|
||||
|
||||
Run `gsd capability list` again and `hello-note` is gone from the array. Run `gsd loop render-hooks plan:pre --raw` and you will see it is absent from `activeHooks`: a removed capability contributes nothing to the loop.
|
||||
Run `msd capability list` again and `hello-note` is gone from the array. Run `msd loop render-hooks plan:pre --raw` and you will see it is absent from `activeHooks`: a removed capability contributes nothing to the loop.
|
||||
|
||||
Removing the installed bundle does not touch the source folder you authored under `capabilities/hello-note/` — that is your copy. To reinstall, just run the Step 4 command again.
|
||||
|
||||
|
||||
@@ -1,19 +1,19 @@
|
||||
# Tutorial: embed GSD in a new host
|
||||
# Tutorial: embed MSD in a new host
|
||||
|
||||
This tutorial walks through embedding GSD's orchestration loop into a brand-new
|
||||
This tutorial walks through embedding MSD's orchestration loop into a brand-new
|
||||
host end-to-end — from classifying the host, to composing the engine adapters,
|
||||
to running a GSD command through the embedded engine. It is the learning path
|
||||
to running a MSD command through the embedded engine. It is the learning path
|
||||
that pairs with the [how-to](../how-to/author-a-host-plugin.md) (steps) and the
|
||||
[reference](../reference/host-integration-interface.md) (spec).
|
||||
|
||||
You will build a minimal **programmatic-cli** host-plugin that invokes a GSD
|
||||
command via the embedded engine. No gsd-core source changes.
|
||||
You will build a minimal **programmatic-cli** host-plugin that invokes a MSD
|
||||
command via the embedded engine. No msd-core source changes.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The GSD Host-Integration SDK entry importable in your host's runtime.
|
||||
- The MSD Host-Integration SDK entry importable in your host's runtime.
|
||||
- Your host's authoritative docs open (you'll declare axes from them, never infer).
|
||||
|
||||
## Step 1 — Classify the host
|
||||
@@ -23,7 +23,7 @@ only receive prompts, not call a model for you). That is the `programmatic-cli`
|
||||
profile.
|
||||
|
||||
```js
|
||||
const SDK = require('@opengsd/gsd-core/sdk');
|
||||
const SDK = require('@golem15/msd-core/sdk');
|
||||
// Confirm the profile from your declared axes:
|
||||
const profile = SDK.profileOf({ embeddingMode: 'imperative', runtime: 'node' });
|
||||
// → 'programmatic-cli'
|
||||
@@ -50,10 +50,10 @@ const { effective, points, warnings } = SDK.handleHandshakeRequest(req);
|
||||
// degradation; `warnings` flags any axis the host omitted.
|
||||
```
|
||||
|
||||
## Step 4 — Run a GSD command through the embedded engine
|
||||
## Step 4 — Run a MSD command through the embedded engine
|
||||
|
||||
The imperative adapter exposes the engine surface; your host binds its command
|
||||
surface (slash commands, palette, chat) to it. A user invoking `/gsd-phase` in
|
||||
surface (slash commands, palette, chat) to it. A user invoking `/msd-phase` in
|
||||
your host dispatches through the embedded engine exactly as it would in a
|
||||
first-party host — that is the parity the interface guarantees.
|
||||
|
||||
@@ -67,8 +67,8 @@ host's own parity test.
|
||||
## Recap
|
||||
|
||||
You classified a host, declared its axes from authoritative docs, composed the
|
||||
adapters, negotiated capabilities over the (serialized) handshake, and ran a GSD
|
||||
command through the embedded engine — all without touching gsd-core source. A
|
||||
adapters, negotiated capabilities over the (serialized) handshake, and ran a MSD
|
||||
command through the embedded engine — all without touching msd-core source. A
|
||||
new host is now a plugin you wrote.
|
||||
|
||||
## Next
|
||||
@@ -1,6 +1,6 @@
|
||||
# Install Your First Capability
|
||||
|
||||
In this tutorial you will install a third-party GSD capability into a project, grant it consent, confirm it is active, check whether a newer version is available, and remove it again. By the end you will have driven the whole consumer-side lifecycle once, from the command line, with every step working.
|
||||
In this tutorial you will install a third-party MSD capability into a project, grant it consent, confirm it is active, check whether a newer version is available, and remove it again. By the end you will have driven the whole consumer-side lifecycle once, from the command line, with every step working.
|
||||
|
||||
This is the *install* side of capabilities. If you want to *author* one, see [Build your first capability](build-your-first-capability.md) — that tutorial builds a capability; this one consumes one.
|
||||
|
||||
@@ -12,14 +12,14 @@ So that the lesson is self-contained and reproducible offline, you will first cr
|
||||
|
||||
You need:
|
||||
|
||||
- **GSD 1.6.0 or later** (`gsd --version`). Capability install and management is a 1.6.0 feature, and the capability you build below declares `engines.gsd: ">=1.6.0"`. On an older host the install **hard-blocks** with an `engines` error before anything is staged — it does not partially install. If `gsd --version` reports an earlier version, upgrade GSD before continuing.
|
||||
- **MSD 1.6.0 or later** (`msd --version`). Capability install and management is a 1.6.0 feature, and the capability you build below declares `engines.msd: ">=1.6.0"`. On an older host the install **hard-blocks** with an `engines` error before anything is staged — it does not partially install. If `msd --version` reports an earlier version, upgrade MSD before continuing.
|
||||
- A throwaway working directory. Create one now:
|
||||
|
||||
```bash
|
||||
mkdir ~/cap-consumer-demo && cd ~/cap-consumer-demo
|
||||
```
|
||||
|
||||
You will work inside `~/cap-consumer-demo` for the rest of this tutorial. You do **not** need to run `gsd init` or have an existing settings file — the install in Step 2 creates the host settings file (and its parent directory) for you when you pass `--shared-file`.
|
||||
You will work inside `~/cap-consumer-demo` for the rest of this tutorial. You do **not** need to run `msd init` or have an existing settings file — the install in Step 2 creates the host settings file (and its parent directory) for you when you pass `--shared-file`.
|
||||
|
||||
---
|
||||
|
||||
@@ -42,7 +42,7 @@ Write the manifest at `./acme-greet/capability.json`:
|
||||
"description": "Prints a greeting on a lifecycle event.",
|
||||
"tier": "standard",
|
||||
"requires": [],
|
||||
"engines": { "gsd": ">=1.6.0" },
|
||||
"engines": { "msd": ">=1.6.0" },
|
||||
"runtimeCompat": { "supported": ["*"], "unsupported": [] },
|
||||
"skills": [],
|
||||
"agents": [],
|
||||
@@ -56,7 +56,7 @@ Write the manifest at `./acme-greet/capability.json`:
|
||||
}
|
||||
```
|
||||
|
||||
The `"engines": { "gsd": ">=1.6.0" }` line is the host-compatibility gate: GSD checks it against your running version at install time, and an older host is hard-blocked with an `engines` error (see [Before you begin](#before-you-begin)). Leave it as-is.
|
||||
The `"engines": { "msd": ">=1.6.0" }` line is the host-compatibility gate: MSD checks it against your running version at install time, and an older host is hard-blocked with an `engines` error (see [Before you begin](#before-you-begin)). Leave it as-is.
|
||||
|
||||
Write the hook script it declares at `./acme-greet/hooks/greet.sh`:
|
||||
|
||||
@@ -78,16 +78,16 @@ You now have a complete, installable bundle:
|
||||
greet.sh
|
||||
```
|
||||
|
||||
Because `acme-greet` declares a `hooks` entry, it has an **executable surface**: installing it would register a script that runs on a lifecycle event. GSD will not activate that without your explicit consent. That is the gate you will see next.
|
||||
Because `acme-greet` declares a `hooks` entry, it has an **executable surface**: installing it would register a script that runs on a lifecycle event. MSD will not activate that without your explicit consent. That is the gate you will see next.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Try to install it, and meet the consent gate
|
||||
|
||||
Install from the local path with `--scope project`, so the capability is scoped to this project only. Because the capability declares a runtime hook, also pass `--shared-file .claude/settings.json` — that tells GSD **which** host settings file to splice the hook registration into. (`--shared-file` is relative to the scope root, which for `--scope project` is your project directory. The file does not need to exist yet: when the install actually writes the hook, GSD creates `.claude/settings.json` and its parent directory if absent, and merges the hook into whatever is already there otherwise.) Without it, the bundle would still be staged, but its hook would never be wired into any runtime config — see Step 5:
|
||||
Install from the local path with `--scope project`, so the capability is scoped to this project only. Because the capability declares a runtime hook, also pass `--shared-file .claude/settings.json` — that tells MSD **which** host settings file to splice the hook registration into. (`--shared-file` is relative to the scope root, which for `--scope project` is your project directory. The file does not need to exist yet: when the install actually writes the hook, MSD creates `.claude/settings.json` and its parent directory if absent, and merges the hook into whatever is already there otherwise.) Without it, the bundle would still be staged, but its hook would never be wired into any runtime config — see Step 5:
|
||||
|
||||
```bash
|
||||
gsd capability install ./acme-greet --scope project --shared-file .claude/settings.json
|
||||
msd capability install ./acme-greet --scope project --shared-file .claude/settings.json
|
||||
```
|
||||
|
||||
The install does **not** complete. You will see a disclosure of the executable surface and a prompt to grant consent, similar to:
|
||||
@@ -100,7 +100,7 @@ Error: This capability declares executable surfaces and needs your consent befor
|
||||
Re-run with --yes to grant consent and install.
|
||||
```
|
||||
|
||||
This is intentional and is the heart of the capability trust model: **install never runs capability code**. The bundle is first copied into an isolated staging directory and its manifest is validated — still without executing anything — and then, before the capability is activated, any executable surface it declares is disclosed and must be consented to. Consent gates *activation*: nothing is promoted into place, no ledger entry or consent record is committed, and no host settings file is touched until you grant it. To understand why GSD draws the line here, read [The capability trust model](../explanation/capability-trust-model.md).
|
||||
This is intentional and is the heart of the capability trust model: **install never runs capability code**. The bundle is first copied into an isolated staging directory and its manifest is validated — still without executing anything — and then, before the capability is activated, any executable surface it declares is disclosed and must be consented to. Consent gates *activation*: nothing is promoted into place, no ledger entry or consent record is committed, and no host settings file is touched until you grant it. To understand why MSD draws the line here, read [The capability trust model](../explanation/capability-trust-model.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -109,7 +109,7 @@ This is intentional and is the heart of the capability trust model: **install ne
|
||||
Re-run the same command with `--yes` to grant consent for the disclosed surface:
|
||||
|
||||
```bash
|
||||
gsd capability install ./acme-greet --scope project --shared-file .claude/settings.json --yes
|
||||
msd capability install ./acme-greet --scope project --shared-file .claude/settings.json --yes
|
||||
```
|
||||
|
||||
This time the install completes. You will see a confirmation naming the capability, its version, the scope, and the executable surface you consented to:
|
||||
@@ -128,7 +128,7 @@ This time the install completes. You will see a confirmation naming the capabili
|
||||
}
|
||||
```
|
||||
|
||||
Three things happened. The bundle was copied into the project's capability root at `.gsd/capabilities/acme-greet/`; the declared `Stop` hook was spliced into the `--shared-file` you named (`.claude/settings.json`); and — because this is a project-scope install — a **consent record** was written to your user-owned consent store at `${GSD_HOME:-~}/.gsd/consent.json`, bound to this project and this exact bundle. That record, not the in-repo ledger, is what lets the capability activate on this machine. The reasoning behind that split is explained in [The capability trust model](../explanation/capability-trust-model.md#the-project-scope-trust-boundary).
|
||||
Three things happened. The bundle was copied into the project's capability root at `.msd/capabilities/acme-greet/`; the declared `Stop` hook was spliced into the `--shared-file` you named (`.claude/settings.json`); and — because this is a project-scope install — a **consent record** was written to your user-owned consent store at `${MSD_HOME:-~}/.msd/consent.json`, bound to this project and this exact bundle. That record, not the in-repo ledger, is what lets the capability activate on this machine. The reasoning behind that split is explained in [The capability trust model](../explanation/capability-trust-model.md#the-project-scope-trust-boundary).
|
||||
|
||||
---
|
||||
|
||||
@@ -137,7 +137,7 @@ Three things happened. The bundle was copied into the project's capability root
|
||||
List the capabilities visible to this project:
|
||||
|
||||
```bash
|
||||
gsd capability list
|
||||
msd capability list
|
||||
```
|
||||
|
||||
`list` emits a JSON array. The first-party capabilities are listed first; your installed overlay `acme-greet` appears as the last entry, with `source: "./acme-greet"`, the `project` scope, and `status: "active"`:
|
||||
@@ -156,12 +156,12 @@ gsd capability list
|
||||
}
|
||||
```
|
||||
|
||||
`status: "active"` is the signal that the capability is both compatible with your GSD version *and* backed by a consent record on this machine. Had you copied a bundle into `.gsd/capabilities/` by hand — with no consent record — the same row would read `status: "inactive"` with a `reason`, and the capability would contribute nothing.
|
||||
`status: "active"` is the signal that the capability is both compatible with your MSD version *and* backed by a consent record on this machine. Had you copied a bundle into `.msd/capabilities/` by hand — with no consent record — the same row would read `status: "inactive"` with a `reason`, and the capability would contribute nothing.
|
||||
|
||||
You can also inspect what you consented to. List your project consent records:
|
||||
|
||||
```bash
|
||||
gsd capability trust list
|
||||
msd capability trust list
|
||||
```
|
||||
|
||||
You will see one record for `acme-greet`, keyed by the project root, recording the bundle integrity and disclosure signature you approved:
|
||||
@@ -184,22 +184,22 @@ You will see one record for `acme-greet`, keyed by the project root, recording t
|
||||
|
||||
## Step 5 — Confirm the hook was registered
|
||||
|
||||
Because you installed with `--shared-file .claude/settings.json`, GSD spliced the capability's `Stop` hook into that file at install time. That is the step that actually wires the hook into the runtime — installing the bundle alone does **not** register a hook; only the `--shared-file` splice does. Look at the file:
|
||||
Because you installed with `--shared-file .claude/settings.json`, MSD spliced the capability's `Stop` hook into that file at install time. That is the step that actually wires the hook into the runtime — installing the bundle alone does **not** register a hook; only the `--shared-file` splice does. Look at the file:
|
||||
|
||||
```bash
|
||||
cat .claude/settings.json
|
||||
```
|
||||
|
||||
You will see a `hooks.Stop` entry stamped with a `_gsdCapability` marker naming the owning capability, whose `command` is the realpath-confined absolute path to the bundle's own `greet.sh`:
|
||||
You will see a `hooks.Stop` entry stamped with a `_msdCapability` marker naming the owning capability, whose `command` is the realpath-confined absolute path to the bundle's own `greet.sh`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"Stop": [
|
||||
{
|
||||
"_gsdCapability": "acme-greet",
|
||||
"_msdCapability": "acme-greet",
|
||||
"hooks": [
|
||||
{ "type": "command", "command": "'/Users/you/cap-consumer-demo/.gsd/capabilities/acme-greet/hooks/greet.sh'" }
|
||||
{ "type": "command", "command": "'/Users/you/cap-consumer-demo/.msd/capabilities/acme-greet/hooks/greet.sh'" }
|
||||
]
|
||||
}
|
||||
]
|
||||
@@ -207,27 +207,27 @@ You will see a `hooks.Stop` entry stamped with a `_gsdCapability` marker naming
|
||||
}
|
||||
```
|
||||
|
||||
That entry is what makes the `Stop` hook run — printing `Hello from acme-greet` — the next time the runtime fires its `Stop` lifecycle event. The `_gsdCapability` marker is also what lets `remove` strip *exactly* this entry later without touching anything else in `settings.json` (you will see that in Step 7).
|
||||
That entry is what makes the `Stop` hook run — printing `Hello from acme-greet` — the next time the runtime fires its `Stop` lifecycle event. The `_msdCapability` marker is also what lets `remove` strip *exactly* this entry later without touching anything else in `settings.json` (you will see that in Step 7).
|
||||
|
||||
Had you installed **without** `--shared-file`, the bundle would still be on disk and `list` would still show it `active`, but `.claude/settings.json` would carry no `Stop` entry — the hook would be declared but never wired in. The `--shared-file` flag is what turns a declared hook into a registered one.
|
||||
|
||||
> **`disable`/`enable` do not apply to an installed overlay.** Those verbs validate the id against GSD's **built-in** capability registry, which does not contain capabilities you installed yourself. Running `gsd capability disable acme-greet` fails:
|
||||
> **`disable`/`enable` do not apply to an installed overlay.** Those verbs validate the id against MSD's **built-in** capability registry, which does not contain capabilities you installed yourself. Running `msd capability disable acme-greet` fails:
|
||||
>
|
||||
> ```text
|
||||
> capability set: error: unknown capability: "acme-greet"
|
||||
> Error: capability set: 1 error(s) — see above
|
||||
> ```
|
||||
>
|
||||
> `disable`/`enable`/`set` are for first-party capabilities. The off-switch for an installed overlay like `acme-greet` is `gsd capability remove` — which you will use in Step 7. (For the difference between the two paths, see [Turn a capability off](../how-to/turn-a-capability-off.md).) For now, leave `acme-greet` installed.
|
||||
> `disable`/`enable`/`set` are for first-party capabilities. The off-switch for an installed overlay like `acme-greet` is `msd capability remove` — which you will use in Step 7. (For the difference between the two paths, see [Turn a capability off](../how-to/turn-a-capability-off.md).) For now, leave `acme-greet` installed.
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — Check whether an update is available
|
||||
|
||||
Ask GSD whether any installed overlay capability has a newer version available:
|
||||
Ask MSD whether any installed overlay capability has a newer version available:
|
||||
|
||||
```bash
|
||||
gsd capability outdated
|
||||
msd capability outdated
|
||||
```
|
||||
|
||||
This prints a table with one row per installed overlay capability. For a **local** source, `outdated` re-reads the `capability.json` at the recorded path and compares its version with the installed one. The bundle you installed from is still on disk at version `1.0.0`, so the row reports `current` — there is nothing newer to fetch:
|
||||
@@ -238,7 +238,7 @@ ID Source Current Latest Status
|
||||
acme-greet local 1.0.0 1.0.0 current
|
||||
```
|
||||
|
||||
For a capability installed from a git URL or npm, `outdated` performs a metadata-only remote peek instead and reports `outdated`, `pinned`, or — when the source cannot be auto-checked — `manual` or `unknown`. It never re-clones or re-extracts a bundle, and a single failing peek never crashes the command. See the [`outdated` reference](../reference/gsd-capability-command.md#outdated) for the full per-source matrix.
|
||||
For a capability installed from a git URL or npm, `outdated` performs a metadata-only remote peek instead and reports `outdated`, `pinned`, or — when the source cannot be auto-checked — `manual` or `unknown`. It never re-clones or re-extracts a bundle, and a single failing peek never crashes the command. See the [`outdated` reference](../reference/msd-capability-command.md#outdated) for the full per-source matrix.
|
||||
|
||||
---
|
||||
|
||||
@@ -247,7 +247,7 @@ For a capability installed from a git URL or npm, `outdated` performs a metadata
|
||||
Remove the capability completely. Because you installed it with `--scope project`, you must remove it from the same scope — `remove` defaults to `global`, so pass `--scope project` here too:
|
||||
|
||||
```bash
|
||||
gsd capability remove acme-greet --scope project
|
||||
msd capability remove acme-greet --scope project
|
||||
```
|
||||
|
||||
(Omitting `--scope` would look in the `global` scope and report `capability "acme-greet" is not installed in global scope`.)
|
||||
@@ -260,16 +260,16 @@ You will see a confirmation listing exactly what was removed:
|
||||
"id": "acme-greet",
|
||||
"scope": "project",
|
||||
"removedFiles": [
|
||||
".gsd/capabilities/acme-greet"
|
||||
".msd/capabilities/acme-greet"
|
||||
],
|
||||
"strippedEdits": 1,
|
||||
"dataPreserved": true
|
||||
}
|
||||
```
|
||||
|
||||
`strippedEdits` is the **count** of marker-isolated fragments stripped from shared files — `1` here, because removal excised the `Stop` hook entry you saw in `.claude/settings.json` in Step 5. Removal strips **only** entries carrying this capability's `_gsdCapability` marker, so anything else in that file (your own hooks, other settings) is left untouched. `dataPreserved` is `true` because you did not pass `--purge-data` — any runtime data the capability created would be left in place; add `--purge-data` to delete it too.
|
||||
`strippedEdits` is the **count** of marker-isolated fragments stripped from shared files — `1` here, because removal excised the `Stop` hook entry you saw in `.claude/settings.json` in Step 5. Removal strips **only** entries carrying this capability's `_msdCapability` marker, so anything else in that file (your own hooks, other settings) is left untouched. `dataPreserved` is `true` because you did not pass `--purge-data` — any runtime data the capability created would be left in place; add `--purge-data` to delete it too.
|
||||
|
||||
Removal does three things, leaving no orphaned state: it deletes the bundle from `.gsd/capabilities/` and strips its hook entry from `.claude/settings.json`, removes the ledger entry, and — because this was a project-scope capability — **revokes the consent record** in your consent store. Run `cat .claude/settings.json` and the `acme-greet` `Stop` entry is gone; run `gsd capability trust list` again and the `acme-greet` record is gone; run `gsd capability list` and the `acme-greet` row is gone.
|
||||
Removal does three things, leaving no orphaned state: it deletes the bundle from `.msd/capabilities/` and strips its hook entry from `.claude/settings.json`, removes the ledger entry, and — because this was a project-scope capability — **revokes the consent record** in your consent store. Run `cat .claude/settings.json` and the `acme-greet` `Stop` entry is gone; run `msd capability trust list` again and the `acme-greet` record is gone; run `msd capability list` and the `acme-greet` row is gone.
|
||||
|
||||
---
|
||||
|
||||
@@ -288,4 +288,4 @@ The lifecycle you just drove — *disclose, consent, activate, audit, revoke*
|
||||
- [Remove a capability](../how-to/remove-a-capability.md) — the full removal task, including `--purge-data`.
|
||||
- [The capability trust model](../explanation/capability-trust-model.md) — *why* install never runs code, and how consent and integrity work.
|
||||
- [How overlay capabilities compose](../explanation/capability-overlay-model.md) — *why* first-party always wins and how precedence is resolved.
|
||||
- [`gsd capability` command reference](../reference/gsd-capability-command.md) — every subcommand, flag, and output shape.
|
||||
- [`msd capability` command reference](../reference/msd-capability-command.md) — every subcommand, flag, and output shape.
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Onboarding an existing codebase
|
||||
|
||||
In this tutorial you will bring GSD Core into a repository that already has code in it. You will map the codebase, create a project that describes what you are *adding*, and run your first discuss-and-plan cycle for a small focused change. By the end, GSD Core's planning pipeline will know your stack, your conventions, and your concerns — and it will use that knowledge every time you plan.
|
||||
In this tutorial you will bring MSD Core into a repository that already has code in it. You will map the codebase, create a project that describes what you are *adding*, and run your first discuss-and-plan cycle for a small focused change. By the end, MSD Core's planning pipeline will know your stack, your conventions, and your concerns — and it will use that knowledge every time you plan.
|
||||
|
||||
---
|
||||
|
||||
## What you'll build
|
||||
|
||||
We will add a single `GET /health` endpoint to an existing Express application. The change is small enough that it will never distract from the real lesson: how GSD Core learns your codebase before it plans anything.
|
||||
We will add a single `GET /health` endpoint to an existing Express application. The change is small enough that it will never distract from the real lesson: how MSD Core learns your codebase before it plans anything.
|
||||
|
||||
---
|
||||
|
||||
@@ -18,12 +18,12 @@ We will add a single `GET /health` endpoint to an existing Express application.
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Install GSD Core
|
||||
## Step 1 — Install MSD Core
|
||||
|
||||
From your repo root:
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
npx @golem15/msd-core@latest
|
||||
```
|
||||
|
||||
Choose **Claude Code** and **local** when prompted. You'll see:
|
||||
@@ -31,7 +31,7 @@ Choose **Claude Code** and **local** when prompted. You'll see:
|
||||
```text
|
||||
✓ Installed 86 skills to .claude/commands/
|
||||
✓ Installed agents to .claude/agents/
|
||||
✓ GSD Core ready — run /gsd-new-project to start
|
||||
✓ MSD Core ready — run /msd-new-project to start
|
||||
```
|
||||
|
||||
---
|
||||
@@ -44,7 +44,7 @@ claude --dangerously-skip-permissions
|
||||
|
||||
> [!CAUTION]
|
||||
> **The permissions flag is optional.** It skips per-file confirmation while
|
||||
> GSD's sub-agents read and write files. Use it only in low-stakes or
|
||||
> MSD's sub-agents read and write files. Use it only in low-stakes or
|
||||
> throwaway contexts. To keep confirmations enabled, start with `claude` instead.
|
||||
> For real work, read the [security model](../explanation/security-model.md) first.
|
||||
|
||||
@@ -53,19 +53,19 @@ claude --dangerously-skip-permissions
|
||||
|
||||
## Step 3 — Start brownfield onboarding
|
||||
|
||||
Before creating a project, let GSD Core inspect the repo state and tell you the safe next top-level command. This is the step that prevents brownfield setup from skipping codebase context or overwriting existing planning files.
|
||||
Before creating a project, let MSD Core inspect the repo state and tell you the safe next top-level command. This is the step that prevents brownfield setup from skipping codebase context or overwriting existing planning files.
|
||||
|
||||
```text
|
||||
/gsd-onboard
|
||||
/msd-onboard
|
||||
```
|
||||
|
||||
If code exists and `.planning/codebase/` is missing, GSD Core asks you to map the codebase first. Choose the recommended mapping option, then run the printed handoff command:
|
||||
If code exists and `.planning/codebase/` is missing, MSD Core asks you to map the codebase first. Choose the recommended mapping option, then run the printed handoff command:
|
||||
|
||||
```text
|
||||
/gsd-map-codebase
|
||||
/msd-map-codebase
|
||||
```
|
||||
|
||||
Use `/gsd-onboard --fast` if you want the onboarding gate to prefer `/gsd-map-codebase --fast` for a lighter first pass. Fast mode is only enough for lightweight onboarding; `/gsd-onboard` still sends you back to the full mapper before `/gsd-new-project`. The full mapper spawns four parallel mapper sub-agents (you'll see "Spawning 4 parallel codebase mapper agents…" — this takes 1–5 minutes; do not interrupt). Each agent focuses on a different concern:
|
||||
Use `/msd-onboard --fast` if you want the onboarding gate to prefer `/msd-map-codebase --fast` for a lighter first pass. Fast mode is only enough for lightweight onboarding; `/msd-onboard` still sends you back to the full mapper before `/msd-new-project`. The full mapper spawns four parallel mapper sub-agents (you'll see "Spawning 4 parallel codebase mapper agents…" — this takes 1–5 minutes; do not interrupt). Each agent focuses on a different concern:
|
||||
|
||||
| Agent | Focus |
|
||||
|-------|-------|
|
||||
@@ -89,9 +89,9 @@ Created .planning/codebase/:
|
||||
- CONCERNS.md (33 lines) - Technical debt and issues
|
||||
```
|
||||
|
||||
Open `.planning/codebase/STACK.md`. You'll see the language, runtime, framework versions, and key dependencies GSD Core detected — grounded in the actual files it read, not guessed.
|
||||
Open `.planning/codebase/STACK.md`. You'll see the language, runtime, framework versions, and key dependencies MSD Core detected — grounded in the actual files it read, not guessed.
|
||||
|
||||
Open `.planning/codebase/CONVENTIONS.md`. You'll see the naming conventions, error-handling patterns, and code-style rules it observed from your source. Every plan GSD Core produces for this repo will follow these conventions automatically.
|
||||
Open `.planning/codebase/CONVENTIONS.md`. You'll see the naming conventions, error-handling patterns, and code-style rules it observed from your source. Every plan MSD Core produces for this repo will follow these conventions automatically.
|
||||
|
||||
Open `.planning/codebase/CONCERNS.md`. This is the most useful file to read before any new feature work — it surfaces technical debt and fragile areas that might affect your plans.
|
||||
|
||||
@@ -108,18 +108,18 @@ Clear the session window:
|
||||
Now rerun onboarding:
|
||||
|
||||
```text
|
||||
/gsd-onboard
|
||||
/msd-onboard
|
||||
```
|
||||
|
||||
If GSD Core detects ADRs, PRDs, specs, RFCs, or top-level requirements docs, choose the recommended docs-ingest handoff first and rerun `/gsd-onboard` afterward. Once codebase context and any existing docs are handled, onboarding prints the project-initialization handoff:
|
||||
If MSD Core detects ADRs, PRDs, specs, RFCs, or top-level requirements docs, choose the recommended docs-ingest handoff first and rerun `/msd-onboard` afterward. Once codebase context and any existing docs are handled, onboarding prints the project-initialization handoff:
|
||||
|
||||
```text
|
||||
/gsd-new-project
|
||||
/msd-new-project
|
||||
```
|
||||
|
||||
Because GSD Core found existing code in the previous step, `/gsd-new-project` knows this is a brownfield project. The questions focus on what you are *adding*, not rebuilding what already exists:
|
||||
Because MSD Core found existing code in the previous step, `/msd-new-project` knows this is a brownfield project. The questions focus on what you are *adding*, not rebuilding what already exists:
|
||||
|
||||
GSD Core asks what you want to build. Answer with the feature you are adding, not a description of the whole codebase:
|
||||
MSD Core asks what you want to build. Answer with the feature you are adding, not a description of the whole codebase:
|
||||
|
||||
```text
|
||||
Add a GET /health endpoint to the Express app. It should return
|
||||
@@ -127,7 +127,7 @@ Add a GET /health endpoint to the Express app. It should return
|
||||
health checks.
|
||||
```
|
||||
|
||||
GSD Core follows up with a small number of clarifying questions, then proceeds to requirements and roadmap creation. Because it already read `ARCHITECTURE.md` and `STACK.md`, it will map existing capabilities into the **Validated** section of `PROJECT.md` automatically — you do not need to describe your existing API surface.
|
||||
MSD Core follows up with a small number of clarifying questions, then proceeds to requirements and roadmap creation. Because it already read `ARCHITECTURE.md` and `STACK.md`, it will map existing capabilities into the **Validated** section of `PROJECT.md` automatically — you do not need to describe your existing API surface.
|
||||
|
||||
Choose recommended defaults for all workflow settings.
|
||||
|
||||
@@ -157,12 +157,12 @@ Approve the roadmap.
|
||||
codebase/ ← the seven map files from Step 3
|
||||
```
|
||||
|
||||
Notice that `.planning/codebase/` is already there from Step 3. GSD Core read those files when writing `PROJECT.md`, which is why it could populate the Validated requirements without you describing them.
|
||||
Notice that `.planning/codebase/` is already there from Step 3. MSD Core read those files when writing `PROJECT.md`, which is why it could populate the Validated requirements without you describing them.
|
||||
|
||||
Run onboarding one more time after project setup completes:
|
||||
|
||||
```text
|
||||
/gsd-onboard
|
||||
/msd-onboard
|
||||
```
|
||||
|
||||
Now that `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist, onboarding creates or confirms:
|
||||
@@ -182,10 +182,10 @@ This summary is a lightweight index of the setup artifacts and the next command
|
||||
```
|
||||
|
||||
```text
|
||||
/gsd-discuss-phase 1
|
||||
/msd-discuss-phase 1
|
||||
```
|
||||
|
||||
Because GSD Core has read your `CONVENTIONS.md` and `ARCHITECTURE.md`, its questions are grounded in your actual codebase — not generic advice. You might see:
|
||||
Because MSD Core has read your `CONVENTIONS.md` and `ARCHITECTURE.md`, its questions are grounded in your actual codebase — not generic advice. You might see:
|
||||
|
||||
```text
|
||||
> Your routes are registered in src/routes/index.js. Should the health
|
||||
@@ -200,7 +200,7 @@ Because GSD Core has read your `CONVENTIONS.md` and `ARCHITECTURE.md`, its quest
|
||||
process.uptime() is fine.
|
||||
```
|
||||
|
||||
When the discussion closes, GSD Core writes:
|
||||
When the discussion closes, MSD Core writes:
|
||||
|
||||
```text
|
||||
.planning/phases/01-health-endpoint/CONTEXT.md
|
||||
@@ -213,7 +213,7 @@ Open that file. The `## Implementation Decisions` section captures your answers.
|
||||
## Step 6 — Plan Phase 1
|
||||
|
||||
```text
|
||||
/gsd-plan-phase 1
|
||||
/msd-plan-phase 1
|
||||
```
|
||||
|
||||
Four research sub-agents run in parallel (1–5 minutes). When they return, the planner reads `CONTEXT.md`, the research findings, and your codebase map to create task plans that match your conventions.
|
||||
@@ -227,7 +227,7 @@ Four research sub-agents run in parallel (1–5 minutes). When they return, the
|
||||
01-02-PLAN.md ← Task: register health route in src/routes/index.js
|
||||
```
|
||||
|
||||
Open `01-01-PLAN.md`. Notice that the `<files>` tag references `src/routes/health.js` — the exact path you specified in the discussion, consistent with the routing pattern GSD Core observed in your codebase map. That is the codebase map at work.
|
||||
Open `01-01-PLAN.md`. Notice that the `<files>` tag references `src/routes/health.js` — the exact path you specified in the discussion, consistent with the routing pattern MSD Core observed in your codebase map. That is the codebase map at work.
|
||||
|
||||
---
|
||||
|
||||
@@ -236,21 +236,21 @@ Open `01-01-PLAN.md`. Notice that the `<files>` tag references `src/routes/healt
|
||||
You now have a project with a codebase map, a discuss decision record, and verified task plans — all grounded in your actual code. From here, the workflow is identical to a greenfield project:
|
||||
|
||||
```text
|
||||
/gsd-execute-phase 1
|
||||
/gsd-verify-work 1
|
||||
/gsd-ship 1
|
||||
/msd-execute-phase 1
|
||||
/msd-verify-work 1
|
||||
/msd-ship 1
|
||||
```
|
||||
|
||||
For every future feature, run `/gsd-map-codebase` again whenever the structure changes significantly, so the codebase map stays fresh. Rerun `/gsd-onboard` only when you want to re-check first-time setup completeness or regenerate the onboarding summary.
|
||||
For every future feature, run `/msd-map-codebase` again whenever the structure changes significantly, so the codebase map stays fresh. Rerun `/msd-onboard` only when you want to re-check first-time setup completeness or regenerate the onboarding summary.
|
||||
|
||||
---
|
||||
|
||||
## What you've learned
|
||||
|
||||
- How `/gsd-onboard` safely sequences brownfield setup without nesting interactive commands or overwriting existing planning files.
|
||||
- How `/gsd-map-codebase` runs four parallel agents to produce `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, and `INTEGRATIONS.md` in `.planning/codebase/`.
|
||||
- How `/gsd-new-project` in a brownfield repo focuses questions on what you are *adding* and populates Validated requirements from existing code.
|
||||
- How the codebase map shapes every question in `/gsd-discuss-phase` — file paths, patterns, and conventions come from your actual code.
|
||||
- How `/msd-onboard` safely sequences brownfield setup without nesting interactive commands or overwriting existing planning files.
|
||||
- How `/msd-map-codebase` runs four parallel agents to produce `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, and `INTEGRATIONS.md` in `.planning/codebase/`.
|
||||
- How `/msd-new-project` in a brownfield repo focuses questions on what you are *adding* and populates Validated requirements from existing code.
|
||||
- How the codebase map shapes every question in `/msd-discuss-phase` — file paths, patterns, and conventions come from your actual code.
|
||||
- How the planner reads `CONTEXT.md` plus `CONVENTIONS.md` to produce plans that match your repo's style.
|
||||
|
||||
---
|
||||
@@ -258,5 +258,5 @@ For every future feature, run `/gsd-map-codebase` again whenever the structure c
|
||||
## Related
|
||||
|
||||
- [Your first project](your-first-project.md) — the full greenfield loop from install to PR
|
||||
- [Commands](../COMMANDS.md) — `/gsd-onboard`, plus all `/gsd-map-codebase` flags and subcommands
|
||||
- [Commands](../COMMANDS.md) — `/msd-onboard`, plus all `/msd-map-codebase` flags and subcommands
|
||||
- [Documentation index](../README.md)
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
> [!TIP]
|
||||
> **This is the one guaranteed path.** You will build a tiny app, run **every**
|
||||
> command in the core loop exactly once, and — the part most tutorials skip —
|
||||
> understand *why* each step exists. This tutorial uses **Claude Code**; GSD
|
||||
> understand *why* each step exists. This tutorial uses **Claude Code**; MSD
|
||||
> works in 15+ runtimes — see [Install on your runtime](../how-to/install-on-your-runtime.md)
|
||||
> for the flag and command syntax for yours.
|
||||
|
||||
@@ -23,10 +23,10 @@
|
||||
|
||||
## 📖 Table of contents
|
||||
|
||||
1. [The one idea that makes GSD click](#-the-one-idea-that-makes-gsd-click)
|
||||
1. [The one idea that makes MSD click](#-the-one-idea-that-makes-msd-click)
|
||||
2. [What you'll build](#-what-youll-build)
|
||||
3. [Prerequisites](#-prerequisites)
|
||||
4. [Step 1 — Install GSD Core](#step-1--install-gsd-core-into-your-runtime)
|
||||
4. [Step 1 — Install MSD Core](#step-1--install-msd-core-into-your-runtime)
|
||||
5. [Step 2 — Open Claude Code](#step-2--open-claude-code)
|
||||
6. [Step 3 — Create the project](#step-3--create-the-project)
|
||||
7. [Step 4 — Discuss Phase 1](#step-4--clear-context-then-discuss-phase-1)
|
||||
@@ -38,12 +38,12 @@
|
||||
|
||||
---
|
||||
|
||||
## 💡 The one idea that makes GSD click
|
||||
## 💡 The one idea that makes MSD click
|
||||
|
||||
GSD Core does **not** "write your whole app in one shot." It runs a **repeating
|
||||
MSD Core does **not** "write your whole app in one shot." It runs a **repeating
|
||||
five-step loop**, and it does the heavy thinking in **fresh, throwaway
|
||||
sub-agents** so your main chat window never fills up with clutter — the quality
|
||||
killer GSD calls [context rot](../explanation/context-engineering.md).
|
||||
killer MSD calls [context rot](../explanation/context-engineering.md).
|
||||
|
||||
You drive that loop **one phase at a time**:
|
||||
|
||||
@@ -60,11 +60,11 @@ flowchart LR
|
||||
|
||||
| Step | Command | In one sentence | Typical time |
|
||||
|:----:|---------|-----------------|:------------:|
|
||||
| 💬 **Discuss** | `/gsd-discuss-phase` | GSD asks *how* to build it and writes your answers down. | 2–4 min |
|
||||
| 📐 **Plan** | `/gsd-plan-phase` | GSD splits the work into small, checkable task plans. | 1–5 min |
|
||||
| ⚙️ **Execute** | `/gsd-execute-phase` | Fresh agents write the code and commit each task. | 2–6 min |
|
||||
| ✅ **Verify** | `/gsd-verify-work` | GSD walks you through "does it actually work?" | 1–3 min |
|
||||
| 🚀 **Ship** | `/gsd-ship` | A pull request is opened for you. | <1 min |
|
||||
| 💬 **Discuss** | `/msd-discuss-phase` | MSD asks *how* to build it and writes your answers down. | 2–4 min |
|
||||
| 📐 **Plan** | `/msd-plan-phase` | MSD splits the work into small, checkable task plans. | 1–5 min |
|
||||
| ⚙️ **Execute** | `/msd-execute-phase` | Fresh agents write the code and commit each task. | 2–6 min |
|
||||
| ✅ **Verify** | `/msd-verify-work` | MSD walks you through "does it actually work?" | 1–3 min |
|
||||
| 🚀 **Ship** | `/msd-ship` | A pull request is opened for you. | <1 min |
|
||||
|
||||
> [!NOTE]
|
||||
> **Keep that table handy.** Whenever you feel lost, ask yourself one question:
|
||||
@@ -76,7 +76,7 @@ flowchart LR
|
||||
<br>
|
||||
|
||||
A single long chat slowly degrades: the more it holds, the more the model
|
||||
juggles, and quality quietly drops. GSD sidesteps this by spawning a **clean
|
||||
juggles, and quality quietly drops. MSD sidesteps this by spawning a **clean
|
||||
200k-token worker** for each heavy job (research, execution) and throwing it away
|
||||
after. Your main session stays lean; the shared `.planning/` files carry memory
|
||||
between them.
|
||||
@@ -84,7 +84,7 @@ between them.
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph main [Your main session · stays lean]
|
||||
you([You + GSD])
|
||||
you([You + MSD])
|
||||
end
|
||||
subgraph workers [Fresh sub-agents · clean context each time]
|
||||
r1[Researcher]
|
||||
@@ -116,7 +116,7 @@ todo done 1 # ✅ complete item 1
|
||||
```
|
||||
|
||||
Items live in a local `todos.json`. It uses **only the Node.js standard library**
|
||||
— nothing to install, nothing to configure — so you focus entirely on the GSD
|
||||
— nothing to install, nothing to configure — so you focus entirely on the MSD
|
||||
loop, not a toolchain.
|
||||
|
||||
> [!TIP]
|
||||
@@ -141,8 +141,8 @@ If you do not already have an empty repository, create and clone one now. If
|
||||
`gh auth status` says you are not logged in, run `gh auth login` first.
|
||||
|
||||
```bash
|
||||
gh repo create gsd-todo-tutorial --private --clone
|
||||
cd gsd-todo-tutorial
|
||||
gh repo create msd-todo-tutorial --private --clone
|
||||
cd msd-todo-tutorial
|
||||
git remote get-url origin
|
||||
```
|
||||
|
||||
@@ -164,20 +164,20 @@ flowchart LR
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Install GSD Core into your runtime
|
||||
## Step 1 — Install MSD Core into your runtime
|
||||
|
||||
From a terminal **in your project directory**, run the installer:
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --claude --local
|
||||
npx @golem15/msd-core@latest --claude --local
|
||||
```
|
||||
|
||||
This tutorial uses `--local`, so GSD is installed only in this project. On a
|
||||
This tutorial uses `--local`, so MSD is installed only in this project. On a
|
||||
different runtime? See [Install on your runtime](../how-to/install-on-your-runtime.md)
|
||||
for its flag. You'll see a summary of what was installed, e.g.:
|
||||
|
||||
```text
|
||||
✓ Installed 71 commands to commands/ (gsd-<cmd>.md flat form)
|
||||
✓ Installed 71 commands to commands/ (msd-<cmd>.md flat form)
|
||||
✓ Installed agents
|
||||
```
|
||||
|
||||
@@ -188,7 +188,7 @@ Then **restart Claude Code** so it picks up the new commands and agents.
|
||||
|
||||
<br>
|
||||
|
||||
A `.claude/` directory in your project now holds GSD's **commands** and
|
||||
A `.claude/` directory in your project now holds MSD's **commands** and
|
||||
**agents**. You never edit these by hand — the installer owns them and keeps them
|
||||
in Claude Code's native format.
|
||||
|
||||
@@ -214,7 +214,7 @@ You'll land at a prompt ready for input.
|
||||
|
||||
> [!CAUTION]
|
||||
> **The permissions flag is optional.** It skips per-file confirmation while
|
||||
> GSD's sub-agents read and write files. Use it only for this throwaway tutorial
|
||||
> MSD's sub-agents read and write files. Use it only for this throwaway tutorial
|
||||
> in an empty folder. To keep confirmations enabled, start with `claude` instead.
|
||||
> For real work, read the [security model](../explanation/security-model.md) first.
|
||||
|
||||
@@ -223,8 +223,8 @@ You'll land at a prompt ready for input.
|
||||
|
||||
<br>
|
||||
|
||||
Claude Code opened in the project where Step 1 installed GSD. It loaded the
|
||||
project-local `.claude/` commands and agents, so `/gsd-*` commands are now
|
||||
Claude Code opened in the project where Step 1 installed MSD. It loaded the
|
||||
project-local `.claude/` commands and agents, so `/msd-*` commands are now
|
||||
available at the prompt.
|
||||
|
||||
</details>
|
||||
@@ -236,7 +236,7 @@ available at the prompt.
|
||||
At Claude Code's prompt:
|
||||
|
||||
```text
|
||||
/gsd-new-project
|
||||
/msd-new-project
|
||||
```
|
||||
|
||||
The first question is always **"What do you want to build?"** Paste this:
|
||||
@@ -277,7 +277,7 @@ flowchart TD
|
||||
class root,PROJECT,REQ,ROAD,STATE,CFG f;
|
||||
```
|
||||
|
||||
These files are GSD's **shared memory** — they survive `/clear`, survive closing
|
||||
These files are MSD's **shared memory** — they survive `/clear`, survive closing
|
||||
your laptop, and let a fresh sub-agent pick up exactly where the last left off.
|
||||
|
||||
</details>
|
||||
@@ -290,7 +290,7 @@ must deliver. This file is your map for the rest of the tutorial.
|
||||
|
||||
## Step 4 — Clear context, then discuss Phase 1
|
||||
|
||||
GSD is built around **fresh contexts**. Clear the window before each phase:
|
||||
MSD is built around **fresh contexts**. Clear the window before each phase:
|
||||
|
||||
```text
|
||||
/clear
|
||||
@@ -299,10 +299,10 @@ GSD is built around **fresh contexts**. Clear the window before each phase:
|
||||
Then open the discussion:
|
||||
|
||||
```text
|
||||
/gsd-discuss-phase 1
|
||||
/msd-discuss-phase 1
|
||||
```
|
||||
|
||||
GSD asks about your **implementation preferences** — *how* to build, not just
|
||||
MSD asks about your **implementation preferences** — *how* to build, not just
|
||||
*what*:
|
||||
|
||||
```text
|
||||
@@ -329,7 +329,7 @@ into the task plans.
|
||||
|
||||
<br>
|
||||
|
||||
`/clear` discarded the old chat context, then `/gsd-discuss-phase 1` captured
|
||||
`/clear` discarded the old chat context, then `/msd-discuss-phase 1` captured
|
||||
your implementation choices in `01-CONTEXT.md`. The next planner receives those
|
||||
decisions without needing the earlier conversation.
|
||||
|
||||
@@ -340,25 +340,25 @@ decisions without needing the earlier conversation.
|
||||
## Step 5 — Plan Phase 1
|
||||
|
||||
```text
|
||||
/gsd-plan-phase 1
|
||||
/msd-plan-phase 1
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant You
|
||||
participant GSD
|
||||
participant MSD
|
||||
participant PL as Planner
|
||||
participant PC as Plan-checker
|
||||
You->>GSD: /gsd-plan-phase 1
|
||||
GSD->>You: Research before planning Phase 1: Core CLI?
|
||||
You->>GSD: Skip research
|
||||
GSD->>PL: 01-CONTEXT.md
|
||||
PL-->>GSD: atomic task plans
|
||||
GSD->>PC: verify each plan hits the goal
|
||||
You->>MSD: /msd-plan-phase 1
|
||||
MSD->>You: Research before planning Phase 1: Core CLI?
|
||||
You->>MSD: Skip research
|
||||
MSD->>PL: 01-CONTEXT.md
|
||||
PL-->>MSD: atomic task plans
|
||||
MSD->>PC: verify each plan hits the goal
|
||||
PC-->>You: plans saved ✓
|
||||
```
|
||||
|
||||
GSD asks **"Research before planning Phase 1: Core CLI?"** — choose **Skip research** (same
|
||||
MSD asks **"Research before planning Phase 1: Core CLI?"** — choose **Skip research** (same
|
||||
as Step 3; this build is small and well-understood). A **planner** then turns
|
||||
`01-CONTEXT.md` into **atomic task plans**, and a **plan-checker** verifies each
|
||||
before saving.
|
||||
@@ -385,10 +385,10 @@ That `<verify>` isn't decoration — the executor runs it after writing code.
|
||||
## Step 6 — Execute Phase 1
|
||||
|
||||
```text
|
||||
/gsd-execute-phase 1
|
||||
/msd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD groups plans into **waves** (independent plans run in parallel), spawns a
|
||||
MSD groups plans into **waves** (independent plans run in parallel), spawns a
|
||||
**fresh 200k-context executor per plan**, and commits each task atomically:
|
||||
|
||||
```text
|
||||
@@ -433,10 +433,10 @@ node todo.js list # → only "write tests"
|
||||
## Step 7 — Verify the work
|
||||
|
||||
```text
|
||||
/gsd-verify-work 1
|
||||
/msd-verify-work 1
|
||||
```
|
||||
|
||||
GSD reads the phase's `SUMMARY.md` files and turns their user-visible
|
||||
MSD reads the phase's `SUMMARY.md` files and turns their user-visible
|
||||
deliverables into checkpoints. It presents one checkpoint at a time; the first
|
||||
one looks like this (the test wording depends on what was built):
|
||||
|
||||
@@ -452,11 +452,11 @@ Running `node todo.js add "buy milk"` creates a pending item without errors.
|
||||
**Type `pass` or describe what's wrong.**
|
||||
```
|
||||
|
||||
Type `pass` when reality matches, or describe what differs. GSD records the
|
||||
Type `pass` when reality matches, or describe what differs. MSD records the
|
||||
answer in `01-UAT.md` and then presents the next checkpoint.
|
||||
|
||||
If a check **fails**, GSD diagnoses the root cause and writes a fix plan → re-run
|
||||
`/gsd-execute-phase 1`, then `/gsd-verify-work 1` again. (Result:
|
||||
If a check **fails**, MSD diagnoses the root cause and writes a fix plan → re-run
|
||||
`/msd-execute-phase 1`, then `/msd-verify-work 1` again. (Result:
|
||||
`.planning/phases/01-core-cli/01-UAT.md`.)
|
||||
|
||||
> [!NOTE]
|
||||
@@ -468,7 +468,7 @@ If a check **fails**, GSD diagnoses the root cause and writes a fix plan → re-
|
||||
|
||||
<br>
|
||||
|
||||
GSD turned the phase summaries into user-visible checks, recorded your answers
|
||||
MSD turned the phase summaries into user-visible checks, recorded your answers
|
||||
in `01-UAT.md`, and routed any failure back through a concrete fix plan. Shipping
|
||||
only starts after those checks match reality.
|
||||
|
||||
@@ -479,10 +479,10 @@ only starts after those checks match reality.
|
||||
## Step 8 — Ship it
|
||||
|
||||
```text
|
||||
/gsd-ship 1
|
||||
/msd-ship 1
|
||||
```
|
||||
|
||||
GSD creates a pull request with a generated body (Summary · Changes ·
|
||||
MSD creates a pull request with a generated body (Summary · Changes ·
|
||||
Requirements Addressed · Verification · Key Decisions):
|
||||
|
||||
```text
|
||||
@@ -510,7 +510,7 @@ flowchart LR
|
||||
|
||||
<br>
|
||||
|
||||
`/gsd-ship 1` assembled the completed phase's requirements, decisions, and
|
||||
`/msd-ship 1` assembled the completed phase's requirements, decisions, and
|
||||
verification evidence into a pull request. The PR is open for review; nothing
|
||||
has been merged into the default branch yet.
|
||||
|
||||
@@ -521,24 +521,24 @@ has been merged into the default branch yet.
|
||||
## 🔁 Doing more than one phase
|
||||
|
||||
For a multi-phase project, repeat **Steps 4–8** for each phase. Not sure what's
|
||||
next? Let GSD detect it:
|
||||
next? Let MSD detect it:
|
||||
|
||||
```text
|
||||
/gsd-progress --next
|
||||
/msd-progress --next
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Mini-glossary
|
||||
|
||||
| Term | Meaning in GSD |
|
||||
| Term | Meaning in MSD |
|
||||
|------|----------------|
|
||||
| **Runtime** | Your AI coding tool. This tutorial uses Claude Code. |
|
||||
| **Phase** | One slice of the roadmap you take through the whole loop. |
|
||||
| **The loop** | Discuss → Plan → Execute → Verify → Ship. |
|
||||
| **Sub-agent** | A fresh, throwaway worker GSD spawns for research or execution. |
|
||||
| **Sub-agent** | A fresh, throwaway worker MSD spawns for research or execution. |
|
||||
| **Context rot** | Quality decay as the main window fills up; fresh sub-agents prevent it. |
|
||||
| **`.planning/`** | GSD's shared memory: PROJECT, REQUIREMENTS, ROADMAP, STATE, per-phase files. |
|
||||
| **`.planning/`** | MSD's shared memory: PROJECT, REQUIREMENTS, ROADMAP, STATE, per-phase files. |
|
||||
| **Requirement (REQ-ID)** | A single v1 capability the roadmap must cover, e.g. `CLI-01`. |
|
||||
| **Success criteria** | Observable behaviors a phase must deliver, checked in Verify. |
|
||||
| **Wave** | A batch of independent task plans executed in parallel. |
|
||||
@@ -549,10 +549,10 @@ next? Let GSD detect it:
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---------|--------------|-----|
|
||||
| A GSD command isn't recognized | Claude Code not restarted after install | Restart Claude Code so it loads the new `/gsd-*` commands. |
|
||||
| A MSD command isn't recognized | Claude Code not restarted after install | Restart Claude Code so it loads the new `/msd-*` commands. |
|
||||
| `Spawning researchers…` looks stuck | Research runs 1–5 min | Wait — don't interrupt. If truly hung, `/clear` and re-run the step. |
|
||||
| Verify keeps failing | Real bug in the code | Let GSD write the fix plan → `/gsd-execute-phase 1` → re-verify. |
|
||||
| Lost track of where you are | — | Open `.planning/STATE.md`, or run `/gsd-progress --next`. |
|
||||
| Verify keeps failing | Real bug in the code | Let MSD write the fix plan → `/msd-execute-phase 1` → re-verify. |
|
||||
| Lost track of where you are | — | Open `.planning/STATE.md`, or run `/msd-progress --next`. |
|
||||
| Wrong install directory | Alternate/prerelease Claude Code config dir | Set `CLAUDE_CONFIG_DIR` to match — see [Install on your runtime](../how-to/install-on-your-runtime.md). |
|
||||
|
||||
---
|
||||
@@ -563,8 +563,8 @@ next? Let GSD detect it:
|
||||
- [The phase loop](../explanation/the-phase-loop.md) — why it's shaped this way
|
||||
- [Context engineering](../explanation/context-engineering.md) — the theory behind fresh sub-agents
|
||||
- [Configure model profiles](../how-to/configure-model-profiles.md) — quality / balanced / budget tiers
|
||||
- [Onboarding an existing codebase](onboarding-an-existing-codebase.md) — bring GSD to a brownfield repo
|
||||
- [Onboarding an existing codebase](onboarding-an-existing-codebase.md) — bring MSD to a brownfield repo
|
||||
|
||||
> [!TIP]
|
||||
> **You now know the whole loop.** Everything else in GSD is a refinement of these
|
||||
> **You now know the whole loop.** Everything else in MSD is a refinement of these
|
||||
> eight steps. Welcome aboard. 🚀
|
||||
|
||||
Reference in New Issue
Block a user