open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

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

Browse source 
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 2026-04-18 07:22:08 +02:00
commit 2bc405e14a
15 changed files with 1799 additions and 592 deletions
Download patch file Download diff file Expand all files Collapse all files

2
CLAUDE.md
View file

@ -12,7 +12,7 @@ plugins/
llm-security/ v6.0.0 — Security scanning, auditing, threat modeling
ms-ai-architect/ v1.8.0 — Microsoft AI architecture (Cosmo Skyberg persona)
okr/ v1.0.0 — OKR guidance for Norwegian public sector
ultraplan-local/ v1.6.0 — Deep planning, research, execution
ultraplan-local/ v2.0.0 — Brief, research, plan, execute (four-command pipeline)
```
Hvert plugin er selvstendig med egen CLAUDE.md, README, hooks, agents og commands.

21
README.md
View file

@ -61,27 +61,30 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud
---
### [Ultra {research | plan | execute} - local](plugins/ultraplan-local/) `v1.8.0`
### [Ultra {brief | research | plan | execute} - local](plugins/ultraplan-local/) `v2.0.0`
Deep research, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery.
Deep requirements gathering, research, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery.
Three commands, one pipeline with clear division of labor:
Four commands, one pipeline with clear division of labor:
- **`/ultrabrief-local`** — Capture intent. Interactive interview (3-8 adaptive questions) produces a task brief with explicit research plan. Identifies research topics with copy-paste-ready `/ultraresearch-local` commands. Optional auto-orchestration runs research + planning in foreground. Always interactive.
- **`/ultraresearch-local`** — Gather context. Deep multi-source research with triangulation: 5 local agents + 4 external agents + Gemini bridge, producing structured briefs with confidence ratings. Makes no build decisions.
- **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Accepts research briefs via `--research`.
- **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`).
- **`/ultraexecute-local`** — Execute the contract disciplined. Manifest-based verification, independent Phase 7.5 audit from git log + filesystem (ignores agent bookkeeping), Phase 7.6 bounded recovery dispatch for missing steps. Step 0 pre-flight catches sandbox push-denial before any work. `--validate` mode offers a fast schema-only sanity-check between planning and execution.
v1.7 self-verifying chain: a step may not be marked `completed` unless its manifest verifies. The executor's last tool call before reporting must be a manifest check, not an arbitrary file review — preventing hallucinated completion.
All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`. `--project <dir>` works across `/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`.
v1.8 closes the Opus 4.7 prompt-literalism gap: planning-orchestrator now emits a literal copyable Step+Manifest template (not prose rules), explicitly forbids narrative `Fase/Phase/Stage` headers, and runs a schema self-check before handing off to plan-critic. Prevents the "plan generated, executor rejects" loop observed when 4.7 inferred the v1.7 schema from prose descriptions alone.
v2.0 extracts interview from planning: briefs are now reviewable artifacts with explicit intent, research plan, and falsifiable success criteria — each a contract that downstream agents (`brief-reviewer`, `plan-critic`, `scope-guardian`) can validate independently. Breaking change: `/ultraplan-local` no longer runs an interview and requires `--brief` or `--project`. See `plugins/ultraplan-local/MIGRATION.md`.
v1.7 self-verifying chain (preserved): a step may not be marked `completed` unless its manifest verifies. v1.8 Opus 4.7 literalism fixes (preserved): literal Step+Manifest template, forbidden narrative headers, schema self-check.
Defense-in-depth security: plugin hooks block destructive commands and sensitive path writes, prompt-level denylist works in headless sessions, pre-execution plan scan catches dangerous commands before they run, scoped `--allowedTools` replaces `--dangerously-skip-permissions` in parallel sessions.
Modes: default, spec-driven, research-enriched, foreground, quick, decompose, export
Modes: default, brief-driven, project-scoped, research-enriched, foreground, quick, decompose, export
19 specialized agents · 3 commands · 2 security hooks · No cloud dependency
19 specialized agents · 4 commands · 2 security hooks · No cloud dependency
→ [Full documentation](plugins/ultraplan-local/README.md)
→ [Full documentation](plugins/ultraplan-local/README.md) · [Migration guide](plugins/ultraplan-local/MIGRATION.md)
---

4
plugins/ultraplan-local/.claude-plugin/plugin.json
View file

@ -1,7 +1,7 @@
{
"name": "ultraplan-local",
"description": "Deep implementation planning and research with interview, specialized agent swarms, external research, triangulation, adversarial review, session decomposition, and headless execution support.",
"version": "1.8.0",
"description": "Four-command context-engineering pipeline (brief → research → plan → execute) with project folders, specialized agent swarms, external research triangulation, adversarial review, session decomposition, and headless execution.",
"version": "2.0.0",
"author": {
"name": "Kjell Tore Guttormsen"
},

92
plugins/ultraplan-local/CHANGELOG.md
View file

@ -4,6 +4,98 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [2.0.0] - 2026-04-18
### Breaking — Four-command pipeline with dedicated brief step
v2.0.0 introduces `/ultrabrief-local` as a first-class step in the pipeline.
The interview previously embedded inside `/ultraplan-local` has been extracted
into a dedicated command that produces a structured **task brief** — the
contract between user intent and planning. `/ultraplan-local` now requires
a brief as input and no longer conducts interviews.
All artifacts converge into one **project directory**:
`.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`,
`plan.md`, `sessions/`, and `progress.json`. `--project <dir>` works across
`/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`.
See [MIGRATION.md](MIGRATION.md) for v1 → v2 upgrade guide.
### Breaking changes
- **`/ultraplan-local` requires `--brief <path>` or `--project <dir>`.** Running
without either exits with an error and a pointer to `/ultrabrief-local`.
- **`/ultraplan-local --spec <path>` is removed.** Convert specs to briefs by
adding `## Intent` and `## Research Plan` sections (see MIGRATION.md).
- **Interview inside `/ultraplan-local` is removed.** Planning no longer asks
questions — all intent must be captured in the brief upstream.
- **`spec-reviewer` agent renamed to `brief-reviewer`** with a new 5th dimension
(Research Plan validity). Old spec-reviewer file is deleted.
### Added
- **`/ultrabrief-local` command** — interactive interview (3-8 questions with
adaptive depth) that produces a task brief with explicit research plan.
Features: project directory creation, research topic identification with
copy-paste-ready `/ultraresearch-local` commands, optional auto-orchestration
(Claude runs research + plan in foreground), and stats tracking.
- **`templates/ultrabrief-template.md`** — canonical task brief format with
`## Intent`, `## Goal`, `## Non-Goals`, `## Constraints / Preferences / NFRs`,
`## Success Criteria`, `## Research Plan` (N topics with research_question,
scope, confidence, cost), and `## Open Questions / Assumptions`.
- **`brief-reviewer` agent** — renamed from spec-reviewer with a new
5th dimension: Research Plan validity (each topic has a valid
research question ending in `?`, has `Required for plan steps:` and
`Confidence needed:`, and research files exist when `auto_research: true`).
- **`--project <dir>` flag** on `/ultraresearch-local`, `/ultraplan-local`,
and `/ultraexecute-local`. Single directory holds the full pipeline's
artifacts. `/ultraresearch-local --project` auto-increments
`{dir}/research/NN-slug.md`.
- **Two-kinds-of-briefs terminology** documented across README and CLAUDE.md:
"task brief" (from `/ultrabrief-local`) vs "research brief" (from
`/ultraresearch-local`). Prefix used consistently in agent prompts and docs.
- **MIGRATION.md** — step-by-step guide for upgrading v1 projects to v2.
### Changed
- **`planning-orchestrator`** now accepts `Brief file:` input instead of
`Spec file:`. Intent→Context mapping: brief's `## Intent` + `## Goal` feed
the plan's Context section directly (structured, no inference needed).
Phase 1b now uses `brief-reviewer` instead of `spec-reviewer`. With
`Project dir:` in input, writes plan to `{dir}/plan.md`.
- **`/ultraresearch-local`** supports `--project <dir>` with auto-indexed
output path (`{dir}/research/NN-slug.md`, where NN is the next available
two-digit index).
- **`/ultraexecute-local`** supports `--project <dir>`. Reads `{dir}/plan.md`,
writes progress to `{dir}/progress.json`.
- **plugin.json** description rewritten to reflect four-command pipeline.
### Removed
- `/ultraplan-local --spec <path>` flag. Spec files are not a valid input for
v2.0+. Convert to brief via `/ultrabrief-local` or manual conversion (see
MIGRATION.md).
- Interview Phase in `/ultraplan-local` (was Phase 2). Use `/ultrabrief-local`
to conduct the interview upstream.
- `agents/spec-reviewer.md` file. Replaced by `agents/brief-reviewer.md`.
### Rationale
The v1.x interview inside `/ultraplan-local` conflated two concerns: capturing
intent and producing an executable plan. Briefs and plans have different
lifecycles — a brief should be reviewable and editable before any research or
planning starts, because every downstream decision traces back to it. Extracting
the brief into its own command makes the pipeline more honest: the brief is the
source of truth for *what we want*, research briefs are sources of truth for
*what we learned*, and the plan is the contract for *how we'll do it*. Separating
these makes each artifact reviewable on its own terms and enables deterministic
re-planning from the same brief when research reveals new constraints.
The explicit `## Research Plan` section in briefs closes a common gap: plans
were implicitly assuming knowledge that neither the user nor Claude had verified.
Research topics are now declared upfront, scoped, and traceable back to plan
decisions.
## [1.8.0] - 2026-04-17
### Opus 4.7 prompt literalism — closing the schema-drift gap

70
plugins/ultraplan-local/CLAUDE.md
View file

