zuvo:architecture — Review, ADR & System Design

Three modes for architecture work: audit an existing codebase structure, document a technical decision, or design a new system from requirements.

Scope: Architecture health assessment, technical decision documentation, system design from specifications. Out of scope: Per-file code quality (zuvo:code-audit), structural metrics without context (zuvo:structure-audit), test quality (zuvo:test-audit), individual file refactoring (zuvo:refactor).

Mandatory File Loading

Read these files before any work begins:

1. ../../shared/includes/codesift-setup.md -- CodeSift discovery and tool selection
2. ../../shared/includes/env-compat.md -- Agent dispatch and environment adaptation

Print the checklist:

CORE FILES LOADED:
  1. codesift-setup.md   -- [READ | MISSING -> STOP]
  2. env-compat.md       -- [READ | MISSING -> STOP]
  3. ../../shared/includes/run-logger.md -- [READ | MISSING -> STOP]
  4. ../../shared/includes/retrospective.md -- [READ | MISSING -> STOP]
  5. ../../shared/includes/backlog-protocol.md -- [READ | MISSING -> STOP]   (Filing findings through backlog-add)

If any file is missing, STOP.

Environment Compatibility

Read ../../shared/includes/env-compat.md for agent dispatch patterns, path resolution, and progress tracking across all supported platforms.

CodeSift Integration

Read ../../shared/includes/codesift-setup.md for the full initialization sequence.

Dispatch follows ../../shared/includes/execution-policy.md through env-compat. Reuse existing authorization within that policy; session restrictions take precedence. Run each required gate and report its actual independence or an unmet requirement.

Mode 1 (review) CodeSift advantages:

• get_knowledge_map(repo, depth=2) -- module relationships in one call
• detect_communities(repo, focus="src") -- architectural boundary discovery
• find_references(repo, symbol_name) -- precise fan-in/fan-out per module
• impact_analysis(repo, since="HEAD~10", depth=2) -- coupling patterns from recent changes
• analyze_hotspots(repo, since_days=90) -- churn hotspots
• trace_call_chain(repo, symbol_name, direction="callers", depth=3) -- dependency chains

Phase 0: Parse $ARGUMENTS

Explicit flags (preferred):

Heuristic fallback (when no --mode flag):

Mode 1: Architecture Review

When to use

Understanding and evaluating an existing codebase -- before a major refactor, onboarding, tech debt planning, or when something feels structurally wrong.

Non-goals

Exception: Architectural security (A8) IS in scope -- auth boundaries, input validation placement, security layer design.

Step 1 -- Read the Project Structure

Read actual files before any assessment. Never write a review from memory.

1. package.json / pyproject.toml / composer.json -- dependencies, scripts, stack
2. Directory tree (top 2 levels) -- module boundaries
3. Entry points: main.ts, app.module.ts, index.ts, server.ts
4. Key domain files: services, controllers, models (sample, not all)
5. README.md, AGENTS.md, CLAUDE.md, any docs/ folder
6. Test infrastructure -- runner config, test locations, coverage config

Test discovery (MANDATORY for A6 scoring)

Check ALL locations:

• Co-located: *.test.ts, *.spec.ts
• Centralized: __tests__/, tests/, test/
• Runner config: jest.config.*, vitest.config.*, pytest.ini, phpunit.xml
• CI config: .github/workflows/

Never score A6 without completing test discovery.

Step 1.5 -- Architecture Style Detection

Identify which architecture style(s) the codebase uses:

1. Match directory structure against known patterns (layered, feature-based, hexagonal, microkernel, etc.)
2. If monorepo detected, note each app and its individual style
3. Record: Detected style, indicators matched, confidence (HIGH/MEDIUM/LOW)

If no clear style matches, record as "Unstructured" with LOW confidence. This is itself an A1 finding.

Scope Bounding (when [path] is specified)

When reviewing a specific path: map architecture within the path only. Cross-boundary imports noted as external deps but not audited. Unobservable dimensions marked as N/A.

Step 2 -- Map the Architecture

Identify:

