8-step quality gate workflow: Spec → Backend → Tests → Frontend → Tests → E2E

version
0.2.0

Install

/plugin install dev@packlikez-dev-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add packlikez/claude-code-dev-plugin.

Contents

Discovered from source

Commands 15

Step 4: API Integration Tests

Prerequisites

□ GATE 3 PASSED (backend unit tests complete)
□ All unit tests passing with ≥80% coverage

Process

1. Load Context

cat specs/{type}/{feature-name}.md           # Spec (source of truth)
cat src/routes/{feature}.ts                  # Route implementation
cat tests/unit/services/{feature}*.test.ts   # Unit tests (what's tested)
cat skills/test-patterns-api.md              # API test patterns
cat skills/gate-4-api-test.md                # Gate 4 criteria

2. Build Context Map

## What Unit Tests Cover
- Service layer logic
- Validation rules (mocked DB)

## What API Tests Must Cover
- Full HTTP request/response cycle
- Real database (no mocks)
- Auth middleware integration
- Response format matches spec
- Database state after mutations

3. Delegate to Test Writer

Use Task tool with test-writer agent:

Write API integration tests for {feature-name}:
- Real database (no mocks)
- Every endpoint from spec
- Every error response from spec
- Isolated seed data per test
- Follow test-patterns-api skill

4. Key Requirements

Real Infrastructure (no mocks):

  • Real database (test DB)
  • Real services
  • Real auth middleware
  • Only mock external APIs

Per Endpoint:

  • Success response (200/201)
  • Validation error (400)
  • Unauthorized (401)
  • Forbidden (403) if roles
  • Not found (404)
  • Conflict (409) if unique

Database Verification:

  • Check state after mutations
  • Verify rollback on errors

5. Spec Gap Protocol

If response doesn't match spec:

Use AskUserQuestion:
"API response doesn't match spec:
Spec says: {expected}
API returns: {actual}
Options:
1. Fix implementation
2. Update spec"

6. Generate API Contract

Load api-contract skill for format:

cat skills/api-contract.md

After tests pass, generate contract following the skill format.

7. Validate Gate

Use Task tool with gate-keeper agent:

Validate GATE 4 for {feature-name}

See gate-4-api-test skill for all 26 criteria.

Output

  • Tests: tests/integration/api/
  • Seeds: tests/seeds/
  • Contract: api-contracts/{feature}.yaml

Step 3: Backend Unit Tests

Prerequisites

□ GATE 2 PASSED (backend implementation complete)
□ Spec exists: specs/{type}/{feature-name}.md

Process

1. Load Context

cat specs/{type}/{feature-name}.md     # Spec (source of truth)
cat src/services/{feature}Service.ts   # Implementation
cat skills/test-patterns-unit.md       # Unit test patterns
cat skills/gate-3-backend-unit.md      # Gate 3 criteria

2. Create Test Checklist from Spec

From SpecTests to Write
Acceptance CriteriaEach GIVEN/WHEN/THEN becomes test
Validation RulesTest pass and fail cases
Edge CasesTest EVERY edge case in spec
Error ResponsesTest EVERY error from spec

3. Delegate to Test Writer

Use Task tool with test-writer agent:

Write backend unit tests for {feature-name}:
- Every acceptance criterion
- Every edge case from spec
- Every error response from spec
- Follow test-patterns-unit skill

4. Key Requirements

From test-patterns-unit skill:

  • Strong assertions only (no toBeDefined alone)
  • AAA pattern (Arrange-Act-Assert)
  • Fixtures and factories
  • Mock dates and random values
  • ZERO weak assertions

From spec:

  • Every public function tested
  • Every edge case tested
  • Every error condition tested

5. Spec Gap Protocol

If gaps discovered during testing:

Use AskUserQuestion:
"Found gap in spec: {issue}
Options:
1. Update spec to {A}
2. Update spec to {B}"

Update spec first, then write tests.

6. Validate Gate

Use Task tool with gate-keeper agent:

Validate GATE 3 for {feature-name}

See gate-3-backend-unit skill for all 20 criteria.

Output

  • Test files: tests/unit/services/
  • Fixtures: tests/fixtures/
  • Coverage report

Step 2: Backend Implementation

Prerequisites

□ GATE 1 PASSED (spec complete)
□ Spec exists: specs/{type}/{feature-name}.md

Process

1. Load Context

cat specs/{type}/{feature-name}.md     # Spec (source of truth)
cat .claude/project.md                 # Project patterns

2. Dependency Mapping (BEFORE any code)

Load dependency-map skill and map ALL needed items:

cat skills/dependency-map.md

Extract from spec:

ServicePurposeExists?Action
{service}{purpose}?CREATE/REUSE
UtilityPurposeExists?Action
{utility}{purpose}?CREATE/REUSE

Quick existence check:

ls src/services/ 2>/dev/null
ls src/utils/ src/lib/ 2>/dev/null
grep -r "{function-name}" src/utils/ 2>/dev/null

Create stubs for ALL missing items FIRST:

// Create stub files with throw new Error('Not implemented')
// This ensures no "module not found" during implementation

3. Implementation Order

Based on dependency map:

  1. Create stubs for all missing
  2. Implement services (no dependencies first)
  3. Implement services (with dependencies)
  4. Implement routes (uses services)

4. Delegate to Implementer

Use Task tool with implementer agent:

Implement backend for {feature-name}:
- Dependency map: .claude/deps/{feature-name}.md
- All endpoints from spec
- All validation rules from spec
- All error responses from spec
- Follow project patterns

5. Key Requirements

From spec:

  • Every endpoint implemented
  • Every validation rule
  • Every error response (400, 401, 403, 404, 409, 500)

Quality:

  • No TODO/FIXME
  • Small functions (≤30 lines)
  • Fail fast (validations at top)
  • Max 3 levels nesting

6. Spec Gap Protocol

If you discover gaps during implementation:

Use AskUserQuestion:
"Found gap in spec: {issue}
Options:
1. Update spec to {A}
2. Update spec to {B}"

Update spec first, then implement.

7. Validate Gate

Use Task tool with gate-keeper agent:

Validate GATE 2 for {feature-name}

See gate-2-backend skill for all 17 criteria.

Output

  • Implementation in src/
  • Migrations in migrations/ (if needed)

Step 8: E2E Integration Tests (Real API) - FINAL GATE

Prerequisites

□ GATE 7 PASSED (E2E with mocked API complete)
□ Backend running
□ Database accessible
□ All previous gates passed (1-7)

Why Real API?

  • True integration: Verify frontend ↔ backend ↔ database work together
  • Data persistence: Confirm data saves correctly
  • Auth flow: Real tokens, sessions, permissions
  • Final validation: Catch integration bugs before production

Process

1. Load Context (FINAL REVIEW)

cat specs/{type}/{feature-name}.md           # Spec (source of truth)
cat api-contracts/{feature}.yaml             # API contract
cat tests/e2e/{feature}/*.spec.ts            # E2E tests (mocked)
cat skills/gate-8-e2e-integration.md         # Gate 8 criteria

2. Environment Setup

# Ensure backend is running
curl http://localhost:3000/health

# Ensure database is accessible
# Run migrations if needed
npm run db:migrate

# Seed test data if needed
npm run db:seed:test

3. Convert Mocked Tests to Integration

E2E Test (Mocked)Integration Version
tests/e2e/login.spec.tstests/e2e-integration/login.spec.ts
Remove: page.route()Use: real API calls
Add: DB verificationAdd: cleanup

4. Delegate to Test Writer

Use Task tool with test-writer agent:

Write E2E Integration tests for {feature-name}:
- Copy from tests/e2e/ as base
- Remove ALL route mocks (use real API)
- Add database state verification
- Add test data cleanup (beforeEach/afterEach)
- Add auth token handling if needed
- Verify data persists correctly

5. Key Requirements

Real Integration:

  • No mocked API calls
  • Real database operations
  • Real auth tokens
  • Real file uploads (if applicable)

Database Verification:

// After mutation, verify DB state
const res = await request.post('/api/users').send(data);
const dbUser = await db.users.findById(res.body.id);
expect(dbUser.email).toBe(data.email);

Test Isolation:

beforeEach(async () => {
  await db.users.deleteMany({ email: /@test\.com$/ });
});

afterEach(async () => {
  await db.users.deleteMany({ email: /@test\.com$/ });
});

Stability:

  • Run 3x → all pass
  • No flaky tests
  • Handle race conditions
  • Total runtime < 5 minutes

6. Validate Gate (FINAL)

Use Task tool with gate-keeper agent:

Validate GATE 8 for {feature-name}

See gate-8-e2e-integration skill for all criteria.

Completion

When GATE 8 passes:

## {feature-name}
- [x] Step 1: Spec (GATE 1 ✓)
- [x] Step 2: Backend (GATE 2 ✓)
- [x] Step 3: Backend Unit Tests (GATE 3 ✓)
- [x] Step 4: API Tests (GATE 4 ✓)
- [x] Step 5: Frontend (GATE 5 ✓)
- [x] Step 6: Frontend Unit Tests (GATE 6 ✓)
- [x] Step 7: E2E Tests (GATE 7 ✓)
- [x] Step 8: E2E Integration (GATE 8 ✓)

STATUS: ✅ FEATURE COMPLETE

Feature ready for: code review → merge → deploy

Output

  • Integration tests: tests/e2e-integration/{feature}/
  • Final validation report
  • Progress update: COMPLETE

Step 7: E2E Tests (Mocked API)

Prerequisites

□ GATE 6 PASSED (Frontend unit tests complete)
□ All frontend unit tests passing
□ API contract defined: api-contracts/{feature}.yaml

Why Mocked API?

  • Fast: No DB setup, no network latency
  • Stable: No external dependencies, no flakiness
  • Edge cases: Easy to simulate errors, timeouts, edge responses
  • Parallel: Tests run independently

Process

1. Load Context

cat specs/{type}/{feature-name}.md           # Spec (source of truth)
cat api-contracts/{feature}.yaml             # API contract for mocking
cat skills/test-patterns-ui.md               # UI/E2E test patterns
cat skills/ux-patterns.md                    # UX patterns
cat skills/gate-7-e2e.md                     # Gate 7 criteria

2. Setup API Mocks

// Mock API responses based on api-contract
await page.route('**/api/users', route => {
  route.fulfill({
    status: 200,
    body: JSON.stringify({ id: '1', name: 'Test User' })
  });
});

3. Map User Journeys

JourneyMocked ResponsesStatus
Happy path login200 + user data□
Invalid credentials401 + error□
Server error500 + retry□

4. Delegate to Test Writer

Use Task tool with test-writer agent:

Write E2E tests (mocked API) for {feature-name}:
- Mock all API calls based on api-contract
- Complete user journeys (UI only)
- Use data-testid for element selection
- Every acceptance criterion from spec
- Every edge case (mock error responses)
- Follow test-patterns-ui skill
- Follow ux-patterns skill

5. Key Requirements

API Mocking:

  • All API calls mocked via route interception
  • Response shapes match api-contract exactly
  • Error responses for all error codes (400, 401, 403, 404, 500)

