open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat: initial open marketplace with llm-security, config-audit, ultraplan-local

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-04-06 18:47:49 +02:00
commit f93d6abdae
380 changed files with 65935 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

351
plugins/ultraplan-local/README.md Normal file
View file

@ -0,0 +1,351 @@
# ultraplan-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)