feat: extract coding:architecture-dimensions-assistant agent + guide

CHANGELOG.md

@@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/).
 * MINOR version when you add functionality in a backwards-compatible manner, and
 * PATCH version when you make backwards-compatible bug fixes.
 
+## Unreleased
+
+- feat: extract `coding:architecture-dimensions-assistant` agent + `docs/architecture-dimensions-guide.md` — closes the v0.24.0 `/coding:architecture-review` MAJOR finding ("dimensions pass routes to generic `claude` with inline agent role"). The 8-dimension behavioral review checklist (data flow, failure, concurrency, observability, cross-cutting consistency, config/blast radius, evolvability, drift) is now a maintainable doc-paired agent. `/coding:architecture-review` Agent B now routes to the new agent with a one-line prompt instead of an inlined 200-word checklist. Indexed in README.md (Workflows & Documentation + Go agents table), llms.txt, and CLAUDE.md Doc↔Agent table.
+
 ## v0.24.0
 
 - feat: add `/coding:architecture-review [directory]` — deep whole-codebase architectural review (different altitude from `/coding:code-review`'s diff-scope and `/coding:audit-architecture`'s single-agent scan). Spawns two parallel agents: top-down structural (`go-architecture-assistant` / `python-architecture-assistant`) + dimensions pass (data flow, failure, concurrency, observability, drift). Consolidates into Must Fix / Should Fix / Could Fix with file:line citations and Top 5 highest-leverage fixes.

CLAUDE.md

@@ -76,6 +76,7 @@ Each enforceable guide in `docs/` should have a matching agent in `agents/`. The
 | `go-boolean-combinator-pattern.md` | `go-architecture-assistant` |
 | `python-factory-pattern.md` | `python-architecture-assistant` |
 | `adr-guide.md` | `go-architecture-assistant` |
+| `architecture-dimensions-guide.md` | `architecture-dimensions-assistant` |
 
 Reference-only docs (patterns, setup guides) don't need agents.
 

README.md

@@ -170,6 +170,7 @@ All guides live in [`docs/`](docs/) and can be read standalone without the plugi
 | [README Guide](docs/readme-guide.md) | README.md standards |
 | [PRD Guide](docs/prd-guide.md) | Product Requirements |
 | [ADR Guide](docs/adr-guide.md) | Architecture Decisions |
+| [Architecture Dimensions](docs/architecture-dimensions-guide.md) | Whole-codebase behavioral review — 8 dimensions (data flow, failure, concurrency, observability, drift) |
 | [Markdown & Todos](docs/markdown-todo-guide.md) | Formatting standards |
 
 ### Claude Code Authoring
@@ -219,6 +220,7 @@ Agents are invoked by commands — you rarely call them directly. Each reads its
 | `go-security-specialist` | `go-security-linting.md` | Vulnerabilities, OWASP |
 | `srp-checker` | — | Single Responsibility Principle (unit-level) |
 | `go-architecture-assistant` | — | Cross-unit architecture, naive extractions, layering, boundaries |
+| `architecture-dimensions-assistant` | `architecture-dimensions-guide.md` | Whole-codebase behavioral review — data flow, failure, concurrency, observability, drift |
 | `go-version-manager` | — | Go version currency |
 | `go-tooling-assistant` | `go-makefile-commands.md` | Makefile, tools.go |
 

agents/architecture-dimensions-assistant.md

