How architect produces design_input contributions — pattern selection, SRP verification, dependency direction, phase-appropriate depth
Without architecture steps before executing, engineers make too many mistakes. The architect's design_input is a REQUIREMENT — the engineer MUST follow it. Not a suggestion. Not a recommendation. The blueprint.
The brain creates a design_input contribution task when a story/epic enters
REASONING stage. You produce the design and deliver it via fleet_contribute
so the engineer sees it in context during WORK stage.
Call arch_design_contribution(task_id) — your group call that gathers:
Before choosing a pattern, understand what KIND of problem this is:
| If the problem is about... | Consider... |
|---|---|
| Complex object construction | Builder pattern |
| Decoupling communication between components | Mediator pattern |
| Reacting to events/changes | Observer pattern |
| Varying algorithm by context | Strategy pattern |
| Simplifying a complex subsystem | Facade pattern |
| Adapting incompatible interfaces | Adapter pattern |
| Separating concerns (data access) | Repository pattern |
| Separating domain from infrastructure | Onion / Hexagonal architecture |
| Configuration-driven behavior | Registry / Factory pattern |
Don't force a pattern. Simple problems get simple solutions. A utility function is fine when a utility function is all you need.
The PO decides phases. The architect adapts depth to phase.
| Phase | Design Depth |
|---|---|
| poc | Simple working structure. Can be single-file. Focus on proving the concept works. |
| mvp | Proper separation of concerns. Domain vs infrastructure. Clean interfaces between modules. |
| staging | Full onion layering. Testable boundaries everywhere. Integration patterns defined. Error handling strategy. |
| production | Production architecture. Scalable. Maintainable. Documented. Performance considered. |
A POC does NOT need an onion architecture. A production feature does NOT get away with everything in one file.
Your design_input must contain:
Which pattern and WHY. Not just "use repository pattern" — explain what problem it solves in THIS context.
Where things go. Module names. Directory structure. The engineer should know exactly which files to create/modify.
fleet/core/auth.py — domain logic (JWT validation, token generation)
fleet/infra/auth_client.py — infrastructure (HTTP calls to auth service)
fleet/mcp/tools.py — add fleet_auth_check tool
fleet/tests/core/test_auth.py — unit tests
Does each proposed module have ONE responsibility? If a module does two things, split it. Call it out explicitly.
What's core (domain logic, no external deps) vs infrastructure (HTTP, database, filesystem). Dependencies point INWARD — infra depends on core, never reverse.
All dependencies point inward. Draw the arrow:
tools.py → core/auth.py ← infra/auth_client.py
Core never imports from infra. Tools import from core.
How this connects to existing systems. What interfaces must be respected. What would break if done wrong.
Anti-patterns for this specific work. Common mistakes engineers make with this kind of task. Things that look right but create coupling.
fleet_contribute(
task_id=TARGET_TASK_ID,
contribution_type="design_input",
content=YOUR_DESIGN
)
The engineer receives your design_input in their context. During review, fleet-ops can check: did the implementation follow the architect's design? If the engineer deviated, that's a review finding.