metareview
Local-first review gates and learning for specs, plans, code, epics, PRs, and post-merge follow-up. Metareview is Go-backed, Markdown-friendly, and designed to run standalone or as a deeper review engine inside metaswarm, Superpowers, and Beads workflows.
Use Cases
metareview is for any moment where a human or coding agent needs a second, structured pass before moving work forward:
- Spec review: check whether requirements are complete, testable, internally consistent, and aligned with the original user intent.
- Plan review: challenge implementation plans before work starts, including sequencing, scope control, missing failure paths, and acceptance gates.
- Architecture review: evaluate service boundaries, data flow, ownership, coupling, scalability, security, and fit with existing repository patterns.
- Feasibility review: identify technical unknowns, external dependencies, risky assumptions, migration hazards, and places where a spike is needed.
- Decomposition review: inspect epics, child tasks, dependency graphs, work-unit boundaries, and DoD coverage before agents start executing.
- Fractal child-plan review: recursively review decomposed child plans and sub-epics until every level is implementation-ready.
- Code review: review local task-sized code chunks before an agent claims done, with repository context and deterministic blocker handling.
- Test and acceptance review: verify that tests, acceptance criteria, validation evidence, and edge cases prove the intended behavior.
- PR readiness review: check branch-level completeness before push, PR creation, or merge readiness.
- Intent-drift review: after iterative revisions, compare the result back to the original request so local fixes do not quietly change the mission.
- Post-merge learning: extract durable lessons from merged work, review feedback, failures, and session history into local knowledge.
- Repository knowledge review: use service inventories, Beads knowledge, session history, and prior GitHub context to avoid duplicate services and repeated mistakes.
What Is This?
metareview brings the discipline of structured, adversarial agent workflows to the review side of software development. It gives humans and coding agents repeatable gates for:
- reviewing specs, plans, architecture notes, designs, decompositions, and documentation
- reviewing local task-sized code chunks before an agent claims the task is done
- checking whether an epic or parent task is actually ready after child tasks complete
- checking whether a branch is ready to push, open as a PR, or merge
- extracting post-merge learning into durable local knowledge
On first use in an existing repository, metareview performs the same kind of initial repository analysis that experienced reviewers do manually: it looks for existing architecture notes, service inventories, Beads knowledge, prior sessions, and GitHub history. If no service registry exists, setup can create a metareview-compatible docs/SERVICE_INVENTORY.md seed so future reviews have a shared map of important services, ownership boundaries, and repeated code paths.
Unlike proprietary SaaS review products such as CodeRabbit, Greptile, and similar hosted reviewers, metareview keeps this learning local, nonproprietary, and user-readable. Its knowledgebase is Markdown/JSONL-friendly and can be synced through git. Each time review feedback is resolved and work is merged, metareview can incorporate useful lessons, idiosyncratic repository decisions, and reviewer calibration while pruning stale, overly specific, or self-evident entries as the codebase evolves.
The goal is not another loose "please review this" prompt. The goal is a review harness with named gates, explicit evidence, deterministic blocker policy, durable Markdown artifacts, service registry context, and knowledge feedback loops that help future agents avoid repeating mistakes.
Agentic Review Patterns
metareview is built around review patterns that work well when humans and coding agents are collaborating:
