Design
Turn approved specifications into an implementation-ready technical design. Requirements are already
settled; focus on architecture, component boundaries, interfaces, data flow, failure handling,
migration, testing, and meaningful trade-offs.
Do not implement, scaffold, or invoke an implementation skill before the user approves the design.
Process
- Read every specification, including deferred-to-design markers, and inspect the relevant code,
interfaces, tests, and repository conventions.
- Use
codagent:ask-questions for consequential architectural choices that repository context cannot
safely resolve. Evaluate options first, recommend a path, and decide low-risk implementation details
yourself.
- Compare plausible approaches when a real trade-off exists. Do not manufacture alternatives for an
obvious, patterned solution.
- Present a design scaled to the change's complexity. Cover the important components, interactions,
decisions, risks, verification strategy, and any resulting specification implications; use diagrams
when they clarify the design.
- After approval, write
design.md and apply any specification changes revealed by the design,
including completing deferred scenarios, only when those implications were presented with the
approved design. Return to the user for a newly discovered behavioral or scope decision. Keep
normative behavioral changes in specs and technical rationale in the design.
If design work exposes a product or scope decision rather than a technical implication, discuss it
with the user instead of silently inventing behavior. The written artifacts must be self-contained for
an implementing agent with no conversation history.
Do not invoke another lifecycle skill after writing.
Artifact template
Omit sections that do not apply.
## Context
<!-- Relevant current state and constraints. -->
## Goals / Non-Goals
**Goals:**
<!-- Outcomes this design enables. -->
**Non-Goals:**
<!-- Explicit exclusions. -->
## Approach
<!-- Components, interfaces, interactions, data flow, and failure behavior. -->
## Decisions
<!-- Consequential choices and rationale. -->
## Risks / Trade-offs
<!-- Material risks, mitigations, and alternatives considered. -->
## Migration Plan
<!-- Rollout and rollback when applicable. -->
## Open Questions
<!-- Only unresolved decisions that remain. -->
1---2name: design3description: Creates design artifacts through collaborative brainstorming of approaches, architecture, and trade-offs. Use when the user says "design this", "create a design", "brainstorm approaches", or "write a design doc".4---56# Design78Turn approved specifications into an implementation-ready technical design. Requirements are already9settled; focus on architecture, component boundaries, interfaces, data flow, failure handling,10migration, testing, and meaningful trade-offs.1112Do not implement, scaffold, or invoke an implementation skill before the user approves the design.1314## Process15161. Read every specification, including deferred-to-design markers, and inspect the relevant code,17 interfaces, tests, and repository conventions.182. Use `codagent:ask-questions` for consequential architectural choices that repository context cannot19 safely resolve. Evaluate options first, recommend a path, and decide low-risk implementation details20 yourself.213. Compare plausible approaches when a real trade-off exists. Do not manufacture alternatives for an22 obvious, patterned solution.234. Present a design scaled to the change's complexity. Cover the important components, interactions,24 decisions, risks, verification strategy, and any resulting specification implications; use diagrams25 when they clarify the design.265. After approval, write `design.md` and apply any specification changes revealed by the design,27 including completing deferred scenarios, only when those implications were presented with the28 approved design. Return to the user for a newly discovered behavioral or scope decision. Keep29 normative behavioral changes in specs and technical rationale in the design.3031If design work exposes a product or scope decision rather than a technical implication, discuss it32with the user instead of silently inventing behavior. The written artifacts must be self-contained for33an implementing agent with no conversation history.3435Do not invoke another lifecycle skill after writing.3637## Artifact template3839Omit sections that do not apply.4041```markdown42## Context4344<!-- Relevant current state and constraints. -->4546## Goals / Non-Goals4748**Goals:**49<!-- Outcomes this design enables. -->5051**Non-Goals:**52<!-- Explicit exclusions. -->5354## Approach5556<!-- Components, interfaces, interactions, data flow, and failure behavior. -->5758## Decisions5960<!-- Consequential choices and rationale. -->6162## Risks / Trade-offs6364<!-- Material risks, mitigations, and alternatives considered. -->6566## Migration Plan6768<!-- Rollout and rollback when applicable. -->6970## Open Questions7172<!-- Only unresolved decisions that remain. -->73```
codagent-ai