| name | core-design |
| description | Activate when the turn produces a design — system architecture, API contract, data model, component decomposition, or trade-off analysis. Covers the thinking, not the document: when the deliverable is written up (ADR, RFC, design doc), activate core-writing too. Provides the Constraints → Explore → Decide → Specify → Plan workflow. |
| user-invocable | false |
Skill: core-design
Follow Constraints → Explore → Decide → Specify → Plan for every design task.
Companion Templates
When the current step matches a trigger below, Read the named companion from this skill's directory (path provided in the activation header). Companions are not pre-loaded — pull them on demand.
| Trigger | Companion |
|---|
| Recording a design decision worth preserving (during or after the Decide step) | templates/decision-record.md |
Workflow
1. Constraints & Requirements
- Extract explicit requirements and implicit constraints from the task.
- Identify what's in scope and what's out.
- Note non-negotiables: existing interfaces, backward compatibility, security, performance targets.
- If requirements are ambiguous, ask before designing further.
2. Architecture Exploration
- Generate 2-3 distinct approaches. Avoid converging on the first idea.
- Compare each approach against: correctness, consistency with existing patterns, complexity, performance, maintainability, testability.
- Use
Grep, Glob, and Read to study existing patterns before proposing new ones.
- For large or unfamiliar domains, activate
core-research first to map the landscape.
3. Design Decision
- Choose the best approach with explicit rationale.
- Document what was chosen AND what was rejected and why.
- The rationale should be specific enough that someone else could reconstruct the same decision from the constraints.
4. Specification
- Define precise contracts: interfaces, data flow, error modes, edge cases.
- Be concrete enough that implementation is straightforward from the spec alone.
- Use
TodoWrite to capture loose ends or open questions.
5. Implementation Plan
- Break the design into discrete implementation steps.
- Each step: Action → Target → Verification.
- Order steps by dependency (what must exist before what).
Safety Rules
- No premature implementation: During steps 1-4, do not write or modify any code. Design decisions come before implementation.
- Approval gate: When running interactively, obtain explicit user approval of the design and plan before starting implementation — this overrides the Working Loop's Frame step, which would otherwise work autonomously on directives. When running non-interactively (no user to approve), do not block on approval: present the design and plan inline and then proceed.
Output Standards
- Structured: Clear sections matching the workflow above.
- Precise: Specific interfaces, types, and contracts — not vague descriptions.
- Context-aware: The design must fit the existing codebase, not introduce a new paradigm unless justified.
- Transparent: Surface trade-offs made and alternatives considered.
