Flowspec

Specification-driven development for AI-augmented teams.

An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.

What is Spec-Driven Development?

Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.

Getting Started

• Installation Guide
• Quick Start Guide
• Local Development

Workflow Configuration

Customize and extend the Spec-Driven Development workflow to match your organization's needs.

Understanding Workflows

• Workflow Architecture - Overall workflow system design and components
• JP Spec Workflow Guide - Comprehensive guide to the workflow system
• Workflow State Mapping - How workflow states map to backlog task states

Customization

• Workflow Customization Guide - How to modify and extend workflows
• Workflow Troubleshooting - Common issues and solutions

Examples

• Minimal Workflow - Simple two-phase workflow (specify + implement)
• Security Audit Workflow - Extended workflow with security audit phase
• Parallel Workflows - Multiple feature tracks running in parallel
• Custom Agents Workflow - Adding organization-specific agents

Reference

• Workflow Schema - Complete schema reference for flowspec_workflow.yml
• Workflow Schema Validation - Validation rules and constraints
• Workflow Artifact Flow - How artifacts flow between workflow phases
• Workflow Step Principles - Design principles for workflow steps

Core Philosophy

Spec-Driven Development is a structured process that emphasizes:

• Intent-driven development where specifications define the "what" before the "how"
• Rich specification creation using guardrails and organizational principles
• Multi-step refinement rather than one-shot code generation from prompts
• Heavy reliance on advanced AI model capabilities for specification interpretation

Development Phases

Phase	Focus	Key Activities
0-to-1 Development ("Greenfield")	Generate from scratch	Start with high-level requirements Generate specifications Plan implementation steps Build production-ready applications
Creative Exploration	Parallel implementations	Explore diverse solutions Support multiple technology stacks & architectures Experiment with UX patterns
Iterative Enhancement ("Brownfield")	Brownfield modernization	Add features iteratively Modernize legacy systems Adapt processes

Experimental Goals

Our research and experimentation focus on:

Technology Independence

• Create applications using diverse technology stacks
• Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks

Enterprise Constraints

• Demonstrate mission-critical application development
• Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
• Support enterprise design systems and compliance requirements

User-Centric Development

• Build applications for different user cohorts and preferences
• Support various development approaches (from vibe-coding to AI-native development)

Creative & Iterative Processes

• Validate the concept of parallel implementation exploration
• Provide robust iterative feature development workflows
• Extend processes to handle upgrades and modernization tasks

Contributing

Please see our Contributing Guide for information on how to contribute to this project.

Support

For support, please check our Support Guide or open an issue on GitHub.