docs/BETA.md
Beta features are opt-in and may change or be removed without notice. They are not covered by the stable API guarantees that apply to the rest of GSD. If a beta feature ships to stable, it will be documented in COMMANDS.md and FEATURES.md with a changelog entry.
/gsd-ultraplan-phase — Ultraplan Integration [BETA]Claude Code only · Requires Claude Code v2.1.91+ Ultraplan is itself a Claude Code research preview — both this command and the underlying feature may change.
/gsd-ultraplan-phase offloads GSD's plan-phase drafting to Claude Code's ultraplan cloud infrastructure. Instead of planning locally in the terminal, the plan is drafted in a browser-based session with:
When you're satisfied with the draft, you save it and import it back into GSD — conflict detection, format validation, and plan-checker verification all run automatically.
| Situation | Recommendation |
|---|---|
| Long, complex phases where you want to read and comment on the plan before it executes | Use /gsd-ultraplan-phase |
| Quick phases, familiar domain, or non-Claude Code runtimes | Use /gsd-plan-phase (stable) |
| You have a plan from another source (teammate, external AI) | Use /gsd-import |
$CLAUDE_CODE_VERSION env var must be set)./gsd-ultraplan-phase # Ultraplan the next unplanned phase
/gsd-ultraplan-phase 2 # Ultraplan a specific phase number
| Argument | Required | Description |
|---|---|---|
N | No | Phase number (defaults to next unplanned phase) |
Initialization — GSD runs the standard plan-phase init, resolving which phase to plan and confirming prerequisites.
Context assembly — GSD reads ROADMAP.md, REQUIREMENTS.md, and any existing RESEARCH.md for the phase. This context is bundled into a structured prompt so ultraplan has everything it needs without you copying anything manually.
Return-path instructions — Before launching ultraplan, GSD prints the import command to your terminal so it's visible in your scroll-back buffer after the browser session ends:
When done: /gsd-import --from <path-to-saved-plan>
Ultraplan launches — The /ultraplan command hands off to the browser. Use the outline sidebar and inline comments to review and refine the draft.
Save the plan — When satisfied, click Cancel in Claude Code. Claude Code saves the plan to a local file and returns you to the terminal.
Import back into GSD — Run the import command that was printed in step 3:
/gsd-import --from /path/to/saved-plan.md
This runs conflict detection against PROJECT.md, converts the plan to GSD format, validates it with gsd-plan-checker, updates ROADMAP.md, and commits — the same path as any external plan import.
| Step | Output |
|---|---|
| After ultraplan | External plan file (saved by Claude Code) |
After /gsd-import | {phase}-{N}-PLAN.md in .planning/phases/ |
PLAN.md files directly — all writes go through /gsd-import/gsd-plan-phase — local planning is unaffected and remains the defaultRESEARCH.md first, run /gsd-plan-phase --skip-verify or a research-only pass before using this command"ultraplan is not available in this runtime"
You're running GSD outside of Claude Code. Switch to a Claude Code terminal session, or use /gsd-plan-phase instead.
Ultraplan browser session never opened
Check your Claude Code version: claude --version. Requires v2.1.91+. Update with claude update.
/gsd-import reports conflicts
Ultraplan may have proposed something that contradicts a decision in PROJECT.md. The import step will prompt you to resolve each conflict before writing anything.
Plan checker fails after import
The imported plan has structural issues. Review the checker output, edit the saved file to fix them, and re-run /gsd-import --from <same-file>.
/gsd-plan-phase — standard local planning (stable, all runtimes)/gsd-import — import any external plan file into GSD