351 lines
16 KiB
Markdown
351 lines
16 KiB
Markdown
# ultraplan-local and ultraexecute-local — Plan Deep, Execute Clean
|
|
|
|
|
|
|
|
|
|
|
|
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)
|