feat: initial open marketplace with llm-security, config-audit, ultraplan-local
This commit is contained in:
Kjell Tore Guttormsen
commit
f93d6abdae
380 changed files with 65935 additions and 0 deletions
685
plugins/ultraplan-local/commands/ultraplan-local.md
Normal file
685
plugins/ultraplan-local/commands/ultraplan-local.md
Normal file
|
|
@ -0,0 +1,685 @@
|
|||
---
|
||||
name: ultraplan-local
|
||||
description: Deep implementation planning with interview, parallel specialized agents, external research, and optional background execution
|
||||
argument-hint: "[--spec spec.md | --fg] <task description>"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
|
||||
---
|
||||
|
||||
# Ultraplan Local v1.0
|
||||
|
||||
Deep, multi-phase implementation planning. Uses an interview to gather requirements,
|
||||
adaptive specialized agent swarms for exploration, external research for unfamiliar
|
||||
technologies, and adversarial review to stress-test the plan.
|
||||
|
||||
## Phase 1 — Parse mode and validate input
|
||||
|
||||
Parse `$ARGUMENTS` for mode flags:
|
||||
|
||||
1. If arguments start with `--spec `: extract the file path after `--spec`.
|
||||
Set **mode = spec-driven**. Read the spec file. If it does not exist, report
|
||||
the error and stop.
|
||||
|
||||
2. If arguments start with `--fg `: extract the task description after `--fg`.
|
||||
Set **mode = foreground**.
|
||||
|
||||
3. If arguments start with `--quick `: extract the task description after `--quick`.
|
||||
Set **mode = quick**.
|
||||
|
||||
4. If arguments start with `--export `: extract the remainder as `{format} {plan-path}`.
|
||||
Split on the first space: format is the first token, plan path is the rest.
|
||||
Valid formats: `pr`, `issue`, `markdown`, `headless`.
|
||||
Set **mode = export**.
|
||||
|
||||
If the format is not one of pr/issue/markdown/headless, report and stop:
|
||||
```
|
||||
Error: unknown export format '{format}'. Valid: pr, issue, markdown, headless
|
||||
```
|
||||
|
||||
If the plan file does not exist, report and stop:
|
||||
```
|
||||
Error: plan file not found: {path}
|
||||
```
|
||||
|
||||
5. If arguments start with `--decompose `: extract the plan file path after `--decompose`.
|
||||
Set **mode = decompose**.
|
||||
|
||||
If the plan file does not exist, report and stop:
|
||||
```
|
||||
Error: plan file not found: {path}
|
||||
```
|
||||
|
||||
6. Otherwise: the entire argument string is the task description.
|
||||
Set **mode = default**.
|
||||
|
||||
If no task description and no spec file, output usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraplan-local <task description>
|
||||
/ultraplan-local --spec <path-to-spec.md>
|
||||
/ultraplan-local --fg <task description>
|
||||
/ultraplan-local --quick <task description>
|
||||
/ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
|
||||
/ultraplan-local --decompose <plan-path>
|
||||
|
||||
Modes:
|
||||
default Interview (interactive) → background planning → notify when done
|
||||
--spec Skip interview, use provided spec → background planning
|
||||
--fg All phases in foreground (blocks session)
|
||||
--quick Interview → plan directly (no agent swarm) → adversarial review
|
||||
--export Generate shareable output from an existing plan (no new planning)
|
||||
--decompose Split an existing plan into self-contained headless sessions
|
||||
|
||||
Examples:
|
||||
/ultraplan-local Add user authentication with JWT tokens
|
||||
/ultraplan-local --spec .claude/ultraplan-spec-2026-04-05-jwt-auth.md
|
||||
/ultraplan-local --fg Refactor the database layer to use connection pooling
|
||||
/ultraplan-local --quick Add rate limiting to the API
|
||||
/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
/ultraplan-local --export headless .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
/ultraplan-local --decompose .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
```
|
||||
|
||||
Do not continue past this step if no task was provided.
|
||||
|
||||
Report the detected mode to the user:
|
||||
```
|
||||
Mode: {default | spec-driven | foreground}
|
||||
Task: {task description or "from spec: {path}"}
|
||||
```
|
||||
|
||||
## Phase 1.5 — Export (runs only when mode = export)
|
||||
|
||||
**Skip this phase entirely unless mode = export.**
|
||||
|
||||
Read the plan file. Extract these sections from the plan content:
|
||||
- Task description (from Context section)
|
||||
- Implementation steps (from Implementation Plan section)
|
||||
- Risks (from Risks and Mitigations section)
|
||||
- Test strategy (from Test Strategy section, if present)
|
||||
- Scope estimate (from Estimated Scope section)
|
||||
|
||||
### Format: `pr`
|
||||
|
||||
Output a markdown block formatted as a PR description:
|
||||
|
||||
```
|
||||
## Summary
|
||||
|
||||
{2–3 sentence summary of what this change does and why}
|
||||
|
||||
## Changes
|
||||
|
||||
{Bulleted list of implementation steps, one line each}
|
||||
|
||||
## Test plan
|
||||
|
||||
{Bulleted checklist from test strategy, formatted as - [ ] items}
|
||||
|
||||
## Risks
|
||||
|
||||
{Risks from plan, abbreviated to 1 line each}
|
||||
|
||||
---
|
||||
*Generated by ultraplan-local from {plan filename}*
|
||||
```
|
||||
|
||||
### Format: `issue`
|
||||
|
||||
Output a markdown block formatted as an issue comment:
|
||||
|
||||
```
|
||||
## Implementation plan summary
|
||||
|
||||
**Task:** {task description}
|
||||
**Plan file:** {plan path}
|
||||
**Scope:** {N files, complexity}
|
||||
|
||||
### Proposed approach
|
||||
{3–5 bullet points from key implementation steps}
|
||||
|
||||
### Open questions / risks
|
||||
{Top 2–3 risks from plan}
|
||||
|
||||
---
|
||||
*Generated by ultraplan-local*
|
||||
```
|
||||
|
||||
### Format: `markdown`
|
||||
|
||||
Output the plan content with internal metadata stripped:
|
||||
- Remove the "Revisions" section
|
||||
- Remove plan-critic and scope-guardian scores/verdicts
|
||||
- Remove `[ASSUMPTION]` markers (but keep the surrounding sentence)
|
||||
- Keep everything else verbatim
|
||||
|
||||
### Format: `headless`
|
||||
|
||||
This is a shortcut for `--decompose`. It runs the full session decomposition
|
||||
pipeline and is equivalent to `--decompose {plan-path}`. Proceed to
|
||||
Phase 1.6 (Decompose) below.
|
||||
|
||||
---
|
||||
|
||||
After outputting the formatted block (for pr/issue/markdown), say:
|
||||
```
|
||||
Export complete ({format}). Copy the block above.
|
||||
```
|
||||
|
||||
Then **stop**. Do not continue to Phase 2 or any subsequent phase.
|
||||
|
||||
## Phase 1.6 — Decompose (runs only when mode = decompose or export headless)
|
||||
|
||||
**Skip this phase entirely unless mode = decompose or export format = headless.**
|
||||
|
||||
Read the plan file. Verify it contains an Implementation Plan section with
|
||||
numbered steps. If no steps are found, report and stop:
|
||||
```
|
||||
Error: plan has no implementation steps. Run /ultraplan-local first to generate a plan.
|
||||
```
|
||||
|
||||
Determine the output directory from the plan slug:
|
||||
- Extract the slug from the plan filename (e.g., `ultraplan-2026-04-06-auth-refactor` → `auth-refactor`)
|
||||
- Output directory: `.claude/ultraplan-sessions/{slug}/`
|
||||
|
||||
Launch the **session-decomposer** agent:
|
||||
|
||||
```
|
||||
Plan file: {plan path}
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
Output directory: .claude/ultraplan-sessions/{slug}/
|
||||
```
|
||||
|
||||
The session-decomposer will:
|
||||
1. Parse the plan's steps and their file dependencies
|
||||
2. Build a dependency graph between steps
|
||||
3. Group steps into sessions of 3–5 steps each
|
||||
4. Identify which sessions can run in parallel (waves)
|
||||
5. Generate one session spec file per session
|
||||
6. Generate a dependency diagram (mermaid)
|
||||
7. Generate a launch script (`launch.sh`)
|
||||
|
||||
When the session-decomposer completes, present the summary to the user:
|
||||
|
||||
```
|
||||
## Decomposition Complete
|
||||
|
||||
**Master plan:** {plan path}
|
||||
**Sessions:** {N} across {W} waves
|
||||
**Output:** .claude/ultraplan-sessions/{slug}/
|
||||
|
||||
### Sessions
|
||||
|
||||
| # | Title | Steps | Wave | Parallel |
|
||||
|---|-------|-------|------|----------|
|
||||
{session table from decomposer}
|
||||
|
||||
### Files generated
|
||||
|
||||
- Session specs: .claude/ultraplan-sessions/{slug}/session-*.md
|
||||
- Dependency graph: .claude/ultraplan-sessions/{slug}/dependency-graph.md
|
||||
- Launch script: .claude/ultraplan-sessions/{slug}/launch.sh
|
||||
|
||||
You can:
|
||||
- Review individual session specs before running
|
||||
- Run all sessions: `bash .claude/ultraplan-sessions/{slug}/launch.sh`
|
||||
- Run a single session: `claude -p "$(cat .claude/ultraplan-sessions/{slug}/session-1-*.md)"`
|
||||
- Say **"launch"** to start headless execution from here
|
||||
```
|
||||
|
||||
If the user says **"launch"**: run the launch script via Bash.
|
||||
|
||||
Then **stop**. Do not continue to Phase 2 or any subsequent phase.
|
||||
|
||||
## Phase 2 — Requirements gathering (interview)
|
||||
|
||||
**Skip this phase entirely if mode = spec-driven.** Proceed to Phase 3.
|
||||
|
||||
Use `AskUserQuestion` to interview the user about the task. Ask **one question at
|
||||
a time** — never dump all questions at once. Follow up based on answers.
|
||||
|
||||
### Interview flow
|
||||
|
||||
**Start with the most important question:**
|
||||
> What is the goal of this task? What does success look like?
|
||||
|
||||
**Then ask follow-ups based on the answer. Choose from these topics:**
|
||||
- What is explicitly NOT in scope? (non-goals)
|
||||
- Are there technical constraints? (specific versions, compatibility, no new dependencies)
|
||||
- Do you have preferences? (library X over Y, specific patterns, architectural style)
|
||||
- Are there non-functional requirements? (performance targets, security needs, accessibility)
|
||||
- Has anything been tried before? What worked or failed?
|
||||
|
||||
**Rules:**
|
||||
- Ask 3–5 questions for typical tasks. Maximum 8 for complex tasks.
|
||||
- If the user says "skip", "proceed", "just plan it", or similar — stop interviewing
|
||||
immediately. Write a minimal spec from the task description alone.
|
||||
- Adapt your questions to what the user tells you. If they give a detailed task
|
||||
description, skip obvious questions.
|
||||
- Never ask about things you can discover from the codebase.
|
||||
|
||||
### Adaptive depth
|
||||
|
||||
After each answer, assess the response length and vocabulary:
|
||||
|
||||
- **Detailed answer** (2+ sentences, technical terminology, specific examples):
|
||||
- Treat the user as senior — they know the codebase
|
||||
- Skip obvious follow-ups they already answered
|
||||
- Ask more targeted questions: constraints, edge cases, specific technical choices
|
||||
- Reduce question count: aim for 3–4 total instead of 5
|
||||
|
||||
- **Short or uncertain answer** (1 sentence or less, "I don't know", "not sure", vague):
|
||||
- Treat the user as unfamiliar with the problem space
|
||||
- Simplify follow-up questions — avoid open-ended technical questions
|
||||
- Offer alternatives instead of asking open questions:
|
||||
> "Should this be synchronous or asynchronous? (synchronous is simpler; async handles more concurrent users)"
|
||||
- For bugs: focus on reproduction before requirements:
|
||||
> "What do you see? What did you expect to see?"
|
||||
- Allow "I don't know" as a valid answer — record it as an open assumption in the spec
|
||||
|
||||
Never change your question count based on impatience. Only change depth based
|
||||
on answer quality.
|
||||
|
||||
### Write the spec file
|
||||
|
||||
After gathering requirements, read the spec template:
|
||||
@${CLAUDE_PLUGIN_ROOT}/templates/spec-template.md
|
||||
|
||||
Generate a slug from the task (first 3-4 meaningful words, lowercase, hyphens).
|
||||
Write the spec to: `.claude/ultraplan-spec-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Create the `.claude/` directory if it does not exist.
|
||||
|
||||
Fill in all sections based on interview answers. Mark unanswered sections with
|
||||
"Not discussed — no constraints assumed."
|
||||
|
||||
Tell the user:
|
||||
```
|
||||
Spec saved: .claude/ultraplan-spec-{date}-{slug}.md
|
||||
```
|
||||
|
||||
## Phase 3 — Background transition
|
||||
|
||||
**If mode = foreground or quick:** Skip this phase. Continue to Phase 4 inline.
|
||||
|
||||
**If mode = default or spec-driven:**
|
||||
|
||||
Launch the **planning-orchestrator** agent with this prompt:
|
||||
|
||||
```
|
||||
Spec file: {spec path}
|
||||
Task: {task description}
|
||||
Mode: {default | spec | quick}
|
||||
Plan destination: .claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
|
||||
Read the spec file and execute your full planning workflow.
|
||||
Write the plan to the destination path.
|
||||
```
|
||||
|
||||
Launch the planning-orchestrator via the Agent tool with `run_in_background: true`.
|
||||
The agent runs autonomously while you continue working — you will be notified
|
||||
when the plan is ready.
|
||||
|
||||
Then output to the user and **stop your response**:
|
||||
```
|
||||
Background planning started via planning-orchestrator.
|
||||
|
||||
Spec: .claude/ultraplan-spec-{date}-{slug}.md
|
||||
Plan: .claude/plans/ultraplan-{date}-{slug}.md
|
||||
|
||||
You will be notified when the plan is ready.
|
||||
You can continue working on other tasks in the meantime.
|
||||
```
|
||||
|
||||
Do not wait for the orchestrator. Do not continue to Phase 4.
|
||||
The planning-orchestrator handles Phases 4 through 10 autonomously.
|
||||
|
||||
---
|
||||
|
||||
**Everything below this line runs either in foreground mode or inside the
|
||||
background agent. The instructions are identical regardless of context.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Codebase sizing
|
||||
|
||||
Determine codebase scale to calibrate agent turns (not agent count).
|
||||
|
||||
Run via Bash:
|
||||
```
|
||||
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.c" -o -name "*.cpp" -o -name "*.h" -o -name "*.cs" -o -name "*.swift" -o -name "*.kt" -o -name "*.sh" -o -name "*.md" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/dist/*" -not -path "*/build/*" | wc -l
|
||||
```
|
||||
|
||||
Classify:
|
||||
- **Small** (< 50 files)
|
||||
- **Medium** (50–500 files)
|
||||
- **Large** (> 500 files)
|
||||
|
||||
Report:
|
||||
```
|
||||
Codebase: {N} source files ({scale}). Deploying exploration agents.
|
||||
```
|
||||
|
||||
## Phase 4b — Spec review
|
||||
|
||||
Launch the **spec-reviewer** agent:
|
||||
Prompt: "Review this spec for quality: {spec path}. Check completeness, consistency,
|
||||
testability, and scope clarity."
|
||||
|
||||
Handle the verdict:
|
||||
- **PROCEED** — continue to Phase 5.
|
||||
- **PROCEED_WITH_RISKS** — continue, carry flagged risks as `[ASSUMPTION]` in the plan.
|
||||
- **REVISE** — in foreground mode, present findings and ask the user for clarification.
|
||||
In background mode, carry all findings as `[ASSUMPTION]` entries.
|
||||
|
||||
## Phase 5 — Parallel exploration (specialized agents + research)
|
||||
|
||||
**If mode = quick:** Do NOT launch any exploration agents. Instead, run a
|
||||
lightweight file check:
|
||||
- `Glob` for files matching key terms from the task description (up to 3 patterns)
|
||||
- `Grep` for function/type definitions matching key terms (up to 3 patterns)
|
||||
|
||||
Report findings as:
|
||||
```
|
||||
Quick scan: {N} potentially relevant files found via Glob/Grep.
|
||||
No agent swarm — proceeding directly to planning.
|
||||
```
|
||||
|
||||
Then skip Phase 6 (deep-dives) and proceed to Phase 7 (Synthesis) with only
|
||||
the quick-scan results.
|
||||
|
||||
---
|
||||
|
||||
**All other modes:** Launch exploration agents **in parallel** (all in a single
|
||||
message). Use the specialized agents from the `agents/` directory.
|
||||
|
||||
**All agents run for all codebase sizes.** Scale `maxTurns` by size (small: halved,
|
||||
medium: default, large: default) instead of dropping agents.
|
||||
|
||||
| Agent | Small | Medium | Large | Purpose |
|
||||
|-------|-------|--------|-------|---------|
|
||||
| `architecture-mapper` | Yes | Yes | Yes | Codebase structure, patterns, anti-patterns |
|
||||
| `dependency-tracer` | Yes | Yes | Yes | Module connections, data flow, side effects |
|
||||
| `risk-assessor` | Yes | Yes | Yes | Risks, edge cases, failure modes |
|
||||
| `task-finder` | Yes | Yes | Yes | Task-relevant files, functions, types, reuse candidates |
|
||||
| `test-strategist` | Yes | Yes | Yes | Test patterns, coverage gaps, strategy |
|
||||
| `git-historian` | Yes | Yes | Yes | Recent changes, ownership, hot files, active branches |
|
||||
| `research-scout` | Conditional | Conditional | Conditional | External docs (only when unfamiliar tech detected) |
|
||||
| `convention-scanner` | No | Yes | Yes | Coding conventions, naming, style, test patterns |
|
||||
|
||||
### Always launch (all codebase sizes):
|
||||
|
||||
**architecture-mapper** — full codebase structure, tech stack, patterns, anti-patterns.
|
||||
Prompt: "Analyze the architecture of this codebase. The task being planned is: {task}"
|
||||
|
||||
**dependency-tracer** — module connections, data flow, side effects for task-relevant code.
|
||||
Prompt: "Trace dependencies and data flow relevant to this task: {task}. Focus on modules
|
||||
that will be affected by the implementation."
|
||||
|
||||
**risk-assessor** — risks, edge cases, failure modes, technical debt near task area.
|
||||
Prompt: "Assess risks and failure modes for implementing this task: {task}. Check for
|
||||
complexity hotspots, security boundaries, and technical debt in the relevant code."
|
||||
|
||||
**task-finder** — all files, functions, types, and interfaces directly related to the task.
|
||||
Prompt: "Find all code relevant to this task: {task}. Include existing implementations
|
||||
that solve similar problems, API boundaries, database models, configuration files.
|
||||
Report file paths and line numbers for every finding."
|
||||
|
||||
**test-strategist** — existing test patterns, coverage gaps, test strategy.
|
||||
Prompt: "Analyze the test infrastructure and design a test strategy for this task: {task}.
|
||||
Discover existing patterns and identify coverage gaps."
|
||||
|
||||
**git-historian** — recent changes, code ownership, hot files, active branches.
|
||||
Prompt: "Analyze git history relevant to this task: {task}. Report recent changes,
|
||||
ownership, hot files, and active branches that may affect planning."
|
||||
|
||||
### Launch for medium+ codebases (50+ files):
|
||||
|
||||
**Convention Scanner** — use the `convention-scanner` plugin agent (model: "sonnet")
|
||||
for medium+ codebases only.
|
||||
Provide concrete examples from the codebase, not generic advice."
|
||||
|
||||
### Conditional: External research
|
||||
|
||||
After reading the task description and spec (if available), determine if the task
|
||||
involves technologies, APIs, or libraries that are:
|
||||
- Not clearly present in the codebase
|
||||
- Being upgraded to a new major version
|
||||
- Being used in an unfamiliar way
|
||||
|
||||
If yes: launch **research-scout** in parallel with the other agents.
|
||||
Prompt: "Research the following technologies for this task: {task}.
|
||||
Specific questions: {list specific questions about the technology}.
|
||||
Technologies to research: {list}."
|
||||
|
||||
If no external technology is involved: skip research-scout and note:
|
||||
"No external research needed — all technologies are well-represented in the codebase."
|
||||
|
||||
## Phase 6 — Targeted deep-dives
|
||||
|
||||
After all Phase 5 agents complete, review their results and identify **knowledge gaps**
|
||||
— areas where exploration was too shallow to plan confidently.
|
||||
|
||||
Common reasons for deep-dives:
|
||||
- A critical function was found but its implementation details are unclear
|
||||
- A dependency chain needs tracing to understand side effects
|
||||
- A test pattern was identified but the test infrastructure needs more detail
|
||||
- A risk was flagged but the actual impact needs verification
|
||||
|
||||
For each significant gap, spawn a targeted deep-dive agent (model: "sonnet",
|
||||
subagent_type: "Explore") with a narrow, specific brief.
|
||||
|
||||
Launch up to 3 deep-dive agents in parallel. If no gaps exist, skip this phase
|
||||
and note: "Initial exploration was sufficient — no deep-dives needed."
|
||||
|
||||
## Phase 7 — Synthesis
|
||||
|
||||
After all agents complete (initial + deep-dives + research), synthesize:
|
||||
|
||||
1. Read all agent results carefully
|
||||
2. Identify overlaps and contradictions between agents
|
||||
3. Build a mental model of the codebase architecture
|
||||
4. Catalog reusable code: existing functions, utilities, patterns
|
||||
5. Integrate research findings with codebase analysis
|
||||
6. Note remaining gaps — things you cannot determine from code or research
|
||||
(these become assumptions in the plan, marked explicitly)
|
||||
7. For each finding, track whether it came from **codebase analysis** or
|
||||
**external research** — the plan must distinguish these sources
|
||||
|
||||
Do NOT write this synthesis to disk. It is internal working context only.
|
||||
|
||||
## Phase 8 — Deep planning
|
||||
|
||||
Read the spec file (from Phase 2 or provided via --spec).
|
||||
Read the plan template: @${CLAUDE_PLUGIN_ROOT}/templates/plan-template.md
|
||||
|
||||
Write the plan following the template structure. The plan MUST include:
|
||||
|
||||
### Required sections
|
||||
|
||||
1. **Context** — Why this change is needed. Reference the spec's goal and constraints.
|
||||
2. **Codebase Analysis** — Tech stack, patterns, relevant files, reusable code,
|
||||
external tech researched. Every file path must be real (verified during exploration).
|
||||
3. **Research Sources** — If research-scout was used: table of technologies, sources,
|
||||
findings, and confidence levels. Omit if no research was conducted.
|
||||
4. **Implementation Plan** — Ordered steps. Each step specifies:
|
||||
- Exact files to modify or create (with paths)
|
||||
- What changes to make and why
|
||||
- Which existing code to reuse
|
||||
- Dependencies on other steps
|
||||
- Whether the step is based on codebase analysis or external research
|
||||
- **On failure:** — recovery action (revert/retry/skip/escalate)
|
||||
- **Checkpoint:** — git commit command after success
|
||||
10. **Execution Strategy** — For plans with > 5 steps: group steps into sessions
|
||||
(3–5 steps each), organize sessions into waves (parallel where independent),
|
||||
specify scope fences per session. Omit for plans with ≤ 5 steps.
|
||||
5. **Alternatives Considered** — At least one alternative approach with
|
||||
pros/cons and reason for rejection.
|
||||
6. **Risks and Mitigations** — From the risk-assessor findings. What could go
|
||||
wrong and how to handle it.
|
||||
7. **Test Strategy** — From the test-strategist findings (if available).
|
||||
What tests to write and which patterns to follow.
|
||||
8. **Verification** — Testable criteria. Not "check that it works" but
|
||||
specific commands to run and expected outputs.
|
||||
9. **Estimated Scope** — File counts and complexity rating.
|
||||
|
||||
### Quality standards
|
||||
|
||||
- Every file path in the plan must exist in the codebase (or be explicitly
|
||||
marked as "new file to create")
|
||||
- Every "reuses" reference must point to a real function/pattern found during
|
||||
exploration
|
||||
- Steps must be ordered by dependency (not by file path or importance)
|
||||
- Verification criteria must be concrete and executable
|
||||
- The plan must be implementable by someone who has not seen the exploration
|
||||
results — it must stand on its own
|
||||
- Research-based decisions must cite their source
|
||||
|
||||
### Write the plan
|
||||
|
||||
Generate the slug from the task description (or reuse the spec slug).
|
||||
Write the plan to: `.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`
|
||||
Create the `.claude/plans/` directory if it does not exist.
|
||||
|
||||
## Phase 9 — Adversarial review
|
||||
|
||||
Launch two review agents **in parallel**:
|
||||
|
||||
**plan-critic** — adversarial review of the plan.
|
||||
Prompt: "Review this implementation plan for the task: {task}.
|
||||
Plan file: {plan path}. Read it and find every problem — missing steps,
|
||||
wrong ordering, fragile assumptions, missing error handling, scope creep,
|
||||
underspecified steps. Rate each finding as blocker, major, or minor."
|
||||
|
||||
**scope-guardian** — scope alignment check.
|
||||
Prompt: "Check this implementation plan against the requirements.
|
||||
Task: {task}. Spec file: {spec path}. Plan file: {plan path}.
|
||||
Find scope creep (plan does more than asked) and scope gaps (plan misses
|
||||
requirements). Check that referenced files and functions exist."
|
||||
|
||||
After both complete:
|
||||
- If **blockers** are found: revise the plan to address them. Add a "Revisions"
|
||||
note at the bottom of the plan listing what changed and why.
|
||||
- If only **major** issues: revise to address them. Add revisions note.
|
||||
- If only **minor** issues or clean: proceed without changes. Note the
|
||||
review result in the plan.
|
||||
|
||||
## Phase 10 — Present and refine
|
||||
|
||||
Present a summary to the user:
|
||||
|
||||
```
|
||||
## Ultraplan Complete
|
||||
|
||||
**Task:** {task description}
|
||||
**Mode:** {default | spec-driven | foreground}
|
||||
**Spec:** {spec file path, or "none (foreground mode)"}
|
||||
**Plan:** .claude/plans/ultraplan-{date}-{slug}.md
|
||||
**Exploration:** {N} agents deployed ({N} specialized + {N} deep-dives + {research status})
|
||||
**Scope:** {N} files to modify, {N} to create — {complexity}
|
||||
|
||||
### Key decisions
|
||||
- {Decision 1 and rationale}
|
||||
- {Decision 2 and rationale}
|
||||
|
||||
### Implementation steps ({N} total)
|
||||
1. {Step 1 summary}
|
||||
2. {Step 2 summary}
|
||||
...
|
||||
|
||||
### Research findings
|
||||
{Summary of external research, or "No external research conducted."}
|
||||
|
||||
### Adversarial review
|
||||
**Plan critic:** {Summary — blockers/majors/minors found, how addressed}
|
||||
**Scope guardian:** {Summary — creep/gaps found, how addressed}
|
||||
|
||||
You can:
|
||||
- Ask questions or request changes to refine the plan
|
||||
- Say **"execute"** to start implementing
|
||||
- Say **"execute with team"** to implement with parallel Agent Team (if eligible)
|
||||
- Say **"save"** to keep the plan for later
|
||||
```
|
||||
|
||||
If the user asks questions or requests changes:
|
||||
- Update the plan file in-place
|
||||
- Show what changed
|
||||
- Re-present the summary
|
||||
|
||||
## Phase 11 — Handoff
|
||||
|
||||
### "save" / "later" / "done"
|
||||
|
||||
Confirm the plan and spec file locations and exit.
|
||||
|
||||
### "execute" / "go" / "start"
|
||||
|
||||
Begin implementing the plan step by step in this session. Follow the plan exactly.
|
||||
Mark each step complete as you go.
|
||||
|
||||
### "execute with team" / "team"
|
||||
|
||||
Before creating a team, verify eligibility:
|
||||
1. Count implementation steps that are **independent** (no dependency on each other)
|
||||
AND touch **different files/modules**
|
||||
2. If fewer than 3 independent steps: inform the user and fall back to sequential
|
||||
execution. "The plan has fewer than 3 independent steps — sequential execution
|
||||
is more efficient."
|
||||
|
||||
If eligible:
|
||||
1. Present the proposed team split: which steps go to which team member
|
||||
2. Ask for confirmation: "Create Agent Team with {N} members? (yes/no)"
|
||||
3. If confirmed: create the team with `TeamCreate`, assign step clusters to
|
||||
each member. Use `isolation: "worktree"` on each team member agent so they
|
||||
work in isolated git worktrees — this prevents file conflicts during parallel
|
||||
implementation. Coordinate execution and clean up with `TeamDelete` when done.
|
||||
4. If `TeamCreate` fails (tool not available): fall back to sequential execution
|
||||
and notify the user
|
||||
|
||||
## Phase 12 — Session tracking
|
||||
|
||||
After the plan is presented (Phase 10) or after handoff (Phase 11), write a
|
||||
session record to `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl` (create the file
|
||||
if it does not exist).
|
||||
|
||||
Record format (one JSON line):
|
||||
```json
|
||||
{
|
||||
"ts": "{ISO-8601 timestamp}",
|
||||
"task": "{task description (first 100 chars)}",
|
||||
"mode": "{default|spec|fg}",
|
||||
"slug": "{plan slug}",
|
||||
"codebase_size": "{small|medium|large}",
|
||||
"codebase_files": {N},
|
||||
"agents_deployed": {N},
|
||||
"deep_dives": {N},
|
||||
"research": {true|false},
|
||||
"critic_verdict": "{BLOCK|REVISE|PASS}",
|
||||
"guardian_verdict": "{ALIGNED|CREEP|GAP|MIXED}",
|
||||
"outcome": "{execute|execute_team|save|refine}"
|
||||
}
|
||||
```
|
||||
|
||||
If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
|
||||
Never let tracking failures block the main workflow.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **Scope**: Only explore the current working directory and its subdirectories.
|
||||
Never read files outside the repo (no ~/.env, no credentials, no other repos).
|
||||
- **Cost**: Sonnet for all agents (exploration, deep-dives, research, critics).
|
||||
Opus only runs in the main thread for synthesis and planning.
|
||||
- **Privacy**: Never log, store, or repeat file contents that look like
|
||||
secrets, tokens, or credentials. Never log prompt text.
|
||||
- **No premature execution**: Do not modify any project files until the user
|
||||
explicitly approves the plan.
|
||||
- **Plan stands alone**: The plan file must be understandable without access
|
||||
to the exploration results. Include all necessary context.
|
||||
- **Honesty**: If exploration reveals the task is trivial (single file, obvious
|
||||
change), say so. Do not inflate the plan to justify the process. Suggest
|
||||
the user just implements it directly.
|
||||
- **Adaptive**: Never spawn more agents than the codebase warrants. A 10-file
|
||||
project does not need 7 exploration agents. Scale down.
|
||||
- **Research transparency**: Always distinguish codebase-derived decisions from
|
||||
research-derived decisions in the plan.
|
||||
Loading…
Add table
Add a link
Reference in a new issue