feat(ultraplan-local)!: v2.0.0 — brief-driven four-command pipeline
Extract interview from /ultraplan-local into new /ultrabrief-local command.
/ultraplan-local now requires --brief or --project (breaking). All pipeline
artifacts land in one project directory: .claude/projects/{date}-{slug}/
with brief.md, research/, plan.md, sessions/, progress.json.
Breaking changes:
- /ultraplan-local requires --brief <path> or --project <dir>
- /ultraplan-local --spec removed (convert specs to briefs per MIGRATION.md)
- Interview phase moved to /ultrabrief-local
- spec-reviewer renamed to brief-reviewer with 5th dimension (Research Plan validity)
Added:
- /ultrabrief-local command (interactive interview → brief.md with research plan)
- templates/ultrabrief-template.md (task brief format with intent + research plan)
- brief-reviewer agent (5-dimension brief quality review)
- --project <dir> flag on /ultraresearch-local, /ultraplan-local, /ultraexecute-local
- MIGRATION.md (v1 → v2 upgrade guide)
Changed:
- planning-orchestrator accepts Brief file: input (was Spec file:)
- planning-orchestrator Phase 1b uses brief-reviewer
- README + CLAUDE.md rewritten for four-command pipeline and task/research brief terminology
- CHANGELOG.md [2.0.0] entry with rationale
- Marketplace root README + CLAUDE.md updated to v2.0.0
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
fb9eb79d17
commit
2bc405e14a
15 changed files with 1799 additions and 592 deletions
|
|
@ -1,34 +1,44 @@
|
|||
# ultraplan-local — Plan, Research, Execute
|
||||
# ultraplan-local — Brief, Research, Plan, Execute
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue