ktg-plugin-marketplace/plugins/ultraplan-local

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

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:

/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.

License

MIT