# 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).