ai-software-architectSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

# In Claude Code, run these commands:
/plugin marketplace add codenamev/ai-software-architect
/plugin install ai-software-architect@ai-software-architect

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: architecture-review
description: Conducts a comprehensive multi-perspective architecture review using ALL architecture team members. Use when the user requests "Start architecture review", "Full architecture review", "Review architecture for version X.Y.Z", "Conduct comprehensive review", or when they want assessment from multiple perspectives. Do NOT use for single-specialist reviews (use specialist-review instead) or for status checks (use architecture-status instead).
allowed-tools: Read,Write,Glob,Grep,Bash(git:*),Agent
---

# Architecture Review (orchestrator)

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](../../.architecture/decisions/adrs/ADR-013-skill-orchestrator-subagent-delegation.md) for the rationale.

## Process

### 1. Determine scope

Identify the review target from the user's request:
- **Version** — "version 2.0.0" → filename `2-0-0.md`
- **Feature** — "authentication feature" → filename `feature-authentication.md`
- **Component** — "payments module" → filename `component-payments-module.md`

Apply input sanitization from [`../_patterns.md`](../_patterns.md). If the scope is ambiguous, ask one clarifying question and stop.

### 2. Load team and config

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`.

### 3. Optional pre-analysis (orchestrator-side)

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.

### 4. Dispatch subagents in parallel

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).`

### 5. Aggregate

When all subagent calls return, build the consolidated review:

1. **Cross-cut analysis** — identify themes that appear in 3+ subagent reviews (these are the high-leverage findings).
2. **Conflict resolution** — when two subagents disagree (e.g., security wants strict validation, performance wants minimal overhead), surface the disagreement explicitly under "Trade-offs" rather than picking a winner. Naming the trade-off is the value.
3. **Prioritization** — bucket every concern into Critical (0-2 weeks) / Important (2-8 weeks) / Nice-to-Have (2-6 months) based on the subagents' severity ratings and the cross-cut analysis.
4. **Verbatim per-perspective sections** — preserve each subagent's full review under a per-member section. This is the source data; aggregation summarizes but does not replace it.

### 6. Write the consolidated review

Use [the review template](assets/review-template.md). Key sections:

- Executive summary (3-5 sentences, overall assessment + top concerns)
- Individual member reviews (verbatim from step 5.4)
- Cross-cutting themes (from step 5.1)
- Trade-offs and disagreements (from step 5.2)
- Prioritized recommendations (from step 5.3)
- Risks if unaddressed (highest-severity items)
- Success metrics and follow-up plan

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`](references/pragmatic-integration.md).

### 7. Report to the user

```
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 

SAFEgrade B · trust 88/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

not all pinned

Secrets in source

none-found

Findings (14)

.coding-assistants/claude-code/claude-code.md

cp -r ../../.architecture ./.architecture

cp -r ../../.coding-assistants ./.coding-assistants

import { ArchitectureServer } from '../../mcp/index.js';

import { ArchitectureServer, renderAdrFromTemplate } from '../../mcp/index.js';

const result = generateSubagent({ ...SAMPLE_MEMBER, id: '../../.claude/hooks/evil' });

@modelcontextprotocol/sdk, yaml, fs-extra, @types/node

yaml

- **Security**: No tool restrictions (implicit full access)

- Issue: No `allowed-tools` in frontmatter means implicit full access

Our Claude Skills currently have implicit unlimited access to all available tools (Read, Write, Edit, Bash, Glob, Grep, etc.). When a skill is activated, it can use any tool without restriction. This

- Implicit full access to Read, Write, Edit, Bash, Glob, Grep, etc.

# setup-architect - Full access (installation requires broad permissions)

Gates applied: no_behavioural_pass, no_license.