wiring

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

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?

Verify Entry Points

```bash

# 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

```python

# Entry point (hook)

.claude/hooks/pre-tool-use.sh

↓

# Shell wrapper calls TypeScript

npx tsx pre-tool-use.ts

↓

# TypeScript calls Python script

spawn('scripts/orchestrate.py')

↓

# Script imports module

from orchestration_layer import dispatch

↓

# Module executes

dispatch(agent_type, task)

```

Test End-to-End

```bash

# Don't just unit test the module

pytest tests/unit/orchestration_layer_test.py # NOT ENOUGH

# Test the full invocation path

echo '{"tool": "Task"}' | .claude/hooks/pre-tool-use.sh # VERIFY THIS WORKS

```

Document Wiring

```markdown

• 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

```

Build Without Wiring

```python

# 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

```python

# 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

```python

# BAD: Assume because you wrote the code, it's imported

from orchestration_layer import dispatch # Does this path exist?

# GOOD: Verify imports at integration test time

uv run python -c "from orchestration_layer import dispatch; print('OK')"

```

Skip Integration Tests

```bash

# BAD: Only unit test

pytest tests/unit/ # All pass, but nothing works end-to-end

# GOOD: Integration test the wiring

pytest tests/integration/ # Verify full call path

```

Hook Not Registered

```json

// .claude/settings.json - hook definition exists but not in hooks section

{

"hooks": {

"PreToolUse": [] // Empty! Your hook never fires

}

}

```

Fix: Add hook registration:

```json

{

"hooks": {

"PreToolUse": [{

"matcher": ["Task"],

"hooks": [{

"type": "command",

"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/orchestration.sh"

}]

}]

}

}

```

Script Not Executable

```bash

# Script exists but can't execute

-rw-r--r-- scripts/orchestrate.py

# Fix: Make executable

chmod +x scripts/orchestrate.py

```

Module Not Importable

```python

# Script tries to import but path is wrong

from orchestration_layer import dispatch

# ModuleNotFoundError

# Fix: Add to Python path or use proper package structure

sys.path.insert(0, str(Path(__file__).parent.parent))

```

Router Has No Dispatch Path

```python

# BAD: Router has beautiful mapping

AGENT_MAP = {

"implement": ImplementAgent,

"research": ResearchAgent,

# ... 18 agent types

}

# But no dispatch function uses the map

def route(task):

return "general-purpose" # Hardcoded! Map is dead code

# GOOD: Dispatch actually uses the map

def route(task):

agent_type = classify(task)

return AGENT_MAP[agent_type]

```

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)

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

Grep for Orphans

```bash

# Find Python modules

find . -name "*.py" -type f

# Check if each is imported

for file in $(find . -name "*.py"); do

module=$(basename $file .py)

grep -r "from.$module import\|import.$module" . || echo "ORPHAN: $file"

done

```

Check Hook Registration

```bash

# List all hooks in .claude/hooks/

ls .claude/hooks/*.sh

# Check each is registered

for 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

```bash

# Find all Python scripts

find scripts/ -name "*.py"

# Test each can be imported

for 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

```

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