a9a7a328e6
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.
5.5 KiB
How to migrate from GSD-2
Goal: Bring an older GSD-2 project (.gsd/ directory layout) forward into MSD Core (.planning/ layout), and optionally absorb any existing ADRs, PRDs, or specs that live in the repository into the new planning structure.
Prerequisites: MSD Core is installed. The GSD-2 project directory is available on disk.
Understand what migrates
GSD-2 used a .gsd/ directory as its planning root. MSD Core uses .planning/. The migration reverses this: it reads .gsd/ artifacts and writes them into the standard .planning/ structure that all MSD Core commands expect.
| What exists in GSD-2 | What /msd-import --from-gsd2 produces |
|---|---|
.gsd/PROJECT.md |
.planning/PROJECT.md |
.gsd/ROADMAP.md |
.planning/ROADMAP.md |
.gsd/STATE.md |
.planning/STATE.md |
.gsd/phases/ directories |
.planning/phases/ directories |
Phase PLAN.md files |
MSD Core {NN}-{MM}-PLAN.md files (renaming enforced) |
Conflict detection runs before any files are written. If the target directory already has a PROJECT.md and the imported content contradicts it, the migration stops at the BLOCKER gate and lists the conflicts for you to resolve.
Run the migration
Migrate the current directory
/msd-import --from-gsd2
MSD reads .gsd/ in the current working directory and writes the migrated artifacts into .planning/.
Migrate from a different path
/msd-import --from-gsd2 --path ~/projects/old-project
Use --path when the GSD-2 project is not your current working directory.
Resolve conflicts
If conflict detection finds blockers — for example, a GSD-2 tech-stack declaration that contradicts an existing .planning/PROJECT.md — it prints a conflict report and stops without writing any files.
Read the report, resolve the contradiction (edit the source document or the existing planning artifact), then re-run /msd-import --from-gsd2. The migration is safe to re-run until it passes cleanly.
Import an external plan file
If you have a standalone plan document (a team planning document, a Markdown spec, an exported task list) rather than a full GSD-2 project, use --from instead:
/msd-import --from /tmp/team-plan.md
MSD performs the same conflict-detection pass, converts the content to MSD Core PLAN.md format, and validates the result with the plan-checker. After validation you will see the target filename and next steps.
Absorb existing documentation
If your repository already contains ADRs (Architecture Decision Records), PRDs, or specification documents, use /msd-ingest-docs to synthesise them into the .planning/ structure after migration:
Scan the whole repository (auto-detects mode)
/msd-ingest-docs
If .planning/ is already present (for example, from the migration you just ran), MSD defaults to merge mode — it synthesises the ingested documents alongside what is already there rather than overwriting it.
Scope to a specific directory
/msd-ingest-docs docs/
/msd-ingest-docs docs/adr/
Use an explicit precedence manifest
When documents have mixed types or you want to control which document wins on conflicts:
/msd-ingest-docs --manifest ingest.yaml
The manifest is a YAML file listing {path, type, precedence?} per document. See the --manifest flag description in Commands for the expected shape.
Force a specific mode
/msd-ingest-docs --mode merge # Merge into existing .planning/
/msd-ingest-docs --mode new # Bootstrap from scratch (overwrites)
Output: /msd-ingest-docs always produces an INGEST-CONFLICTS.md with three buckets — auto-resolved, competing-variants, and unresolved-blockers. Review this file after every ingest run. Hard-stops only occur on LOCKED-vs-LOCKED ADR contradictions; everything else is surfaced for your review, not silently discarded.
Verify the migrated project
Once migration and any doc ingestion are complete, confirm the project state is consistent:
/msd-health
/msd-health --repair
/msd-health checks .planning/ directory integrity and reports any drift. --repair auto-fixes recoverable issues.
Then check that MSD Core can read your project state:
/msd-progress
If the project came across cleanly you will see the current phase status and the recommended next step. From here the standard MSD Core workflow applies.
Conditionals: what migrates and what does not
| Situation | What to do |
|---|---|
.gsd/ exists in the current directory |
Run /msd-import --from-gsd2 (no --path needed) |
.gsd/ is in a different directory |
Use --path ~/projects/old-project |
| You have a standalone plan document, not a full GSD-2 project | Use /msd-import --from /path/to/plan.md |
You have ADRs in docs/adr/ |
Run /msd-ingest-docs docs/adr/ after migration |
| You have a mix of ADRs, PRDs, and specs | Run /msd-ingest-docs at repo root; it classifies automatically |
| Conflict detection reports blockers | Resolve the listed contradictions then re-run; no files are written until all blockers clear |
| You are not sure whether migration worked | Run /msd-health and /msd-progress to confirm |
| INGEST-CONFLICTS.md lists unresolved blockers | These require manual resolution before affected documents are incorporated into planning |