open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

docs(ultraplan-local): trim README — outcomes section + remove duplication

Browse source 
Add "What you get" with Solo / Team / Virksomhet profiles + honest
"What it doesn't solve" list. Lets adoption decisions land before
command details.

Cuts (deduplication and historical noise):
- Architecture file-tree (~50 lines) → terse top-level layout +
  pointer to CONTRIBUTING.md. Original was stale (missing lib/,
  wrong hook-count, wrong plugin.json version note)
- "How it compares" matrix (~17 lines) — sales-coded comparison
  vs cloud tools, doesn't help adoption decisions
- Per-command "How it works" 8-step prose (~50 lines across 4
  commands) → 2-3 sentence summaries
- Exploration / Review / Research agent tables (~40 lines) →
  one-liner pointers to agents/ directory (already self-documenting)
- v1.x and v2.x migration sections (~30 lines) → pointer to
  CHANGELOG.md / MIGRATION.md
- v3.0.0, v2.4.0 historical callouts (~9 lines) — CHANGELOG owns
  these
- Cost profile bullet-list (~13 lines) → one paragraph

Net: 770 → 609 lines (-21%). Tests green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-01 06:44:44 +02:00
commit 5df8e8888e
1 changed files with 44 additions and 181 deletions
Download patch file Download diff file Expand all files Collapse all files

225
plugins/ultraplan-local/README.md
View file