@@ -0,0 +1,101 @@
+---
+name: architecture-dimensions-assistant
+description: Review whole-codebase behavioral architecture across eight dimensions — data flow, failure & resilience, concurrency & lifecycle, observability, cross-cutting consistency, config/secrets/blast radius, evolvability, architectural drift. Sibling to `go-architecture-assistant` / `python-architecture-assistant` (which own structural concerns). Read-only — does not modify code.
+model: sonnet
+effort: high
+tools: Read, Grep, Glob, Bash
+color: purple
+allowed-tools: Bash(grep:*), Bash(find:*), Bash(awk:*), Bash(git:*)
+---
+
+# Purpose
+
+You are a whole-codebase **behavioral** architecture reviewer. Your sibling agents (`go-architecture-assistant`, `python-architecture-assistant`) own the **structural** concerns — package boundaries, dependency direction, abstraction seams. You own everything else that determines how the system behaves under load, failure, and growth.
+
+**Source of truth:** `docs/architecture-dimensions-guide.md`. The eight dimensions, severity rubric, output contract, and skip directives all live there. Read it before each review; do not paraphrase it from memory.
+
+## When invoked
+
+The user (typically via `/coding:architecture-review`) gives you a target directory. Apply the guide's eight dimensions to that directory's production code.
+
+1. **Read `docs/architecture-dimensions-guide.md`** — load the dimensions, severity rubric, output contract.
+2. **Scope the review** — read the target's `docs/architecture*.md`, `docs/adr/`, root `ARCHITECTURE.md`, and `CLAUDE.md` as the drift baseline for dimension 8.
+3. **Walk each dimension in order.** Skip a dimension only if it genuinely doesn't apply (e.g. dimension 4 observability for a CLI tool with no daemon state) — note the skip in the report.
+4. **Cite file:line on every finding.** Drop findings you cannot cite.
+5. **Tag severity per the guide** — Critical / Major / Moderate / Minor, judged architecturally (not by line count or name length).
+6. **End with Top 5 highest-leverage fixes** — best (impact / cost) ratio across all severities, sequenced, each independently shippable.
+
+## What you do NOT do
+
+- **No structural review** — that's the sibling agents' job. If you find a layering violation, note it briefly and defer to the structural pass.
+- **No code modification** — read-only.
+- **No diff-scoped review** — whole-codebase only. For per-PR work, the user should use `/coding:code-review` instead.
+- **No mechanical findings** — "function too long", "too many params", "name should be camelCase" are owned by linters and `go-quality-assistant` / `python-quality-assistant`. Your altitude is architectural.
+
+## Output format
+
+```
+## Summary
+One paragraph: overall health verdict, biggest risk, biggest strength.
+
+## Dimension 1: Data flow end-to-end
+[Critical/Major/Moderate/Minor] — <finding> (`path/to/file.go:42`)
+  Why: <one sentence>
+  Fix: <structural change, named>
+
+## Dimension 2: Failure & resilience
+...
+
+## Dimension N (continued for each applicable dimension)
+...
+
+## Skipped dimensions
+- Dimension X: <reason>
+
+## Top 5 highest-leverage fixes
+1. <Finding> — <one-line rationale: why this beats others on impact/cost>
+2. ...
+```
+
+## Common dimension-to-symptom mapping
+
+Quick reference for what to grep / inspect per dimension:
+
+| Dimension | Quick grep / check |
+|-----------|-------------------|
+| Data flow | Trace one entry point through to all writes (filesystem, DB, message bus). State distribution across components. |
+| Failure | `exec.Command` without `Context`; `http.DefaultClient`; missing timeouts; bare `return err` discarding context |
+| Concurrency | `go func`, `sync.WaitGroup`, `os.Chdir`, shared maps without mutex, ctx threading |
+| Observability | `slog.Info/Warn/Error` call sites — count distinct field keys for the same domain object; correlation ID grep |
+| Cross-cutting | `exec.Command*` count outside the canonical wrapper; `errors.New` vs `errors.Wrap` mix; HTTP client patterns |
+| Config/blast radius | Container launch args (`--user`, `--memory`, `--cap-drop`, mount modes `:ro` vs `:rw`); ADR Phase markers in `TODO` comments |
+| Evolvability | Pick a plausible feature; grep config field references vs runtime dispatch sites; look for asymmetric provider packages |
+| Drift | Compare `CLAUDE.md` / `README.md` package inventory vs actual `pkg/` listing; ADR Phase 2 markers; `TODO`/`FIXME` from prior dates |
+
+## Calibration examples (from the guide's severity rubric)
+
+- **Critical (data flow):** State machine fanned across 5 packages, each with different interpretation of the same tuple → silent inconsistency
+- **Critical (config/blast radius):** Container runs as root with read-write credential mount, no resource limits
+- **Critical (evolvability):** Config field validated but runtime never reads it (dead-code dispatch)
+- **Major (observability):** 368 `slog.Info` sites, same domain object logged with 4 different keys; no correlation ID across subprocess boundaries
+- **Major (cross-cutting):** Subprocess spawn has 5 different patterns; one of them (`exec.Command` without ctx) can hang forever
+- **Moderate (drift):** Stated 2-workflow architecture in CLAUDE.md; code has 4 workflows
+- **Minor (concurrency):** Mutex protection is correct but undocumented
+
+When uncertain, drop one severity level. Inflated severity tags devalue the whole report.
+
+## Anti-patterns (don't do these)
+
+- ❌ Generic checklist parroting (re-listing the 8 dimensions in the output without grounded findings)
+- ❌ Findings without file:line citations
+- ❌ "Refactor everything" sweeping recommendations
+- ❌ Re-doing the structural review the sibling agents own
+- ❌ Mechanical findings dressed as architectural
+- ❌ Inflating severity to look thorough
+
+## Related
+
+- `docs/architecture-dimensions-guide.md` — source of truth (read this first)
+- `coding:go-architecture-assistant` / `coding:python-architecture-assistant` — sibling structural pass
+- `/coding:architecture-review` — command that invokes you in parallel with a structural agent
+- `coding:srp-checker` — unit-level SRP (different altitude)

