codenamev avatar

ai-software-architect

AI-powered architecture documentation framework with ADRs, reviews, and pragmatic mode

version
1.6.0
GitHub stars
80

Install

/plugin install ai-software-architect@ai-software-architect

Run it inside Claude Code after adding the marketplace with /plugin marketplace add codenamev/ai-software-architect.

Contents

Discovered from source

Skills 8

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

Also read .architecture/principles.md. It is the project's recorded constitution, and every review is checked against it: step 4 hands it to each member, step 6.5 collects what they found. If the file is missing, write "no principles recorded" in the review's Principle Conflicts section and skip the gate. Never block a review on it.

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>, the optional shared brief, and the principles block):

Conduct a focused review of: <target>.

<optional shared brief from step 3>

Recorded principles (.architecture/principles.md, the "Core Principles"
section verbatim; drop the quotations above it):
<principles>

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, each with severity (critical / high / medium / low),
  confidence (0.0-1.0), location (file:line where applicable),
  why-it-matters, concrete fix. Confidence is your own estimate that
  the concern is real: 0.9+ means you opened the code and confirmed
  it; 0.5 or below means you are inferring from names, patterns, or
  files you did not read. Never omit it and never round it up.
- Recommendations, ordered: immediate / short-term / long-term, with
  rough effort estimates (S/M/L)
- Risks if unaddressed
- Principle conflicts: every concern above that violates a recorded
  principle, restated as "<principle name>: <one line>". Every
  recommendation that would change or retire a recorded principle,
  labeled PRINCIPLE CHANGE with the principle named. Write "none"
  when there are none. Do not omit the section.
- Unresolved assumptions: anything your concerns or recommendations
  depend on that neither the code, the configs, nor the ADRs settle
  (expected load, who calls an endpoint, whether a constraint is
  still real). One line each: the assumption, the title of the
  concern above that depends on it (as you wrote it under Concerns),
  and the evidence that would settle it. Do not also list the
  assumption under Concerns, and give it no severity. Write "none"
  when there are none. Do not omit the section.

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. Challenge round

The individual reviews are monologues: no member has seen another's findings. Before aggregating, run one adversarial pass over the findings that carry the most weight. This is the collaborative_phase from members.yml, made concrete.

  1. Select every concern rated critical or high across all returned reviews. Medium and low findings skip this round.
  2. Assign a challenger per finding: the active member best positioned to refute it, never its author. Use the members' perspective and domains fields — a security critical demanding mandatory validation goes to performance_specialist; an architectural rewrite goes to pragmatic_enforcer (when active) or maintainability_expert; a domain-model concern goes to systems_architect. When no member is an obvious counterweight, use pragmatic_enforcer if active, otherwise skip the finding and note it as unchallenged.
  3. Dispatch one Agent call per finding, all in the same response:
Agent({
  subagent_type: "<challenger kebab-id>",
  description: "Challenge: <finding title>",
  prompt: <see template below>
})

Challenge prompt template:

Another reviewer (<author title>) rated this finding <critical|high>
in a review of: <target>.

<finding verbatim: issue, location, why-it-matters, recommended fix>

Your job is to attack it from your specialty, not to agree with it.
Check the cited location. Look for evidence that the finding is
overstated, already mitigated, out of scope for this target, or that
its fix costs more than the problem. Return exactly one of:

- NO OBJECTION — one sentence on why it holds.
- DOWNGRADE to <high|medium|low> — the specific evidence, with
  file:line, and what the author missed.
- REFUTE — the specific evidence that the finding is wrong.

Two hundred words maximum. Cite what you read.
  1. Record the outcome on each finding and carry it into aggregation:
    • NO OBJECTION → severity unchanged, annotated challenged by , survived.
    • DOWNGRADE → severity set to the challenger's level, rebuttal recorded verbatim under the finding.
    • REFUTE → finding moved out of the prioritized lists into the Challenges section with the rebuttal verbatim. The author's original text stays in their per-member section untouched.

The orchestrator does not adjudicate. A challenge either produces cited evidence or it does not; the response format forces that choice. Cost is one subagent call per critical/high finding, typically 3-6 per review.

6. Aggregate

When the challenge round returns, first normalize and filter the raw returns (Claude Code 2.1.277+ wraps each return under a "subagent output" header; strip that framing before parsing):

  • Dedup by location. Concerns from different members that point at the same file:line (or the same file when no line is given) and describe the same problem merge into one finding that lists every member who raised it, keeps the highest severity, and takes the highest confidence. Different problems at the same location stay separate.
  • Low-confidence appendix. A concern with confidence below 0.7 that only one member raised goes to the "Low-confidence findings" appendix of the review, not into the sections below. A concern two or more members raised stays in whatever its confidence: independent agreement is evidence. Nothing is deleted; each member's verbatim review (6.4) still carries every concern it returned.

Then build the consolidated review from the filtered set and the post-challenge severities. A merged finding counts once in the cross-cut analysis, with the number of members who raised it noted. That number is the signal, not eight copies of the same line.

  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 on something the challenge round did not settle (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 post-challenge severity ratings and the cross-cut analysis. Refuted findings are excluded here; they appear only under Challenges.
  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.
  5. Principle gate — collect every member's Principle conflicts section into the review's Principle Conflicts table, one row per conflict, principle named. Two rules follow. A concern tied to a recorded principle is never bucketed below Important, whatever its severity rating: the principle already settled that it matters. A PRINCIPLE CHANGE recommendation never enters the prioritized lists at all; it goes under Proposed Principle Changes with a pointer to create-adr, because changing the constitution is a decision to record, not a finding to schedule. Findings refuted in step 5 drop out of the gate with everything else.
  6. Unresolved assumptions — collect every member's Unresolved assumptions section into the "Unresolved assumptions" appendix of the review. Merge the same assumption made by several members into one row listing all of them; an assumption three members leaned on is the one most worth checking. Assumptions are not findings: they get no severity, skip the challenge round, and never enter the prioritized lists. In the "Concerns that rest on it" cell, name each concern by the title it carries in the consolidated review (after dedup), and mark where that concern ended up: (refuted) if the challenge round refuted it, (low-confidence) if it went to the low-confidence appendix, nothing if it is in the prioritized lists. Keep the assumption even when every concern resting on it was refuted; the marker shows that. The orchestrator does not settle assumptions; the row's last column says what evidence would.

7. Write the consolidated review

Use the review template. Key sections:

  • Executive summary (3-5 sentences, overall assessment + top concerns)
  • Individual member reviews (verbatim from step 6.4)
  • Challenges (from step 5: every critical/high finding with its challenger and outcome, rebuttals verbatim)
  • Principle conflicts and proposed principle changes (from step 6.5)
  • Cross-cutting themes (from step 6.1)
  • Trade-offs and disagreements (from step 6.2)
  • Prioritized recommendations (from step 6.3)
  • Risks if unaddressed (highest-severity items)
  • Success metrics and follow-up plan
  • Unresolved assumptions (from step 6.6)
  • Dispositions: every Area for Improvement and every low-confidence row is written with Disposition: pending. The orchestrator never writes accepted, rejected, or deferred; those are the maintainer's calls, made directly or at the point where the review's findings are turned into a plan (recalibration), and a review that ships with them pre-filled has had its judgment made for it.

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.

8. Report to the user

Architecture Review Complete: <target>

Location: .architecture/reviews/<filename>
Overall Assessment: <Strong | Adequate | Needs Improvement>

Challenge round: <n> findings challenged, <s> survived, <d> downgraded, <r> refuted
Principle gate: <c> findings conflict with recorded principles, <p> principle changes proposed

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
- Stamp each finding's Disposition as you rule on it (accepted / rejected: reason / deferred: trigger); recalibration does this for the findings it consumes

Why this skill is small

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, challenge, aggregate, write, report.

One source of truth per concept — the framework principle holds. Specialist behavior lives in the subagent files, not duplicated here.

Related skills

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)

