# review-architecture

review-architecture is a Claude Code skill that checks a written architecture artifact against the system it describes.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 155 repo stars
- Author: serpro69
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/serpro69/claude-toolbox/tree/HEAD/kodex-plugin/skills/review-architecture/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/review-architecture

## What it does

Point it at one committed artifact and it turns the prose into a set of claims. Each claim is then checked for whether the named mechanism exists and sits in the right place: module boundaries, who owns which data, NFR mechanisms, failure isolation, state consistency, versioning, binding to the domain. A second pass grades the decisions against the context the artifact states for itself.

The checking runs in a read-only `architecture-reviewer` subagent. The skill owns acceptance and presentation, so it relays the full claim table, the per-dimension verdicts and the Not Reviewed section. Compressing that report throws away the inspectable middle artifact the claim set exists to be.

One artifact per call: `$kk:review-architecture <artifact-path>`. Diagrams need prose beside them, and two paths at once are rejected. For a domain-reference kit, pass either page and the glossary/traps counterpart is found automatically. Runtime behaviour is not its job: that is `$kk:review-code` and `$kk:review-spec`. Security architecture goes to `mcp__pal__secaudit`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill review-architecture -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/review-architecture/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/review-architecture/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill review-architecture -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/review-architecture/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill review-architecture -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/review-architecture/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install serpro69/claude-toolbox kodex-plugin/skills/review-architecture
```

2. **Manually: put the files in place**
- File: `.github/skills/review-architecture/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill review-architecture -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/serpro69/claude-toolbox --path kodex-plugin/skills/review-architecture
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/review-architecture/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

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/kodex-plugin/skills/review-architecture/SKILL.md

## When to use it
- catch an ADR that names a mechanism the system does not have
- review a glossary and its traps page as one composite artifact
- get a verdict per dimension instead of a single overall grade
- judge how reversible a decision is before building on it
- route security architecture to `mcp__pal__secaudit` on its own track

## Example prompts
- Run `$kk:review-architecture <artifact-path>` on the ADR in `docs/adr/` and relay the report in full.
- Review only the architecture section of the design doc under `docs/feat/wip/`.
- Review `docs/domain/<context>.md` as a composite together with its traps page.

## Similar
- [architecture-review](https://affpapa.org/en/nevibecode/skills/owainlewis-architecture-review.md) — skill · 347 installs
- [adr-review](https://affpapa.org/en/nevibecode/skills/adr-review.md) — skill · 747 installs
- [architecture-compass](https://affpapa.org/en/nevibecode/skills/architecture-compass.md) — skill · 2700 installs
- [architecture-decision](https://affpapa.org/en/nevibecode/skills/architecture-decision.md) — skill · 505 installs
- [Python Backend Architecture Review](https://affpapa.org/en/nevibecode/skills/python-backend-architecture-review.md) — skill · 528 installs
- [code-architecture-review](https://affpapa.org/en/nevibecode/skills/code-architecture-review.md) — skill · 270 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
