feat(ultraplan-local)!: v2.0.0 — brief-driven four-command pipeline
Extract interview from /ultraplan-local into new /ultrabrief-local command.
/ultraplan-local now requires --brief or --project (breaking). All pipeline
artifacts land in one project directory: .claude/projects/{date}-{slug}/
with brief.md, research/, plan.md, sessions/, progress.json.
Breaking changes:
- /ultraplan-local requires --brief <path> or --project <dir>
- /ultraplan-local --spec removed (convert specs to briefs per MIGRATION.md)
- Interview phase moved to /ultrabrief-local
- spec-reviewer renamed to brief-reviewer with 5th dimension (Research Plan validity)
Added:
- /ultrabrief-local command (interactive interview → brief.md with research plan)
- templates/ultrabrief-template.md (task brief format with intent + research plan)
- brief-reviewer agent (5-dimension brief quality review)
- --project <dir> flag on /ultraresearch-local, /ultraplan-local, /ultraexecute-local
- MIGRATION.md (v1 → v2 upgrade guide)
Changed:
- planning-orchestrator accepts Brief file: input (was Spec file:)
- planning-orchestrator Phase 1b uses brief-reviewer
- README + CLAUDE.md rewritten for four-command pipeline and task/research brief terminology
- CHANGELOG.md [2.0.0] entry with rationale
- Marketplace root README + CLAUDE.md updated to v2.0.0
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
fb9eb79d17
commit
2bc405e14a
15 changed files with 1799 additions and 592 deletions
|
|
@ -1,114 +1,151 @@
|
|||
---
|
||||
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>"
|
||||
description: Deep implementation planning from a task brief. Requires --brief or --project. Runs parallel specialized agents, optional external research, and adversarial review.
|
||||
argument-hint: "--brief <path> | --project <dir> [--fg | --quick | --research <brief> | --decompose <plan> | --export <fmt> <plan>]"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
|
||||
---
|
||||
|
||||
# Ultraplan Local v1.0
|
||||
# Ultraplan Local v2.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.
|
||||
Deep, multi-phase implementation planning driven by a **task brief**.
|
||||
Planning consumes the brief (produced by `/ultrabrief-local`) and any
|
||||
research briefs referenced in it, then runs specialized exploration
|
||||
agents, synthesis, and adversarial review to produce an executable plan.
|
||||
|
||||
**v2.0 is a breaking release.** The interview phase has been extracted
|
||||
into `/ultrabrief-local`. This command no longer accepts free-text task
|
||||
descriptions — it requires either `--brief <path>` or `--project <dir>`.
|
||||
|
||||
Pipeline position:
|
||||
|
||||
```
|
||||
/ultrabrief-local → brief.md
|
||||
/ultraresearch-local → research/*.md
|
||||
/ultraplan-local → plan.md (this command)
|
||||
/ultraexecute-local → execution
|
||||
```
|
||||
|
||||
## Phase 1 — Parse mode and validate input
|
||||
|
||||
Parse `$ARGUMENTS` for mode flags:
|
||||
Parse `$ARGUMENTS` for mode flags. Order of precedence:
|
||||
|
||||
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.
|
||||
1. **`--export <format> <plan-path>`** — extract `{format}` (first token after
|
||||
`--export`) and `{plan-path}` (remainder). Valid formats: `pr`, `issue`,
|
||||
`markdown`, `headless`. Set **mode = export**.
|
||||
|
||||
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:
|
||||
If format is not in the valid set:
|
||||
```
|
||||
Error: unknown export format '{format}'. Valid: pr, issue, markdown, headless
|
||||
```
|
||||
|
||||
If the plan file does not exist, report and stop:
|
||||
If the plan file does not exist:
|
||||
```
|
||||
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:
|
||||
2. **`--decompose <plan-path>`** — extract the plan path. Set **mode = decompose**.
|
||||
If the plan file does not exist:
|
||||
```
|
||||
Error: plan file not found: {path}
|
||||
```
|
||||
|
||||
6. If arguments contain `--research `: extract file path(s) after `--research`.
|
||||
Collect paths until encountering another `--` flag or a token that does not
|
||||
look like a file path (no `/` or `.md` extension). Maximum 3 briefs.
|
||||
Set **has_research_brief = true**. Validate each path exists — if any is
|
||||
missing, report and stop:
|
||||
3. **`--project <dir>`** — extract the project directory path.
|
||||
- Resolve `{dir}` (trim trailing slash).
|
||||
- Derive implicit flags:
|
||||
- `--brief {dir}/brief.md`
|
||||
- Plan destination: `{dir}/plan.md`
|
||||
- Research briefs auto-discovered from `{dir}/research/*.md` (sorted).
|
||||
- If `{dir}` does not exist or `{dir}/brief.md` is missing:
|
||||
```
|
||||
Error: project directory not initialized. Run /ultrabrief-local to create it.
|
||||
Missing: {dir}/brief.md
|
||||
```
|
||||
- Set **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
|
||||
- Set **has_research_brief = true** if `{dir}/research/*.md` matches ≥ 1 file.
|
||||
|
||||
4. **`--brief <path>`** — extract the brief path. If the file does not exist:
|
||||
```
|
||||
Error: brief file not found: {path}
|
||||
```
|
||||
Set **brief_path = {path}**. Plan destination will be derived in Phase 3
|
||||
from the brief's slug and date (see Phase 3).
|
||||
|
||||
5. **`--research <brief.md> [brief2.md] [brief3.md]`** — collect paths after
|
||||
`--research` until the next `--` flag or a token that does not look like a
|
||||
file path. Maximum 3 briefs. Set **has_research_brief = true**. Validate
|
||||
each path exists — if any is missing:
|
||||
```
|
||||
Error: research brief not found: {path}
|
||||
```
|
||||
The `--research` flag can combine with other flags:
|
||||
- `--research brief.md <task>` — default mode with research brief
|
||||
- `--research brief.md --fg <task>` — foreground with research brief
|
||||
- `--research brief.md --spec spec.md` — spec-driven with research brief
|
||||
Remove `--research` and its paths from the argument string before
|
||||
applying the other flag checks above.
|
||||
`--research` combines with `--brief`, `--project`, `--fg`, and `--quick`.
|
||||
When combined with `--project`, the explicit `--research` briefs are
|
||||
appended to the auto-discovered ones (deduplicated by path).
|
||||
|
||||
7. Otherwise: the entire argument string is the task description.
|
||||
Set **mode = default**.
|
||||
6. **`--fg`** — set **mode = foreground**. All phases run in this session
|
||||
(no background handoff).
|
||||
|
||||
If no task description and no spec file, output usage and stop:
|
||||
7. **`--quick`** — set **mode = quick**. Skip agent swarm; use lightweight
|
||||
Glob/Grep scan and go directly to planning + adversarial review.
|
||||
|
||||
8. If neither `--brief` nor `--project` is present after flag parsing,
|
||||
output usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraplan-local <task description>
|
||||
/ultraplan-local --spec <path-to-spec.md>
|
||||
/ultraplan-local --research <brief.md> [brief2.md] <task description>
|
||||
/ultraplan-local --fg <task description>
|
||||
/ultraplan-local --quick <task description>
|
||||
Usage: /ultraplan-local --brief <path-to-brief.md>
|
||||
/ultraplan-local --project <project-dir>
|
||||
/ultraplan-local --brief <path> --research <research-brief.md>
|
||||
/ultraplan-local --project <dir> --fg
|
||||
/ultraplan-local --project <dir> --quick
|
||||
/ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
|
||||
/ultraplan-local --decompose <plan-path>
|
||||
|
||||
A brief is required. Produce one with /ultrabrief-local first.
|
||||
|
||||
Modes:
|
||||
default Interview (interactive) → background planning → notify when done
|
||||
--spec Skip interview, use provided spec → background planning
|
||||
--research Enrich planning with pre-built research brief(s) (up to 3)
|
||||
--brief Plan from a brief file (background unless --fg)
|
||||
--project Plan from a project directory (brief.md + research/ auto-resolved)
|
||||
--research Add up to 3 extra research briefs as planning context
|
||||
--fg All phases in foreground (blocks session)
|
||||
--quick Interview → plan directly (no agent swarm) → adversarial review
|
||||
--quick Skip exploration agent swarm; plan directly
|
||||
--export Generate shareable output from an existing plan (no new planning)
|
||||
--decompose Split an existing plan into self-contained headless sessions
|
||||
|
||||
--research can combine with other flags:
|
||||
--research brief.md <task> Default mode + research context
|
||||
--research brief.md --fg <task> Foreground + research context
|
||||
--research brief.md --spec spec.md Spec-driven + research context
|
||||
|
||||
Examples:
|
||||
/ultraplan-local Add user authentication with JWT tokens
|
||||
/ultraplan-local --spec .claude/ultraplan-spec-2026-04-05-jwt-auth.md
|
||||
/ultraplan-local --research .claude/research/ultraresearch-2026-04-08-oauth2.md Implement OAuth2 auth
|
||||
/ultraplan-local --fg Refactor the database layer to use connection pooling
|
||||
/ultraplan-local --quick Add rate limiting to the API
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/brief.md
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --research extra.md
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --fg
|
||||
/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
|
||||
|
||||
Migrating from v1.x? See MIGRATION.md in this plugin. The old --spec flag
|
||||
and free-text interview mode were removed in v2.0.
|
||||
```
|
||||
|
||||
Do not continue past this step if no task was provided.
|
||||
Do not continue past this step if no brief was provided.
|
||||
|
||||
Report the detected mode to the user:
|
||||
### Read the brief
|
||||
|
||||
Read the brief file and parse its frontmatter. Extract:
|
||||
- `task` — one-line task description
|
||||
- `slug` — slug for plan filenames
|
||||
- `project_dir` — if present, overrides derived project path (optional)
|
||||
- `research_topics` — N (used as a sanity check)
|
||||
- `research_status` — `pending | in_progress | complete | skipped`
|
||||
|
||||
If `research_status == pending` and `research_topics > 0`:
|
||||
- Warn the user: "Brief declares {N} research topics but research is still
|
||||
pending. Plan confidence will be lower. Continue anyway?"
|
||||
- `AskUserQuestion`: **Continue with low confidence** / **Cancel — run research first**.
|
||||
- If cancel: print the research invocations from the brief's "How to continue"
|
||||
section and stop.
|
||||
|
||||
Report the detected mode:
|
||||
```
|
||||
Mode: {default | spec-driven | foreground}
|
||||
Task: {task description or "from spec: {path}"}
|
||||
Mode: {background | foreground | quick | export | decompose}
|
||||
Brief: {brief_path}
|
||||
Project: {project_dir or "-"}
|
||||
Research: {N local briefs, M extra via --research}
|
||||
```
|
||||
|
||||
## Phase 1.5 — Export (runs only when mode = export)
|
||||
|
|
@ -189,7 +226,7 @@ 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.
|
||||
Then **stop**. Do not continue to any subsequent phase.
|
||||
|
||||
## Phase 1.6 — Decompose (runs only when mode = decompose or export headless)
|
||||
|
||||
|
|
@ -252,108 +289,43 @@ You can:
|
|||
|
||||
If the user says **"launch"**: run the launch script via Bash.
|
||||
|
||||
Then **stop**. Do not continue to Phase 2 or any subsequent phase.
|
||||
Then **stop**. Do not continue to any subsequent phase.
|
||||
|
||||
## Phase 2 — Requirements gathering (interview)
|
||||
## Phase 2 — (removed in v2.0)
|
||||
|
||||
**Skip this phase entirely if mode = spec-driven.** Proceed to Phase 3.
|
||||
|
||||
### Research-enriched interview
|
||||
|
||||
If **has_research_brief = true**: read each research brief file before starting the
|
||||
interview. Then adjust the interview:
|
||||
|
||||
1. Tell the user: "I've read {N} research brief(s). The interview will focus on
|
||||
decisions and implementation details — skipping topics already covered."
|
||||
2. Skip questions about technologies, patterns, or approaches already researched.
|
||||
3. Focus on: implementation preferences, non-functional requirements, scope decisions.
|
||||
4. Reference brief findings in questions where relevant:
|
||||
> "The research brief found that {finding}. Does this affect your approach?"
|
||||
> "The brief identified {risk}. Should the plan account for this?"
|
||||
|
||||
If **has_research_brief = false**: proceed with the standard interview below.
|
||||
|
||||
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
|
||||
```
|
||||
The interview phase has moved to `/ultrabrief-local`. This command no
|
||||
longer asks the user any requirements questions — the brief is the
|
||||
authoritative input.
|
||||
|
||||
## Phase 3 — Background transition
|
||||
|
||||
**If mode = foreground or quick:** Skip this phase. Continue to Phase 4 inline.
|
||||
|
||||
**If mode = default or spec-driven:**
|
||||
**If mode = default (background):**
|
||||
|
||||
Determine the plan destination path:
|
||||
- If `project_dir` is set (from `--project` or the brief's `project_dir`
|
||||
frontmatter field): **plan destination = {project_dir}/plan.md**.
|
||||
- Otherwise: derive slug and date — if the brief has frontmatter `slug` and
|
||||
`created`, use them; otherwise extract from the brief filename. Destination:
|
||||
`.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`.
|
||||
|
||||
Collect all research briefs (from `--research` flag and auto-discovered
|
||||
`{project_dir}/research/*.md`).
|
||||
|
||||
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
|
||||
Brief file: {brief_path}
|
||||
Project dir: {project_dir or "-"}
|
||||
Task: {task from brief frontmatter}
|
||||
Mode: {default | quick}
|
||||
Plan destination: {plan destination}
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
Research briefs: {path1, path2, ...} ← include ONLY if has_research_brief = true
|
||||
Research briefs: {comma-separated list, or "none"}
|
||||
|
||||
Read the spec file and execute your full planning workflow.
|
||||
Write the plan to the destination path.
|
||||
Read the brief file and every research brief. 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`.
|
||||
|
|
@ -361,11 +333,13 @@ 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
|
||||
Brief: {brief_path}
|
||||
Project: {project_dir or "-"}
|
||||
Plan: {plan destination}
|
||||
|
||||
You will be notified when the plan is ready.
|
||||
You can continue working on other tasks in the meantime.
|
||||
|
|
@ -400,11 +374,11 @@ Report:
|
|||
Codebase: {N} source files ({scale}). Deploying exploration agents.
|
||||
```
|
||||
|
||||
## Phase 4b — Spec review
|
||||
## Phase 4b — Brief review
|
||||
|
||||
Launch the **spec-reviewer** agent:
|
||||
Prompt: "Review this spec for quality: {spec path}. Check completeness, consistency,
|
||||
testability, and scope clarity."
|
||||
Launch the **brief-reviewer** agent:
|
||||
Prompt: "Review this task brief for quality: {brief_path}. Check completeness,
|
||||
consistency, testability, scope clarity, and research-plan validity."
|
||||
|
||||
Handle the verdict:
|
||||
- **PROCEED** — continue to Phase 5.
|
||||
|
|
@ -416,7 +390,7 @@ Handle the verdict:
|
|||
|
||||
**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)
|
||||
- `Glob` for files matching key terms from the brief's task/intent (up to 3 patterns)
|
||||
- `Grep` for function/type definitions matching key terms (up to 3 patterns)
|
||||
|
||||
Report findings as:
|
||||
|
|
@ -444,7 +418,7 @@ medium: default, large: default) instead of dropping agents.
|
|||
| `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) |
|
||||
| `research-scout` | Conditional | Conditional | Conditional | External docs (only when unfamiliar tech detected AND no research brief covers it) |
|
||||
| `convention-scanner` | No | Yes | Yes | Coding conventions, naming, style, test patterns |
|
||||
|
||||
### Always launch (all codebase sizes):
|
||||
|
|
@ -481,19 +455,25 @@ 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:
|
||||
After reading the brief, 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.
|
||||
**Skip research-scout** for any topic already answered by an attached research
|
||||
brief. If the brief's `research_status == complete` and all `Research Plan`
|
||||
topics have corresponding research files, skip research-scout entirely.
|
||||
|
||||
If yes (and not covered by attached briefs): 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."
|
||||
If no external technology is involved or all topics are covered by briefs:
|
||||
skip research-scout and note:
|
||||
"No external research needed — covered by research briefs / well-represented in codebase."
|
||||
|
||||
## Phase 6 — Targeted deep-dives
|
||||
|
||||
|
|
@ -530,18 +510,19 @@ 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 brief file (from `--brief` or `--project`).
|
||||
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.
|
||||
1. **Context** — Why this change is needed. Use the brief's **Intent** verbatim
|
||||
or tightly paraphrased. The plan's motivation must trace directly to the brief.
|
||||
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.
|
||||
3. **Research Sources** — If any research briefs or research-scout was used: table
|
||||
of technologies, sources, findings, and confidence levels. Omit if none.
|
||||
4. **Implementation Plan** — Ordered steps. Each step specifies:
|
||||
- Exact files to modify or create (with paths)
|
||||
- What changes to make and why
|
||||
|
|
@ -555,12 +536,12 @@ Write the plan following the template structure. The plan MUST include:
|
|||
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.
|
||||
6. **Risks and Mitigations** — From the risk-assessor findings and the brief's
|
||||
open questions. 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.
|
||||
8. **Verification** — Reuse the brief's **Success Criteria** as the baseline.
|
||||
Each criterion must be an executable command or observable condition.
|
||||
9. **Estimated Scope** — File counts and complexity rating.
|
||||
|
||||
### Quality standards
|
||||
|
|
@ -574,12 +555,16 @@ Write the plan following the template structure. The plan MUST include:
|
|||
- 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
|
||||
- Every implementation decision must be traceable to a brief section (Intent,
|
||||
Goal, Constraint, Preference, NFR, or Success Criterion)
|
||||
|
||||
### 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.
|
||||
Use the plan destination computed in Phase 3:
|
||||
- `--project` mode: `{project_dir}/plan.md`
|
||||
- `--brief` mode: `.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Create the parent directory if it does not exist.
|
||||
|
||||
## Phase 9 — Adversarial review
|
||||
|
||||
|
|
@ -592,10 +577,12 @@ 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."
|
||||
Prompt: "Check this implementation plan against the brief.
|
||||
Task: {task}. Brief file: {brief_path}. Plan file: {plan path}.
|
||||
Find scope creep (plan does more than the brief requires) and scope gaps
|
||||
(plan misses brief requirements). Check that referenced files and functions
|
||||
exist. Verify that every Success Criterion in the brief is covered by the
|
||||
plan's Verification section."
|
||||
|
||||
After both complete:
|
||||
- If **blockers** are found: revise the plan to address them. Add a "Revisions"
|
||||
|
|
@ -612,9 +599,10 @@ 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
|
||||
**Mode:** {background | foreground | quick}
|
||||
**Brief:** {brief_path}
|
||||
**Project:** {project_dir or "-"}
|
||||
**Plan:** {plan_path}
|
||||
**Exploration:** {N} agents deployed ({N} specialized + {N} deep-dives + {research status})
|
||||
**Scope:** {N} files to modify, {N} to create — {complexity}
|
||||
|
||||
|
|
@ -628,7 +616,7 @@ Present a summary to the user:
|
|||
...
|
||||
|
||||
### Research findings
|
||||
{Summary of external research, or "No external research conducted."}
|
||||
{Summary of external research + attached research briefs, or "No external research used."}
|
||||
|
||||
### Adversarial review
|
||||
**Plan critic:** {Summary — blockers/majors/minors found, how addressed}
|
||||
|
|
@ -650,7 +638,7 @@ If the user asks questions or requests changes:
|
|||
|
||||
### "save" / "later" / "done"
|
||||
|
||||
Confirm the plan and spec file locations and exit.
|
||||
Confirm the plan and brief file locations and exit.
|
||||
|
||||
### "execute" / "go" / "start"
|
||||
|
||||
|
|
@ -687,13 +675,16 @@ Record format (one JSON line):
|
|||
{
|
||||
"ts": "{ISO-8601 timestamp}",
|
||||
"task": "{task description (first 100 chars)}",
|
||||
"mode": "{default|spec|fg}",
|
||||
"mode": "{default|fg|quick}",
|
||||
"slug": "{plan slug}",
|
||||
"brief_path": "{brief_path}",
|
||||
"project_dir": "{project_dir or null}",
|
||||
"codebase_size": "{small|medium|large}",
|
||||
"codebase_files": {N},
|
||||
"agents_deployed": {N},
|
||||
"deep_dives": {N},
|
||||
"research": {true|false},
|
||||
"research_briefs_used": {N},
|
||||
"research_scout_used": {true|false},
|
||||
"critic_verdict": "{BLOCK|REVISE|PASS}",
|
||||
"guardian_verdict": "{ALIGNED|CREEP|GAP|MIXED}",
|
||||
"outcome": "{execute|execute_team|save|refine}"
|
||||
|
|
@ -705,6 +696,11 @@ Never let tracking failures block the main workflow.
|
|||
|
||||
## Hard rules
|
||||
|
||||
- **Brief-driven**: Every plan decision must trace back to a section of the
|
||||
brief (Intent, Goal, Constraint, Preference, NFR, Success Criterion). If a
|
||||
step has no brief basis, it is scope creep — flag it or remove it.
|
||||
- **No interview**: Never ask the user requirements questions. If the brief is
|
||||
inadequate, stop and ask the user to run `/ultrabrief-local` again.
|
||||
- **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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue