feat(voyage)!: collapse MIGRATION.md to v3->v4 rebrand notice [skip-docs]
This commit is contained in:
parent
14ecda886c
commit
15607b182e
1 changed files with 12 additions and 284 deletions
|
|
@ -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 <dir>` |
|
||||
| `/ultraplan-local --spec spec.md` | Convert spec → brief, then `/ultraplan-local --brief brief.md` |
|
||||
| `/ultraresearch-local "..."` | Same (still works). Add `--project <dir>` to land results inside a project dir. |
|
||||
| `/ultraexecute-local plan.md` | Same (still works). Add `--project <dir>` 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 <dir>
|
||||
│ └── 02-existing-auth-code.md
|
||||
├── plan.md ← /ultraplan-local --project <dir>
|
||||
├── sessions/ ← /ultraplan-local --decompose
|
||||
└── progress.json ← /ultraexecute-local --project <dir>
|
||||
```
|
||||
|
||||
`--project <dir>` 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 <dir>` — reads `{dir}/brief.md` + any `{dir}/research/*.md`
|
||||
- `--brief <path>` — 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: <path>` | `Brief file: <path>` |
|
||||
|
||||
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 <question>` without `--project` — still writes to
|
||||
`.claude/research/ultraresearch-{date}-{slug}.md`
|
||||
- `/ultraexecute-local <plan-path>` — executes any v1 or v2 plan
|
||||
- `/ultraplan-local --decompose <plan>` — works on both v1 and v2 plans
|
||||
- `/ultraplan-local --export <format> <plan>` — 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 <task>` without `--brief` or `--project` — errors out
|
||||
- `/ultraplan-local --spec <path>` — `--spec` flag no longer exists
|
||||
- Any script that references `agents/spec-reviewer.md` — file is deleted
|
||||
- Planning orchestrator invocations that pass `Spec file: <path>` — now
|
||||
expects `Brief file: <path>`
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue