ktg-plugin-marketplace/plugins/ultraplan-local/MIGRATION.md

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:

/ultraplan-local "Add authentication with JWT"
# ...interview happens inside the command

v2.0:

/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:

/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.

/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:

---
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:

/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:

/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:

   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/:

   cp .claude/research/ultraresearch-2026-03-*.md \
      .claude/projects/2026-04-18-auth/research/01-prior-research.md
   

4. Re-plan:

   /ultraplan-local --project .claude/projects/2026-04-18-auth
   

5. Execute:

   /ultraexecute-local --project .claude/projects/2026-04-18-auth
   

Option 3: Start fresh with v2 workflow

For new work, skip the conversion:

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