This skill should be used when the orchestrator needs to "design architecture", "create contracts", "define tech stack", or "validate design". Handles one aspect of design per invocation at increasing resolution.
Handle one focused aspect of design per invocation. Read what exists,
do focused work, write results to .clawdance/design/. The orchestrator calls
you multiple times at increasing resolution.
Based on what exists and what the orchestrator asked for:
| State | Focus |
|---|---|
| Orchestrator says "analyze" + source code exists | Analyze — reverse-engineer existing codebase |
No .clawdance/design/ at all + user idea provided | Architecture — full initial design |
.clawdance/design/DESIGN.md exists, no STACK.md | Stack — tech stack and testing |
.clawdance/design/DESIGN.md + STACK.md exist, contracts incomplete | Contracts — specific interface |
| All artifacts exist | Validate — coherence check |
| Orchestrator specified a focus | That specific focus |
When the orchestrator invokes this skill in analyze mode, the project already has source code. The job: understand what exists and produce design artifacts that describe the CURRENT system, not a new design.
Don't read every file. Read structure + key files (entry points, config, main modules). For a specific feature request, focus on the area that feature will touch.
Write .clawdance/design/DESIGN.md describing what EXISTS:
Write .clawdance/design/STACK.md from actual tech stack:
Write .clawdance/design/contracts/ for existing inter-component
interfaces. These may be implicit — extract them from actual code
(API routes, shared types, database schemas).
Read codebase patterns and seed .clawdance/constraints.yaml with
discovered invariants. Examples:
These get discovered_by: init and confidence: inferred. The build
skill upgrades to verified when it confirms them during implementation.
Present the findings: "Here's the architecture I see. [summary]. [N] constraints discovered." The human corrects or approves.
When creating the initial design from a user's idea:
If the user's idea is vague, ask clarifying questions:
Keep it conversational. 2-4 rounds of clarification is typical. Don't ask all questions at once.
Produce .clawdance/design/DESIGN.md:
Present as a recommendation: "Here's the architecture I'd use. [reasoning]" The user approves or redirects.
Produce .clawdance/design/STACK.md:
Read .clawdance/design/DESIGN.md first — the stack must serve the architecture.
For a specific inter-component interface, produce a contract file in
.clawdance/design/contracts/:
Read .clawdance/design/DESIGN.md to understand the interface. The contract must be
specific enough that two agents implementing each side independently would
produce compatible code.
Format is flexible (YAML, JSON Schema, OpenAPI, markdown). Name the file after the interface it describes.
Read ALL design artifacts: DESIGN.md, STACK.md, all contracts. Check:
If gaps found: report them specifically. The orchestrator will invoke another design pass to fix them.
If coherent: report "Design is complete and coherent. Ready for decomposition."