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>
This commit is contained in:
Kjell Tore Guttormsen
parent
fb9eb79d17
commit
2bc405e14a
15 changed files with 1799 additions and 592 deletions
420
plugins/ultraplan-local/commands/ultrabrief-local.md
Normal file
420
plugins/ultraplan-local/commands/ultrabrief-local.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: ultraexecute-local
|
||||
description: Disciplined plan executor — single-session or multi-session with parallel orchestration, failure recovery, and headless support
|
||||
argument-hint: "[--fg | --resume | --dry-run | --validate | --step N | --session N] <plan.md>"
|
||||
argument-hint: "[--project <dir>] [--fg | --resume | --dry-run | --validate | --step N | --session N] [plan.md]"
|
||||
model: opus
|
||||
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
||||
---
|
||||
|
|
@ -18,29 +18,49 @@ Designed to work identically in interactive and headless (`claude -p`) mode.
|
|||
|
||||
Parse `$ARGUMENTS` for mode flags:
|
||||
|
||||
1. If arguments contain `--fg`: extract the file path. Set **mode = foreground**.
|
||||
2. If arguments contain `--resume`: extract the file path. Set **mode = resume**.
|
||||
3. If arguments contain `--dry-run`: extract the file path. Set **mode = dry-run**.
|
||||
4. If arguments contain `--validate`: extract the file path. Set **mode = validate**.
|
||||
5. If arguments contain `--step N` (N is a positive integer): extract N and the file path.
|
||||
1. If arguments contain `--project <dir>`: extract the directory path.
|
||||
- Resolve `{dir}` (trim trailing slash).
|
||||
- Set **project_dir = {dir}**.
|
||||
- Derive implicit file path: `{dir}/plan.md`.
|
||||
- If `{dir}` does not exist or `{dir}/plan.md` is missing:
|
||||
```
|
||||
Error: project directory missing plan.md: {dir}
|
||||
Run /ultraplan-local --project {dir} to produce it.
|
||||
```
|
||||
- If no explicit `<plan.md>` argument is provided after flag parsing,
|
||||
use the derived `{dir}/plan.md`. If a `<plan.md>` argument IS provided,
|
||||
use that path but keep `project_dir` set (user may be pointing at a
|
||||
recovery session spec inside the project).
|
||||
- Continue parsing remaining flags (they combine with `--project`).
|
||||
2. If arguments contain `--fg`: extract the file path. Set **mode = foreground**.
|
||||
3. If arguments contain `--resume`: extract the file path. Set **mode = resume**.
|
||||
4. If arguments contain `--dry-run`: extract the file path. Set **mode = dry-run**.
|
||||
5. If arguments contain `--validate`: extract the file path. Set **mode = validate**.
|
||||
6. If arguments contain `--step N` (N is a positive integer): extract N and the file path.
|
||||
Set **mode = step**, **target-step = N**.
|
||||
6. If arguments contain `--session N` (N is a positive integer): extract N and the file path.
|
||||
7. If arguments contain `--session N` (N is a positive integer): extract N and the file path.
|
||||
Set **mode = session**, **target-session = N**.
|
||||
7. Otherwise: the entire argument string is the file path. Set **mode = execute**.
|
||||
8. Otherwise: the entire argument string is the file path. Set **mode = execute**.
|
||||
|
||||
If no path is provided, output usage and stop:
|
||||
If no path is provided (and `--project` was not used to derive one), output
|
||||
usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraexecute-local <plan.md>
|
||||
/ultraexecute-local --project <dir>
|
||||
/ultraexecute-local --fg <plan.md>
|
||||
/ultraexecute-local --resume <plan.md>
|
||||
/ultraexecute-local --dry-run <plan.md>
|
||||
/ultraexecute-local --validate <plan.md>
|
||||
/ultraexecute-local --step N <plan.md>
|
||||
/ultraexecute-local --session N <plan.md>
|
||||
/ultraexecute-local --project <dir> --resume
|
||||
/ultraexecute-local --project <dir> --session N
|
||||
|
||||
Modes:
|
||||
(default) Auto — multi-session if plan has Execution Strategy, else foreground
|
||||
--project Resolve plan.md inside an ultrabrief project folder; progress.json
|
||||
is written there too
|
||||
--fg Force foreground — all steps sequentially, ignore Execution Strategy
|
||||
--resume Resume from last progress checkpoint
|
||||
--dry-run Validate plan and show execution strategy without running
|
||||
|
|
@ -50,6 +70,8 @@ Modes:
|
|||
|
||||
Examples:
|
||||
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth --resume
|
||||
/ultraexecute-local --fg .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/ultraexecute-local --session 2 .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/ultraexecute-local --dry-run .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
|
|
@ -63,7 +85,8 @@ Error: file not found: {path}
|
|||
|
||||
Report detected mode:
|
||||
```
|
||||
Mode: {execute | resume | dry-run | step N}
|
||||
Mode: {execute | resume | dry-run | step N | session N}
|
||||
Project: {project_dir or "-"}
|
||||
File: {path}
|
||||
```
|
||||
|
||||
|
|
@ -634,12 +657,19 @@ need to know it is in a worktree — git handles this transparently.
|
|||
|
||||
## Phase 3 — Progress file setup
|
||||
|
||||
The progress file lives at `{plan-dir}/.ultraexecute-progress-{slug}.json` where
|
||||
`{slug}` is the plan filename without extension.
|
||||
The progress file location depends on whether `--project` is in use:
|
||||
|
||||
**Session-scoped naming:** When `mode = session N`, use
|
||||
`{plan-dir}/.ultraexecute-progress-{slug}-session-{N}.json` instead. This prevents
|
||||
merge conflicts when parallel sessions each write their own progress file.
|
||||
- **With `--project <dir>`:** progress lives at `{project_dir}/progress.json`.
|
||||
- **Without `--project`:** progress lives at
|
||||
`{plan-dir}/.ultraexecute-progress-{slug}.json`, where `{slug}` is the plan
|
||||
filename without extension.
|
||||
|
||||
**Session-scoped naming:** When `mode = session N`:
|
||||
- With `--project`: `{project_dir}/progress-session-{N}.json`.
|
||||
- Without `--project`: `{plan-dir}/.ultraexecute-progress-{slug}-session-{N}.json`.
|
||||
|
||||
This prevents merge conflicts when parallel sessions each write their own
|
||||
progress file.
|
||||
|
||||
### Progress file schema
|
||||
|
||||
|
|
|
|||
|
|
@ -1,114 +1,151 @@
|
|||
---
|
||||
name: ultraplan-local
|
||||
description: Deep implementation planning with interview, parallel specialized agents, external research, and optional background execution
|
||||
argument-hint: "[--spec spec.md | --fg] <task description>"
|
||||
description: Deep implementation planning from a task brief. Requires --brief or --project. Runs parallel specialized agents, optional external research, and adversarial review.
|
||||
argument-hint: "--brief <path> | --project <dir> [--fg | --quick | --research <brief> | --decompose <plan> | --export <fmt> <plan>]"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
|
||||
---
|
||||
|
||||
# Ultraplan Local v1.0
|
||||
# Ultraplan Local v2.0
|
||||
|
||||
Deep, multi-phase implementation planning. Uses an interview to gather requirements,
|
||||
adaptive specialized agent swarms for exploration, external research for unfamiliar
|
||||
technologies, and adversarial review to stress-test the plan.
|
||||
Deep, multi-phase implementation planning driven by a **task brief**.
|
||||
Planning consumes the brief (produced by `/ultrabrief-local`) and any
|
||||
research briefs referenced in it, then runs specialized exploration
|
||||
agents, synthesis, and adversarial review to produce an executable plan.
|
||||
|
||||
**v2.0 is a breaking release.** The interview phase has been extracted
|
||||
into `/ultrabrief-local`. This command no longer accepts free-text task
|
||||
descriptions — it requires either `--brief <path>` or `--project <dir>`.
|
||||
|
||||
Pipeline position:
|
||||
|
||||
```
|
||||
/ultrabrief-local → brief.md
|
||||
/ultraresearch-local → research/*.md
|
||||
/ultraplan-local → plan.md (this command)
|
||||
/ultraexecute-local → execution
|
||||
```
|
||||
|
||||
## Phase 1 — Parse mode and validate input
|
||||
|
||||
Parse `$ARGUMENTS` for mode flags:
|
||||
Parse `$ARGUMENTS` for mode flags. Order of precedence:
|
||||
|
||||
1. If arguments start with `--spec `: extract the file path after `--spec`.
|
||||
Set **mode = spec-driven**. Read the spec file. If it does not exist, report
|
||||
the error and stop.
|
||||
1. **`--export <format> <plan-path>`** — extract `{format}` (first token after
|
||||
`--export`) and `{plan-path}` (remainder). Valid formats: `pr`, `issue`,
|
||||
`markdown`, `headless`. Set **mode = export**.
|
||||
|
||||
2. If arguments start with `--fg `: extract the task description after `--fg`.
|
||||
Set **mode = foreground**.
|
||||
|
||||
3. If arguments start with `--quick `: extract the task description after `--quick`.
|
||||
Set **mode = quick**.
|
||||
|
||||
4. If arguments start with `--export `: extract the remainder as `{format} {plan-path}`.
|
||||
Split on the first space: format is the first token, plan path is the rest.
|
||||
Valid formats: `pr`, `issue`, `markdown`, `headless`.
|
||||
Set **mode = export**.
|
||||
|
||||
If the format is not one of pr/issue/markdown/headless, report and stop:
|
||||
If format is not in the valid set:
|
||||
```
|
||||
Error: unknown export format '{format}'. Valid: pr, issue, markdown, headless
|
||||
```
|
||||
|
||||
If the plan file does not exist, report and stop:
|
||||
If the plan file does not exist:
|
||||
```
|
||||
Error: plan file not found: {path}
|
||||
```
|
||||
|
||||
5. If arguments start with `--decompose `: extract the plan file path after `--decompose`.
|
||||
Set **mode = decompose**.
|
||||
|
||||
If the plan file does not exist, report and stop:
|
||||
2. **`--decompose <plan-path>`** — extract the plan path. Set **mode = decompose**.
|
||||
If the plan file does not exist:
|
||||
```
|
||||
Error: plan file not found: {path}
|
||||
```
|
||||
|
||||
6. If arguments contain `--research `: extract file path(s) after `--research`.
|
||||
Collect paths until encountering another `--` flag or a token that does not
|
||||
look like a file path (no `/` or `.md` extension). Maximum 3 briefs.
|
||||
Set **has_research_brief = true**. Validate each path exists — if any is
|
||||
missing, report and stop:
|
||||
3. **`--project <dir>`** — extract the project directory path.
|
||||
- Resolve `{dir}` (trim trailing slash).
|
||||
- Derive implicit flags:
|
||||
- `--brief {dir}/brief.md`
|
||||
- Plan destination: `{dir}/plan.md`
|
||||
- Research briefs auto-discovered from `{dir}/research/*.md` (sorted).
|
||||
- If `{dir}` does not exist or `{dir}/brief.md` is missing:
|
||||
```
|
||||
Error: project directory not initialized. Run /ultrabrief-local to create it.
|
||||
Missing: {dir}/brief.md
|
||||
```
|
||||
- Set **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
|
||||
- Set **has_research_brief = true** if `{dir}/research/*.md` matches ≥ 1 file.
|
||||
|
||||
4. **`--brief <path>`** — extract the brief path. If the file does not exist:
|
||||
```
|
||||
Error: brief file not found: {path}
|
||||
```
|
||||
Set **brief_path = {path}**. Plan destination will be derived in Phase 3
|
||||
from the brief's slug and date (see Phase 3).
|
||||
|
||||
5. **`--research <brief.md> [brief2.md] [brief3.md]`** — collect paths after
|
||||
`--research` until the next `--` flag or a token that does not look like a
|
||||
file path. Maximum 3 briefs. Set **has_research_brief = true**. Validate
|
||||
each path exists — if any is missing:
|
||||
```
|
||||
Error: research brief not found: {path}
|
||||
```
|
||||
The `--research` flag can combine with other flags:
|
||||
- `--research brief.md <task>` — default mode with research brief
|
||||
- `--research brief.md --fg <task>` — foreground with research brief
|
||||
- `--research brief.md --spec spec.md` — spec-driven with research brief
|
||||
Remove `--research` and its paths from the argument string before
|
||||
applying the other flag checks above.
|
||||
`--research` combines with `--brief`, `--project`, `--fg`, and `--quick`.
|
||||
When combined with `--project`, the explicit `--research` briefs are
|
||||
appended to the auto-discovered ones (deduplicated by path).
|
||||
|
||||
7. Otherwise: the entire argument string is the task description.
|
||||
Set **mode = default**.
|
||||
6. **`--fg`** — set **mode = foreground**. All phases run in this session
|
||||
(no background handoff).
|
||||
|
||||
If no task description and no spec file, output usage and stop:
|
||||
7. **`--quick`** — set **mode = quick**. Skip agent swarm; use lightweight
|
||||
Glob/Grep scan and go directly to planning + adversarial review.
|
||||
|
||||
8. If neither `--brief` nor `--project` is present after flag parsing,
|
||||
output usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraplan-local <task description>
|
||||
/ultraplan-local --spec <path-to-spec.md>
|
||||
/ultraplan-local --research <brief.md> [brief2.md] <task description>
|
||||
/ultraplan-local --fg <task description>
|
||||
/ultraplan-local --quick <task description>
|
||||
Usage: /ultraplan-local --brief <path-to-brief.md>
|
||||
/ultraplan-local --project <project-dir>
|
||||
/ultraplan-local --brief <path> --research <research-brief.md>
|
||||
/ultraplan-local --project <dir> --fg
|
||||
/ultraplan-local --project <dir> --quick
|
||||
/ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
|
||||
/ultraplan-local --decompose <plan-path>
|
||||
|
||||
A brief is required. Produce one with /ultrabrief-local first.
|
||||
|
||||
Modes:
|
||||
default Interview (interactive) → background planning → notify when done
|
||||
--spec Skip interview, use provided spec → background planning
|
||||
--research Enrich planning with pre-built research brief(s) (up to 3)
|
||||
--brief Plan from a brief file (background unless --fg)
|
||||
--project Plan from a project directory (brief.md + research/ auto-resolved)
|
||||
--research Add up to 3 extra research briefs as planning context
|
||||
--fg All phases in foreground (blocks session)
|
||||
--quick Interview → plan directly (no agent swarm) → adversarial review
|
||||
--quick Skip exploration agent swarm; plan directly
|
||||
--export Generate shareable output from an existing plan (no new planning)
|
||||
--decompose Split an existing plan into self-contained headless sessions
|
||||
|
||||
--research can combine with other flags:
|
||||
--research brief.md <task> Default mode + research context
|
||||
--research brief.md --fg <task> Foreground + research context
|
||||
--research brief.md --spec spec.md Spec-driven + research context
|
||||
|
||||
Examples:
|
||||
/ultraplan-local Add user authentication with JWT tokens
|
||||
/ultraplan-local --spec .claude/ultraplan-spec-2026-04-05-jwt-auth.md
|
||||
/ultraplan-local --research .claude/research/ultraresearch-2026-04-08-oauth2.md Implement OAuth2 auth
|
||||
/ultraplan-local --fg Refactor the database layer to use connection pooling
|
||||
/ultraplan-local --quick Add rate limiting to the API
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/brief.md
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --research extra.md
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --fg
|
||||
/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
/ultraplan-local --export headless .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
/ultraplan-local --decompose .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
|
||||
Migrating from v1.x? See MIGRATION.md in this plugin. The old --spec flag
|
||||
and free-text interview mode were removed in v2.0.
|
||||
```
|
||||
|
||||
Do not continue past this step if no task was provided.
|
||||
Do not continue past this step if no brief was provided.
|
||||
|
||||
Report the detected mode to the user:
|
||||
### Read the brief
|
||||
|
||||
Read the brief file and parse its frontmatter. Extract:
|
||||
- `task` — one-line task description
|
||||
- `slug` — slug for plan filenames
|
||||
- `project_dir` — if present, overrides derived project path (optional)
|
||||
- `research_topics` — N (used as a sanity check)
|
||||
- `research_status` — `pending | in_progress | complete | skipped`
|
||||
|
||||
If `research_status == pending` and `research_topics > 0`:
|
||||
- Warn the user: "Brief declares {N} research topics but research is still
|
||||
pending. Plan confidence will be lower. Continue anyway?"
|
||||
- `AskUserQuestion`: **Continue with low confidence** / **Cancel — run research first**.
|
||||
- If cancel: print the research invocations from the brief's "How to continue"
|
||||
section and stop.
|
||||
|
||||
Report the detected mode:
|
||||
```
|
||||
Mode: {default | spec-driven | foreground}
|
||||
Task: {task description or "from spec: {path}"}
|
||||
Mode: {background | foreground | quick | export | decompose}
|
||||
Brief: {brief_path}
|
||||
Project: {project_dir or "-"}
|
||||
Research: {N local briefs, M extra via --research}
|
||||
```
|
||||
|
||||
## Phase 1.5 — Export (runs only when mode = export)
|
||||
|
|
@ -189,7 +226,7 @@ After outputting the formatted block (for pr/issue/markdown), say:
|
|||
Export complete ({format}). Copy the block above.
|
||||
```
|
||||
|
||||
Then **stop**. Do not continue to Phase 2 or any subsequent phase.
|
||||
Then **stop**. Do not continue to any subsequent phase.
|
||||
|
||||
## Phase 1.6 — Decompose (runs only when mode = decompose or export headless)
|
||||
|
||||
|
|
@ -252,108 +289,43 @@ You can:
|
|||
|
||||
If the user says **"launch"**: run the launch script via Bash.
|
||||
|
||||
Then **stop**. Do not continue to Phase 2 or any subsequent phase.
|
||||
Then **stop**. Do not continue to any subsequent phase.
|
||||
|
||||
## Phase 2 — Requirements gathering (interview)
|
||||
## Phase 2 — (removed in v2.0)
|
||||
|
||||
**Skip this phase entirely if mode = spec-driven.** Proceed to Phase 3.
|
||||
|
||||
### Research-enriched interview
|
||||
|
||||
If **has_research_brief = true**: read each research brief file before starting the
|
||||
interview. Then adjust the interview:
|
||||
|
||||
1. Tell the user: "I've read {N} research brief(s). The interview will focus on
|
||||
decisions and implementation details — skipping topics already covered."
|
||||
2. Skip questions about technologies, patterns, or approaches already researched.
|
||||
3. Focus on: implementation preferences, non-functional requirements, scope decisions.
|
||||
4. Reference brief findings in questions where relevant:
|
||||
> "The research brief found that {finding}. Does this affect your approach?"
|
||||
> "The brief identified {risk}. Should the plan account for this?"
|
||||
|
||||
If **has_research_brief = false**: proceed with the standard interview below.
|
||||
|
||||
Use `AskUserQuestion` to interview the user about the task. Ask **one question at
|
||||
a time** — never dump all questions at once. Follow up based on answers.
|
||||
|
||||
### Interview flow
|
||||
|
||||
**Start with the most important question:**
|
||||
> What is the goal of this task? What does success look like?
|
||||
|
||||
**Then ask follow-ups based on the answer. Choose from these topics:**
|
||||
- What is explicitly NOT in scope? (non-goals)
|
||||
- Are there technical constraints? (specific versions, compatibility, no new dependencies)
|
||||
- Do you have preferences? (library X over Y, specific patterns, architectural style)
|
||||
- Are there non-functional requirements? (performance targets, security needs, accessibility)
|
||||
- Has anything been tried before? What worked or failed?
|
||||
|
||||
**Rules:**
|
||||
- Ask 3–5 questions for typical tasks. Maximum 8 for complex tasks.
|
||||
- If the user says "skip", "proceed", "just plan it", or similar — stop interviewing
|
||||
immediately. Write a minimal spec from the task description alone.
|
||||
- Adapt your questions to what the user tells you. If they give a detailed task
|
||||
description, skip obvious questions.
|
||||
- Never ask about things you can discover from the codebase.
|
||||
|
||||
### Adaptive depth
|
||||
|
||||
After each answer, assess the response length and vocabulary:
|
||||
|
||||
- **Detailed answer** (2+ sentences, technical terminology, specific examples):
|
||||
- Treat the user as senior — they know the codebase
|
||||
- Skip obvious follow-ups they already answered
|
||||
- Ask more targeted questions: constraints, edge cases, specific technical choices
|
||||
- Reduce question count: aim for 3–4 total instead of 5
|
||||
|
||||
- **Short or uncertain answer** (1 sentence or less, "I don't know", "not sure", vague):
|
||||
- Treat the user as unfamiliar with the problem space
|
||||
- Simplify follow-up questions — avoid open-ended technical questions
|
||||
- Offer alternatives instead of asking open questions:
|
||||
> "Should this be synchronous or asynchronous? (synchronous is simpler; async handles more concurrent users)"
|
||||
- For bugs: focus on reproduction before requirements:
|
||||
> "What do you see? What did you expect to see?"
|
||||
- Allow "I don't know" as a valid answer — record it as an open assumption in the spec
|
||||
|
||||
Never change your question count based on impatience. Only change depth based
|
||||
on answer quality.
|
||||
|
||||
### Write the spec file
|
||||
|
||||
After gathering requirements, read the spec template:
|
||||
@${CLAUDE_PLUGIN_ROOT}/templates/spec-template.md
|
||||
|
||||
Generate a slug from the task (first 3-4 meaningful words, lowercase, hyphens).
|
||||
Write the spec to: `.claude/ultraplan-spec-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Create the `.claude/` directory if it does not exist.
|
||||
|
||||
Fill in all sections based on interview answers. Mark unanswered sections with
|
||||
"Not discussed — no constraints assumed."
|
||||
|
||||
Tell the user:
|
||||
```
|
||||
Spec saved: .claude/ultraplan-spec-{date}-{slug}.md
|
||||
```
|
||||
The interview phase has moved to `/ultrabrief-local`. This command no
|
||||
longer asks the user any requirements questions — the brief is the
|
||||
authoritative input.
|
||||
|
||||
## Phase 3 — Background transition
|
||||
|
||||
**If mode = foreground or quick:** Skip this phase. Continue to Phase 4 inline.
|
||||
|
||||
**If mode = default or spec-driven:**
|
||||
**If mode = default (background):**
|
||||
|
||||
Determine the plan destination path:
|
||||
- If `project_dir` is set (from `--project` or the brief's `project_dir`
|
||||
frontmatter field): **plan destination = {project_dir}/plan.md**.
|
||||
- Otherwise: derive slug and date — if the brief has frontmatter `slug` and
|
||||
`created`, use them; otherwise extract from the brief filename. Destination:
|
||||
`.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`.
|
||||
|
||||
Collect all research briefs (from `--research` flag and auto-discovered
|
||||
`{project_dir}/research/*.md`).
|
||||
|
||||
Launch the **planning-orchestrator** agent with this prompt:
|
||||
|
||||
```
|
||||
Spec file: {spec path}
|
||||
Task: {task description}
|
||||
Mode: {default | spec | quick}
|
||||
Plan destination: .claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md
|
||||
Brief file: {brief_path}
|
||||
Project dir: {project_dir or "-"}
|
||||
Task: {task from brief frontmatter}
|
||||
Mode: {default | quick}
|
||||
Plan destination: {plan destination}
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
Research briefs: {path1, path2, ...} ← include ONLY if has_research_brief = true
|
||||
Research briefs: {comma-separated list, or "none"}
|
||||
|
||||
Read the spec file and execute your full planning workflow.
|
||||
Write the plan to the destination path.
|
||||
Read the brief file and every research brief. Execute your full planning
|
||||
workflow. Write the plan to the destination path.
|
||||
```
|
||||
|
||||
Launch the planning-orchestrator via the Agent tool with `run_in_background: true`.
|
||||
|
|
@ -361,11 +333,13 @@ The agent runs autonomously while you continue working — you will be notified
|
|||
when the plan is ready.
|
||||
|
||||
Then output to the user and **stop your response**:
|
||||
|
||||
```
|
||||
Background planning started via planning-orchestrator.
|
||||
|
||||
Spec: .claude/ultraplan-spec-{date}-{slug}.md
|
||||
Plan: .claude/plans/ultraplan-{date}-{slug}.md
|
||||
Brief: {brief_path}
|
||||
Project: {project_dir or "-"}
|
||||
Plan: {plan destination}
|
||||
|
||||
You will be notified when the plan is ready.
|
||||
You can continue working on other tasks in the meantime.
|
||||
|
|
@ -400,11 +374,11 @@ Report:
|
|||
Codebase: {N} source files ({scale}). Deploying exploration agents.
|
||||
```
|
||||
|
||||
## Phase 4b — Spec review
|
||||
## Phase 4b — Brief review
|
||||
|
||||
Launch the **spec-reviewer** agent:
|
||||
Prompt: "Review this spec for quality: {spec path}. Check completeness, consistency,
|
||||
testability, and scope clarity."
|
||||
Launch the **brief-reviewer** agent:
|
||||
Prompt: "Review this task brief for quality: {brief_path}. Check completeness,
|
||||
consistency, testability, scope clarity, and research-plan validity."
|
||||
|
||||
Handle the verdict:
|
||||
- **PROCEED** — continue to Phase 5.
|
||||
|
|
@ -416,7 +390,7 @@ Handle the verdict:
|
|||
|
||||
**If mode = quick:** Do NOT launch any exploration agents. Instead, run a
|
||||
lightweight file check:
|
||||
- `Glob` for files matching key terms from the task description (up to 3 patterns)
|
||||
- `Glob` for files matching key terms from the brief's task/intent (up to 3 patterns)
|
||||
- `Grep` for function/type definitions matching key terms (up to 3 patterns)
|
||||
|
||||
Report findings as:
|
||||
|
|
@ -444,7 +418,7 @@ medium: default, large: default) instead of dropping agents.
|
|||
| `task-finder` | Yes | Yes | Yes | Task-relevant files, functions, types, reuse candidates |
|
||||
| `test-strategist` | Yes | Yes | Yes | Test patterns, coverage gaps, strategy |
|
||||
| `git-historian` | Yes | Yes | Yes | Recent changes, ownership, hot files, active branches |
|
||||
| `research-scout` | Conditional | Conditional | Conditional | External docs (only when unfamiliar tech detected) |
|
||||
| `research-scout` | Conditional | Conditional | Conditional | External docs (only when unfamiliar tech detected AND no research brief covers it) |
|
||||
| `convention-scanner` | No | Yes | Yes | Coding conventions, naming, style, test patterns |
|
||||
|
||||
### Always launch (all codebase sizes):
|
||||
|
|
@ -481,19 +455,25 @@ Provide concrete examples from the codebase, not generic advice."
|
|||
|
||||
### Conditional: External research
|
||||
|
||||
After reading the task description and spec (if available), determine if the task
|
||||
involves technologies, APIs, or libraries that are:
|
||||
After reading the brief, determine if the task involves technologies, APIs, or
|
||||
libraries that are:
|
||||
- Not clearly present in the codebase
|
||||
- Being upgraded to a new major version
|
||||
- Being used in an unfamiliar way
|
||||
|
||||
If yes: launch **research-scout** in parallel with the other agents.
|
||||
**Skip research-scout** for any topic already answered by an attached research
|
||||
brief. If the brief's `research_status == complete` and all `Research Plan`
|
||||
topics have corresponding research files, skip research-scout entirely.
|
||||
|
||||
If yes (and not covered by attached briefs): launch **research-scout** in
|
||||
parallel with the other agents.
|
||||
Prompt: "Research the following technologies for this task: {task}.
|
||||
Specific questions: {list specific questions about the technology}.
|
||||
Technologies to research: {list}."
|
||||
|
||||
If no external technology is involved: skip research-scout and note:
|
||||
"No external research needed — all technologies are well-represented in the codebase."
|
||||
If no external technology is involved or all topics are covered by briefs:
|
||||
skip research-scout and note:
|
||||
"No external research needed — covered by research briefs / well-represented in codebase."
|
||||
|
||||
## Phase 6 — Targeted deep-dives
|
||||
|
||||
|
|
@ -530,18 +510,19 @@ Do NOT write this synthesis to disk. It is internal working context only.
|
|||
|
||||
## Phase 8 — Deep planning
|
||||
|
||||
Read the spec file (from Phase 2 or provided via --spec).
|
||||
Read the brief file (from `--brief` or `--project`).
|
||||
Read the plan template: @${CLAUDE_PLUGIN_ROOT}/templates/plan-template.md
|
||||
|
||||
Write the plan following the template structure. The plan MUST include:
|
||||
|
||||
### Required sections
|
||||
|
||||
1. **Context** — Why this change is needed. Reference the spec's goal and constraints.
|
||||
1. **Context** — Why this change is needed. Use the brief's **Intent** verbatim
|
||||
or tightly paraphrased. The plan's motivation must trace directly to the brief.
|
||||
2. **Codebase Analysis** — Tech stack, patterns, relevant files, reusable code,
|
||||
external tech researched. Every file path must be real (verified during exploration).
|
||||
3. **Research Sources** — If research-scout was used: table of technologies, sources,
|
||||
findings, and confidence levels. Omit if no research was conducted.
|
||||
3. **Research Sources** — If any research briefs or research-scout was used: table
|
||||
of technologies, sources, findings, and confidence levels. Omit if none.
|
||||
4. **Implementation Plan** — Ordered steps. Each step specifies:
|
||||
- Exact files to modify or create (with paths)
|
||||
- What changes to make and why
|
||||
|
|
@ -555,12 +536,12 @@ Write the plan following the template structure. The plan MUST include:
|
|||
specify scope fences per session. Omit for plans with ≤ 5 steps.
|
||||
5. **Alternatives Considered** — At least one alternative approach with
|
||||
pros/cons and reason for rejection.
|
||||
6. **Risks and Mitigations** — From the risk-assessor findings. What could go
|
||||
wrong and how to handle it.
|
||||
6. **Risks and Mitigations** — From the risk-assessor findings and the brief's
|
||||
open questions. What could go wrong and how to handle it.
|
||||
7. **Test Strategy** — From the test-strategist findings (if available).
|
||||
What tests to write and which patterns to follow.
|
||||
8. **Verification** — Testable criteria. Not "check that it works" but
|
||||
specific commands to run and expected outputs.
|
||||
8. **Verification** — Reuse the brief's **Success Criteria** as the baseline.
|
||||
Each criterion must be an executable command or observable condition.
|
||||
9. **Estimated Scope** — File counts and complexity rating.
|
||||
|
||||
### Quality standards
|
||||
|
|
@ -574,12 +555,16 @@ Write the plan following the template structure. The plan MUST include:
|
|||
- The plan must be implementable by someone who has not seen the exploration
|
||||
results — it must stand on its own
|
||||
- Research-based decisions must cite their source
|
||||
- Every implementation decision must be traceable to a brief section (Intent,
|
||||
Goal, Constraint, Preference, NFR, or Success Criterion)
|
||||
|
||||
### Write the plan
|
||||
|
||||
Generate the slug from the task description (or reuse the spec slug).
|
||||
Write the plan to: `.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`
|
||||
Create the `.claude/plans/` directory if it does not exist.
|
||||
Use the plan destination computed in Phase 3:
|
||||
- `--project` mode: `{project_dir}/plan.md`
|
||||
- `--brief` mode: `.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Create the parent directory if it does not exist.
|
||||
|
||||
## Phase 9 — Adversarial review
|
||||
|
||||
|
|
@ -592,10 +577,12 @@ wrong ordering, fragile assumptions, missing error handling, scope creep,
|
|||
underspecified steps. Rate each finding as blocker, major, or minor."
|
||||
|
||||
**scope-guardian** — scope alignment check.
|
||||
Prompt: "Check this implementation plan against the requirements.
|
||||
Task: {task}. Spec file: {spec path}. Plan file: {plan path}.
|
||||
Find scope creep (plan does more than asked) and scope gaps (plan misses
|
||||
requirements). Check that referenced files and functions exist."
|
||||
Prompt: "Check this implementation plan against the brief.
|
||||
Task: {task}. Brief file: {brief_path}. Plan file: {plan path}.
|
||||
Find scope creep (plan does more than the brief requires) and scope gaps
|
||||
(plan misses brief requirements). Check that referenced files and functions
|
||||
exist. Verify that every Success Criterion in the brief is covered by the
|
||||
plan's Verification section."
|
||||
|
||||
After both complete:
|
||||
- If **blockers** are found: revise the plan to address them. Add a "Revisions"
|
||||
|
|
@ -612,9 +599,10 @@ Present a summary to the user:
|
|||
## Ultraplan Complete
|
||||
|
||||
**Task:** {task description}
|
||||
**Mode:** {default | spec-driven | foreground}
|
||||
**Spec:** {spec file path, or "none (foreground mode)"}
|
||||
**Plan:** .claude/plans/ultraplan-{date}-{slug}.md
|
||||
**Mode:** {background | foreground | quick}
|
||||
**Brief:** {brief_path}
|
||||
**Project:** {project_dir or "-"}
|
||||
**Plan:** {plan_path}
|
||||
**Exploration:** {N} agents deployed ({N} specialized + {N} deep-dives + {research status})
|
||||
**Scope:** {N} files to modify, {N} to create — {complexity}
|
||||
|
||||
|
|
@ -628,7 +616,7 @@ Present a summary to the user:
|
|||
...
|
||||
|
||||
### Research findings
|
||||
{Summary of external research, or "No external research conducted."}
|
||||
{Summary of external research + attached research briefs, or "No external research used."}
|
||||
|
||||
### Adversarial review
|
||||
**Plan critic:** {Summary — blockers/majors/minors found, how addressed}
|
||||
|
|
@ -650,7 +638,7 @@ If the user asks questions or requests changes:
|
|||
|
||||
### "save" / "later" / "done"
|
||||
|
||||
Confirm the plan and spec file locations and exit.
|
||||
Confirm the plan and brief file locations and exit.
|
||||
|
||||
### "execute" / "go" / "start"
|
||||
|
||||
|
|
@ -687,13 +675,16 @@ Record format (one JSON line):
|
|||
{
|
||||
"ts": "{ISO-8601 timestamp}",
|
||||
"task": "{task description (first 100 chars)}",
|
||||
"mode": "{default|spec|fg}",
|
||||
"mode": "{default|fg|quick}",
|
||||
"slug": "{plan slug}",
|
||||
"brief_path": "{brief_path}",
|
||||
"project_dir": "{project_dir or null}",
|
||||
"codebase_size": "{small|medium|large}",
|
||||
"codebase_files": {N},
|
||||
"agents_deployed": {N},
|
||||
"deep_dives": {N},
|
||||
"research": {true|false},
|
||||
"research_briefs_used": {N},
|
||||
"research_scout_used": {true|false},
|
||||
"critic_verdict": "{BLOCK|REVISE|PASS}",
|
||||
"guardian_verdict": "{ALIGNED|CREEP|GAP|MIXED}",
|
||||
"outcome": "{execute|execute_team|save|refine}"
|
||||
|
|
@ -705,6 +696,11 @@ Never let tracking failures block the main workflow.
|
|||
|
||||
## Hard rules
|
||||
|
||||
- **Brief-driven**: Every plan decision must trace back to a section of the
|
||||
brief (Intent, Goal, Constraint, Preference, NFR, Success Criterion). If a
|
||||
step has no brief basis, it is scope creep — flag it or remove it.
|
||||
- **No interview**: Never ask the user requirements questions. If the brief is
|
||||
inadequate, stop and ask the user to run `/ultrabrief-local` again.
|
||||
- **Scope**: Only explore the current working directory and its subdirectories.
|
||||
Never read files outside the repo (no ~/.env, no credentials, no other repos).
|
||||
- **Cost**: Sonnet for all agents (exploration, deep-dives, research, critics).
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: ultraresearch-local
|
||||
description: Deep research combining local codebase analysis with external knowledge, producing structured research briefs with triangulation and confidence ratings
|
||||
argument-hint: "[--quick | --local | --external | --fg] <research question>"
|
||||
argument-hint: "[--project <dir>] [--quick | --local | --external | --fg] <research question>"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, WebSearch, WebFetch, mcp__tavily__tavily_search, mcp__tavily__tavily_research
|
||||
---
|
||||
|
|
@ -42,12 +42,24 @@ Supported flags:
|
|||
4. `--fg` — foreground mode. Run all phases inline (blocking) instead of
|
||||
launching the research-orchestrator in background. Set **execution = foreground**.
|
||||
|
||||
5. `--project <dir>` — attach this research to an ultrabrief project folder.
|
||||
The brief will be written to `{dir}/research/{NN}-{slug}.md` (auto-incremented
|
||||
index) instead of the default `.claude/research/` path. Set **project_dir = {dir}**.
|
||||
|
||||
If `{dir}` does not exist:
|
||||
```
|
||||
Error: project directory not found: {dir}
|
||||
Run /ultrabrief-local first to create it.
|
||||
```
|
||||
Create `{dir}/research/` if it does not already exist.
|
||||
|
||||
Flags can be combined:
|
||||
- `--local --fg` — local-only research, foreground
|
||||
- `--external --quick` — external-only, lightweight
|
||||
- `--project <dir> --external` — attach external research to a project
|
||||
- `--quick` alone implies both local and external (lightweight)
|
||||
|
||||
Defaults: **scope = both**, **execution = background**.
|
||||
Defaults: **scope = both**, **execution = background**, **project_dir = none**.
|
||||
|
||||
After stripping flags, the remaining text is the **research question**.
|
||||
|
||||
|
|
@ -59,6 +71,7 @@ Usage: /ultraresearch-local <research question>
|
|||
/ultraresearch-local --local <research question>
|
||||
/ultraresearch-local --external <research question>
|
||||
/ultraresearch-local --fg <research question>
|
||||
/ultraresearch-local --project <dir> [--external|--local|--quick|--fg] <research question>
|
||||
|
||||
Modes:
|
||||
default Interview → background research (local + external) → brief
|
||||
|
|
@ -66,8 +79,9 @@ Modes:
|
|||
--local Only codebase analysis agents (skip external + Gemini)
|
||||
--external Only external research agents (skip codebase analysis)
|
||||
--fg All phases in foreground (blocks session)
|
||||
--project Write brief into an ultrabrief project folder (auto-indexed)
|
||||
|
||||
Flags can be combined: --local --fg, --external --quick
|
||||
Flags can be combined: --local --fg, --external --quick, --project <dir> --external
|
||||
|
||||
Examples:
|
||||
/ultraresearch-local Should we migrate from Express to Fastify?
|
||||
|
|
@ -75,6 +89,7 @@ Examples:
|
|||
/ultraresearch-local --local How is error handling structured in this codebase?
|
||||
/ultraresearch-local --external What are the security implications of using Redis for sessions?
|
||||
/ultraresearch-local --fg --local What patterns does this codebase use for database access?
|
||||
/ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external What JWT library is best for Node.js?
|
||||
```
|
||||
|
||||
Do not continue past this step if no question was provided.
|
||||
|
|
@ -82,9 +97,23 @@ Do not continue past this step if no question was provided.
|
|||
Report the detected mode:
|
||||
```
|
||||
Mode: {default | quick}, Scope: {both | local | external}, Execution: {background | foreground}
|
||||
Project: {project_dir or "-"}
|
||||
Question: {research question}
|
||||
```
|
||||
|
||||
### Compute brief destination
|
||||
|
||||
If **project_dir is set**:
|
||||
- Scan `{project_dir}/research/` for existing files matching `NN-*.md`.
|
||||
- Find the highest existing index; set `N = highest + 1`. If no files exist, `N = 1`.
|
||||
- Zero-pad to 2 digits: `01`, `02`, ...
|
||||
- Brief destination: `{project_dir}/research/{NN}-{slug}.md`
|
||||
|
||||
If **project_dir is not set**:
|
||||
- Brief destination: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Store as `brief_destination` for use in later phases.
|
||||
|
||||
## Phase 2 — Research interview
|
||||
|
||||
Use `AskUserQuestion` to clarify the research question. Ask **one question at a time**.
|
||||
|
|
@ -146,7 +175,7 @@ Research dimensions identified:
|
|||
**If execution = background (default):**
|
||||
|
||||
Generate a slug from the research question (first 3-4 meaningful words, lowercase,
|
||||
hyphens).
|
||||
hyphens). Use the `brief_destination` computed in Phase 1.
|
||||
|
||||
Launch the **research-orchestrator** agent with this prompt:
|
||||
|
||||
|
|
@ -155,7 +184,8 @@ Research question: {question}
|
|||
Dimensions: {list of dimensions from interview}
|
||||
Mode: {default | quick}
|
||||
Scope: {both | local | external}
|
||||
Brief destination: .claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md
|
||||
Project dir: {project_dir or "-"}
|
||||
Brief destination: {brief_destination}
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
```
|
||||
|
||||
|
|
@ -168,7 +198,8 @@ Background research started via research-orchestrator.
|
|||
Question: {research question}
|
||||
Dimensions: {N} identified
|
||||
Scope: {both | local | external}
|
||||
Brief: .claude/research/ultraresearch-{date}-{slug}.md
|
||||
Project: {project_dir or "-"}
|
||||
Brief: {brief_destination}
|
||||
|
||||
You will be notified when the research brief is ready.
|
||||
You can continue working on other tasks in the meantime.
|
||||
|
|
@ -317,8 +348,11 @@ Write the research brief following the template. Key rules:
|
|||
6. **Sources** — every claim traced to URL or codebase path.
|
||||
|
||||
Generate the slug from the research question (first 3-4 meaningful words).
|
||||
Write the brief to: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
Create the `.claude/research/` directory if needed.
|
||||
Write the brief to the `brief_destination` computed in Phase 1:
|
||||
- With `--project`: `{project_dir}/research/{NN}-{slug}.md`
|
||||
- Without `--project`: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Create the parent directory if it does not exist.
|
||||
|
||||
## Phase 8 — Present and track
|
||||
|
||||
|
|
@ -329,7 +363,8 @@ Present a summary to the user:
|
|||
|
||||
**Question:** {research question}
|
||||
**Mode:** {default | quick}, Scope: {both | local | external}
|
||||
**Brief:** .claude/research/ultraresearch-{date}-{slug}.md
|
||||
**Brief:** {brief_destination}
|
||||
**Project:** {project_dir or "-"}
|
||||
**Confidence:** {overall confidence 0.0-1.0}
|
||||
**Dimensions:** {N} researched
|
||||
**Agents:** {N} local + {N} external + {gemini: used | unavailable | skipped}
|
||||
|
|
@ -346,8 +381,9 @@ Present a summary to the user:
|
|||
- {Question 1, or "None — all dimensions adequately covered."}
|
||||
|
||||
You can:
|
||||
- Read the full brief at {brief path}
|
||||
- Feed into planning: `/ultraplan-local --research {brief path} <task>`
|
||||
- Read the full brief at {brief_destination}
|
||||
- If `--project` was used: run `/ultraplan-local --project {project_dir}` when all research topics are complete
|
||||
- Otherwise: `/ultraplan-local --research {brief_destination} --brief <your-brief.md>`
|
||||
- Ask follow-up questions about specific findings
|
||||
```
|
||||
|
||||
|
|
@ -364,6 +400,8 @@ Record format (one JSON line):
|
|||
"mode": "{default|quick}",
|
||||
"scope": "{both|local|external}",
|
||||
"slug": "{brief slug}",
|
||||
"project_dir": "{project_dir or null}",
|
||||
"brief_path": "{brief_destination}",
|
||||
"dimensions": {N},
|
||||
"agents_local": {N},
|
||||
"agents_external": {N},
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue