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 drive MSD Core from a tracker issue
Goal: Take a single well-scoped GitHub, Linear, or Jira issue through the full MSD pipeline — from isolated workspace to merged PR — using only commands that already exist in MSD Core, with no custom scripts or tracker integrations.
Prerequisites: MSD Core is installed. The issue has bounded scope, observable acceptance criteria, and no upstream blockers.
For the concepts and design rationale behind this pattern, see Issue-driven orchestration explained.
Step 1: Map the issue to a phase
Open your tracker issue and decide how it maps onto ROADMAP.md:
- Issue matches an existing phase → note the phase number and move to Step 2.
- Issue is standalone new work → add a phase:
/msd-phase "Description matching the issue title"
- Issue is urgent and must slot between existing phases → insert a decimal phase:
/msd-phase --insert 3 "Fix: description from issue"
Copy the tracker issue URL. You will paste it into CONTEXT.md in Step 3 so traceability survives context compaction.
Step 2: Create an isolated workspace
Every issue gets its own workspace — a git worktree with an independent .planning/ directory. Partial work, aborted plans, and exploratory commits stay outside main.
/msd-workspace --new --name my-issue-slug --repos . --strategy worktree
Switch into the workspace directory before continuing:
cd ~/msd-workspaces/my-issue-slug
Step 3: Discuss the phase
Run discuss-phase to lock in implementation decisions before any planning happens. When the session opens, paste the tracker issue URL into the discussion so it is captured in CONTEXT.md.
/msd-discuss-phase N
MSD asks about ambiguities in the issue scope — error handling, edge cases, interface contracts, technology choices. Your answers shape the plan that follows.
If you already know all the answers and want to move quickly:
/msd-discuss-phase N --auto
Step 4: Plan the phase
/msd-plan-phase N
MSD spawns research agents, reads your CONTEXT.md decisions (including the issue URL), and produces atomic PLAN.md files. A plan-checker validates each plan before saving.
If you want peer review from external AI CLIs before execution (recommended for significant changes):
/msd-review --phase N
/msd-plan-phase N --reviews
Or run the full plan–review–converge loop until no HIGH concerns remain:
/msd-plan-review-convergence N
Step 5: Execute the phase
For interactive, phase-at-a-time execution:
/msd-execute-phase N
For a hands-off run through all remaining phases:
/msd-autonomous
For an interactive dashboard where you can watch progress and dispatch work across phases:
/msd-manager
All three approaches update STATE.md, commit each task atomically, and run the post-phase verifier.
Step 6: Verify the work
/msd-verify-work N
MSD walks you through the acceptance criteria from the phase goal (which reflects your tracker issue) one at a time. If anything fails, MSD diagnoses the root cause and creates a fix plan. Re-run execute and re-verify until all checks pass.
Treat verification_failed as a blocker even when the code looks correct — the failure usually surfaces a missed acceptance criterion from the original issue.
Step 7: Review and ship
Run a code review before opening the PR:
/msd-code-review N
/msd-code-review N --fix
Then create the PR:
/msd-ship N
MSD assembles the PR body from your planning artifacts: phase goal, changes summary, requirements addressed, verification status, and key decisions. Include Closes #NNN or Fixes #NNN in the PR body (or set it via /msd-config) so the tracker issue closes automatically when the PR merges.
Step 8: Capture follow-up work
As you work through the issue you will often discover related work. Capture it without losing context:
/msd-capture "Follow-up: description of discovered work" # Add as a todo
/msd-capture --seed "Idea worth a future phase" # Preserve for the next milestone
/msd-capture --backlog "Not urgent but worth tracking" # Park in the backlog
MSD does not post to your tracker automatically. Creating a tracker issue from captured follow-ups is a separate manual step — this keeps human review in the loop.
Conditionals
| Situation | What to do |
|---|---|
| Issue is very small (typo, config change) | Skip workspace + discuss + plan; use /msd-quick instead |
| Issue has multiple independent sub-tasks | Use /msd-manager to parallelise execution across plans |
| Issue is blocked on another issue | Do not start until the upstream blocker is resolved; MSD has no automatic dependency poller |
| Issue scope turns out larger than expected mid-execution | Stop, run /msd-phase --insert N to add sub-phases, continue |
| You want to skip the interactive discussion | Use --auto flag with /msd-discuss-phase, or set workflow.skip_discuss: true for project-wide automation |
| Multiple issues form a coherent release | Run /msd-new-milestone to group them and /msd-autonomous to execute in sequence |