open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/ultraplan-local/README.md
Kjell Tore Guttormsen 8e2b868826 docs(ultraplan-local): document security hardening in README and CLAUDE.md 
Add Security hardening section to ultraplan-local README covering all 4
defense layers. Update architecture tree to include hooks directory.
Update root marketplace README with security summary and hook count.
Update CLAUDE.md architecture section with Phase 2.4 and --allowedTools.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-08 18:35:34 +02:00

466 lines
24 KiB
Markdown
Raw Blame History

# ultraplan-local — Plan, Research, Execute
![Version](https://img.shields.io/badge/version-1.6.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 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
```bash
# 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:**
```bash
/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):**
```bash
/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:**
```bash
/ultraplan-local Add WebSocket notifications
# Review the plan, then:
/ultraexecute-local .claude/plans/ultraplan-2026-04-08-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-08-websocket.md
```
**Quick plan for small tasks:**
```bash
/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:**
```bash
/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`:
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
```
Or enable directly in `~/.claude/settings.json`:
```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](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
- Optional: [Gemini MCP server](https://github.com/anthropics/anthropic-cookbook/tree/main/tool-use/gemini-mcp) 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](CONTRIBUTING.md).
## License
[MIT](LICENSE)
Reference in a new issue View git blame Copy permalink