msd-core/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

`@golem15/msd-core` (MSD) is a meta-prompting / spec-driven development system for AI coding agents, a fork of open-gsd `gsd-core` that was renamed GSD → MSD. Most of the product is **prompt text** (slash commands, workflows, agents) plus a Node CLI (`msd-tools`) that the prompts shell out to for state, config, phase and git work. An installer copies or converts this content into each supported runtime: Claude Code, Codex, OpenCode, Cursor, ZCode and Antigravity. Other runtimes were removed on purpose, and `lint:retired-runtime-name` guards against re-adding their names.

Before you name or refactor modules, read `CONTEXT.md`, the canonical domain vocabulary. Its predicates are cited by ID, so don't paraphrase them. Also check `docs/adr/`. The architecture deep-dive is `docs/ARCHITECTURE.md`.

## Commands

Node ≥ 24 (`.nvmrc`). Install with `npm ci`, not `npm install`.

```bash
npm run build:lib          # tsc: src/*.cts -> msd-core/bin/lib/*.cjs (required before running anything)
npm run build              # full build: lib + generated manifests/indexes/skills/hooks
npm test                   # all suites (pretest runs build:lib + lint:skill-deps)
npm run test:unit          # also: test:integration, test:install, test:security, test:slow, test:qa
npm run test:affected      # only tests affected by your changes
node --test tests/foo.test.cjs                          # single file (run build:lib first)
node scripts/run-tests.cjs --files "tests/a.test.cjs tests/b.test.cjs"
npm run lint               # eslint, --max-warnings 0
npm run lint:ci            # the full CI lint battery (drift/parity/seam linters)
npm run lint:generated-sync  # verifies every generated artifact is up to date (--check mode)
npm run regen:derived      # regenerate all derived files after changing their sources
npm run check:alias-drift  # after touching src/command-aliases.cts or src/*-command-router.cts
npm run changeset -- --type Fixed --pr <N> --body "..."  # changelog fragment
```

The test suite comes from the filename suffix: `foo.security.test.cjs` → `security`, and a plain `foo.test.cjs` → `unit`. See `docs/TESTING-SUITES.md`.

## Architecture

- **`commands/msd/*.md`**: slash-command definitions, the source of truth. `skills/msd-*/SKILL.md` is **generated** from them (`gen:plugin-skills`), so never edit `skills/` by hand.
- **`msd-core/workflows/*.md`**: the workflow bodies that commands dispatch to. Large workflows use progressive disclosure: `workflows/<name>/modes/*.md`, with `discuss-phase/` as the canonical example. Workflows are thin orchestrators that spawn agents with fresh context, and state lives in files under the user project's `.planning/` (STATE.md, ROADMAP.md, phases/).
- **`agents/*.md`**: subagent definitions, the canonical source. `.claude/agents/`, `.cursor/agents/` and `.github/agents/msd-*` are gitignored install outputs, so never edit them.
- **`msd-core/references/`, `templates/`, `contexts/`**: shared reference text and templates loaded by workflows.
- **`src/*.cts` → `msd-core/bin/lib/*.cjs`** (ADR-457, "build-at-publish"): the core library is TypeScript compiled to CommonJS, and the compiled `.cjs` files are **gitignored**. Edit `src/`, never the generated `.cjs`. A handful of `bin/lib/*.cjs` files are still tracked: some are hand-written and some are generated-and-committed (`capability-registry.cjs`, `package-identity.cjs`, `loop-host-contract.cjs`, `vendor/`). Run `git ls-files msd-core/bin/lib` to tell which is which.
- **`msd-core/bin/msd-tools.cjs`**: the CLI the prompts call (`state …`, `phase …`, `resolve-model`, `init …`, `commit`, and more). Subcommands go through `command-routing-hub` and the per-family `src/*-command-router.cts` + `src/command-aliases.cts`, and the alias drift check keeps these in sync.
- **`capabilities/<id>/capability.json`**: optional feature/runtime modules (tdd, security, code-review, mempalace, per-runtime ones such as `claude`, `codex`, …). They declare config keys, contributions to workflow steps, hooks and agents. The aggregated registry `msd-core/bin/lib/capability-registry.cjs` is generated (`gen:capability-registry`).
- **`hooks/`**: runtime hooks (prompt/read guards, context monitor, commit validation, …), built into `hooks/dist` by `build:hooks`.
- **`bin/install.js`**: the multi-runtime installer that converts and copies commands, agents, skills and hooks into each runtime's config dir.
- **`scripts/`**: build, generate and lint tooling. Many `gen-*.cjs` scripts support `--write` and `--check`, and CI runs them all in `--check`.

