Skip to main content
subagent CX Codex

arch-reviewer — Claude Code subagent: what it does, how to install

arch-reviewer inspects project files for layer boundary violations, circular dependencies, and dead imports without modifying code.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What arch-reviewer does

This subagent operates in strict read-only mode using Read, Grep, and Glob. Editing and execution capabilities like Edit, Write, Bash, and NotebookEdit are explicitly blocked in its settings, preventing accidental code changes during reviews.

Before scanning code, the agent inspects AGENTS.md, checks CLAUDE.md if present, and looks into .claude/rules/ for extra constraints. It checks four areas: import layer boundaries, pattern compliance, dead imports, and circular module references. Every finding gets reported with an exact file:line citation, sorted into critical boundary violations or pattern warnings.

Because the agent derives all validation logic from documentation, running it without defined rules in AGENTS.md or CLAUDE.md produces no meaningful verification.

What it helps with

  • detect forbidden cross-layer imports across modules
  • identify circular dependencies between project packages
  • locate unused imports across specified directories
  • audit code adherence to rules defined in AGENTS.md

Example prompts for the agent

  • Run arch-reviewer on src/api to check for layer violations
  • Check the repository for circular dependencies using arch-reviewer
  • Review new services against architectural patterns in AGENTS.md with arch-reviewer

How to install arch-reviewer

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

2Manually: put the files in place

.claude/agents/arch-reviewer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about arch-reviewer

How to install arch-reviewer in Claude Code?

First register the source with /plugin marketplace add SethGammon/Citadel, then run /plugin install citadel@citadel-local. Alternatively, place the agent definition directly into .claude/agents/arch-reviewer.md.

Does arch-reviewer modify source files?

No, it is strictly read-only. Modification tools like Edit and Write are disallowed, so the subagent reports issues without applying fixes.

Where does arch-reviewer look for architecture guidelines?

It reads AGENTS.md first, inspects CLAUDE.md if available, and scans any supplemental rule definitions stored under .claude/rules/.

Source text

arch-reviewer.md · MIT
---
name: arch-reviewer
description: >-
  Read-only architecture reviewer. Checks files for boundary violations,
  import rule breaks, and pattern compliance. Does not modify files.
maxTurns: 50
effort: medium
disallowedTools:
  - Edit
  - Write
  - Bash
  - NotebookEdit
tools:
  - Read
  - Grep
  - Glob
---

# Architecture Reviewer

You are a read-only architecture reviewer. You check code for compliance with
the project's architectural rules defined in AGENTS.md (or CLAUDE.md).

## What You Check

1. **Import boundaries**: Do imports follow the project's layer rules?
2. **Pattern compliance**: Are established patterns followed consistently?
3. **Dead imports**: Are there unused imports?
4. **Circular dependencies**: Do modules create import cycles?

## How You Work

1. Read AGENTS.md, then CLAUDE.md if it also exists, to understand the project's architecture rules
2. Read any files in `.claude/rules/` for additional constraints
3. Scan the specified files or directories
4. Report violations with specific file:line references
5. Categorize: critical (boundary violation) vs warning (pattern inconsistency)

## Output Format

```
=== Architecture Review ===

CRITICAL:
  src/api/users.ts:15 — imports from src/frontend/ (layer violation)

WARNING:
  src/utils/helpers.ts:3 — unused import: lodash

CLEAN: 12 files checked, 1 critical, 1 warning
```

## Rules

- You NEVER modify files. Read-only.
- You ALWAYS cite specific file:line numbers.
- You ALWAYS read the project guidance (AGENTS.md, then CLAUDE.md) first.
- You report what you find. You do not fix it.

© SethGammon · MIT · SethGammon/Citadel

Similar subagents

All subagents for Code review and refactoring →

From the same set55

The whole set →
knowledge-extractor The knowledge-extractor subagent saves reusable patterns, pitfalls, and decisions from finished work for a project wiki. Run it after completing a substantial piece of work. CX Codex ★ 937repo stars session-handoff session-handoff turns the current session into a structured HANDOFF block so the next session can pick up work without re-auditing the project. CX Codex +1 ★ 937repo stars verify verify — a skill to self-test the Citadel hook pipeline during a live session. Exercises real tool calls (Write, Edit, Bash, Read), verifies that hooks fire, telemetry accumulates, and no errors occur. CX Codex +1 ★ 937repo stars unharness unharness is a Claude Code skill that plans Citadel removal from a project and keeps a portable archive. It runs on requests to remove Citadel or clean up the harness. CX Codex +1 ★ 937repo stars grill grill turns a vague plan into a sharp technical spec through one-question-at-a-time interview, each with a default answer you edit. CX Codex +1 ★ 937repo stars autopilot autopilot processes queued tickets from .planning/intake/ through automated research, implementation, and verification. CX Codex +1 ★ 937repo stars doc-gen doc-gen generates function comments, directory READMEs, and API references while following the project’s existing conventions. Use it when docs should explain code behavior rather than repeat signatures. CX Codex +1 ★ 937repo stars policy-enforcer policy-enforcer is a Claude Code subagent that checks proposed actions against Citadel’s rules and returns an allow-or-block verdict. Archon and Fleet spawn it before actions with low reversibility. CX Codex ★ 937repo stars

Project sponsors

Companies that keep this analytics open