crucible

Crucible

Not Another Code Reviewer.

A Claude Code plugin that runs your code through a corporate review pipeline. A Profiler reads your project, interviews you about the phase, and casts a 4–8 persona review committee from a 23-persona library. Peers review at the code level, departments hunt for gaps, and leadership grades alignment to your stated aims. An Aggregator synthesizes the holistic verdict — no math, no averaging, just Opus reasoning over the committee's reports.

The output is a live terminal stream while the pipeline runs and a fully-detailed markdown report saved at .review/reports/<id>.md. See examples/ for sample reports.

---

Why this exists

Every Claude Code plugin's reviewer fans out agents in parallel and aggregates their findings. Crucible is structurally different in three ways:

1. Adaptive cast. A Profiler reads your project and picks the right reviewers from a 23-persona library. A Next.js auth refactor casts TypeScript + SQL + Security + Backend + Database + Architect + PM. A PyTorch training change casts Python + Quality + Data-ML + Performance + Architect + PM. The committee fits the work.
2. Three altitudes. Stage 1 peers review at the code level (idioms, bugs, quality). Stage 2 cross-functional reviewers hunt for gaps (security, performance, accessibility, observability — domain-specific lenses). Stage 3 leadership reasons at the strategic level (architectural coherence, aim alignment).
3. Aim alignment. A lead-project-manager persona reads your .review/aims.md — written interactively by the Profiler — and grades the change against your stated success criteria. Nobody else does this. Your code isn't graded in a vacuum; it's graded against what you said you were trying to do.

The result: every persona reasons in their lane, the stages hand off structured findings, and one final reasoning agent synthesizes everything into a single score, verdict, and curated executive summary. No mechanical roll-up; the Aggregator weighs signals as a thoughtful executive would when reading a 7-person review committee.

---

Quick start

Inside Claude Code, add Crucible as a self-hosted marketplace and install the plugin (one-time setup):

/plugin marketplace add hazarsozer/crucible-cc
/plugin install crucible@crucible
/reload-plugins

Then, in any project directory:

cd your-project
/crucible:run

Alternative: ClaudePluginHub Quick Install

npx claudepluginhub hazarsozer/crucible-cc --plugin crucible

A single line of code provided by Claude Plugin Hub.

Alternative: clone the repo and load it directly (no install step)

git clone https://github.com/hazarsozer/crucible-cc.git
claude --plugin-dir ./crucible-cc

Useful if you want full source on disk to read, modify, or contribute back. The /plugin install path above copies Crucible to Claude Code's cache automatically.

Optional commands:

/crucible:aims      # refresh .review/aims.md without running a full review
/crucible:history   # list past reviews stored in .review/reports/

The first run of /crucible:run will:

1. Read your project files (file tree, README, language manifests, recent commits).
2. Detect project type (web-app, api, ml-pipeline, cli, library, mobile, data-pipeline, mixed).
3. Interview you about the phase: goal, success criteria, non-goals, constraints.
4. Write .review/aims.md and update .gitignore if needed.
5. Ask what to review (full project, phase, files, branch diff).
6. Cast the committee and confirm with you before dispatching.
7. Run the 5-stage pipeline and write the report.

Subsequent runs reuse .review/aims.md (with a "still accurate?" prompt).

---

⚠️ When NOT to use /crucible:run

Crucible runs 5 stages and 4–8 specialized agents per review. It is not another lightweight reviewer — it is a corporate-review simulation, and that shape costs tokens.

Use /crucible:run for:

• Full-project reviews (initial audit, pre-release, milestone gate)
• Partial-implementation reviews (a feature, a phase, a refactor in flight)

Don't use /crucible:run for:

• A single script or one-file change
• Trivial PRs or one-line tweaks
• Anything where one specialist's perspective is enough

For those, call a specific persona directly via the Task tool — crucible:peer-python-reviewer, crucible:team-security-reviewer, crucible:lead-senior-architect, etc. The full list of 23 personas is below; each is independently invokable. The pipeline is the heavyweight; individual personas are the scalpel.

Measured cost and wall-time ranges (from runs on a 7-file Next.js fixture) are in the Costs section below. A recommended-scope threshold (e.g. "≥N files") will land in a future release once we have measured runs on larger projects and other project types.

---

