mirror of
https://github.com/glittercowboy/get-shit-done
synced 2026-05-13 10:36:38 +02:00
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>
99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# 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](COMMANDS.md) and [FEATURES.md](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](https://code.claude.ai) 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_VERSION` env var must be set).
|
|
- **Cost:** No extra charge for Pro and Max subscribers. Ultraplan is included at no additional cost.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
/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
|
|
|
|
1. **Initialization** — GSD runs the standard plan-phase init, resolving which phase to plan and confirming prerequisites.
|
|
|
|
2. **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.
|
|
|
|
3. **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>
|
|
```
|
|
|
|
4. **Ultraplan launches** — The `/ultraplan` command hands off to the browser. Use the outline sidebar and inline comments to review and refine the draft.
|
|
|
|
5. **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.
|
|
|
|
6. **Import back into GSD** — Run the import command that was printed in step 3:
|
|
```bash
|
|
/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.
|
|
|
|
### 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.md` files 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.md` first, run `/gsd-plan-phase --skip-verify` or 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`](COMMANDS.md#gsd-plan-phase) — standard local planning (stable, all runtimes)
|
|
- [`/gsd-import`](COMMANDS.md#gsd-import) — import any external plan file into GSD
|