Spec-First Pipeline

The SEA™ development process is spec-first: requirements drive design, design drives DSL, DSL drives code generation.

1
ADR → PRD → SDS → SEA™ → AST → IR → manifest → codegen

1. ADR (Architecture Decision Record)

Path: docs/specs/<ctx>/<ctx>.adr.md

2. PRD (Product Requirements)

Path: docs/specs/<ctx>/<ctx>.prd.md

• Uses EARS format for requirements
• Each requirement has a REQ-### ID
• References ADR IDs it satisfies

3. SDS (Software Design Spec)

Path: docs/specs/<ctx>/<ctx>.sds.yaml

Machine-readable design including:

• Aggregates, entities, value objects
• Commands/queries/events (CQRS)
• Policies (invariants)
• Runtime choices (api, persistence, messaging)

Validate: python tools/validate_sds.py <sds.yaml>

4. SEA-DSL

Path: docs/specs/<ctx>/<ctx>.sea

Translate SDS into SEA-DSL:

• Entities → Entity declarations
• Value objects → Resource declarations
• Commands/queries/events → Flow with @cqrs annotations
• Invariants → Policy with expression trees

See: flow-annotations.md

5. Compilation Pipeline

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Validate SEA™
sea validate docs/specs/<ctx>/<ctx>.sea

# Parse to AST
sea parse --format json docs/specs/<ctx>/<ctx>.sea > <ctx>.ast.json

# AST → IR
python tools/ast_to_ir.py <ctx>.ast.json <ctx>.ir.json

# IR → Manifest
python tools/ir_to_manifest.py <ctx>.ir.json <ctx>.manifest.json

# Manifest → Generated Code
python tools/codegen/gen.py <ctx>.manifest.json

# Determinism check
python tools/regen_check.py <ctx>.manifest.json

6. Nx Targets

Per bounded context, define targets in project.json:

Run all:

1
2
nx run specs-<ctx>:codegen
nx run-many -t codegen