spec-driven-dev

User Request → Extract Requirements → Write Spec → Validate Spec → Implement → Verify Against Spec
                                          ↑                |
                                          └── Revise ──────┘

// requirements.ts — Extract structured requirements from natural language
/**
 * Turns vague requests into concrete, testable requirements.
 * Each requirement gets a priority, acceptance criteria,
 * and explicit out-of-scope markers.
 */

interface Requirement {
  id: string;                      // REQ-001, REQ-002, etc.
  title: string;
  description: string;
  priority: "must" | "should" | "could" | "wont";  // MoSCoW
  acceptanceCriteria: string[];    // Testable conditions
  outOfScope?: string[];           // Explicitly excluded
}

interface RequirementsDoc {
  projectName: string;
  overview: string;
  stakeholders: string[];
  requirements: Requirement[];
  assumptions: string[];
  constraints: string[];
  openQuestions: string[];         // Things that need clarification
}

/**
 * Template for requirement extraction prompt.
 * The agent uses this to interview the user or analyze the request.
 */
const EXTRACTION_PROMPT = `
Analyze the following request and extract structured requirements.

For each requirement:
1. Write a clear, testable acceptance criterion
2. Assign priority (must/should/could/won't)
3. Note anything explicitly out of scope
4. Flag assumptions that need validation
5. List open questions that could change the design

Be specific. "Fast" is not a requirement. "Page loads in <2 seconds on 3G" is.
"Secure" is not a requirement. "All API endpoints require JWT auth with 15-min expiry" is.
`;

# Technical Spec Template

## 1. Overview
One paragraph: what we're building and why.

## 2. Goals & Non-Goals
### Goals
- [Specific, measurable outcome]
- [Specific, measurable outcome]

### Non-Goals
- [Explicitly excluded scope]
- [Things we're NOT building]

## 3. Background
Why now? What's the current state? What's the problem?

## 4. Technical Design

### 4.1 Architecture
High-level architecture: components, data flow, integrations.

### 4.2 Data Model
Database schema, API types, key data structures.

### 4.3 API Design
Endpoints, request/response types, error handling.

### 4.4 Key Algorithms
Non-obvious logic. Decision trees. State machines.

## 5. Alternatives Considered
| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| Option A | ... | ... | Chosen because... |
| Option B | ... | ... | Rejected because... |

## 6. Implementation Plan
### Phase 1: [Name] (Week 1)
- [ ] Task 1
- [ ] Task 2

### Phase 2: [Name] (Week 2)
- [ ] Task 3
- [ ] Task 4

## 7. Testing Strategy
- Unit tests for [what]
- Integration tests for [what]
- E2E tests for [what]
- Performance benchmarks for [what]

## 8. Rollout Plan
- Feature flag: [name]
- Rollout: 5% → 25% → 100%
- Rollback trigger: [metric] drops below [threshold]

## 9. Open Questions
- [ ] Question 1
- [ ] Question 2

## 10. References
- [Related RFC or design doc]
- [External documentation]

// validate-spec.ts — Automated spec validation
/**
 * Checks a technical spec for common issues:
 * - Vague requirements without acceptance criteria
 * - Missing error handling considerations
 * - No rollback/migration plan
 * - Unaddressed security concerns
 */

interface ValidationResult {
  category: string;
  check: string;
  status: "pass" | "warn" | "fail";
  message: string;
}

export function validateSpec(spec: string): ValidationResult[] {
  const results: ValidationResult[] = [];

  // Completeness checks
  const requiredSections = [
    "Overview", "Goals", "Non-Goals", "Technical Design",
    "Testing Strategy", "Rollout Plan",
  ];
  for (const section of requiredSections) {
    results.push({
      category: "completeness",
      check: `Has "${section}" section`,
      status: spec.toLowerCase().includes(section.toLowerCase()) ? "pass" : "fail",
      message: spec.includes(section) ? "Present" : `Missing "${section}" section`,
    });
  }

  // Quality checks
  const vagueTerms = ["fast", "secure", "scalable", "user-friendly", "robust", "efficient"];
  for (const term of vagueTerms) {
    const regex = new RegExp(`\\b${term}\\b`, "gi");
    const matches = spec.match(regex);
    if (matches && matches.length > 0) {
      results.push({
        category: "quality",
        check: `No vague term: "${term}"`,
        status: "warn",
        message: `Found "${term}" ${matches.length} time(s) — replace with measurable criteria`,
      });
    }
  }

  // Error handling check
  if (!spec.toLowerCase().includes("error") && !spec.toLowerCase().includes("failure")) {
    results.push({
      category: "reliability",
      check: "Addresses error handling",
      status: "fail",
      message: "No mention of error handling or failure scenarios",
    });
  }

  // Security check
  if (!spec.toLowerCase().includes("auth") && !spec.toLowerCase().includes("security")) {
    results.push({
      category: "security",
      check: "Addresses security",
      status: "warn",
      message: "No mention of authentication or security considerations",
    });
  }

  // Migration/rollback check
  if (!spec.toLowerCase().includes("rollback") && !spec.toLowerCase().includes("migration")) {
    results.push({
      category: "operations",
      check: "Has rollback plan",
      status: "warn",
      message: "No rollback or migration strategy mentioned",
    });
  }

  return results;
}

// implement.ts — Convert spec sections to implementation tasks
/**
 * Breaks a spec into ordered implementation tasks.
 * Each task maps to a spec section and includes
 * the acceptance criteria as test assertions.
 */

interface ImplementationTask {
  id: string;
  specSection: string;          // Which spec section this implements
  description: string;
  files: string[];              // Files to create or modify
  acceptanceCriteria: string[]; // From the spec — become test assertions
  dependencies: string[];       // Task IDs that must complete first
  estimatedMinutes: number;
}

function specToTasks(spec: string): ImplementationTask[] {
  // Parse spec sections and generate implementation order
  // Data model first, then API, then business logic, then tests
  return [
    {
      id: "IMPL-001",
      specSection: "4.2 Data Model",
      description: "Create database schema and migrations",
      files: ["prisma/schema.prisma", "prisma/migrations/"],
      acceptanceCriteria: [
        "All tables from spec exist with correct columns and types",
        "Foreign keys and indexes match spec",
        "Migration runs cleanly on empty database",
      ],
      dependencies: [],
      estimatedMinutes: 30,
    },
    {
      id: "IMPL-002",
      specSection: "4.3 API Design",
      description: "Implement API endpoints with types",
      files: ["src/routes/", "src/types/"],
      acceptanceCriteria: [
        "All endpoints from spec are implemented",
        "Request/response types match spec exactly",
        "Error responses follow spec format",
      ],
      dependencies: ["IMPL-001"],
      estimatedMinutes: 60,
    },
    // ... more tasks
  ];
}