# ultraplan-local and ultraexecute-local — Plan Deep, Execute Clean

![Version](https://img.shields.io/badge/version-1.4.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 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

```bash
# 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

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

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

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

### 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:

1. Parses sessions, waves, and scope fences from the plan
2. Launches parallel `claude -p "/ultraexecute-local --session N plan.md"` per session per wave
3. Waits for each wave to complete before starting the next
4. 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_summary` block 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:**
```bash
/ultraplan-local Add WebSocket notifications
# Review the plan, then:
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-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-06-websocket.md
```

**Quick plan for small tasks:**
```bash
/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:**
```bash
/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

```bash
git clone https://git.fromaitochitta.com/open/ultraplan-local.git ~/plugins/ultraplan-local
```

### Usage with Claude Code

**One-time:**

```bash
claude --plugin-dir ~/plugins/ultraplan-local
```

**Permanent** -- add to `~/.claude/settings.json`:

```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](https://docs.anthropic.com/en/docs/claude-code) (CLI, desktop app, or web app)
- Claude subscription with Opus access (Max plan recommended)
- Optional: [Tavily MCP server](https://github.com/tavily-ai/tavily-mcp) 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](CONTRIBUTING.md).

## License

[MIT](LICENSE)