diff --git a/README.md b/README.md index 0305aee..879e0e4 100644 --- a/README.md +++ b/README.md @@ -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 ` 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 ` 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: [, ...]` 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::` 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::` 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) diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index 0126496..01d1085 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/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/)