feat(ultraplan-local)!: v2.0.0 — brief-driven four-command pipeline

Extract interview from /ultraplan-local into new /ultrabrief-local command. /ultraplan-local now requires --brief or --project (breaking). All pipeline artifacts land in one project directory: .claude/projects/{date}-{slug}/ with brief.md, research/, plan.md, sessions/, progress.json. Breaking changes: - /ultraplan-local requires --brief <path> or --project <dir> - /ultraplan-local --spec removed (convert specs to briefs per MIGRATION.md) - Interview phase moved to /ultrabrief-local - spec-reviewer renamed to brief-reviewer with 5th dimension (Research Plan validity) Added: - /ultrabrief-local command (interactive interview → brief.md with research plan) - templates/ultrabrief-template.md (task brief format with intent + research plan) - brief-reviewer agent (5-dimension brief quality review) - --project <dir> flag on /ultraresearch-local, /ultraplan-local, /ultraexecute-local - MIGRATION.md (v1 → v2 upgrade guide) Changed: - planning-orchestrator accepts Brief file: input (was Spec file:) - planning-orchestrator Phase 1b uses brief-reviewer - README + CLAUDE.md rewritten for four-command pipeline and task/research brief terminology - CHANGELOG.md [2.0.0] entry with rationale - Marketplace root README + CLAUDE.md updated to v2.0.0 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-18 07:22:08 +02:00 · 2026-04-18 07:22:08 +02:00 · 2bc405e14a
commit 2bc405e14a
parent fb9eb79d17
15 changed files with 1799 additions and 592 deletions
--- a/plugins/ultraplan-local/commands/ultrabrief-local.md
+++ b/plugins/ultraplan-local/commands/ultrabrief-local.md
@ -0,0 +1,420 @@
+---
+name: ultrabrief-local
+description: Interactive interview that produces a task brief with explicit research plan. Feeds /ultraresearch-local and /ultraplan-local. Optionally orchestrates the full pipeline end-to-end.
+argument-hint: "[--quick] <task description>"
+model: opus
+allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
+---
+
+# Ultrabrief Local v2.0
+
+Interactive requirements-gathering command. Produces a **task brief** — a
+structured markdown file that declares intent, goal, constraints, and an
+**explicit research plan** with copy-paste-ready `/ultraresearch-local` commands.
+
+Pipeline position:
+
+```
+/ultrabrief-local  →  brief.md                         (this command)
+/ultraresearch-local --project <dir>  →  research/*.md
+/ultraplan-local --project <dir>  →  plan.md
+/ultraexecute-local --project <dir>  →  execution
+```
+
+The brief is the contract between the user's intent and `/ultraplan-local`.
+Every decision the plan makes must trace back to content in the brief.
+
+**This command is always interactive.** There is no background mode — the
+interview requires user input. After the brief is written, the command
+optionally orchestrates the rest of the pipeline (research + plan) in
+foreground if the user opts in.
+
+## Phase 1 — Parse mode and validate input
+
+Parse `$ARGUMENTS`:
+
+1. If arguments start with `--quick`: set **mode = quick**. Interview is
+   shorter (3-4 questions instead of 5-8). Strip the flag; remainder is
+   the task description.
+
+2. Otherwise: **mode = default**. Full interview (5-8 questions).
+
+If no task description is provided, output usage and stop:
+
+```
+Usage: /ultrabrief-local <task description>
+       /ultrabrief-local --quick <task description>
+
+Modes:
+  default       Full interview (5-8 questions) → brief with research plan
+  --quick       Short interview (3-4 questions) → brief with research plan
+
+Examples:
+  /ultrabrief-local Add user authentication with JWT tokens
+  /ultrabrief-local --quick Add rate limiting to the API
+  /ultrabrief-local Migrate from Express to Fastify
+```
+
+Report:
+```
+Mode: {default | quick}
+Task: {task description}
+```
+
+## Phase 2 — Generate slug and create project directory
+
+Generate a slug from the task description: first 3-4 meaningful words,
+lowercase, hyphens. Example: "Migrate from Express to Fastify" → `fastify-migration`.
+
+Set today's date as `YYYY-MM-DD` (UTC).
+
+Create the project directory:
+
+```bash
+PROJECT_DIR=".claude/projects/{YYYY-MM-DD}-{slug}"
+mkdir -p "$PROJECT_DIR/research"
+```
+
+Report:
+```
+Project directory: .claude/projects/{YYYY-MM-DD}-{slug}/
+```
+
+If the directory already exists and is non-empty, warn and ask:
+> "Directory {path} exists. Overwrite, reuse (keep existing files), or pick new slug?"
+
+Use `AskUserQuestion` with three options. If "pick new slug", ask for a
+new slug and restart Phase 2.
+
+## Phase 3 — Interview
+
+Use `AskUserQuestion` throughout. **Ask one question at a time.** Never
+dump all questions at once. Follow up based on answers.
+
+### Interview flow
+
+**Question 1 (always) — Intent:**
+> "What is the motivation for this task? Why does it matter? What happens
+> if we don't do it? (The plan will use this to justify every implementation
+> decision.)"
+
+**Question 2 (always) — Goal:**
+> "What does success look like concretely? Describe the end state in
+> 1-3 sentences — specific enough to disagree with."
+
+**Question 3 (always) — Success criteria:**
+> "How will we verify it's done? List 2-4 specific, testable conditions
+> (commands to run, observations, metrics). Avoid 'it works'."
+
+**Question 4 (usually) — Non-goals:**
+> "What is explicitly NOT in scope? (Prevents scope-guardian flagging gaps
+> for things we deliberately don't do.)"
+
+**Question 5 (conditional) — Constraints:**
+> "Are there technical, time, or resource constraints? (Dependencies,
+> compatibility, deadlines, budget.)"
+>
+> Skip if the user already mentioned constraints.
+
+**Question 6 (conditional) — Preferences:**
+> "Preferences on libraries, patterns, or architectural style?"
+>
+> Skip for small tasks or when constraints already imply them.
+
+**Question 7 (conditional) — Non-functional requirements:**
+> "Performance, security, accessibility, or scalability targets? (Quantified
+> where possible.)"
+>
+> Skip if not applicable.
+
+**Question 8 (conditional) — Prior attempts:**
+> "Has this been tried before? What worked or failed?"
+>
+> Skip if the task is clearly fresh.
+
+### Adaptive depth
+
+After each answer:
+
+- **Detailed technical answer (2+ sentences, domain vocabulary):** skip
+  obvious follow-ups the user already covered. Aim for 4-5 total questions.
+- **Short or uncertain answer ("I don't know", "not sure", vague):** offer
+  alternatives instead of open questions. Record uncertainty as an
+  open assumption.
+- **"Skip" / "just make it" / "proceed":** stop interviewing. Write a
+  minimal brief from the task description and answers so far. Mark
+  uncovered sections as "Not discussed — no constraints assumed."
+
+### Quick mode
+
+If **mode = quick**, ask only Questions 1, 2, 3, and 4. Maximum 4 questions.
+Skip the rest.
+
+### Research topic identification (CRITICAL)
+
+As the interview progresses, identify topics that will need research for
+the plan to be high-confidence. Watch for:
+
+- **Unfamiliar technologies** — libraries, frameworks, protocols not
+  clearly present in the codebase
+- **Version upgrades** — migrating to a new major version
+- **Security-sensitive decisions** — auth, crypto, data handling
+- **Architectural choices** — pattern X vs Y, library A vs B
+- **Unknown integrations** — third-party APIs, external services
+- **Compliance / legal** — GDPR, accessibility, industry regulations
+
+For each potential topic, probe briefly:
+> "Do you already know {topic}, or should I plan a research step for it?"
+
+Record:
+- Topic title (short)
+- Why it matters for the plan
+- Exact research question (phrased for `/ultraresearch-local`)
+- Suggested scope (local / external / both)
+- Confidence needed (high / medium / low)
+- Estimated cost (quick / standard / deep)
+
+If the user says "I know this" — do not add it as a topic. Trust the user.
+
+If no topics emerge: `research_topics = 0` is valid. Not every task needs
+external research.
+
+## Phase 4 — Write the brief
+
+Read the brief template:
+`@${CLAUDE_PLUGIN_ROOT}/templates/ultrabrief-template.md`
+
+Write the brief to: `{PROJECT_DIR}/brief.md`.
+
+Fill in every section based on interview answers:
+
+- **Frontmatter:** populate `task`, `slug`, `project_dir`, `research_topics`,
+  `research_status: pending`, `auto_research: false` (will update in Phase 5
+  if user opts in), `interview_turns`, `source: interview`.
+- **Intent:** expand the user's motivation into 3-5 sentences. This is
+  load-bearing — be explicit.
+- **Goal:** concrete end state.
+- **Non-Goals:** from user's answer, or empty list with note.
+- **Constraints / Preferences / NFRs:** from user's answers. Mark
+  "Not discussed — no constraints assumed" if not covered.
+- **Success Criteria:** falsifiable commands/observations. Reject vague
+  criteria from the user — ask for a concrete version if needed.
+- **Research Plan:** one section per identified topic, with the full
+  structure from the template. If 0 topics, write the "No external
+  research needed" note.
+- **Open Questions / Assumptions:** from "I don't know" answers and
+  implicit gaps.
+- **Prior Attempts:** from user's answer, or "None — fresh task."
+
+Populate the "How to continue" footer with the actual project path and
+topic questions.
+
+Report:
+```
+Brief written: {PROJECT_DIR}/brief.md
+Research topics identified: {N}
+```
+
+## Phase 5 — Auto-orchestration opt-in (if research_topics > 0)
+
+**Skip this phase if research_topics = 0.** Proceed directly to Phase 6.
+
+Ask the user via `AskUserQuestion`:
+
+**Question:** "You have {N} research topic(s). How do you want to proceed?"
+
+| Option | Description |
+|--------|-------------|
+| **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. |
+| **Auto (managed by Claude Code)** | I run all {N} research topics in parallel, then automatically trigger `/ultraplan-local` when research completes. Foreground — this session blocks until the plan is ready. |
+
+### Manual path (default)
+
+Output:
+
+```
+## Brief complete
+
+Project: {PROJECT_DIR}/
+Brief:   {PROJECT_DIR}/brief.md
+Research topics: {N}
+
+Next steps (run in order or parallel):
+
+{For each topic:}
+  /ultraresearch-local --project {PROJECT_DIR} --external "{topic question}"
+
+Then:
+  /ultraplan-local --project {PROJECT_DIR}
+
+Then:
+  /ultraexecute-local --project {PROJECT_DIR}
+```
+
+Stop. Do not continue to Phase 6.
+
+### Auto path
+
+Set `auto_research: true` in the brief's frontmatter (edit the file).
+
+Proceed to Phase 6.
+
+## Phase 6 — Auto research dispatch (auto path only)
+
+**Runs only when user opted into auto mode.**
+
+### Step 6a — Billing safety check
+
+Run via Bash:
+```bash
+echo "${ANTHROPIC_API_KEY:+SET}"
+```
+
+If `SET`, warn via `AskUserQuestion`:
+
+**Question:** "`ANTHROPIC_API_KEY` is set. Running {N} parallel research
+jobs in background will bill your API account (not your Claude
+subscription). Continue?"
+
+| Option | Action |
+|--------|--------|
+| **Continue — API billing** | Proceed. |
+| **Switch to sequential** | Run topics one at a time in foreground instead of parallel background. Stays on subscription for this session. |
+| **Cancel — do manual** | Revert to manual path (print commands, stop). |
+
+If cancelled → fall back to manual path output and stop.
+If sequential → note and proceed (Step 6b runs foreground, one at a time).
+If continue → proceed with parallel background.
+
+### Step 6b — Launch research jobs
+
+Set `research_status: in_progress` in the brief's frontmatter.
+
+For each research topic (index i = 1 .. N):
+
+Launch the **research-orchestrator** agent with this prompt:
+
+```
+Research question: {topic i question}
+Dimensions: {infer 3-5 dimensions from topic confidence + cost hints}
+Mode: {default if cost=standard or deep; quick if cost=quick}
+Scope: {topic i scope hint: local | external | both}
+Brief destination: {PROJECT_DIR}/research/{NN}-{topic-slug}.md
+Plugin root: ${CLAUDE_PLUGIN_ROOT}
+```
+
+Where `{NN}` is zero-padded index (`01`, `02`, ...) and `{topic-slug}` is
+the topic title slugified.
+
+**Parallel (default auto path):** launch all N research-orchestrator agents
+in parallel via a single message with multiple Agent tool calls, all
+`run_in_background: true`. **Do not wait** in the same message — return
+control. You will be notified when each completes.
+
+**Sequential (if user chose sequential):** launch one research-orchestrator
+at a time, foreground (no `run_in_background`), wait for completion, then
+launch the next.
+
+### Step 6c — Wait for all research to complete
+
+Wait for all research agent notifications. When all {N} have completed,
+verify each research brief file exists:
+
+```bash
+ls -1 {PROJECT_DIR}/research/*.md | wc -l
+```
+
+Expected count: N. If any are missing, report and ask the user how to
+proceed (retry, skip missing topic, cancel).
+
+Update brief frontmatter: `research_status: complete`.
+
+### Step 6d — Auto-trigger planning
+
+Launch the **planning-orchestrator** agent with this prompt:
+
+```
+Brief file: {PROJECT_DIR}/brief.md
+Project dir: {PROJECT_DIR}
+Task: {task description from brief}
+Mode: default
+Plan destination: {PROJECT_DIR}/plan.md
+Plugin root: ${CLAUDE_PLUGIN_ROOT}
+Research briefs: {list of {PROJECT_DIR}/research/*.md files}
+
+Read the brief file and every research brief. Execute your full planning
+workflow. Write the plan to the destination path.
+```
+
+Launch foreground (wait for completion — user asked for full auto).
+
+### Step 6e — Report completion
+
+When the planning-orchestrator finishes, present:
+
+```
+## Ultrabrief + Ultraresearch + Ultraplan Complete (auto mode)
+
+**Project:** {PROJECT_DIR}/
+**Brief:** {PROJECT_DIR}/brief.md
+**Research briefs:** {N} in {PROJECT_DIR}/research/
+**Plan:** {PROJECT_DIR}/plan.md
+
+### Pipeline summary
+
+| Step | Status |
+|------|--------|
+| Brief | Complete ({interview_turns} interview turns) |
+| Research | Complete ({N} topics, {P} parallel / {S} sequential) |
+| Plan | Complete ({steps} steps, critic: {verdict}) |
+
+Next:
+  /ultraexecute-local --project {PROJECT_DIR}
+
+Or:
+  /ultraexecute-local --dry-run --project {PROJECT_DIR}   # preview
+  /ultraexecute-local --validate --project {PROJECT_DIR}  # schema check
+```
+
+## Phase 7 — Stats tracking
+
+Append one record to `${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl`:
+
+```json
+{
+  "ts": "{ISO-8601}",
+  "task": "{task description (first 100 chars)}",
+  "slug": "{slug}",
+  "mode": "{default | quick}",
+  "interview_turns": {N},
+  "research_topics": {N},
+  "auto_research": {true | false},
+  "auto_result": "{completed | cancelled | failed | manual}",
+  "project_dir": "{path}"
+}
+```
+
+If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip silently.
+Never let stats failures block the workflow.
+
+## Hard rules
+
+1. **Interactive only.** This command requires user input. There is no
+   `--fg` or background mode — the interview cannot run headless.
+2. **Brief is the contract.** Every section must have substantive content
+   or an explicit "Not discussed" note. No empty sections.
+3. **Intent is load-bearing.** Do not accept a one-line intent. Expand with
+   the user until motivation is clear — the plan and every review agent
+   will trace decisions back to this.
+4. **Research topics must be answerable.** Each topic's research question
+   must be phrased so `/ultraresearch-local` can answer it. If a topic is
+   too vague, split or reformulate before writing.
+5. **Never invent research topics the user did not agree to.** Topics
+   come from the interview. If the user says "I know this", respect it.
+6. **Project dir is the single source of truth.** Every artifact (brief,
+   research briefs, plan, progress) lives in one project directory.
+   Never scatter files across `.claude/research/`, `.claude/plans/`, etc.
+7. **Auto mode blocks foreground.** If the user opts into auto, this
+   session waits for research + planning to complete. Document this in
+   the opt-in question.
+8. **Privacy:** never log prompt text, secrets, or credentials.