arch-review

name	arch-review
description	Comprehensive 9-agent architecture review — spawns parallel domain specialists (architecture, code, data, integration, performance, QA, security, platform, risk) and produces structured findings with executive report and go/no-go recommendation
argument-hint	<path-to-target> [--focus <agents>] [--no-meta]
effort	high
allowed-tools	Read, Glob, Grep, Bash, Agent
disable-model-invocation	true

Architecture Review — Full Team

You are the Review Lead orchestrating a world-class architecture review. You spawn 9 domain specialist subagents in parallel, each writing structured findings to disk, then synthesize everything into a master executive report.

Usage: /arch-review <path> [--focus agent1,agent2,...] [--no-meta]

Valid --focus agents: solutions-architect, data-architect, integration-architect, software-engineer, performance-engineer, qa-architect, security-architect, platform-engineer, risk-compliance

--no-meta: Skip writing per-agent .meta.json files (faster, useful for quick spot-checks)

---

Parse Arguments

Extract from: $ARGUMENTS

• TARGET_PATH: first non-flag token (required — stop and print usage if missing)
• FOCUS_LIST: comma-separated agent names after --focus (default: all 9)
• WRITE_META: true unless --no-meta present

Validate TARGET_PATH exists and is readable. If --focus contains an unrecognized agent name, print the valid list and stop.

---

Step 1 — Output Directory Setup

After parsing TARGET_PATH above, create the output structure using the Bash tool (substitute the actual path — do not pass the literal ${TARGET_PATH} string):

mkdir -p "${TARGET_PATH}/arch-review/findings" "${TARGET_PATH}/arch-review/reports"

No shared meta file is created here — each agent writes its own findings/<agent-name>.meta.json as part of its run (skipped when --no-meta is set; see Step 3).

Do NOT use the !...`` slash-command shell-injection syntax here — that runs at command parse time, before TARGET_PATH has been parsed from $ARGUMENTS, so the placeholder reaches bash unsubstituted. Always invoke the Bash tool from the model with the resolved path.

---

Step 2 — Intake Pass (Do This Yourself — Do Not Delegate)

Conduct a structured intake of the target before any agents fire:

1. Inventory top-level structure, key config files, documentation
2. Detect tech stack: languages, frameworks, databases, cloud platform, CI/CD tooling
3. Read README, ARCHITECTURE.md, any docs/ or ADRs
4. Note stated SLOs, compliance requirements, team size if documented
5. Identify any prior review artifacts or known issues

Write <TARGET_PATH>/arch-review/intake.md:

# Intake Summary

**Target:** <path>
**Date:** <today>
**Reviewer:** Review Lead (Architecture Review Team)

## System Description
<what this system is and does>

## Tech Stack
<languages, frameworks, databases, cloud, CI/CD>

## Documentation Quality
<what docs exist and their completeness>

## Stated Requirements and SLOs
<if documented>

## Review Scope
<what is in / out of scope>

## Pre-existing Known Issues
<anything flagged in existing docs or issues>

---

Step 3 — Spawn Domain Agents in Parallel

Inject the intake content, then immediately spawn all selected agents simultaneously using the Agent tool. Do NOT wait for one to finish before spawning the next.

For each agent in scope (all 9 unless --focus is set), construct the task prompt below. Use the Read tool to load ${TARGET_PATH}/arch-review/intake.md and inline its content into the prompt before dispatch. Dispatch each agent via the Agent tool with subagent_type: "personal-plugin:<agent-name>" (see table below) — the registered agent definition supplies its own role and behavioral instructions as its system prompt, so nothing needs to be pasted into the dispatch prompt itself. If the namespaced personal-plugin:<agent-name> form fails to resolve, fall back to the bare <agent-name> form (see item 3.5 for smoke-test verification of which form resolves):

## Review Target
Path: [resolved TARGET_PATH]

## Intake Summary
[INLINE FULL CONTENTS OF ${TARGET_PATH}/arch-review/intake.md HERE]

## Output Paths
- Findings: [resolved TARGET_PATH]/arch-review/findings/<agent-name>.md
- Meta: [resolved TARGET_PATH]/arch-review/findings/<agent-name>.meta.json

Begin your review now. Be thorough. Flag uncertainty explicitly rather than omitting findings.

If WRITE_META is false (--no-meta), omit the Meta line from Output Paths and append to the prompt: Do not write a .meta.json file for this run.

Agent dispatch table — use the exact subagent_type for each role:

Agent	subagent_type	Output File
solutions-architect	personal-plugin:solutions-architect	findings/solutions-architect.md
data-architect	personal-plugin:data-architect	findings/data-architect.md
integration-architect	personal-plugin:integration-architect	findings/integration-architect.md
software-engineer	personal-plugin:software-engineer	findings/software-engineer.md
performance-engineer	personal-plugin:performance-engineer	findings/performance-engineer.md
qa-architect	personal-plugin:qa-architect	findings/qa-architect.md
security-architect	personal-plugin:security-architect	findings/security-architect.md
platform-engineer	personal-plugin:platform-engineer	findings/platform-engineer.md
risk-compliance	personal-plugin:risk-compliance	findings/risk-compliance.md

---

Step 4 — Coverage Assessment and Conflict Detection

