ktg-plugin-marketplace/plugins/ultraplan-local

ultraplan-local — Plan, Research, Execute

A Claude Code plugin for deep implementation planning, multi-source research, and autonomous execution. Three commands, one pipeline:

Command	What it does
/ultraresearch-local	Research — deep local + external research with triangulation
/ultraplan-local	Plan — interview, agent swarm exploration, 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.

No cloud dependency. No GitHub requirement. Works on Mac, Linux, and Windows.

Quick start

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

# Plan with research context
/ultraplan-local --research .claude/research/ultraresearch-2026-04-08-express-fastify.md Migrate API to Fastify

# Plan without prior research
/ultraplan-local Add user authentication with JWT tokens

# Execute
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-jwt-auth.md

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
• You need to research a technology, library, or approach before deciding (use /ultraresearch-local)

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

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.

---

/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 to produce insights that neither local nor external research could provide alone.

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

Output: .claude/research/ultraresearch-{date}-{slug}.md

Modes

Mode	Usage	Behavior
Default	/ultraresearch-local <question>	Interview + background research (local + external + Gemini)
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.

Research agents

Agent	Role	Scope
architecture-mapper	How architecture relates to the research question	Local
dependency-tracer	Dependencies and integrations relevant to the topic	Local
task-finder	Existing code relevant to the question	Local
git-historian	Recent changes and ownership in related areas	Local
convention-scanner	Coding patterns relevant to evaluating options	Local (medium+ codebases)
docs-researcher	Official documentation, RFCs, vendor docs	External
community-researcher	Real-world experience, issues, blog posts	External
security-researcher	CVEs, audit history, supply chain risks	External
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.

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

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

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

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 (worktree-isolated)

When a plan has an ## Execution Strategy section (auto-generated by /ultraplan-local for plans with > 5 steps), /ultraexecute-local automatically:

1. Pre-flight checks — validates clean working tree, plan file tracked in git, no scope fence overlaps between parallel sessions, no stale worktrees
2. Creates git worktrees — each parallel session gets its own isolated worktree and branch (ultraplan/{slug}/session-{N})
3. Launches claude -p per session per wave, each in its own worktree
4. Merges branches back sequentially with --no-ff after each wave completes
5. Cleans up worktrees and branches unconditionally (even on failure)
6. Runs master verification on the merged result

Wave 1: Session 1 (worktree-1) + Session 2 (worktree-2)  -- parallel
         ↓ both complete → sequential merge to main
Wave 2: Session 3 (worktree-3)                             -- sequential
         ↓ complete → merge to main
Cleanup worktrees + Master verification

Each session operates in complete filesystem isolation — no shared git index, no race conditions, no data loss. If a merge produces conflicts, the merge is aborted and conflicting files are reported.

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

Security hardening

The executor implements defense-in-depth security across four layers:

1. Plugin hooks — pre-bash-executor.mjs blocks 13 categories of destructive commands (rm -rf /, chmod 777, pipe-to-shell, eval injection, disk wipe, shutdown, fork bombs, cron persistence, process killing, history destruction) with bash evasion normalization. pre-write-executor.mjs blocks writes to .git/hooks/, .claude/settings.json, shell configs, .ssh/, .aws/, and .env files
2. Prompt-level denylist — Security rules embedded in the executor command and session spec template that work even in headless claude -p sessions where hooks don't run
3. Pre-execution plan scan — Phase 2.4 scans all Verify: and Checkpoint: commands against the denylist before execution begins, catching dangerous commands before they reach the executor
4. Scoped tool access — Headless child sessions use --allowedTools "Read,Write,Edit,Bash,Glob,Grep" instead of --dangerously-skip-permissions, blocking Agent spawning, MCP tools, and web access in parallel sessions

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

 /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                 │
                                                                └──────────────────────┘

Example workflows

Research-first planning:

/ultraresearch-local Should we use Redis or Memcached for session caching?
# → .claude/research/ultraresearch-2026-04-08-redis-memcached.md

/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

Standalone research (no planning):

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

/ultraplan-local Add WebSocket notifications
# Review the plan, then:
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-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-08-websocket.md

Quick plan for small tasks:

/ultraplan-local --quick Fix the login redirect bug
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-login-fix.md

Dry run to validate before executing:

/ultraexecute-local .claude/plans/ultraplan-2026-04-08-auth.md --dry-run
# Looks good:
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-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
Deep research pipeline	No	No	No	10 agents + Gemini + triangulation
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

Add the marketplace and browse plugins with /plugin:

claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git

Or enable directly in ~/.claude/settings.json:

{
  "enabledPlugins": {
    "ultraplan-local@ktg-plugin-marketplace": true
  }
}

Cost profile

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

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
• Optional: Gemini MCP server for independent second opinion via Gemini Deep Research

Architecture

ultraplan-local/
├── .claude-plugin/
│   └── plugin.json                # Plugin manifest (v1.6.0)
├── agents/                        # 19 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 (planning)
│   ├── session-decomposer.md      # Plan → headless session specs
│   ├── convention-scanner.md      # Coding conventions and patterns
│   ├── planning-orchestrator.md   # Background planning pipeline
│   ├── 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
│   ├── ultraresearch-local.md     # /ultraresearch-local — research
│   ├── ultraplan-local.md         # /ultraplan-local — planning
│   └── ultraexecute-local.md      # /ultraexecute-local — execution
├── templates/
│   ├── 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
├── hooks/
│   ├── hooks.json                 # Hook registration (PreToolUse: Bash, Write)
│   └── scripts/
│       ├── pre-bash-executor.mjs  # Blocks destructive commands (13 BLOCK + 8 WARN rules)
│       └── pre-write-executor.mjs # Blocks writes to sensitive paths (8 rules)
├── settings.json                  # Default plugin configuration
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── README.md

Pure markdown commands and agents. Hooks are self-contained Node.js with zero dependencies.

Contributing

See CONTRIBUTING.md.

License

MIT