Development Methodology

Spec-Driven
Development

Every feature starts with a specification. Clear requirements, defined acceptance criteria, and validated implementations before any code is written.

SPEC-0042: User Dashboard Widget

Approved

Objective

Create an interactive dashboard widget that displays real-time project metrics and enables quick actions.

Requirements

Display active task count with status breakdown
Show recent activity timeline (last 24h)
Enable quick-create for new issues
Support keyboard navigation

Acceptance Criteria

Widget loads within 200ms

Real-time updates via WebSocket

Accessible (WCAG 2.1 AA)

Unit test coverage > 80%

Why Specs First?

Structured development eliminates ambiguity and catches issues before implementation

Clear Objectives

Every feature has a defined purpose, scope, and success criteria before development begins. No more scope creep.

Auto-Generated Specs

The Architect analyzes your issue and generates comprehensive specifications automatically, saving hours of planning.

Testable Criteria

Acceptance criteria are written as verifiable checkpoints. Runners validate implementation against specs.

Human Review Gates

Specs require approval before implementation. Stakeholders validate requirements match expectations.

Version Control

Specs are tracked in GitHub. Changes are audited, revisions are linked to issues, history is preserved.

Code Alignment

Implementation is validated against specs. Deviations are flagged. PRs reference spec checkpoints.

The Spec Flow

From issue to implementation, guided by specification

Issue Created

A new feature request or bug is opened. The Architect analyzes the issue context, codebase patterns, and related issues.

Spec Generated

Alpha PM generates a comprehensive specification including objectives, requirements, acceptance criteria, and technical approach.

Human Review

Stakeholders review the spec via Slack or GitHub. Feedback is incorporated, scope is adjusted, and final approval is granted.

Implementation

Runners execute against the approved spec. Each acceptance criterion becomes a validation checkpoint during development.

Verification

The completed work is validated against spec criteria. Tests verify requirements are met. PR links spec to implementation.

Spec Format

Structured YAML specifications stored alongside your code

specs/SPEC-0042-dashboard-widget.yaml

id: SPEC-0042
title: User Dashboard Widget
issue: #142
status: approved
author: alpha-pm
approved_by: @david.winter

objective: |
  Create an interactive dashboard widget
  displaying real-time project metrics.

requirements:
  - Display active task count with breakdown
  - Show recent activity timeline
  - Enable quick-create for new issues
  - Support keyboard navigation

acceptance_criteria:
  - id: AC-001
    description: Widget loads within 200ms
    testable: true
  - id: AC-002
    description: Real-time updates via WebSocket
    testable: true
  - id: AC-003
    description: WCAG 2.1 AA accessible
    testable: true

technical_approach:
  components:
    - DashboardWidget.tsx
    - MetricsProvider.tsx
  dependencies:
    - @tanstack/react-query
    - socket.io-client

Spec-DrivenDevelopment