diff --git a/README.md b/README.md index 0126496..01d1085 100644 --- a/README.md +++ b/README.md @@ -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: [, ...]` 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 ` | brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write `{dir}/review.md` | +| **Since ref** | `/ultrareview-local --project --since ` | Override "before" SHA for the diff range. Validated via `git rev-parse --verify` | +| **Quick** | `/ultrareview-local --project --quick` | Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass | +| **Validate** | `/ultrareview-local --project --validate` | Schema-only check on existing `review.md`. No LLM calls | +| **Dry run** | `/ultrareview-local --project --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 +# → review.md (BLOCKER + MAJOR findings) + +/ultraplan-local --brief /review.md +# → plan.md with `source_findings: [, ...]` 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 # execute ``` +**Review feedback loop (Handover 6):** +```bash +/ultrareview-local --project +# → 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 /review.md +# → plan.md with source_findings: [, ...] audit trail + +/ultraexecute-local --project # execute the remediation plan + +/ultrareview-local --project # 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/)