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

docs(ultraplan-local): document ultrareview-local in plugin + marketplace README

Browse source 
Plugin README: add /ultrareview-local to command tables, division-of-labor,
quick start, and example workflows. New /ultrareview-local section with
modes, output format, triage gate, and Handover 6 feedback loop. Bump
agent count 19 → 23 and command count 4 → 5 in architecture diagram.

Marketplace root README: bump ultraplan-local version 3.1.0 → 3.2.0,
update tagline to "Five-command (brief, research, plan, execute, review)
universal pipeline", add /ultrareview-local bullet, add v3.2.0 narrative
paragraph, bump plugin-card counts (5 commands · 5 hooks · 23 agents).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-01 17:18:16 +02:00
commit 90d45a5be4
2 changed files with 85 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

15
README.md
View file

@ -72,18 +72,21 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud
---
### [Ultra {brief | research | plan | execute} - local](plugins/ultraplan-local/) `v3.1.0`
### [Ultra {brief | research | plan | execute | review} - local](plugins/ultraplan-local/) `v3.2.0`
Deep requirements gathering, research, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery.
Deep requirements gathering, research, implementation planning, self-verifying execution, and independent post-hoc review with specialized agent swarms, adversarial review, and failure recovery. Five-command (brief, research, plan, execute, review) universal pipeline.
Four commands, one pipeline with clear division of labor:
Five commands, one pipeline with clear division of labor:
- **`/ultrabrief-local`** — Capture intent. Dynamic, quality-gated interview: a section-driven completeness loop (Phase 3) followed by a `brief-reviewer` stop-gate (Phase 4, max 3 review iterations). Required sections must reach an initial-signal gate AND pass review across completeness, consistency, testability, scope clarity, and research-plan validity before `brief.md` is written. Identifies research topics with copy-paste-ready `/ultraresearch-local` commands. Optional auto-orchestration runs research + planning in foreground. Always interactive.
- **`/ultraresearch-local`** — Gather context. Deep multi-source research with triangulation: 5 local agents + 4 external agents + Gemini bridge, producing structured briefs with confidence ratings. Makes no build decisions.
- **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`). Auto-discovers `architecture/overview.md` when the optional `ultra-cc-architect` plugin is installed and cross-references its `cc_features_proposed` against exploration findings.
- **`/ultraexecute-local`** — Execute the contract disciplined. Manifest-based verification, independent Phase 7.5 audit from git log + filesystem (ignores agent bookkeeping), Phase 7.6 bounded recovery dispatch for missing steps. Step 0 pre-flight catches sandbox push-denial before any work. `--validate` mode offers a fast schema-only sanity-check between planning and execution.
- **`/ultrareview-local`** — Close the iteration loop. Independent post-hoc reviewer reads `brief.md` from scratch and evaluates the diff produced by execute. Two parallel reviewers (brief-conformance + code-correctness) plus a Judge Agent (review-coordinator) for dedup and reasonableness filtering. Severity-tagged findings (Critical/High/Medium/Low/Info) with stable 40-char hex IDs feed back into planning via Handover 6 (`/ultraplan-local --brief review.md` → remediation plan with `source_findings:` audit trail).
All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`. `--project <dir>` works across `/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`.
All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, `progress.json`, and `review.md`. `--project <dir>` works across `/ultraresearch-local`, `/ultraplan-local`, `/ultraexecute-local`, and `/ultrareview-local`.
v3.2.0 (non-breaking) adds `/ultrareview-local` as the fifth command and the contracted **Handover 6 (review → plan)** feedback loop. New artifact type `type: ultrareview` validated by `lib/validators/review-validator.mjs`, stable 40-char SHA1 finding-IDs from `lib/parsers/finding-id.mjs`, Jaccard similarity for determinism testing (`lib/parsers/jaccard.mjs`), and a 12-key version-pinned rule catalogue (`lib/review/rule-catalogue.mjs`). Four new agents (review-orchestrator, brief-conformance-reviewer, code-correctness-reviewer, review-coordinator) implementing the Judge-Agent dedup pattern. `/ultraplan-local` now consumes `--brief review.md` (BLOCKER + MAJOR findings become plan goals) and writes `source_findings: [<id>, ...]` audit trail. `brief-validator` accepts both `type: ultrabrief` and `type: ultrareview`.
v3.0.0 extracts the Claude-Code-specific architecture phase to a separate plugin (`ultra-cc-architect`, see below). The planning pipeline now stays technology-agnostic; CC-feature matching becomes opt-in. The plan command still auto-discovers `architecture/overview.md` if the new plugin is installed — the contract is filesystem-level, not code-level. Non-breaking for users of brief/research/plan/execute. See `plugins/ultraplan-local/CHANGELOG.md` for migration steps.
@ -95,13 +98,13 @@ v1.7 self-verifying chain (preserved): a step may not be marked `completed` unle
v3.1.0 (in progress) adds a `lib/`-tree of zero-dep validators (`brief-validator`, `research-validator`, `plan-validator`, `progress-validator`, `architecture-discovery`) wired into the four commands as CLI shims, plus 109 `node:test` cases and a doc-consistency invariant test. The Phase 5.5 schema self-check now runs as `node lib/validators/plan-validator.mjs --strict` instead of three `grep -cE` calls — same checks, single source of truth, machine-readable error codes. Architecture discovery treats the `ultra-cc-architect` contract as drift-WARN, never drift-FAIL. Forking the plugin? `npm test` is the readiness gate.
v3.1.0 also adds: `docs/HANDOVER-CONTRACTS.md` as the single source of truth for the 5 pipeline handovers; PreCompact-hook (`pre-compact-flush.mjs`, CC v2.1.105+) that fixes the documented progress.json drift bug — `--resume` now works after long conversations; UserPromptSubmit-hook that sets session titles `ultra:<command>:<slug>` for headless multiplexing (CC v2.1.94+); PostToolUse-hook that captures Bash `duration_ms` per call (CC v2.1.97+); semantic plan-critic rubric that catches paraphrased deferred decisions ("implement as needed", "wire it up") instead of just exact-string blacklist; `examples/01-add-verbose-flag/` showing a calibrated end-to-end pipeline run; `SECURITY.md` boilerplate; `docs/architect-bridge-test.md` smoke checklist.
v3.1.0 also adds: `docs/HANDOVER-CONTRACTS.md` as the single source of truth for the 5 pipeline handovers (extended to 6 in v3.2.0); PreCompact-hook (`pre-compact-flush.mjs`, CC v2.1.105+) that fixes the documented progress.json drift bug — `--resume` now works after long conversations; UserPromptSubmit-hook that sets session titles `ultra:<command>:<slug>` for headless multiplexing (CC v2.1.94+); PostToolUse-hook that captures Bash `duration_ms` per call (CC v2.1.97+); semantic plan-critic rubric that catches paraphrased deferred decisions ("implement as needed", "wire it up") instead of just exact-string blacklist; `examples/01-add-verbose-flag/` showing a calibrated end-to-end pipeline run; `SECURITY.md` boilerplate; `docs/architect-bridge-test.md` smoke checklist.
Defense-in-depth security: plugin hooks block destructive commands and sensitive path writes, prompt-level denylist works in headless sessions, pre-execution plan scan catches dangerous commands before they run, scoped `--allowedTools` replaces `--dangerously-skip-permissions` in parallel sessions. Recommended hardening: `disableSkillShellExecution: true` for fork-ers handling untrusted plans (CC v2.1.91+).
Modes: default, brief-driven, project-scoped, research-enriched, foreground, quick, decompose, export
19 specialized agents · 4 commands · 4 plugin hooks · No cloud dependency
23 specialized agents · 5 commands · 5 plugin hooks · No cloud dependency
→ [Full documentation](plugins/ultraplan-local/README.md) · [Migration guide](plugins/ultraplan-local/MIGRATION.md)

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

