Design

Design (Phase 3)

Produce the artifacts Build will reference and Test will execute against.

Prerequisite

.claude/sdlc/gates/analyze-<task-slug>.md must exist and be signed.

Artifacts produced (or updated)

All live under .claude/sdlc/architecture/ with a manifest.json index:

1. Application architecture — components, integrations, data flow, NFRs (performance, availability, scalability)
2. Data architecture — entities, schema changes, flows, retention, classification
3. Platform architecture — runtimes, orchestration, environments
4. Infrastructure architecture — compute, network, storage, identity
5. Security architecture — threat model, controls, secrets handling, authn/authz
6. Test architecture — pyramid shape, test types, tooling, environments, test-data strategy
7. Technical specifications — API contracts, data contracts, module responsibilities (under .claude/sdlc/tech-specs/)
8. Test cases — one or more per requirement, each tied to REQ IDs (under .claude/sdlc/test-cases/)
9. DevOps pipeline design — stages, gates, environments, promotion rules

Rule: validate before rewriting

If architecture artifacts already exist:

• Read them.
• Produce a validation report comparing existing architecture against the current requirements set.
• Surface deltas (new NFRs, new entities, new integrations, new controls) for human decision.
• Only after the human agrees, update the affected files. Never wholesale-regenerate a working architecture.

Test-case rule

Each requirement gets at least one test case. Each test case references:

• The REQ IDs it covers
• The test type (unit / integration / e2e / NFR)
• Preconditions, steps, expected outcome
• Data needs

Use templates/test-case.md.

Tech spec rule

For each in-scope module or service, produce or update a spec under .claude/sdlc/tech-specs/. Specs are the contract Build validates its code against — API shape, inputs/outputs, error modes, side effects, NFR commitments.

Subagent delegation (optional)

When the architect or test-designer subagents are enabled, run them in parallel:

• architect validates existing architecture and proposes changes (read-only over code; write-only into architecture/)
• test-designer produces test cases from requirements (write-only into test-cases/)

The skill coordinates; the human still approves.

Human gate

Summarize: architecture deltas, test-case count, spec count, pipeline changes. Sign-off goes to .claude/sdlc/gates/design-<task-slug>.md.

What this skill must NOT do

• Do not write application code. That is Build.
• Do not generate a new architecture when a valid one exists — validate first.
• Do not produce test cases that aren't traceable to a REQ ID.

References

• templates/tech-spec.md
• templates/test-case.md
• templates/gate.md
• agents/architect.md
• agents/test-designer.md

Next step hint

After writing the gate file, pipe the next_suggestions conditions to skills/_shared/next-hint.sh and print any output:

printf '%s\n' \
  'design_gate_signed|run /build to write code and unit tests scoped to the plan' \
  'pending_signoff_for_current_user|write your sign-off at sign-offs/<REQ-ID>-<role>.md, then /build when all roles are covered' \
  | bash skills/_shared/next-hint.sh

Print any output verbatim. If the script outputs nothing, add nothing.