Workflow Speckit

# Phase 3 — Spec-Driven Breakdown with Spec-Kit (Vertical-Slice Architecture)

You are the lead specification architect. Your job is to transform the validated PRD at `docs/prd.md` into a complete set of spec-kit artifacts that are precise enough to drive implementation — and then PROVE at every step that the process was followed correctly and the outputs meet quality standards.

**CRITICAL**: This phase follows the Spec-Kit (github.com/github/spec-kit) methodology precisely. Spec-Kit uses a Spec-Driven Development (SDD) flow with specific artifact outputs at each stage. Do NOT deviate from this process.

**CRITICAL — VERTICAL SLICES**: Tasks MUST be organized as vertical slices, NOT horizontal layers. Each slice delivers ONE user-visible capability spanning data + logic + UI. You MUST NOT create task orderings that build all backend before any UI. For web applications, every slice must include UI work so the feature can be verified in a browser.

## Inputs

- Read `docs/prd.md` (required — must exist from Phase 2)
- Read `CLAUDE.md` if it exists
- Read any research materials in `docs/`

## Prerequisites

Ensure spec-kit is initialized. If `.specify/` does not exist:

```bash
# Install if needed
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# Initialize for Claude Code
specify init . --ai claude --force

If spec-kit is already initialized, verify the .specify/ directory contains memory/, scripts/, templates/, and specs/ subdirectories. Read the templates at .specify/templates/spec-template.md, .specify/templates/plan-template.md, and .specify/templates/tasks-template.md to understand the exact output format required.

---

MASTER TASK — Five Stages

STAGE 1: Build ALL validation tests first (TDD for specs)
STAGE 2: Generate spec-kit artifacts step-by-step with per-step validation
STAGE 3: Run full-chain validation across all artifacts
STAGE 4: Fix-and-revalidate loop until all tests pass
STAGE 5: Git hooks and artifact protection

---

STAGE 1: Build the Complete Validation Framework

Before generating a single artifact, create the ENTIRE test suite. This is TDD for specifications — the tests define "done" for every step.

Create scripts/validate-speckit.js (Node.js). This single script must support two modes:

# Validate a single step's output
node scripts/validate-speckit.js --step constitution
node scripts/validate-speckit.js --step specify
node scripts/validate-speckit.js --step plan
node scripts/validate-speckit.js --step analyze
node scripts/validate-speckit.js --step tasks
node scripts/validate-speckit.js --step checklist

# Validate the entire artifact chain
node scripts/validate-speckit.js --all

The --step mode is used after each step in Stage 2 to gate progression. The --all mode is used in Stage 3 for full-chain validation.

Test Categories by Step

STEP 1 Tests: Constitution (.specify/memory/constitution.md)

TEST-C01: File exists and is non-empty
TEST-C02: Contains at least 3 distinct principles or articles
TEST-C03: Every principle uses imperative language (MUST, MUST NOT, SHALL, SHALL NOT)
TEST-C04: Principles cover code quality (scan for keywords: style, lint, format, naming)
TEST-C05: Principles cover testing (scan for: test, TDD, coverage, assertion)
TEST-C06: Principles cover architecture (scan for: module, boundary, dependency, layer, separation)
TEST-C07: No two principles contradict each other (flag pairs that reference the same domain with opposing directives)
TEST-C08: If CLAUDE.md exists, its MUST/MUST NOT rules appear in constitution (cross-reference check)

STEP 2 Tests: Specification (.specify/specs/[feature-dir]/spec.md)

Structural tests:

TEST-S01: File exists in a correctly numbered feature directory (NNN-feature-name/)
TEST-S02: Contains required sections: Feature Overview, User Stories, Functional Requirements, Non-Functional Requirements, UI Component Specifications, Out of Scope
TEST-S03: Contains a "Review & Acceptance Checklist" section
TEST-S04: Checklist items are checked off (marked complete), not left blank

User Story tests:

TEST-S05: At least 3 user stories exist
TEST-S06: Every user story has a priority level (P1, P2, or P3)
TEST-S07: Every user story has a plain-language "Description" section
TEST-S08: Every user story has a "Why this priority" rationale
TEST-S09: Every user story has an "Independent Test" description
TEST-S10: Every user story has at least 1 acceptance scenario in Given/When/Then format
TEST-S11: Total acceptance scenarios >= (user story count x 1.5)
TEST-S12: Every user story has "Visual Acceptance Criteria" describing what the user sees

Functional Requirements tests:

TEST-S13: At least 5 functional requirements exist
TEST-S14: Every FR follows pattern: FR-XXX: System MUST/MUST NOT [action]
TEST-S15: FRs are sequentially numbered with no gaps
TEST-S16: No FR uses subjective language without measurable definition

UI Component Specifications tests (NEW):

TEST-S28: spec.md contains a "UI Component Specifications" section
TEST-S29: Every UI component references at least one FR
TEST-S30: Every user story with visual acceptance criteria has at least one corresponding UI component specification
TEST-S31: Every UI component specifies: name, props/data, visual states (default, loading, error, empty), interaction behavior

Edge case and error coverage tests:

TEST-S17: Spec contains at least 2 edge case/error scenario FRs (scan for: "error", "fail", "invalid", "boundary", "edge case", "when [X] is empty", "when [X] does not exist")
TEST-S18: At least one NFR addresses security
TEST-S19: At least one NFR addresses performance with a specific metric

Clarification tests:

TEST-S20: Zero unresolved [NEEDS CLARIFICATION] markers remain
TEST-S21: If a "Clarifications" section exists, every entry references a specific FR or US number

Traceability tests: `` ```