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

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

How to Run

# 1. Write a DONE_WHEN brief
cat > /tmp/brief.md \x3C\x3C 'EOF'
Goal: \x3Cwhat this build accomplishes>
Scope: \x3Cwhat files/systems are touched>
Done when: \x3Cspecific acceptance criteria>
EOF

# 2. Run the critic
bash ~/.openclaw/workspace/skills/architecture-critic/scripts/run-critic.sh \
  --task "Brief description of the build" \
  --done-when /tmp/brief.md \
  --repo /path/to/your/repo

Or let your agent run it automatically — see the Agent Integration section below.

Verdicts

Verdicts are saved to specialists/critic-verdicts/YYYY-MM-DD-\x3Cslug>.md in your workspace.

Agent Integration

Add this to your AGENTS.md or agent instructions:

## Architecture Critic — MANDATORY GATE
Before any significant build (new endpoint, schema change, payment/auth touch, >3 files):
1. Write the DONE_WHEN brief to a temp file
2. Run: bash ~/.openclaw/workspace/skills/architecture-critic/scripts/run-critic.sh \
        --task "\x3Cdescription>" --done-when \x3Cfile> [--repo \x3Cpath>]
3. APPROVE → proceed
4. REVISE → fix findings, re-run (max 2 cycles)
5. REJECT → stop, escalate to human

Skip only for: copy/style-only changes \x3C3 files no logic, isolated bug fixes no payment/auth.

How It Works

The critic script:

1. Snapshots the relevant codebase state (file tree + key files)
2. Combines it with your DONE_WHEN brief into a structured prompt
3. Spawns an isolated agent at temperature 0 — no creativity, no encouragement
4. The agent runs the checklist against your plan
5. Returns a verdict with specific, itemized findings
6. Saves the verdict to your workspace

The critic agent never sees your conversation history, your enthusiasm, or the proposer's reasoning. It sees only the spec and the code.

LLM Compatibility

Works with any LLM configured in your OpenClaw instance:

• Anthropic (Claude Sonnet, Haiku)
• OpenAI (GPT-4o, GPT-4 Turbo)
• Google (Gemini)
• Local models via Ollama

The script reads your OpenClaw config to find the active model and API key. No separate configuration required.

Checklist Coverage

The critic reviews against domain-specific checklists:

• Web (references/checklist-web.md) — routes, caching, deployment config, breaking changes
• Security (references/security.md) — auth bypass, injection, secrets, CORS, OWASP Top 10
• Payment flows (references/payment-flows.md) — webhooks, idempotency, race conditions, PCI scope
• AI builds (references/ai-builds.md) — prompt injection, hot paths, token costs, fallback handling
• General (references/checklist-general.md) — scope creep, dependencies, rollback, data migration

Pass --checklist references/security.md to focus on a specific domain, or let the critic auto-select based on your brief.

Files

architecture-critic/
├── SKILL.md                      # This file
├── README.md                     # GitHub-facing docs
├── LICENSE                       # MIT
├── scripts/
│   └── run-critic.sh             # Main runner script
└── references/
    ├── checklist-web.md          # Web/API checklist
    ├── checklist-general.md      # General architecture checklist
    ├── security.md               # Security checklist
    ├── payment-flows.md          # Payment/billing checklist
    └── ai-builds.md              # AI/LLM-specific checklist