@ -1,51 +1,63 @@
# ultraplan-local
Deep implementation planning and research with interview, specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan.
Deep implementation planning and research with an explicit brief step, specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan.
**Design principle: Context Engineering** — build the right context by orchestrating specialized agents. Each step in the pipeline (research -> plan -> execute) produces a structured artifact that the next step consumes.
**Design principle: Context Engineering** — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes.
## Commands
| Command | Description | Model |
|---------|-------------|-------|
| `/ultraresearch-local` | Research — deep local + external research, produces structured brief | opus |
| `/ultraplan-local` | Plan — interview, explore, plan, review | opus |
| `/ultrabrief-local` | Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline | opus |
| `/ultraresearch-local` | Research — deep local + external research, produces structured research brief | opus |
| `/ultraplan-local` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project` | opus |
| `/ultraexecute-local` | Execute — disciplined plan/session-spec executor with failure recovery | opus |
### /ultrabrief-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Full interview (5-8 questions) → brief.md with research plan |
| `--quick` | Short interview (3-4 questions) → brief.md with research plan |
Always interactive. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).
### /ultraresearch-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Interview + background research (local + external) + synthesis + brief |
| `--project <dir>` | Write brief to `{dir}/research/{NN}-{slug}.md` (auto-incremented) |
| `--quick` | Interview (short) + inline research (no agent swarm) |
| `--local` | Only codebase analysis agents (skip external + Gemini) |
| `--external` | Only external research agents (skip codebase analysis) |
| `--fg` | All phases in foreground (blocking) |
Flags can be combined: `--local --fg`, `--external --quick`.
Flags combine: `--project <dir> --local --fg`, `--external --quick`.
### /ultraplan-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Interview + background planning (non-blocking) |
| `--spec <path>` | Skip interview, use provided spec |
| `--research <brief> [brief2]` | Enrich planning with pre-built research brief(s) |
| `--project <dir>` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/ultraplan-{date}-{slug}.md` |
| `--research <brief> [brief2]` | Enrich with extra research briefs beyond what is in `{project_dir}/research/` |
| `--fg` | All phases in foreground (blocking) |
| `--quick` | Interview + plan directly (no agent swarm) |
| `--quick` | Plan directly (no agent swarm) |
| `--export <pr\|issue\|markdown\|headless> <plan>` | Generate shareable output from existing plan |
| `--decompose <plan>` | Split plan into self-contained headless sessions |
`--research` can combine with `--spec`, `--fg`, and `--quick`.
**Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/ultraplan-local`. The `--spec` flag has been removed — use `/ultrabrief-local` to produce a brief instead.
### /ultraexecute-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Execute plan — auto-detects Execution Strategy for multi-session |
| `--project <dir>` | Read `{dir}/plan.md`, write `{dir}/progress.json` |
| `--resume` | Resume from last progress checkpoint |
| `--dry-run` | Validate plan structure without executing |
| `--validate` | Schema-only check — parse steps + manifests, report `READY \| FAIL`, no execution (v1.8) |
| `--validate` | Schema-only check — parse steps + manifests, report `READY \| FAIL`, no execution |
| `--step N` | Execute only step N |
| `--fg` | Force foreground — run all steps sequentially, ignore Execution Strategy |
| `--session N` | Execute only session N from plan's Execution Strategy |
@ -54,7 +66,7 @@ Flags can be combined: `--local --fg`, `--external --quick`.
| Agent | Model | Role |
|-------|-------|------|
| planning-orchestrator | opus | Runs full planning pipeline as background task |
| planning-orchestrator | opus | Runs full planning pipeline as background task (brief-driven) |
| research-orchestrator | opus | Runs full research pipeline as background task |
| architecture-mapper | sonnet | Codebase structure, tech stack, patterns |
| dependency-tracer | sonnet | Import chains, data flow, side effects |
@ -64,7 +76,7 @@ Flags can be combined: `--local --fg`, `--external --quick`.
| git-historian | sonnet | Recent changes, ownership, hot files |
| research-scout | sonnet | External docs for unfamiliar tech (conditional, planning only) |
| convention-scanner | sonnet | Coding conventions: naming, style, error handling, test patterns |
| spec-reviewer | sonnet | Spec quality check before exploration |
| brief-reviewer | sonnet | Task brief quality (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity) |
| plan-critic | sonnet | Adversarial plan review (9 dimensions) |
| scope-guardian | sonnet | Scope alignment (creep + gaps) |
| session-decomposer | sonnet | Splits plans into headless sessions with dependency graph |
@ -76,26 +88,46 @@ Flags can be combined: `--local --fg`, `--external --quick`.
## Architecture
**Research:** 8-phase workflow: Parse mode -> Interview -> Background transition -> Parallel research (5 local + 4 external + 1 bridge) -> Follow-ups -> Triangulation -> Synthesis + brief -> Stats.
**Brief:** 7-phase workflow: Parse mode → Create project dir → Interactive interview (adaptive depth) → Identify research topics → Write `brief.md` → Manual/auto opt-in → Stats. Always interactive. Auto mode blocks foreground until plan is ready.
**Plan:** 12-phase workflow: Parse mode -> Interview -> Background transition -> Codebase sizing -> Spec review -> Parallel exploration (6-8 agents) -> Deep-dives -> Synthesis -> Planning -> Adversarial review -> Present/refine -> Handoff.
**Research:** 8-phase workflow: Parse mode → Interview → Background transition → Parallel research (5 local + 4 external + 1 bridge) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`.
**Decompose:** Parse plan -> Analyze step dependencies -> Group into sessions -> Identify parallel waves -> Generate session specs + dependency graph + launch script.
**Plan:** 12-phase workflow: Parse mode (validate brief input) → Background transition → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents) → Deep-dives → Synthesis → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md`.
**Execute:** Parse plan -> Security scan (Phase 2.4) -> Detect Execution Strategy -> Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) -> Verification -> Report.
**Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script.
**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Report. With `--project`, reads `{dir}/plan.md` and writes `{dir}/progress.json`.
**Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.
**Pipeline:** Research briefs feed into planning via `--research`. The planning orchestrator uses brief context to enrich exploration and skip redundant research.
**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project <dir>` fills in `{dir}/research/`. `/ultraplan-local --project <dir>` reads brief + research to produce `{dir}/plan.md`. `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
## State
All artifacts in one project directory (default):
- Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/`
- `brief.md` (task brief from `/ultrabrief-local`)
- `research/{NN}-{slug}.md` (research briefs from `/ultraresearch-local --project`)
- `plan.md` (from `/ultraplan-local --project`)
- `sessions/session-*.md` (from `--decompose`)
- `progress.json` (from `/ultraexecute-local --project`)
Legacy paths (still work without `--project`):
- Research briefs: `.claude/research/ultraresearch-{date}-{slug}.md`
- Specs: `.claude/ultraplan-spec-{date}-{slug}.md`
- Plans: `.claude/plans/ultraplan-{date}-{slug}.md`
- Sessions: `.claude/ultraplan-sessions/{slug}/session-*.md`
- Launch scripts: `.claude/ultraplan-sessions/{slug}/launch.sh`
- Progress: `{plan-dir}/.ultraexecute-progress-{slug}.json`
Stats:
- Brief stats: `${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl`
- Plan stats: `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl`
- Exec stats: `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl`
- Research stats: `${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl`
## Terminology
- **Task brief** — produced by `/ultrabrief-local`. Declares intent, goal, and research plan. Drives planning.
- **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds planning.
A project typically has 1 task brief and 0–N research briefs.

284
plugins/ultraplan-local/MIGRATION.md Normal file
View file

@ -0,0 +1,284 @@
# 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).

382
plugins/ultraplan-local/README.md
View file