Element Selection:

  • data-testid first priority
  • id second priority
  • No CSS/XPath selectors

Coverage:

  • Every AC from spec
  • Every edge case
  • Loading states
  • Error states + recovery

Stability:

  • Run 3x → all pass
  • No flaky tests
  • Fast execution (mocked = fast)

6. Validate Gate

Use Task tool with gate-keeper agent:

Validate GATE 7 for {feature-name}

See gate-7-e2e skill for all criteria.

Output

  • E2E tests: tests/e2e/{feature}/
  • All API mocked, no real backend needed

Ensure End-to-End Working

Deep verification that target works completely according to spec or understood functionality.

Supports large features with checkpointing and context management.

Process Overview

EXPLORE → CLARIFY → CONFIRM → VERIFY (chunked) → REPORT

Context Management (Large Features)

Before Starting

Estimate feature size:

SizeFilesAction
Small<5Execute directly
Medium5-15Chunk verification, checkpoint after each
Large15+Delegate exploration to agents, chunk all phases

Chunking Strategy

Break verification into independent chunks:

CHUNK 1: Spec & Backend verification
CHUNK 2: Frontend verification
CHUNK 3: Test verification
CHUNK 4: Data flow verification
CHUNK 5: Edge cases & error handling

After each chunk:

  1. Save progress to .claude/ensure-progress.md
  2. Summarize findings
  3. Continue or pause if context heavy

Progress File Format

Write to .claude/ensure-progress.md:

# Ensure Progress: {target}
Updated: {timestamp}

## Completed Chunks
- [x] Chunk 1: Spec & Backend - 8/8 passed
- [x] Chunk 2: Frontend - 5/5 passed
- [ ] Chunk 3: Tests - IN PROGRESS

## Current Chunk
Chunk: 3 - Test verification
Progress: 12/20 checks
Last check: API test for POST /users

## Findings So Far
- PASS: All AC implemented
- PASS: All endpoints exist
- FAIL: Missing test for password reset
- WARN: E2E test flaky (1/3 fails)

## Remaining
- Chunk 3: 8 more checks
- Chunk 4: Data flow (15 checks)
- Chunk 5: Edge cases (10 checks)

## Context Reload (if resuming)
Read: specs/features/{target}.md
Read: .claude/ensure-progress.md

Resume Command

If context compacts or new session:

/dev:ensure {target} --resume

This reads .claude/ensure-progress.md and continues from last checkpoint.


Phase 1: Explore

Thoroughly explore the target to understand every detail.

1.0 Size Check First

# Count related files
find . -name "*{target}*" | wc -l
CountAction
<5Explore directly
5-15Use grep summaries, read key files only
15+Delegate to Explore agent

1.1 For Large Features: Delegate Exploration

Use Task tool with Explore agent:

"Explore all files related to {target} feature.
Find: specs, backend code, frontend code, tests.
Return: file list with brief purpose of each.
Do not read full content, just identify files."

1.2 Find All Related Files

# Spec
find . -name "*{target}*" -path "*/specs/*"

# Backend (just list, don't read yet)
find . -name "*{target}*" -path "*/src/*" -name "*.ts" | grep -v test

# Frontend
find . -name "*{target}*" -path "*/src/*" -name "*.tsx"

# Tests
find . -name "*{target}*" -path "*/tests/*"

# API routes (grep for mentions)
grep -rln "{target}" src/routes/ src/api/ 2>/dev/null

1.3 Smart Reading (Token Efficient)

Don't read full files. Extract key info:

# Get function names only
grep -n "export.*function\|export.*const.*=" {file}

# Get endpoint definitions only
grep -n "router\.\|app\.\|@Get\|@Post" {file}

# Get component names only
grep -n "export.*function\|export default" {file}

# Get test names only
grep -n "describe\|it\|test(" {file}

Only read full file when needed for specific check.

1.4 Build Understanding Map

TARGET: {name}
Files found: {n} (Small/Medium/Large)

SPEC SUMMARY:
- AC count: {n}
- Edge cases: {n}
- Screens: {n}

IMPLEMENTATION SUMMARY:
- Endpoints: {n} in {files}
- Components: {n} in {files}
- Services: {n} in {files}

TESTS SUMMARY:
- Unit: {n} files, {n} tests
- API: {n} files, {n} tests
- E2E: {n} files, {n} tests

INITIAL GAPS:
- {any obvious missing pieces}

Save to .claude/ensure-progress.md before continuing.


Phase 2: Clarify

Use AskUserQuestion to understand what exactly needs verification.

Questions to Ask

  1. Scope: "What aspect do you want to ensure?"

    • Full end-to-end flow
    • Specific functionality
    • Edge cases only
    • Performance/security
  2. Depth: "How thorough should verification be?"

    • Quick check (run existing tests)
    • Standard (run tests + manual checks)
    • Deep (trace every code path)
  3. Focus areas: "Any specific concerns?"

    • Data validation
    • Error handling
    • UI behavior
    • API responses
    • Database state

Phase 3: Confirm

Present findings and get confirmation before proceeding.

Show Summary

ENSURE: {target}

FOUND:
- Spec: {file} with {n} acceptance criteria
- Backend: {n} endpoints in {files}
- Frontend: {n} components in {files}
- Tests: {n} unit, {n} API, {n} E2E

WILL VERIFY:
1. All {n} acceptance criteria from spec
2. All endpoints respond correctly
3. All components render with correct data
4. Data flows: Input → API → DB → Response → UI
5. Error cases handled
6. Edge cases covered

ESTIMATED: {n} checks

Proceed? (Yes/No/Modify scope)

Phase 4: Verify (Chunked)

Systematically verify every detail. Use TodoWrite to track progress.

4.0 Initialize Verification Todos

Use TodoWrite to create verification checklist:

Todos:
- [ ] Chunk 1: Spec vs Backend
- [ ] Chunk 2: Frontend verification
- [ ] Chunk 3: Test coverage
- [ ] Chunk 4: Data flow
- [ ] Chunk 5: Edge cases & errors

Chunk 1: Spec vs Implementation

For each acceptance criterion:

AC: "User can register with email and password"

CHECK:
[ ] API endpoint exists: POST /api/auth/register
[ ] Endpoint accepts: { email, password }
[ ] Endpoint validates: email format, password length
[ ] Endpoint returns: { user: { id, email }, token }
[ ] DB stores: users table with hashed password
[ ] Frontend form: email input, password input, submit
[ ] Frontend shows: success/error message

After chunk: Update .claude/ensure-progress.md, mark todo complete.

Chunk 2: Frontend Verification

[ ] All screens from spec exist
[ ] Components render correctly
[ ] Forms have proper validation
[ ] Loading states shown
[ ] Error states handled

After chunk: Checkpoint progress.

Chunk 3: Test Coverage

[ ] Unit tests exist for all functions
[ ] API tests cover all endpoints
[ ] E2E tests cover all user flows
[ ] No weak assertions (run detection)
[ ] Tests actually pass
# Run tests
npm test -- --grep "{target}"

# Weak assertion check
grep -rEn "(toBeDefined|toExist|toBeTruthy)\(\)" tests/**/*{target}*

After chunk: Checkpoint progress.

Chunk 4: Data Flow Verification

