diff --git a/README.md b/README.md index 8c2b80e..f155c7a 100644 --- a/README.md +++ b/README.md @@ -44,18 +44,19 @@ Key commands: `/config-audit posture`, `/config-audit discover`, `/config-audit --- -### [Ultraplan Local and Ultra Execute Local](plugins/ultraplan-local/) `v1.4.0` +### [Ultraplan Local](plugins/ultraplan-local/) `v1.6.0` -Deep implementation planning with specialized agent swarms and adversarial review, then autonomous execution with failure recovery. +Deep research, implementation planning, and autonomous execution with specialized agent swarms, adversarial review, and failure recovery. -Two commands, one pipeline: plan first, then execute. The plan is the contract between the two. +Three commands, one pipeline: research first, then plan, then execute. -- **`/ultraplan-local`** — Interview, 6-8 specialized agents explore the codebase in parallel, adversarial review by plan-critic and scope-guardian +- **`/ultraresearch-local`** — Deep multi-source research with triangulation: 5 local agents + 4 external agents + Gemini bridge, producing structured briefs with confidence ratings +- **`/ultraplan-local`** — Interview, 6-8 specialized agents explore the codebase in parallel, adversarial review by plan-critic and scope-guardian. Accepts research briefs via `--research` - **`/ultraexecute-local`** — Step-by-step implementation with git checkpoints, automatic failure recovery, and parallel session decomposition -Modes: default (interview + background), spec-driven, foreground, quick, decompose, export +Modes: default, spec-driven, research-enriched, foreground, quick, decompose, export -13 specialized agents · 2 commands · No cloud dependency +19 specialized agents · 3 commands · No cloud dependency → [Full documentation](plugins/ultraplan-local/README.md) diff --git a/plugins/ultraplan-local/CONTRIBUTING.md b/plugins/ultraplan-local/CONTRIBUTING.md index 7ed57ec..818a63f 100644 --- a/plugins/ultraplan-local/CONTRIBUTING.md +++ b/plugins/ultraplan-local/CONTRIBUTING.md @@ -31,23 +31,29 @@ Changes to this plugin must preserve: | File | Purpose | |------|---------| | `.claude-plugin/plugin.json` | Plugin manifest | -| `commands/ultraplan-local.md` | The `/ultraplan-local` slash command — workflow orchestration | -| `agents/*.md` | Specialized agents for exploration, review, and orchestration | +| `commands/ultraresearch-local.md` | The `/ultraresearch-local` slash command — research orchestration | +| `commands/ultraplan-local.md` | The `/ultraplan-local` slash command — planning orchestration | +| `commands/ultraexecute-local.md` | The `/ultraexecute-local` slash command — execution orchestration | +| `agents/*.md` | 19 specialized agents for research, exploration, review, and orchestration | | `templates/plan-template.md` | Structured plan output format | +| `templates/research-brief-template.md` | Research brief format with triangulation and confidence | | `templates/spec-template.md` | Spec file format | +| `templates/session-spec-template.md` | Session spec format for headless execution | +| `templates/headless-launch-template.md` | Launch script template | -The command file is the core. All planning logic lives in markdown. +The command files are the core. All logic lives in markdown. ## Testing locally ```bash claude --plugin-dir /path/to/ultraplan-local # Then in the session: +/ultraresearch-local /ultraplan-local +/ultraexecute-local ``` Verify: -- Exploration agents spawn in parallel -- Plan follows the template structure -- Plan file is written to `.claude/plans/` -- Adversarial review runs (plan-critic + scope-guardian) +- `/ultraresearch-local`: Research agents spawn, brief written to `.claude/research/` +- `/ultraplan-local`: Exploration agents spawn in parallel, plan follows template, plan written to `.claude/plans/`, adversarial review runs +- `/ultraexecute-local`: Steps execute with verify + checkpoint per step diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index 76a12ca..8feef99 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -1,17 +1,18 @@ -# ultraplan-local and ultraexecute-local — Plan Deep, Execute Clean +# ultraplan-local — Plan, Research, Execute -![Version](https://img.shields.io/badge/version-1.5.0-blue) +![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 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: +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 | -Plan first, then execute. Or plan and execute in one flow. The plan is the contract between the two. +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**. @@ -21,15 +22,19 @@ No cloud dependency. No GitHub requirement. Works on **Mac, Linux, and Windows** # Install git clone https://git.fromaitochitta.com/open/ultraplan-local.git ~/plugins/ultraplan-local -# Plan +# 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-06-jwt-auth.md +/ultraexecute-local .claude/plans/ultraplan-2026-04-08-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:** @@ -38,16 +43,86 @@ That's it. `/ultraplan-local` interviews you, explores the codebase with 6-8 spe - 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 -- 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. --- +## `/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 ` | Interview + background research (local + external + Gemini) | +| **Quick** | `/ultraresearch-local --quick ` | Interview (short) + inline research, no agent swarm | +| **Local** | `/ultraresearch-local --local ` | Only codebase analysis agents (skip external + Gemini) | +| **External** | `/ultraresearch-local --external ` | Only external research agents (skip codebase analysis) | +| **Foreground** | `/ultraresearch-local --fg ` | 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. @@ -56,7 +131,7 @@ Runs a structured planning workflow that produces an implementation plan detaile 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) +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 @@ -71,11 +146,14 @@ Output: `.claude/plans/ultraplan-{date}-{slug}.md` |------|-------|----------| | **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: @@ -83,7 +161,7 @@ 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) +- **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 @@ -198,29 +276,44 @@ If no API key is set, parallel sessions use your subscription and proceed withou ## 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 │ - └──────────────────────┘ + /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-06-websocket.md +/ultraexecute-local .claude/plans/ultraplan-2026-04-08-websocket.md ``` **Spec-driven headless (CI/automation):** @@ -228,20 +321,20 @@ If no API key is set, parallel sessions use your subscription and proceed withou # 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 +/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-06-login-fix.md +/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-06-auth.md --dry-run +/ultraexecute-local .claude/plans/ultraplan-2026-04-08-auth.md --dry-run # Looks good: -/ultraexecute-local .claude/plans/ultraplan-2026-04-06-auth.md +/ultraexecute-local .claude/plans/ultraplan-2026-04-08-auth.md ``` --- @@ -253,6 +346,7 @@ If no API key is set, parallel sessions use your subscription and proceed withou | 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** | @@ -294,10 +388,12 @@ claude --plugin-dir ~/plugins/ultraplan-local ## 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) -- **Research**: 0-1 Sonnet agent (only when unfamiliar tech detected) +- **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 (planning-orchestrator) +- **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 @@ -308,36 +404,45 @@ The plugin minimizes Opus usage by front-loading cheap Sonnet exploration. - [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.5.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 +│ └── 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) -│ ├── session-spec-template.md # Session spec format for headless execution +│ ├── 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 -├── settings.json # Default plugin configuration +│ └── spec-template.md # Spec file format +├── settings.json # Default plugin configuration ├── CONTRIBUTING.md ├── CHANGELOG.md ├── LICENSE