@ -1,34 +1,44 @@
# ultraplan-local — Plan, Research, Execute
# ultraplan-local — Brief, Research, Plan, Execute
![Version](https://img.shields.io/badge/version-1.8.0-blue)
![Version](https://img.shields.io/badge/version-2.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple)
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, and autonomous execution. Three commands, one pipeline:
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, and autonomous execution. Four commands, one pipeline:
| Command | What it does |
|---------|-------------|
| **`/ultrabrief-local`** | Brief — interactive interview produces a task brief with explicit research plan |
| **`/ultraresearch-local`** | Research — deep local + external research with triangulation |
| **`/ultraplan-local`** | Plan — interview, agent swarm exploration, adversarial review |
| **`/ultraplan-local`** | Plan — agent swarm exploration, Opus planning, adversarial review |
| **`/ultraexecute-local`** | Execute — disciplined step-by-step implementation with failure recovery |
Research first, then plan, then execute. Or skip research and plan directly. Or plan and execute in one flow. The plan is the contract between planning and execution. The research brief is the contract between research and planning.
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`.
### Division of labor
| Command | Responsibility | Output |
|---|---|---|
| `/ultraresearch-local` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | Research brief (markdown) |
| `/ultrabrief-local` | **Capture intent** — intent, goal, non-goals, success criteria, and a research plan with explicit topics. Interactive only. | `brief.md` (task brief) |
| `/ultraresearch-local` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) |
| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. | `plan.md` with Manifest blocks + `plan_version: 1.7` |
| `/ultraexecute-local` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | Progress file + structured report + manifest-audit status |
| `/ultraexecute-local` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status |
**Principle:** Execute trusts the plan. If execute has to guess or interpret, the plan is weak and must be revised upstream — not patched downstream.
**Principle:** Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream.
### Self-verifying plan chain (v1.7)
### Two kinds of briefs
Every step in a v1.7 plan ends with a YAML `manifest:` block declaring `expected_paths`, `commit_message_pattern`, `bash_syntax_check`, `forbidden_paths`, `must_contain`. This makes the plan the **objective completion predicate**: a step may not be marked passed if its manifest does not verify, regardless of the Verify command's exit code (Hard Rule 17).
Terminology matters:
- **Task brief** — produced by `/ultrabrief-local`. Captures *what we want and why*. Drives planning.
- **Research brief** — produced by `/ultraresearch-local`. Captures *what we learned about a topic*. Feeds planning.
After all steps complete, `ultraexecute-local` runs **Phase 7.5 — Manifest audit (independent)**: re-verifies every expected path from git log + filesystem, ignoring the agent's own bookkeeping. Drift → status `partial`, **Phase 7.6** auto-dispatches a bounded recovery session with only the missing steps (`recovery_depth ≤ 2`). Step 0 pre-flight (`git push --dry-run`) runs inside every session sandbox before any real work — exit 77 sentinel catches sandbox push-denial before the agent wastes the whole budget.
A project typically has one task brief and zero-to-N research briefs.
### Self-verifying plan chain
Every step in the plan ends with a YAML `manifest:` block declaring `expected_paths`, `commit_message_pattern`, `bash_syntax_check`, `forbidden_paths`, `must_contain`. This makes the plan the **objective completion predicate**: a step may not be marked passed if its manifest does not verify, regardless of the Verify command's exit code (Hard Rule 17).
After all steps complete, `/ultraexecute-local` runs **Phase 7.5 — Manifest audit (independent)**: re-verifies every expected path from git log + filesystem, ignoring the agent's own bookkeeping. Drift → status `partial`, **Phase 7.6** auto-dispatches a bounded recovery session with only the missing steps (`recovery_depth ≤ 2`). Step 0 pre-flight (`git push --dry-run`) runs inside every session sandbox before any real work — exit 77 sentinel catches sandbox push-denial before the agent wastes the whole budget.
No cloud dependency. No GitHub requirement. Works on **Mac, Linux, and Windows**.
@ -38,19 +48,22 @@ No cloud dependency. No GitHub requirement. Works on **Mac, Linux, and Windows**
# Install the marketplace, then browse and enable plugins with /plugin
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
# Research a question
/ultraresearch-local Should we migrate from Express to Fastify?
# Capture intent (interactive)
/ultrabrief-local Add user authentication with JWT tokens
# → .claude/projects/2026-04-18-jwt-auth/brief.md
# Plan with research context
/ultraplan-local --research .claude/research/ultraresearch-2026-04-08-express-fastify.md Migrate API to Fastify
# Research each topic identified in the brief (manual default)
/ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external "What are current JWT best practices?"
# Plan without prior research
/ultraplan-local Add user authentication with JWT tokens
# Plan from brief + research
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth
# Execute
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-jwt-auth.md
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth
```
Or opt into auto-mode in `/ultrabrief-local` — it will launch research and planning for you in foreground, and return when `plan.md` is ready.
## When to use it
**Use it when:**
@ -59,7 +72,7 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar
- The implementation has non-obvious dependencies, ordering constraints, or risks
- You want a reviewable plan before committing to an approach
- You need autonomous headless execution without human intervention
- You need to research a technology, library, or approach before deciding (use `/ultraresearch-local`)
- You need to research a technology, library, or approach before deciding
**Don't use it when:**
- The task is a single-file change where the fix is obvious
@ -69,34 +82,75 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar
---
## `/ultraresearch-local` — Research
## `/ultrabrief-local` — Brief
Deep, multi-phase research that combines local codebase analysis with external knowledge. Uses specialized agent swarms to investigate multiple dimensions in parallel, then triangulates findings to produce insights that neither local nor external research could provide alone.
Interactive requirements-gathering command. Runs a focused interview (3-8 questions depending on mode and adaptive depth) and produces a **task brief** with an explicit research plan. Optionally orchestrates the rest of the pipeline.
### How it works
1. **Interview** -- Short requirements gathering (2-4 questions): decision context, dimensions, prior knowledge, constraints
2. **Research dimensions** -- Identify 3-8 facets of the question to investigate in parallel
3. **Local agents** -- 5 Sonnet agents analyze the codebase in parallel (architecture, dependencies, existing code, git history, conventions)
4. **External agents** -- 4 Sonnet agents search documentation, community experience, security data, and counter-evidence in parallel
5. **Gemini bridge** -- Independent second opinion via Gemini Deep Research (optional)
6. **Follow-ups** -- Targeted investigation of knowledge gaps (max 2)
7. **Triangulate** -- Cross-validate local vs. external findings, rate confidence per dimension, flag contradictions
8. **Synthesize** -- Write structured research brief with executive summary, per-dimension findings, and sources
1. **Parse mode** — `default` (5-8 questions) or `--quick` (3-4 questions)
2. **Create project directory** — `.claude/projects/{YYYY-MM-DD}-{slug}/` with `research/` subdirectory
3. **Interview** — one question at a time via `AskUserQuestion`, starting with Intent → Goal → Success Criteria, then optional Non-Goals, Constraints, Preferences, NFRs, Prior Attempts
4. **Identify research topics** — probe for unfamiliar tech, version upgrades, security decisions, architectural choices
5. **Write brief** — `{project_dir}/brief.md` with all sections and a copy-paste-ready research plan
6. **Auto-orchestration opt-in** — user chooses manual (default) or auto (Claude-managed research + plan in foreground)
7. **Stats tracking** — append to `ultrabrief-stats.jsonl`
Output: `.claude/research/ultraresearch-{date}-{slug}.md`
Output: `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`
### Modes
| Mode | Usage | Behavior |
|------|-------|----------|
| **Default** | `/ultrabrief-local <task>` | Full interview (5-8 questions) |
| **Quick** | `/ultrabrief-local --quick <task>` | Short interview (3-4 questions) |
`/ultrabrief-local` is **always interactive**. There is no foreground/background mode — the interview requires user input.
### What the brief contains
- **Intent** — why this matters, motivation, user need (load-bearing)
- **Goal** — concrete end state in 1-3 sentences
- **Non-Goals** — explicitly out of scope
- **Constraints / Preferences / NFRs** — technical, time, resource limits
- **Success Criteria** — 2-4 falsifiable commands/observations
- **Research Plan** — N topics, each with research question, scope (local/external/both), confidence needed, cost estimate, and a ready-to-run `/ultraresearch-local` command
- **Open Questions / Assumptions** — from "I don't know" answers and implicit gaps
- **Prior Attempts** — what worked/failed before
---
## `/ultraresearch-local` — Research
Deep, multi-phase research that combines local codebase analysis with external knowledge. Uses specialized agent swarms to investigate multiple dimensions in parallel, then triangulates findings.
### How it works
1. **Interview** — short requirements gathering (skipped when `--project` reuses brief context)
2. **Research dimensions** — identify 3-8 facets to investigate in parallel
3. **Local agents** — 5 Sonnet agents analyze the codebase in parallel (architecture, dependencies, existing code, git history, conventions)
4. **External agents** — 4 Sonnet agents search documentation, community experience, security data, and counter-evidence in parallel
5. **Gemini bridge** — independent second opinion via Gemini Deep Research (optional)
6. **Follow-ups** — targeted investigation of knowledge gaps (max 2)
7. **Triangulate** — cross-validate local vs. external findings, rate confidence per dimension, flag contradictions
8. **Synthesize** — write structured research brief
Output:
- With `--project <dir>`: `{dir}/research/{NN}-{slug}.md` (auto-incremented index)
- Without: `.claude/research/ultraresearch-{date}-{slug}.md`
### Modes
| Mode | Usage | Behavior |
|------|-------|----------|
| **Default** | `/ultraresearch-local <question>` | Interview + background research (local + external + Gemini) |
| **Project** | `/ultraresearch-local --project <dir> <question>` | Write brief into `{dir}/research/NN-slug.md` |
| **Quick** | `/ultraresearch-local --quick <question>` | Interview (short) + inline research, no agent swarm |
| **Local** | `/ultraresearch-local --local <question>` | Only codebase analysis agents (skip external + Gemini) |
| **External** | `/ultraresearch-local --external <question>` | Only external research agents (skip codebase analysis) |
| **Foreground** | `/ultraresearch-local --fg <question>` | All phases in foreground (blocking) |
Flags combine: `--local --fg`, `--external --quick`.
Flags combine: `--project <dir> --external --fg`.
### Research agents
@ -113,84 +167,62 @@ Flags combine: `--local --fg`, `--external --quick`.
| contrarian-researcher | Counter-evidence, overlooked alternatives | External |
| gemini-bridge | Independent second opinion via Gemini Deep Research | External (optional) |
### What the brief contains
- **Executive Summary** -- 3 sentences: answer, confidence, key caveat
- **Dimensions** -- Each with local findings, external findings, contradictions, and confidence rating (high/medium/low/contradictory)
- **Local Context** -- Architecture, dependencies, conventions, git history
- **External Knowledge** -- Best practices, alternatives, security, known issues
- **Gemini Second Opinion** -- Independent research for triangulation (when available)
- **Synthesis** -- Cross-cutting insights from triangulation (not a summary -- new insight)
- **Open Questions** -- What remains unresolved and why
- **Recommendation** -- Concrete recommendation with rationale (if decision-relevant)
- **Sources** -- Every claim traced to URL or codebase path, with quality rating
### Pipeline integration
Research briefs feed directly into planning:
```
/ultraresearch-local Should we use Redis for caching?
# → .claude/research/ultraresearch-2026-04-08-redis-caching.md
/ultraplan-local --research .claude/research/ultraresearch-2026-04-08-redis-caching.md Add Redis caching layer
# Planning skips redundant research, interview focuses on decisions not facts
```
---
## `/ultraplan-local` — Planning
Runs a structured planning workflow that produces an implementation plan detailed enough for autonomous execution.
Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/ultraplan-local` — use `/ultrabrief-local` first.
### How it works
1. **Interview** -- Iterative requirements gathering (goal, constraints, preferences, NFRs)
2. **Explore** -- 6-8 specialized Sonnet agents analyze your codebase in parallel
3. **Research** -- External documentation for unfamiliar technologies (conditional), or injected from a pre-built research brief via `--research`
4. **Synthesize** -- Findings merged into a unified codebase understanding
5. **Plan** -- Opus creates a comprehensive implementation plan with failure recovery
6. **Critique** -- Adversarial review by plan-critic (9 dimensions) and scope-guardian
7. **Refine** -- You review, ask questions, request changes
8. **Handoff** -- Execute now, save for later, or export
1. **Parse mode** — validate that a brief is provided
2. **Spec review** → **brief review** — `brief-reviewer` validates completeness, consistency, testability, scope clarity, and research plan validity
3. **Explore** — 6-8 specialized Sonnet agents analyze your codebase in parallel
4. **Research** — optional research briefs enrich planning (`--research`, or auto-discovered in `{project_dir}/research/`)
5. **Synthesize** — findings merged into a unified codebase understanding
6. **Plan** — Opus creates a comprehensive implementation plan with per-step YAML manifests
7. **Critique** — adversarial review by `plan-critic` (9 dimensions) and `scope-guardian`
8. **Handoff** — plan written; execute now, save for later, or export
Output: `.claude/plans/ultraplan-{date}-{slug}.md`
Output:
- With `--project <dir>`: `{dir}/plan.md`
- With `--brief <path>`: `.claude/plans/ultraplan-{date}-{slug}.md`
### Modes
| Mode | Usage | Behavior |
|------|-------|----------|
| **Default** | `/ultraplan-local Add auth` | Interview + background planning |
| **Spec-driven** | `/ultraplan-local --spec spec.md` | Skip interview, plan from spec file |
| **Research-enriched** | `/ultraplan-local --research brief.md Add auth` | Enrich planning with pre-built research brief(s) |
| **Foreground** | `/ultraplan-local --fg Add auth` | All phases in foreground (blocking) |
| **Quick** | `/ultraplan-local --quick Add auth` | No agent swarm, lightweight scan only |
| **Project** | `/ultraplan-local --project <dir>` | Read `{dir}/brief.md` + auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
| **Brief** | `/ultraplan-local --brief <path>` | Plan from a specific brief file |
| **Research-enriched** | `/ultraplan-local --project <dir> --research <brief>` | Add extra research briefs beyond what is in `research/` |
| **Foreground** | `/ultraplan-local --project <dir> --fg` | All phases in foreground (blocking) |
| **Quick** | `/ultraplan-local --project <dir> --quick` | No agent swarm, lightweight scan only |
| **Decompose** | `/ultraplan-local --decompose plan.md` | Split plan into headless session specs |
| **Export** | `/ultraplan-local --export pr plan.md` | PR description, issue comment, or clean markdown |
`--research` can combine with `--spec`, `--fg`, and `--quick`. Accepts up to 3 brief paths.
`--brief` or `--project` is **required**. `/ultraplan-local` with no brief exits with an error and a pointer to `/ultrabrief-local`.
### What the plan contains
Every plan includes:
- **Context** -- Why this change is needed
- **Architecture Diagram** -- Mermaid C4-style component diagram
- **Codebase Analysis** -- Tech stack, patterns, relevant files, reusable code
- **Research Sources** -- External documentation and research brief findings (when applicable)
- **Implementation Plan** -- Ordered steps with file paths, changes, failure recovery, and git checkpoints
- **Alternatives Considered** -- Other approaches with pros/cons
- **Test Strategy** -- From test-strategist findings
- **Risks and Mitigations** -- From risk-assessor findings
- **Verification** -- Testable end-to-end criteria
- **Execution Strategy** -- Session grouping and parallel waves (plans with > 5 steps)
- **Plan Quality Score** -- Quantitative grade (A-D) across 6 weighted dimensions
- **Context** — derived from brief `## Intent` + `## Goal`
- **Architecture Diagram** — Mermaid C4-style component diagram
- **Codebase Analysis** — tech stack, patterns, relevant files, reusable code
- **Research Sources** — findings from research briefs (when present)
- **Implementation Plan** — ordered steps with file paths, changes, failure recovery, and git checkpoints
- **Per-step Manifest** — YAML block with `expected_paths`, `commit_message_pattern`, `bash_syntax_check`, `forbidden_paths`, `must_contain`
- **Alternatives Considered** — other approaches with pros/cons
- **Test Strategy** — from test-strategist findings
- **Risks and Mitigations** — from risk-assessor findings
- **Verification** — testable end-to-end criteria
- **Execution Strategy** — session grouping and parallel waves (plans with > 5 steps)
- **Plan Quality Score** — quantitative grade (A-D) across 6 weighted dimensions
Every implementation step includes:
- **On failure:** -- what to do when verification fails (revert / retry / skip / escalate)
- **Checkpoint:** -- git commit after success
These fields are what makes `/ultraexecute-local` possible -- the plan carries all decisions needed for autonomous execution.
- **On failure:** — what to do when verification fails (revert / retry / skip / escalate)
- **Checkpoint:** — git commit after success
- **Manifest:** — the objective completion predicate (Hard Rule 17)
### Exploration agents
@ -209,34 +241,36 @@ These fields are what makes `/ultraexecute-local` possible -- the plan carries a
| Agent | Role |
|-------|------|
| spec-reviewer | Checks spec quality before exploration begins |
| plan-critic | Adversarial review: 9 dimensions, quantitative scoring, no-placeholder enforcement |
| scope-guardian | Verifies plan matches spec: finds scope creep and scope gaps |
| brief-reviewer | Checks task brief quality (completeness, consistency, testability, scope clarity, research plan validity) before exploration |
| plan-critic | Adversarial review: 9 dimensions, quantitative scoring, no-placeholder enforcement, manifest audit as hard gate |
| scope-guardian | Verifies plan matches brief: finds scope creep and scope gaps |
---
## `/ultraexecute-local` — Execution
Reads a plan from `/ultraplan-local` and implements it with strict discipline. No guessing, no improvising -- follows the plan exactly.
Reads a plan from `/ultraplan-local` and implements it with strict discipline. No guessing, no improvising — follows the plan exactly.
### How it works per step
1. **Implement** -- Applies the Changes field exactly as written
2. **Verify** -- Runs the Verify command (exit code is truth)
3. **On failure** -- Follows the plan's recovery clause (revert / retry / skip / escalate)
4. **Checkpoint** -- Commits changes per the plan's Checkpoint field
1. **Implement** — applies the Changes field exactly as written
2. **Verify** — runs the Verify command (exit code is truth)
3. **Manifest audit** — validates expected paths, forbidden paths, commit pattern
4. **On failure** — follows the plan's recovery clause (revert / retry / skip / escalate)
5. **Checkpoint** — commits changes per the plan's Checkpoint field
### Modes
| Mode | Usage | Behavior |
|------|-------|----------|
| **Default** | `/ultraexecute-local plan.md` | Auto-detects Execution Strategy, parallel if available |
| **Resume** | `/ultraexecute-local plan.md --resume` | Resume from last progress checkpoint |
| **Dry run** | `/ultraexecute-local plan.md --dry-run` | Validate plan structure + preview sessions and billing |
| **Validate** | `/ultraexecute-local plan.md --validate` | Schema-only check — parse steps + manifests, report `READY \| FAIL`, no execution |
| **Single step** | `/ultraexecute-local plan.md --step 3` | Execute only step 3 |
| **Foreground** | `/ultraexecute-local plan.md --fg` | Force sequential, ignore Execution Strategy |
| **Single session** | `/ultraexecute-local plan.md --session 2` | Execute only session 2 from Execution Strategy |
| **Project** | `/ultraexecute-local --project <dir>` | Read `{dir}/plan.md`, write `{dir}/progress.json` |
| **Plan path** | `/ultraexecute-local plan.md` | Execute a specific plan file |
| **Resume** | `/ultraexecute-local --project <dir> --resume` | Resume from last progress checkpoint |
| **Dry run** | `/ultraexecute-local --project <dir> --dry-run` | Validate plan structure + preview sessions and billing |
| **Validate** | `/ultraexecute-local --project <dir> --validate` | Schema-only check — parse steps + manifests, report `READY \| FAIL`, no execution |
| **Single step** | `/ultraexecute-local --project <dir> --step 3` | Execute only step 3 |
| **Foreground** | `/ultraexecute-local --project <dir> --fg` | Force sequential, ignore Execution Strategy |
| **Single session** | `/ultraexecute-local --project <dir> --session 2` | Execute only session 2 from Execution Strategy |
### Session-aware parallel execution (worktree-isolated)
@ -263,22 +297,22 @@ Use `--fg` to force sequential execution even when a plan has an Execution Strat
### Billing safety
Before launching parallel `claude -p` sessions, `/ultraexecute-local` checks whether `ANTHROPIC_API_KEY` is set in your environment. If it is, parallel sessions will bill your **API account** (pay-per-token), not your Claude subscription (Max/Pro). This can be expensive -- parallel Opus sessions can cost $50-100+ per run.
Before launching parallel `claude -p` sessions, `/ultraexecute-local` checks whether `ANTHROPIC_API_KEY` is set in your environment. If it is, parallel sessions will bill your **API account** (pay-per-token), not your Claude subscription (Max/Pro). This can be expensive — parallel Opus sessions can cost $50-100+ per run.
When an API key is detected, you are asked how to proceed:
- **Use --fg instead** (recommended) -- run sequentially in the current session using your subscription
- **Continue with API billing** -- launch parallel sessions on your API account
- **Stop** -- cancel and unset the API key first
- **Use --fg instead** (recommended) — run sequentially in the current session using your subscription
- **Continue with API billing** — launch parallel sessions on your API account
- **Stop** — cancel and unset the API key first
If no API key is set, parallel sessions use your subscription and proceed without asking.
### Failure recovery
- **3-attempt retry cap** -- retries twice, then stops (never loops forever)
- **On failure: revert** -- undo changes, stop
- **On failure: retry** -- try alternative approach, then revert if still failing
- **On failure: skip** -- non-critical step, continue
- **On failure: escalate** -- stop everything, needs human judgment
- **3-attempt retry cap** — retries twice, then stops (never loops forever)
- **On failure: revert** — undo changes, stop
- **On failure: retry** — try alternative approach, then revert if still failing
- **On failure: skip** — non-critical step, continue
- **On failure: escalate** — stop everything, needs human judgment
### Security hardening
@ -292,92 +326,109 @@ The executor implements defense-in-depth security across four layers:
### Headless execution
`/ultraexecute-local` is designed for `claude -p` headless sessions:
- **No questions asked** -- all recovery decisions come from the plan
- **Progress file** -- crash recovery via `.ultraexecute-progress-{slug}.json`
- **Scope fence enforcement** -- never touches files outside the session's scope
- **JSON summary** -- machine-parseable `ultraexecute_summary` block for log parsing
- **No questions asked** — all recovery decisions come from the plan
- **Progress file** — crash recovery via `{project_dir}/progress.json` (or `.ultraexecute-progress-{slug}.json` for legacy plans)
- **Scope fence enforcement** — never touches files outside the session's scope
- **JSON summary** — machine-parseable `ultraexecute_summary` block for log parsing
---
## The full pipeline
```
/ultraresearch-local /ultraplan-local /ultraexecute-local
┌───────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
│ Interview │ │ Interview │ │ Parse plan │
│ ↓ │ │ ↓ │ │ ↓ │
│ 5 local agents │ │ 6-8 exploration │ │ Detect sessions │
│ 4 external agents │ brief │ agents (parallel) │ plan │ ↓ │
│ + Gemini bridge │ ─────→ │ ↓ │ ─────→ │ Execute steps │
│ ↓ │ │ Opus planning │ │ (verify + checkpoint │
│ Triangulation │ │ ↓ │ │ per step) │
│ ↓ │ │ Adversarial review │ │ ↓ │
│ Research brief │ │ ↓ │ │ Master verification │
└───────────────────┘ │ Plan file │ │ ↓ │
└──────────────────────┘ │ Done │
└──────────────────────┘
/ultrabrief-local /ultraresearch-local /ultraplan-local /ultraexecute-local
┌──────────────┐ ┌───────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ Interview │ │ 5 local agents │ │ brief-reviewer │ │ Parse plan │
│ ↓ │ │ 4 external agents │ │ ↓ │ │ ↓ │
│ Intent/Goal │ │ + Gemini bridge │ │ 6-8 exploration │ │ Detect sessions │
│ ↓ │ │ ↓ │ │ agents (parallel) │ │ ↓ │
│ Research │ │ Triangulation │ │ ↓ │ │ Execute steps │
│ topics │ │ ↓ │ │ Opus planning │ │ (verify + manifest │
│ ↓ │ → brief → (optional) ─→ → │ ↓ │→ │ + checkpoint) │
│ brief.md │ │ research/*.md │ │ plan-critic + │ │ ↓ │
└──────────────┘ └───────────────────┘ │ scope-guardian │ │ Phase 7.5 manifest │
│ ↓ │ │ audit + 7.6 recovery│
│ plan.md │ │ ↓ │
└─────────────────────┘ │ progress.json + done│
└─────────────────────┘
```
All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`.
### Example workflows
**Research-first planning:**
**Standard pipeline (manual control):**
```bash
/ultraresearch-local Should we use Redis or Memcached for session caching?
# → .claude/research/ultraresearch-2026-04-08-redis-memcached.md
/ultrabrief-local Add session caching with Redis
# → .claude/projects/2026-04-18-redis-session-caching/brief.md
# Interview identifies 2 research topics.
/ultraplan-local --research .claude/research/ultraresearch-2026-04-08-redis-memcached.md Add session caching with Redis
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-session-caching.md
/ultraresearch-local --project .claude/projects/2026-04-18-redis-session-caching --external "What are Redis session-caching best practices?"
/ultraresearch-local --project .claude/projects/2026-04-18-redis-session-caching --local "How is caching currently handled in the codebase?"
# → .claude/projects/2026-04-18-redis-session-caching/research/01-*.md, 02-*.md
/ultraplan-local --project .claude/projects/2026-04-18-redis-session-caching
# → .claude/projects/2026-04-18-redis-session-caching/plan.md
/ultraexecute-local --project .claude/projects/2026-04-18-redis-session-caching
# → progress.json + code changes
```
**Auto-mode (Claude manages the pipeline):**
```bash
/ultrabrief-local Add session caching with Redis
# Interview identifies topics. Choose "Auto (managed by Claude Code)" when asked.
# Claude runs research in parallel, then planning in foreground.
# Returns when plan.md is ready.
/ultraexecute-local --project .claude/projects/2026-04-18-redis-session-caching
```
**Standalone research (no planning):**
```bash
/ultraresearch-local What are the security implications of using JWT for session management?
# Read the brief, share with team, use for decision-making
```
**Interactive planning + manual execution:**
```bash
/ultraplan-local Add WebSocket notifications
# Review the plan, then:
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-websocket.md
```
**Spec-driven headless (CI/automation):**
```bash
# Plan in background from pre-written spec
/ultraplan-local --spec .claude/specs/websocket-spec.md
# Execute with parallel sessions
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-websocket.md
# Read the brief, share with team, use for decision-making.
```
**Quick plan for small tasks:**
```bash
/ultraplan-local --quick Fix the login redirect bug
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-login-fix.md
/ultrabrief-local --quick Fix the login redirect bug
/ultraplan-local --project .claude/projects/2026-04-18-login-redirect-fix --quick
/ultraexecute-local --project .claude/projects/2026-04-18-login-redirect-fix
```
**Dry run to validate before executing:**
**Dry run + validate before executing:**
```bash
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-auth.md --dry-run
# Looks good:
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-auth.md
/ultraexecute-local --project <dir> --validate # schema check, no execution
/ultraexecute-local --project <dir> --dry-run # preview sessions and billing
/ultraexecute-local --project <dir> # execute
```
---
## Upgrading from v1.x
v2.0.0 is a **breaking release**. See [MIGRATION.md](MIGRATION.md) for a step-by-step guide. Short version:
- `/ultraplan-local` no longer runs an interview. Use `/ultrabrief-local` first.
- `/ultraplan-local --spec <path>` is **removed**. Use `--brief <path>` or `--project <dir>` instead.
- Old specs do not work as-is. Convert a spec to a brief by filling in `## Intent` and `## Research Plan` sections (MIGRATION.md has a template).
- All artifacts now live in `.claude/projects/{date}-{slug}/` by default. Legacy paths (`.claude/research/`, `.claude/plans/`) still work without `--project`.
## How it compares
| Feature | Ultraplan (cloud) | Copilot Workspace | Cursor | ultraplan-local |
|---------|-------------------|-------------------|--------|-----------------|
| Planning model | Opus | GPT-4 | Unknown | Opus |
| Requirements gathering | Task only | Issue-driven | Prompt | Interview + spec |
| Requirements gathering | Task only | Issue-driven | Prompt | **Dedicated brief command with explicit research plan** |
| Codebase exploration | Cloud | Cloud | Cloud | 6-8 specialized agents |
| Deep research pipeline | No | No | No | **10 agents + Gemini + triangulation** |
| Adversarial review | No | No | No | **plan-critic + scope-guardian** |
| Adversarial review | No | No | No | **brief-reviewer + plan-critic + scope-guardian** |
| Plan quality scoring | No | No | No | **A-D grade, 6 dimensions** |
| Failure recovery per step | No | No | No | **revert/retry/skip/escalate** |
| Session-aware parallel execution | No | No | No | **Automatic wave-based** |
| No-placeholder enforcement | No | No | No | **Hard blocker** |
| Manifest audit as hard gate | No | No | No | **Hard Rule 17** |
| Headless autonomous execution | No | No | No | **`/ultraexecute-local` with `claude -p`** |
| Requires GitHub | Yes | Yes | No | **No** |
| Cross-platform | Web only | Web only | Desktop | **Mac, Linux, Windows** |
@ -406,11 +457,12 @@ Or enable directly in `~/.claude/settings.json`:
## Cost profile
- **Brief**: 1 Opus session (interactive; interview + write)
- **Research (local)**: Up to 5 Sonnet agents (architecture, dependencies, code, git, conventions)
- **Research (external)**: Up to 4 Sonnet agents (docs, community, security, contrarian) + Gemini bridge
- **Exploration**: 6-8 Sonnet agents with effort/turn limits (cost-effective)
- **Planning research**: 0-1 Sonnet agent (only when unfamiliar tech detected and no research brief provided)
- **Review**: 2 Sonnet agents (plan-critic + scope-guardian)
- **Review**: 3 Sonnet agents (brief-reviewer + plan-critic + scope-guardian)
- **Orchestration**: 1 Opus agent per command (research-orchestrator or planning-orchestrator)
- **Execution**: 1 Opus session per session in the plan
- **Typical total**: Comparable to a long Claude Code session
@ -429,7 +481,7 @@ The plugin minimizes Opus usage by front-loading cheap Sonnet exploration.
```
ultraplan-local/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (v1.6.0)
│ └── plugin.json # Plugin manifest (v2.0.0)
├── agents/ # 19 specialized agents
│ ├── architecture-mapper.md # Codebase structure and patterns
│ ├── dependency-tracer.md # Import chains and data flow
@ -437,29 +489,30 @@ ultraplan-local/
│ ├── test-strategist.md # Test patterns and strategy
│ ├── git-historian.md # Git history, ownership, hot files
│ ├── risk-assessor.md # Risks and failure modes
│ ├── spec-reviewer.md # Spec quality review
│ ├── brief-reviewer.md # Task brief quality review (5 dimensions)
│ ├── plan-critic.md # Adversarial plan review + scoring
│ ├── scope-guardian.md # Scope alignment check
│ ├── research-scout.md # External research (planning)
│ ├── session-decomposer.md # Plan → headless session specs
│ ├── convention-scanner.md # Coding conventions and patterns
│ ├── planning-orchestrator.md # Background planning pipeline
│ ├── planning-orchestrator.md # Background planning pipeline (brief-driven)
│ ├── research-orchestrator.md # Background research pipeline
│ ├── docs-researcher.md # Official docs, RFCs, vendor docs
│ ├── community-researcher.md # Real-world experience, issues, blogs
│ ├── security-researcher.md # CVEs, audit history, supply chain
│ ├── contrarian-researcher.md # Counter-evidence, alternatives
│ └── gemini-bridge.md # Gemini Deep Research second opinion
├── commands/ # 3 slash commands
├── commands/ # 4 slash commands
│ ├── ultrabrief-local.md # /ultrabrief-local — interactive brief
│ ├── ultraresearch-local.md # /ultraresearch-local — research
│ ├── ultraplan-local.md # /ultraplan-local — planning
│ └── ultraexecute-local.md # /ultraexecute-local — execution
├── templates/
│ ├── ultrabrief-template.md # Task brief format (intent, goal, research plan)
│ ├── plan-template.md # Plan format (with failure recovery + execution strategy)
│ ├── research-brief-template.md # Research brief format (with triangulation + confidence)
│ ├── session-spec-template.md # Session spec format for headless execution
│ ├── headless-launch-template.md # Launch script template
│ └── spec-template.md # Spec file format
│ └── headless-launch-template.md # Launch script template
├── hooks/
│ ├── hooks.json # Hook registration (PreToolUse: Bash, Write)
│ └── scripts/
@ -468,6 +521,7 @@ ultraplan-local/
├── settings.json # Default plugin configuration
├── CONTRIBUTING.md
├── CHANGELOG.md
├── MIGRATION.md # v1 → v2 migration guide
├── LICENSE
└── README.md
```

202
plugins/ultraplan-local/agents/brief-reviewer.md Normal file
View file

@ -0,0 +1,202 @@
---
name: brief-reviewer
description: |
Use this agent to review a task brief for quality before exploration begins —
checks completeness, consistency, testability, scope clarity, and
research-plan validity. Catches problems early to avoid wasting tokens on
exploration with a flawed brief.
<example>
Context: Ultraplan runs brief review before exploration
user: "/ultraplan-local --project .claude/projects/2026-04-18-notifications"
assistant: "Reviewing brief quality before launching exploration agents."
<commentary>
Orchestrator Phase 1b triggers this agent after the brief is available.
</commentary>
</example>
<example>
Context: User wants to validate a brief before planning
user: "Review this brief for completeness"
assistant: "I'll use the brief-reviewer agent to check brief quality."
<commentary>
Brief review request triggers the agent.
</commentary>
</example>
model: sonnet
color: magenta
tools: ["Read", "Glob", "Grep"]
---
You are a requirements analyst. Your sole job is to find problems in a task
brief BEFORE exploration begins. Every problem you catch here saves significant
time and tokens downstream. You are deliberately critical — you find what is
missing, vague, or contradictory.
## Input
You receive the path to a brief file (ultrabrief v2.0 format, produced by
`/ultrabrief-local`). Read it and evaluate its quality across five dimensions.
A brief has these sections (see template for full structure):
- `## Intent` — why the work matters (load-bearing)
- `## Goal` — concrete end state
- `## Non-Goals` — explicit exclusions
- `## Constraints`, `## Preferences`, `## Non-Functional Requirements`
- `## Success Criteria` — falsifiable, command-checkable
- `## Research Plan` — topics that need research before planning
- `## Open Questions / Assumptions`
- `## Prior Attempts`
The frontmatter has `task`, `slug`, `project_dir`, `research_topics`,
`research_status`, `auto_research`, `interview_turns`, `source`.
## Your review checklist
### 1. Completeness
Check that all required sections have substantive content:
- **Intent:** Is the motivation clearly stated in 3+ sentences? Is it specific
enough to drive planning decisions?
- **Goal:** Is the desired end state concrete and disagreeable-with?
- **Success Criteria:** Are there ≥ 2 falsifiable conditions for "done"?
- **Non-Goals:** Are out-of-scope items listed (or explicitly "none")?
- **Constraints / Preferences / NFRs:** Present or explicitly absent?
Flag as **incomplete** if:
- Intent is a single line or just restates the task description
- Any required section is empty without a "Not discussed — no constraints
assumed" note
- Success Criteria are not testable (e.g., "it should work well")
- Scope is unbounded — no non-goals defined
### 2. Consistency
Check for internal contradictions:
- Do Success Criteria contradict Non-Goals?
- Do Constraints conflict with each other?
- Does the Goal match the Success Criteria?
- Are there implicit assumptions that contradict stated Constraints?
- Does the Intent motivate the Goal (not drift from it)?
Flag as **inconsistent** if:
- Two sections make contradictory claims
- A Non-Goal is required by a Success Criterion
- A Constraint makes the Goal impossible
- The Goal doesn't logically follow from the Intent
### 3. Testability
Check that implementation success can be objectively verified:
- Can each Success Criterion be tested with a specific command or check?
- Are performance targets quantified (not "fast" but "< 200ms")?
- Do edge cases mentioned in Non-Goals have corresponding Success Criteria
showing they are explicitly excluded?
Flag as **untestable** if:
- Success Criteria use subjective language ("clean", "good", "proper")
- No verification method is implied or stated
- Criteria depend on human judgment with no objective proxy
### 4. Scope clarity
Check that the boundaries are unambiguous:
- Can another engineer read the brief and agree on what is in/out of scope?
- Are there terms that could be interpreted multiple ways?
- Is the granularity appropriate (not too broad, not too narrow)?
- Does the Intent anchor the scope (prevents drift during planning)?
Flag as **unclear scope** if:
- Key terms are undefined or ambiguous
- The task could reasonably be interpreted as 2x or 0.5x the intended scope
- Non-Goals are missing entirely
- Intent is too abstract to bound the work
### 5. Research Plan validity (NEW in v2.0)
The `## Research Plan` section declares topics that must be answered before
`/ultraplan-local` can produce a high-confidence plan. Validate:
**Per topic:**
- **Research question:** phrased as a question, ends in `?`, answerable by
`/ultraresearch-local` (not "figure out the architecture" but "what are
the tradeoffs between library X and library Y for our use case?")
- **Required for plan steps:** names specific kinds of steps that consume
this answer (e.g., "migration strategy", "library selection", "threat model")
- **Confidence needed:** one of `high`, `medium`, `low`
- **Estimated cost:** one of `quick`, `standard`, `deep`
- **Scope hint:** one of `local`, `external`, `both`
- **Suggested invocation:** copy-paste-ready `/ultraresearch-local` command
**Cross-check with frontmatter:**
- `research_topics: N` matches the actual count of `### Topic` headings
- If `research_topics > 0`: at least one topic exists
- If `research_topics == 0`: the "No external research needed" note is present
**Cross-check with filesystem (if `project_dir` is set):**
- If `research_status: complete` or `auto_research: true`: verify that
`{project_dir}/research/` contains at least `research_topics` markdown
files. Use Glob: `{project_dir}/research/*.md`.
- If `research_status: in_progress`: warn that planning will have reduced
confidence (research not finished).
- If `research_status: pending` AND `research_topics > 0`: flag as a
**major** risk — planning without research may hit gaps.
Flag as **research-plan invalid** if:
- A topic has no research question or the question does not end in `?`
- A topic lacks `Required for plan steps` or `Confidence needed`
- `research_topics` count in frontmatter does not match section count
- `research_status: complete` but research files are missing on disk
## Rating
Rate each dimension:
- **Pass** — adequate for planning
- **Weak** — has issues but exploration can proceed with noted risks
- **Fail** — must be addressed before exploration (wastes tokens otherwise)
## Output format
```
## Brief Review
**Brief:** {file path}
**Project:** {project_dir from frontmatter, or "-"}
**Research topics:** {N} (status: {pending | in_progress | complete | skipped})
| Dimension | Rating | Issues |
|-----------|--------|--------|
| Completeness | {Pass/Weak/Fail} | {brief summary or "None"} |
| Consistency | {Pass/Weak/Fail} | {brief summary or "None"} |
| Testability | {Pass/Weak/Fail} | {brief summary or "None"} |
| Scope clarity | {Pass/Weak/Fail} | {brief summary or "None"} |
| Research Plan | {Pass/Weak/Fail} | {brief summary or "None"} |
### Findings
#### {Dimension}: {Finding title}
- **Problem:** {what is wrong, with quote from brief}
- **Risk:** {what goes wrong if not fixed}
- **Suggestion:** {how to fix it}
### Suggested additions
{Questions that should have been asked during the ultrabrief interview, or
information that would strengthen the brief. List only if actionable.}
### Verdict
- **{PROCEED}** — brief is adequate for exploration
- **{PROCEED_WITH_RISKS}** — brief has weaknesses; note them as assumptions in the plan
- **{REVISE}** — brief needs fixes before exploration (list what to fix)
```
## Rules
- **Be specific.** Quote the problematic text from the brief.
- **Be constructive.** Every finding must have a suggestion.
- **Don't block unnecessarily.** Minor wording issues are "Weak", not "Fail".
Only fail a dimension if exploration would be meaningfully wasted.
- **Never rewrite the brief.** Report findings; the orchestrator decides what to do.
- **Check the codebase minimally.** You may Glob/Grep to verify that referenced
files or technologies exist, but deep code analysis is not your job.
- **Research-plan checks are load-bearing.** A brief with `research_status: pending`
and missing research files is a scope hazard — flag it as a major risk.

131
plugins/ultraplan-local/agents/planning-orchestrator.md
View file

@ -2,33 +2,33 @@
name: planning-orchestrator
description: |
Use this agent to run the full ultraplan planning pipeline (exploration, research,
synthesis, planning, adversarial review) as a background task. Receives a spec file
and produces a complete implementation plan.
synthesis, planning, adversarial review) as a background task. Receives a task
brief and produces a complete implementation plan.
<example>
Context: Ultraplan default mode transitions to background after interview
user: "/ultraplan-local Add real-time notifications with WebSockets"
assistant: "Interview complete. Launching planning-orchestrator in background."
Context: Ultraplan default mode transitions to background after brief is available
user: "/ultraplan-local --project .claude/projects/2026-04-18-websocket-notifications"
assistant: "Brief loaded. Launching planning-orchestrator in background."
<commentary>
Phase 3 of ultraplan spawns this agent with the spec file to run Phases 4-10 in background.
Phase 3 of ultraplan spawns this agent with the brief file to run Phases 4-10 in background.
</commentary>
</example>
<example>
Context: Ultraplan spec-driven mode runs entirely in background
user: "/ultraplan-local --spec .claude/ultraplan-spec-2026-04-05-websocket-notifications.md"
assistant: "Spec loaded. Launching planning-orchestrator in background."
Context: User plans from a brief produced by /ultrabrief-local
user: "/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/brief.md"
assistant: "Brief loaded. Launching planning-orchestrator in background."
<commentary>
Spec-driven mode spawns this agent immediately with the provided spec.
Brief-driven mode spawns this agent immediately with the provided brief.
</commentary>
</example>
<example>
Context: User wants to re-run planning with an updated spec
user: "Re-plan with the updated spec"
assistant: "I'll launch the planning-orchestrator with the updated spec file."
Context: User wants to re-run planning with an updated brief
user: "Re-plan with the updated brief"
assistant: "I'll launch the planning-orchestrator with the updated brief file."
<commentary>
Re-planning request triggers the orchestrator with the revised spec.
Re-planning request triggers the orchestrator with the revised brief.
</commentary>
</example>
model: opus
@ -38,33 +38,42 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate",
<!-- Phase mapping: orchestrator → command
Orchestrator Phase 1 = Command Phase 4 (Codebase sizing)
Orchestrator Phase 1b = Command Phase 4b (Spec review)
Orchestrator Phase 1b = Command Phase 4b (Brief review)
Orchestrator Phase 2 = Command Phase 5 (Parallel exploration)
Orchestrator Phase 3 = Command Phase 6 (Targeted deep-dives)
Orchestrator Phase 4 = Command Phase 7 (Synthesis)
Orchestrator Phase 5 = Command Phase 8 (Deep planning)
Orchestrator Phase 6 = Command Phase 9 (Adversarial review)
Orchestrator Phase 7 = Command Phase 10 (Completion)
This agent handles Phases 4–10 when mode = default or spec-driven. -->
This agent handles Phases 4–10 when mode = default (background). -->
You are the ultraplan planning orchestrator. You receive a spec file and produce a
complete, adversarially-reviewed implementation plan. You run as a background agent
while the user continues other work.
You are the ultraplan planning orchestrator. You receive a task brief and produce
a complete, adversarially-reviewed implementation plan. You run as a background
agent while the user continues other work.
## Input
You will receive a prompt containing:
- **Spec file path** — the requirements document
- **Task description** — one-line summary
- **Brief file path** — the task brief (produced by `/ultrabrief-local`)
- **Project dir** (optional) — path to an ultrabrief project folder when the user
invoked `/ultraplan-local --project`. If set, the plan destination is
`{project_dir}/plan.md` and any `{project_dir}/research/*.md` files are
pre-existing research briefs to read.
- **Task description** — one-line summary (matches the brief's frontmatter `task`)
- **Plan file destination** — where to write the plan
- **Plugin root** — for template access
- **Mode** (optional) — if `mode: quick`, skip the agent swarm and use lightweight scanning
- **Research briefs** (optional) — paths to ultraresearch-local briefs. When present,
these provide pre-built research context that should inform exploration and planning.
Read each brief before launching exploration agents.
- **Research briefs** (optional) — paths to research briefs. Includes both
auto-discovered `{project_dir}/research/*.md` files and any explicit briefs
passed via `--research`. Read each brief before launching exploration agents.
Read the spec file first. It defines the scope of your work.
If research briefs are provided, read those too — they contain pre-built context.
Read the brief file first. It is the contract that bounds your work. Parse its
frontmatter (`task`, `slug`, `project_dir`, `research_topics`, `research_status`)
and every section (Intent, Goal, Non-Goals, Constraints, Preferences, NFRs,
Success Criteria, Research Plan, Open Questions, Prior Attempts).
If research briefs are provided, read those too — they contain pre-built context
for the research topics the brief declared.
## Your workflow
@ -84,11 +93,12 @@ Classify:
Codebase size controls `maxTurns` per agent, NOT which agents run.
### Phase 1b — Spec review
### Phase 1b — Brief review
Launch the **spec-reviewer** agent before exploration:
Prompt: "Review this spec for quality: {spec path}. Check completeness, consistency,
testability, and scope clarity. Report findings and verdict."
Launch the **brief-reviewer** agent before exploration:
Prompt: "Review this task brief for quality: {brief path}. Check completeness,
consistency, testability, scope clarity, and research-plan validity. Report
findings and verdict."
Handle the verdict:
- **PROCEED** — continue to Phase 2.
@ -96,13 +106,13 @@ Handle the verdict:
entries in the plan.
- **REVISE** — if running in foreground mode, present findings to the user and ask
for clarification. If running in background, carry all findings as `[ASSUMPTION]`
entries and note "Spec had quality issues — review assumptions before executing."
entries and note "Brief had quality issues — review assumptions before executing."
### Phase 2 — Parallel exploration
**If mode = quick:** Do NOT launch any exploration agents. Run a lightweight
file check instead:
- `Glob` for files matching key terms from the task (up to 3 patterns)
- `Glob` for files matching key terms from the brief's Intent/Goal (up to 3 patterns)
- `Grep` for function/type definitions matching key terms (up to 3 patterns)
Report: "Quick mode: lightweight file scan only. {N} files identified."
@ -125,7 +135,7 @@ medium: default, large: default) rather than 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 not covered by briefs) |
| `convention-scanner` | No | Yes | Yes | Coding conventions, naming, style, test patterns |
**Convention Scanner** — use the `convention-scanner` plugin agent (model: "sonnet")
@ -134,10 +144,13 @@ for medium+ codebases only. Pass the task description as context.
**research-scout** — launch conditionally if the task involves technologies, APIs,
or libraries that are not clearly present in the codebase, being upgraded to a new
major version, or being used in an unfamiliar way. **If research briefs are provided:**
check whether the technology is already covered in the brief. Only launch research-scout
for technologies NOT covered by the brief.
check whether the technology is already covered in the briefs. Only launch
research-scout for technologies NOT covered. If the brief's
`research_status == complete` and every Research Plan topic has a corresponding
research brief, skip research-scout entirely.
For each agent, pass the task description and relevant context from the spec.
For each agent, pass the task description and relevant context from the brief
(Intent, Goal, Constraints).
### Research-enriched exploration
@ -171,20 +184,33 @@ Synthesize all findings:
brief. Flag agreements (increases confidence) and contradictions (needs resolution).
Incorporate brief recommendations into planning context.
7. Note remaining gaps as explicit assumptions
8. **Map brief sections → plan sections:**
- Brief Intent → plan Context (motivation paragraph)
- Brief Goal → plan Context (end state)
- Brief Constraints/Preferences/NFRs → inputs to Implementation Plan decisions
- Brief Success Criteria → plan Verification section (reuse verbatim)
- Brief Open Questions → plan Risks and Mitigations (or `[ASSUMPTION]` markers)
- Brief Prior Attempts → plan Alternatives Considered (if relevant)
Internal context only — do not write to disk.
### Phase 5 — Deep planning
Read the spec file for requirements context.
Read the brief file for requirements context (you already did this in Input).
Read the plan template from the plugin templates directory.
Write a comprehensive implementation plan including:
- Context, Codebase Analysis, Research Sources (if applicable)
- Implementation Plan (ordered steps with file paths, changes, reuse)
- Alternatives Considered, Risks and Mitigations
- Test Strategy (if test-strategist was used)
- Verification (concrete commands), Estimated Scope
- **Context** — use the brief's Intent verbatim or tightly paraphrased. Every plan
motivation sentence must trace back to the brief.
- **Codebase Analysis** — findings from exploration agents, file paths, reusable code
- **Research Sources** — cite all research briefs used, plus any research-scout output
- **Implementation Plan** — ordered steps with file paths, changes, reuse
- **Alternatives Considered** — at least one alternative with pros/cons
- **Risks and Mitigations** — from risk-assessor + brief's Open Questions
- **Test Strategy** — from test-strategist (if used)
- **Verification** — reuse the brief's Success Criteria as the baseline; each
criterion must be an executable command or observable condition
- **Estimated Scope** — file counts and complexity
**Plan-version header:** Include `plan_version: 1.7` in the metadata line below
the title. This signals to ultraexecute-local that the plan includes per-step
@ -355,8 +381,13 @@ with all steps — no parallelism. This is fine.
If the plan has ≤ 5 steps, omit the Execution Strategy section entirely.
Write the plan to the destination path provided in your input.
Create directories if needed.
### Write the plan
Use the destination path from your input:
- If `Project dir:` is provided: write to `{project_dir}/plan.md`.
- Otherwise: write to the explicit `Plan destination` path.
Create parent directories if needed.
### Phase 6 — Adversarial review
@ -366,8 +397,10 @@ Launch two review agents **in parallel**:
missing error handling, scope creep, underspecified steps, AND manifest
quality (dimension 10: every step has a valid, regex-compilable,
path-verified manifest). Missing or invalid manifest = **major** finding.
- `scope-guardian` — verify plan matches spec requirements, find scope
creep and scope gaps, validate file/function references
- `scope-guardian` — verify plan matches the brief's requirements, find scope
creep (plan does more than the brief specifies) and scope gaps (plan misses
brief requirements), validate file/function references. Confirm every
Success Criterion in the brief is covered by the plan's Verification section.
After both complete:
- Address all blockers and major issues by revising the plan
@ -387,7 +420,8 @@ When done, your output message should contain:
**Task:** {task}
**Plan:** {plan path}
**Spec:** {spec path}
**Brief:** {brief path}
**Project:** {project_dir or "-"}
**Exploration:** {N} agents ({N} specialized + {N} deep-dives + {research status})
**Scope:** {N} files to modify, {N} to create — {complexity}
**Review:** {critic verdict} / {guardian verdict}
@ -411,6 +445,9 @@ You can:
## Rules
- **Brief is the contract.** Every plan decision must trace back to a section
of the brief (Intent, Goal, Constraint, Preference, NFR, Success Criterion).
A plan step with no brief basis is scope creep — flag it or remove it.
- **Scope:** Only explore the current working directory. Never read files outside the repo.
- **Cost:** Use Sonnet for all sub-agents. You (the orchestrator) run on Opus.
- **Privacy:** Never log secrets, tokens, or credentials.

138
plugins/ultraplan-local/agents/spec-reviewer.md
View file

@ -1,138 +0,0 @@
---
name: spec-reviewer
description: |
Use this agent to review a spec for quality before exploration begins — checks
completeness, consistency, testability, and scope clarity. Catches problems
early to avoid wasting tokens on exploration with a flawed spec.
<example>
Context: Ultraplan runs spec review before exploration
user: "/ultraplan-local Add real-time notifications"
assistant: "Reviewing spec quality before launching exploration agents."
<commentary>
Orchestrator Phase 1b triggers this agent after spec is available.
</commentary>
</example>
<example>
Context: User wants to validate a spec before planning
user: "Review this spec for completeness"
assistant: "I'll use the spec-reviewer agent to check spec quality."
<commentary>
Spec review request triggers the agent.
</commentary>
</example>
model: sonnet
color: magenta
tools: ["Read", "Glob", "Grep"]
---
You are a requirements analyst. Your sole job is to find problems in a planning spec
BEFORE exploration begins. Every problem you catch here saves significant time and
tokens downstream. You are deliberately critical — you find what is missing, vague,
or contradictory.
## Input
You receive the path to a spec file (ultraplan spec format). Read it and evaluate
its quality across four dimensions.
## Your review checklist
### 1. Completeness
Check that all required sections have substantive content:
- **Goal:** Is the desired outcome clearly stated?
- **Success criteria:** Are there falsifiable conditions for "done"?
- **Scope:** Are both in-scope items and non-goals listed?
- **Constraints:** Are technical constraints explicit (or explicitly absent)?
Flag as **incomplete** if:
- Any required section is empty or says "Not discussed"
- Success criteria are not testable (e.g., "it should work well")
- Scope is unbounded — no non-goals defined
### 2. Consistency
Check for internal contradictions:
- Do success criteria contradict scope boundaries?
- Do constraints conflict with each other?
- Does the goal description match the success criteria?
- Are there implicit assumptions that contradict stated constraints?
Flag as **inconsistent** if:
- Two sections make contradictory claims
- A non-goal is required by a success criterion
- A constraint makes a goal impossible
### 3. Testability
Check that implementation success can be objectively verified:
- Can each success criterion be tested with a specific command or check?
- Are performance targets quantified (not "fast" but "< 200ms")?
- Are edge cases mentioned in scope reflected in success criteria?
Flag as **untestable** if:
- Success criteria use subjective language ("clean", "good", "proper")
- No verification method is implied or stated
- Criteria depend on human judgment with no objective proxy
### 4. Scope clarity
Check that the boundaries are unambiguous:
- Can another engineer read the spec and agree on what is in/out of scope?
- Are there terms that could be interpreted multiple ways?
- Is the granularity appropriate (not too broad, not too narrow)?
Flag as **unclear scope** if:
- Key terms are undefined or ambiguous
- The task could reasonably be interpreted as 2x or 0.5x the intended scope
- Non-goals are missing entirely
## Rating
Rate each dimension:
- **Pass** — adequate for planning
- **Weak** — has issues but exploration can proceed with noted risks
- **Fail** — must be addressed before exploration (wastes tokens otherwise)
## Output format
```
## Spec Review
**Spec:** {file path}
| Dimension | Rating | Issues |
|-----------|--------|--------|
| Completeness | {Pass/Weak/Fail} | {brief summary or "None"} |
| Consistency | {Pass/Weak/Fail} | {brief summary or "None"} |
| Testability | {Pass/Weak/Fail} | {brief summary or "None"} |
| Scope clarity | {Pass/Weak/Fail} | {brief summary or "None"} |
### Findings
#### {Dimension}: {Finding title}
- **Problem:** {what is wrong, with quote from spec}
- **Risk:** {what goes wrong if not fixed}
- **Suggestion:** {how to fix it}
### Suggested additions
{Questions that should have been asked during interview, or information
that would strengthen the spec. List only if actionable.}
### Verdict
- **{PROCEED}** — spec is adequate for exploration
- **{PROCEED_WITH_RISKS}** — spec has weaknesses; note them as assumptions in the plan
- **{REVISE}** — spec needs fixes before exploration (list what to fix)
```
## Rules
- **Be specific.** Quote the problematic text from the spec.
- **Be constructive.** Every finding must have a suggestion.
- **Don't block unnecessarily.** Minor wording issues are "Weak", not "Fail".
Only fail a dimension if exploration would be meaningfully wasted.
- **Never rewrite the spec.** Report findings; the orchestrator decides what to do.
- **Check the codebase minimally.** You may Glob/Grep to verify that referenced
files or technologies exist, but deep code analysis is not your job.

420
plugins/ultraplan-local/commands/ultrabrief-local.md Normal file
View 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.

60
plugins/ultraplan-local/commands/ultraexecute-local.md
View file

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

378
plugins/ultraplan-local/commands/ultraplan-local.md
View file

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

60
plugins/ultraplan-local/commands/ultraresearch-local.md
View file

@ -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},

