| name | architecture-fitness-functions |
| description | Use when architecture choices need executable guardrails: dependency rules, cycle checks, boundary tests, ownership review gates, ADR compliance, runtime/resilience checks, and CI fitness functions. |
Architecture Fitness Functions
Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this plugin's root directory.
Use when architecture quality should become observable, testable, or CI-enforced.
Rule Shape
Each rule needs: intent, scope, owner, signal, mechanism, pass condition, cadence, failure action, exception path, related ADR/principle, protected quality attribute, and tradeoff.
Cadence: local, pre-commit, ci, release, scheduled, production.
Rollout: measure -> warn -> enforce for legacy systems.
Common Guardrails
- Dependency direction: domain, UI, adapters, shared packages, and apps import only allowed layers.
- Cycle prevention: package, namespace, module, service, or workspace cycles.
- Boundary API: imports only through public entry points.
- Data ownership: one bounded context owns writes for a table/topic/entity family.
- Runtime coupling: sync calls, queues, cache, external APIs follow approved directions.
- Observability/resilience: critical flows expose logs/metrics/traces/health checks and timeout/retry/fallback/idempotency policies.
- Deployment safety: migration order, feature flags, rollback readiness, compatibility windows.
- Documentation drift: architecture-changing code links ADRs, diagrams, ownership docs.
- Ownership topology: architecture-significant paths have owner coverage; cross-owned changes request both owner paths or documented waiver.
- Change amplification: co-change hotspots or touched-file width stay below agreed thresholds.
- Conformance/metrics: forbidden edges stay absent, required edges/docs exist, cycles stay absent, high fan-out requires review.
Tooling Preference
Prefer existing project tools; add dependencies only when the boundary is important and cost is explicit.
Examples: ArchUnit/jQAssistant, NetArchTest/NDepend, dependency-cruiser/eslint/Nx graph, import-linter/pytest checks, go list, cargo metadata/clippy, SwiftPM target graph/XCTest.
Lightweight start:
python3 "$PLUGIN_ROOT/scripts/architecture_probe.py" <repo-path> --json
python3 "$PLUGIN_ROOT/scripts/architecture_probe.py" <repo-path> --json --policy <policy.json>
The probe covers top-level coupling, instability, cycles, runtime signals, ownership topology, and simple policy checks.
Workflow
- State architecture principle in one sentence.
- Pick the smallest measurable signal.
- Choose cheapest existing mechanism.
- Name protected quality attribute and tradeoff.
- Define pass/fail threshold and exception policy.
- Tie to ADR/rule and rollout mode.
Output
Use architecture_intelligence.fitness_plan.v1 or a compact table: Rule, Signal, Tool, Pass condition, Cadence, Owner.
Do not create brittle gates that block delivery without migration path.