• Layers: presentation / application / domain / infrastructure -- present and respected?
• Module boundaries: main modules/services, cohesion assessment
• Data flow: request path from entry point to DB and back
• External dependencies: APIs, queues, caches -- coupling assessment
• Cross-cutting concerns: auth, logging, error handling -- centralized or scattered?
• Design patterns: Repository, Factory, Strategy, Adapter -- correct usage, missing patterns?

Step 2.5 -- Structural Metrics (MANDATORY)

Gather quantitative metrics before qualitative scoring. They provide evidence and prevent subjective drift.

1. Dependency cycles: Check for circular imports between modules/directories. Report cycle count and paths.
2. Fan-in / fan-out per module: For each top-level module, count cross-module imports only. Internal subdir imports DO NOT count. High cross-module fan-out (>10) = coupling risk. High fan-in (>8) = fragile shared module.
3. Module size: LOC per top-level module. Flag modules >3000 LOC as size candidates for investigation (not automatic god modules -- size alone does not confirm the anti-pattern).
4. Instability index: Per module: I = fan-out / (fan-in + fan-out). Stable (I<0.3) modules should be abstract; unstable (I>0.7) should be concrete. Flag violations.

5. Tool-assisted metrics (JS/TS projects). RUN THEM — do not check whether they are installed.

   • npx --yes madge --circular --extensions ts,tsx [source-dir] for cycle detection
   • npx --yes jscpd [source-dir] --min-lines 10 --reporters json for duplication
   • ESLint complexity rules (if project config available) For Python: uvx radon cc [source-dir] -a -nc (or pipx run radon, or radon if present)

   These are fetched on demand. Their absence from package.json, node_modules or PATH is not a reason to skip them and is not evidence that they are unavailable — npx pulls them into its own cache and writes nothing into the project, so no install consent applies (that gate exists for installs that mutate the project, not for this). --yes matters: without it npx prompts before fetching an uncached package, and in a non-interactive shell that prompt is indistinguishable from the tool being missing.

   A 2026-09-05 review of tgm-survey-platform recorded madge / jscpd | UNAVAILABLE | Not installed in this checkout and dropped A1/A3/A4 to a lexical approximation. In that same checkout npx madge --version returns 8.0.0 and npx jscpd --version returns cpd 5.0.11. Neither had been run. Report a tool unavailable only with the failing command's own error text — see the CLI-tool rules in ../../shared/includes/codesift-setup.md.

6. Temporal coupling (git history): Identify files that frequently change together despite no direct import relationship.

   git log --format=format: --name-only --since="6 months ago" | \
     awk '/^$/{if(NR>1) for(i in f) for(j in f) if(i<j) print i" "j; delete f; next} {f[$0]}' | \
     sort | uniq -c | sort -rn | head -20

   High co-change count + NO direct import = temporal coupling (hidden dependency).

Report metrics in a ## Structural Metrics section before dimension scores.

Step 3 -- Score Against 9 Dimensions

Score each dimension 0-3:

Each score requires 1-line evidence with confidence (HIGH/MEDIUM/LOW):

• HIGH: direct code evidence (file:line, metric)
• MEDIUM: inferred from patterns
• LOW: assumption based on limited sample

Weighted total: A_total = sum(A1..A9) / 27 * 100%

Inequalities, not 60-79%: the total is sum/27*100, which is fractional. Of the 28 reachable scores, 16/27 = 59.26% belonged to no band at all — above 40-59, below 60-79.

Critical gate: Any A1-A4 = 0 caps the verdict at "Significant issues" at most. A9 is informational, not gated.

Step 4 -- Identify Top Problems

For each Critical or Needs-work dimension:

• Pattern: what is wrong
• Risk: what breaks if this stays
• Fix: concrete recommendation with file references

Step 4.5 -- Reconciliation (MANDATORY before report)

Prevent contradictions between report sections:

1. List all preliminary flags from Step 2.5
2. Check each against deeper analysis in Steps 3-4
3. If invalidated: REMOVE from metrics table, anti-pattern summary, and dimension evidence
4. If partially confirmed: downgrade appropriately

The report must be internally consistent. No "Invalidated Recommendations" section.

