Orchestrates parallel reviews from all architecture specialist subagents, aggregates into consolidated report for full multi-perspective assessments.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-software-architect:architecture-reviewThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Comprehensive multi-perspective architecture review. This skill is an **orchestrator** — it dispatches one subagent invocation per active team member in parallel, then aggregates the returned reviews into a consolidated document. The deep-perspective work happens in the subagents (`agents/<id>.md`), not in this skill's main thread.
Comprehensive multi-perspective architecture review. This skill is an orchestrator — it dispatches one subagent invocation per active team member in parallel, then aggregates the returned reviews into a consolidated document. The deep-perspective work happens in the subagents (agents/<id>.md), not in this skill's main thread.
See ADR-013 for the rationale.
Identify the review target from the user's request:
2-0-0.mdfeature-authentication.mdcomponent-payments-module.mdApply input sanitization from ../_patterns.md. If the scope is ambiguous, ask one clarifying question and stop.
Read .architecture/config.yml and .architecture/members.yml:
config.yml.pragmatic_mode.enabled decides whether to include the pragmatic_enforcer subagent.members.yml.members[] is the list of subagents to dispatch.Each member's id (e.g., security_specialist) maps to agents/<kebab-id>.md (e.g., agents/security-specialist.md). The drift check in CI guarantees these files exist and are in sync.
Active set: every member in members.yml, excluding pragmatic_enforcer if config.yml.pragmatic_mode.enabled == false.
For broad reviews, an initial scan helps the orchestrator give every subagent a shared starting context. Use Glob, Grep, and Bash(git:*) (e.g., git log --oneline -20, git diff main...HEAD --stat) to assemble a short brief: target description, recent activity, key files. Keep this brief under ~500 tokens — it's a shared header, not a review.
If the review target is narrow (a single feature or ADR), this step can be skipped.
Issue one Agent call per active member, all in the same response (parallel dispatch is the documented best practice for independent work):
Agent({
subagent_type: "<kebab-id>",
description: "<Title> review of <target>",
prompt: <see template below>
})
Prompt template (used for every subagent — vary only the <target> and the optional shared brief):
Conduct a focused review of: <target>.
<optional shared brief from step 3>
Apply your perspective (your subagent file lists your specialty,
disciplines, skillsets, and domains). Stay within your specialty —
other team members are reviewing concurrently and will cover their
own areas.
Return a markdown review with:
- Perspective statement (1-2 sentences from your unique vantage)
- Key observations (3-5)
- Strengths within your domain (3-5)
- Concerns with severity (critical / high / medium / low), each with
location (file:line where applicable), why-it-matters, concrete fix
- Recommendations, ordered: immediate / short-term / long-term, with
rough effort estimates (S/M/L)
- Risks if unaddressed
Read code, configs, and ADRs as needed via your scoped tools. Cite
exact file paths and line numbers. Do not range outside your
specialty.
For pragmatic_enforcer (when included), append: Apply the Pragmatic Enforcer Analysis structure from .architecture/templates/adr-template.md (Necessity, Complexity, Ratio, Recommendation).
When all subagent calls return, build the consolidated review:
Use the review template. Key sections:
Save to .architecture/reviews/<filename> (filename from step 1).
If pragmatic mode is enabled, ensure the pragmatic_enforcer review's Necessity / Complexity / Ratio analysis is surfaced in the executive summary, not buried in the member section. See references/pragmatic-integration.md.
Architecture Review Complete: <target>
Location: .architecture/reviews/<filename>
Overall Assessment: <Strong | Adequate | Needs Improvement>
Top 3 priorities:
1. <Critical priority>
2. <Critical priority>
3. <Important priority>
Immediate actions:
- <Highest-severity concrete fix>
- <Next>
Cross-cutting themes:
- <Theme that appeared in 3+ specialist reviews>
Next steps:
- Review with team
- `create-adr` for the priorities that need a decision recorded
- `specialist-review` to deep-dive any concern that needs more work
The previous version (~130 lines) inlined the review process for each persona. With subagents, persona and per-perspective review structure live in agents/<id>.md (generated from members.yml). This skill's job is the orchestration layer: scope, dispatch, aggregate, write, report.
One source of truth per concept — the framework principle holds. Specialist behavior lives in the subagent files, not duplicated here.
Before: architecture-status (what's already documented), list-members (who is on the team)
During: specialist-review (deep-dive any single subagent's findings)
After: create-adr (record decisions arising from priorities), architecture-recalibration (translate findings into a plan)
npx claudepluginhub codenamev/ai-software-architect --plugin ai-software-architectPerforms systematic architecture reviews across 7 dimensions (structural, scalability, enterprise readiness, performance, security, ops, data) with scored reports and prioritized recommendations.
Lead effective architecture reviews. Manage discussions, surface disagreements, build consensus, document decisions. Use when conducting reviews or running architecture forums.
Analyzes any codebase's architecture with 6 specialist agents (perf/scale, reliability, security, ops/DX, data/deps + Codex cross-review). Agents debate risks, fragile spots, improvements for audits/refactors.