fleet-domain-boundary-enforcement
How the architect enforces domain boundaries — core doesn't depend on infra, dependency direction is inward. The structural principle that keeps the codebase from becoming a tangled web.
SKILL.md.claude/skills/fleet-domain-boundary-enforcement/SKILL.md
GitHubDomain Boundary Enforcement — Architect's Structural Principle
The fleet follows onion architecture. Inner layers define interfaces. Outer layers implement them. Dependencies point INWARD. When this principle erodes, the codebase becomes untestable, unmaintainable, and fragile.
The Fleet's Layer Structure
OUTERMOST: fleet/cli/ — CLI commands, entry points
fleet/mcp/ — MCP tools, server, roles
MIDDLE: fleet/infra/ — External service clients (MC, IRC, GitHub, Plane, ntfy)
fleet/templates/ — Output formatting
INNERMOST: fleet/core/ — Domain logic, business rules, models
The Rule
Inner layers MUST NOT import from outer layers.
| Import Direction | Example | Allowed? |
|---|---|---|
| cli → core | from fleet.core.model_selection import ... |
YES — outer uses inner |
| mcp → core | from fleet.core.contributions import ... |
YES — outer uses inner |
| mcp → infra | from fleet.infra.mc_client import ... |
YES — outer uses outer |
| core → infra | from fleet.infra.plane_client import ... |
NO — inner depends on outer |
| core → mcp | from fleet.mcp.tools import ... |
NO — inner depends on outer |
| core → cli | from fleet.cli.dispatch import ... |
NO — inner depends on outer |
How to Check
During Design (Contribution)
When producing design_input, verify your proposed solution respects boundaries:
- Does the new module belong in
core/orinfra/? - If
core/: does it need external services? → Define an interface in core, implement in infra - If
infra/: does it call domain logic? → Import from core, don't duplicate
During Review (Architecture Health)
Use the dependency-mapper sub-agent:
Agent: dependency-mapper
Prompt: "Scan fleet/core/ for imports from fleet/infra/, fleet/mcp/, or fleet/cli/.
Report any violations of inward dependency direction."
Manual Check
# Find core modules importing from infra
grep -rn "from fleet\.infra\|from fleet\.mcp\|from fleet\.cli" fleet/core/
# Should return NOTHING. Any match is a violation.
Common Violations and Fixes
Violation: Core imports infra client
# BAD: fleet/core/contributions.py
from fleet.infra.mc_client import MCClient # core depends on infra!
Fix: Core defines what it needs as a parameter. Caller provides the implementation.
# GOOD: fleet/core/contributions.py
async def check_contribution_completeness(task_id, mc, board_id):
# mc is passed in, not imported — core doesn't know about MCClient
comments = await mc.list_comments(board_id, task_id)
Violation: Core reads config files directly
# BAD: fleet/core/phases.py
import yaml
with open("config/phases.yaml") as f: # core knows about file paths!
Fix: Config loading belongs in infra or a config module. Core receives data.
# GOOD: fleet/core/phases.py
def check_phase_standards(task, phase_config):
# phase_config is loaded elsewhere and passed in
Violation: Core emits to specific surfaces
# BAD: fleet/core/contributions.py
from fleet.infra.irc_client import notify_irc # core talks to IRC!
Fix: Core emits events. The chain runner (outer layer) routes to surfaces.
# GOOD: fleet/core/event_chain.py
def build_contribution_chain(...):
# Defines WHAT should happen. ChainRunner (mcp layer) executes HOW.
Why This Matters
- Testability: Core modules can be tested without external services. No mocking MC, IRC, Plane in core tests.
- Flexibility: Swap MC backend without touching core logic. Swap IRC for Slack without touching contributions.
- Comprehensibility: Reading
fleet/core/contributions.pytells you the business rules without wading through HTTP calls. - The fleet's 20 systems: Each system crosses multiple layers. Enforcing boundaries keeps the crossings clean and traceable.
Integration with Architecture Health CRON
Your weekly architecture-health-check CRON should include boundary verification as a standard check. Report violations in the architecture health report. Create tasks to fix structural violations before they spread.