Coupling Router

🔀 Coupling Router — Architectural Delegation, Skill-Stack & Concurrency Router

Evaluates the topological coupling of a task breakdown and audits active skill stacks before dispatching subagents. Deterministically routes tightly coupled tasks (shared types, schema migrations, rendering pipelines) to a single sequential builder, dispatches truly orthogonal tasks (isolated test suites, independent docs, separate microservices) to parallel fan-out subagents, and audits installed skills to enforce a Minimal Viable Skill Set (MVSS) that eliminates prompt contradictions and token bloat.

When to Use

Trigger Conditions

Execute this skill when:

1. Planning Multi-Agent Delegation: You have a task list or project plan with 2 or more subtasks.
2. Auditing Skill-Stack Compatibility: Multiple agent skills are installed or active, risking prompt contradictions, overlapping triggers, or token budget exhaustion.
3. Enforcing Minimal Viable Skill Set (MVSS): Trimming secondary/redundant skills when a primary dominant skill (e.g., ai-ready, git, refactor-ui, code-review) already covers the execution scope.
4. Preventing Merge Collisions: Multiple files or modules share mutable state, type contracts, or lifecycle flows.
5. Deciding Concurrency Strategy: Resolving whether to spawn subagents concurrently in parallel or pipeline them sequentially.
6. Complex Refactors: Multi-layer changes spanning database schemas, API controllers, and frontend clients.
7. Shared Checkout, Multiple Sessions (/worktree-lease): Another agent session (or a human) may be working in the same git clone — acquire or respect the worktree lease before switching branches, touching stashes, or staging shared files.

Anti-Triggers

Do NOT use this skill when:

• Executing a single atomic task in the current conversation without subagents.
• Running simple batch queries or file searches across unrelated directories where only one skill is needed.

Quick Reference

Coupling Decision Matrix

                        ┌───────────────────────────────┐
                        │   Task Graph Dependency &     │
                        │    Skill Stack Pre-Flight     │
                        └──────────────┬────────────────┘
                                       │
                ┌──────────────────────┴──────────────────────┐
                ▼                                             ▼
     ┌──────────────────────┐                      ┌──────────────────────┐
     │    HIGH COUPLING     │                      │     LOW COUPLING     │
     │ - Shared type defs   │                      │ - Independent files  │
     │ - DB schema updates  │                      │ - Separate docs/libs │
     │ - Pipeline state     │                      │ - Isolated unit tests│
     └──────────┬───────────┘                      └──────────┬───────────┘
                │                                             │
                ▼                                             ▼
     ┌──────────────────────┐                      ┌──────────────────────┐
     │ SEQUENTIAL PIPELINE  │                      │   PARALLEL FAN-OUT   │
     │ Single builder agent │                      │ Concurrent subagents │
     │ with linear commits  │                      │ with disjoint scopes │
     └──────────────────────┘                      └──────────────────────┘

Coupling Classification Rubric

Skill Compatibility & Conflict Matrix

Skill Precedence Hierarchy

Tier 1: Governance & Verification (secretary, evidence-ledger, gauntlet-loop)
   └── Tier 2: Review & Correctness Doctrine (code-review / Karpathy)
         └── Tier 3: Architecture & Context Engines (coupling-router, ai-ready, agent-engine)
               └── Tier 4: Domain Implementation Specialists (refactor-ui, designscope, updatedocs, git)
                     └── Tier 5: Ad-Hoc / Generic Prompts (Suppressed when higher tiers active)

Procedure

Step 0 — Worktree Lease Gate (shared checkouts)

Before any git mutation (branch switch, stash push/pop, git checkout --, commit, branch force-update) in a clone that another session may share:

1. Probe .agents/artifacts/WORKTREE-LEASE.md. Absent → acquire (write owner/branch/heartbeat/scope/notes, ≤20 lines). Present with a fresh heartbeat (≤30 min) → you are the second session: take a separate git worktree add directory (preferred), stay read-only, or wait — never mutate shared git state. Present with a stale heartbeat → takeover: append a takeover line, preserve any WIP recorded in the lease notes as foreign.
   • One-command gate: bun <skill-dir>/coupling-router/scripts/worktree-lease.ts probe --owner <id> --scope "<paths>" (exit 0 = clear to mutate, exit 1 = defer; also hold and release subcommands).
2. Re-probe before each mutation; stage explicit paths only; never pop a stash you did not create; audit shared-surface diffs hunk-by-hunk (skills.json, llms.txt, README, CHANGELOG).
3. Release at close: fold state into HANDOFF.md, delete the lease, leave a residual-state note for whatever stays in the worktree.

Full contract, takeover rules, and the collision repair ladder: references/worktree-lease-protocol.md.

Step 1 — Skill-Stack Compatibility & Conflict Audit

1. Inventory Candidate Skills: Identify all installed or triggered skills requested for the workflow.
2. Pairwise Conflict Check: Consult references/skill-compatibility-matrix.md to evaluate interactions between candidate skills.
3. Resolve Contradictory Directives:
   • If an instruction contradiction exists (e.g. broad speculative refactoring vs surgical diff discipline), enforce the higher precedence tier and silence the subordinate rule.
