Architecture Overview

Architecture Overview

The component-level map. Canonical, exhaustive version: docs/ARCHITECTURE.md — this page is a shorter concept-first companion to it, not a replacement.

Module map

                 shared/
            review policies
                  │
         ┌────────┴────────┐
         │                 │
local-code-review    github-pr-review
         │                 │
 local report        GitHub delivery

Location	Owns
shared/policies/	portable review semantics used identically by both Skills — scope, severity, evidence, review-context, review-evidence, review-ownership, change-risk, repository-expansion, large-PR partitioning, stopping criteria, runtime-validation, trusted-host-execution, parallel-review, specialist-depth composition and its domain-specific deepening capabilities, and more
shared/templates/	the canonical finding and review-summary shapes both Skills render
skills/local-code-review/	local-Git-specific rules with no PR analogue
skills/github-pr-review/	GitHub-delivery rules with no local analogue

Thin runbooks, canonical policy owners

A runbook (skills/<name>/runbooks/) defines flow and ordering only — which policy governs each phase — never a second copy of that policy's decision tables. Reusable semantics live in shared/policies/; Skill-specific semantics live in that Skill's own policies/. See policies/skill-development-policy.md, "Runbook Design."

Base reasoning plus evidence-driven specialist depth

Base review reasoning (review-scope.md) runs unconditionally for every materially implicated dimension. Layered on top, specialist-depth.md owns the composition contract for when that base reasoning's own evidence justifies going further with one of the five implemented domain-specific deepening capabilities (Security, Distributed Systems, Database/Migration, Performance, Dependency/Supply-Chain) — and how 0..N of them compose into a single review rather than independent verdicts. See Specialist-Depth-Review for the full model; it is not a second scope model or a plugin architecture, and this page does not restate it.

Separation of concerns

Concern	Owned by
Review reasoning (what's wrong, why, severity)	shared/policies/, consumed identically by both Skills
Local Git state inspection	local-code-review
GitHub state inspection + delivery	github-pr-review
Orchestration (which Skill runs when, loop control, applying fixes)	the calling workflow — never either Skill
Implementation ownership (writing/fixing code)	the implementing Agent or developer — never either Skill

Orchestration boundary

Neither Skill decides when it runs again. local-code-review requires fresh, explicit user approval for every single invocation — the first review and every re-review after a fix. An implementing Agent never invokes github-pr-review against the PR it just opened or updated — that's the calling workflow's job, enforced at two separate points (orchestration prevention and a Skill-level defensive check). See docs/ARCHITECTURE.md §4–5 and policies/review-orchestration-policy.md.

Packaging: source vs. distribution layout

Source layout (skills/<name>/, shared/) and the flat archive layout that ships are intentionally different — see Packaging-and-Portability for the consumer-facing summary, and docs/ARCHITECTURE.md §7 for the exact substitution rules packaging applies.

What's deliberately not built

docs/ARCHITECTURE.md's "Future work" section lists what is intentionally absent today — for example, automatic branch-protection changes beyond one opt-in required-check setup, and any execution of a target repository's own tests/build/lint. This Wiki doesn't restate that list; read it directly so it never goes stale here.

---

Wiki Page Map

Page	What it covers
Home	Wiki entry point: what the two Skills are and where to go next.
Getting-Started	First steps to package and run either Skill.
Choosing-a-Review-Skill	How to decide between local-code-review and github-pr-review.
How-the-Review-Model-Works	Concept-level walkthrough of the review pipeline shared by both Skills.
Architecture-Overview	Component-level map of how the repository's pieces fit together.
Specialist-Depth-Review	When and how a review goes deeper than its base pass.
Local-Code-Review-Guide	Usage guide for reviewing local, not-yet-PR'd Git changes.
GitHub-PR-Review-Guide	Usage guide for reviewing an existing GitHub Pull Request.
Review-Context-and-Existing-Evidence	How optional requirements/context and prior review evidence are supplied.
Feature-Pages	Index of per-feature capability pages and their shared template.
Feature-Delta-Re-Review	How a re-review scopes itself to only what changed since the last pass.
Feature-GitHub-Publication-and-Authorization	What a PR review publishes to GitHub and under what authority.
Feature-Human-Style-Review-Output	The senior-engineer-voice prose summary output option.
Feature-Requirement-Coverage	How supplied requirements are checked and reported as covered or not.
Feature-Runtime-Validation-Evidence	How a review can execute commands or reproductions as evidence.
Severity-and-Decision-Model	The P0/P1/P2 severity levels and how the merge decision is derived.
Packaging-and-Portability	How the Skills go from source repository to a standalone archive.
Development-Workflow	Contributor guide for working on this repository itself.
Benchmark-Testing	Orientation to this repository's own review-quality benchmark pipeline.
Repository-Documentation-Map	Where each concern's canonical, authoritative source lives.
AI-Code-Review-Landscape	Neutral snapshot comparing this project against other AI code-review products.
FAQ	Short, practical answers to common questions.