Spec-Driven Workflow

Requirements that mean something. Workflows that work. Documentation that doesn't rot.

Why Spec-Driven?

Most development workflows fail at the same point: requirements are vague, designs are implicit, and documentation is an afterthought. The spec-driven approach flips this by making requirements the foundation everything else builds on.

Core principle: If you can't express a requirement in testable, unambiguous language, you don't actually have a requirement—you have a vibe. And vibes don't deploy.

EARS Notation

EARS (Easy Approach to Requirements Syntax) provides a structured format for expressing requirements that are both human-readable and machine-parseable:

Requirement Patterns

Ubiquitous

THE SYSTEM SHALL [expected behavior]

For requirements that always apply, unconditionally.

Event-driven

WHEN [trigger event] THE SYSTEM SHALL [expected behavior]

For requirements triggered by specific events.

State-driven

WHILE [in specific state] THE SYSTEM SHALL [expected behavior]

For requirements that apply only during certain states.

Unwanted behavior

IF [unwanted condition] THEN THE SYSTEM SHALL [required response]

For handling error conditions and edge cases.

Optional

WHERE [feature is included] THE SYSTEM SHALL [expected behavior]

For optional features or configuration-dependent behavior.

Example Requirements

docs/PRD.mdmarkdown

## Authentication Requirements

### REQ-AUTH-001: Session Creation
WHEN a user provides valid credentials
THE SYSTEM SHALL create a new authenticated session
AND return a signed JWT token with 24-hour expiration.

### REQ-AUTH-002: Session Validation
WHILE a user session is active
THE SYSTEM SHALL validate the JWT signature on each request
AND reject requests with expired or invalid tokens.

### REQ-AUTH-003: Rate Limiting
IF a user exceeds 100 login attempts per hour
THEN THE SYSTEM SHALL block further attempts for 15 minutes
AND log the incident to the security audit trail.

The 6-Phase Execution Loop

Every DevCycle follows this structured execution model. No skipping phases. No vibes-driven shortcuts.

Analyze

• Read specs and context
• Parse EARS requirements
• Generate confidence score
• Identify dependencies

Design

• Create technical design
• Write ADRs for decisions
• Build task breakdown
• Adapt to confidence level

Implement

• Write production code
• Create tests alongside
• Document as you go
• Commit incrementally

Validate

• Run automated tests
• Check quality gates
• Verify acceptance criteria
• Performance profiling

Reflect

• Refactor for quality
• Update documentation
• Identify tech debt
• Log lessons learned

Handoff

• Create pull request
• Generate summaries
• Prepare deployment
• Transition to next cycle

Confidence-Based Execution

The Analyze phase generates a confidence score (0-100%) that determines how the Design phase proceeds:

Confidence	Strategy
High (>85%)	Full implementation. Skip PoC. Comprehensive plan.
Medium (66-85%)	Start with PoC/MVP. Validate approach before full build.
Low (<66%)	Research phase first. Re-analyze after knowledge gain.

Documentation Templates

Action Documentation

Every action during execution gets logged with this structure:

Action document templatemarkdown

### [TYPE] - [ACTION] - [TIMESTAMP]
**Objective**: Goal being accomplished
**Context**: Current state and references
**Decision**: Approach chosen and rationale
**Execution**: Steps taken with parameters
**Output**: Complete results and logs
**Validation**: Success verification
**Next**: Continuation plan

Decision Records

All decisions are captured for future reference:

Decision record templatemarkdown

### Decision - [TIMESTAMP]
**Decision**: What was decided
**Context**: Situation and data
**Options**: Alternatives evaluated
**Rationale**: Why this option
**Impact**: Anticipated consequences
**Review**: Reassessment conditions

💡

Traceability

Every code change links back to a requirement ID, decision record, and DevCycle phase. This creates an audit trail from feature request to production deployment.

Artifact Outputs

DevCycles generate dual-format outputs for both humans and machines:

NDJSON (Machine)

Structured logs for CI/CD integration, metrics, and programmatic analysis. One JSON object per line for easy streaming.

.loaded-vibes/logs/*.ndjson

Markdown (Human)

Readable summaries for pull requests, changelogs, and documentation. Formatted for review and collaboration.

docs/summaries/*.md

Next Steps

Learn about the Artifacts that make up the framework's tooling, or dive into the Running DevCycles guide for practical examples.