# AIOX Spec-Driven Development (SDD)

> Mandatory flow for every new project by André Bassi: specs before code. PRD -> Architecture -> Stories -> implementation story-by-story. Point an LLM here and it produces specs and implements exactly in this format.

## Hard Rules

1. No code before `docs/prd.md`, `docs/architecture.md` and `docs/stories/` exist.
2. Exact paths — NEVER `PRD.md`, `ARCHITECTURE.md`, `docs/specs/`:

       docs/prd.md
       docs/architecture.md
       docs/stories/{epic}.{story}.{slug}.md     # e.g. 1.3.transcription.md
       docs/stories/DEPENDENCY-GRAPH.md
       docs/runbooks/<topic>.md

3. `executor != quality_gate` — ALWAYS. Who builds doesn't validate.
4. Story atomic: start and finish before the next. Never skip dependency-graph order.
5. Dev Notes are the SINGLE source of truth during implementation — dev never re-reads architecture.md.
6. Story updated in real time: Status, Tasks [x], Dev Agent Record, QA Results.
7. Docs are part of "Done": specs stay in sync with code.

## Flow (mandatory order)

    1. @analyst   -> brief (optional, complex projects)
    2. @pm        -> docs/prd.md
    3. @architect -> docs/architecture.md
    4. @sm        -> docs/stories/{epic}.{story}.{slug}.md
    5. @dev       -> code, story by story (graph order)
    6. @qa        -> tests + quality gate
    7. @devops    -> deploy

## PRD Sections (exact order)

1. Goals and Background Context — goals bullets, background 1-2 paragraphs, change log table
2. Requirements — Functional (FR1, FR2...), Non Functional (NFR1, NFR2...)
3. Technical Assumptions — repo structure, service architecture, testing requirements
4. Epic List — title + one-sentence goal each
5. Epic Details — per epic: goal + stories in user-story format + acceptance criteria
6. Next Steps — architect prompt + UX expert prompt

## Architecture Sections (exact order)

1. Introduction (starter template check, change log)
2. High Level Architecture (summary, platform, repo structure, diagram ASCII/Mermaid, patterns)
3. Tech Stack — table: Category | Technology | Version | Purpose | Rationale
4. Data Models (entities, attributes, types, relations)
5. API Specification (endpoints, payloads, auth)
6. External APIs (purpose, docs URL, base URL, auth, rate limits, endpoints)
7. Core Workflows (sequence diagrams)
8. Database Schema (full SQL DDL)
9. Backend Architecture
10. Frontend Architecture (if applicable)
11. Deployment Architecture (strategy, CI/CD)
12. Development Workflow (local setup, env vars, commands)

## Story Sections (EXACT order)

1. Status — Draft | Approved | InProgress | Review | Done
2. Executor Assignment — executor, quality_gate, quality_gate_tools
3. Story — "As a {role}, I want {action}, so that {benefit}"
4. Acceptance Criteria — numbered, testable
5. Tasks / Subtasks — checkboxes referencing ACs
6. Dev Notes — FULL context (+ Testing subsection with test patterns)
7. Change Log — table: Date, Version, Description, Author
8. Dev Agent Record — empty until implementation (Agent Model, Debug Log refs, Completion Notes, File List)
9. QA Results — empty until QA

## Executor Assignment Rules

| Work Type | Executor | Quality Gate |
|---|---|---|
| Code/Features/Logic | @dev | @architect |
| Schema/DB/Migrations | @data-engineer | @dev |
| Infra/CI/CD/Deploy | @devops | @architect |
| Design/UI Components | @ux-design-expert | @dev |
| Research/Investigation | @analyst | @pm |
| Architecture Decisions | @architect | @pm |

## Implementation Loop (per story)

    1. Read full story (Dev Notes = only context source)
    2. Status: Draft -> InProgress
    3. Implement Tasks, mark [x] as completed
    4. Validate every Acceptance Criterion
    5. Fill Dev Agent Record (model, completion notes, file list)
    6. Status: InProgress -> Review
    7. Run Quality Gate (tests, review by quality_gate role)
    8. Fill QA Results
    9. Status: Review -> Done
    10. Next story (graph order; parallelism only without mutual deps)

## Pre-Implementation Checklist

- [ ] docs/prd.md exists in AIOX format
- [ ] docs/architecture.md exists in AIOX format
- [ ] Stories exist with Status, Executor, Quality Gate, ACs, Tasks, full Dev Notes
- [ ] Dev Notes sufficient to implement without reading architecture.md
- [ ] Dependency graph clear (DEPENDENCY-GRAPH.md or in PRD)

## Framework Install

    npm install -g aiox-core && aiox-core install
    # or copy: cp -rL /opt/homebrew/lib/node_modules/aiox-core/.aiox-core .aiox-core

Templates: `.aiox-core/product/templates/{prd-tmpl,fullstack-architecture-tmpl,story-tmpl}.yaml`
Agents: `.aiox-core/development/agents/{analyst,pm,architect,sm,dev,qa,po,data-engineer,devops,ux-design-expert}.md`