What it does — the 5-stage pipeline

                User: /crucible:run from project dir
                            │
                            ▼
 STAGE 0  ┌──────────────────────────────────────┐
   ░░░    │  PROFILER  (Sonnet 4.6)              │
          │  Reads project, interviews user,     │
          │  casts the committee, partitions     │
          │  files per persona                   │
          └──────────────────┬───────────────────┘
                             │ casting roster
                             ▼
 STAGE 1  ┌──────────────────────────────────────┐
   ███    │  PEER engineers (Haiku/Sonnet × 3-5) │
          │  Code-level: idioms, bugs, quality   │
          └──────────────────┬───────────────────┘
                             │ stage-1 findings
                             ▼
 STAGE 2  ┌──────────────────────────────────────┐
   ███    │  CROSS-FUNCTIONAL  (Sonnet × 2-4)    │
          │  Gap-level: security, perf, infra,   │
          │  privacy, observability, etc.        │
          └──────────────────┬───────────────────┘
                             │ stage-1 + stage-2
                             ▼
 STAGE 3  ┌──────────────────────────────────────┐
   ███    │  LEADERSHIP  (Opus × 2)              │
          │  Architect: ADR verdict              │
          │  PM: aim-alignment grade             │
          └──────────────────┬───────────────────┘
                             │ all stage findings
                             ▼
 STAGE 4  ┌──────────────────────────────────────┐
   ███    │  AGGREGATOR  (Opus)                  │
          │  Holistic score + verdict +          │
          │  curated executive summary           │
          └──────────────────┬───────────────────┘
                             │
                             ▼
              Live terminal stream (compact)
              + .review/reports/<id>.md (detailed)

Key invariants:

• Within a stage, personas run in parallel and never see each other's findings.
• Across stages, handoff is via structured JSON. Stage 2 reads Stage 1's findings; Stage 3 reads both; Aggregator reads everything plus the aims snapshot.
• File partitioning is computed by the Profiler. Each persona only sees its assigned scope.
• No mechanical roll-up — the final score and verdict are reasoned by the Aggregator.

---

The 23 personas

Stage 1 — Peer code reviewers (10)

Persona	Model	Lens
peer-python-reviewer	Haiku 4.5	PEP 8, idioms, type hints, common pitfalls
peer-typescript-reviewer	Sonnet 4.6	Type safety, async correctness, strict-mode patterns
peer-go-reviewer	Haiku 4.5	Idiomatic Go, error handling, concurrency
peer-rust-reviewer	Sonnet 4.6	Ownership, lifetimes, unsafe audit
peer-java-kotlin-reviewer	Sonnet 4.6	JVM idioms, Spring/Android patterns
peer-c-cpp-reviewer	Sonnet 4.6	Memory safety, modern C++ idioms, UB hunting
peer-swift-reviewer	Haiku 4.5	Swift idioms, iOS patterns
peer-sql-reviewer	Haiku 4.5	Schema, queries, indexing, migration safety
peer-quality-engineer	Sonnet 4.6	Test coverage, edge cases, missing assertions
peer-readability-engineer	Haiku 4.5	Naming, structure, function size, comment quality

Stage 2 — Cross-functional gap reviewers (11)

Persona	Model	Lens
team-security-reviewer	Sonnet 4.6	OWASP, auth flaws, secret leakage, crypto misuse
team-frontend-reviewer	Sonnet 4.6	UI/UX bugs, state, rendering, framework patterns
team-backend-reviewer	Sonnet 4.6	Server logic, request handling, error paths, idempotency
team-network-reviewer	Sonnet 4.6	API contracts, retries, timeouts, idempotency over the wire
team-database-reviewer	Sonnet 4.6	Schema, query plans, migrations, indexing
team-devops-infra-reviewer	Sonnet 4.6	CI/CD, IaC, secrets management, deployment safety
team-performance-reviewer	Sonnet 4.6	Cross-system bottlenecks, capacity, hot paths
team-accessibility-reviewer	Sonnet 4.6	WCAG, semantic HTML, keyboard support
team-observability-reviewer	Sonnet 4.6	Logging, metrics, tracing, alertability
team-privacy-compliance-reviewer	Sonnet 4.6	PII handling, GDPR-style rights, retention
team-data-ml-reviewer	Sonnet 4.6	Data quality, training correctness, reproducibility

Stage 3 — Leadership (2)

Persona	Model	Output style
lead-senior-architect	Opus 4.7	ADR-style verdict (Context / Decision / Consequences / Recommendation)
lead-project-manager	Opus 4.7	Aim alignment grade + scope discipline memo

Each persona prompt is 250–400 lines of authored content covering identity, lens, in-scope concerns, out-of-scope delegation, output contract, reasoning approach, anti-patterns, and few-shot examples grounded in the test fixtures. See agents/ for all 25 agent definitions (23 personas + Profiler + Aggregator).

---

What the output looks like

Live terminal stream while running: