golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: hard-fork GSD -> MSD (Make Software Done)

Browse Source 
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
2026-10-06 01:47:40 +02:00
parent fe069b2a56
commit a9a7a328e6
2763 changed files with 78465 additions and 78434 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/tutorials/onboarding-an-existing-codebase.md
View File

@@ -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)