Output -- Architecture Review Report

REQUIRED: emit the Tool Availability Block (template in ../../shared/includes/codesift-setup.md) at the top of the report, after the title and before findings. The standard table replaces the ad-hoc **Tools:** line below — do NOT use both.

# Architecture Review: [Project Name]

**Date:** [YYYY-MM-DD]
**Stack:** [framework, language, key dependencies]
**Scope:** [modules/paths reviewed]
**Tools:** [madge, eslint, jscpd, radon, CodeSift -- list used tools]

## Overview
[2-3 sentences: overall structural assessment]

## Architecture Style
**Detected:** [Style] (confidence: HIGH/MEDIUM/LOW)
**Indicators:** [folder patterns matched]

## Architecture Map
[ASCII or described component diagram with data flow]

## Structural Metrics
| Module | LOC | Cross-Module Fan-in | Cross-Module Fan-out | Instability | Notes |
|--------|-----|---------------------|----------------------|-------------|-------|

### Hidden Coupling (Temporal)
| # | Co-changes | File A | File B | Direct Import? | Verdict |

## Dimension Scores
| Dimension | Score (0-3) | Evidence | Confidence |
|-----------|-------------|----------|------------|

**Total: [N]/27 ([N]%) -- [verdict]**
**Critical gate: A1=[N] A2=[N] A3=[N] A4=[N] -- [PASS/FAIL]**

## Critical Issues
[Pattern, Risk, Fix, Files for each]

## Needs-Work Items
[Same format, lower severity]

## Strengths
[What is done well]

## Recommendations
[Prioritized by impact: 1, 2, 3]

Save to: zuvo/audits/architecture-review-YYYY-MM-DD.md — at the project root (zuvo/ resolves via git rev-parse --show-toplevel; override $ZUVO_OUTPUT_DIR. See ../../shared/includes/report-output-location.md).

Mode 2: ADR -- Architecture Decision Record

When to use

Capturing a significant technical decision: framework choice, data store selection, communication pattern, API design, auth strategy.

Step 0: Check Existing ADRs

Before writing, search docs/adr/, architecture/decisions/, adr/ for:

• Same topic: update existing ADR
• Conflicting decision: new ADR with Supersedes: ADR-[N]
• Related decision: add Related: ADR-[N] cross-reference

Step 1: Extract Context

Gather:

• The decision question (concrete: "Use Kafka vs SQS for event bus")
• Constraints (timeline, team expertise, cost, existing stack)
• Forces at play (competing requirements)
• Options (at least 2)

Step 2: Evaluate Options

Score each option across:

Step 3: Output -- ADR Format

# ADR-[N]: [Title -- specific decision question]

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-[N]
**Date:** [YYYY-MM-DD] | **Deciders:** [names] | **Area:** [Auth/Data/Infra/API/Frontend]

## Context
[2-4 sentences: situation + forces. No solution yet.]

## Decision
[One clear sentence. For security/credential decisions, pin the observable lifecycle semantics here or in Action Items -- expiry, revocation/kill-switch, retention, residual-exposure ownership -- implementers must not invent them.]

## Options Considered

### Option A: [Name]
| Dimension | Assessment |
|-----------|------------|
[Full evaluation table]

**Pros:** [list] | **Cons:** [list]

### Option B: [Name]
[Same format]

### Option C: Status Quo / Do Nothing
[Cost of change vs benefit]

## Trade-off Analysis
[Synthesize: "A wins on X/Y but loses on Z."]

## Decision Rationale
[Why this option. Connect to constraints.]

## Consequences
- **Easier:** [what this enables]
- **Harder:** [what this constrains]
- **Revisit when:** [trigger conditions]

## Action Items
- [ ] [steps]

Save to: docs/adr/[NNNN]-[slug].md

Mode 3: System Design

When to use

Designing a new service, API, or subsystem from requirements.

Framework (6 Steps)

Step 1 -- Requirements

• Functional: what it does (user stories or capabilities)
• Non-functional: scale (RPS), latency (P50/P99), availability (SLA), cost
• Constraints: team size, timeline, tech stack, compliance

