16 KiB
ultraplan-local and ultraexecute-local — Plan Deep, Execute Clean
A Claude Code plugin that plans complex implementations with specialized agent swarms and adversarial review, then executes them autonomously with failure recovery and parallel sessions. Two commands, one pipeline:
| Command | What it does |
|---|---|
/ultraplan-local |
Plan — interview, agent swarm exploration, adversarial review |
/ultraexecute-local |
Execute — disciplined step-by-step implementation with failure recovery |
Plan first, then execute. Or plan and execute in one flow. The plan is the contract between the two.
No cloud dependency. No GitHub requirement. Works on Mac, Linux, and Windows.
Quick start
# Install
git clone https://git.fromaitochitta.com/open/ultraplan-local.git ~/plugins/ultraplan-local
# Plan
/ultraplan-local Add user authentication with JWT tokens
# Execute
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-jwt-auth.md
That's it. /ultraplan-local interviews you, explores the codebase with 6-8 specialized agents, writes a plan with adversarial review, and hands you a plan file. /ultraexecute-local reads that plan and implements it step by step with automatic failure recovery and git checkpoints.
When to use it
Use it when:
- The task touches 3+ files or modules and you need to understand how they connect
- You're working in an unfamiliar codebase and need a map before you start
- 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
Don't use it when:
- The task is a single-file change where the fix is obvious
- You already know exactly what to change and in what order
- The task is pure research or exploration with no implementation to plan
Rule of thumb: If you can describe the full implementation in one sentence and it touches 1-2 files, skip ultraplan and just implement. If you need to think about it, ultraplan earns its cost.
/ultraplan-local — Planning
Runs a structured planning workflow that produces an implementation plan detailed enough for autonomous execution.
How it works
- Interview -- Iterative requirements gathering (goal, constraints, preferences, NFRs)
- Explore -- 6-8 specialized Sonnet agents analyze your codebase in parallel
- Research -- External documentation for unfamiliar technologies (conditional)
- Synthesize -- Findings merged into a unified codebase understanding
- Plan -- Opus creates a comprehensive implementation plan with failure recovery
- Critique -- Adversarial review by plan-critic (9 dimensions) and scope-guardian
- Refine -- You review, ask questions, request changes
- Handoff -- Execute now, save for later, or export
Output: .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 |
| Foreground | /ultraplan-local --fg Add auth |
All phases in foreground (blocking) |
| Quick | /ultraplan-local --quick Add auth |
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 |
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 (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
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.
Exploration agents
| Agent | Role | Runs on |
|---|---|---|
| architecture-mapper | Codebase structure, patterns, anti-patterns | All codebases |
| dependency-tracer | Import chains, data flow, side effects | All codebases |
| task-finder | Task-relevant files, functions, reuse candidates | All codebases |
| test-strategist | Test patterns, coverage gaps, strategy | All codebases |
| git-historian | Git history, ownership, hot files, branches | All codebases |
| risk-assessor | Threats, edge cases, failure modes | All codebases |
| research-scout | External docs, best practices | When unfamiliar tech detected |
| convention-scanner | Coding conventions, naming, style, test patterns | Medium+ codebases |
Review agents
| 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 |
/ultraexecute-local — Execution
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
- Implement -- Applies the Changes field exactly as written
- Verify -- Runs the Verify command (exit code is truth)
- On failure -- Follows the plan's recovery clause (revert / retry / skip / escalate)
- 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 |
| 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 |
Session-aware parallel execution
When a plan has an ## Execution Strategy section (auto-generated by /ultraplan-local for plans with > 5 steps), /ultraexecute-local automatically:
- Parses sessions, waves, and scope fences from the plan
- Launches parallel
claude -p "/ultraexecute-local --session N plan.md"per session per wave - Waits for each wave to complete before starting the next
- Aggregates results and runs master verification
Wave 1: Session 1 (Foundation) + Session 2 (Middleware) -- parallel
↓ both complete
Wave 2: Session 3 (Integration) -- sequential
↓ complete
Master verification
Use --fg to force sequential execution even when a plan has an Execution Strategy.
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.
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
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
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_summaryblock for log parsing
The full pipeline
/ultraplan-local /ultraexecute-local
┌──────────────────────┐ ┌──────────────────────┐
│ Interview │ │ Parse plan │
│ ↓ │ │ ↓ │
│ 6-8 exploration │ │ Detect sessions │
│ agents (parallel) │ plan.md │ ↓ │
│ ↓ │ ──────────────→ │ Execute steps │
│ Opus planning │ │ (verify + checkpoint │
│ ↓ │ │ per step) │
│ Adversarial review │ │ ↓ │
│ ↓ │ │ Master verification │
│ Plan file │ │ ↓ │
└──────────────────────┘ │ Done │
└──────────────────────┘
Example workflows
Interactive planning + manual execution:
/ultraplan-local Add WebSocket notifications
# Review the plan, then:
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-websocket.md
Spec-driven headless (CI/automation):
# 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-06-websocket.md
Quick plan for small tasks:
/ultraplan-local --quick Fix the login redirect bug
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-login-fix.md
Dry run to validate before executing:
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-auth.md --dry-run
# Looks good:
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-auth.md
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 |
| Codebase exploration | Cloud | Cloud | Cloud | 6-8 specialized agents |
| Adversarial review | No | No | No | 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 |
| 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 |
Known limitations
Infrastructure-as-code (IaC) gets reduced value. The exploration agents are designed for application code. Terraform, Helm, Pulumi, CDK projects will get a plan, but agents like architecture-mapper and test-strategist produce less useful output for IaC. Use ultraplan-local for the structural plan, then supplement IaC-specific steps manually.
Installation
From source
git clone https://git.fromaitochitta.com/open/ultraplan-local.git ~/plugins/ultraplan-local
Usage with Claude Code
One-time:
claude --plugin-dir ~/plugins/ultraplan-local
Permanent -- add to ~/.claude/settings.json:
{
"plugins": [
"~/plugins/ultraplan-local"
]
}
Cost profile
- Exploration: 6-8 Sonnet agents with effort/turn limits (cost-effective)
- Research: 0-1 Sonnet agent (only when unfamiliar tech detected)
- Review: 2 Sonnet agents (plan-critic + scope-guardian)
- Orchestration: 1 Opus agent (planning-orchestrator)
- Execution: 1 Opus session per session in the plan
- Typical total: Comparable to a long Claude Code session
The plugin minimizes Opus usage by front-loading cheap Sonnet exploration.
Requirements
- Claude Code (CLI, desktop app, or web app)
- Claude subscription with Opus access (Max plan recommended)
- Optional: Tavily MCP server for enhanced external research
Architecture
ultraplan-local/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (v1.4.0)
├── agents/ # 13 specialized agents
│ ├── architecture-mapper.md # Codebase structure and patterns
│ ├── dependency-tracer.md # Import chains and data flow
│ ├── task-finder.md # Task-relevant code discovery
│ ├── 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
│ ├── plan-critic.md # Adversarial plan review + scoring
│ ├── scope-guardian.md # Scope alignment check
│ ├── research-scout.md # External research
│ ├── session-decomposer.md # Plan → headless session specs
│ ├── convention-scanner.md # Coding conventions and patterns
│ └── planning-orchestrator.md # Background planning pipeline
├── commands/ # 2 slash commands
│ ├── ultraplan-local.md # /ultraplan-local — planning
│ └── ultraexecute-local.md # /ultraexecute-local — execution
├── templates/
│ ├── plan-template.md # Plan format (with failure recovery + execution strategy)
│ ├── session-spec-template.md # Session spec format for headless execution
│ ├── headless-launch-template.md # Launch script template
│ └── spec-template.md # Spec file format
├── settings.json # Default plugin configuration
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── README.md
Pure markdown. No scripts, no dependencies, no platform-specific code.
Contributing
See CONTRIBUTING.md.