AI Dev Flow Framework

AI Dev Flow Framework

Specification-Driven Development (SDD) Template System for AI-Assisted Software Engineering

Overview

The AI Dev Flow Framework is a comprehensive template system for implementing AI-Driven Specification-Driven Development (SDD). It provides structured workflows, document templates, and traceability mechanisms to transform business requirements into production-ready code through a systematic, traceable approach optimized for AI-assisted development.

MVP Note: When using the MVP track, all artifacts are single, flat files. Do not use document splitting or DOCUMENT_SPLITTING_RULES.md.

Automation Philosophy: Maximum Velocity to Production

PRIMARY GOAL: Fastest Transition from Business Idea to Production MVP

AI Dev Flow eliminates manual bottlenecks through intelligent automation and strategic human oversight.

Automation Capabilities:

• Quality-Gated Automation: Replace mandatory checkpoints with AI-scored quality validation
  • Auto-approve if quality score ≥ threshold (90-95%)
  • Human review only if score fails
  • Result: Up to 93% automation (12 of 13 production layers)
• AI Code Generation: YAML specs → Production-ready code
• Auto-Fix Testing: 3 retry attempts reduce manual debugging
• Strategic Checkpoints: Only 5 critical decisions need human approval if quality score < threshold (90%)
• Continuous Pipeline: Automated validation, security scanning, deployment builds

Human-in-the-Loop Checkpoints (Quality Gates):

| Layer | Checkpoint | Why Human Review? | |-------|------------|------------------| | L1 (BRD) | Business owner approves | Strategic business alignment | | L2 (PRD) | Product manager approves | Product vision validation | | L5 (ADR) | Architect approves | Technical architecture decisions | | L11 (Code) | Developer reviews | Code quality and security | | L13 (Deployment) | Ops approves | Production release gating |

Automated Layers (No human intervention required):

• L3 (EARS), L4 (BDD), L6 (SYS), L7 (REQ), L8 (CTR), L9 (SPEC), L10 (TASKS), L12 (Tests)

Result: Dramatically reduced manual effort while maintaining quality through strategic oversight.

MVP Delivery Loop: Iterative Product Development

AI Dev Flow supports continuous product evolution through iterative MVP cycles:

The Delivery Loop:

┌─────────────────────────────────────────────────┐
│ MVP v1.0 → Defect Fixes → Production Release   │
│     ↓                                           │
│ MVP v2.0 (Add Features) ← Market Feedback       │
│     ↓                                           │
│ Defect Fixes → Production                       │
│     ↓                                           │
│ MVP v3.0 (Add Features) ← ...                   │
└─────────────────────────────────────────────────┘

Key Benefits:

• Rapid Iteration: Complete L1-L13 pipeline with 90% automation
• Incremental Features: Add features as new MVPs, preserve working product
• Production Focus: Every MVP targets production deployment
• Cumulative Traceability: Each MVP inherits and extends previous version's artifacts

How Automation Enables the Loop:

| Stage | Automation Support | |-------|-------------------| | Build MVP v1.0 | Full L1-L13 automation (90% automated) | | Fix Defects | Auto-retry testing (3x), auto-fix capabilities | | Deploy to Production | Automated build, validation, security scans | | Add Features (MVP v2.0) | Reuse or create new BRD/PRD/ADR, auto-generate new REQ→CODE | | Iterate | Cumulative tags enable impact analysis |

MVP Evolution Example:

• MVP 1.0: User authentication → Production
• Defect Fixes: Password reset bugs → Production
• MVP 2.0: Add social login (Google, GitHub) → Production
• MVP 3.0: Add 2FA and session management → Production

Each cycle leverages automation to maintain velocity while ensuring quality through human checkpoints.

Default Template Selection (MVP is Default)

MVP templates are the framework default for all new document creation. Full templates are available for enterprise/regulatory projects.

Available MVP Templates (Layers 1-7)

| Layer | Artifact | Default Template | |-------|----------|-----------------| | 1 | BRD | BRD-MVP-TEMPLATE.md | | 2 | PRD | PRD-MVP-TEMPLATE.md | | 3 | EARS | EARS-MVP-TEMPLATE.md | | 4 | BDD | BDD-MVP-TEMPLATE.feature | | 5 | ADR | ADR-MVP-TEMPLATE.md | | 6 | SYS | SYS-MVP-TEMPLATE.md | | 7 | REQ | REQ-MVP-TEMPLATE.md |

Layers 8-15 use full templates only (no MVP variants).

Triggering Full Templates

When full documentation is required, trigger full templates using:

Method 1 - Project Settings (in .autopilot.yaml or CLAUDE.md):

template_profile: enterprise  # or "full" or "strict"

Method 2 - Prompt Keywords (include in your request):

• "use full template"
• "use enterprise template"
• "enterprise mode"
• "full documentation"
• "comprehensive template"
• "regulatory compliance"