@ -17,8 +17,6 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`.
> **v3.0.0 — architect extracted to its own plugin.** The `/ultra-cc-architect-local` and `/ultra-skill-author-local` commands moved to the separate `ultra-cc-architect` plugin (v0.1.0). The plan command still auto-discovers `architecture/overview.md` if present, so installing both plugins gives you the full pipeline (brief → research → architect → plan → execute). See [CHANGELOG.md](CHANGELOG.md) for migration steps.
### Division of labor
| Command | Responsibility | Output |
@ -70,8 +68,6 @@ Or opt into auto-mode in `/ultrabrief-local` — it will run research and planni
For Claude-Code-specific architecture matching (matching brief+research to features like Hooks, Subagents, Skills, MCP), install the separate `ultra-cc-architect` plugin. It sits between research and plan — `/ultraplan-local` auto-discovers its output.
> **v2.4.0 — background mode removed.** All four orchestrator commands now run foreground in the main context. The `--fg` flag is preserved as a no-op alias for backward compatibility. Background mode silently degraded the agent swarm (the harness does not expose the Agent tool to sub-agents) — see [CHANGELOG](CHANGELOG.md) for the full rationale.
## When to use it
**Use it when:**
@ -88,22 +84,37 @@ For Claude-Code-specific architecture matching (matching brief+research to featu
**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.
## What you get
Concrete capabilities, observable in the code — not aspirations.
**Across all profiles:**
- Strategy-to-execution on four explicit handover points. Each transition is a filesystem contract (`docs/HANDOVER-CONTRACTS.md`), not a conversation. You can stop after any stage and resume later without context loss.
- Resume safety after long sessions. The PreCompact hook reconciles `progress.json` with git history before context compaction (CC v2.1.105+) — closes a documented `--resume` failure mode.
- Schema discipline. `plan-validator --strict` enforces `### Step N:` form and rejects narrative drift (`### Fase`, `### Phase`, `### Stage`, `### Steg`) before execution.
- Audit trail by construction. Every executed step records `commit_sha`, `verify_passed`, `files_changed` in `progress.json`.
**Solo developer.** Plans survive across sessions; adversarial review (plan-critic + scope-guardian) catches your own tunnel vision before code is written; brief-phase forces clarity on what the task actually is. `examples/01-add-verbose-flag/` shows what good shape looks like.
**Team (2–10).** Plan files are handover-ready — a colleague can pick up a project directory without re-asking "what did you mean here?". `--decompose` splits a plan into self-contained headless sessions with scoped `--allowedTools`. The plan-critic semantic rubric gives the team a shared definition of "this plan defers decisions to the executor".
**Virksomhet / regulated environment.** Defense-in-depth security across four layers (plugin hooks, prompt-level denylist, pre-execution plan scan, scoped tool access). `disableSkillShellExecution: true` recommendation for fork-ers handling untrusted briefs. No cloud dependency, no GitHub requirement. Validators are plain-Node CLIs — invocable from CI, custom hooks, or external tools, not just from ultra commands.
**What it doesn't solve:**
- LLM output truthfulness. Validators check shape, not facts. A plan with hallucinated paths passes schema but fails in execute. Plan-critic catches some, not all.
- Multi-user concurrency on a single project directory. Two simultaneous executors will clobber `progress.json`.
- Cost management. Opus on the orchestrator layer is expensive; documented in [Cost profile](#cost-profile), no automatic model downgrade.
- Linear/Jira/Slack integrations. Intentional omission — solo project, no enterprise wiring.
**One-line summary:** an executable contract pipeline where each stage is filesystem-validated, session-survivable, and skill-independent — in exchange for writing an actual brief before planning and an actual plan before coding.
---
## `/ultrabrief-local` — Brief
Interactive requirements-gathering command. Runs a **dynamic, quality-gated interview** and produces a **task brief** with an explicit research plan. Optionally orchestrates the rest of the pipeline.
### How it works (v2.1 — quality-gated)
1. **Parse mode** — `default` (dynamic; probes until quality gates pass) or `--quick` (starts compact, still escalates if gates fail)
2. **Create project directory** — `.claude/projects/{YYYY-MM-DD}-{slug}/` with `research/` subdirectory
3. **Phase 3 — Completeness loop** — a section-driven loop (not a fixed question list) picks the next question from the section with the weakest signal (Intent → Goal → Success Criteria → Research Plan first, then optional sections). Required sections must reach an initial-signal gate before Phase 3 exits. No hard cap on question count.
4. **Identify research topics** — inline during Phase 3; probe for unfamiliar tech, version upgrades, security-sensitive decisions, architectural choices. Topics get a research question, scope, confidence, and cost.
5. **Phase 4 — Draft, review, revise** — draft the brief in memory, write to `brief.md.draft`, launch `brief-reviewer` as a stop-gate. The reviewer scores five dimensions (completeness, consistency, testability, scope clarity, research plan) 1–5 and returns machine-readable JSON. Gate passes when all ≥ 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.
6. **Finalize** — rename draft to `brief.md` on pass, or write with `brief_quality: partial` + a `## Brief Quality` section if the cap is hit or the user force-stops.
7. **Auto-orchestration opt-in** — user chooses manual (default) or auto (Claude-managed research + plan in foreground)
8. **Stats tracking** — append to `ultrabrief-stats.jsonl` (includes `review_iterations` and `brief_quality`)
A section-driven interview loop fills required brief sections (Intent / Goal / Success Criteria / Research Plan) until each shows initial signal, then `brief-reviewer` scores the draft on five dimensions (completeness, consistency, testability, scope clarity, research-plan validity) and gates publication. Max 3 review iterations; force-stop yields a `brief_quality: partial` brief with the failing dimensions documented.
Output: `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`
@ -139,16 +150,7 @@ If you say "stop" or "enough" during Phase 4, the current review findings are su
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.
### How it works
1. **Interview** — short requirements gathering (skipped when `--project` reuses brief context)
2. **Research dimensions** — identify 3-8 facets 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
A parallel swarm of up to 5 local + 4 external Sonnet agents investigates 3–8 research dimensions, with optional Gemini Deep Research as an independent second opinion. Findings are triangulated (local vs. external, confidence per dimension, contradictions flagged) and synthesized into a structured research brief.
Output:
- With `--project <dir>`: `{dir}/research/{NN}-{slug}.md` (auto-incremented index)
@ -167,20 +169,7 @@ Output:
Flags combine: `--project <dir> --external`.
### 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) |
Research uses up to 5 local agents (architecture-mapper, dependency-tracer, task-finder, git-historian, convention-scanner) and 4 external agents (docs-researcher, community-researcher, security-researcher, contrarian-researcher) plus the optional Gemini bridge for an independent second opinion. Per-agent details in [`agents/`](agents/).
---
@ -188,17 +177,7 @@ Flags combine: `--project <dir> --external`.
Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/ultraplan-local` — use `/ultrabrief-local` first.
### How it works
1. **Parse mode** — validate that a brief is provided
2. **Spec review** → **brief review** — `brief-reviewer` validates completeness, consistency, testability, scope clarity, and research plan validity
3. **Explore** — 6-8 specialized Sonnet agents analyze your codebase in parallel
4. **Research** — optional research briefs enrich planning (`--research`, or auto-discovered in `{project_dir}/research/`)
5. **Architecture priors** — if `{project_dir}/architecture/overview.md` exists (produced by the optional `ultra-cc-architect` plugin), `cc_features_proposed` are loaded as priors. Missing file is fine.
6. **Synthesize** — findings merged into a unified codebase understanding
7. **Plan** — Opus creates a comprehensive implementation plan with per-step YAML manifests
8. **Critique** — adversarial review by `plan-critic` (9 dimensions) and `scope-guardian`
9. **Handoff** — plan written; execute now, save for later, or export
After `brief-reviewer` validates the input brief, 6–8 Sonnet exploration agents analyze the codebase in parallel and merge findings into a synthesis. Optional research briefs (`--research`, or auto-discovered in `{project_dir}/research/`) enrich the plan; `architecture/overview.md` priors are loaded if the `ultra-cc-architect` plugin produced one. Opus then writes the plan with per-step YAML manifests, which `plan-critic` (9 dimensions) and `scope-guardian` adversarially review before handoff.
Output:
- With `--project <dir>`: `{dir}/plan.md`
@ -240,26 +219,7 @@ Every implementation step includes:
- **Checkpoint:** — git commit after success
- **Manifest:** — the objective completion predicate (Hard Rule 17)
### Exploration agents
| Agent | Role | Runs on |
|-------|------|---------|
| architecture-mapper | Codebase structure, patterns, anti-patterns | All codebases |
| dependency-tracer | Import chains, data flow, side effects | All codebases |
| task-finder | Task-relevant files, functions, reuse candidates | All codebases |
| test-strategist | Test patterns, coverage gaps, strategy | All codebases |
| git-historian | Git history, ownership, hot files, branches | All codebases |
| risk-assessor | Threats, edge cases, failure modes | All codebases |
| research-scout | External docs, best practices | When unfamiliar tech detected |
| convention-scanner | Coding conventions, naming, style, test patterns | Medium+ codebases |
### Review agents
| Agent | Role |
|-------|------|
| brief-reviewer | Checks task brief quality (completeness, consistency, testability, scope clarity, research plan validity) before exploration |
| plan-critic | Adversarial review: 9 dimensions, quantitative scoring, no-placeholder enforcement, manifest audit as hard gate |
| scope-guardian | Verifies plan matches brief: finds scope creep and scope gaps |
Exploration uses 6–8 Sonnet agents in parallel (architecture-mapper, dependency-tracer, task-finder, test-strategist, git-historian, risk-assessor, plus convention-scanner on medium+ codebases and research-scout when unfamiliar tech is detected). Adversarial review then runs `brief-reviewer`, `plan-critic` (9 dimensions, no-placeholder enforcement, manifest audit), and `scope-guardian` (creep + gap detection). Per-agent details in [`agents/`](agents/).
---
@ -267,13 +227,7 @@ Every implementation step includes:
Reads a plan from `/ultraplan-local` and implements it with strict discipline. No guessing, no improvising — follows the plan exactly.
### How it works per step
1. **Implement** — applies the Changes field exactly as written
2. **Verify** — runs the Verify command (exit code is truth)
3. **Manifest audit** — validates expected paths, forbidden paths, commit pattern
4. **On failure** — follows the plan's recovery clause (revert / retry / skip / escalate)
5. **Checkpoint** — commits changes per the plan's Checkpoint field
Per step: apply Changes exactly as written → run Verify (exit code is truth) → manifest audit (expected paths, forbidden paths, commit pattern) → follow the plan's failure clause if anything fails (revert / retry / skip / escalate) → Checkpoint commit. After all steps: independent Phase 7.5 manifest audit from git log + filesystem (ignoring agent bookkeeping); drift triggers Phase 7.6 bounded recovery.
### Modes
@ -480,54 +434,9 @@ To insert a Claude-Code-specific architecture-matching step between research and
---
## Upgrading from v2.x to v3.0.0
## Upgrading
v3.0.0 is a structural release that does **not** break the planning flow but changes plugin layout:
- `/ultra-cc-architect-local` and `/ultra-skill-author-local` were moved to the new `ultra-cc-architect` plugin (v0.1.0).
- `/ultraplan-local` still auto-discovers `architecture/overview.md` if present — install both plugins to keep the full pipeline working.
- `cc-architect-catalog` skill moved to the new plugin. If you customized seeds locally, follow `git log --follow` to track them in the new location.
- `ngram-overlap.mjs` script and skill-factory test fixtures moved with the new plugin.
If you only used `/ultrabrief-local`, `/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`: no action needed. Update the plugin and continue.
If you used `/ultra-cc-architect-local` or `/ultra-skill-author-local`: install the new plugin alongside this one:
```json
{
"enabledPlugins": {
"ultraplan-local@ktg-plugin-marketplace": true,
"ultra-cc-architect@ktg-plugin-marketplace": true
}
}
```
## Upgrading from v1.x
v2.0.0 is a **breaking release**. See [MIGRATION.md](MIGRATION.md) for a step-by-step guide. Short version:
- `/ultraplan-local` no longer runs an interview. Use `/ultrabrief-local` first.
- `/ultraplan-local --spec <path>` is **removed**. Use `--brief <path>` or `--project <dir>` instead.
- Old specs do not work as-is. Convert a spec to a brief by filling in `## Intent` and `## Research Plan` sections (MIGRATION.md has a template).
- All artifacts now live in `.claude/projects/{date}-{slug}/` by default. Legacy paths (`.claude/research/`, `.claude/plans/`) still work without `--project`.
## How it compares
| Feature | Ultraplan (cloud) | Copilot Workspace | Cursor | ultraplan-local |
|---------|-------------------|-------------------|--------|-----------------|
| Planning model | Opus | GPT-4 | Unknown | Opus |
| Requirements gathering | Task only | Issue-driven | Prompt | **Dedicated brief command with explicit research plan** |
| Codebase exploration | Cloud | Cloud | Cloud | 6-8 specialized agents |
| Deep research pipeline | No | No | No | **10 agents + Gemini + triangulation** |
| Adversarial review | No | No | No | **brief-reviewer + 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** |
| Session-aware parallel execution | No | No | No | **Automatic wave-based** |
| No-placeholder enforcement | No | No | No | **Hard blocker** |
| Manifest audit as hard gate | No | No | No | **Hard Rule 17** |
| Headless autonomous execution | No | No | No | **`/ultraexecute-local` with `claude -p`** |
| Requires GitHub | Yes | Yes | No | **No** |
| Cross-platform | Web only | Web only | Desktop | **Mac, Linux, Windows** |
Migration notes for breaking changes (v1.x → v2.0, v2.x → v3.0) live in [CHANGELOG.md](CHANGELOG.md) and [MIGRATION.md](MIGRATION.md). v3.x non-breaking — minor bumps within v3 add features without changing pipeline contracts.
## Quality infrastructure (since v3.1.0)
@ -588,17 +497,7 @@ For Claude-Code-specific architecture matching (between research and plan), also
## Cost profile
- **Brief**: 1 Opus session (interactive; interview + write)
- **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)
- **Planning research**: 0-1 Sonnet agent (only when unfamiliar tech detected and no research brief provided)
- **Review**: 3 Sonnet agents (brief-reviewer + plan-critic + scope-guardian)
- **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
The plugin minimizes Opus usage by front-loading cheap Sonnet exploration.
Opus runs the orchestrators (one per command) and the executor (one per plan session). Sonnet runs the exploration and review swarms (5–10 agents per command, with effort/turn limits). The pipeline front-loads cheap Sonnet work so Opus only does synthesis and execution. Typical total: comparable to a long single Claude Code session — the per-command cost is published in `${CLAUDE_PLUGIN_DATA}/ultra*-stats.jsonl` if you want exact numbers.
## Requirements
@ -609,57 +508,21 @@ The plugin minimizes Opus usage by front-loading cheap Sonnet exploration.
## Architecture
Top-level layout:
```
ultraplan-local/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (v3.0.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
│ ├── brief-reviewer.md # Task brief quality review (5 dimensions)
│ ├── 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 # Inline reference for the planning pipeline (brief-driven)
│ ├── research-orchestrator.md # Inline reference for the 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/ # 4 slash commands
│ ├── ultrabrief-local.md # /ultrabrief-local — interactive brief
│ ├── ultraresearch-local.md # /ultraresearch-local — research
│ ├── ultraplan-local.md # /ultraplan-local — planning
│ └── ultraexecute-local.md # /ultraexecute-local — execution
├── templates/
│ ├── ultrabrief-template.md # Task brief format (intent, goal, research plan)
│ ├── 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
├── hooks/
│ ├── hooks.json # Hook registration (PreToolUse: Bash, Write)
│ └── scripts/
│ ├── pre-bash-executor.mjs # Blocks destructive commands (13 BLOCK + 8 WARN rules)
│ └── pre-write-executor.mjs # Blocks writes to sensitive paths (8 rules)
├── settings.json # Default plugin configuration
├── CONTRIBUTING.md
├── CHANGELOG.md
├── MIGRATION.md # v1 → v2 migration guide
├── LICENSE
└── README.md
├── agents/ 19 specialized agents (sonnet for exploration, opus for orchestration)
├── commands/ 4 slash commands (ultrabrief, ultraresearch, ultraplan, ultraexecute)
├── templates/ Frontmatter templates for brief, research, plan, session, launch
├── hooks/ 5 hooks (pre-bash, pre-write, session-title, post-bash-stats, pre-compact-flush)
├── lib/ Zero-dep parsers and validators (CLI shims under lib/validators/)
├── tests/ 109 node:test cases — `npm test` is the fork-readiness gate
├── docs/ HANDOVER-CONTRACTS.md + architect-bridge-test.md
└── examples/ 01-add-verbose-flag/ — calibrated end-to-end pipeline demo
```
CC-feature catalog, skill-factory, and architect/skill-author commands moved to the separate `ultra-cc-architect` plugin in v3.0.0.
Pure markdown commands and agents. Hooks are self-contained Node.js with zero dependencies.
Pure markdown commands and agents. Hooks and validators are self-contained Node.js with zero npm dependencies. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full file inventory.
## Extending the plugin