Second Brain

class-audit-pattern-wiring-artifact-class-to-workflow-stages

3 min read

Class-Audit Pattern — wiring artifact-class to workflow stages with canonical disambiguation + drift detector

Class-Audit Pattern

When a class of system artifact (plugins, MCP servers, skills, infra services) gets installed without explicit per-instance integration into the active workflow surface, dormant capability accumulates and ambiguous overlaps create silent behavioral drift across sessions. The Class-Audit Pattern resolves this in a single session via four cohesive layers — applicable to any agent maintaining a multi-artifact intelligence system.

When to invoke

  • After a new plugin / MCP / skill bundle lands and the agent realizes mandates haven’t been updated
  • After an unexpected upgrade incident exposes that no drift detector exists
  • When AJ asks “are we making most of all the available X?” — that’s a class-audit prompt
  • Periodically (e.g., quarterly) for any artifact class with >5 instances

The four layers

LayerWhat it producesWhy it’s needed
1. Class × Workflow-stage matrixA table mapping each artifact instance to the workflow stage(s) where it should be dispatchedMakes orchestrators know which primitive to call at which step. Without this, orchestrators reinvent what artifacts already provide → Law 10 (Full Capability) violation.
2. Canonical disambiguation tableFor every overlapping capability, the ONE canonical instance + the aliases that must NOT be invokedEliminates the “which-do-I-pick” deliberation tax. Without this, different sessions pick differently → Law 2 (Zero Ambiguity) violation.
3. Drift detector cronSnapshots the artifact inventory, alerts on unannounced version/instance changesMakes auto-upgrades visible the morning after, not when something breaks. Without this, silent upgrades cause crash loops (e.g., versioned-path systemd ExecStart breaks when plugin auto-upgrades).
4. Orchestrator-skill pointerAdds a “Plugin Primitive Cohesion” / equivalent principle to the master-orchestrator skill referencing the matrixEnsures the matrix is LIVE behavior, not just documentation. Every orchestrator dispatch reads the matrix.

All four must ship in the same session the audit runs. Skipping any one means the gap that triggered the audit will recur.

Reference implementation

2026-04-26 plugin utilization audit on AJ’s developer enterprise (arjtech-dev):

  • 9 plugins installed (Superpowers, pr-review-toolkit, engineering, plugin-dev, ralph-loop, hookify, anthropic-skills, playground, skill-creator), pre-audit utilization ~55%
  • Layer 1: 12-row Helix Layer × Plugin Primitive Wiring table in plugin-integration.md (L1-L7 + Meta + session-close + documentation deliverables)
  • Layer 2: feedback_plugin_capability_routing.md for 9 overlapping capabilities (skill-creation triplet → superpowers:writing-skills, recurring-loops → loop, review → pr-review-toolkit:review-pr, etc.)
  • Layer 3: plugin-version-drift-check.sh cron at 02:30 IST, snapshots installed_plugins.json with 30-day retention, Telegrams on drift
  • Layer 4: master-orchestrator/SKILL.md Principle 6 — Plugin Primitive Cohesion

Trigger event: 25-Apr Superpowers 5.0.5→5.0.7 silent auto-upgrade broke brainstorm.service (versioned-path ExecStart) — 4,300 cold-start failures in 6h. Drift detector (Layer 3) alone wouldn’t have prevented the crash, but combined with the wrapper-everywhere mandate (/usr/local/bin/<service>-launch.sh resolves version at runtime) it makes the failure class extinct.

Anti-patterns

  • Adding a plugin and writing a plan to “wire it later” — that “later” never comes; the plugin sits dormant.
  • Picking-by-vibe each session (“which excalidraw / schedule / skill-creator do I use this time?“) — silent behavioral drift.
  • Documenting the matrix without a pointer in the orchestrator skill — read-only documentation, not enforcement.
  • Drift detector that only logs without alerting — silent log files don’t change behavior.

Cross-system applicability

This pattern is class-agnostic. Other classes where it applies:

  • MCP servers (Permanent + on-demand split) — already governed by feedback_mcp_two_tier_model.md
  • Skills bundle (~150 entries) — periodic audit prevents Law-2 ambiguity as new skills land
  • Crons (/root/.claude/crons/) — drift detection prevents orphan cron accumulation
  • Infra services in docker-compose — Class × Service Mesh Routing matrix ensures every service has a known consumer

Graph View

Backlinks