Generated artifacts are everywhere (skills, registries, `docs/INVENTORY-MANIFEST.json`, `docs/CONTEXT-INDEX.json`, `FEATURES.md`, exit-code docs, …). If you change a source that feeds one, regenerate it (`npm run regen:derived` or the specific `gen:*` script), or `lint:generated-sync` will fail.

## Coding rules (from CONTRIBUTING.md / .clinerules)

- CommonJS runtime (`require`). Core lib/CLI use **Node built-ins only**, with no runtime npm deps in core (vendored deps sit in `bin/lib/vendor/`).
- To spawn a process, use `execFileSync` with array args, never `execSync` with string interpolation. Validate user-provided paths with `validatePath()` (security module).
- Tests use **`node:test` + `node:assert/strict` only**. Use `tests/helpers.cjs` (`createTempProject`, `createTempGitProject`, `cleanup`, `runMsdTools`) and spawn subprocesses through `tests/helpers/process-seam.cjs`. Clean up with `beforeEach`/`afterEach` or `t.after()`, never `try/finally` in a test body.
- **No source-grep tests and no raw-text matching on outputs** (stdout, rendered files, reason strings). Assert on structured values: `--json` modes, frozen reason enums, builder IRs. This is enforced by the `local/no-source-grep` ESLint rule. Exemptions need an `allow-test-rule: <reason>` annotation (for example `source-text-is-the-product` for `.md` prompt content).
- Changes to shipped prompt content (workflows, agents, commands) are checked by `tests/emitted-attribution.test.cjs`, and size budgets exist (`workflow-size-budget`, `agent-size-budget`). If emitted bytes move for a reason the diff doesn't show, add a commit trailer: `Emitted-Drift-Ack-Hash:` / `Emitted-Drift-Ack-Growth: <path> — <why>`.
- Commits follow conventional format `<type>(<scope>): <subject>`, with the subject ≤72 chars, lowercase, imperative and without a trailing period (enforced by `hooks/msd-validate-commit.sh`). Put the test-fixture correction in its own `test:` commit.
- A PR that touches `bin/`, `msd-core/`, `src/`, `agents/`, `commands/` or `hooks/` needs a `.changeset/*.md` fragment. Never edit `CHANGELOG.md` directly.
- Branching: feature branches open PRs against `next` on git.golem15.com (Gitea; use `tea`, not `gh`). There is no `main`. `.githooks/` contains pre-commit (alias drift) and pre-push gates.

## Distribution and releases

MSD is **not on npm**; the inherited `.github/workflows/release.yml` npm pipeline does not apply to this fork.
- Users install with `curl -fsSL https://msd.golem15.com | bash` (`scripts/bootstrap.sh`). It clones into `~/.local/share/msd-core`, builds, and runs `bin/install.js`. A Cloudflare Worker (`msd-installer`) serves the script from the `stable` branch.
- A release is a `vX.Y.Z` tag on `next`, after which the `stable` branch is moved to that tag. `/msd-update` and the SessionStart update check find the latest version from those tags (`msd-core/bin/check-latest-version.cjs`, `git ls-remote`), then rerun the bootstrap installer pinned with `--ref vX.Y.Z`.
- The repository URL and manual-install command come from the generated Package Identity seam (`scripts/generate-package-identity.cjs` → `msd-core/bin/lib/package-identity.cjs`), derived from `package.json`.