Code Generation Pipeline

Praetor's code generation pipeline transforms a specification into working code by traversing the Unified Project Graph in dependency order, executing Kit jobs for each node, and verifying outputs against the spec. Successful generations feed back into the pattern system, making future runs faster and more consistent.

The full flow

Spec ingested into graph
         │
         ▼
Topological sort (Kahn's algorithm)
→ Build order: entities → services → endpoints
         │
         ▼
For each node (in order):
  Load upstream Interface Contracts
  Match patterns from graph
  Build KitJobInput
         │
         ▼
Kit execution (via ContainerPlatform job queue)
         │
         ▼
Structural verification
  Pass → write generated_from edge, extract pattern
  Fail → CEGIS retry (up to 3 attempts)
         │
         ▼
Generation run summary

Pipeline Sub-pages

Topological Sort

How Kahn's algorithm orders Kit execution across the spec graph. What batch groups are, how dependency resolution works, and how circular references in the spec are detected and surfaced before generation begins.

Kit Execution

The 7-phase lifecycle every Kit follows — CHECK, SPEC, PLAN, APPLY, TEST, VERIFY, REGISTER. The KitInput/KitOutput contract, how the CEGIS feedback loop is structured, and how LLM Kits differ from deterministic pipeline steps.

Code Kits

The catalog of LLM-driven Kits that generate logic-bearing source files: EntityKit, ServiceKit, OperationKit, EndpointKit, SchemaKit, GuardKit, AuthKit, APIClientKit, WorkflowKit, WorkflowStepKit, and NotificationKit.

Config Kits

The deterministic pipeline steps that produce project scaffolding without LLM calls: ScaffoldStep, SharedTypesStep, DesignSystemStep, MigrationStep, TestInfraStep, and CICDStep.

Interface Contracts

How typed handoffs work between Kit phases. The InterfaceContract type that each Kit writes after generation, how downstream Kits consume upstream contracts, and what information passes between Kit phases.

Pattern Matching

How patterns from the pattern flywheel are matched and applied during generation. What a pattern is, how the matching algorithm scores candidates, and how successful generations become reusable patterns over time.

Infra Kits

Infrastructure-layer Kits and pipeline steps that produce deployment configuration: Docker, Railway, GitHub Actions, and environment scaffolding.

Architecture Context

The codegen pipeline is one part of a larger architecture. For the broader picture:

• Kit System Architecture — how Kits are registered and composed
• Convergence Model — how convergence checking drives retries
• Emitter Router — how per-emitter routing works
• Convergence (CEGIS deep-dive) — the mathematical framework behind verification