References

Architecture Status

Provides overview of architecture documentation state.

Process

1. Check Framework Setup

If .architecture/ doesn't exist:

The AI Software Architect framework is not set up yet.

To get started: "Setup ai-software-architect"

Once set up, you'll have:
- Architectural Decision Records (ADRs)
- Architecture reviews
- Specialist reviews
- Recalibration tracking

2. Gather Information

Collect from .architecture/:

  • ADRs: Count files in decisions/adrs/, note recent ones, check statuses
  • Reviews: Count files in reviews/, categorize (version/feature/specialist/initial)
  • Recalibration: Count files in recalibration/, check progress docs
  • Comparisons: List files in comparisons/
  • Team: Count members in members.yml
  • Last Activity: Most recent date from any document
  • Framework version: read version.framework_version from .architecture/config.yml (the installed version). When $CLAUDE_PLUGIN_ROOT is set, also read version from $CLAUDE_PLUGIN_ROOT/.claude-plugin/plugin.json (the plugin version). The plugin auto-updates; the installed .architecture/ copy does not, so these drift apart silently.
    • Same version → Framework: 1.6.0 (installed matches plugin)
    • Behind → Framework: installed 1.4.0, plugin 1.6.0 - 2 releases behind; see CHANGELOG 1.5.0…1.6.0 and UPGRADE.md
    • No stamp → Framework: installed unknown (pre-1.2 install), plugin 1.6.0 - see UPGRADE.md
    • No $CLAUDE_PLUGIN_ROOT → report the installed version only.
    • Report only. Never upgrade, rewrite, or restamp .architecture/ from this skill; the upgrade is the user's explicit action.

3. Generate Status Report

# Architecture Framework Status

**Report Date**: [Date]
**Project**: [Project name if known]
**Framework**: [installed X.Y.Z / plugin X.Y.Z drift line from step 2]

## Summary

**Health Status**: Excellent | Good | Needs Attention | Inactive

**Key Metrics**:
- ADRs: [count]
- Reviews: [count]
- Recalibration Plans: [count]
- Team Members: [count]
- Last Activity: [Date]

## Architectural Decision Records

**Total**: [count]

**Recent ADRs**:
1. ADR-[XXX]: [Title] ([Status], [Date])
2. ADR-[YYY]: [Title] ([Status], [Date])
[List 5-10 most recent]

**By Status**:
- ✅ Accepted: [count]
- 🔄 Proposed: [count]
- ⚠️ Deprecated: [count]
- 🔀 Superseded: [count]

**Coverage**: [Main areas covered: Data, Security, Infrastructure, etc.]

## Architecture Reviews

**Total**: [count]

**Version Reviews**: [List with dates]
**Feature Reviews**: [List with dates]
**Specialist Reviews**: [List with dates]

**Most Recent**: [Title] ([Date])

## Recalibration

**Total Documents**: [count]

**Active**:
1. [Target]: [Status], [Completion %]

**Status**:
- ✅ Completed: [count]
- 🔄 In Progress: [count]
- 📋 Planned: [count]

## Architecture Team

**Total Members**: [count]

**Team**: [List member titles]

**Coverage**: Security ([count]), Performance ([count]), System Design ([count]), etc.

**View full roster**: "List architecture members"

## Activity

**Recent**:
- [Date]: Created ADR-XXX: [Title]
- [Date]: Completed review for [target]
- [Date]: [Activity]

**Level**: High | Medium | Low | Inactive

## Documentation Health

**Completeness**: [X%]