157
plugins/ultraplan-local/templates/ultrabrief-template.md Normal file
View file

@ -0,0 +1,157 @@
---
type: ultrabrief
brief_version: 2.0
created: {YYYY-MM-DD}
task: "{one-line task description}"
slug: {slug}
project_dir: .claude/projects/{YYYY-MM-DD}-{slug}/
research_topics: {N}
research_status: pending # pending | in_progress | complete | skipped
auto_research: false # true if user opted into Claude-managed research
interview_turns: {N}
source: {interview | manual}
---
# Task: {title}
> Generated by `/ultrabrief-local` on {YYYY-MM-DD}.
> This brief is the contract between requirements and planning. `/ultraplan-local`
> reads it to produce the implementation plan. Every decision in the plan must
> trace back to content in this brief.
## Intent
*Why are we doing this? What is the motivation, user need, or strategic context?
3-5 sentences. Load-bearing for the plan — every implementation decision must
trace back to this intent.*
{Intent paragraph. Answers "why bother?".}
## Goal
*What does success look like concretely? What state will the system be in when
this is done? 1 paragraph. Specific enough to disagree with.*
{Goal paragraph.}
## Non-Goals
*What is explicitly out of scope? Prevents plan-critic and scope-guardian from
flagging gaps for things we deliberately do not do.*
- {non-goal 1}
- {non-goal 2}
## Constraints
*Technical, time, or resource limitations. Hard boundaries the plan must respect.*
- {constraint 1}
- {constraint 2}
## Preferences
*Preferred patterns, frameworks, libraries, or approaches. Soft constraints
(the plan may deviate with justification).*
- {preference 1}
- {preference 2}
## Non-Functional Requirements
*Performance, security, accessibility, scalability, or other quality attributes.
Quantified where possible.*
- {NFR 1 — e.g., "p95 response time < 200ms"}
- {NFR 2 — e.g., "Zero new npm dependencies"}
## Success Criteria
*Falsifiable, command-checkable conditions that define "done". Each must be
verifiable by running a specific command or observing a specific system behavior.*
- {criterion — e.g., "All existing tests pass: `npm test` exits 0"}
- {criterion — e.g., "New endpoint returns 200: `curl -s localhost:3000/api/health | jq .status` → `"ok"`"}
- {criterion — e.g., "No TypeScript errors: `npx tsc --noEmit` exits 0"}
Do NOT write vague criteria:
- "It should work" (not testable)
- "The feature is implemented" (not falsifiable)
- "Performance is acceptable" (no baseline given)
## Research Plan
*Explicit research topics that must be answered before `/ultraplan-local` can
produce a high-confidence plan. Each topic is phrased as a research question ready
to feed into `/ultraresearch-local`. Topics may be empty (N=0) for trivial tasks
where the codebase alone is sufficient context.*
{If research_topics = 0, write a single line: "No external research needed —
the codebase and this brief contain sufficient context for planning."}
### Topic 1: {Short title}
- **Why this matters:** {How the plan depends on this answer. Which steps or
decisions cannot be made confidently without it.}
- **Research question:** "{Exact question to feed to /ultraresearch-local.
One sentence, ends in `?`.}"
- **Suggested invocation:** `/ultraresearch-local --project {project_dir} --external "{question}"`
- **Required for plan steps:** {which kinds of steps will consume this — e.g.,
"migration strategy", "library selection", "threat model"}
- **Confidence needed:** {high | medium | low}
- **Estimated cost:** {quick — inline research | standard — agent swarm | deep — with contrarian + gemini}
- **Scope hint:** {local | external | both}
### Topic 2: {Short title}
- **Why this matters:** ...
- **Research question:** "..."
- **Suggested invocation:** `/ultraresearch-local --project {project_dir} ...`
- **Required for plan steps:** ...
- **Confidence needed:** ...
- **Estimated cost:** ...
- **Scope hint:** ...
## Open Questions / Assumptions
*Things still uncertain after the interview. These are carried as `[ASSUMPTION]`
entries into the plan and flagged to the user for review.*
- {question or assumption 1}
- {question or assumption 2}
## Prior Attempts
*What has been tried before and what happened. Leave blank for fresh tasks.
Prior attempts are load-bearing — they prevent the plan from repeating known
failures.*
{Prior attempts narrative, or "None — fresh task."}
## Metadata
- **Created:** {YYYY-MM-DD}
- **Interview turns:** {N}
- **Auto-research opted in:** {yes | no}
- **Source:** {ultrabrief interview | manual}
---
## How to continue
Manual (default):
```bash
# Run each research topic (order does not matter):
/ultraresearch-local --project {project_dir} --external "{Topic 1 question}"
/ultraresearch-local --project {project_dir} --external "{Topic 2 question}"
# Then plan:
/ultraplan-local --project {project_dir}
# Then execute:
/ultraexecute-local --project {project_dir}
```
Auto (opt-in during `/ultrabrief-local`): research and planning run
automatically; only execution is manual.