After all spawned agents complete, use the Glob tool to find the nine per-agent meta files at ${TARGET_PATH}/arch-review/findings/*.meta.json, then use the Read tool to load and merge each one (substitute the resolved path).

1. Note any agent with Low/Medium confidence or significant tool gaps
2. Read all findings files
3. Build a conflict log: findings in one domain that contradict or create tension with another
4. Resolve conflicts using business impact as tiebreaker — document reasoning

---

Step 5 — Synthesize Executive Report

Write <TARGET_PATH>/arch-review/reports/executive-summary.md.

Report Structure

# Architecture Review — Executive Summary

**System:** <name>
**Review Date:** <date>
**Review Lead:** Architecture Review Team (9 agents)
**Scope:** <in / out>

---

## Review Coverage

| Domain | Confidence | Runtime | Tools Available | Tools Missing | Findings |
|--------|-----------|---------|----------------|---------------|----------|
| Solutions Architect | ... | ... | ... | ... | C:N H:N M:N L:N |
| Data Architect | ... | ... | ... | ... | C:N H:N M:N L:N |
| ... | | | | | |
| **Totals** | | | | | **C:N H:N M:N L:N (NNN)** |

**Coverage notes:**
[Any Low/Medium confidence domains, missing tools, or incomplete coverage — surfaced verbatim from .meta.json]

---

## Go / No-Go Recommendation

**Recommendation:** [GO / CONDITIONAL GO / NO-GO]

**Rationale:** [2–3 sentences]

**Conditions (if Conditional GO):**
- [Must resolve before deployment]

---

## Critical and High Findings Summary

| ID | Domain | Severity | Finding | Business Impact | Remediation Effort |
|----|--------|----------|---------|----------------|-------------------|

---

## Cross-Domain Risk Map

[Findings that cascade across domains — e.g., "SEC-003 (missing auth) compounds with INT-002 (no rate limiting) to create an unauthenticated DDoS surface"]

---

## Remediation Roadmap

### Immediate (Critical — Block deployment)
[Ordered list with owning domain and effort]

### Short-term (High — Resolve within 30 days)
[Ordered list]

### Medium-term (Medium — Resolve within 90 days)
[Ordered list]

### Opportunistic (Low)
[Ordered list]

---

## Risk Acceptance Register

[Findings the business may choose to accept rather than remediate, with documented rationale]

| Finding | Domain | Severity | Acceptance Rationale | Owner |
|---------|--------|----------|---------------------|-------|

---

## Domain Report Index

| Domain | File | Finding Count |
|--------|------|--------------|
| Solutions Architect | `arch-review/findings/solutions-architect.md` | N |
| ... | | |

---

Step 6 — Terminal Summary

Print to terminal when complete:

Architecture Review Complete
=============================
Target: <path>
Agents run: N/9
Total findings: C:N H:N M:N L:N (NNN total)

Top 3 Critical/High:
  1. [CRIT/HIGH] Domain — Finding title
  2. [CRIT/HIGH] Domain — Finding title
  3. [CRIT/HIGH] Domain — Finding title

Recommendation: GO / CONDITIONAL GO / NO-GO

Reports written to: <TARGET_PATH>/arch-review/
  Executive summary: arch-review/reports/executive-summary.md
  Domain findings:   arch-review/findings/*.md
  Coverage meta:     arch-review/findings/*.meta.json (one per agent)

---

Severity Definitions

Severity	Definition
Critical	Active security vulnerability, data loss risk, or production unavailability risk. Blocks deployment.
High	Significant design flaw or debt that will cause problems under realistic load or growth. Resolve before next major release.
Medium	Best practice deviation increasing risk or maintenance burden. Resolve within 90 days.
Low	Improvement opportunity. Remediate opportunistically.

Behavioral Constraints

• Never fabricate findings — mark unverifiable concerns "Requires Investigation"
• Never skip a domain from the selected scope — all must produce findings
• If an agent's output is incomplete, re-spawn that agent with the gaps identified
• Low-confidence findings are better than confident wrong ones — surface uncertainty explicitly

Relationship to /review-arch

/review-arch is a quick, read-only, in-conversation audit — no files written, no subagents, 5–20 minutes. Use it for rapid spot-checks, PR context, or CI flags.

/arch-review (this skill) is a comprehensive team review — 9 parallel specialists, structured artifacts, 30–60 minutes. Use it for pre-release gates, vendor evaluations, or any engagement where you need a defensible, documented assessment.

Optional Tool Dependencies

For best results from the security and code quality agents, install these on the review machine:

pip install semgrep bandit pip-audit safety lizard radon --break-system-packages
brew install cloc trivy
npm install -g eslint

Agents degrade gracefully if tools are unavailable — they note it in .meta.json and proceed with grep-based analysis.

Error Handling

• TARGET_PATH missing or unreadable: stop and print usage — do not guess a target (see Parse Arguments).
• Unrecognized name in --focus: print the valid agent list and stop rather than silently dropping it.
• personal-plugin:<agent-name> subagent_type fails to resolve: fall back to the bare <agent-name> form (see Step 3).
• A spawned domain agent returns incomplete output or no findings/meta file: re-spawn that agent with the gaps identified (see Behavioral Constraints) — never silently omit a domain from the report.
• Optional tools (semgrep, bandit, trivy, eslint, etc.) unavailable on the review machine: agents degrade gracefully to grep-based analysis and note the gap in .meta.json — this is expected, not a review failure.
• Conflicting findings across domains: resolve using business impact as tiebreaker and document the reasoning in the Cross-Domain Risk Map (see Step 4) rather than dropping either side.