Step 2 -- High-Level Design

• Component diagram: services, stores, queues, clients
• Data flow: input to output paths
• API contracts: interfaces between components
• Storage choices: data store per data type with rationale

Step 3 -- Deep Dive (focus on the hardest parts)

• Data model: entities, relationships, indexes
• API design: endpoints, shapes, pagination
• Caching: what, where, TTL, invalidation
• Queue/event design: topics, consumers, delivery guarantees
• Error handling: retry, dead-letter, circuit breakers

Step 4 -- Scale and Reliability

• Load estimation: peak RPS, data volume, storage growth
• Bottlenecks: where it breaks first
• Horizontal scaling: which components
• Failover: per-component failure plan
• Monitoring: health metrics

Step 5 -- Rollout and Migration (MANDATORY)

• Migration plan: current state to new design
• Backward compatibility: what breaks, dual-write periods
• Rollout strategy: big bang / gradual / canary with rationale
• Rollback plan: data safety, API compatibility
• Timeline: phases with go/no-go criteria

Step 6 -- Trade-offs and Open Questions

• Make every design trade-off explicit
• List assumptions that could change the design
• Identify what to revisit at 10x scale

Output -- Design Document

# [System Name] -- Design Document

**Status:** Draft | Review | Approved | **Date:** [YYYY-MM-DD]
**Author(s):** [Names] | **Related ADRs:** [links]

## Summary
[2-3 sentences]

## Requirements
- **Functional:** [capabilities]
- **Non-functional:** Scale [RPS], Latency [P50/P99], Availability [SLA]
- **Constraints:** [timeline, team, stack, compliance]

## High-Level Design
[ASCII diagram + data flow]

## Data Model
[Key entities, relationships, indexes]

## API Design
[Key endpoints with request/response shapes]

## Rollout and Migration
[Step-by-step or "Greenfield"]

## Trade-offs
| Decision | Chose | Alternative | Why |

## Open Questions and Scale Triggers

Save to: docs/design/[slug].md

Adversarial Review on Output (MANDATORY — do NOT skip)

After generating the architecture output (review report, ADR, or design document), run cross-model validation. Point --files at the file you just wrote — do NOT run the literal placeholder (it matches nothing and burns a pass).

# review mode → zuvo/audits/architecture-review-<date>.md; adr/design mode → the docs/ file you wrote
OUT="$(ls -t zuvo/audits/architecture-review-*.md 2>/dev/null | head -1)"   # or set to your ADR/design path
[ -n "$OUT" ] && [ -f "$OUT" ] && ~/.zuvo/adversarial-review --mode audit --files "$OUT" \
  || echo "adversarial: set OUT to the architecture file you just wrote"

Record the verdicts after triage: every finding is fixed, rejected (a false positive) or deferred — record each by its ID: in ONE call, ~/.zuvo/adversarial-review --record-disposition ID-1 fixed --record-disposition ID-2 rejected …, per ../../shared/includes/adversarial-loop.md Step 4.9 (the review lists its IDs on stderr).

If adversarial-review is not in PATH: ~/.zuvo/adversarial-review (stable; the versioned cache path breaks after any release)

Wait for complete output. Then:

• CRITICAL (unsupported claims, missing evidence, contradictions) → fix in output before delivery
• WARNING (vague rationale, missing alternatives) → append to open questions section
• INFO → ignore

Completion

After completing any mode, print the completion block:

ARCHITECTURE COMPLETE
-----
Mode:   [review | adr | design]
Run: <ISO-8601-Z>	architecture	<project>	-	-	<VERDICT>	-	<DURATION>	<NOTES>	<BRANCH>	<SHA7>	<INCLUDES>	<TIER>
-----

Retrospective (REQUIRED)

Follow the retrospective protocol from retrospective.md. Gate check → structured questions → TSV emit → markdown append. If gate check skips: print "RETRO: skipped (trivial session)" and proceed.

Append via wrapper (REQUIRED). Never >> directly to ~/.zuvo/runs.log — the wrapper is the gate that verifies a retro entry exists for this run. Order: retro bash executed → wrapper invoked → completion claimed.