**Strengths**:
- ✅ [What's well documented]

**Gaps**:
- ⚠️ [What needs attention]

**Recommendations**:
1. [Recommendation 1]
2. [Recommendation 2]

## Quick Actions

**Create**:
- "Create ADR for [decision]"
- "Start architecture review for [version/feature]"
- "Ask [specialist] to review [target]"

**View**:
- "List architecture members"
- [Specific docs to review based on status]

**Update**:
- [Actions based on current state]

---

4. Analyze Health

Health indicators:

  • Excellent: Regular ADRs, recent reviews, active recalibration
  • Good: Some ADRs, occasional reviews
  • Needs Attention: Old docs, no recent activity
  • Inactive: Framework unused

5. Provide Recommendations

Based on status:

If well-maintained:

✅ Excellent documentation discipline!

Keep momentum:
- Continue documenting decisions
- Regular reviews (quarterly/before releases)
- Track recalibration progress

If partially used:

⚠️ Good foundations, room for improvement.

Suggestions:
- Document 3-5 key decisions as ADRs
- Schedule architecture review
- Address review findings

If minimal usage:

❌ Framework underutilized.

Get started:
1. Document your most important decisions as ADRs
2. Conduct initial architecture review
3. Make documentation a regular habit

6. Make It Actionable

Always end with:

  • Specific commands to run
  • Concrete actions to improve
  • Examples relevant to their status

Metrics to Track

Volume: Total ADRs, reviews, recalibration docs, team members Activity: Last update, docs per month, active vs completed Coverage: Decision areas, review types, specialist expertise Health: Documentation completeness, review frequency, progress tracking

Error Handling

  • No .architecture/: Offer setup
  • Permission issues: Report and suggest fixes
  • Corrupted files: Note which have issues
  • Empty directories: Suggest starting points

Related Skills

Based on Status Results:

If Documentation Gaps Found:

  • "Create ADR for [missing decision]" - Fill documentation gaps
  • "Start architecture review for [area]" - Comprehensive assessment
  • "Ask [specialist] to review [weak area]" - Focused improvement

If Status is Good:

  • "List architecture members" - See your active team
  • Continue regular documentation practices
  • Schedule periodic reviews

Regular Workflow:

  1. Start work → "What's our architecture status?" → Identify gaps
  2. Make changes → Document with ADRs → Status check to verify
  3. Before release → Status check → Architecture review → Address findings

Workflow Examples:

  1. Status check → Find 0 ADRs → Create ADRs for key decisions → Status check shows progress
  2. Status check → See old reviews → Request new architecture review → Update status
  3. Weekly: Status check → Track documentation health → Maintain good practices

Notes

  • Be honest but encouraging
  • Focus on actionable next steps
  • Show value of maintained documentation
  • Adapt tone to current state

Create Architectural Decision Record (ADR)

Creates structured ADRs following the framework's template.

Process

1. Gather Context

Ask if needed:

  • What decision is being made?
  • What problem does it solve?
  • What alternatives were considered?
  • What are the trade-offs?
  • Does this replace an existing ADR? If so, which one (ADR-NNN)?

Then read .architecture/principles.md if it exists. The decision is written against it in step 6.

2. Generate ADR Number

# Find highest ADR number
ls .architecture/decisions/adrs/ | grep -E "^ADR-[0-9]+" | sed 's/ADR-//' | sed 's/-.*//' | sort -n | tail -1

New ADR = next sequential number (e.g., if highest is 003, create 004)

3. Validate and Sanitize Input

Security: Sanitize user input to prevent path traversal and injection:

  • Remove or replace: .., /, \, null bytes, control characters
  • Convert to lowercase kebab-case: spaces → hyphens, remove special chars
  • Limit length: max 80 characters for filename portion
  • Validate result: ensure filename contains only [a-z0-9-]

4. Create Filename

Format: ADR-XXX-kebab-case-title.md

Examples:

  • ADR-001-use-react-for-frontend.md
  • ADR-002-choose-postgresql-database.md

Valid input: "Use React for Frontend" → use-react-for-frontend Invalid blocked: "../etc/passwd" → sanitized or rejected

5. Check Configuration

  • Read .architecture/config.yml to check if pragmatic_mode is enabled
  • If enabled and applies to ADR creation, include Pragmatic Enforcer analysis

6. Write ADR

Use the template from .architecture/templates/adr-template.md:

Core sections:

  • Status, Context, Decision Drivers, Decision, Consequences
  • Implementation, Alternatives Considered, Validation, References

Principles check (when .architecture/principles.md exists): name each recorded principle the decision upholds under Decision Drivers, and each one it conflicts with under Consequences → Negative. A decision that conflicts with a principle is still recordable; an unacknowledged conflict is not. If the point of the decision is to change or retire a principle, say so in the first sentence of Context and edit .architecture/principles.md in the same change, citing the ADR number next to the edited principle. The two files move together or not at all.

If pragmatic_mode is enabled: Add Pragmatic Enforcer Analysis section:

  • Necessity Assessment (0-10): Current need, future need, cost of waiting, evidence
  • Complexity Assessment (0-10): Added complexity, maintenance, learning curve, dependencies
  • Alternative Analysis: Review if simpler alternatives adequately considered
  • Simpler Alternative Proposal: Concrete proposal for simpler approach
  • Recommendation: Approve / Approve with simplifications / Defer / Recommend against
  • Pragmatic Score: Necessity, Complexity, Ratio (target <1.5)
  • Overall Assessment: Appropriate engineering vs over-engineering

If deferrals enabled: Track deferred decisions in .architecture/deferrals.md

If this ADR supersedes another: confirm the old file exists in .architecture/decisions/adrs/ before writing anything. If it doesn't, stop and ask; don't create a dangling link. Add supersedes: ADR-NNN to the new ADR's frontmatter.

7. Save ADR

Write to: .architecture/decisions/adrs/ADR-XXX-title.md

If this ADR supersedes another, edit the old ADR in the same change:

  • frontmatter status: superseded
  • frontmatter superseded-by: ADR-XXX (the new number)
  • if the old ADR keeps a ## Status section, change it to Superseded and link the new ADR so it matches the frontmatter

Leave the rest of the old ADR alone. It's the record of what was decided then. validate-adr checks that both sides of the link agree, so a half-written pair fails validation.

8. Report to User

Created ADR-XXX: [Title]

Location: .architecture/decisions/adrs/ADR-XXX-title.md
Status: [Status]
Supersedes: [ADR-NNN, now marked superseded | none]

Key Points:
- Decision: [Summary]
- Main benefit: [Key benefit]
- Main trade-off: [Key trade-off]

Next Steps:
- [Immediate action 1]
- [Immediate action 2]

When to Create ADRs

Do create for:

  • Technology choices (frameworks, databases, languages)
  • Architectural patterns (microservices, event-driven, etc.)
  • Infrastructure decisions (cloud provider, deployment)
  • Security approaches (authentication, encryption)

Don't create for:

  • Implementation details (function names, variable names)
  • Temporary decisions
  • Minor decisions with limited impact

Status Lifecycle

  • Proposed: Documented but not approved
  • Accepted: Approved and should be implemented
  • Deprecated: No longer best practice
  • Superseded: Replaced by a newer ADR. Set by the new ADR's supersedes: field (step 7), never by hand alone

Related Skills

Before Creating ADR:

  • "Which ADRs cover [topic]?" - Find a decision that already covers this, or one the new ADR supersedes
  • "What's our architecture status?" - Check existing ADRs to avoid duplication
  • "List architecture members" - See who should review the decision

After Creating ADR:

  • "Ask [specialist] to review [the ADR]" - Get focused expert review
  • "Start architecture review for [version]" - Include in comprehensive review

Workflow Examples:

  1. Create ADR → Ask Security Specialist to review → Revise ADR
  2. Architecture review → Create ADRs for key decisions → Status check

Notes

  • Focus on "why" more than "what"
  • Be honest about trade-offs
  • Keep it concise but complete
  • ADRs can be updated as new information emerges

Find Relevant ADRs

Ranks the project's ADRs against a question and/or a file path. Tier-1 parity with the MCP find_relevant_adrs tool (ADR-015): both call tools/lib/adr-index.js, so the same inputs give the same ranking.

Process

1. Check Framework Setup

If .architecture/decisions/adrs/ doesn't exist, say so and suggest "Setup ai-software-architect". Stop.

2. Locate the CLI

TOOLS_CLI=""
if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/tools/cli.js" ]; then
  TOOLS_CLI="$CLAUDE_PLUGIN_ROOT/tools/cli.js"
else
  TOOLS_CLI=$(find ~/.claude/plugins -type f -name cli.js -path '*ai-software-architect/tools/*' 2>/dev/null | head -1)
fi

3. Run the Search

Pass the user's question as --query and, when they named a file or you are about to edit one, its project-relative path as --file:

node "$TOOLS_CLI" find-adrs --project . --query "<question>" --file "<path>" --json

At least one of --query or --file is required. --limit (1-20, default 5) caps the results.

Matching is plain, with no embeddings: keywords against ADR titles and bodies (rarer terms weigh more, title hits weigh triple), plus optional affects: globs in ADR frontmatter matched against --file.

No CLI found (manual install without the plugin): fall back to reading. List .architecture/decisions/adrs/, read titles and statuses, and pick the ADRs whose title or body covers the question. Say in the report that the ranking is by hand.

4. Report

For each result, in rank order:

  • ADR-XXX: <title>: status, and why it matched (matched)
  • If current is false: say it is superseded and name supersededBy. Read the successor, and never present the superseded ADR as the decision in force.

Then read the top one or two ADRs in full before answering the user's question or editing the file. The ranking points; the ADR text decides.

If nothing matched, relay the note: no recorded decision covers this, so a new choice may warrant an ADR ("Create ADR for [topic]").

Related Skills

  • "Create ADR for [topic]" - Record a decision when none covers the change
  • "What's our architecture status?" - Counts and documentation health
  • "Ask [specialist] to review [ADR]" - Expert read on a matched decision

List Architecture Members

Displays all architecture team members and their expertise areas.

Process

1. Check Setup

If .architecture/members.yml doesn't exist:

The AI Software Architect framework hasn't been set up yet.

To get started: "Setup ai-software-architect"

2. Load Members

Read .architecture/members.yml and parse all members (id, name, title, specialties, disciplines, skillsets, domains, perspective).

3. Display Team Roster

# Architecture Team Members

Your AI Software Architect team consists of [count] specialized reviewers.

Total Members: [count]

---

## Team Roster

### [Member 1 Name] - [Member 1 Title]

**ID**: `[member_id]`

**Specialties**: [Specialty 1], [Specialty 2], [Specialty 3]

**Disciplines**: [Discipline 1], [Discipline 2]

**Domains**: [Domain 1], [Domain 2], [Domain 3]

**Perspective**: [Their unique perspective]

**Request review**: `Ask [Member Title] to review [your target]`

---

[Repeat for all members]

---

## Quick Reference

**Specialist reviews**:
- `Ask [Specialist Title] to review [target]`

**Examples**:
- "Ask Security Specialist to review authentication"
- "Ask Performance Specialist to review database queries"
- "Ask [Your Specialist] to review [anything]"

**Full architecture review**:
- `Start architecture review for version X.Y.Z`

**Other commands**:
- `Create ADR for [decision topic]`
- `What's our architecture status?`

---

## Team by Specialty

[Group members by their primary domains/specialties]

**Security & Compliance**: [Members]
**Performance & Scalability**: [Members]
**Code Quality & Maintainability**: [Members]
**Domain & Business Logic**: [Members]
**System Design & Architecture**: [Members]
**Technology-Specific**: [Members]

---

## Adding New Members

Request a review from any specialist, even if they don't exist:
- "Ask Ruby Expert to review my modules"
- "Have Accessibility Expert review forms"

I'll create the specialist and add them to your team automatically.

Or manually edit `.architecture/members.yml` and add:
```yaml
- id: your_specialist_id
  name: "[Name]"
  title: "[Title]"
  specialties: ["[Specialty 1]", "[Specialty 2]"]
  disciplines: ["[Discipline 1]", "[Discipline 2]"]
  skillsets: ["[Skill 1]", "[Skill 2]"]
  domains: ["[Domain 1]", "[Domain 2]"]
  perspective: "[Brief description]"

Using the Team

For focused reviews (specific expertise):

Ask [Specialist] to review [target]

Fast turnaround, targeted insights

For comprehensive reviews (all perspectives):

Start architecture review for [version/feature]

All members review, collaborative discussion

For decisions:

Create ADR for [decision topic]

Document decisions with team input



### 4. Provide Context
After listing:
- Explain when to use specialist vs full reviews
- Show how to add new members dynamically
- Provide usage examples
- Suggest next steps

## Example Output Summary
After showing full roster, provide a concise summary:

Ready to use your architecture team:

  • [N] specialists available
  • Request reviews: "Ask [specialist] to review [target]"
  • Add new specialists: Just ask for them by name
  • Full review: "Start architecture review for [scope]"

## Error Handling
- No `.architecture/`: Offer setup instructions
- Empty `members.yml`: Show default team and offer setup
- Malformed YAML: Show what's parseable, note issues

## Related Skills

**After Listing Members**:
- "Ask [specialist] to review [target]" - Request focused expert review
- "Start architecture review for [scope]" - Comprehensive review with all members
- "What's our architecture status?" - See how team has been used

**When Adding Members**:
- Just request a specialist that doesn't exist - they'll be created automatically
- "Setup ai-software-architect" - Adds members based on your tech stack

**Workflow Examples**:
1. List members → Identify relevant specialist → Request review
2. Need new expertise → Request it → Specialist auto-created → List to verify
3. Status check → List members → Review with specific specialists

## Notes
- Keep presentation clear and scannable
- Make it actionable with specific commands
- Encourage exploration and usage
- Explain that team can grow dynamically

Pragmatic Guard Mode

Enables and configures the Pragmatic Guard Mode to actively challenge over-engineering.

Process

1. Check Current Configuration

  • Read .architecture/config.yml to check current settings
  • If config.yml doesn't exist, offer to create it from .architecture/templates/config.yml
  • Check if pragmatic_mode.enabled is true
  • Note the intensity level (strict/balanced/lenient)
  • Review exemption categories and triggers

2. Enable Pragmatic Mode (if requested)

If user wants to enable:

  • If config.yml doesn't exist:
    cp .architecture/templates/config.yml .architecture/config.yml
    
  • Set pragmatic_mode.enabled: true
  • Confirm intensity level with user or use default (balanced)
  • Create .architecture/deferrals.md from template if it doesn't exist:
    cp .architecture/templates/deferrals.md .architecture/deferrals.md
    
  • Inform user about mode activation and current settings

3. Configure Intensity Level

Ask user which intensity they prefer if not specified:

Strict Mode:

  • Challenges aggressively, requires strong justification for any complexity
  • Questions every "should" and "could"
  • Pushes for absolute minimal implementation
  • Best for: New projects, MVPs, startups with limited resources

Balanced Mode (RECOMMENDED):

  • Challenges thoughtfully, accepts justified complexity
  • Seeks middle ground between simplicity and best practices
  • Questions "should" but accepts reasonable "must"
  • Best for: Most projects, growing teams, moderate complexity

Lenient Mode:

  • Raises concerns without blocking
  • Suggests simpler alternatives as options
  • Focuses on major complexity additions only
  • Best for: Established projects, teams with strong architecture practices

4. Configure Triggers (optional)

Ask if user wants to customize which situations trigger pragmatic analysis:

  • New abstraction layers (interfaces, base classes, DI containers)
  • New external dependencies (libraries, frameworks, services)
  • New architectural patterns (repository, strategy, observer)
  • Scope expansion beyond initial requirements
  • Performance optimizations without evidence
  • Test infrastructure upfront
  • Flexibility/configurability additions

5. Configure Exemptions (optional)

Confirm exemption categories where best practices should be maintained:

  • Security-critical features (always exempt by default)
  • Data integrity (always exempt by default)
  • Compliance requirements (always exempt by default)
  • Accessibility (always exempt by default)

6. Understanding the Pragmatic Enforcer

Explain how the Pragmatic Enforcer will participate:

In Architecture Reviews:

  • Reviews each architect's recommendations
  • Applies necessity assessment (0-10 scoring)
  • Applies complexity assessment (0-10 scoring)
  • Proposes simpler alternatives
  • Calculates pragmatic score (complexity/necessity ratio, target <1.5)

In ADR Creation:

  • Challenges proposed decisions
  • Questions whether complexity is justified by current needs
  • Suggests phased approaches or deferrals
  • Documents trigger conditions for deferred decisions

Question Framework:

  • Necessity: "Do we need this right now?" "What breaks without it?"
  • Simplicity: "What's the simplest thing that could work?"
  • Cost: "What's the cost of implementing now vs waiting?"
  • Alternatives: "What if we just...?" "Could we use existing tools?"
  • Best Practices: "Does this best practice apply to our context?"

7. Deferrals Tracking

If behavior.track_deferrals is true:

  • Maintain .architecture/deferrals.md with deferred decisions
  • Include trigger conditions for each deferral
  • Track when deferrals are implemented or remain deferred

8. Report to User

Pragmatic Guard Mode: [Enabled | Disabled]

Configuration:
- Intensity: [strict | balanced | lenient]
- Apply to: [List of phases where it applies]
- Deferrals tracking: [enabled | disabled]

Exemptions:
- Security-critical: [enabled | disabled]
- Data integrity: [enabled | disabled]
- Compliance: [enabled | disabled]
- Accessibility: [enabled | disabled]

Triggers:
[List of active triggers]

The Pragmatic Enforcer will now:
- Challenge recommendations from other architects
- Question complexity and abstractions
- Propose simpler alternatives
- Calculate pragmatic scores (target ratio <1.5)
- [If enabled] Track deferred decisions in .architecture/deferrals.md

Next Steps:
- Create an ADR: "Create ADR for [topic]" (will include pragmatic analysis)
- Start a review: "Start architecture review for [target]" (will include pragmatic challenges)
- Adjust settings: Edit .architecture/config.yml

When to Use Pragmatic Mode

Enable for:

  • New projects or MVPs
  • Teams prone to over-engineering
  • Resource-constrained environments
  • Learning environments (teaching YAGNI)
  • Projects with tight deadlines

Consider disabling for:

  • Mature systems with established patterns
  • High-complexity domains requiring abstractions
  • Teams already practicing strong YAGNI principles
  • Projects with specific architectural requirements

Notes

  • Pragmatic mode is about finding balance, not blocking progress
  • The Pragmatic Enforcer's role is to question and challenge, not to veto
  • Intensity level should match team maturity and project complexity
  • Exemptions ensure critical areas maintain appropriate rigor
  • Deferrals can always be implemented when triggered by actual needs

Setup AI Software Architect Framework

Sets up and customizes the AI Software Architect framework for a project.

Overview

This skill performs a complete framework installation:

  1. Locates the framework source (plugin install dir or legacy clone)
  2. Analyzes the target project (languages, frameworks, structure, patterns)
  3. Scaffolds .architecture/ in the target project from framework templates
  4. Customizes team members and principles for the detected tech stack
  5. Performs an initial system analysis
  6. Reports customizations and findings, with explicit next steps

Detailed procedures: references/installation-procedures.md Customization guide: references/customization-guide.md

What happens when you run Setup ai-software-architect

The skill creates a .architecture/ directory in your target project (not in this plugin's repo) and populates it with templates customized for your tech stack. After it finishes you'll have:

  • .architecture/decisions/adrs/ — empty, ready for create-adr
  • .architecture/reviews/initial-system-analysis.md — your team's first pass at the codebase
  • .architecture/members.yml — team customized for your detected stack
  • .architecture/principles.md — principles tailored to your frameworks
  • .architecture/config.yml — operational config (pragmatic mode, etc.)
  • .architecture/templates/ — ADR + review templates ready to use

The skill writes into your target project's .architecture/, plus two integration points outside it: it appends a framework section to an existing CLAUDE.md (step 6), and the installation procedure creates .coding-assistants/ for assistant-specific config. It does not modify application code.

High-Level Workflow

1. Locate framework source

The framework templates can live in two places: inside the installed Claude Code plugin (canonical, 1.4.0+) or under a legacy .architecture/.architecture/ clone in the target project. Discovery is deterministic — run the framework's own CLI:

# Locate the plugin install on disk first; tools/cli.js lives inside it.
TOOLS_CLI=""
if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/tools/cli.js" ]; then
  TOOLS_CLI="$CLAUDE_PLUGIN_ROOT/tools/cli.js"
else
  TOOLS_CLI=$(find ~/.claude/plugins -type f -name cli.js -path '*ai-software-architect/tools/*' 2>/dev/null | head -1)
fi

if [ -z "$TOOLS_CLI" ] && [ -f ".architecture/.architecture/tools/cli.js" ]; then
  # Legacy clone path: the cli ships in the cloned repo.
  TOOLS_CLI=".architecture/.architecture/tools/cli.js"
fi

if [ -z "$TOOLS_CLI" ]; then
  echo "Framework not found. Install the plugin or clone manually — see error message below."
  exit 1
fi

# Resolve the framework source via the canonical discovery logic.
FRAMEWORK_ROOT=$(node "$TOOLS_CLI" find-source)

Discovery order (the order and sentinel live in tools/lib/setup-source-discovery.js, tested via tools/test/setup-source-discovery.test.js; the ~/.claude/plugins walk itself is findPluginCandidates in tools/cli.js, mirrored by the MCP server's listPluginCandidates and exercised by mcp/test/setup-source.test.js):

  1. ${CLAUDE_PLUGIN_ROOT} env var (if set and contains .architecture/templates/adr-template.md).
  2. Recursive search of ~/.claude/plugins/ for any ai-software-architect/ directory, or an immediate subdirectory of one (Claude Code installs under cache/<marketplace>/<plugin>/<version>/), containing the sentinel; versions marked .orphaned_at by a plugin update are skipped.
  3. .architecture/.architecture/ in the target project (legacy clone path).

If find-source exits non-zero, surface its error message verbatim — it tells the user exactly which install option to take.

2. Analyze Project

Identify project characteristics:

  • Languages: JavaScript/TypeScript, Python, Ruby, Java, Go, Rust
  • Frameworks: React, Vue, Django, Rails, Spring, etc.
  • Infrastructure: Testing setup, CI/CD, package managers
  • Structure: Directory layout, architectural patterns

Use Glob and Grep to detect technologies, Read to examine configs.

3. Install Framework

Execute installation steps (see references/installation-procedures.md):

# $FRAMEWORK_ROOT is from step 1.
# Directories first: on a fresh project .architecture/ doesn't exist yet,
# and cp into a missing parent fails.
mkdir -p .architecture/decisions/adrs
mkdir -p .architecture/reviews
mkdir -p .architecture/recalibration
mkdir -p .architecture/comparisons
mkdir -p .architecture/agent_docs

cp -r "$FRAMEWORK_ROOT/.architecture/templates" .architecture/templates
cp "$FRAMEWORK_ROOT/.architecture/principles.md" .architecture/principles.md
# members.yml is seeded, not copied: drops motivated_by refs to this framework's ADRs/issues.
node "$TOOLS_CLI" seed-members "$FRAMEWORK_ROOT/.architecture/members.yml" .architecture/members.yml
cp "$FRAMEWORK_ROOT/.architecture/config.yml" .architecture/config.yml

# config.yml's pragmatic_mode.deferral_log points here; create it so the
# first deferral has somewhere to land.
[ -f .architecture/deferrals.md ] || cp .architecture/templates/deferrals.md .architecture/deferrals.md

# Git drops empty directories; keep the structure in the first commit.
for d in decisions/adrs reviews recalibration comparisons agent_docs; do
  [ -n "$(ls -A .architecture/$d)" ] || touch .architecture/$d/.gitkeep
done
  • Create directory structure (decisions/adrs, reviews, recalibration, etc.)
  • Initialize .architecture/config.yml from the source location's .architecture/config.yml (not templates/config.yml)
  • Set up agent documentation (ADR-006 progressive disclosure)
  • Legacy clone path only: remove .architecture/.architecture/ and (with safeguards) the cloned .git/ directory. Plugin path: no clone removal needed — the plugin's install dir stays where it is under ~/.claude/plugins/.

Critical (legacy clone path only): Follow safety procedures when removing .git/ directory. See references/installation-procedures.md § Cleanup Procedures.

4. Customize Architecture Team

Steps 4 and 5 edit members.yml and principles.md, which the plugin's PreToolUse hook protects. Open a setup window first, so the hook lets those edits through:

touch .architecture/.setup-in-progress

The hook honors the sentinel for an hour from its mtime, so an aborted setup can't leave protection off. Step 7 removes it.

Add technology-specific members to .architecture/members.yml:

  • JavaScript/TypeScript: JavaScript Expert, framework specialists (React/Vue/Angular)
  • Python: Python Expert, framework specialists (Django/Flask/FastAPI)
  • Ruby: Ruby Expert, Rails Architect
  • Java: Java Expert, Spring Boot Specialist
  • Go: Go Expert, Microservices Architect
  • Rust: Rust Expert, Systems Programmer

Use template from assets/member-template.yml.

Keep all canonical core members — never drop one. The framework's .architecture/members.yml defines 8: Systems Architect, Domain Expert, Security Specialist, Maintainability Expert, Performance Specialist, Implementation Strategist, AI Engineer, Pragmatic Enforcer. Append technology specialists as additional advisors.

Customization details: references/customization-guide.md § Customize Team Members

5. Customize Architectural Principles

Add framework-specific principles to .architecture/principles.md:

  • React: Component composition, hooks, unidirectional data flow
  • Rails: Convention over configuration, DRY, RESTful design
  • Django: Explicit over implicit, reusable apps, use built-ins

These are defaults. Where the repo already shows a convention (service objects, a stated layering rule in its contributor docs), record the repo's convention and skip any default that contradicts it.

Principle examples: references/customization-guide.md § Customize Principles

6. Update CLAUDE.md Integration

If CLAUDE.md exists in project root, append framework usage section:

  • Available commands
  • Where to find documentation
  • How to invoke skills

Template: references/customization-guide.md § Update CLAUDE.md

7. Cleanup

Close the setup window so the hook protects the customized files again:

rm -f .architecture/.setup-in-progress

Remove framework development files:

  • Framework documentation (README.md, USAGE*.md, INSTALL.md)
  • Template .git/ directory (with critical safety checks)

⚠️ IMPORTANT: Follow all safeguards in references/installation-procedures.md § Cleanup.

8. Create Initial System Analysis

Generate comprehensive initial analysis document:

  • Each member analyzes system from their perspective
  • System overview (stack, structure, patterns)
  • Strengths identified
  • Concerns raised (with impact levels)
  • Recommendations prioritized (Critical/Important/Nice-to-Have)
  • Collaborative synthesis of findings

Save to .architecture/reviews/initial-system-analysis.md.

Template: assets/initial-analysis-template.md

9. Report to User

Provide a setup summary using the template below, then the success checklist so the user can verify the install end-to-end.

Provide setup summary:

AI Software Architect Framework Setup Complete

Customizations:
- Added [N] technology specialists: [list]
- Customized principles for: [frameworks]
- Configuration: Pragmatic mode [enabled/disabled]

Initial Analysis Highlights:
- Overall assessment: [assessment]
- Top strength: [strength]
- Top concern: [concern]
- Critical recommendation: [recommendation]

Location: .architecture/reviews/initial-system-analysis.md

Next Steps:
- Review initial analysis findings
- "List architecture members" to see customized team
- "Create ADR for [first decision]" to start documenting
- "What's our architecture status?" to verify setup

Setup successful when...

A first-time user can verify the install by checking that all of these are true:

  • .architecture/decisions/adrs/ exists and is empty
  • .architecture/reviews/initial-system-analysis.md exists and is non-empty
  • .architecture/members.yml lists all eight canonical core members (per the framework's .architecture/members.yml) plus any technology specialists added in step 4
  • .architecture/principles.md exists and includes any framework-specific principles added in step 5
  • .architecture/config.yml exists (pragmatic mode flag visible)
  • .architecture/templates/ contains adr-template.md and review-template.md
  • No leftover .architecture/.architecture/ directory (legacy clone path only)
  • Running What's our architecture status? returns a coherent summary
  • Running List architecture members shows the customized team

If any of these fail, see the recovery section below.

Recovery

If setup fails partway through (e.g., framework files copied but customization didn't run):

  1. Inspect .architecture/ to see what landed.
  2. If only a few files copied, the simplest recovery is rm -rf .architecture/ and re-run Setup ai-software-architect (no project code is touched outside .architecture/).
  3. If most files are in place but members.yml or principles.md weren't customized, you can re-run setup; the skill will detect the partial install and offer to complete the customization step rather than restart.
  4. If the initial analysis didn't run, ask: Generate initial system analysis at .architecture/reviews/initial-system-analysis.md — the orchestrator will dispatch the team without redoing the file install.

If setup ran but the team isn't right for your project, you don't need to re-run setup. Edit .architecture/members.yml directly (set CLAUDE_ALLOW_PROTECTED=1 to satisfy the PreToolUse hook) and run node "$TOOLS_CLI" generate-subagents from anywhere inside the project to refresh the matching .claude/agents/<id>.md files.

Error Handling

Framework source not found:

I can't find the framework templates. Two installation options:

  Recommended (plugin):
    /plugin marketplace add codenamev/ai-software-architect
    /plugin install ai-software-architect@ai-software-architect

  Legacy (clone):
    git clone https://github.com/codenamev/ai-software-architect .architecture/.architecture

After installing, run "Setup ai-software-architect" again.

Already set up:

Framework appears to be already set up.

To verify: "What's our architecture status?"
To reconfigure: Manually edit .architecture/members.yml and .architecture/principles.md

Unclear project structure:

Could not clearly identify project type. Please describe:
- Primary programming language(s)
- Framework(s) used
- Project purpose

I'll customize the framework accordingly.

Related Skills

After Setup:

  • list-members - View customized team
  • architecture-status - Verify setup completion
  • create-adr - Document first decision

Initial Work:

  • Review initial-system-analysis.md findings
  • specialist-review - Deep-dive on specific concerns
  • create-adr - Document existing key decisions

Workflow Example: Setup → Review initial analysis → Create ADRs → Status check → Regular reviews

Notes

  • Customize based on actual project, not every possible option
  • Be specific about why each customization was made
  • Initial analysis should be thorough but focused on actionable findings
  • Safety checks during cleanup are non-negotiable

Documentation

Specialist Review (orchestrator)

Single-specialist deep-dive review. This skill is an orchestrator — it identifies the right specialist and delegates the review to that specialist's subagent (agents/<id>.md). The deep-perspective work happens in the subagent's isolated context, not in this skill's main thread.

See ADR-013 for the rationale.

Process

1. Parse the request

Extract from the user's request:

  • Specialist role (e.g., "Security Specialist", "Performance Expert")
  • Target (e.g., "API authentication", "the payments module", "ADR-007")

If either is unclear, ask one focused clarifying question and stop.

2. Resolve the specialist

Read .architecture/members.yml and find the member whose name or title matches the requested role (case-insensitive, allow common abbreviations like "security" → "Security Specialist").

The member's id (e.g., security_specialist) maps to a subagent at <kebab-id>.md (e.g., security-specialist.md): in .claude/agents/ of a project using the plugin, or the plugin's own agents/. The drift check in CI (generate-subagents --check) guarantees that file exists if the member exists.

If the requested specialist is not in members.yml:

The previous version of this skill auto-created new members on the fly. That is no longer supported because .architecture/members.yml is now protected by a PreToolUse hook (see ADR-013 Pragmatic Analysis). Instead:

  1. Tell the user: " is not in your architecture team. To add them: edit .architecture/members.yml (the PreToolUse hook will refuse the write — set CLAUDE_ALLOW_PROTECTED=1 to override), add a member entry following the existing schema, then run node tools/cli.js generate-subagents."
  2. Stop. Do not attempt the review until the member exists.

3. Delegate to the subagent

Dispatch a single Agent call:

Agent({
  subagent_type: "<kebab-id>",
  description: "<Role> review of <target>",
  prompt: <see template below>
})

Prompt template for the subagent call:

You are conducting a focused review of: <target>.

Apply your perspective (see your subagent file for your specialty,
disciplines, and domains). Do not range outside your specialty —
other specialists will cover their own areas.

Produce a review with these sections:
- Executive summary (2-3 sentences, overall assessment)
- Strengths (what is working well within your domain)
- Concerns (with severity: critical / high / medium / low)
  - For each concern: location (file:line), why it matters, concrete fix
- Recommendations (ordered: immediate / short-term / long-term)
- Risks if unaddressed
- Success metrics (how to verify the recommendations land)

If the target requires you to read code, configs, or ADRs, do so via
your Read/Grep/Glob tools. Reference exact files and line numbers.

Return the review as markdown. Do not write to disk; the orchestrator
will save it.

4. (Optional) Save the review

If the user asked to persist the review (e.g., "save to reviews/" or "create a review document"):

  1. Filename format: <specialist-id>-<target-slug>.md (kebab-case, max 100 chars total). Example: security-specialist-api-authentication.md.
  2. Apply input sanitization from ../_patterns.md to the target slug.
  3. Wrap the subagent's returned markdown in the review template header (reviewer name, date, target).
  4. Write to .architecture/reviews/<filename>.

If the user did not ask to persist, return the review inline.

5. Report

Concise summary back to the user:

<Title> Review Complete: <target>

Reviewer: <Name>
Location: <path or "inline">
Assessment: <executive summary first sentence>

Key concerns:
1. <highest-severity concern>
2. <next>
3. <next>

Counts: <critical>/<high>/<medium>/<low>

Suggested next:
- <immediate action from recommendations>
- <follow-up specialist if cross-cutting concern surfaced>

Why this skill is small

The previous version (~200 lines) inlined detailed review-process instructions because Claude was expected to be the specialist mid-conversation. With subagents, the specialist's persona, perspective, and tool scoping live in agents/<id>.md (generated from members.yml). This skill's job is just to route the request and assemble the response.

Specialist-specific guidance (how a Security Specialist thinks vs a Performance Specialist) lives in the subagent files themselves, not duplicated here. The framework principle: one source of truth per concept.

Related skills

Before:

  • list-members — see who is available
  • architecture-status — check what's already been reviewed

After:

  • create-adr — document decisions arising from findings
  • architecture-review — fold this finding into a multi-perspective review

Workflow examples:

  1. Security review surfaces auth issue → create-adr for the fix → re-review
  2. Performance review identifies bottleneck → ADR for caching strategy → implementation
  3. Specialist review on one slice → comprehensive architecture-review for the full version cut

References

Agents 8

AI Engineer

Perspective

Evaluates the architecture from an AI integration perspective, focusing on practical utility, system evaluation, observability, and agent interaction patterns.

Specialties

  • AI/ML integration
  • LLM application design
  • agent-based systems
  • AI evaluation frameworks
  • agent orchestration

Disciplines

  • applied AI
  • prompt engineering
  • agent workflow design
  • AI system observability
  • multi-agent coordination

Skillsets

  • building practical AI solutions
  • evaluating user experience with AI
  • integrating AI components
  • designing AI metrics and benchmarks
  • implementing observability systems

Domains

  • end-user AI applications
  • AI development workflows
  • practical implementation
  • AI system evaluation
  • observability and metrics

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • Can the assistant actually follow this, or is it an instruction only a human could hold? (motivated by: ADR-005; instruction-following degrades past a measured capacity)
  • Which agent decides here, and which merely executes? (motivated by: ADR-013; the orchestrator pattern exists because skills doing their own delegation duplicated judgment)
  • How would we know this prompt or persona got worse after the next edit?
  • What does the tool see, and what did we assume it would infer? (motivated by: #30; tool inputs were validated by convention, not by schema, until the McpServer migration)

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • A prompt change with no way to evaluate it beyond reading it
  • Two agents with overlapping authority over the same decision
  • Tool input or output trusted without a schema on the boundary

Signature trade-off

The axis this reviewer habitually trades against the others: measurable, evaluable AI behavior vs. the flexibility of free-form prompts. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Domain Expert

Perspective

Evaluates how well the architecture represents and serves the problem domain and business concepts.

Specialties

  • domain-driven design
  • bounded contexts
  • ubiquitous language

Disciplines

  • business logic modeling
  • domain analysis
  • requirements engineering

Skillsets

  • translating business needs to technical solutions
  • identifying core domain concepts
  • defining domain boundaries

Domains

  • business logic representation
  • semantic accuracy
  • model integrity

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • What is this thing called in the user's vocabulary, and does the code use the same word? (motivated by: ADR-003; 'agents', 'members', 'personas' and 'subagents' named overlapping concepts)
  • Which business rule is encoded here, and where would a user go to learn it exists?
  • Is this a real domain concept or a technical artifact wearing a domain name?
  • What invariant must hold across this boundary, and what enforces it?

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • The same concept carrying two names across code, docs, and generated output
  • A domain rule living only in a prompt or template where nothing can test it
  • A boundary that leaks another context's internal model into its public shape

Signature trade-off

The axis this reviewer habitually trades against the others: semantic fidelity to the problem domain vs. implementation simplicity and reuse. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Implementation Strategist

Perspective

Evaluates HOW and WHEN changes should be implemented, considering blast radius, reversibility, technical readiness, team capability, and timing. Asks 'Is the system ready?' and 'Is the team ready?' before 'Can we build it?'

Specialties

  • change sequencing
  • blast radius analysis
  • reversibility design
  • team readiness assessment
  • migration planning

Disciplines

  • change management
  • risk analysis
  • phased rollouts
  • impact assessment
  • timing optimization

Skillsets

  • evaluating change impact scope
  • designing reversible architectures
  • assessing system and team readiness
  • sequencing dependent changes
  • calculating social cost of changes

Domains

  • implementation timing
  • change risk management
  • architectural evolution
  • team capability alignment

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • Is the system ready for this change, and is the team ready? (motivated by: the original perspective line; the one question users cite this persona for)
  • What is the blast radius if this ships wrong, and how fast can it be reversed? (motivated by: ADR-014; setup gained dry-run and recovery after a failed run left users mid-state)
  • What is the smallest first step that proves the direction without committing to the whole?
  • What must be true in the released artifact before this can ship? (motivated by: #41; a package.json that outran the published npm version broke main until CI gated it)

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • A change with no rollback path and no dry-run
  • A dependent change sequenced before the thing it depends on has landed
  • A release step that assumes the published artifact matches the repo without checking

Signature trade-off

The axis this reviewer habitually trades against the others: reversibility and phased delivery vs. the momentum of shipping the whole thing at once. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Maintainability Expert

Perspective

Evaluates how well the architecture facilitates long-term maintenance, evolution, and developer understanding.

Specialties

  • code quality
  • refactoring
  • technical debt

Disciplines

  • code organization
  • complexity analysis
  • maintainability metrics

Skillsets

  • identifying maintenance bottlenecks
  • assessing technical debt
  • simplifying complex structures

Domains

  • code maintainability
  • architectural clarity
  • evolutionary design

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • Will the next person find this by reading the top-level file, or only by already knowing it exists? (motivated by: ADR-006 and ADR-008; progressive disclosure exists because flat docs stopped being findable)
  • How many places must change together for this to change once?
  • Is this logic in a script something can run, or in prose something must interpret? (motivated by: ADR-009; deterministic operations moved out of instructions into scripts after drift)
  • What here is copied from somewhere else, and which copy wins when they diverge?

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • Duplicated rules or templates with no designated source copy
  • Behavior that lives only in instruction prose when a script could enforce it
  • A change that raises the instruction count without a matching removal

Signature trade-off

The axis this reviewer habitually trades against the others: long-term legibility and change cost vs. shipping speed and minimal ceremony now. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Performance Specialist

Perspective

Focuses on performance implications of architectural decisions and suggests optimizations.

Specialties

  • performance optimization
  • resource utilization
  • scalability planning

Disciplines

  • performance analysis
  • bottleneck identification
  • efficiency improvement

Skillsets

  • profiling system performance
  • identifying performance critical paths
  • optimizing resource usage

Domains

  • system performance
  • response time
  • throughput

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • How many instructions does the assistant now carry on every turn because of this? (motivated by: ADR-005; instruction capacity is the scarce resource in this system, not CPU)
  • What is loaded eagerly here that could be loaded when first needed? (motivated by: ADR-008; large skills split into on-demand references to protect the context budget)
  • Which path runs on every invocation, and which only on the rare one?
  • What does this cost at ten times the current number of members, skills, or ADRs?

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • Always-on context growth with no measurement of what it displaces
  • Repeated filesystem or network reads inside a loop that could be read once
  • A hot path made slower to serve a case that is rare or hypothetical

Signature trade-off

The axis this reviewer habitually trades against the others: context budget and response latency vs. completeness of what the assistant sees up front. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Pragmatic Enforcer — YAGNI Guardian & Simplicity Advocate

Perspective

Rigorously questions whether proposed solutions, abstractions, and features are actually needed right now, pushing for the simplest approach that solves the immediate problem.

Specialties

  • YAGNI principles
  • incremental design
  • complexity analysis
  • requirement validation
  • minimum viable solutions

Disciplines

  • scope management
  • cost-benefit analysis
  • technical debt prevention
  • simplification strategies
  • deferral decision-making

Skillsets

  • identifying premature optimization
  • challenging unnecessary abstractions
  • proposing simpler alternatives
  • calculating cost of waiting
  • questioning best-practice applicability

Domains

  • implementation simplicity
  • requirement sufficiency
  • appropriate complexity

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • Who asked for this, and what breaks today without it? (motivated by: ADR-002; pragmatic mode exists to make this question mandatory rather than optional)
  • What is the cost of waiting until the need is real?
  • Is this abstraction covering two cases, or one case and a guess?
  • Is the best practice being applied because it fits, or because it is a best practice? (motivated by: the deferrals log; most deferred Phase 2-4 items were documentation for usage that had not happened)

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • A new abstraction with a single concrete caller
  • Configuration for a variation nobody has requested
  • Documentation or tooling written ahead of the usage it describes

Signature trade-off

The axis this reviewer habitually trades against the others: solving only today's problem vs. every other reviewer's future-proofing. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Activation

This subagent is most relevant when pragmatic_mode.enabled == true (see .architecture/config.yml). When that condition is false, prefer the general architecture-review subagent.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Security Specialist

Perspective

Reviews the architecture from a security-first perspective, identifying potential vulnerabilities and security implications.

Specialties

  • threat modeling
  • security patterns
  • data protection

Disciplines

  • security analysis
  • risk assessment
  • vulnerability identification

Skillsets

  • identifying security implications
  • recommending security controls
  • evaluating authentication/authorization approaches

Domains

  • system security
  • data protection
  • access control

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • What new trust boundary does this change create or move? (motivated by: ADR-010; every boundary is a place authz can be forgotten)
  • Where does user-controlled data first touch this code path? (motivated by: the MCP server's tool inputs reached path.join unvalidated before #30)
  • What happens when this component's secrets or config are wrong, missing, or leaked?
  • Which existing control is the author assuming covers this, and does it actually?

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • Untrusted input reaching a filesystem path, shell, or query without validation
  • An authorization decision made client-side, or repeated inconsistently server-side
  • Secrets or credentials committed, logged, or rendered into generated files

Signature trade-off

The axis this reviewer habitually trades against the others: security controls vs. performance overhead and onboarding friction. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Systems Architect

Perspective

Focuses on how components work together as a cohesive system and analyzes big-picture architectural concerns.

Specialties

  • distributed systems
  • service architecture
  • scalability patterns

Disciplines

  • system design
  • infrastructure modeling
  • load distribution

Skillsets

  • high-level architecture planning
  • system decomposition
  • technical roadmapping

Domains

  • overall system coherence
  • architectural principles
  • technical governance

Silent checklist

Questions this reviewer asks before reading any further. Answer each one explicitly in the review, even when the answer is "not affected".

  • Which component now owns this responsibility, and does anything else still think it does? (motivated by: ADR-016; setup derived team and stack from sources that disagreed)
  • What is the single source of truth this change reads from, and who else writes to it? (motivated by: ADR-016 'canonical sources')
  • If this component is removed tomorrow, what breaks and would the failure be visible?
  • Does this add a second way to do something the framework already does one way? (motivated by: ADR-015; MCP and Skills drifted into two parallel capability surfaces before reconciliation)

Blocking criteria

Any of these makes a finding critical and this reviewer will not sign off until it is resolved or explicitly accepted by the maintainer:

  • Two components each believing they are the canonical owner of the same state or config
  • A dependency that runs opposite to the layer direction the rest of the system follows
  • A capability added to one surface (MCP, skill, CLI) with no stated reason it is not on the others

Signature trade-off

The axis this reviewer habitually trades against the others: system coherence and uniform patterns vs. local convenience and speed of a one-off fix. Name it when it applies so the aggregated review can record the trade-off rather than an unexplained disagreement.

Source of truth

This file is generated from .architecture/members.yml. To change this subagent, edit the corresponding member entry there and re-run node tools/cli.js generate-subagents.

Sponsors

Details

Marketplace
codenamev/ai-software-architect
Author
AI Software Architect Project
Category
Development Tools
License
MIT
Keywords
architecture, adr, architectural-decision-records, documentation, architecture-reviews, pragmatic-mode, yagni, software-design, claude-code, claude-plugin