design-artifacts

name	design-artifacts
description	Generate the full project-level spec stack from ARCHITECTURE.md and PRD — DATABASE_SCHEMA, API_REFERENCE, SEQUENCE_DIAGRAMS, DATA_FLOW, DEPLOYMENT, DEVELOPMENT_GUIDE, DEBUGGING-GUIDE, TEMPLATE_SCHEMA. The missing link between DEFINE and BUILD. Usage: /design-artifacts [all | doc-name ...]

Core Philosophy: Agents during BUILD read whatever docs exist. If no specs exist, they guess. This skill generates the foundational docs that make /story and /implement reliable — grounded in the architecture and PRD, not invented from scratch.

Triggers: "generate design docs", "create the spec stack", "write the database schema doc", "set up project documentation", "design artifacts", "/design-artifacts"

---

You are the design artifacts generator. Your job is to produce the project-level specification documents that BUILD phase agents read for context. Every doc is grounded in the existing ARCHITECTURE.md and PRD — you don't invent scope, you document what's already decided.

8 output docs. All by default. Individual selection supported.

---

Step 0 — Register in task files

Before doing anything else, write an in-progress breadcrumb to tasks/notes.md in EVERY pack and mode:

• Append under an "In Progress" or "Current" heading (create one if absent):

  - [DEFINE] /design-artifacts — <project name or "all docs"> — started YYYY-MM-DD
  

• If tasks/notes.md is genuinely missing, skip this step silently.
• NEVER write the breadcrumb to todo.md.

Use the Edit tool — one targeted append. Do NOT rewrite the whole file.

---

Step 1 — Input gate (pre-flight)

Read these two files — both are required:

1. ARCHITECTURE.md — check docs/ARCHITECTURE.md then ARCHITECTURE.md at repo root
2. PRD.md — check PRD.md at repo root

If either is missing, stop immediately:

"I need both an ARCHITECTURE.md and a PRD.md to generate design artifacts.

• ARCHITECTURE.md: [found at / not found — run /architect first]
• PRD.md: [found at / not found — run /prd first]"

(Gate type: pre-flight)

---

Step 2 — Gather context

Read silently (skip if not found):

• CONTEXT.md — domain glossary and module map
• docs/adr/*.md — architecture decisions
• tasks/lessons.md or tasks/notes.md — project conventions (frameworks, patterns)
• research.md — cached external API research
• tasks/compliance-owners.md — regulated data handling

If the project already has code, explore it:

• Read package.json, *.csproj, requirements.txt, go.mod, or equivalent for dependencies
• Glob src/**/* to understand the current structure
• Read key files (entry points, route definitions, data models) to ground the docs in reality

---

Step 3 — Ask which docs to generate

Parse $ARGUMENTS for doc selection. Accept:

• all (default if no args) — generate all 8 docs
• Individual names: database-schema, api-reference, sequence-diagrams, data-flow, deployment, development-guide, debugging-guide, template-schema
• Multiple names: database-schema api-reference deployment

If the user specified individual docs, confirm:

"Generating: [list]. The others will be skipped. Proceed?"

If all, proceed without asking.

The 8 docs:

Doc	Output path	What it covers
Database Schema	docs/DATABASE_SCHEMA.md	Entity definitions, relationships, field types, constraints, indexes
API Reference	docs/API_REFERENCE.md	Endpoints, request/response shapes, auth, status codes
Sequence Diagrams	docs/SEQUENCE_DIAGRAMS.md	Key flows as Mermaid sequence diagrams
Data Flow	docs/DATA_FLOW.md	How data moves through the system, regulated data paths highlighted
Deployment	docs/DEPLOYMENT.md	Deployment steps, environment config, infrastructure dependencies
Development Guide	docs/DEVELOPMENT_GUIDE.md	Local setup, dev conventions, how to run the project
Debugging Guide	docs/DEBUGGING-GUIDE.md	Common problems and how to diagnose them
Template Schema	docs/TEMPLATE_SCHEMA.md	Project-specific template/schema definitions (optional)

---

Step 4 — Generate the docs

For each selected doc, generate content grounded in the ARCHITECTURE.md and PRD. Use the templates in skills/design-artifacts/templates/ as the structure.

Two modes:

Mode A — Project init (no existing code): Generate from PRD + ARCHITECTURE.md as the design spec. Entities, endpoints, and flows come from the architecture decisions and PRD requirements. Mark sections as "Planned" where implementation doesn't exist yet.

Mode B — Mid-project (existing code): Read the codebase first. Entities come from actual data models. Endpoints come from actual route definitions. Flows come from actual code paths. Only add "Planned" sections for things in the PRD/architecture that haven't been built yet.

For each doc:

1. Check if the doc already exists at the output path
2. If it exists, read it and update only sections that changed — don't regenerate from scratch
3. If it doesn't exist, create it from the template
4. Use Mermaid for all diagrams (sequence diagrams, data flow diagrams, entity relationships)
5. Use domain vocabulary from CONTEXT.md if available
6. Highlight regulated data paths (PHI/PII) in DATA_FLOW.md

Work through docs one at a time. After each doc is written, report:

"Wrote docs/<NAME>.md — [one-sentence summary of what it covers]."

---

Step 5 — Log completion in task files

After all selected docs are written:

1. tasks/notes.md — find the in-progress breadcrumb and mark it done in EVERY pack/mode:

   - ✅ [DEFINE] /design-artifacts — <project> — N docs generated — output: docs/
   

   Never mark ✅ in todo.md — it is a generated dashboard (D9).

2. flags-and-notes.md — append to "Important Notes":

   - [DESIGN-ARTIFACTS] Generated N docs — <date> — output: docs/ — Status: Draft
   

Use the Edit tool — targeted appends, not rewrites.

---

Step 6 — Summary

Present a summary table:

Design artifacts generated:

Doc	Path	Status
Database Schema	docs/DATABASE_SCHEMA.md	Created / Updated / Skipped
...	...	...

"These docs are now available for /story and /implement to read during planning. Review them and update as the project evolves."

---

Rules

• Never generate a doc without grounding it in ARCHITECTURE.md and PRD. No invented scope.
• Never regenerate a doc from scratch if it already exists. Update in place — preserve user edits.
• All diagrams use Mermaid. No external tools, no image generation.
• Use domain vocabulary from CONTEXT.md when available.
• Highlight regulated data paths in DATA_FLOW.md — call out where PHI/PII flows and how it's protected.
• TEMPLATE_SCHEMA.md is optional — only generate it if the PRD or architecture mentions project-specific templates or schemas.
• Mark sections as "Planned" when documenting features not yet implemented. Don't present planned work as existing.
• No emoji. Keep the format tight.