diff --git a/plugins/ultraplan-local/MIGRATION.md b/plugins/ultraplan-local/MIGRATION.md index 5d42fd8..cec0a12 100644 --- a/plugins/ultraplan-local/MIGRATION.md +++ b/plugins/ultraplan-local/MIGRATION.md @@ -1,284 +1,12 @@ -# Migration guide: v1.x → v2.0.0 - -v2.0.0 is a breaking release. This guide walks through everything that changed -and how to update your workflow. - -## TL;DR - -| You used to run | Now run | -|-----------------|---------| -| `/ultraplan-local "Add auth"` | `/ultrabrief-local "Add auth"` → `/ultraplan-local --project ` | -| `/ultraplan-local --spec spec.md` | Convert spec → brief, then `/ultraplan-local --brief brief.md` | -| `/ultraresearch-local "..."` | Same (still works). Add `--project ` to land results inside a project dir. | -| `/ultraexecute-local plan.md` | Same (still works). Add `--project ` to use project paths. | - -## What changed and why - -### 1. Four commands, not three - -v1.x had three commands. v2.0 introduces `/ultrabrief-local` as a first-class -step: - -``` -/ultrabrief-local → brief.md (NEW in v2.0) -/ultraresearch-local → research briefs -/ultraplan-local → plan.md -/ultraexecute-local → progress.json -``` - -**Why:** In v1, the interview was buried inside `/ultraplan-local`. That made -it impossible to review the captured intent before research + planning started. -With `/ultrabrief-local` as a separate step: - -- The **task brief** is a reviewable, editable artifact before you spend a - single Opus token on planning. -- Research topics are declared explicitly, with clear scope and confidence - requirements. -- You can re-plan from the same brief multiple times (e.g., after research - reveals a new constraint). - -### 2. Project directory as the single source of truth - -All pipeline artifacts now live in one directory: - -``` -.claude/projects/2026-04-18-jwt-auth/ -├── brief.md ← /ultrabrief-local -├── research/ -│ ├── 01-jwt-best-practices.md ← /ultraresearch-local --project -│ └── 02-existing-auth-code.md -├── plan.md ← /ultraplan-local --project -├── sessions/ ← /ultraplan-local --decompose -└── progress.json ← /ultraexecute-local --project -``` - -`--project ` works on `/ultraresearch-local`, `/ultraplan-local`, and -`/ultraexecute-local`. Pass it once and each command writes to the right -place automatically. - -**Legacy paths still work.** If you don't pass `--project`, commands write to -the v1.x locations (`.claude/research/`, `.claude/plans/`, etc.). Existing -v1 plans execute unchanged. - -### 3. `/ultraplan-local` requires a brief - -**v1.x:** -```bash -/ultraplan-local "Add authentication with JWT" -# ...interview happens inside the command -``` - -**v2.0:** -```bash -/ultraplan-local "Add authentication with JWT" -# ERROR: /ultraplan-local requires --brief or --project. -# Run /ultrabrief-local first. -``` - -You must pass one of: -- `--project ` — reads `{dir}/brief.md` + any `{dir}/research/*.md` -- `--brief ` — reads a specific brief file - -**Why:** Separating interview from planning is a deliberate architectural choice. -See CHANGELOG.md `[2.0.0]` → Rationale. - -### 4. `--spec` is removed - -**v1.x:** -```bash -/ultraplan-local --spec .claude/ultraplan-spec-2026-04-01-auth.md -``` - -**v2.0:** The `--spec` flag is gone. You can either: - -**Option A (recommended):** Re-run `/ultrabrief-local` to capture intent fresh. -```bash -/ultrabrief-local "Add authentication with JWT" -``` - -**Option B:** Convert an old spec to a brief manually. The two formats are -similar but a brief has two additional required sections: `## Intent` and -`## Research Plan`. - -Minimal conversion template — take your old spec and add: - -```markdown ---- -type: ultrabrief -brief_version: 2.0 -created: 2026-04-18 -task: "{copy one-line description from your spec}" -slug: {your-slug} -project_dir: .claude/projects/2026-04-18-{slug}/ -research_topics: 0 -research_status: skipped -auto_research: false -interview_turns: 0 -source: manual ---- - -# Task: {Your title} - -## Intent - -*New section in v2.0. 3-5 sentences on why this matters.* - -{Write why this task exists — motivation, user need, strategic context.} - -## Goal - -{Copy your spec's goal/overview here — 1 paragraph.} - -## Non-Goals - -{Copy from spec. Or list explicitly what's out of scope.} - -## Constraints / Preferences / NFRs - -{Copy from spec's constraints section.} - -## Success Criteria - -{Copy from spec. Ensure each is falsifiable — a command or observation.} - -## Research Plan - -*New section in v2.0. Declare research topics upfront.* - -No external research needed. (Or list N topics if you have them.) - -## Open Questions / Assumptions - -{Copy from spec, or list any assumptions you're making.} - -## Prior Attempts - -None — fresh task. (Or describe what was tried before.) -``` - -Save this as `brief.md` inside your project directory, then: - -```bash -/ultraplan-local --project .claude/projects/2026-04-18-{slug} -``` - -### 5. `spec-reviewer` → `brief-reviewer` - -The review agent that runs before exploration has been renamed and expanded: - -| | v1.x | v2.0 | -|--|------|------| -| File | `agents/spec-reviewer.md` | `agents/brief-reviewer.md` | -| Dimensions | 4 (completeness, consistency, testability, scope clarity) | 5 (+ Research Plan validity) | -| Input | `Spec file: ` | `Brief file: ` | - -The new 5th dimension checks that every research topic has a valid research -question (ends in `?`), declares `Required for plan steps:` and -`Confidence needed:`, and — if `auto_research: true` — verifies the actual -research briefs exist in `{project_dir}/research/`. - -## Step-by-step migration for an in-flight v1 project - -Say you have: - -``` -.claude/ultraplan-spec-2026-03-20-auth.md # old spec -.claude/plans/ultraplan-2026-03-20-auth.md # old plan -``` - -### Option 1: Keep existing plan, skip re-planning - -Old plans execute unchanged in v2.0. Just run: - -```bash -/ultraexecute-local .claude/plans/ultraplan-2026-03-20-auth.md -``` - -No migration needed. Legacy plans remain valid. - -### Option 2: Re-plan with v2 tooling - -1. Create the project directory: - ```bash - mkdir -p .claude/projects/2026-04-18-auth/research - ``` - -2. Convert spec → brief using the template above. Save as: - ``` - .claude/projects/2026-04-18-auth/brief.md - ``` - -3. (Optional) Copy any prior research briefs into `research/`: - ```bash - cp .claude/research/ultraresearch-2026-03-*.md \ - .claude/projects/2026-04-18-auth/research/01-prior-research.md - ``` - -4. Re-plan: - ```bash - /ultraplan-local --project .claude/projects/2026-04-18-auth - ``` - -5. Execute: - ```bash - /ultraexecute-local --project .claude/projects/2026-04-18-auth - ``` - -### Option 3: Start fresh with v2 workflow - -For new work, skip the conversion: - -```bash -/ultrabrief-local "Add authentication with JWT" -# Answer interview questions. Identifies research topics. - -# Manual path: -/ultraresearch-local --project .claude/projects/2026-04-18-auth --external "JWT best practices?" -/ultraplan-local --project .claude/projects/2026-04-18-auth -/ultraexecute-local --project .claude/projects/2026-04-18-auth - -# OR auto path — choose "Auto" when /ultrabrief-local asks. -# Research + planning run in foreground, return when plan.md is ready. -/ultraexecute-local --project .claude/projects/2026-04-18-auth -``` - -## What still works unchanged - -- `/ultraresearch-local ` without `--project` — still writes to - `.claude/research/ultraresearch-{date}-{slug}.md` -- `/ultraexecute-local ` — executes any v1 or v2 plan -- `/ultraplan-local --decompose ` — works on both v1 and v2 plans -- `/ultraplan-local --export ` — works on both v1 and v2 plans -- All `--fg`, `--quick`, `--resume`, `--dry-run`, `--validate`, `--step`, - `--session` flags — unchanged behavior - -## What breaks without a migration - -- `/ultraplan-local ` without `--brief` or `--project` — errors out -- `/ultraplan-local --spec ` — `--spec` flag no longer exists -- Any script that references `agents/spec-reviewer.md` — file is deleted -- Planning orchestrator invocations that pass `Spec file: ` — now - expects `Brief file: ` - -## FAQ - -**Q: Do I have to migrate old plans?** -A: No. Old plans execute unchanged. Migration is only needed if you want to -re-plan. - -**Q: Can I keep using the old spec files?** -A: Yes, but not with `/ultraplan-local`. You can continue referring to them -manually, but to re-plan in v2 you must convert them to briefs (see Option 2 -above). - -**Q: What if I don't want an interview?** -A: Write `brief.md` directly using the template in -`templates/ultrabrief-template.md`. Set `source: manual` in the frontmatter. - -**Q: Can I run `/ultraplan-local` with just a research brief, no task brief?** -A: No. A task brief is required. The task brief captures *intent*; a research -brief captures *information about a topic*. These are not interchangeable. - -**Q: My `.claude/projects/` directory doesn't exist. Should I create it?** -A: `/ultrabrief-local` creates it automatically when you run it. You only need -to create it manually if you're converting an old spec (Option 2 above). +# Migration + +v3.x → v4.0.0 is a rebrand. All command names changed: +`/ultrabrief-local` → `/trekbrief`, `/ultraresearch-local` → `/trekresearch`, +`/ultraplan-local` → `/trekplan`, `/ultraexecute-local` → `/trekexecute`, +`/ultrareview-local` → `/trekreview`, `/ultracontinue-local` → `/trekcontinue`, +`/ultraplan-end-session-local` → `/trekendsession`. The plugin is now +named `voyage`. Re-fork from main if upgrading. There is no migration +path — see `GOVERNANCE.md` for the fork-and-own model. + +Prior version migration notes (v1→v2, v2→v3) are preserved in +`CHANGELOG.md` only.