Skills

aid-design

Frontmatter

name — aid-design
description — Produce a design artifact you intend to keep — a UX or interaction flow, a component or interface design, with accessibility notes — meant to inform the real build. Use this skill when the subject has no dedicated design row of its own; when a dedicated /aid-design-<artifact> row exists, use that row instead. It is grounded in the Knowledge Base (.aid/knowledge/) and the project source, produced by aid-architect and independently verified by aid-reviewer, because a kept design drives a build and its correctness matters. It resolves nothing: it presents the design, you decide, and building it is a separate /aid-create step. For a throwaway model that only validates a direction, use /aid-prototype instead.
allowed-tools — Read, Glob, Grep, Bash, Write, Edit, Agent
argument-hint — <subject> — what to design (a flow, a component/interface, a UI; use a dedicated /aid-design-<artifact> row when one exists)

Definition: canonical/skills/aid-design/SKILL.md

Flow

flowchart TB
  classDef aidNode color:#fff
  classDef aidEntry fill:#166534,stroke:#14532d,color:#fff
  classDef aidExit fill:#991b1b,stroke:#7f1d1d,color:#fff
  classDef aidDecision fill:#92400e,stroke:#78350f,color:#fff
  classDef aidLoopBack fill:#1e3a8a,stroke:#1e3a8a,color:#fff
  classDef aidStep fill:#1a2035,stroke:#d4a853,color:#f1f5f9
  n1(["INTAKE"])
  n2["DESIGN"]
  n3["VERIFY<br/>full -- a kept design drives a build"]
  n4{"PRESENT"}
  n5["HANDOFF<br/>optional; printed suggestions only"]
  n6(["DONE"])
  n1 --> n2
  n2 --> n3
  n3 -.-> n2
  n3 --> n4
  n4 -->|"optional"| n5
  n4 --> n6
  n5 --> n6
  class n1 aidEntry
  class n2 aidStep
  class n3 aidLoopBack
  class n4 aidDecision
  class n5 aidStep
  class n6 aidExit
  class n1 aidNode
  class n2 aidNode
  class n3 aidNode
  class n4 aidNode
  class n5 aidNode
  class n6 aidNode

Source fragments

Every node in the chart above, in chart order, with the exact canonical/ text it was derived from.

1 · INTAKE · entry

## State: INTAKE

1. **Require a subject.** Empty argument -> ask one bootstrapping question ("What do you
   want designed, and what will it need to support?") and wait.
2. **Pick the path:** **Fast** -- a clear thing to design ("design the checkout flow",
   "design this service's interface") -> design now. **Guided** -- open-ended ("design our
   onboarding") -> scope the subject, constraints, and success criteria first.
3. **Classify complexity (model + effort):** simple (one component/flow) -> `aid-architect`
   at **sonnet / medium**; complex (a system architecture, a multi-screen flow) -> **opus /
   high**. Verifier tier >= producer tier.
4. **Consult the Work Initiation Gate, then allocate the work folder + STATE.** First run
   the gate (`canonical/aid/templates/work-initiation-gate.md`):
   `bash canonical/aid/scripts/works/enumerate-works.sh` (main tree + every git worktree).
   Empty -> allocate, no prompt. Works exist -> ask new-vs-continuation; on **continuation**
   route to the chosen work's resume door and STOP (allocate nothing); on **new work**:
   create and enter the worktree per the gate's `§ 3a` step 2
   (`worktree-lifecycle.sh create <work-id> <name>`, STOP on a non-zero exit or empty path,
   else enter the resolved path), **then** allocate (`pipeline.path: lite`, `initiator:
   aid-design`, `lifecycle: Running`, `active_skill: aid-design`; `phase` not driven).

Source: canonical/skills/aid-design/SKILL.md#L35-L53 · full step: canonical/skills/aid-design/SKILL.md#L35-L55

2 · DESIGN · step

## State: DESIGN

Dispatch **`aid-architect`** (clean context, tiered) to produce the design, **grounded in
the KB** (existing patterns, conventions, `architecture.md`) + the request: variables/flow,
control/interaction, component or interface shape, and **accessibility notes**
(`task-type-rules.md ## DESIGN`). It writes `DESIGN.md` into the work folder (the design's
kept record).

Source: canonical/skills/aid-design/SKILL.md#L59-L65 · full step: canonical/skills/aid-design/SKILL.md#L59-L67

3 · VERIFY — full — a kept design drives a build · loop-back

## State: VERIFY  (full -- a kept design drives a build)

1. **Mechanical grounding check** (no dispatch): design decisions cite the KB/source they
   build on; accessibility is addressed.
2. **Adversarial verification** -- clean-context **`aid-reviewer`** checks `DESIGN.md`:
   grounded, complete, internally consistent, consistent with KB conventions + a11y, and
   buildable. Writes a review-quality ledger to `.aid/.temp/review-pending/<work>-verify.md`.
3. **Grade:** `bash canonical/aid/scripts/grade.sh --explain <ledger>`. Not clean -> loop
   to DESIGN. Circuit-breaker: 3 cycles -> IMPEDIMENT + `lifecycle: Blocked`.

Source: canonical/skills/aid-design/SKILL.md#L71-L79 · full step: canonical/skills/aid-design/SKILL.md#L71-L81

4 · PRESENT — hard stop — the user decides · decision

## State: PRESENT  (hard stop -- the user decides)

Set `lifecycle: Paused-Awaiting-Input`. Present `DESIGN.md` clearly. Assert no resolution --
the user decides whether/when to build it.

Source: canonical/skills/aid-design/SKILL.md#L85-L88 · full step: canonical/skills/aid-design/SKILL.md#L85-L90

5 · HANDOFF — optional; printed suggestions only · step

## State: HANDOFF  (optional; printed suggestions only)

Printed suggestions: build it (`/aid-create*` / `/aid-update*`, referencing the design), or
capture it as a formal doc (`/aid-create-document`). Never auto-invoked; never a resolution.

Source: canonical/skills/aid-design/SKILL.md#L94-L97 · full step: canonical/skills/aid-design/SKILL.md#L94-L99

6 · DONE · exit · UNSPECIFIED

## State: DONE

Set `lifecycle: Completed`, `updated` now, append a `## Lifecycle History` row. Keep
`DESIGN.md` in the work folder as the kept design record.

Source: canonical/skills/aid-design/SKILL.md#L103-L106 · full step: canonical/skills/aid-design/SKILL.md#L103-L106

Report an issue with this page →