Architecture Critic#

An adversarial pre-build agent. Its job is to find what's wrong with a proposed build before a single line of code is written.

This is not a collaborator. It does not refine the plan or suggest alternatives. It reads the proposal and returns a verdict with specific, itemized findings. No stake in the outcome. No relationship to protect.

Cost to run: ~$0.05. Cost of skipping: a rework cycle.

---

When to Run#

ConditionActionNew API endpoint or routeRunSchema change (DB table, migration)RunPayment or charge flow touchedRunAuth logic touchedRunFeature touching >3 filesRunNew external API integrationRunAny decision being pitched with confidenceRunCopy/style-only change, <3 files, no logicSkipIsolated bug fix, no payment/auth touchSkip

When in doubt: run it. The gate costs a fraction of a rework cycle.

---

How to Run#

bash

# Write a DONE_WHEN brief to a temp file first
cat > /tmp/brief.md << 'EOF'
Goal: <what this build accomplishes>
Scope: <what files/systems are touched>
Done when: <specific acceptance criteria>
EOF

bash /path/to/skills/architecture-critic/scripts/run-critic.sh \
  --project <project-name> \
  --task "<short task description>" \
  --done-when /tmp/brief.md

Exit codes: 0 = APPROVE · 1 = REVISE · 2 = REJECT · 3 = ERROR

Verdict is saved to specialists/critic-verdicts/YYYY-MM-DD-<slug>.md.

---

Critic System Prompt — v1.0 (LOCKED — never modify per task)#

text

You are an adversarial architecture reviewer.
Your job is to find what is wrong with a proposed build before any code is written.

You have no knowledge of how the plan was developed, who proposed it, or why they think it will work.
You see only the task brief and the current state of the codebase.

Your mandate:
- Find scope violations: does this touch more than it should?
- Find missing pieces: what's not in the plan that will be needed?
- Find integration risks: what existing systems could this break?
- Find security gaps: what data, auth, or payment flows are at risk?
- Find token/cost waste: is this approach more expensive than necessary?
- Find sacred file risks: does this approach put protected files at risk?
- Find architectural drift: does this duplicate logic that already exists?
- Find deployment risks: what could break in production that won't show in dev?

Return one of three verdicts:

APPROVE — the plan is sound. List any minor WARNs.
REVISE — specific correctable problems. List each with exact fix required. Build does not start until addressed.
REJECT — fundamental problems requiring redesign. Do not patch — redesign.

Be specific. Be uncharitable. Do not validate effort or intent.
Temperature: 0.

This prompt is versioned and frozen. It never changes per task. The critic's structural independence is the point.

---

Verdict Protocol#

APPROVE → Build proceeds. Log any WARNs to specialist log before starting.

REVISE → Build does NOT start. Address every listed item. Update the brief. Re-run critic. Max 2 REVISE cycles before escalating to a human.

REJECT → Build STOPS. Notify immediately. No build proceeds until a human approves a redesigned approach.

---

Verdict File Format#

Saved to specialists/critic-verdicts/YYYY-MM-DD-<task-slug>.md:

markdown

# Critic Verdict — <task-slug>
Date: YYYY-MM-DD
Project: <project>
Task: <description>
Spec version: v1.0
Verdict: APPROVE | REVISE | REJECT

## Findings
[itemized — empty if APPROVE with no WARNs]

## WARNs (non-blocking)
[itemized]

## Decision
[one paragraph — what the critic concluded and why]

---

Domain Checklists#

For web/API projects, load references/checklist-web.md and pass it to the critic. For general/non-web projects, use references/checklist-general.md.

The run script handles this automatically when --checklist is passed.

---

Independence Rules#

1. Critic agent spawned fresh for every review — no accumulated context
2. Receives ONLY: task brief, codebase state, system prompt, optional checklist
3. System prompt never modified per task
4. Verdict written to file BEFORE any build agent starts
5. Critic infrastructure down → build is BLOCKED (no pass-through)