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.2 KiB
Design: /msd-ultraplan-phase [BETA]
Date: 2026-04-17 Status: Approved — ready for implementation Branch: Beta feature, isolated from core plan pipeline
Summary
A standalone /msd-ultraplan-phase command that offloads MSD's research+plan phase to Claude Code's ultraplan cloud infrastructure. The plan drafts remotely while the terminal stays free, is reviewed in a rich browser UI with inline comments, then imports back into MSD via the existing /msd-import --from workflow.
This is a beta of a beta: ultraplan itself is in research preview, so this command is intentionally isolated from the core /msd-plan-phase pipeline to prevent breakage if ultraplan changes.
Scope
In scope:
- New
commands/msd/ultraplan-phase.mdcommand - New
msd-core/workflows/ultraplan-phase.mdworkflow - Runtime gate: Claude Code only (checks
$CLAUDE_CODE_VERSION) - Builds structured ultraplan prompt from MSD phase context
- Return path via existing
/msd-import --from <file>(no new import logic)
Out of scope (future):
- Parallel next-phase planning during
/msd-execute-phase - Auto-detection of ultraplan's saved file path
- Text mode / non-interactive fallback
Architecture
/msd-ultraplan-phase [phase]
│
├─ Runtime gate (CLAUDE_CODE_VERSION check)
├─ msd-sdk query init.plan-phase → phase context
├─ Build ultraplan prompt (phase scope + requirements + research)
├─ Display return-path instructions card
└─ /ultraplan <prompt>
│
[cloud: user reviews, comments, revises]
│
[browser: Approve → teleport back to terminal]
│
[terminal: Cancel → saves to file]
│
/msd-import --from <saved file path>
│
├─ Conflict detection
├─ MSD format conversion
├─ msd-plan-checker validation
├─ ROADMAP.md update
└─ Commit
Command File (commands/msd/ultraplan-phase.md)
Frontmatter:
name: msd:ultraplan-phasedescription:includes[BETA]markerargument-hint: [phase-number]allowed-tools:Read, Bash, Glob, Grep- References:
@~/.claude/msd-core/workflows/ultraplan-phase.md, ui-brand
Workflow Steps
1. Banner
Display MSD ► ULTRAPLAN PHASE [BETA] banner.
2. Runtime Gate
echo $CLAUDE_CODE_VERSION
If unset/empty: print error and exit.
⚠ /msd-ultraplan-phase requires Claude Code.
/ultraplan is not available in this runtime.
Use /msd-plan-phase for local planning.
3. Initialize
INIT=$(msd-sdk query init.plan-phase "$PHASE")
Parse: phase number, phase name, phase slug, phase dir, roadmap path, requirements path, research path.
If no .planning/ exists: error — run /msd-new-project first.
4. Build Ultraplan Prompt
Construct a prompt that includes:
- Phase identification:
"Plan phase {N}: {phase name}" - Phase scope block from ROADMAP.md
- Requirements summary (if REQUIREMENTS.md exists)
- Research summary (if RESEARCH.md exists — reduces cloud redundancy)
- Output format instruction: produce a MSD PLAN.md with standard frontmatter fields
5. Return-Path Instructions Card
Display prominently before triggering (visible in terminal scroll-back):
When ◆ ultraplan ready:
1. Open the session link in your browser
2. Review, comment, and revise the plan
3. When satisfied: "Approve plan and teleport back to terminal"
4. At the terminal dialog: choose Cancel (saves plan to file)
5. Run: /msd-import --from <the file path Claude prints>
6. Trigger Ultraplan
/ultraplan <constructed prompt>
Return Path
No new code needed. The user runs /msd-import --from <path> after ultraplan saves the file. That workflow handles everything: conflict detection, MSD format conversion, plan-checker, ROADMAP update, commit.
Runtime Detection
$CLAUDE_CODE_VERSION is set by Claude Code in the shell environment. If unset, the session is not Claude Code (Gemini CLI, Copilot, etc.) and /ultraplan does not exist.
Pricing
Ultraplan runs as a standard Claude Code on the web session. For Pro/Max subscribers this is included in the subscription — no extra usage billing (unlike ultrareview which bills $5–20/run). No cost gate needed.
Beta Markers
[BETA]in command description⚠ BETAin workflow banner- Comment in workflow noting ultraplan is in research preview
Test Coverage
tests/ultraplan-phase.test.cjs — structural assertions covering:
- File existence (command + workflow)
- Command frontmatter completeness (name, description with
[BETA], argument-hint) - Command references workflow
- Workflow has runtime gate (
CLAUDE_CODE_VERSION) - Workflow has beta warning
- Workflow has init step (msd-sdk query)
- Workflow builds ultraplan prompt with phase context
- Workflow triggers
/ultraplan - Workflow has return-path instructions (Cancel path,
/msd-import --from) - Workflow does NOT directly implement plan writing (delegates to
/msd-import)