794f7e1b0b
* docs: add design spec for /gsd-ultraplan-phase beta command Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: add /gsd-ultraplan-phase [BETA] command Offloads GSD plan phase to Claude Code's ultraplan cloud infrastructure. Plan drafts remotely while terminal stays free; browser UI for inline comments and revisions; imports back via existing /gsd-import --from. Intentionally isolated from /gsd-plan-phase so upstream ultraplan changes cannot break the core planning pipeline. Closes #2374 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: resolve 5 pre-existing test failures before PR - ARCHITECTURE.md: update command count 75→80 and workflow count 72→77 (stale doc counts; also incremented by new ultraplan-phase files) - sketch.md: add TEXT_MODE plain-text fallback for AskUserQuestion (#2012) - read-guard.test.cjs: clear CLAUDECODE env var alongside CLAUDE_SESSION_ID so positive-path hook tests pass when run inside a Claude Code session Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: add BETA.md with /gsd-ultraplan-phase user documentation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: address CodeRabbit review — MD040 fence labels and sketch.md TEXT_MODE duplicate - Add language identifiers to all unlabeled fenced blocks in ultraplan-phase.md and design spec (resolves MD040) - Remove duplicate TEXT_MODE explanation from sketch.md mood_intake step (was identical to the banner step definition) - Make AskUserQuestion conditional explicit in mood_intake prose Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
4.8 KiB
GSD Beta Features
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.
What it does
/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:
- An outline sidebar for navigating the plan structure
- Inline comments for annotating and refining tasks
- A persistent browser tab so your terminal stays free while the plan is being drafted
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.
Why use it
| 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 |
Requirements
- Runtime: Claude Code only. The command exits with an error on Gemini CLI, Copilot CLI, and other runtimes.
- Version: Claude Code v2.1.91 or later (the
$CLAUDE_CODE_VERSIONenv var must be set). - Cost: No extra charge for Pro and Max subscribers. Ultraplan is included at no additional cost.
Usage
/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) |
How it works
-
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 existingRESEARCH.mdfor 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
/ultraplancommand 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.mdThis runs conflict detection against
PROJECT.md, converts the plan to GSD format, validates it withgsd-plan-checker, updatesROADMAP.md, and commits — the same path as any external plan import.
What gets produced
| Step | Output |
|---|---|
| After ultraplan | External plan file (saved by Claude Code) |
After /gsd-import |
{phase}-{N}-PLAN.md in .planning/phases/ |
What this command does NOT do
- Write
PLAN.mdfiles directly — all writes go through/gsd-import - Replace
/gsd-plan-phase— local planning is unaffected and remains the default - Run research agents — if you need
RESEARCH.mdfirst, run/gsd-plan-phase --skip-verifyor a research-only pass before using this command
Troubleshooting
"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>.
Related commands
/gsd-plan-phase— standard local planning (stable, all runtimes)/gsd-import— import any external plan file into GSD