fleet-design-pattern-selection
How the architect selects design patterns — when each fits, when it doesn't, and how the choice flows into design_input contributions that engineers must follow.
SKILL.md.claude/skills/fleet-design-pattern-selection/SKILL.md
GitHubDesign Pattern Selection — Architect's Decision Framework
You don't just "use a pattern." You SELECT a pattern based on the problem's constraints, justify the selection, and communicate it as a design_input contribution that the engineer treats as a requirement.
The Selection Process
Step 1: Identify the Problem Category
Before choosing a pattern, categorize what you're solving:
| Category | Characteristic | Candidate Patterns |
|---|---|---|
| External dependency | Code talks to API, database, or service | Adapter, Repository, Gateway |
| Complex creation | Object construction has many steps or variants | Builder, Factory, Abstract Factory |
| Event-driven behavior | Actions trigger reactions across components | Observer, Mediator, Event Bus |
| Algorithm variation | Same interface, different implementations | Strategy, Template Method |
| Access control | Need to control or enhance access to something | Proxy, Decorator |
| Structural simplification | Complex subsystem needs a simple interface | Facade, Adapter |
| State management | Object behavior depends on internal state | State, FSM |
Step 2: Evaluate Against Fleet Constraints
The fleet has specific architectural principles that constrain pattern selection:
Onion architecture: Inner layers (core/) MUST NOT depend on outer layers (infra/). This means:
- Repository pattern for data access: core/ defines interface, infra/ implements
- Adapter pattern for external services: core/ defines port, infra/ provides adapter
- NO direct imports from infra/ in core/ — even for "convenience"
Single Responsibility: Each module/class does ONE thing. A "service" that reads config, calls an API, transforms data, AND writes results is 4 responsibilities. Split it.
Dependency direction: Always inward. fleet/mcp/tools.py calls fleet/core/contributions.py, never the reverse. If core needs something from mcp, define an interface in core and inject from mcp.
Step 3: Select and Justify
Your design_input contribution must include:
- Pattern name — what you chose
- Why this pattern — what problem characteristic matches
- Why NOT alternatives — what you considered and rejected
- Target files — where the pattern applies (specific paths)
- Constraints — what the engineer MUST follow (dependency direction, interface boundaries)
Common Patterns in the Fleet Codebase
| Pattern | Where It's Used | Why |
|---|---|---|
| Repository | mc_client.py, plane_client.py | Isolate data access from business logic |
| Adapter | gh_client.py, ntfy_client.py | External services behind stable interfaces |
| Builder | event_chain.py (chain builders) | Complex event chains built step by step |
| Strategy | backend_router.py | Multiple routing strategies, same interface |
| Observer | _emit_event() pattern | Tools emit, multiple systems react |
| Facade | context_assembly.py | Complex multi-source data behind one call |
| Template Method | role_providers.py | Base provider pattern, role-specific overrides |
| Mediator | ChainRunner | Coordinates operations across 6 surfaces |
Anti-Patterns to Flag
When you see these in a task's codebase area, flag them in your design_input:
- God class — one module doing everything. Split by responsibility.
- Circular dependency — A imports B, B imports A. Introduce interface.
- Leaky abstraction — core/ code that knows about HTTP status codes or SQL syntax.
- Premature abstraction — Abstract base class with exactly one implementation. Wait for the second case.
- Config in code — Magic numbers, hardcoded URLs. These belong in config/ YAML files (fleet's IaC principle).
Phase-Appropriate Design Depth
| Phase | Design Depth | What to Include |
|---|---|---|
| poc | Minimal. Pick the obvious pattern. | "Use Repository for data access. Target: X.py" |
| mvp | Moderate. Consider alternatives. | Pattern + why + 1 alternative rejected + constraints |
| staging | Thorough. Full evaluation. | Pattern + 3 alternatives + performance implications + migration path |
| production | Complete. Production-grade. | Everything above + scalability analysis + failure modes + monitoring hooks |
Your arch_design_contribution group call reads the delivery phase and adjusts the template accordingly. Follow its guidance on depth.