Key Features

• 90%+ Automation: 12 of 13 production layers generate automatically with quality gates
• Strategic Human Oversight: Only 5 critical checkpoints require human approval (if quality score < 90%)
• Code-from-Specs: Direct YAML-to-Python code generation from technical specifications
• Auto-Fix Testing: Failing tests trigger automatic code corrections (max 3 retries)
• Continuous Delivery Loop: MVP → Defects → Production → Next MVP rapid iteration
• 15-Layer Architecture: Structured progression from strategy to validation (Strategy → BRD → PRD → EARS → BDD → ADR → SYS → REQ → IMPL → CTR → SPEC → TASKS → Code → Tests → Validation)
• Cumulative Tagging Hierarchy: Each artifact includes tags from ALL upstream layers for complete audit trails
• REQ v3.0 Support: Enhanced REQ templates with sections 3-7 (interfaces/schemas/errors/config/quality attributes) for ≥90% SPEC-readiness
• Tag-Based Auto-Discovery: Lightweight @tags in code auto-generate bidirectional traceability matrices
• Namespaced Traceability: Unified TYPE.NN.TT.SS format (e.g., BRD.01.01.30) prevents ambiguity
• Complete Traceability: Bidirectional links between all artifacts (business → architecture → code)
• AI-Optimized Templates: Ready for Claude Code, Gemini, GitHub Copilot, and other AI coding assistants
• Domain-Agnostic: Adaptable to any software domain (finance, healthcare, e-commerce, SaaS, IoT)
• Token-Efficient Design: Optimized for AI tool context windows (50K-100K tokens per document)
• Dual-File Contracts: CTR uses .md (human) + .yaml (machine) for parallel development
• Automated Validation: Scripts for tag extraction, cumulative tagging validation, and matrix generation with CI/CD integration
• Regulatory Compliance: Complete audit trails meet SEC, FINRA, FDA, ISO requirements

🤖 Agent Swarm Integration (.aidev)

The framework now includes a native Agent Orchestration System located in .aidev/. This system implements the BMAD Methodology, deploying a swarm of 16 specialized AI agents (using Claude Code, Gemini, and Codex) to autonomously generate and validate the documentation artifacts.

Key Capabilities

• 16-Layer Swarm: A dedicated agent role for every layer (e.g., product-manager for PRDs, architect for ADRs).
• Adversarial Pair Architecture: Every step is executed by one model (e.g., Gemini) and reviewed by another (e.g., Claude) to minimize hallucinations.
• CLI-First: Designed to work with standard CLI tools (claude, gemini, codex).

👉 Get Started with the Agent Swarm

Quality Gates and Traceability Validation

The framework includes automated quality gates that ensure each layer in the 16-layer SDD workflow meets maturity thresholds before progressing to downstream artifacts. Quality gates prevent immature artifacts from affecting subsequent development stages.

Quality Gate Architecture

Automatic Validation Points:

• Ready Score Gates: Each artifact includes a maturity score (e.g., EARS-Ready Score: ✅ 95% ≥90%)
• Cumulative Tag Enforcement: All artifacts must include traceability tags from upstream layers
• Pre-commit Blocking: Git hooks validate artifacts before commits

Pre-commit Quality Gates:

• ./scripts/validate_quality_gates.sh docs/PRD/PRD-001.md - Validates individual artifact readiness
• Automatic validation during git commit on changes to docs/ directory
• Refer to TRACEABILITY_VALIDATION.md for complete specification

Quality Gate Workflow By Layer

Each layer transition has specific quality requirements:

| From→To | Quality Gate | Validation Command | |-------------|------------------|----------------------| | BRD→PRD | EARS-Ready Score ≥90% | ./scripts/validate_quality_gates.sh docs/BRD/BRD-001.md | | PRD→EARS | BDD-Ready Score ≥90% | ./scripts/validate_quality_gates.sh docs/PRD/PRD-001.md | | EARS→BDD | ADR-Ready Score ≥90% | ./scripts/validate_quality_gates.sh docs/EARS/EARS-001.md | | BDD→ADR | SYS-Ready Score ≥90% | ./scripts/validate_quality_gates.sh docs/BDD/BDD-001.feature | | ADR→SYS | REQ-Ready Score ≥90% | ./scripts/validate_quality_gates.sh docs/ADR/ADR-001.md | | SYS→REQ | SPEC-Ready Score ≥90% | ./scripts/validate_quality_gates.sh docs/SYS/SYS-001.md | | REQ→IMPL | IMPL-Ready Score ≥90% | ./scripts/validate_quality_gates.sh docs/REQ/risk/lim/REQ-001.md | | IMPL→SPEC | TASKS-Ready Score ≥90% (SPEC) | ./scripts/validate_quality_gates.sh docs/SPEC/SPEC-001.yaml | | CTR→SPEC | Contract file validati