Wiring

Wiring Verification

When building infrastructure components, ensure they're actually invoked in the execution path.

Pattern

Every module needs a clear entry point. Dead code is worse than no code - it creates maintenance burden and false confidence.

The Four-Step Wiring Check

Before marking infrastructure "done", verify:

1. Entry Point Exists: How does user action trigger this code?
2. Call Graph Traced: Can you follow the path from entry to execution?
3. Integration Tested: Does an end-to-end test exercise this path?
4. No Dead Code: Is every built component actually reachable?

DO

Verify Entry Points

# Hook registered?grep -r "orchestration" .claude/settings.json
# Skill activated?grep -r "skill-name" .claude/skill-rules.json
# Script executable?ls -la scripts/orchestrate.py
# Module imported?grep -r "from orchestration_layer import" .

Trace Call Graphs

# Entry point (hook).claude/hooks/pre-tool-use.sh  ↓# Shell wrapper calls TypeScriptnpx tsx pre-tool-use.ts  ↓# TypeScript calls Python scriptspawn('scripts/orchestrate.py')  ↓# Script imports modulefrom orchestration_layer import dispatch  ↓# Module executesdispatch(agent_type, task)

Test End-to-End

# Don't just unit test the modulepytest tests/unit/orchestration_layer_test.py  # NOT ENOUGH
# Test the full invocation pathecho '{"tool": "Task"}' | .claude/hooks/pre-tool-use.sh  # VERIFY THIS WORKS

Document Wiring

## Wiring
- **Entry Point**: PreToolUse hook on Task tool- **Registration**: `.claude/settings.json` line 45- **Call Path**: hook → pre-tool-use.ts → scripts/orchestrate.py → orchestration_layer.py- **Test**: `tests/integration/task_orchestration_test.py`

DON'T

Build Without Wiring

# BAD: Created orchestration_layer.py with 500 lines# But nothing imports it or calls it# Result: Dead code, wasted effort
# GOOD: Start with minimal wiring, then expand# 1. Create hook (10 lines)# 2. Test hook fires# 3. Add script (20 lines)# 4. Test script executes# 5. Add module logic (iterate)

Create Parallel Routing

# BAD: Agent router has dispatch logic# AND skill-rules.json has agent selection logic# AND hooks have agent filtering logic# Result: Three places to update, routing conflicts
# GOOD: Single source of truth for routing# skill-rules.json activates skill → skill calls router → router dispatches

Assume Imports Work

# BAD: Assume because you wrote the code, it's importedfrom orchestration_layer import dispatch  # Does this path exist?
# GOOD: Verify imports at integration test timeuv run python -c "from orchestration_layer import dispatch; print('OK')"

Skip Integration Tests

# BAD: Only unit testpytest tests/unit/  # All pass, but nothing works end-to-end
# GOOD: Integration test the wiringpytest tests/integration/  # Verify full call path

Common Wiring Gaps

Hook Not Registered

// .claude/settings.json - hook definition exists but not in hooks section{  "hooks": {    "PreToolUse": []  // Empty! Your hook never fires  }}

Fix: Add hook registration:

{  "hooks": {    "PreToolUse": [{      "matcher": ["Task"],      "hooks": [{        "type": "command",        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/orchestration.sh"      }]    }]  }}

Script Not Executable

# Script exists but can't execute-rw-r--r-- scripts/orchestrate.py
# Fix: Make executablechmod +x scripts/orchestrate.py

Module Not Importable

# Script tries to import but path is wrongfrom orchestration_layer import dispatch# ModuleNotFoundError
# Fix: Add to Python path or use proper package structuresys.path.insert(0, str(Path(__file__).parent.parent))

Router Has No Dispatch Path

# BAD: Router has beautiful mappingAGENT_MAP = {    "implement": ImplementAgent,    "research": ResearchAgent,    # ... 18 agent types}
# But no dispatch function uses the mapdef route(task):    return "general-purpose"  # Hardcoded! Map is dead code
# GOOD: Dispatch actually uses the mapdef route(task):    agent_type = classify(task)    return AGENT_MAP[agent_type]

Wiring Checklist

Before marking infrastructure "complete":

• Entry point identified and tested (hook/skill/CLI)
• Call graph documented (entry → module execution)
• Integration test exercises full path
• No orphaned modules (everything imported/called)
• Registration complete (settings.json/skill-rules.json)
• Permissions correct (scripts executable)
• Import paths verified (manual import test passes)

Real-World Examples

Example 1: DAG Orchestration (This Session)

What was built:

• opc/orchestration/orchestration_layer.py (500+ lines)
• opc/orchestration/dag/ (DAG builder, validator, executor)
• 18 agent type definitions
• Sophisticated routing logic

Wiring gap:

• No hook calls orchestration_layer.py
• No script imports the DAG modules
• Agent routing returns hardcoded "general-purpose"
• Result: 100% dead code

Fix:

1. Create PreToolUse hook for Task tool
2. Hook calls scripts/orchestrate.py
3. Script imports and calls orchestration_layer.dispatch()
4. Dispatch uses AGENT_MAP to route to actual agents
5. Integration test: Submit Task → verify correct agent type used

Example 2: Artifact Index (Previous Session)

What was built:

• SQLite database schema
• Indexing logic
• Query functions

Wiring gap:

• No hook triggered indexing
• Files created but never indexed

Fix:

1. PostToolUse hook on Write tool
2. Hook calls indexing script immediately
3. Integration test: Write file → verify indexed

Detection Strategy

Grep for Orphans

# Find Python modulesfind . -name "*.py" -type f
# Check if each is importedfor file in $(find . -name "*.py"); do  module=$(basename $file .py)  grep -r "from.*$module import\|import.*$module" . || echo "ORPHAN: $file"done

Check Hook Registration

# List all hooks in .claude/hooks/ls .claude/hooks/*.sh
# Check each is registeredfor hook in $(ls .claude/hooks/*.sh); do  basename_hook=$(basename $hook)  grep -q "$basename_hook" .claude/settings.json || echo "UNREGISTERED: $hook"done

Verify Script Execution

# Find all Python scriptsfind scripts/ -name "*.py"
# Test each can be importedfor script in $(find scripts/ -name "*.py"); do  uv run python -c "import sys; sys.path.insert(0, 'scripts'); import $(basename $script .py)" 2>/dev/null || echo "IMPORT FAIL: $script"done

Source

• This session: DAG orchestration wiring gap - 500+ lines of dead code discovered
• Previous sessions: Artifact Index, LMStudio integration - wiring added after initial build