Files
msd-core/docs/superpowers/specs/2026-04-17-ultraplan-phase-design.md
Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)
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.
2026-10-06 01:47:40 +02:00

5.2 KiB
Raw Blame History

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.md command
  • New msd-core/workflows/ultraplan-phase.md workflow
  • 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-phase
  • description: includes [BETA] marker
  • argument-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
  • ⚠ BETA in 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)