Design Workflow

Design Workflow

Orchestrates a full system design by sequencing the focused skills in the right order. Each skill does one thing well — this skill decides which ones to invoke, in what order, and handles the transitions between them.

This plugin owns the core system design workflow skills: architecture, data-modeling, design-review, and c4-diagrams. For full end-to-end work, compose with companion plugin skills when they are installed: planning:requirements, codebase:api-design, documentation:write-design-doc, and documentation:write-adr.

When to use this vs a specific skill

• User says "design me a system for X" → use this workflow
• User says "design the API for X" → go directly to api-design
• User says "review this design" → go directly to design-review
• User says "what should the database look like" → go directly to data-modeling
• User has a broad, ambiguous request → start here, narrow down

The design sequence

Not every project needs every step. Skip steps that don't apply, but skip consciously — acknowledge what you're skipping and why.

Step 1: Scope check

Before doing anything, figure out what already exists:

• Read .context/architecture/ for existing design artifacts
• Read the codebase for existing schemas, routes, and infrastructure
• Check if requirements, architecture docs, or ADRs already exist

If significant work already exists, don't start from scratch — pick up where the existing work leaves off.

Step 2: Requirements (skip if scope is clear)

When to do this: The user has a vague idea ("I need to build X") or the requirements have gaps that would block architecture decisions.

When to skip: The user has a clear, specific ask with known constraints, or existing documentation covers the requirements.

What to do: If planning:requirements is installed, follow it. Otherwise gather the minimum requirements inline. The output is a structured requirements doc in .context/architecture/requirements/. The key deliverables are: functional requirements (MoSCoW-prioritized, numbered), NFR targets with concrete numbers, constraints, and open questions.

Transition: Once requirements are captured, move to architecture. Carry the requirements doc forward — the architecture skill reads it as input.

Step 3: Architecture

Always do this for new systems. This is the core intellectual work — component decomposition, data flow, failure modes, tech selection.

What to do: Follow the architecture skill. The output is a set of components with clear boundaries, data flow analysis, failure mode thinking, and tech selection with trade-offs.

Key decision at this step: D1 vs Neon (see data-modeling's "Data store selection"). This shapes everything downstream.

Transition: Architecture produces the component list and data flow. Hand these to data-modeling for schema design, then api-design for the API surface.

Step 4: Data modeling

When to do this: The system has persistent state (most systems do).

When to skip: The system is stateless (pure compute, proxy, or orchestration layer with no database).

What to do: Follow the data-modeling skill. Start from the entities identified in architecture. The output is a Drizzle schema with IDs, naming, tenancy, timestamps, indexes, and migrations.

Transition: The schema informs the API design — resources map to entities, and the API shapes are derived from the schema.

Step 5: API design

When to do this: The system has an HTTP or RPC interface (most systems do).

When to skip: The system is purely background (queue consumer, cron job) with no external API.

What to do: Follow the api-design skill. Start from the resources identified in data modeling and the flows from architecture. The output is a spec with endpoints, schemas, auth, errors, and cross-cutting concerns.

Step 6: Write the design doc

When to do this: The design is substantial enough to document (>1 service, >5 endpoints, non-trivial architecture). Or the user explicitly asks for a design doc.

When to skip: Small features, quick additions, or when the user prefers to keep things informal.

What to do: If documentation:write-design-doc is installed, follow it. Otherwise write the design doc inline from the outputs of steps 2-5. The design doc is the artifact that engineers implement from.

Step 7: ADRs and diagrams (as needed)

ADRs: If any non-obvious decisions were made during the design (new service, new vendor, deviation from defaults), suggest capturing them as ADRs via documentation:write-adr when available. Don't create ADRs for every decision — only for genuine trade-offs where the rejected option had real merit.

Diagrams: If the system has >4 components or the user wants a visual, produce a C4 diagram via workflow:c4-diagrams when available. A Container-level diagram is the most useful default.

Step 8: Self-review

Before declaring the design done, run a quick self-review using the design-review lens:

• Does every NFR have a concrete mechanism in the architecture?
• Are failure modes addressed for each component?
• Is the trade-off table complete?
• Would a junior engineer be able to implement from this doc?

If gaps surface, go back and fill them rather than leaving them as "open questions" — unless they genuinely need input from someone else.

Working style

• Don't dump everything at once. Work through one step at a time. Show the output of each step, check if the user has feedback, then move to the next.
• Skip freely, but say so. "Skipping formal requirements gathering since you've already described the scope clearly" is better than silently jumping to architecture.
• Carry context forward. Each step builds on the previous one. Reference specific decisions, entity names, and component names from earlier steps.
• Surface trade-offs at decision points. When architecture produces a decision (D1 vs Neon, sync vs async, monolith vs service), pause and explain the trade-off before continuing. The user may have a preference.
• Use AskUserQuestion for genuine forks. When there are two viable paths and the choice affects everything downstream, ask. Don't ask about cosmetic details.