4. Select Minimal Viable Skill Set (MVSS):
   • Suppress redundant secondary skills (e.g., suppress new-project Stage 0 if ai-ready is active; suppress generic styling if refactor-ui is active).
5. Enforce Token Budget Gate:
   • Ensure the total active skill prompt footprint remains $\le 6,000$ tokens ($\le 3$ active skills per subagent context).
   • Prune auxiliary skills into staged sequential handoffs if the token budget is exceeded.

Step 2 — Plan-Evaluation Gate (pre-execution)

Before any dispatch, evaluate the routing plan itself against five checks. A plan that fails any check is rejected and reworked — not dispatched with caveats:

The primary verdict is spec alignment: a plan missing spec alignment is rejected as primary, before the other checks are even consulted.

Multi-perspective review (plans with ≥5 tasks): a large plan is reviewed through more than one lens before dispatch — at minimum three, in sequence: (1) spec/devil's-advocate lens — does each task trace to the spec, and what premise could invalidate it; (2) coupling lens — write-overlap matrix, interface locks, wave structure (the checks of Steps 3–4); (3) failure lens — for each wave, what happens when it fails: recovery owner, dead-letter route, dependent-skip policy. Findings from each lens are recorded against the plan; unresolved findings reject the plan. Single-lens review is acceptable only below 5 tasks.

Step 3 — Dependency & Artifact Overlap Audit

1. List all planned subtasks: $T_1, T_2, \dots, T_n$.
2. For each task, list intended Input Dependencies and Target Write Files.
3. Calculate the Write-Overlap Matrix:
   • If two tasks write to the same file or package interface $\rightarrow$ HIGH COUPLING ($C \ge 0.6$).
   • If Task $B$ reads the output of Task $A$ before starting $\rightarrow$ SEQUENTIAL DEPENDENCY.

Step 4 — Interface Invariant Check

Audit whether shared types, API schemas, or configuration contracts are already established and locked:

• Unlocked Interfaces: Must be assigned to a single precursor task before any downstream work begins.
• Locked Interfaces: Downstream implementations can safely parallelize.

Step 5 — Emit Routing Plan (ROUTING_PLAN.md)

Output structured routing instructions:

• Skill Stack Allocation: Active Minimal Viable Skill Set (MVSS) and explicitly suppressed skills.
• Execution Strategy: SEQUENTIAL | STAGED_PIPELINE | PARALLEL_FAN_OUT.
• Task Ordering Graph: Mermaid DAG showing execution phases, barriers, and subagent assignments.
• Context Allocation: Explicit scope and file boundaries for each assigned agent.
• Lease Handshake (shared checkouts): every git-mutating task spec embeds the one-command lease probe (scripts/worktree-lease.ts probe --owner <task-id> --scope "<paths>") as its first step; tasks whose scopes overlap on one checkout are never dispatched concurrently.
• Implementation-Existence Clause: every task marked complete in the plan carries a verification receipt — the test run, file path, or command output proving the work exists and passes. A completion claim without a receipt reopens the task.

Pitfalls

• Skill Token Bloat: Loading 5+ skills simultaneously, exhausting 30–50% of the context window with redundant instructions before reading user code.
• Contradictory Mandates: Running un-audited skills where one demands "speculative architectural refactoring" and another demands "surgical, minimal diffs".
• False Parallelism: Spawning 3 parallel agents to write client, server, and shared types simultaneously guarantees merge conflicts and divergent interfaces.
• Premature Concurrency: Parallelizing tasks before the database schema or shared interfaces are committed and tested.
• Dispatching an Unverified Plan: Skipping the Plan-Evaluation Gate because the plan "looks right" — spec-misaligned or unverifiable tasks produce rework that exceeds the gate's cost by an order of magnitude.
• Unverified Completion Claims: Accepting "done" from a subagent without a verification receipt — premature completion is the #1 multi-agent failure mode.
• Over-Serialization: Forcing documentation, standalone unit tests, and independent CSS styling into sequential bottlenecks when they share zero files.
• Blind Staging in a Shared Checkout: git add . in a clone where another session left WIP sweeps their hunks into your commit; a branch switch behind their back orphans their uncommitted work onto the wrong branch. Probe the lease first; stage explicit paths only.

Verification

Before executing subagent delegation:

1. Plan-Evaluation Gate passed: spec alignment, verifiable acceptance criteria, DAG integrity, no overlap with completed work, evidence-backed assumptions.
2. Active skills audited for trigger collisions and contradictory instructions against the Precedence Hierarchy.
3. Minimal Viable Skill Set (MVSS) selected; redundant secondary skills marked as SUPPRESSED.
4. Combined skill instruction token footprint verified within budget ($\le 6,000$ tokens).
5. No two parallel tasks have overlapping target write file paths.
6. Shared types and database schemas are fully committed before fan-out begins.
7. Output ROUTING_PLAN.md provides unambiguous subagent assignments, skill stacks, isolation boundaries, and verification receipts for every completion claim.
8. Worktree lease probed (and held, if mutating) before every branch switch, stash operation, or shared-surface staging; foreign WIP untouched.