@~/.claude/gsd-core/references/response-language-directive.md
# Ultraplan Phase Workflow [BETA]
Offload GSD's plan phase to Claude Code's ultraplan cloud infrastructure.
⚠ **BETA feature.** Ultraplan is in research preview and may change. This workflow is
intentionally isolated from /gsd:plan-phase so upstream changes to ultraplan cannot
affect the core planning pipeline.
---
Display the stage banner:
```text
### GSD ► ULTRAPLAN PHASE ⚠ BETA
Ultraplan is in research preview (Claude Code v2.1.91+).
Use /gsd:plan-phase for stable local planning.
```
---
Check that the session is running inside Claude Code:
```bash
if [ "$CLAUDECODE" = "1" ] || [ -n "$CLAUDE_CODE_ENTRYPOINT" ]; then
CC_VERSION="$(claude --version 2>/dev/null | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)"
if [ -n "$CC_VERSION" ] && [ "$(printf '%s\n' "2.1.91" "$CC_VERSION" | sort -V | head -n1)" = "2.1.91" ]; then
echo "claude-code:${CC_VERSION}"
else
echo ""
fi
else
echo ""
fi
```
If the output is empty or unset, display the following error and exit:
```text
### RUNTIME ERROR
/gsd:ultraplan-phase requires Claude Code.
ultraplan is not available in this runtime.
Use /gsd:plan-phase for local planning instead.
```
---
Parse phase number from `$ARGUMENTS`. If no phase number is provided, detect the next
unplanned phase from the roadmap (same logic as /gsd:plan-phase).
Load GSD phase context:
```bash
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @therocketcode/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@therocketcode/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @therocketcode/gsd-core - it is either a different package or an @therocketcode/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
INIT=$(gsd_run query init.plan-phase "$PHASE")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
Parse JSON for: `phase_found`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`,
`phase_dir`, `roadmap_path`, `requirements_path`, `research_path`, `planning_exists`.
**If `planning_exists` is false:** Error and exit:
```text
No .planning directory found. Initialize the project first:
/gsd:new-project
```
**If `phase_found` is false:** Error with the phase number provided and exit.
Display detected phase:
```text
Phase {N}: {phase name}
```
---
Build the ultraplan prompt from GSD context.
1. Read the phase scope from ROADMAP.md — extract the goal, deliverables, and scope for
the target phase.
2. Read REQUIREMENTS.md if it exists (`requirements_path` is not null) — extract a
concise summary (key requirements relevant to this phase, not the full document).
3. Read RESEARCH.md if it exists (`research_path` is not null) — extract a concise
summary of technical findings. Including this reduces redundant cloud research.
4. **Grounding (do NOT skip — the cloud planner is isolated from plan-phase, so the
grounding must be carried in the prompt).** Resolve the active sources with
`gsd_run query grounding required` and read each: the strategy decisions (ADR rung
per subdomain, TEST-STRATEGY levels, SECURITY/FE/INFRA/CICD posture), plus
`CONTEXT.md`, `DESIGN-INVENTORY.md`, `LEGACY-INVENTORY.md`, and this phase's
`UI-SPEC.md` / `AI-SPEC.md` when present. Summarize the decisions the plan must honor.
Construct the prompt:
```text
Plan phase {phase_number}: {phase_name}
## Phase Scope (from ROADMAP.md)
{phase scope block extracted from ROADMAP.md}
## Requirements Context
{requirements summary, or "No REQUIREMENTS.md found — infer from phase scope."}
## Existing Research
{research summary, or "No RESEARCH.md found — research from scratch."}
## Grounding (honor these — the plan MUST include a `## Grounding` block citing them)
{summary of the active strategy sources' decisions from step 4 — the ADR rung per subdomain, TEST-STRATEGY levels, SECURITY/FE/INFRA/CICD posture, DESIGN-INVENTORY fields, UI-SPEC/AI-SPEC contracts. Or "No strategy artifacts yet — build to the engineering-standards floor." The imported PLAN.md is checked by `check.grounding-plan` on import, so it must cite every active (done) source.}
## Output Format
Produce a GSD PLAN.md with the following YAML frontmatter:
---
phase: "{padded_phase}-{phase_slug}"
plan: "{padded_phase}-01"
type: "feature"
wave: 1
depends_on: []
files_modified: []
autonomous: true
must_haves:
truths: []
artifacts: []
---
Then a ## Plan section with numbered tasks. Each task should have:
- A clear imperative title
- Files to create or modify
- Specific implementation steps
Keep the plan focused and executable.
```
---
Display the return-path instructions **before** triggering ultraplan so they are visible
in the terminal scroll-back after ultraplan launches:
```text
### WHEN THE PLAN IS READY — WHAT TO DO
When ◆ ultraplan ready appears in your terminal:
1. Open the session link in your browser
2. Review the plan — use inline comments and emoji reactions to give feedback
3. Ask Claude to revise until you're satisfied
4. Click "Approve plan and teleport back to terminal"
5. At the terminal dialog, choose Cancel ← saves the plan to a file
6. Note the file path Claude prints
7. Run: /gsd:import --from
/gsd:import will run conflict detection, convert to GSD format,
validate via plan-checker, update ROADMAP.md, and commit.
### Launching ultraplan for Phase {N}: {phase_name}...
```
---
Trigger ultraplan with the constructed prompt:
```text
/ultraplan {constructed prompt from build_prompt step}
```
Your terminal will show a `◇ ultraplan` status indicator while the remote session works.
Use `/tasks` to open the detail view with the session link, agent activity, and a stop action.