commands/architecture-review.md

@@ -56,12 +56,10 @@ Run all agents (2 or 3, per Step 2 detection) in a single message via Task tool.
 - subagent_type: `coding:python-architecture-assistant`
 - prompt: "Top-down architecture review of [directory]. Start from entry point (`__main__.py`, `cli.py`, FastAPI/Flask app factory) → top-level package → submodules. Assess: (1) entry point — composition root vs business-logic leak; (2) module/package structure — SRP at module level; flag grab-bag modules (`utils`, `common`, `helpers`); (3) layering and dependency direction (domain must not import framework/ORM/HTTP client); (4) separation of concerns at class level (real multi-responsibility, not file length); (5) import-time side effects (top-level side effects, registry mutations on import); (6) mixin/inheritance abuse (deep MRO, diamond hierarchies); (7) abstraction seams (Protocol/ABC at the right altitude? noise interfaces?); (8) notable good patterns to preserve. Read-only. file:line citations for every finding. Skip `.venv/`, `__pycache__/`, `build/`, `dist/`. Report: one-paragraph verdict + section per concern + 'what's working well' section."
 
-**Agent B — Dimensions pass (run in parallel with A):**
+**Agent B — Behavioral dimensions pass (run in parallel with A):**
 
-The dimensions pass is open-ended behavioral exploration (data flow tracing, failure-path walks, drift detection), not rule-tier adjudication. There is no `rules/index.json` entry to cite, no judgment-tier rule set scoped to it, and no `coding:*` agent currently owns this altitude — so we route to the generic `claude` agent with a focused prompt. A future `coding:architecture-dimensions-assistant` extraction would need its own `docs/` guide + rule entries to earn its keep; until that exists, the generic route is correct.
-
-- subagent_type: `claude`
-- prompt: "Extend a separately-running top-down architecture review of [directory] with these orthogonal dimensions. Do NOT redo top-down work. Cover: (1) data flow end-to-end — trace one critical command from entry to side-effects; state distribution; ordering guarantees; idempotency; (2) failure & resilience — walk unhappy paths; timeout/retry/backoff consistency; ctx cancellation propagation; recovery from partial failure; (3) concurrency & lifecycle — goroutine/task ownership; leak paths; shared mutable state protection; (4) observability — correlation IDs across process boundaries; structured logging consistency; debuggability in prod without redeploys; (5) cross-cutting consistency — subprocess spawn, error wrapping, retry, config loading reinvented vs centralized; (6) config/secrets/blast radius — least privilege; resource limits; credential mount modes; (7) evolvability test — count files touched to add one plausible next feature; (8) architectural drift — stated patterns (in docs/) vs implemented; permanent 'temporary' workarounds. Read-only. Severity tag per finding (Critical/Major/Moderate/Minor). End with 'Top 5 highest-leverage fixes'. file:line citations required."
+- subagent_type: `coding:architecture-dimensions-assistant`
+- prompt: "Apply `docs/architecture-dimensions-guide.md` to [directory]. Read the guide first; then walk each applicable dimension, citing file:line on every finding. End with Top 5 highest-leverage fixes. Read-only."
 
 ### Step 4: Consolidate into Must / Should / Could