architecture

name: architecture description: > Architecture skill with three modes: review existing codebase architecture (A1-A9 dimensions), create Architecture Decision Records, or design new systems from requirements. Modes: --mode review [path], --mode adr, --mode design. Uses CodeSift for module discovery, dependency mapping, structural metrics, and temporal coupling detection. codesift_tools: always: - analyze_project - index_status - index_folder - index_file - plan_turn - get_file_tree - get_file_outline - detect_communities # KEY — module discovery - check_boundaries # boundary violations - fan_in_fan_out # coupling - classify_roles # hub/leaf/bridge - architecture_summary - find_circular_deps - analyze_complexity - analyze_hotspots # temporal coupling - search_text - search_symbols - codebase_retrieval # semantic — design questions - audit_scan by_stack: typescript: [get_type_info] javascript: [] python: [python_audit, analyze_async_correctness] php: [php_project_audit, php_security_scan, resolve_php_namespace] kotlin: [analyze_sealed_hierarchy, find_extension_functions, trace_flow_chain, trace_suspend_chain, trace_compose_tree, analyze_compose_recomposition, trace_hilt_graph, trace_room_schema, analyze_kmp_declarations, extract_kotlin_serialization_contract] nestjs: [nest_audit] nextjs: [framework_audit, nextjs_route_map] astro: [astro_audit, astro_actions_audit, astro_hydration_audit, astro_middleware, astro_sessions] hono: [analyze_hono_app, audit_hono_security, detect_hono_modules] express: [] fastify: [] react: [react_quickstart, analyze_hooks, analyze_renders, analyze_context_graph, audit_compiler_readiness, trace_component_tree] django: [analyze_django_settings, effective_django_view_security, taint_trace] fastapi: [trace_fastapi_depends, get_pydantic_models] flask: [find_framework_wiring] jest: [] yii: [resolve_php_service, trace_php_event, find_php_views] prisma: [analyze_prisma_schema] drizzle: [] sql: [sql_audit] postgres: [migration_lint]

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]

If any file is missing, STOP.

Environment Compatibility

Read ../../shared/includes/env-compat.md for agent dispatch patterns, path resolution, and progress tracking across Claude Code, Codex, and Cursor.

CodeSift Integration

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

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):

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

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%

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

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

adversarial-review --mode audit --files "[output file path]"

If adversarial-review is not in PATH: ~/.claude/plugins/cache/zuvo-marketplace/zuvo/*/scripts/adversarial-review.sh

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, persist actionable items to memory/backlog.md:

Review mode: Each Critical and Needs-work issue from the report. ADR mode: "Harder" consequences, "Revisit when" triggers, incomplete action items. Design mode: Open questions, scale triggers, rollout risks.

Zero risks may be silently discarded. If the output has consequences, questions, or risks, they must reach the backlog.