open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/ultraplan-local/CLAUDE.md
Kjell Tore Guttormsen 1634197853 feat(ultraplan-local): v2.1.0 — dynamic quality-gated interview 
Replace hardcoded Q1-Q8 in /ultrabrief-local with a section-driven
completeness loop (Phase 3) and a draft/review/revise loop with
brief-reviewer as stop-gate (Phase 4). Quality drives the interview,
not a question counter.

brief-reviewer now emits a machine-readable JSON block with per-dimension
scores (1-5) and detail arrays alongside the existing prose report;
planning-orchestrator continues to consume the prose verdict unchanged.

Phase 4 gate: all dimensions >= 4 AND research_plan = 5. On fail, a
targeted follow-up is generated from the weakest dimension's detail
field and the draft is re-reviewed. Max 3 review iterations bound cost;
exhaustion writes brief.md with brief_quality: partial and an explicit
Brief Quality section. Force-stop surfaces per-dimension findings before
the user chooses continue or partial.

Not breaking. /ultrabrief-local [--quick] <task> interface unchanged.
--quick now means compact start with escalation, not a max-N cap.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-18 09:43:43 +02:00

133 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ultraplan-local
Deep implementation planning and research with an explicit brief step, 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 (brief → research → plan → execute) produces a structured artifact that the next step consumes.
## Commands
| Command | Description | Model |
|---------|-------------|-------|
| `/ultrabrief-local` | Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline | opus |
| `/ultraresearch-local` | Research — deep local + external research, produces structured research brief | opus |
| `/ultraplan-local` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project` | opus |
| `/ultraexecute-local` | Execute — disciplined plan/session-spec executor with failure recovery | opus |
### /ultrabrief-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Dynamic interview until quality gates pass → brief.md with research plan |
| `--quick` | Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan |
Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a `brief-reviewer` stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).
### /ultraresearch-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Interview + background research (local + external) + synthesis + brief |
| `--project <dir>` | Write brief to `{dir}/research/{NN}-{slug}.md` (auto-incremented) |
| `--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 combine: `--project <dir> --local --fg`, `--external --quick`.
### /ultraplan-local modes
| Flag | Behavior |
|------|----------|
| `--project <dir>` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/ultraplan-{date}-{slug}.md` |
| `--research <brief> [brief2]` | Enrich with extra research briefs beyond what is in `{project_dir}/research/` |
| `--fg` | All phases in foreground (blocking) |
| `--quick` | 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 |
**Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/ultraplan-local`. The `--spec` flag has been removed — use `/ultrabrief-local` to produce a brief instead.
### /ultraexecute-local modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Execute plan — auto-detects Execution Strategy for multi-session |
| `--project <dir>` | Read `{dir}/plan.md`, write `{dir}/progress.json` |
| `--resume` | Resume from last progress checkpoint |
| `--dry-run` | Validate plan structure without executing |
| `--validate` | Schema-only check — parse steps + manifests, report `READY \| FAIL`, no execution |
| `--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 (brief-driven) |
| 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 |
| brief-reviewer | sonnet | Task brief quality (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity) |
| 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
**Brief:** 7-phase workflow: Parse mode → Create project dir → Phase 3 completeness loop (section-driven, no question cap) → Phase 4 draft/review/revise with `brief-reviewer` as stop-gate (max 3 iterations; gate = all dimensions ≥ 4 and research plan = 5) → Finalize (`brief.md` on pass, or `brief_quality: partial` on cap/force-stop) → Manual/auto opt-in → Stats. Always interactive. Auto mode blocks foreground until plan is ready.
**Research:** 8-phase workflow: Parse mode → Interview → Background transition → Parallel research (5 local + 4 external + 1 bridge) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`.
**Plan:** 12-phase workflow: Parse mode (validate brief input) → Background transition → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents) → Deep-dives → Synthesis → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md`.
**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`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Report. With `--project`, reads `{dir}/plan.md` and writes `{dir}/progress.json`.
**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:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project <dir>` fills in `{dir}/research/`. `/ultraplan-local --project <dir>` reads brief + research to produce `{dir}/plan.md`. `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
## State
All artifacts in one project directory (default):
- Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/`
- `brief.md` (task brief from `/ultrabrief-local`)
- `research/{NN}-{slug}.md` (research briefs from `/ultraresearch-local --project`)
- `plan.md` (from `/ultraplan-local --project`)
- `sessions/session-*.md` (from `--decompose`)
- `progress.json` (from `/ultraexecute-local --project`)
Legacy paths (still work without `--project`):
- Research briefs: `.claude/research/ultraresearch-{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`
Stats:
- Brief stats: `${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl`
- Plan stats: `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl`
- Exec stats: `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl`
- Research stats: `${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl`
## Terminology
- **Task brief** — produced by `/ultrabrief-local`. Declares intent, goal, and research plan. Drives planning.
- **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds planning.
A project typically has 1 task brief and 0–N research briefs.
Reference in a new issue View git blame Copy permalink