8e2b868826
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>
5.8 KiB
ultraplan-local
Deep implementation planning and research with interview, specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan.
Design principle: Context Engineering — build the right context by orchestrating specialized agents. Each step in the pipeline (research -> plan -> execute) produces a structured artifact that the next step consumes.
Commands
| Command | Description | Model |
|---|---|---|
/ultraresearch-local |
Research — deep local + external research, produces structured brief | opus |
/ultraplan-local |
Plan — interview, explore, plan, review | opus |
/ultraexecute-local |
Execute — disciplined plan/session-spec executor with failure recovery | opus |
/ultraresearch-local modes
| Flag | Behavior |
|---|---|
| (default) | Interview + background research (local + external) + synthesis + brief |
--quick |
Interview (short) + inline research (no agent swarm) |
--local |
Only codebase analysis agents (skip external + Gemini) |
--external |
Only external research agents (skip codebase analysis) |
--fg |
All phases in foreground (blocking) |
Flags can be combined: --local --fg, --external --quick.
/ultraplan-local modes
| Flag | Behavior |
|---|---|
| (default) | Interview + background planning (non-blocking) |
--spec <path> |
Skip interview, use provided spec |
--research <brief> [brief2] |
Enrich planning with pre-built research brief(s) |
--fg |
All phases in foreground (blocking) |
--quick |
Interview + plan directly (no agent swarm) |
--export <pr|issue|markdown|headless> <plan> |
Generate shareable output from existing plan |
--decompose <plan> |
Split plan into self-contained headless sessions |
--research can combine with --spec, --fg, and --quick.
/ultraexecute-local modes
| Flag | Behavior |
|---|---|
| (default) | Execute plan — auto-detects Execution Strategy for multi-session |
--resume |
Resume from last progress checkpoint |
--dry-run |
Validate plan structure without executing |
--step N |
Execute only step N |
--fg |
Force foreground — run all steps sequentially, ignore Execution Strategy |
--session N |
Execute only session N from plan's Execution Strategy |
Agents
| Agent | Model | Role |
|---|---|---|
| planning-orchestrator | opus | Runs full planning pipeline as background task |
| research-orchestrator | opus | Runs full research pipeline as background task |
| architecture-mapper | sonnet | Codebase structure, tech stack, patterns |
| dependency-tracer | sonnet | Import chains, data flow, side effects |
| task-finder | sonnet | Task-relevant files, functions, reuse candidates |
| risk-assessor | sonnet | Risks, edge cases, failure modes |
| test-strategist | sonnet | Test patterns, coverage gaps, strategy |
| git-historian | sonnet | Recent changes, ownership, hot files |
| research-scout | sonnet | External docs for unfamiliar tech (conditional, planning only) |
| convention-scanner | sonnet | Coding conventions: naming, style, error handling, test patterns |
| spec-reviewer | sonnet | Spec quality check before exploration |
| plan-critic | sonnet | Adversarial plan review (9 dimensions) |
| scope-guardian | sonnet | Scope alignment (creep + gaps) |
| session-decomposer | sonnet | Splits plans into headless sessions with dependency graph |
| docs-researcher | sonnet | Official documentation, RFCs, vendor docs (Tavily, MS Learn) |
| community-researcher | sonnet | Community experience: issues, blogs, discussions |
| security-researcher | sonnet | CVEs, audit history, supply chain risks |
| contrarian-researcher | sonnet | Counter-evidence, overlooked alternatives |
| gemini-bridge | sonnet | Gemini Deep Research second opinion (conditional) |
Architecture
Research: 8-phase workflow: Parse mode -> Interview -> Background transition -> Parallel research (5 local + 4 external + 1 bridge) -> Follow-ups -> Triangulation -> Synthesis + brief -> Stats.
Plan: 12-phase workflow: Parse mode -> Interview -> Background transition -> Codebase sizing -> Spec review -> Parallel exploration (6-8 agents) -> Deep-dives -> Synthesis -> Planning -> Adversarial review -> Present/refine -> Handoff.
Decompose: Parse plan -> Analyze step dependencies -> Group into sessions -> Identify parallel waves -> Generate session specs + dependency graph + launch script.
Execute: Parse plan -> Security scan (Phase 2.4) -> Detect Execution Strategy -> Single-session (step loop) or multi-session (parallel waves via claude -p with scoped --allowedTools) -> Verification -> Report.
Security: 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped --allowedTools replacing --dangerously-skip-permissions. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.
Pipeline: Research briefs feed into planning via --research. The planning orchestrator uses brief context to enrich exploration and skip redundant research.
State
- Research briefs:
.claude/research/ultraresearch-{date}-{slug}.md - Specs:
.claude/ultraplan-spec-{date}-{slug}.md - Plans:
.claude/plans/ultraplan-{date}-{slug}.md - Sessions:
.claude/ultraplan-sessions/{slug}/session-*.md - Launch scripts:
.claude/ultraplan-sessions/{slug}/launch.sh - Progress:
{plan-dir}/.ultraexecute-progress-{slug}.json - Plan stats:
${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl - Exec stats:
${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl - Research stats:
${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl