Epic: Vibe-Check — Design Quality & Architectural Metrics Toolkit

[jflowers]

What Users Get

Vibe-Check gives engineering teams automated, continuous structural quality enforcement for their codebases — starting with Go, then Python and TS/JS.

In concrete terms, when this epic is complete a user can:

1. Run vibe-check analyze ./... and get a full Martin metrics report: Afferent Coupling (Ca), Efferent Coupling (Ce), Instability (I), Abstractness (A), Distance from Main Sequence (D), LCOM cohesion, circular dependency detection, and code duplication — per package, with zone classifications (main-sequence, zone-of-pain, zone-of-uselessness).

2. Gate CI on structural quality — PRs that degrade coupling metrics, introduce circular dependencies, or increase code duplication fail the build automatically: vibe-check analyze --regression-base=origin/main --no-new-circular-deps.

3. Get AI-assisted structural review — the divisor-entropy agent joins the Review Council automatically, computing the structural delta between base and PR and blocking merges that leave the codebase worse than they found it (Boy Scout Rule enforcement).

4. Query metrics conversationally — /vibe-check summary for a health overview, /vibe-check detailed for per-package breakdown, /vibe-check trending for drift over time.

5. Track architectural drift — metrics are stored as time-series snapshots in Dewey, with an mx-f-architecture-trend agent that alerts on gradual degradation before thresholds are crossed.

6. Analyze Python projects — rattler implements the ExternalAdapter JSON-RPC 2.0 protocol, so vibe-check analyze --language=python works seamlessly.

7. Enforce codified design rules — the AD-001 through AD-010 convention pack gives agents (and reviewers) concrete, measurable structural quality constraints: max fan-out, instability limits, no circular deps, file size, DRY, cohesion thresholds.

No single OSS tool currently computes the full Martin metrics suite for Go — or any language — through a unified, language-agnostic model. Vibe-Check fills that gap with a two-layer architecture: a universal metrics model (Layer 1, complete) and language-specific adapters (Layer 2, starting with Go).

---

Foundation (Complete)

• Design universal multi-language coupling metrics model (Group 10 — architecture) #1 — Universal coupling metrics model (metrics package) — merged via PR feat: implement universal coupling metrics model (Layer 1) #17

---

Execution Order

Issues are grouped into waves by priority and dependency. Within a wave, items can run in parallel unless noted.

Wave 1 — P0: Core Engine

