Design-first collaboration using a five-level progressive framework (Capabilities → Components → Interactions → Contracts → Summary). Adapts to OOP or FP paradigms based on project language. Produces design output with mermaid diagrams.
Use when designing features before implementation, planning architecture, aligning on design decisions, or when the user mentions "design first", "design session", or wants to think through a feature before coding.
Design-first collaboration using a five-level progressive framework (Capabilities → Components → Interactions → Contracts → Summary). Adapts to OOP or FP paradigms based on project language. Produces design output with mermaid diagrams.
Use when designing features before implementation, planning architecture, aligning on design decisions, or when the user mentions "design first", "design session", or wants to think through a feature before coding.
Collaborating on Design
Five-level progressive design framework based on Martin Fowler's design-first
collaboration. No code until the design is agreed. Each level is a checkpoint
requiring explicit user approval before advancing.
Dependencies
thinking-patterns skill — used for structured reasoning at each level.
If unavailable, perform equivalent structured reasoning without the specific pattern invocations.
Variables
TASK: $ARGUMENTS — the story, requirements, or feature description
If TASK is empty, STOP immediately and ask the user what they want to design.
Paradigm Detection
Auto-detect the project's paradigm before starting:
Use /thinking atomic-thought to decompose requirements independently
OOP guidance: Frame capabilities as behaviors the system exposes.
See oop-design-vocabulary.md for vocabulary.
FP guidance: Frame capabilities as data transformations the system performs.
See fp-design-vocabulary.md for vocabulary.
Diagrams: Generally not needed at this level. Use a simple bulleted list.
Checkpoint: Present the capabilities summary. Wait for explicit approval
before advancing. If the user pushes back, revise at this level.
Level 2: Components
What to produce: The building blocks, their responsibilities, and
relationships.
Identify major abstractions, services, modules
Assign a single clear responsibility to each component
IMPORTANT: Challenge unnecessary abstractions. Only introduce components that
earn their existence. Flag anything that wraps an existing library without
adding value.
Before proposing a custom solution for a capability, check whether an
already-imported library provides it natively. Prefer library-native APIs
over custom reimplementations — they're maintained, documented, and
integrate with the library's other features.
Use /thinking tree-of-thoughts to evaluate component alternatives
OOP guidance: Components are classes, services, repositories, factories,
controllers. Apply SRP. Define collaborator relationships.
See oop-design-vocabulary.md.
FP guidance: Components are modules, behaviours, GenServers, supervisors,
data pipelines. Define transformation responsibilities and data ownership.
See fp-design-vocabulary.md.
Diagrams: Use mermaid class diagrams (OOP) or module/component diagrams (FP).
See mermaid-patterns.md for syntax.
Checkpoint: Present the component list with one-line responsibilities and
a diagram. Wait for explicit approval.
Level 3: Interactions
What to produce: How components communicate, data flow, and operation
sequences for key scenarios.
Map data flow between components
Define API calls, events, message passing
Walk through key scenarios step by step
Identify failure modes and recovery paths
Use /thinking chain-of-thought to trace through scenarios
OOP guidance: Method calls, observer/pub-sub patterns, dependency injection,
event dispatch. Show object collaboration.
See oop-design-vocabulary.md.
FP guidance: Function composition, pipe chains, message passing, event
streams, supervision strategies. Show data transformation flow.
See fp-design-vocabulary.md.
Diagrams: Use mermaid sequence diagrams for workflows, flowcharts for
decision logic, data flow diagrams for pipelines.
See mermaid-patterns.md.
Checkpoint: Present interaction diagrams and scenario walkthroughs. Wait
for explicit approval.
Level 4: Contracts
What to produce: Function signatures, types, schemas, and interfaces at
every component boundary.
Define input/output types for each boundary
Specify error cases and edge conditions
Establish validation rules and invariants
Present contracts in the project's language conventions
Use /thinking skeleton-of-thought to outline contract structure
OOP guidance: Interfaces, abstract classes, protocols, method signatures.
Define what each collaborator expects and provides.
See oop-design-vocabulary.md.
FP guidance: Typespecs, behaviours, protocols, data schemas, function
signatures. Define input/output shapes for each transformation.
See fp-design-vocabulary.md.
Diagrams: Use mermaid class diagrams showing interfaces and type
relationships. See mermaid-patterns.md.
Checkpoint: Present contracts in the project's language. Wait for explicit
approval.
Level 5: Summary
What to produce: The design is complete. No code is written in this session.
Summarize all approved levels into a coherent design document
Flag risks or open questions discovered during design
Guidelines
DO:
Produce visible output at each level before pausing
State which paradigm was detected and which level you're starting at
Challenge unnecessary abstractions at Level 2
Use mermaid diagrams where they aid understanding
Keep each level focused on its concern only
Match depth to complexity — not every task needs all five levels
DON'T:
Write implementation code — type signatures and contracts at Level 4 are expected
Leak implementation details into Capabilities
Discuss data flow in Components (that's Interactions)
Skip the approval checkpoint at any level
Introduce components that don't earn their existence
Force the design toward implementation concerns
When Stuck:
If stuck on Capabilities: Ask the user what behaviors matter most
If stuck on Components: Present what you have, ask what's missing
If stuck on Interactions: Walk through a concrete scenario together
If stuck on Contracts: Start with the happiest path, then add edge cases
Example
User: "Design a webhook delivery system for our Elixir app"
Complexity: Multi-component feature → Start at Level 1
Level 1: Capabilities
In scope:
- Accept webhook registration (URL, events, secret)
- Queue outbound deliveries when events fire
- Retry failed deliveries with exponential backoff
- Provide delivery status and history
Out of scope:
- Webhook signature verification on the receiving end
- Real-time delivery streaming (polling/API only)
Constraints:
- Must handle 10k+ events/minute
- Delivery attempts timeout after 30 seconds
→ Wait for approval
Level 2: Components
- Webhooks context module — CRUD for webhook registrations
- Dispatcher — receives events, fans out to matching webhooks
- DeliveryWorker — performs HTTP delivery with retry logic (Oban job)
- DeliveryLog — records attempt results for status/history queries
→ Includes component diagram. Wait for approval.
Level 3: Interactions
Event fired → Dispatcher matches registered webhooks
→ Enqueues DeliveryWorker job per webhook
→ DeliveryWorker POSTs payload, records result in DeliveryLog
→ On failure: Oban retries with backoff schedule
