golem15/msd-core
4
0
Fork 0
Code Issues Pull Requests Actions 1 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

120
docs/tutorials/your-first-project.md
View File

@@ -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. 🚀