The unlock for everything else. Must complete sequentially (#2 then #3).

• vibe-check analyze — Go-native package-level coupling metrics #2 — vibe-check analyze (Go-native package-level coupling metrics)

  • Builds the Go adapter (internal/go/) and cobra CLI (cmd/vibe-check/) on top of the merged metrics package
  • Computes: Ca, Ce, I, A, D, LCOM, circular deps per Go package using golang.org/x/tools/go/packages
  • Outputs: JSON (ModuleGraph schema), text table, or SARIF
  • Depends on: Design universal multi-language coupling metrics model (Group 10 — architecture) #1 (done)
  • Unlocks: everything below

• divisor-entropy agent — structural delta enforcement #3 — divisor-entropy agent (structural delta enforcement)

  • New divisor-entropy.md agent auto-discovered by Review Council
  • Calls vibe-check analyze on base and PR branches, computes deltas
  • Deployed via vibe-check init (embedded in binary, //go:embed)
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2

Wave 2 — P1: Enforcement & Conventions

All items depend on #2 but are independent of each other — can run in parallel.

• Agent-design convention pack AD-001 through AD-010 (Group 3) #4 — Agent-design convention pack (AD-001 through AD-010)

  • 10 codified structural quality rules for agents: cognitive complexity, fan-out, instability, circular deps, naming, contract coverage, file size, DRY, cohesion, behavior-asserting tests
  • Enforced by vibe-check analyze (vibe-check analyze — Go-native package-level coupling metrics #2) and gaze (test quality rules)
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2 (for enforcement tooling); Code duplication detection as a vibe-check structural gate #13 (for AD-008 duplication rule)
  • Independent of divisor-entropy agent — structural delta enforcement #3, /vibe-check command and vibe-check-reporter agent #5, Package metric regression gates in CI #8

• /vibe-check command and vibe-check-reporter agent #5 — /vibe-check command + vibe-check-reporter agent

  • Three modes: summary, detailed, trending
  • Reporter agent interprets coupling data, stores snapshots in Dewey
  • Deployed via vibe-check init
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2

• Package metric regression gates in CI #8 — Package metric regression gates in CI

  • vibe-check analyze --regression-base=origin/main compares base vs PR metrics
  • Configurable thresholds: --max-instability-delta, --max-distance-delta, --no-new-circular-deps
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2

Wave 3 — P2: Depth & Multi-language

All items depend on #2. Some have additional dependencies noted.

• rattler — Python coupling adapter for vibe-check #9 — rattler (Python coupling adapter)

  • Standalone Python project implementing ExternalAdapter JSON-RPC 2.0 protocol
  • Analogous to snake-eyes for gaze — completely independent codebase
  • vibe-check analyze --language=python spawns rattler as subprocess
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2

• Architectural drift tracking and trend agent (Group 7) #12 — Architectural drift tracking

  • Time-series storage of vibe-check analyze snapshots in Dewey
  • mx-f-architecture-trend.md agent monitors trends and generates drift alerts
  • Powers /vibe-check trending mode
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2, /vibe-check command and vibe-check-reporter agent #5

• Code duplication detection as a vibe-check structural gate #13 — Code duplication detection

  • AST-based structural similarity detection for Go (go/ast)
  • vibe-check analyze --max-duplication=5 as CI gate
  • Reports duplicated blocks with file locations and similarity scores
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2

Wave 4 — P3: Future

• P3 consolidated: Supply chain security, TS/JS coupling adapter, mutation testing reference (Groups 5, 9, 10-TS/JS) #14 — P3 consolidated (supply chain security, TS/JS adapter, mutation testing reference)
  • OSV-Scanner integration, SBOM generation, license compliance
  • TS/JS coupling adapter via ExternalAdapter protocol
  • Mutation testing: reference/integration point, not standalone effort
  • Depends on: vibe-check analyze — Go-native package-level coupling metrics #2

Housekeeping (No Wave — Anytime)

• docs: Create README.md and CHANGELOG.md for initial metrics package release #18 — README.md and CHANGELOG.md
• blog: Announcing Vibe-Check — Martin Metrics for Go Codebases #19 — Blog: Announcing Vibe-Check

Gaze-Owned (Separate Project)

These issues live in this tracker but belong to the gaze project — they run on their own timeline:

• Pre-change CRAP gate: --gate-on-change flag (Group 2b) #6 — Pre-change CRAP gate (--gate-on-change in gaze)
• CRAP delta reporting in Review Council (Group 2c) #7 — CRAP delta reporting in Review Council (gaze)
• Cognitive complexity per function in Gaze + GazeCRAP-CC variant (Group 6) #10 — Cognitive complexity in Gaze + GazeCRAP-CC variant
• Branch coverage as standalone CI gate (Group 11) #11 — Branch coverage as standalone CI gate (gaze)

---

Dependency Graph

#1 (done) ──► #2 ──┬──► #3 (divisor-entropy)
                    ├──► #4 (convention pack) ◄── #13 (duplication, for AD-008)
                    ├──► #5 (/vibe-check command) ──► #12 (drift tracking)
                    ├──► #8 (regression gates)
                    ├──► #9 (rattler)
                    ├──► #13 (duplication)
                    └──► #14 (P3 consolidated)

---

Architecture

User
  │
  ├── vibe-check analyze ./...              ← #2 (CLI + Go adapter)
  │     ├── internal/go/                    ← Go-native package analysis
  │     ├── metrics/                        ← Universal model (#1, done)
  │     └── spawns ExternalAdapter          ← rattler (#9), TS/JS (#14)
  │
  ├── vibe-check analyze --regression-base  ← #8 (CI regression gates)
  │
  ├── vibe-check init                       ← Deploys agents + commands
  │     ├── .opencode/agents/divisor-entropy.md        ← #3
  │     ├── .opencode/agents/vibe-check-reporter.md    ← #5
  │     └── .opencode/commands/vibe-check.md           ← #5
  │
  ├── /vibe-check [summary|detailed|trending]          ← #5, #12
  │     └── delegates to vibe-check-reporter agent
  │           └── stores snapshots in Dewey            ← #12
  │
  └── .opencode/uf/packs/agent-design.md               ← #4
        └── AD-001..AD-010 enforced by vibe-check + gaze

RFC

https://github.com/orgs/unbound-force/discussions/483