design

Files (1)

• SKILL.md

SKILL.md (first lines)

# /design — Design (Tech Spec)

You are the **phase orchestrator** for AIDLC **Design** (Tech Spec). Ground truth is **`docs/AIDLC.md`** in the **consumer workspace**.

**Plan (Product Spec)** is **`/plan`** ([skills/plan/SKILL.md](../plan/SKILL.md)). This skill assumes **Product Spec is approved** (or the user explicitly approves proceeding in the current thread).

**Library skills** — [docs/SKILLS.md](../../docs/SKILLS.md); resolve from your install or `.claude/skills/<bundle>/`.

## Before you start

1. Resolve **feature slug** from `$ARGUMENTS` or from the same folder the team used for `/plan`.
2. **Read `feature/<slug>/product-spec.md`**. If it is missing or clearly not approved, **stop** and ask the human to run **`/plan`** or confirm approval — do not invent product scope.
3. Ensure `feature/<slug>/` exists. If `tech-spec.md` is missing, create it from **[`tech-spec-template.md`](../spec-management/templates/tech-spec-template.md)**.
4. Link the work to the same **parent work item** as `/plan` (per **`AGENTS.md` → Issue tracker (AIDLC)**). For GitHub-only automation, see [GITHUB-AIDLC-PROJECT.md](https://github.com/queen-of-code/AI-DLC/blob/main/docs/GITHUB-AIDLC-PROJECT.md). Portability: [ISSUE-TRACKER-PORTABILITY.md](https://github.com/queen-of-code/AI-DLC/blob/main/docs/ISSUE-TRACKER-PORTABILITY.md).

## Orchestration — Tech Spec (`tech-spec.md`)

1. Translate the **approved** Product Spec into one or more **Units**; one `tech-spec.md` in this feature folder unless work is split across sub-issues (link related specs in the doc).
2. Include: scope, architecture, API/UI contracts, data model, acceptance criteria for **Review**, **testing approach** (what Build+Test must cover), risks — per AIDLC Design in `docs/AIDLC.md`.
   - **Architecturally-relevant changes** — anything touching a **state/status field, an enum, an async handoff, a gated or terminal action, a multi-step pipeline, or a publish/compile step** (trivial copy/CSS/config is exempt) — **must** additionally carry, per **[docs/ARCHITECTURAL-SOUNDNESS.md](../../docs/ARCHITECTURAL-SOUNDNESS.md)**: a **state machine** (states + a single transition function every path routes through + why illegal states are unreachable *by construction*), **sequence diagram(s)** for each cross-component/async handoff, the **invariants + their single enforcement chokepoint**, and the **validity boundary** (where invalid states are made unreachable — prefer schema/type/compile/publish over run-time guards). Without these, the change is **not ready** for the Design gate; `/review`'s Architectural Soundness pass scores against them.
3. **Tech Spec review passes** (run in order; merge findings into the doc; open issues in an appendix if needed):

| Pass | Library skill |
|------|----------------|
| Architecture / boundaries | `architecture` ([skills/architecture/SKILL.md](../architecture/SKILL.md)) |
| Frontend | `frontend-web` ([skills/frontend-web/SKILL.md](../frontend-web/SKILL.md)) |
| Backend / API | `backend-saas` ([skills/backend-saas/SKILL.md](../backend-saas/SKILL.md)) |
| Testing strategy | `testing` ([skills/testing/SKILL.md](../testing/SKILL.md)) |
| CI / Docker / deploy | `architecture` + read `.github/workflows/`, `docker-compose`, Dockerfiles |

4. **Stop for human approval** of the Tech Spec before **`/build`**.

## Outputs

- `feature/<slug>/tech-spec.md` (and linked ADR drafts under `adr/` if your repo uses them per **spec-management**)

## Rules

- Do not reopen settled Product decisions in the Tech Spec without flagging a **change request** to Product.
- **Conversation first** for technical ambiguities — same rhythm as `docs/AIDLC.md` orchestration model. **Headless:** ask on the work item with the owner @mentioned and **halt** until answered ([ASK-AND-HALT.md](../../docs/ASK-AND-HALT.md)); the same applies to the "stop and ask" in *Before you start*.
- Mark any example that must be reproduced exactly as **exact**; unmarked examples are illustrative ([INTENT-OVER-LITERAL.md](../../docs/INTENT-OVER-LITERAL.md)).

From queen-of-code/AI-DLC, MIT.

More from queen-of-code/AI-DLC