printf '%b\n' "$RUN_LINE" | ~/.zuvo/append-runlog

Expected stdout: OK: appended to runs.log (retro verified for <skill> on <project>). If exit 2 with RETRO_REQUIRED — go execute the retro bash from retrospective.md first; never bypass with ZUVO_SKIP_RETRO_GATE=1. After the wrapper succeeds, print a Logs: evidence line (tail -1 ~/.zuvo/retros.log, grep -c "^<!-- RETRO -->" ~/.zuvo/retros.md, tail -1 ~/.zuvo/runs.log) before claiming completion. Printing the markdown retro section without executing the bash leaves all three log files empty.

<DURATION>: use the mode label (review, adr, or design).

Backlog Integration (ALL MODES)

After completing any mode, every actionable item below goes through backlog-add, one call per item (../../shared/includes/backlog-protocol.md "Filing from a skill"; the bars, the dedupe and where the backlog lives are the protocol's, so compute no fingerprint and restate nothing).

Review mode: each Critical and Needs-work issue from the report is a Generic write, --severity critical for a Critical one and --severity medium for a Needs-work one (<level> below). The class follows the dimension: A1 Modularity, A2 Layering, A3 Dependency direction, A5 Scalability, A6 Testability, A7 Observability and A9 SOLID are CQ; A4 is SIZE for a god class or module over its size limit, CPLX for one too complex to follow, DUP for duplicated logic, else CQ; A8 Security boundary is SEC. A CQ, SIZE, CPLX or DUP issue takes no anchor: ~/.zuvo/backlog-add --repo "$R" --class CQ --conf <N> --source architecture --file "$F" --line <n> --severity <level> --title "$T" (pass SIZE, CPLX or DUP as the class for those). A SEC issue takes --anchor "$A", copied from the line that shows the defect or, for a missing check, from the line of the code that lacks it ("The location rule"): ~/.zuvo/backlog-add --repo "$R" --class SEC --conf <N> --source architecture --file "$F" --line <n> --anchor "$A" --severity <level> --title "$T". An issue that holds for the whole file is a whole-file finding: --line 1, a "Whole file: ..." title. A repo-wide issue with no single file (a dependency cycle, a layering violation) is filed at the first file of the cycle or violation in path order (byte-wise, LC_ALL=C sort: backlog-protocol.md "The location rule"), with --line 1 and a "Whole file: ..." title, and you append --evidence "$E" to that call, listing the other files, one per line. ADR mode: each "Harder" consequence, "Revisit when" trigger and incomplete action item is a Process item, and so is each open question, scale trigger and rollout risk of Design mode. A question is a decision subject: ~/.zuvo/backlog-add --repo "$R" --class PROCESS --conf 90 --source architecture --target subject:architecture-decision-<slug> --evidence "$E" --title "$T", with T the question (or the follow-up), the same words on every run, and E both options (for a consequence or risk with one answer, the mitigation and accepting it). <slug> is the decision slug (backlog-protocol.md "Filing from a skill", The decision slug), written into the report entry.

Assign "$R" and "$T" before each call, "$F" only for a file finding ("$A" only for a SEC one), "$E" only for a process item or a repo-wide issue, as "Free text goes through a variable" in that section says; an empty value you pass is a bug, and backlog-add refuses a missing required field (REFUSED missing-field:<f>). Report the B- or F-id each call prints and Recorded: N (backlog: a, ledger: b) ("The report line" in backlog-protocol.md), plus each NOT PERSISTED (<reason>) by name, and name each process item's F-id in the final summary. On a non-zero exit act on the protocol's exit table, and never append by hand.

Nothing is dropped silently: an item is recorded, or listed under NOT PERSISTED (<reason>).

This audit does not commit: it stages nothing. It lists the wrote= paths backlog-add printed as Backlog writes: <path>, ... (Backlog writes: none when there are none), in its report for the user when it runs standalone, and in its report for the calling skill's closing commit to carry when another skill runs it (backlog-protocol.md "Filing from a skill", Committing what backlog-add wrote).