feat: /coding:architecture-review — deep whole-codebase review

[bborbe]

Summary

Adds /coding:architecture-review [directory] — a deep whole-codebase architectural review at a different altitude from existing commands:

• /coding:code-review — diff-scoped, per-PR
• /coding:audit-architecture — single-agent quick scan
• /coding:architecture-review (new) — two parallel agents, dimensions coverage, Must/Should/Could consolidation

What it does

Spawns in parallel:

1. Top-down structural — coding:go-architecture-assistant (or coding:python-architecture-assistant per project type): entry point → packages, SRP at package level, layering, dependency direction, abstraction seams, notable good patterns.
2. Dimensions pass — generic claude (open-ended behavioral exploration; documented in-place why generic agent is correct here): data flow end-to-end, failure & resilience, concurrency & lifecycle, observability, cross-cutting consistency, config/blast radius, evolvability test, architectural drift.

Consolidates into Must Fix / Should Fix / Could Fix with file:line citations and Top 5 highest-leverage fixes.

When to use

• Quarterly architectural health audit
• Before scaling a service (team, traffic, complexity)
• When persistent friction signals "the design is fighting us"
• Onboarding a codebase you didn't write

Test plan

• make precommit green (30 checks)
• Local self-review loop converged (3 passes; 2 Should Fix + 3 Could Fix found and fixed)
• Manual end-to-end run against a real codebase (deferred until merge — the command itself only ships agent invocations + framing, no executable code to dry-run)

[ben-s-pull-request-reviewer]

Based on my analysis, here's my review:

{
  "verdict": "approve",
  "summary": "The `/coding:architecture-review` command is well-designed: thin wrapper (~109 lines), correct frontmatter, minimal allowed-tools, delegates all deep work to parallel agents. Two concerns noted below are Should Fix / Nice to Have, not blockers.",
  "comments": [
    {
      "file": "commands/architecture-review.md",
      "line": 2,
      "severity": "major",
      "message": "allowed-tools 'Bash(git status:+)','Bash(git log:+)','Bash(git branch:+)' are marked with '+' suffix but the Context section (lines 9-11) uses `!git ...` syntax which is a Claude Code variable expansion, not a Bash tool call — the '+' suffix may not be needed. However since 'git status' and 'git log' without '+' could be unsafe, keeping the '+' variants is the conservative choice. Verify this works as intended in a live test."
    },
    {
      "file": "commands/architecture-review.md",
      "line": 61,
      "severity": "minor",
      "message": "Step 3 spawns 2-3 parallel Task agents with no explicit concurrency limit or timeout. For large codebases this could consume significant resources. Consider documenting the expected resource envelope or adding a note that users should ensure their Claude Code session has sufficient context window."
    },
    {
      "file": "commands/architecture-review.md",
      "line": 64,
      "severity": "minor",
      "message": "The dimensions pass (Agent B) routes to the generic 'claude' subagent with a detailed prompt. The PR body acknowledges that validation against a real codebase is deferred. Consider adding a NOTE in the command that first-run validation against a real codebase is pending."
    }
  ],
  "concerns_addressed": [
    "correctness: allowed-tools list is intentionally minimal — verified. The '+' suffix on git tools is conservative but may not match `!git` variable syntax; needs live verification.",
    "correctness: Step 3 parallel Task agents — no timeout/concurrency limit is a known trade-off for deep reviews, not a bug. Consider documenting resource expectations.",
    "tests: e2e validation deferred — acknowledged as a limitation in the PR body. Acceptable for a plugin repo; should be validated before first stable release."
  ]
}