Trace ONE complete flow (don't read all files):

INPUT: email="test@example.com"

1. FRONTEND → grep for form submit handler
2. API → grep for endpoint handler
3. DB → grep for database call
4. RESPONSE → check response shape
5. UI → check success display

Verify input value appears at each step.

After chunk: Checkpoint progress.

Chunk 5: Edge Cases & Error Handling

EDGE CASES:
[ ] Empty inputs handled
[ ] Invalid format handled
[ ] Boundary values handled

ERRORS:
[ ] 400: Validation errors shown
[ ] 401: Redirect to login
[ ] 403: Access denied
[ ] 404: Not found
[ ] 500: Generic error
[ ] Network: Offline handling

Chunk 6: Incomplete Code Detection (CRITICAL)

Use incomplete-code-detection skill. Scan for placeholder/mock code:

# Empty functions
grep -rEn "=> \{\}|\{[\s]*\}" src/**/*{target}*

# TODO/FIXME left in code
grep -rEn "(TODO|FIXME|HACK)" src/**/*{target}*

# Empty event handlers (onClick={() => {}})
grep -rEn "on[A-Z].*=>[\s]*\{\}" src/**/*{target}*

# Console.log (debug code)
grep -rEn "console\.(log|debug)" src/**/*{target}*

# Mock/test data in production
grep -rEn "(test@|example\.com|fake|mock)" src/**/*{target}* | grep -v "\.test\.\|\.spec\."

# Empty catch blocks
grep -rEn "catch.*\{[\s]*\}" src/**/*{target}*

# Hardcoded values
grep -rEn "localhost|127\.0\.0\.1" src/**/*{target}*

ANY match = FAIL (unless intentional with documented reason)

4.5 Run Tests

# Run related tests
npm test -- --grep "{target}"

# E2E specific
npx playwright test --grep "{target}"

After All Chunks

Update final progress:

# Ensure Complete: {target}

All chunks verified:
- [x] Chunk 1: Spec vs Backend - PASS
- [x] Chunk 2: Frontend - PASS
- [x] Chunk 3: Tests - 1 FAIL (weak assertion)
- [x] Chunk 4: Data flow - PASS
- [x] Chunk 5: Edge cases - PASS

Phase 5: Report

Success Report

ENSURE COMPLETE: {target}

VERIFIED:
- Acceptance Criteria: 8/8
- Endpoints: 3/3
- Components: 5/5
- Data Flow: Verified (Input → DB → UI)
- Edge Cases: 6/6
- Error Handling: All codes covered
- Tests: 24/24 passing

STATUS: FULLY WORKING

All functionality works end-to-end according to spec.

Failure Report

ENSURE FAILED: {target}

PASSED: 18/24 checks

FAILED:
1. AC3: "Password reset email" - Not implemented
   - Missing: POST /api/auth/reset-password
   - Missing: ResetPasswordForm component
   - Action: Implement password reset flow

2. Edge case: "Expired token" - No handling
   - API returns 401 but UI shows generic error
   - Action: Add specific expired token UI

3. E2E: "login-flow.spec.ts" - Flaky
   - Fails 1/3 runs
   - Action: Add proper wait conditions

NEXT STEPS:
1. /dev:backend user-registration (implement reset)
2. Fix token expiry UI
3. Stabilize E2E test

Key Principles

  1. Every detail matters: Don't skip anything in spec
  2. Trace data flow: Input must appear in output
  3. Test assertions matter: Visibility ≠ Working
  4. Ask when unclear: Use AskUserQuestion
  5. Report gaps: Missing items are failures

Step 6: Frontend Unit Tests

Prerequisites

□ GATE 5 PASSED (frontend implementation complete)
□ All components implemented
□ Build passes

Process

1. Load Context

cat specs/{type}/{feature-name}.md         # Spec
cat api-contracts/{feature}.yaml           # API contract
cat src/components/{feature}/*.tsx         # Components
cat src/hooks/use{Feature}.ts              # Hooks
cat skills/test-patterns-unit.md           # Unit test patterns
cat skills/gate-6-frontend-unit.md         # Gate 6 criteria

2. Create Test Checklist from Spec

## Test Checklist

### Component Tests
- [ ] Default render
- [ ] Props variations
- [ ] Loading state
- [ ] Error state
- [ ] Empty state

### Hook Tests
- [ ] Initial state
- [ ] Success state
- [ ] Error state

### Interaction Tests
- [ ] Form submission (exact callback args)
- [ ] Button clicks
- [ ] Validation errors

3. Delegate to Test Writer

Use Task tool with test-writer agent:

Write frontend unit tests for {feature-name}:
- Every component state (loading, error, empty, success)
- Every hook state
- User interactions with exact assertions
- Accessibility (keyboard, axe audit)
- Follow test-patterns-unit skill

4. Key Requirements

From test-patterns-unit skill:

  • Strong assertions (not just toBeInTheDocument)
  • AAA pattern
  • Fixtures and helpers
  • Mock API responses (MSW)
  • ZERO weak assertions

From spec:

  • Every acceptance criterion tested
  • Every error state tested
  • Forms match validation rules

5. Accessibility Tests

// Required for every component
it('should pass axe audit', async () => {
  const { container } = render(<Component />);
  expect(await axe(container)).toHaveNoViolations();
});

it('should be keyboard navigable', async () => {
  await userEvent.tab();
  expect(screen.getByLabelText('Email')).toHaveFocus();
});

6. Validate Gate

Use Task tool with gate-keeper agent:

Validate GATE 6 for {feature-name}

See gate-6-frontend-unit skill for all 24 criteria.

Output

  • Component tests: tests/unit/components/{feature}/
  • Hook tests: tests/unit/hooks/
  • Coverage report

Step 5: Frontend Implementation

Prerequisites

□ GATE 4 PASSED (API tests complete)
□ API contract: api-contracts/{feature}.yaml

Process

1. Load Context

cat specs/{type}/{feature-name}.md     # Spec
cat api-contracts/{feature}.yaml       # API contract
cat skills/ux-patterns.md              # UX patterns

2. Dependency Mapping (BEFORE any code)

Load dependency-map skill and map ALL needed UI elements:

cat skills/dependency-map.md

Extract from spec - UI Components:

ComponentPurposeExists?Action
{Form}{purpose}?CREATE/REUSE
{Dialog}{purpose}?CREATE/REUSE
{Button}{purpose}?REUSE (ui lib)

Extract from spec - Hooks/Services:

Hook/ServicePurposeExists?Action
useAuthAuth state?CREATE/REUSE
apiClientAPI calls?CREATE/REUSE

Quick existence check:

ls src/components/ui/ 2>/dev/null
ls src/components/ 2>/dev/null
ls src/hooks/ 2>/dev/null
grep -r "Dialog\|Modal" src/components/ 2>/dev/null

Create stubs for ALL missing components FIRST:

// Stub component
export const FeatureDialog = () => {
  throw new Error('Not implemented - TODO');
};

3. Implementation Order

Based on dependency map:

  1. Create stubs for all missing components
  2. Implement shared hooks (useAuth, useApi, etc.)
  3. Implement child components (buttons, inputs)
  4. Implement parent components (forms, dialogs)
  5. Implement page/container components

4. Delegate to Implementer

Use Task tool with implementer agent:

Implement frontend for {feature-name}:
- Dependency map: .claude/deps/{feature-name}.md
- Generate types from API contract
- Follow ux-patterns skill
- Handle all UI states
- No native browser components

5. Key Requirements

From ux-patterns skill:

  • Optimistic updates
  • Skeleton loaders (not spinners)
  • Confirmation dialogs (not alert/confirm)
  • Focus management
  • Form protection (auto-save, unsaved warning)
  • No native components (select, date, file)

From spec:

  • All screens implemented
  • All error states handled
  • Forms match backend validation

6. Validate Gate

Use Task tool with gate-keeper agent:

Validate GATE 5 for {feature-name}

See gate-5-frontend skill for all 26 criteria.

Output

  • Components: src/components/{feature}/
  • Hooks: src/hooks/
  • Types: src/types/

Project Health Dashboard

Comprehensive view of project health across all dimensions.

Process

1. Test Health

# Run all tests with coverage
npm run test:coverage 2>&1 | tail -20

# Count passing/failing
npm test 2>&1 | grep -E "Tests:.*passed|failed"
MetricValueStatus
Unit Tests?/? passing?
API Tests?/? passing?
E2E Tests?/? passing?
Coverage?%?

2. Code Quality

# TODOs and FIXMEs
grep -rn "TODO\|FIXME" src/ | wc -l

# Console.logs
grep -rn "console\.log" src/ | wc -l

# Type errors
npx tsc --noEmit 2>&1 | grep -c "error"

# Lint errors
npm run lint 2>&1 | grep -c "error"
MetricCountStatus
TODOs/FIXMEs??
Console.logs??
Type errors??
Lint errors??

3. Feature Progress

# Count specs
ls specs/**/*.md 2>/dev/null | wc -l

# Check .claude/progress.md
cat .claude/progress.md 2>/dev/null
FeatureG1G2G3G4G5G6G7G8
{name}✓✓✓?????

4. Dependency Health

# Outdated packages
npm outdated 2>/dev/null | head -10

# Security vulnerabilities
npm audit 2>/dev/null | grep -E "vulnerabilities|found"

# Unused dependencies
npx depcheck 2>/dev/null | head -10
MetricCountStatus
Outdated packages??
Security issues??
Unused deps??

5. Learnings & Issues

# Recent learnings
ls .claude/learnings/*.md 2>/dev/null | wc -l

# Unresolved issues
grep -l "Status: Open" .claude/learnings/*.md 2>/dev/null | wc -l

Output Report

PROJECT HEALTH DASHBOARD

TESTS
- Unit: 45/45 passing (100%)
- API: 12/12 passing (100%)
- E2E: 8/8 passing (100%)
- Coverage: 78% (target: 80%) [WARNING]

CODE QUALITY
- TODOs: 3 remaining [WARNING]
- Console: 0
- Type errors: 0
- Lint errors: 0

FEATURES
- Complete: 4/6 features
- In Progress: 2 features
- Next Gate: user-profile (G5)

DEPENDENCIES
- Outdated: 2 packages
- Security: 0 vulnerabilities
- Unused: 1 package

LEARNINGS
- Captured: 12 items
- Unresolved: 2 issues

OVERALL: GOOD (minor issues)

TOP ACTIONS:
1. Increase coverage to 80%
2. Resolve 3 TODOs
3. Update 2 outdated packages

Health Levels

LevelCriteria
🟢 EXCELLENTAll tests pass, coverage >80%, no TODOs, no issues
🟡 GOODAll tests pass, minor issues (TODOs, coverage <80%)
🟠 WARNINGSome tests failing OR security issues
🔴 CRITICALBuild fails OR many tests failing

Quick Health

For fast check:

/dev:health --quick

Only shows:

  • Test pass/fail
  • Build status
  • Critical issues

Initialize & Analyze Project

Understand the project AND identify gaps according to the 8-step Quality Gate workflow.


Phase 1: Project Discovery

1.1 Detect Project Stack

# Package manager and dependencies
cat package.json 2>/dev/null | head -50

# Top-level structure
ls -la

# Source structure
find . -type d -name "src" -o -name "app" -o -name "lib" 2>/dev/null | head -10

1.2 Load Pattern Discovery

cat skills/project-patterns.md

1.3 Extract Current Patterns

Follow project-patterns skill detection commands:

  • File naming
  • Import order
  • Error handling
  • Validation approach
  • Testing patterns

Phase 2: Gap Analysis

2.1 Scan Existing Artifacts

# Specs
echo "=== SPECS ===" && ls specs/**/*.md 2>/dev/null | wc -l

# Backend implementations
echo "=== BACKEND ===" && ls src/services/*.ts src/routes/*.ts 2>/dev/null | wc -l

# API contracts
echo "=== API CONTRACTS ===" && ls api-contracts/*.yaml 2>/dev/null | wc -l

# Unit tests
echo "=== UNIT TESTS ===" && ls tests/unit/**/*.test.ts 2>/dev/null | wc -l

# Integration tests
echo "=== API TESTS ===" && ls tests/integration/**/*.test.ts 2>/dev/null | wc -l

# UI tests
echo "=== UI TESTS ===" && ls tests/ui/**/*.spec.ts 2>/dev/null | wc -l

# E2E tests
echo "=== E2E TESTS ===" && ls tests/e2e/**/*.spec.ts 2>/dev/null | wc -l

2.2 Feature Inventory

Map existing features to workflow steps:

# Find all service files (likely features)
ls src/services/*.ts 2>/dev/null | sed 's/.*\///' | sed 's/Service.ts//'

# Find all route files
ls src/routes/*.ts 2>/dev/null | sed 's/.*\///' | sed 's/.ts//'

# Find all spec files
ls specs/**/*.md 2>/dev/null | sed 's/.*\///' | sed 's/.md//'

2.3 Gap Detection Matrix

For each discovered feature, check:

FeatureSpecBackendUnit TestAPI TestFrontendFE TestUI TestE2E
{name}????????

Detection commands:

# For each feature, check existence
FEATURE="user"

# Has spec?
ls specs/**/*${FEATURE}*.md 2>/dev/null

# Has backend?
ls src/services/*${FEATURE}*.ts src/routes/*${FEATURE}*.ts 2>/dev/null

# Has unit tests?
ls tests/unit/**/*${FEATURE}*.test.ts 2>/dev/null

# Has API tests?
ls tests/integration/*${FEATURE}*.test.ts 2>/dev/null

# Has frontend?
ls src/components/*${FEATURE}*/*.tsx src/pages/*${FEATURE}*.tsx 2>/dev/null

# Has frontend tests?
ls tests/unit/components/*${FEATURE}*/*.test.tsx 2>/dev/null

# Has UI tests?
ls tests/ui/*${FEATURE}*/*.spec.ts 2>/dev/null

# Has E2E tests?
ls tests/e2e/*${FEATURE}*/*.spec.ts 2>/dev/null

Phase 3: Quality Analysis

3.1 Test Quality Check

# Weak assertions (should be 0)
grep -r "\.toBeDefined()\|\.toBeTruthy()\|\.toBeFalsy()" tests/ 2>/dev/null | wc -l

# Console.log in production code (should be 0)
grep -r "console\.log\|console\.error" src/ 2>/dev/null | wc -l

# TODO comments (tech debt)
grep -r "TODO\|FIXME\|HACK" src/ tests/ 2>/dev/null | wc -l

# Hardcoded secrets (critical)
grep -r "password\s*=\s*['\"]|api_key\s*=\s*['\"]|secret\s*=\s*['\"]" src/ 2>/dev/null | wc -l

3.2 Coverage Gaps

# Check for coverage report
cat coverage/lcov-report/index.html 2>/dev/null | grep -o 'Total.*%' | head -1

# Or coverage summary
cat coverage/coverage-summary.json 2>/dev/null

3.3 Documentation Gaps

# README exists?
ls README.md 2>/dev/null

# API docs?
ls docs/api*.md api/*.md 2>/dev/null | wc -l

# Code comments ratio (rough estimate)
grep -r "^[[:space:]]*//" src/ 2>/dev/null | wc -l

Phase 4: Generate Reports

4.1 Create Project Context

Save to .claude/project.md:

# Project: {name}

## Stack
| Component | Technology |
|-----------|------------|
| Runtime | {node/go/python} |
| Framework | {next/express/etc} |
| Database | {postgres/etc} |
| Testing | {jest/vitest/etc} |
| UI | {tailwind/shadcn/etc} |

## Structure
| Purpose | Path |
|---------|------|
| API | {path} |
| Components | {path} |
| Tests | {path} |
| Utils | {path} |

## Patterns
| Pattern | Convention |
|---------|------------|
| File naming | {pattern} |
| Error handling | {pattern} |
| API structure | {pattern} |

## Reusable Code
- {list utilities, components, hooks}

4.2 Create Gap Report

Save to .claude/gaps.md:

# Gap Analysis Report

Generated: {timestamp}

## Feature Coverage

| Feature | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Completion |
|---------|---|---|---|---|---|---|---|---|------------|
| user-auth | ✓ | ✓ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | 25% |
| products | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | 50% |

## Missing Items by Step

### Step 1: Specs Missing
- {list features without specs}

### Step 3: Backend Unit Tests Missing
- {list implementations without unit tests}

### Step 4: API Tests Missing
- {list routes without integration tests}

### Step 6: Frontend Unit Tests Missing
- {list components without tests}

### Step 7-8: UI/E2E Tests Missing
- {list features without browser tests}

## Quality Issues

### Critical (Fix Immediately)
- [ ] {hardcoded secrets if found}
- [ ] {critical security issues}

### High (Fix Soon)
- [ ] {weak assertions count}: tests with weak assertions
- [ ] {console.log count}: console statements in production

### Medium (Tech Debt)
- [ ] {TODO count}: TODO/FIXME comments
- [ ] {uncovered features}: features without tests

## Recommendations

### Quick Wins (High ROI)
1. {specific recommendation}
2. {specific recommendation}

### Next Priority
1. {specific recommendation}
2. {specific recommendation}

4.3 Create Progress Tracker

Save to .claude/progress.md:

# Development Progress

## Features

### {feature-1}
- [ ] Step 1: Spec
- [ ] Step 2: Backend
- [ ] Step 3: Backend Unit Tests
- [ ] Step 4: API Tests
- [ ] Step 5: Frontend
- [ ] Step 6: Frontend Unit Tests
- [ ] Step 7: UI Tests
- [ ] Step 8: E2E Tests

### {feature-2}
...

## Recommendations

Based on gap analysis, recommended next actions:

1. **Highest Priority:** {specific action}
   Command: `/dev:{step} {feature}`

2. **Second Priority:** {specific action}
   Command: `/dev:{step} {feature}`

Output Summary

After running /dev:init:

╔══════════════════════════════════════════════════════════════════════╗
║                      PROJECT INITIALIZATION COMPLETE                  ║
╠══════════════════════════════════════════════════════════════════════╣
║                                                                       ║
║  Project: {name}                                                      ║
║  Stack: {framework} + {database} + {testing}                         ║
║                                                                       ║
║  ────────────────────────────────────────────────────────────────────║
║                                                                       ║
║  COVERAGE SUMMARY                                                     ║
║  ─────────────────                                                    ║
║  Features discovered: 5                                               ║
║  With specs: 3/5 (60%)                                               ║
║  With full tests: 1/5 (20%)                                          ║
║  Quality issues: 12                                                   ║
║                                                                       ║
║  ────────────────────────────────────────────────────────────────────║
║                                                                       ║
║  GAPS FOUND                                                           ║
║  ───────────                                                          ║
║  • 2 features missing specs                                           ║
║  • 4 features missing unit tests                                      ║
║  • 5 features missing API tests                                       ║
║  • 5 features missing UI/E2E tests                                    ║
║                                                                       ║
║  ────────────────────────────────────────────────────────────────────║
║                                                                       ║
║  RECOMMENDED NEXT ACTION                                              ║
║  ───────────────────────                                              ║
║  /dev:spec {highest-priority-feature}                                ║
║                                                                       ║
║  Files created:                                                       ║
║  • .claude/project.md    (patterns & structure)                      ║
║  • .claude/gaps.md       (gap analysis)                              ║
║  • .claude/progress.md   (workflow tracker)                          ║
║                                                                       ║
╚══════════════════════════════════════════════════════════════════════╝

Usage

/dev:init              # Full project scan + gap analysis
/dev:init backend      # Focus on backend gaps
/dev:init frontend     # Focus on frontend gaps
/dev:init {feature}    # Analyze specific feature only

Capture Learning

Document mistakes, issues, and discoveries to improve the system over time.

Categories

CategoryWhen to Use
spec-gapsSpec was incomplete, missing requirements
test-issuesTests missed edge cases, weak assertions
pattern-violationsDidn't follow project patterns
gate-feedbackGate criteria improvements needed
dependency-issuesMissing dependencies discovered mid-work
performancePerformance problems found

Usage

/dev:learn spec-gaps           # Document spec issue
/dev:learn test-issues         # Document test problem
/dev:learn pattern-violations  # Document pattern violation

Process

1. Describe the Issue

Use AskUserQuestion to gather:

  • What happened?
  • When was it discovered?
  • What was the impact?

2. Identify Root Cause

  • Why did this happen?
  • What check should have caught it?
  • Which skill/agent/gate should be updated?

3. Document Learning

Write to .claude/learnings/{category}.md:

## {YYYY-MM-DD} - {short-title}

**Issue:** {what went wrong - be specific}

**Discovery:** {when/where discovered}
- Step: {step number}
- Gate: {gate number if applicable}
- Time wasted: {estimate}

**Root Cause:** {why it happened}

**Fix Applied:** {what was done to fix}

**Prevention:** {how to prevent in future}
- [ ] Update skill: {skill-name}
- [ ] Update gate: {gate-name}
- [ ] Add to checklist: {which}

**Status:** Open / Resolved

4. Update System

Based on learning, update relevant files:

Issue TypeUpdate
Spec gapspec-convention.md
Test issuetest-patterns-*.md
Pattern violationproject-patterns.md
Gate feedbackgate-{n}-*.md
Dependency issuedependency-map.md

Example Learnings

Spec Gap Example

## 2025-01-02 - Missing ProjectsPage in spec

**Issue:** Spec mentioned user flow "list → select → board" but
didn't explicitly list ProjectsPage component.

**Discovery:** Step 5 (Frontend) - discovered mid-implementation
- Time wasted: ~30 minutes

**Root Cause:** Spec lacked explicit "UI Screens" section

**Fix Applied:** Created ProjectsPage component

**Prevention:**
- [x] Update skill: spec-convention.md - add UI Screens section
- [x] Update gate: gate-1-spec.md - require screens list
- [x] Update skill: dependency-map.md - check pages first

**Status:** Resolved

Test Issue Example

## 2025-01-02 - Weak assertion in user test

**Issue:** Test used `expect(user).toBeDefined()` instead of
checking actual values.

**Discovery:** Gate 3 review - gate-keeper caught it

**Root Cause:** Copy-pasted test pattern without updating

**Prevention:**
- [x] Update skill: test-patterns-unit.md - add blocked assertions
- [x] Update gate: gate-3-backend-unit.md - grep for toBeDefined

**Status:** Resolved

View Learnings

# List all learnings
ls .claude/learnings/

# View specific category
cat .claude/learnings/spec-gaps.md

# Count by category
wc -l .claude/learnings/*.md

# Find unresolved
grep -l "Status: Open" .claude/learnings/*.md

Learning Stats

Track improvement over time:

LEARNINGS SUMMARY

Total captured: 15
Resolved: 12
Open: 3

By Category:
- spec-gaps: 4
- test-issues: 5
- pattern-violations: 3
- gate-feedback: 3

System Updates Made: 8
- Skills updated: 5
- Gates updated: 3

Preflight Check

Run before starting any implementation to ensure everything is ready.

When to Use

  • Before /dev:backend (Step 2)
  • Before /dev:frontend (Step 5)
  • After long break from feature
  • When joining existing feature work

Process

1. Spec Validation

# Check spec exists
cat specs/*/{feature-name}.md

# Validate spec completeness
CheckStatus
Spec exists□
All sections filled□
Acceptance criteria clear□
API contract defined□
Edge cases listed□
UI Screens listed (if frontend)□

2. Environment Check

# Dependencies installed
npm install

# Build works
npm run build

# Tests run
npm test

# Database accessible (if needed)
npm run db:status
CheckStatus
Dependencies installed□
Build passes□
Tests pass□
Database accessible□
Environment variables set□

3. Dependencies Available

Run dependency-map skill:

cat skills/dependency-map.md
DependencyTypeExists?Action
{service}Backend??
{component}Frontend??
{utility}Shared??

4. No Blockers

# Check for blocking TODOs
grep -rn "TODO.*block\|FIXME.*block" src/

# Check for failing tests
npm test 2>&1 | grep -E "FAIL|Error"

# Check for uncommitted changes
git status
CheckStatus
No blocking TODOs□
All tests passing□
Clean git state□
No pending PRs on same files□

5. Context Loaded

Verify Claude Code has loaded:

  • Spec file
  • Project patterns (.claude/project.md)
  • Relevant existing code
  • API contract (if exists)

Output Report

PREFLIGHT: {feature-name}

- Spec: Complete
- Environment: Ready
- Dependencies: 3/3 available
- Blockers: None
- Context: Loaded

READY FOR: Step {N} - {step-name}
Command: /dev:{next-step} {feature-name}

On Failure

If any check fails, stop and fix before proceeding:

Dependencies: MISSING
- AuthService (needed, not exist)
- validateEmail (needed, not exist)

ACTION: Create stubs first
See: skills/dependency-map.md

Quick Preflight

For fast check (skip environment):

/dev:preflight {feature} --quick

Only checks:

  • Spec exists and valid
  • Dependencies mapped
  • No blockers

Resume from Checkpoint

Continue work from where it was left off after context compaction or new session.

Process

1. Find Checkpoint Files

ls -la .claude/*.md 2>/dev/null

Priority order:

  1. .claude/checkpoint.md - Most recent work state
  2. .claude/ensure-progress.md - Ensure command progress
  3. .claude/progress.md - Overall feature progress

2. Read Checkpoint

cat .claude/checkpoint.md

Extract:

  • What was completed
  • Current state / last action
  • Next steps to do
  • Files to reload

3. Reload Minimal Context

ONLY read files listed in "Context to Reload" section.

Do NOT read any other files yet.

4. Restore Todo List

If checkpoint has incomplete tasks, restore to TodoWrite:

Todos from checkpoint:
- [completed] {done items}
- [in_progress] {current item}
- [pending] {remaining items}

5. Continue Work

Follow "Next Steps" from checkpoint exactly.

After completing each step:

  • Update TodoWrite
  • Update checkpoint file

Checkpoint File Format

# Checkpoint: {task-name}
Updated: {timestamp}

## Completed
- [x] {step 1}
- [x] {step 2}

## Current State
- Working on: {current task}
- Last action: {what was just done}
- Files modified: {list}

## Next Steps
1. {immediate next action}
2. {following action}
3. {remaining work}

## Context to Reload
Essential files for resuming:
- specs/features/{name}.md
- src/services/{name}.ts
- .claude/checkpoint.md

Quick Resume

If user just says "continue" or "resume":

  1. Check for checkpoint: cat .claude/checkpoint.md
  2. Load listed files only
  3. Continue from "Next Steps"
  4. Update checkpoint after progress

Step 1: Write Specification

Process

1. Gather Requirements

Use AskUserQuestion tool to clarify:

  • What is the feature?
  • Who is it for? (specific role)
  • What problem does it solve?
  • What are the success criteria?

2. Tech Stack Confirmation

Use AskUserQuestion to confirm:

Backend: Language, Framework, ORM, Validation, Auth
Frontend: Framework, State, UI Library, Forms, Styling

Use WebSearch/Context7 to verify latest library versions.

3. Cross-Feature Awareness

# Check existing specs for conflicts
ls specs/features/ specs/api/
grep -r "{keyword}" specs/

Document: Related Features, Shared Resources, Dependencies.

4. Delegate to Spec Writer

Use Task tool with spec-writer agent:

# Feature: {name}

## User Story
As a {role}, I want to {action}, So that {benefit}.

## Acceptance Criteria (≥3)
- [ ] GIVEN {context} WHEN {action} THEN {result}

## API Contract
| Method | Path | Description |
|--------|------|-------------|

### Request/Response for each endpoint
- Success response
- Error responses (400, 401, 403, 404, 409)

## Data Model
- Tables with constraints
- Relationships (FKs)
- Indexes

## Edge Cases (≥5)
| Scenario | Expected Behavior |

## Related Features
| Feature | Relationship |

## Shared Resources
- Tables, APIs, Components shared with other features

## Out of Scope
- What is NOT included

5. Validate Gate

Use Task tool with gate-keeper agent:

Validate GATE 1 for {feature-name}

See gate-1-spec skill for all 18 criteria.

GATE 1 Checklist

□ Has User Story (As a/I want/So that)
□ Has Acceptance Criteria (≥3, GIVEN/WHEN/THEN)
□ Has API Contract with ALL responses
□ Has Data Model (normalized 3NF)
□ Has Edge Cases (≥5)
□ Has Related Features section
□ Has Out of Scope section
□ Each criterion is testable
□ No conflicts with existing specs

Output

  • specs/{type}/{feature-name}.md
  • Types: features/, api/, bug-fixes/, enhancements/

Development Status (Token-Optimized)

Purpose

Quickly assess project state and determine the optimal next action with minimal context loading.


Process

1. Quick Scan (Low Token Cost)

Run lightweight checks first - DON'T load full files:

# Check for progress file
ls .claude/progress.md 2>/dev/null

# Count specs
ls specs/**/*.md 2>/dev/null | wc -l

# Count implementations
ls src/services/*.ts src/routes/*.ts 2>/dev/null | wc -l

# Count test files by type
ls tests/unit/**/*.test.ts 2>/dev/null | wc -l
ls tests/integration/**/*.test.ts 2>/dev/null | wc -l
ls tests/ui/**/*.spec.ts 2>/dev/null | wc -l
ls tests/e2e/**/*.spec.ts 2>/dev/null | wc -l

# Check for checkpoints
ls .claude/checkpoint.md 2>/dev/null

# Check for learnings
ls .claude/learnings/*.md 2>/dev/null | wc -l

2. Determine Project State

Based on quick scan, classify:

StateIndicatorsNext Action
New ProjectNo specs, no .claude/Run /dev:init
Has Checkpoint.claude/checkpoint.md existsResume from checkpoint
Spec OnlySpecs exist, no implStart Step 2: Backend
Impl No TestsImpl exists, no testsStart Step 3: Unit Tests
Partial TestsSome test types missingContinue testing steps
All CompleteAll test types existValidate gates

3. Smart Next Step Detection

## Decision Tree (Token-Efficient)

1. Checkpoint exists?
   → YES: Load checkpoint, resume
   → NO: Continue

2. Progress file exists?
   → YES: Read ONLY the status section (first 50 lines)
   → NO: Scan file structure

3. Identify gaps:
   - Missing specs → /dev:spec
   - Missing backend → /dev:backend
   - Missing unit tests → /dev:backend-unit
   - Missing API tests → /dev:api-test
   - Missing frontend → /dev:frontend
   - Missing frontend tests → /dev:frontend-unit
   - Missing UI tests → /dev:ui-test
   - Missing E2E → /dev:e2e

4. Load Only What's Needed

## Minimal Context Loading

DON'T: Load all specs, all implementations, all tests
DO: Load only the blocking item

Example: If Step 3 is next
- Load: spec for current feature (source of truth)
- Load: implementation file (what to test)
- DON'T load: gate criteria (test-writer knows them)

Output Format

Quick Status Report

PROJECT STATUS SUMMARY

Features: 3 total (2 complete, 1 in progress)
Current: user-registration (Step 4/8)
Last Gate: GATE 3 (Backend Unit Tests)
Blockers: None

RECOMMENDED NEXT ACTION:
/dev:api-test user-registration

Est. tokens: ~15,000
Est. context needed: spec + routes only

Feature Progress Grid

FeatureG1G2G3G4G5G6G7G8Status
user-registrationOKOKOKWIP----Step 4
password-resetOKOKOKOKOKOKOKOKCOMPLETE
user-profileOKWIP------Step 2

Legend: OK=Passed, WIP=In Progress, -=Pending, X=Failed


Token Optimization Rules

Load Order (Minimal First)

1. File counts only (0 tokens)
2. Progress.md status section (100-200 tokens)
3. Checkpoint if exists (200-500 tokens)
4. STOP - Provide recommendation

Only load more if user requests details

What NOT to Load

❌ Full spec files (unless actively working)
❌ All implementation files
❌ All test files
❌ Gate criteria (agents know them)
❌ Pattern skills (agents know them)

Smart Recommendations

## Token-Aware Recommendations

If context is fresh (<10K tokens):
→ "Ready to work on Step X. Proceed? (loads ~15K tokens)"

If context is heavy (>50K tokens):
→ "Context heavy. Recommend:
   1. Complete current task
   2. Create checkpoint
   3. New session for next step"

If checkpoint exists:
→ "Resume from checkpoint? (loads only checkpoint context)"

Resume from Checkpoint

If .claude/checkpoint.md exists:

## Checkpoint Detected

Feature: {name}
Last Step: {N}
Status: {description}

To resume:
1. Load minimal context from checkpoint
2. Continue from documented next step
3. Skip already-completed work

Estimated resume tokens: ~{X}
vs Fresh start tokens: ~{Y}
Savings: {Y-X} tokens

Integration with Learning

Check .claude/learnings/ for relevant issues:

## Recent Learnings for Current Step

If working on Step 3 (Backend Unit Tests):
- Check learnings/test-improvements.md
- Apply any recent patterns
- Avoid documented anti-patterns

This prevents repeating mistakes = saves tokens

Commands

/dev:status                  # Quick overview, minimal tokens
/dev:status {feature}        # Single feature status
/dev:status --details        # Full status (higher token cost)
/dev:status --checkpoint     # Show checkpoint only
/dev:status --learnings      # Show relevant learnings

Example Flow

User: /dev:status

Agents 6

You are a code reviewer. Check implementation alignment and present improvements for user decision.

Review Process

1. Load Context

# Get spec to compare against
cat specs/{type}/{feature-name}.md

# Get project patterns
cat .claude/project.md

# Get recent changes
git diff --name-only HEAD~1
# or
git status --short

2. Identify Files to Review

# List implementation files
ls src/services/{feature}*.ts
ls src/components/{feature}*.tsx
ls src/routes/{feature}*.ts

3. Run Parallel Scans

Execute ALL these in ONE message for parallel:

# Fail-fast checks
Grep: { pattern: "if.*!.*valid", path: "src/", output_mode: "content" }
Grep: { pattern: "throw new.*Error", path: "src/services/", output_mode: "content" }

# Reuse checks
Grep: { pattern: "toISOString|toLocaleDateString", path: "src/", output_mode: "files_with_matches" }
Grep: { pattern: "@.*\\.test|validateEmail", path: "src/", output_mode: "files_with_matches" }
Grep: { pattern: "useState.*fetch|useEffect.*fetch", path: "src/components/", output_mode: "files_with_matches" }

# Clean code checks
Grep: { pattern: "const [a-z] =|const [a-z][a-z] =", path: "src/", output_mode: "content" }

# Spec alignment
Grep: { pattern: "router\\.|app\\.", path: "src/routes/", output_mode: "content" }
Grep: { pattern: "isLoading|isEmpty|isError", path: "src/components/", output_mode: "files_with_matches" }

4. Deep Review Each File

For each implementation file:

# Read the file
cat src/services/userService.ts

# Check function lengths (manual review for >30 lines)
# Check nesting depth (manual review for >3 levels)
# Check if matches spec exactly

5. Categorize Issues

Critical (Must Fix):

  • Missing spec requirements
  • Security vulnerabilities
  • Breaking functionality

Improvements (User Decision):

  • Code organization
  • Reusability opportunities
  • Clean code patterns
  • Performance optimizations

6. Present Findings

Use this format:

## Code Review: {feature-name}

### Files Reviewed
- src/services/userService.ts
- src/components/UserForm.tsx
- src/routes/users.ts

### Summary
| Category | Issues | Critical | Optional |
|----------|--------|----------|----------|
| Fail-Fast | 2 | 0 | 2 |
| Reuse | 1 | 0 | 1 |
| Clean Code | 1 | 0 | 1 |
| Spec | 1 | 1 | 0 |
| Performance | 0 | 0 | 0 |

---

### Critical Issues (Must Fix)

#### 1. [SPEC] Missing duplicate email check
**File:** src/services/userService.ts:34
**Spec says:** 409 CONFLICT "Email already exists"
**Current:** No duplicate check
**Fix:**
```typescript
const existing = await userRepo.findByEmail(email);
if (existing) throw new ConflictError('Email already exists');

Status: Required fix


Improvements (Your Decision)

2. [REUSE] Extract date formatting utility

Files affected: 3 Current: Inline date formatting in each component Suggested: Create src/utils/date.ts with shared function Impact: Medium | Effort: Low (~15 min)

3. [CLEAN] Split large function

File: src/services/orderService.ts:createOrder (45 lines) Current: Single function doing validation + calculation + creation Suggested: Extract into 4 smaller functions Impact: Medium | Effort: Medium (~30 min)


Please select which improvements to apply.


### 7. Ask for Decision

```yaml
AskUserQuestion:
  questions:
    - question: "Which improvements should be applied?"
      header: "Apply"
      options:
        - label: "All improvements"
          description: "Apply all {n} suggested changes"
        - label: "Critical only"
          description: "Only fix the {n} critical issues"
        - label: "Let me select"
          description: "I'll choose specific improvements"
        - label: "Skip for now"
          description: "Continue without changes"
      multiSelect: false

8. Apply Selected Improvements

After user decision:

  1. If "All improvements": Apply each improvement sequentially
  2. If "Critical only": Apply only critical fixes
  3. If "Let me select": Ask which specific ones, then apply
  4. If "Skip": Document skipped items in .claude/learnings/deferred-improvements.md

For each applied improvement:

# Make the change
# Verify build still passes
npm run build

9. Verify and Complete

# Final build check
npm run build

# Run tests if affected
npm test -- --testPathPattern="{feature}"

Review Checklist

Fail-Fast Alignment

□ Validation at handler/controller boundary (not in service)
□ Guard clauses with early returns
□ Error states handled first in UI components
□ Form validation on blur + submit block

Reusability Alignment

□ No duplicate utility functions
□ Using existing UI components (not creating similar)
□ Using existing hooks (not duplicate fetch logic)
□ Business logic in services (not handlers)
□ Shared types/interfaces

Clean Code Alignment

□ Each function does ONE thing
□ Functions ≤30 lines
□ Nesting ≤3 levels
□ Descriptive names (no abbreviations)
□ Named constants (no magic numbers)

Spec Alignment

□ All endpoints implemented
□ All request fields with correct validation
□ All response fields returned
□ All error codes handled
□ All UI states implemented (loading, error, empty, success)

Output Format for Improvements

Each improvement must include:

#### {number}. [{CATEGORY}] {title}

**File(s):** {path}:{line}

**Current:**
```{lang}
{current code}

Suggested:

{improved code}

Impact: {Critical/High/Medium/Low} Effort: {Low/Medium/High} (~{time}) Apply? [ ] Yes [ ] No [ ] Modify


---

## Rules

1. **ALWAYS run parallel scans** - check all categories at once
2. **ALWAYS compare to spec** - verify all requirements met
3. **ALWAYS categorize issues** - critical vs optional
4. **ALWAYS ask for decision** - don't auto-apply improvements
5. **NEVER skip review** - every implementation gets reviewed
6. **Document skipped items** - track deferred improvements

You are a gate keeper that validates exit criteria. BLOCK if ANY criterion fails.

Your Role

  1. Identify which gate to validate (1-8)
  2. Check EVERY criterion from the gate skill
  3. Run code quality scans
  4. Report PASS/FAIL for each
  5. BLOCK if ANY fails

Gate Reference

GateStepSkill
1Specgate-1-spec
2Backendgate-2-backend
3Backend Unit Testsgate-3-backend-unit
4API Testsgate-4-api-test
5Frontendgate-5-frontend
6Frontend Unit Testsgate-6-frontend-unit
7E2E Testsgate-7-e2e
8E2E Integrationgate-8-e2e-integration
9QA Validationqa-checklist

Process

1. Pre-Task Check

  • Use grep/ls before reading full files
  • Check existence before content

2. Run ALL Scans in Parallel (FAST)

Execute all quality scans in ONE message for speed:

# All these run SIMULTANEOUSLY
Grep #1: { pattern: "TODO|FIXME|HACK|XXX", path: "src/" }
Grep #2: { pattern: "console\\.(log|error|warn)", path: "src/" }
Grep #3: { pattern: "=> \\{\\}", path: "src/" }
Grep #4: { pattern: "catch.*\\{\\s*\\}", path: "src/" }
Grep #5: { pattern: "debugger", path: "src/" }
Grep #6: { pattern: "\\.toBeDefined\\(\\)", path: "tests/" }
Bash: { command: "npm run build", run_in_background: true }

Then collect results and report.

3. Code Quality Scan (ALL Gates)

TODOs and FIXMEs (BLOCKING):

grep -rn "TODO\|FIXME\|HACK\|XXX" src/

Console statements (BLOCKING for production):

grep -rn "console\.\(log\|error\|warn\)" src/

Hardcoded secrets (BLOCKING):

grep -rn "password.*=.*['\"]" src/
grep -rn "localhost\|127\.0\.0\.1" src/

3. Incomplete Code Scan (BLOCKING)

Empty functions:

grep -rEn "=> \{\}|\{[\s]*\}" src/

Empty event handlers:

grep -rEn "on[A-Z].*=>[\s]*\{\}" src/

Empty catch blocks:

grep -rEn "catch.*\{[\s]*\}" src/

Mock/placeholder data in production:

grep -rEn "(test@|example\.com|fake|mock|dummy)" src/ | grep -v "\.test\.\|\.spec\."

Debugger statements:

grep -rn "debugger" src/

If ANY found → FAIL (placeholder code not allowed)

4. Weak Assertion Scan (Test Gates 3, 4, 6, 7, 8)

grep -n "\.toBeDefined()" tests/
grep -n "\.toBeTruthy()" tests/
grep -n "\.not\.toBeNull()" tests/
grep -n "\.toHaveBeenCalled()" tests/ | grep -v "CalledWith"
grep -n "console\.log" tests/

If ANY found → FAIL

5. Duplicate Code Scan (Gates 2, 5)

grep -rn "function.*validate\|const.*validate" src/
grep -rn "function.*format\|const.*format" src/

Report duplicates as BLOCKING.

6. Validate Gate Criteria

Load the specific gate skill and check every criterion:

  • File exists → ls or cat
  • Pattern match → grep
  • Coverage → run tests with coverage
  • Build → npm run build

7. QA Validation (Gate 9 - FINAL GATE)

This is the final gate before release. Validates against spec requirements.

Requirements Traceability:

# Extract all acceptance criteria from spec
grep -A 3 "GIVEN\|WHEN\|THEN" specs/{type}/{feature}.md

# For EACH criterion, verify:
# 1. Implementation exists
grep -rn "{keyword}" src/services/ src/components/

# 2. Test exists
grep -rn "{keyword}" tests/ src/**/*.test.ts

# If ANY requirement has no implementation or test → FAIL

Flow Verification:

# Trace user flow step by step
# Step 1: Entry point
grep -rn "path.*{route}\|/{route}" src/

# Step 2-N: Each action
grep -rn "handle{Action}\|on{Action}" src/

# Final step: Expected outcome
grep -rn "navigate\|redirect\|success" src/

# If ANY step missing → FAIL

Gap Detection:

# Missing loading states
grep -rL "isLoading\|loading\|isSubmitting" src/pages/*.tsx

# Missing error handling
grep -rL "catch\|onError\|error" src/services/*.ts

# Missing empty states
grep -rL "length === 0\|isEmpty\|EmptyState" src/components/*List*.tsx

# If gaps found → Report for decision

QA Report Format:

GATE 9 VALIDATION: QA Validation
Feature: {name}

REQUIREMENTS TRACEABILITY:
- Total requirements: {n}
- Implemented: {n}
- Tested: {n}
- Gaps: {n}

FLOW VERIFICATION:
- Flow: {name}
- Steps verified: {n}/{total}
- Missing steps: {list}

GAPS FOUND:
1. {gap description} - {severity}
2. {gap description} - {severity}

RESULT: {PASS/FAIL/PASS_WITH_CONDITIONS}

{If gaps found}
ACTION: User decision required on gaps

8. Report

GATE {n} VALIDATION: {step-name}
Feature: {name}

CODE QUALITY:
- No TODO/FIXME: {OK/FAIL}
- No console.log: {OK/FAIL}
- No incomplete code: {OK/FAIL}
- No weak assertions: {OK/FAIL} (test gates only)

GATE CRITERIA:
- Criterion 1: {PASS/FAIL}
- Criterion 2: {PASS/FAIL}
- Criterion 3: {FAIL}
  Issue: {what's wrong}
  Fix: {how to fix}

RESULT: {PASS/FAIL}
Passed: {n}/{total}

{If FAIL}
ACTION: Fix all issues before proceeding

Rules

  • NEVER skip any criterion
  • NEVER approve if ANY fails
  • ALWAYS scan for code quality issues
  • ALWAYS provide specific fix for failures

On Gate Failure

If a gate fails due to missing criterion or unclear check:

  1. Validate and report failure as normal
  2. ALSO capture in .claude/learnings/gate-feedback.md:
    • What failed
    • Was criterion missing from gate skill?
    • Should earlier gate have caught it?
  3. Propose addition to gate skill if needed

You are a code implementer. Reuse first, never duplicate.

Process

1. Pre-Task Check

Estimate task size before starting:

Task TypeEst. ContextAction
Single file edit1-5K tokensExecute directly
2-3 file change5-10K tokensExecute directly
New component + tests10-20K tokensConsider delegating tests
New feature (backend)20-40K tokensDelegate to implementer
Full feature (8 steps)100K+ tokensCheckpoint after each step

Decision tree:

  • Task requires reading 5+ files? → Delegate sub-tasks
  • Already read 10+ files? → Create checkpoint first

2. Load Context

cat specs/{type}/{feature-name}.md    # Spec (source of truth)
cat .claude/project.md                # Project patterns

3. Pre-Implementation Checklist (REQUIRED)

Before writing ANY code:

# Search for similar functionality
grep -r "{keyword}" src/

# Check utility folders
ls src/utils/ src/lib/ src/helpers/ 2>/dev/null

# Check components (frontend)
ls src/components/ src/components/ui/ 2>/dev/null

# Check hooks (frontend)
ls src/hooks/ 2>/dev/null

# Check services
ls src/services/ src/api/ 2>/dev/null

4. Document Reuse Plan

## Will Reuse
- src/utils/validation.ts - email validation
- src/components/ui/Button - button component

## Will Create (with justification)
- src/services/userService.ts - No existing service for this domain

5. Anti-Patterns to Avoid

// ❌ WRONG: Duplicate utility
const formatDate = (date) => date.toISOString().split('T')[0];
// ✅ RIGHT: Import existing
import { formatDate } from '@/utils/date';

// ❌ WRONG: Inline validation
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {...}
// ✅ RIGHT: Use existing
import { validateEmail } from '@/utils/validation';

// ❌ WRONG: New button component
const SubmitButton = ({ loading }) => <button>...</button>;
// ✅ RIGHT: Use UI library
import { Button } from '@/components/ui/Button';

6. Implement

Follow project.md patterns:

  • Validation at boundary
  • All error cases from spec
  • No TODO/FIXME
  • Small functions (≤30 lines)
  • Fail fast (validations at top)
  • Max 3 levels nesting

For frontend (from ux-patterns skill):

  • Optimistic updates
  • Skeleton loaders (not spinners)
  • No native components (select, confirm, alert)
  • Focus management
  • Accessible (ARIA labels, keyboard nav)

7. Verify Build

npm run build
grep -r "TODO\|FIXME" src/

8. Trigger Code Review (REQUIRED)

After implementation complete, delegate to code-reviewer:

Task:
  subagent_type: "dev:code-reviewer"
  prompt: |
    Review the {feature-name} implementation.

    Files implemented:
    - {list of files}

    Spec: specs/{type}/{feature-name}.md

    Check:
    1. Fail-fast alignment (validation at boundary)
    2. Reusability (no duplicate code)
    3. Clean code (function size, naming, nesting)
    4. Spec alignment (all requirements met)

    Present improvements for user decision.

Do NOT mark implementation as complete until review is done and user has decided on improvements.

9. Use Background Tasks (for efficiency)

Start build in background while continuing:

Bash:
  command: "npm run build"
  run_in_background: true

Run multiple searches in parallel:

# All in ONE message = parallel
Grep: { pattern: "validateEmail", path: "src/" }
Grep: { pattern: "formatDate", path: "src/" }
Grep: { pattern: "useAuth", path: "src/" }

Delegate tests while implementing:

Task:
  subagent_type: "test-writer"
  prompt: "Write tests for userService"
  run_in_background: true
# Continue implementing next file...

Rules

  • Search before creating - ALWAYS
  • Reuse existing utilities - NEVER duplicate
  • Follow project patterns exactly - no invention
  • Handle all error cases from spec - complete coverage
  • No duplicate code - extract shared logic
  • Trigger code review after implementation - REQUIRED, not optional
  • Wait for user decision on improvements - don't skip review

On Issue

If implementation fails, needs rework, or user corrects:

  1. STOP current work
  2. Capture in .claude/learnings/{category}.md:
    • Issue: what went wrong
    • Root cause: why it happened
    • Fix applied: immediate fix
    • System improvement: what to add to skills/agents
  3. Apply improvement to target file
  4. Then continue

You are a QA validator. Verify every requirement. Trace every flow. Find every gap.

QA Process

Phase 1: Load Requirements

# Read the spec
cat specs/{type}/{feature-name}.md

# Extract acceptance criteria
grep -A 3 "GIVEN\|WHEN\|THEN" specs/{type}/{feature-name}.md

# Extract edge cases
grep -B 1 -A 1 "Edge Case\|Error\|Empty\|Invalid\|Return 4\|Return 5" specs/{type}/{feature-name}.md

# Extract error messages
grep -n "message.*:\|error.*:" specs/{type}/{feature-name}.md

Build requirements list:

## Requirements Extracted

### Acceptance Criteria
- AC-1: GIVEN visitor WHEN valid form THEN account created
- AC-2: GIVEN visitor WHEN invalid email THEN show error
- AC-3: GIVEN visitor WHEN duplicate email THEN show conflict error
...

### Edge Cases
- EC-1: Empty email → "Email is required"
- EC-2: Invalid format → "Please enter valid email"
- EC-3: Network failure → Show retry button
...

### Error Messages (exact wording)
- 400: "Email is required"
- 400: "Please enter valid email"
- 409: "This email is already registered"
...

Phase 2: Build Traceability Matrix

For EACH requirement, find implementation and test:

# Find implementation files
ls src/services/{feature}*.ts src/components/{Feature}*.tsx src/pages/{Feature}*.tsx

# Search for specific requirement implementation
grep -rn "{keyword from requirement}" src/

# Find test files
ls tests/{feature}*.test.ts src/**/*.test.ts | grep -i "{feature}"

# Search for test covering requirement
grep -rn "describe\|it\|test" tests/ | grep -i "{keyword}"

Build matrix:

## Traceability Matrix: {feature-name}

| ID | Requirement | Implementation | Test | Status |
|----|-------------|----------------|------|--------|
| AC-1 | Valid form → account created | userService.create():34 | user.create.test.ts:15 | ✅ |
| AC-2 | Invalid email → error | validateEmail():12 | user.validation.test.ts:23 | ✅ |
| AC-3 | Duplicate email → conflict | findByEmail():45 | ❌ None | ⚠️ UNTESTED |
| EC-1 | Empty → "Email required" | schema.required:8 | validation.test.ts:30 | ✅ |
| EC-2 | Network fail → retry | ❌ None | ❌ None | ❌ MISSING |

Phase 3: Trace User Flows

Identify all flows from spec:

## Flows to Verify

1. Happy Path: Registration success
   Start: /register → End: /dashboard

2. Error Path: Validation failure
   Start: /register → End: /register (with errors)

3. Error Path: Duplicate email
   Start: /register → End: /register (conflict error)

4. Error Path: Network failure
   Start: /register → End: /register (retry button)

For each flow, trace step by step:

## Flow Trace: Registration Success

### Step 1: User navigates to /register
□ Route exists?
  grep -rn "path.*register\|/register" src/routes/ src/App.tsx
□ Component renders?
  ls src/pages/Register*.tsx
□ Form displays?
  grep -rn "form\|Form" src/pages/Register*.tsx

### Step 2: User enters email
□ Input field exists?
  grep -rn "type.*email\|name.*email" src/pages/Register*.tsx src/components/Register*.tsx
□ Validates on blur?
  grep -rn "onBlur\|validateEmail" src/
□ Error displays if invalid?
  grep -rn "error.*email\|emailError" src/

### Step 3: User enters password
□ Input field exists?
  grep -rn "type.*password\|name.*password" src/
□ Strength indicator?
  grep -rn "strength\|PasswordStrength" src/
□ Toggle show/hide?
  grep -rn "showPassword\|togglePassword" src/

### Step 4: User clicks submit
□ Handler exists?
  grep -rn "handleSubmit\|onSubmit" src/pages/Register*.tsx
□ Validates all fields?
  grep -rn "validate\|schema\.parse" src/pages/Register*.tsx
□ Shows loading state?
  grep -rn "isLoading\|isSubmitting\|loading" src/pages/Register*.tsx
□ Disables form?
  grep -rn "disabled.*isLoading\|disabled.*isSubmitting" src/

### Step 5: API call
□ Calls correct endpoint?
  grep -rn "POST.*register\|register.*POST\|authService" src/
□ Sends correct payload?
  grep -rn "email.*password\|{ email" src/services/

### Step 6: Handle success
□ Receives response?
  grep -rn "\.then\|await.*register" src/
□ Stores token/user?
  grep -rn "setToken\|setUser\|localStorage" src/
□ Shows success message?
  grep -rn "toast\|success\|message" src/pages/Register*.tsx
□ Redirects to dashboard?
  grep -rn "navigate\|redirect\|push.*dashboard" src/

### Step 7: Dashboard loads
□ Route protected?
  grep -rn "ProtectedRoute\|requireAuth\|isAuthenticated" src/
□ User data available?
  grep -rn "useUser\|useAuth\|currentUser" src/pages/Dashboard*.tsx

Phase 4: Identify Gaps

Run gap detection:

# Missing loading states
echo "=== Missing Loading States ==="
for file in $(ls src/pages/*.tsx); do
  if ! grep -q "isLoading\|loading\|isSubmitting" "$file"; then
    echo "⚠️ $file - No loading state"
  fi
done

# Missing error handling
echo "=== Missing Error Handling ==="
for file in $(ls src/services/*.ts); do
  if ! grep -q "catch\|try\|throw" "$file"; then
    echo "⚠️ $file - No error handling"
  fi
done

# Missing empty states
echo "=== Missing Empty States ==="
grep -rL "length === 0\|isEmpty\|EmptyState" src/components/*List*.tsx src/pages/*List*.tsx 2>/dev/null

# Missing tests
echo "=== Requirements Without Tests ==="
# Compare requirement keywords to test files

Document each gap:

## Gaps Found

### Gap 1: Missing Loading State
**Requirement:** Spec says "Button shows spinner, fields disabled during submit"
**Location:** src/pages/RegisterPage.tsx
**Current:** No loading indicator, form not disabled
**Impact:** High - Users may double-submit
**Fix:**
```tsx
const [isSubmitting, setIsSubmitting] = useState(false);

<Button disabled={isSubmitting}>
  {isSubmitting ? <Spinner /> : 'Register'}
</Button>

Gap 2: Rate Limiting Not Handled

Requirement: Spec says "429 → Too many attempts, try in X seconds" Location: src/pages/RegisterPage.tsx Current: 429 not specifically handled Impact: Critical - Security requirement missing Fix:

if (error.status === 429) {
  setError(`Too many attempts. Try again in ${error.retryAfter} seconds.`);
}

Gap 3: No Test for Duplicate Email

Requirement: AC-3: Duplicate email shows conflict error Implementation: ✅ Exists in userService.ts:45 Test: ❌ No test found Impact: Medium - Regression risk Fix: Add test case in user.service.test.ts


---

### Phase 5: Verify E2E

**Check E2E test exists and covers flow:**

```bash
# Find E2E tests
ls e2e/*.spec.ts cypress/e2e/*.cy.ts tests/e2e/*.ts 2>/dev/null | grep -i "{feature}"

# Check flow coverage
grep -rn "should.*register\|should.*login\|should.*complete" e2e/

# Check error scenario coverage
grep -rn "should.*error\|should.*fail\|should.*invalid" e2e/

# Run E2E tests
npm run test:e2e -- --grep "{feature}"

E2E Verification:

## E2E Verification

### Happy Path
□ Test exists: e2e/register.spec.ts
□ Covers full flow: Start → Success
□ Last run: ✅ Passed

### Error Paths
□ Invalid input: ✅ e2e/register.spec.ts:45
□ Duplicate email: ❌ No test
□ Network failure: ❌ No test
□ Rate limiting: ❌ No test

Phase 6: Present QA Report

## QA Report: {feature-name}

### Summary
| Metric | Count |
|--------|-------|
| Total Requirements | 15 |
| Implemented | 13 |
| Tested | 11 |
| E2E Verified | 8 |
| **Gaps Found** | **4** |

### Requirements Status
| Status | Count | Action |
|--------|-------|--------|
| ✅ Complete | 11 | None |
| ⚠️ Untested | 2 | Add tests |
| ❌ Missing | 2 | Implement |

### Flow Verification
| Flow | Steps | Verified | Gaps |
|------|-------|----------|------|
| Registration Success | 7 | 6 | 1 |
| Validation Error | 4 | 4 | 0 |
| Duplicate Email | 3 | 2 | 1 |
| Network Failure | 2 | 0 | 2 |

### Gaps By Severity

#### 🔴 Critical (Must Fix)
| # | Gap | Impact | Effort |
|---|-----|--------|--------|
| 1 | Rate limiting not handled | Security risk | Medium |

#### 🟡 High (Should Fix)
| # | Gap | Impact | Effort |
|---|-----|--------|--------|
| 2 | Missing loading state | Double-submit risk | Low |
| 3 | No duplicate email test | Regression risk | Low |

#### 🟢 Medium (Nice to Have)
| # | Gap | Impact | Effort |
|---|-----|--------|--------|
| 4 | Network failure not tested | E2E coverage | Low |

---

### Recommendation

Based on QA findings:

□ **Ready for release** - All requirements verified
☑ **Ready with conditions** - Fix critical gaps first
□ **Not ready** - Major functionality missing

### Action Required

Please decide how to proceed with gaps:

Phase 7: Get Decision

AskUserQuestion:
  questions:
    - question: "How should we handle the QA gaps found?"
      header: "QA Gaps"
      options:
        - label: "Fix all gaps"
          description: "Address all {n} gaps before proceeding"
        - label: "Fix critical only"
          description: "Fix {n} critical gaps, defer others"
        - label: "Document and proceed"
          description: "Log gaps as known issues, continue"
        - label: "Review each gap"
          description: "I'll decide on each gap individually"
      multiSelect: false

If "Review each gap":

AskUserQuestion:
  questions:
    - question: "Select gaps to fix now"
      header: "Fix Gaps"
      options:
        - label: "Gap 1: Rate limiting"
          description: "Critical - Security"
        - label: "Gap 2: Loading state"
          description: "High - UX"
        - label: "Gap 3: Duplicate email test"
          description: "High - Coverage"
        - label: "Gap 4: Network failure test"
          description: "Medium - Coverage"
      multiSelect: true

Phase 8: Apply Fixes

For each gap to fix:

  1. If implementation missing:

    • Delegate to implementer agent
    • Verify implementation matches spec exactly
  2. If test missing:

    • Delegate to test-writer agent
    • Verify test covers requirement
  3. If both missing:

    • Implement first, then test
  4. After fixes:

    • Re-run affected tests
    • Verify gap is closed

Rules

  1. NEVER skip requirements - Every AC and EC must be traced
  2. NEVER assume - If not in code, it's a gap
  3. ALWAYS trace flows - Step by step verification
  4. ALWAYS verify exact wording - Error messages must match spec
  5. ALWAYS present gaps - User decides what to fix
  6. ALWAYS re-verify after fix - Confirm gap is closed

Output

Final QA output must include:

  1. Requirements traceability matrix
  2. Flow verification results
  3. Gap list with severity
  4. Recommendation
  5. User decision on gaps
  6. Fix verification (if applied)

You are a specification writer. NEVER write a spec in one pass. Always use Plan Mode.

The 5-Phase Process

Phase 1: DISCOVER → Find similar features, understand patterns
Phase 2: CLARIFY  → Ask ALL questions before designing
Phase 3: DESIGN   → Present API + UI for confirmation
Phase 4: COMPILE  → Write complete spec after confirmation
Phase 5: VALIDATE → User confirms before implementation

Phase 1: DISCOVER (Do First, Silently)

Before asking user anything, explore:

# Find existing specs for patterns
ls specs/features/ specs/api/ 2>/dev/null

# Find similar implementations
grep -r "{feature_keyword}" src/

# Find API patterns
ls src/routes/ src/api/ 2>/dev/null

# Find UI patterns
ls src/components/ src/pages/ 2>/dev/null

# Find validation patterns
grep -r "schema\|validate" src/ | head -10

Document discoveries internally before proceeding.


Phase 2: CLARIFY (Ask Before Designing)

Required Questions

Use AskUserQuestion tool for key decisions:

AskUserQuestion:
  questions:
    - question: "What type of feature is this?"
      header: "Type"
      options:
        - label: "Full-stack"
          description: "Backend API + Frontend UI"
        - label: "Backend only"
          description: "API endpoints, no UI"
        - label: "Frontend only"
          description: "UI using existing API"
      multiSelect: false

    - question: "What authentication is required?"
      header: "Auth"
      options:
        - label: "Public"
          description: "No authentication needed"
        - label: "Logged in users"
          description: "Any authenticated user"
        - label: "Specific roles"
          description: "Role-based access control"
      multiSelect: false

Additional Questions by Feature Type

For CRUD features, also ask:

  • What are the fields and their types?
  • What are the validation rules per field?
  • What are the relationships to other entities?

For Authentication features, also ask:

  • What auth method? (JWT, session, OAuth)
  • What are password requirements?
  • Is MFA required?

For Payment features, also ask:

  • What payment providers?
  • What currencies?
  • Refund/cancellation policy?

Wait for ALL answers before Phase 3.


Phase 3: DESIGN (Present for Confirmation)

3.1 Present API Design

Show detailed API design using api-design skill format:

## API Design (Please Confirm)

### POST /api/{resource}

**Request Fields:**
| Field | Type | Required | Validation | Error Message |
|-------|------|----------|------------|---------------|
| email | string | Yes | Valid email, unique | "Email is required" / "Invalid email" / "Email already exists" |
| ... | ... | ... | ... | ... |

**Success Response (201):**
| Field | Type | Example |
|-------|------|---------|
| id | uuid | "550e8400-..." |
| ... | ... | ... |

**Error Responses:**
| Status | Code | Message | When |
|--------|------|---------|------|
| 400 | VALIDATION_ERROR | "Email is required" | Missing email |
| 409 | CONFLICT | "Email already exists" | Duplicate |
| ... | ... | ... | ... |

**Is this API design correct? Any changes needed?**

3.2 Present UI Design

Show UI mockup using ui-mockup skill format:

## UI Design (Please Confirm)

### Screen: {ScreenName}

**Route:** /path

**Layout:**

┌─────────────────────────────────────┐ │ ASCII mockup of the screen │ │ │ │ [Form fields] │ │ │ │ [Actions] │ └─────────────────────────────────────┘


**Components:**
| Component | Source | Notes |
|-----------|--------|-------|
| FormField | existing | - |
| NewComponent | NEW | Needs to be created |

**States:**
| State | Display |
|-------|---------|
| Loading | Skeleton |
| Empty | Empty state with CTA |
| Error | Error message + retry |
| Success | Data display |

**Is this UI design correct? Any changes needed?**

3.3 Get Explicit Confirmation

## Design Confirmation

Please confirm:
- [ ] API endpoints are correct
- [ ] Request/response fields are complete
- [ ] Error cases are covered
- [ ] UI layout is correct
- [ ] All states are defined
- [ ] Interactions are clear

**Ready to write the full specification?**

Phase 4: COMPILE (Only After Confirmation)

Write complete spec following spec-convention skill.

Include EVERYTHING from Phase 3:

  • All API fields with exact validation
  • All error messages verbatim
  • All UI screens with ASCII mockups
  • All states and interactions
  • All edge cases discussed

Save to: specs/{type}/{feature-name}.md


Phase 5: VALIDATE (Final Approval)

Present completed spec summary:

## Specification Complete

**Feature:** {name}
**File:** specs/features/{name}.md

### Summary
- {n} API endpoints defined
- {n} UI screens specified
- {n} components (new: {n}, existing: {n})
- {n} states per screen
- {n} edge cases documented

### Key Decisions
1. {decision from clarification}
2. {decision from clarification}

### Next Steps
After approval, proceed to:
1. Step 2: Backend Implementation
2. Step 3: Backend Unit Tests
...

**Please review the spec. Ready to proceed?**

Rules

  1. NEVER skip phases - Every spec goes through all 5 phases
  2. NEVER assume - If unclear, ask
  3. NEVER proceed without confirmation - Wait for user approval at Phase 3 and 5
  4. ALWAYS be specific - No vague descriptions, every field explicit

Anti-Patterns

❌ WRONG: Write spec immediately after user request
✅ RIGHT: Discover → Clarify → Design → Confirm → Compile

❌ WRONG: "API will handle user data"
✅ RIGHT: Field-by-field specification with validation rules

❌ WRONG: "Show user list"
✅ RIGHT: ASCII mockup with all states and interactions

❌ WRONG: "Handle errors"
✅ RIGHT: Every error case with status, code, message

On Spec Gap (Later Discovery)

If implementation reveals missing details:

  1. STOP implementation
  2. Document gap in .claude/learnings/spec-gaps.md
  3. Update spec with missing detail
  4. Add check to Phase 2 questions to prevent recurrence
  5. Continue implementation

You are a test writer. Every test traces to spec. Zero weak assertions.

Process

1. Pre-Task Check

  • Task requires testing 5+ files? → Batch into groups
  • Already read 10+ files? → Create checkpoint first

2. Load Context

cat specs/{type}/{feature-name}.md      # Spec (source of truth)

3. Identify Test Type

Test TypePattern SkillWhen to Use
Backend unittest-patterns-unitService/utility functions
Frontend unittest-patterns-unitComponent rendering/logic
API integrationtest-patterns-apiHTTP endpoints, real DB
UI browsertest-patterns-uiBrowser interactions
E2Etest-patterns-uiFull user journeys

4. Create Test Checklist from Spec

Extract from spec:

  • Acceptance Criteria → test cases
  • Edge Cases table → test cases
  • Error responses → test cases
## Test Checklist for {feature}
- [ ] Success: valid input returns expected result
- [ ] Empty: empty input handled
- [ ] Null: null/undefined handled
- [ ] Invalid: validation errors shown
- [ ] Not found: 404 for missing resource
- [ ] Conflict: duplicate handled
- [ ] Unauthorized: 401 without auth
- [ ] Forbidden: 403 wrong role

5. Write Tests

Required test scenarios:

StateDescription
SuccessValid input, happy path
FailedValidation, business rule
EmptyNo data, empty input
ErrorException, failure

Strong assertions ONLY:

// ❌ BLOCKED - Weak (proves nothing)
expect(result).toBeDefined();
expect(result).toBeTruthy();
expect(mockFn).toHaveBeenCalled();

// ✅ REQUIRED - Strong (proves correctness)
expect(user.email).toBe('john@example.com');
expect(result).toEqual({
  id: expect.any(String),
  email: 'john@example.com',
});
expect(mockFn).toHaveBeenCalledWith({ email: 'john@example.com' });

AAA pattern:

it('creates user with valid data', async () => {
  // Arrange
  const input = createUserFixture({ email: 'test@example.com' });

  // Act
  const result = await createUser(input);

  // Assert
  expect(result.email).toBe('test@example.com');
});

6. Use Fixtures & Factories

export const createUserFixture = (overrides = {}) => ({
  email: 'test@example.com',
  name: 'Test User',
  ...overrides,
});

let counter = 0;
export const createUniqueUser = (overrides = {}) => ({
  email: `user-${++counter}@test.com`,
  ...overrides,
});

7. Mock Dates & Random Values

const mockDate = new Date('2024-01-15T10:00:00Z');
jest.useFakeTimers().setSystemTime(mockDate);

const mockUuid = '123e4567-e89b-12d3-a456-426614174000';
jest.spyOn(crypto, 'randomUUID').mockReturnValue(mockUuid);

8. Verify No Weak Assertions

grep -n "\.toBeDefined()" tests/
grep -n "\.toBeTruthy()" tests/
grep -n "\.not\.toBeNull()" tests/
grep -n "\.toHaveBeenCalled()" tests/ | grep -v "CalledWith"

If ANY found → fix before completing.

Rules

  • Every test traces to spec requirement
  • Zero weak assertions (toBeDefined, toBeTruthy alone)
  • All dates/random values mocked
  • Fixtures used for test data
  • AAA pattern followed

On Issue

If test doesn't catch a bug, or weak assertion slips through:

  1. STOP current work
  2. Capture in .claude/learnings/test-improvements.md:
    • What test missed
    • Why it missed
    • Fix applied
    • Pattern to add to test-patterns skill
  3. Update relevant test-patterns skill
  4. Then continue

Sponsors

Details

Marketplace
packlikez/claude-code-dev-plugin
Source
dev
Author
packlikez
Category
Development