@ -1,4 +1,4 @@
# ultraplan-local — Brief, Research, Plan, Execute
# ultraplan-local — Brief, Research, Plan, Execute, Review
![Version](https://img.shields.io/badge/version-3.1.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
@ -6,7 +6,7 @@
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, and autonomous execution. Four commands, one pipeline:
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, and independent post-hoc review. Five commands, one pipeline:
| Command | What it does |
|---------|-------------|
@ -14,8 +14,9 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep
| **`/ultraresearch-local`** | Research — deep local + external research with triangulation |
| **`/ultraplan-local`** | Plan — agent swarm exploration, Opus planning, adversarial review |
| **`/ultraexecute-local`** | Execute — disciplined step-by-step implementation with failure recovery |
| **`/ultrareview-local`** | Review — independent post-hoc review of delivered code against the brief, severity-tagged findings |
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`.
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, `progress.json`, and `review.md`.
### Division of labor
@ -25,6 +26,7 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s
| `/ultraresearch-local` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) |
| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when the `ultra-cc-architect` plugin is installed. | `plan.md` with Manifest blocks + `plan_version: 1.7` |
| `/ultraexecute-local` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status |
| `/ultrareview-local` | **Close the loop** — independent post-hoc reviewer reads `brief.md` and the diff produced by execute, runs brief-conformance + code-correctness reviewers in parallel, dedups via Judge Agent. Severity-tagged findings (Critical/High/Medium/Low/Info) feed back into planning via Handover 6. | `review.md` (`type: ultrareview`) with stable 40-char hex finding-IDs |
**Principle:** Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream.
@ -62,10 +64,16 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar
# Execute
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth
# Review (independent post-hoc verification of the diff against brief.md)
/ultrareview-local --project .claude/projects/2026-04-18-jwt-auth
# → .claude/projects/2026-04-18-jwt-auth/review.md
```
Or opt into auto-mode in `/ultrabrief-local` — it will run research and planning sequentially inline in the main context, and return when `plan.md` is ready.
If review finds issues, feed `review.md` back into planning to produce a remediation plan: `/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/review.md`. The remediation plan carries `source_findings: [<id>, ...]` in its frontmatter — full audit trail back to the consumed findings (Handover 6).
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.
## When to use it
@ -359,6 +367,55 @@ across executions.
---
## `/ultrareview-local` — Review
Independent post-hoc review of delivered code against the brief. Reads `brief.md`
from scratch and treats research/plan as supplementary context. The output
`review.md` is a new artifact type (`type: ultrareview`) with its own validator
and a contracted **Handover 6 (review → plan)** so findings can be fed back into
`/ultraplan-local --brief review.md` to produce a remediation plan — closing
the iteration loop without ad-hoc conventions.
### Modes
| Mode | Command | Description |
|------|---------|-------------|
| **Default** | `/ultrareview-local --project <dir>` | brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write `{dir}/review.md` |
| **Since ref** | `/ultrareview-local --project <dir> --since <ref>` | Override "before" SHA for the diff range. Validated via `git rev-parse --verify` |
| **Quick** | `/ultrareview-local --project <dir> --quick` | Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass |
| **Validate** | `/ultrareview-local --project <dir> --validate` | Schema-only check on existing `review.md`. No LLM calls |
| **Dry run** | `/ultrareview-local --project <dir> --dry-run` | Print discovered scope + triage map; skip writes |
### What review produces
`review.md` carries a flat array of finding-IDs in frontmatter (40-char hex from `lib/parsers/finding-id.mjs`) plus the full finding objects in the body under per-severity headings:
- `## Findings (BLOCKER)` — must-fix before merge
- `## Findings (MAJOR)` — should-fix
- `## Findings (MINOR)` — nice-to-fix
- `## Findings (SUGGESTION)` — opinion-only
Required body sections: `## Executive Summary`, `## Coverage`, `## Remediation Summary`. The Coverage section enumerates which files were deep-reviewed, summary-only, or skipped (with reason) — explicit triage to avoid silent skips.
### Triage gate (deterministic)
A path-pattern classifier produces `{file → deep-review|summary-only|skip}` before any LLM runs. Hardcoded skip patterns: `*.lock`, `*.svg`, `dist/**`, `build/**`, `node_modules/**`, generated markers. Deep-review patterns: `auth/**`, `crypto/**`, `**/security/**`. Hard refuse-with-suggestion above 100 files / 100K diff tokens.
### Feedback loop (Handover 6)
```bash
/ultrareview-local --project <dir>
# → review.md (BLOCKER + MAJOR findings)
/ultraplan-local --brief <dir>/review.md
# → plan.md with `source_findings: [<id>, ...]` audit trail
# (BLOCKER + MAJOR findings become plan goals; MINOR + SUGGESTION skipped for v1.0)
```
The plan's optional `source_findings:` frontmatter list is the audit trail back to consumed findings. See `docs/HANDOVER-CONTRACTS.md` for the full Handover 6 contract.
---
## The full pipeline
```
@ -432,6 +489,20 @@ To insert a Claude-Code-specific architecture-matching step between research and
/ultraexecute-local --project <dir> # execute
```
**Review feedback loop (Handover 6):**
```bash
/ultrareview-local --project <dir>
# → review.md with severity-tagged findings + verdict (BLOCK / WARN / ALLOW)
# If verdict is BLOCK or WARN, feed findings back into a remediation plan:
/ultraplan-local --brief <dir>/review.md
# → plan.md with source_findings: [<id>, ...] audit trail
/ultraexecute-local --project <dir> # execute the remediation plan
/ultrareview-local --project <dir> # re-review (overwrites review.md)
```
---
## Upgrading
@ -512,8 +583,8 @@ Top-level layout:
```
ultraplan-local/
├── agents/ 19 specialized agents (sonnet for exploration, opus for orchestration)
├── commands/ 4 slash commands (ultrabrief, ultraresearch, ultraplan, ultraexecute)
├── agents/ 23 specialized agents (sonnet for exploration + review, opus for orchestration)
├── commands/ 5 slash commands (ultrabrief, ultraresearch, ultraplan, ultraexecute, ultrareview)
├── 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/)