e7ed5b4c9f
Some checks failed
Tests / plugin-validate (push) Successful in 1m7s
Tests / test (inert CI) (push) Has been skipped
Tests / Required tests (push) Has been cancelled
Tests / PR mergeability (push) Successful in 23s
Tests / Detect test scope (push) Successful in 19s
Tests / lint-tests (push) Failing after 2m13s
Tests / Base branch health (push) Successful in 12s
Tests / test (ubuntu-latest, 24, shard 1/3) (push) Failing after 23s
Tests / test (ubuntu-latest, 24, shard 2/3) (push) Failing after 22s
Tests / test (ubuntu-latest, 24, shard 3/3) (push) Failing after 22s
Tests / test (ubuntu-latest, 24) (push) Failing after 21s
Tests / QA loop walk (smell ratchet) (push) Failing after 20s
Tests / Coverage gate (merged shards) (push) Has been skipped
Tests / Publish emitted-baseline artifact (push) Has been skipped
Branch Cleanup / Delete merged PR branch (push) Has been skipped
Branch Cleanup / Weekly orphaned branch sweep (push) Successful in 10s
Tests / conformance test (macos-latest, 24) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 1/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 2/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 3/3) (push) Has been cancelled
Stale Cleanup / stale (push) Successful in 13s
Stale Cleanup / stale-retest (push) Successful in 10s
CI timeout budget report / report (push) Failing after 15s
Dismiss Unauthorized PR Approvals / dismiss-unauthorized-approval (push) Successful in 9s
173 lines
8.8 KiB
Markdown
173 lines
8.8 KiB
Markdown
<div align="center">
|
|
|
|
# MSD Core
|
|
|
|
**Make Software Done.**
|
|
|
|
**English** · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
|
|
|
|
**A light-weight meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Antigravity CLI, Codex, Cursor, and more.**
|
|
|
|
[](LICENSE)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## What is MSD Core
|
|
|
|
MSD Core is a context-engineering and spec-driven development framework that drives AI coding agents (Claude Code, Codex, Antigravity CLI, Cursor, and more) through a disciplined phase loop. It solves [context rot](docs/explanation/context-engineering.md) — the quality degradation that accumulates as an AI fills its context window — by running all heavy research, planning, and execution work in fresh-context subagents while keeping your main session lean.
|
|
|
|
---
|
|
|
|
## Differences from GSD
|
|
|
|
MSD Core is a hard fork of [GSD](https://github.com/open-gsd/gsd-core) (`gsd-core`). It contains all GSD changes up to the fork point (everything after GSD 1.14.0 shipped in MSD 2.0.0). The phase loop, workflows and `.planning/` artifacts work the same way. What differs:
|
|
|
|
| | GSD | MSD |
|
|
|---|---|---|
|
|
| **Name** | `/gsd-*` commands, `gsd-tools` CLI, `gsd-core` package | `/msd-*` commands, `msd-tools` CLI, `@golem15/msd-core` package |
|
|
| **Runtimes** | 18 runtimes | 6: Claude Code, Codex, OpenCode, Cursor, ZCode, Antigravity. The other 12 (including Kimi) were removed, together with their installer code, capabilities, hooks and docs |
|
|
| **Distribution** | npm package | Not on npm. Installed with `curl -fsSL https://msd.golem15.com \| bash`, which clones, builds and installs from git |
|
|
| **Releases and updates** | npm versions | `vX.Y.Z` git tags on `next`, with a `stable` branch pointing at the latest one. `/msd-update` and the update check read those tags and rerun the installer pinned to the chosen version. `/msd-update --next` also considers `-rc.N` tags |
|
|
| **Hosting** | GitHub, with issue and PR governance | [git.golem15.com/golem15/msd-core](https://git.golem15.com/golem15/msd-core) (Gitea). PRs go against `next`, and GSD's issue and PR governance workflows were dropped |
|
|
|
|
### Fixes that exist only in MSD
|
|
|
|
**UAT verification loops (2.0.1).** In GSD, a phase whose human UAT had passed could loop forever between `/gsd-execute-phase` and `/gsd-verify-work`. A gap-closure plan, or a later phase editing a covered file, made the verification report stale. The re-run verifier could not see the UAT results and asked for human verification again, and execute-phase then rewrote `*-UAT.md` with every row back to `[pending]`. MSD fixes each link in that chain:
|
|
|
|
- **The verifier reads recorded UAT results as evidence** (`verification.uat-evidence`). A row that passed on unchanged code counts as verified. Only rows whose covered implementation files changed since the UAT are requested again, each with a `retest_reason`.
|
|
- **`*-UAT.md` is merged, never overwritten** (`verification.seed-uat`). Existing rows are kept byte-for-byte, and a pass is reset only with a recorded reason.
|
|
- **One guarded `human_needed` → `passed` transition** (`verification.canonicalize-uat`). It applies only when the UAT rows are the only outstanding items, and it refuses a stale report.
|
|
- **Stale reports are re-verified in place.** `verify-work` and `progress` re-run the verifier themselves instead of routing back to `execute-phase`. `verification.status` reports a `stale_reason`, and `progress` offers every executed-but-stale phase as one re-verify action.
|
|
- **Gap-closure UAT answers are recorded first.** `execute-phase` writes a gap-closure checkpoint's UAT answers before it dispatches the verifier.
|
|
|
|
Staleness still fails closed: a malformed fingerprint or a real change to covered code still marks the report stale.
|
|
|
|
**Other fixes:**
|
|
|
|
- **`/msd-update` and the update check work.** The inherited npm-based check looked for a package that was never published, so it never found an update. MSD reads git release tags instead.
|
|
- **Plan-phase quota recovery.** `/msd-plan-phase` recovers safely when an agent run hits provider quota exhaustion.
|
|
|
|
See [CHANGELOG.md](CHANGELOG.md) for the full 2.0.0 entry.
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
Each milestone repeats the same five-step loop, one phase at a time:
|
|
|
|
1. **Discuss** — capture implementation decisions before anything is planned
|
|
2. **Plan** — research, decompose, and verify the plan fits a fresh context window
|
|
3. **Execute** — run plans in parallel waves; each executor starts with a clean 200k-token context
|
|
4. **Verify** — walk through what was built; diagnose and fix before declaring done
|
|
5. **Ship** — create the PR, archive the phase, repeat for the next one
|
|
|
|
---
|
|
|
|
## Quickstart
|
|
|
|
MSD Core is not published to npm. Install the latest release (needs Node.js 24+, git and jq) with:
|
|
|
|
```bash
|
|
curl -fsSL https://msd.golem15.com | bash
|
|
```
|
|
|
|
This installs Claude Code if it is missing, clones MSD into `~/.local/share/msd-core` at the `stable` branch (the latest tagged release), builds it and installs it globally for Claude Code. Rerun the same command, or `/msd-update` inside your runtime, to update. Options go after `bash -s --`:
|
|
|
|
```bash
|
|
curl -fsSL https://msd.golem15.com | bash -s -- --claude --codex # several runtimes
|
|
curl -fsSL https://msd.golem15.com | bash -s -- --local # into the current project only
|
|
curl -fsSL https://msd.golem15.com | bash -s -- --ref next # unreleased work from next
|
|
```
|
|
|
|
From a checkout of this repository you can also run the installer directly:
|
|
|
|
```bash
|
|
git clone https://git.golem15.com/golem15/msd-core.git
|
|
cd msd-core && npm ci && npm run build:hooks
|
|
node bin/install.js --claude --global
|
|
```
|
|
|
|
For any other runtime, run `node bin/install.js` directly. The installer prompts for your runtime (Claude Code, OpenCode, Antigravity CLI, Codex, Cursor, and more) and whether to install globally or locally. The installer is required for cross-runtime compatibility — do not copy files from `agents/` or `commands/` directly.
|
|
|
|
On another runtime or without Node.js? See [Install on your runtime](docs/how-to/install-on-your-runtime.md).
|
|
|
|
Once installed, start a new project or onboard an existing repo:
|
|
|
|
```bash
|
|
/msd-new-project # greenfield project
|
|
/msd-onboard # existing codebase
|
|
```
|
|
|
|
New here? Follow [Your first project](docs/tutorials/your-first-project.md) for a guided walkthrough from install to first shipped phase, or [Onboarding an existing codebase](docs/tutorials/onboarding-an-existing-codebase.md) for brownfield setup.
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
**What's new in 1.7.0** → [docs/whats-new-1.7.0.md](docs/whats-new-1.7.0.md)
|
|
|
|
**Tutorials** — learning by doing:
|
|
- [Your first project](docs/tutorials/your-first-project.md)
|
|
- [Onboarding an existing codebase](docs/tutorials/onboarding-an-existing-codebase.md)
|
|
|
|
**How-to guides** — task-focused recipes:
|
|
- [Install on your runtime](docs/how-to/install-on-your-runtime.md)
|
|
- [Plan a phase](docs/how-to/plan-a-phase.md)
|
|
- [Verify and ship](docs/how-to/verify-and-ship.md)
|
|
- … [see all how-to guides](docs/README.md#how-to-guides)
|
|
|
|
**Reference** — authoritative facts:
|
|
- [Commands](docs/COMMANDS.md)
|
|
- [Configuration](docs/CONFIGURATION.md)
|
|
- [CLI tools](docs/CLI-TOOLS.md)
|
|
|
|
**Explanation** — concepts and design decisions:
|
|
- [Context engineering](docs/explanation/context-engineering.md)
|
|
- [The phase loop](docs/explanation/the-phase-loop.md)
|
|
- [Architecture](docs/ARCHITECTURE.md)
|
|
|
|
Full index: [docs/README.md](docs/README.md). Other languages: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md).
|
|
|
|
---
|
|
|
|
## Why it works
|
|
|
|
Most AI-coding setups fail at scale because context bloat silently degrades output quality, there is no shared memory between sessions, and nothing verifies that code actually works. MSD Core solves all three: heavy work runs in fresh subagents, structured artifacts like `STATE.md` and `CONTEXT.md` survive session boundaries, and the verify step walks through what was built and generates fix plans before a phase is declared done. See [docs/explanation/context-engineering.md](docs/explanation/context-engineering.md) for the full reasoning.
|
|
|
|
Troubleshooting? See [docs/how-to/recover-and-troubleshoot.md](docs/how-to/recover-and-troubleshoot.md).
|
|
|
|
---
|
|
|
|
## Community
|
|
|
|
| Project | Platform |
|
|
|---------|----------|
|
|
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | Original OpenCode port |
|
|
| [Discord](https://discord.gg/mYgfVNfA2r) | Community support |
|
|
|
|
---
|
|
|
|
## What MSD stands for
|
|
|
|
**Make Software Done.** The runners-up, preserved for posterity:
|
|
|
|
- Mostly Sane Development
|
|
- Minimum Suffering Delivery
|
|
- Merge, Ship, Disappear
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT License. See [LICENSE](LICENSE) for details.
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**Claude Code is powerful. MSD Core makes it reliable.**
|
|
|
|
</div>
|