# architecture-reviewer

The architecture-reviewer subagent for Claude Code independently checks architectural documents against repository code. It verifies declared structures, not runtime behavior.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 155 repo stars
- Author: serpro69
- License: Elastic-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/serpro69/claude-toolbox/tree/HEAD/klaude-plugin/agents/architecture-reviewer.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/architecture-reviewer

## What it does

The subagent executes in structural isolation from the design authoring session. It has zero access to conversational history, discarded drafts, or file-writing tools, which eliminates confirmation bias. Operations are strictly limited to file reading, search via `Grep` and `Glob`, and knowledge retrieval through `capy_search`.

Execution follows three rigid stages. First, the reviewer parses the text in a repo-blind extraction pass to list every explicit claim. Next, it verifies the existence and topological layout of declared entities in the codebase, such as a database column or a specific endpoint. It explicitly leaves behavioral validity under retries or edge cases to code-review tools.

Without a valid absolute plugin path in its prompt, execution halts immediately because the agent lacks shell execution and cannot expand environment variables. Security boundaries, permission modeling, and data classification are routed out to dedicated security tools rather than handled directly.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add serpro69/claude-toolbox
```
In the agent chat (not a shell):
```text
/plugin install kk@claude-toolbox
```

2. **Manually: put the files in place**
- File: `.claude/agents/architecture-reviewer.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/architecture-reviewer.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/architecture-reviewer.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/serpro69/claude-toolbox/tree/HEAD/klaude-plugin/agents/architecture-reviewer.md

## When to use it
- verify ADR assertions against declared repository layout
- evaluate reversibility and reasoning soundness in design docs
- detect missing infrastructure mechanisms referenced in specifications
- audit composite domain glossary and constraint kits

## Example prompts
- Run an architecture review on `docs/adr/0004-idempotency.md`
- Validate the architecture section of `docs/design/billing-v2.md` against codebase
- Audit domain reference files in `docs/domain/` for missing links

## Similar
- [System Architecture Reviewer](https://affpapa.org/en/nevibecode/agents/system-architecture-reviewer.md) — subagent · ★ 1627 repo stars
- [architecture-decision](https://affpapa.org/en/nevibecode/skills/architecture-decision.md) — skill · 505 installs
- [architecture-review](https://affpapa.org/en/nevibecode/skills/owainlewis-architecture-review.md) — skill · 347 installs
- [create-architecture-documentation](https://affpapa.org/en/nevibecode/commands/create-architecture-documentation.md) — command · 6136 installs
- [oma-architecture](https://affpapa.org/en/nevibecode/skills/first-fluke-oma-architecture.md) — skill · ★ 1472 repo stars
- [create-architecture](https://affpapa.org/en/nevibecode/skills/create-architecture.md) — skill · 651 installs

From the same set: [serpro69/claude-toolbox](https://affpapa.org/en/nevibecode/by/serpro69/claude-toolbox.md) — 30 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
