The Docspecs/Codespecs Software Factory is the staged, AI-assisted process by which Tom applications are created — from an initial idea, through structured specifications, to working, tested code — with complete traceability from a business requirement to the implementation and the test that covers it. It is one of the seven building blocks of the framework, and the one that turns "describe the system" into "the system exists".

Where the other areas provide runtime capabilities, this area provides a methodology and the tooling that enforces it. Its premise is that AI cannot reliably infer intent: specifications must be explicit, examples are specifications, boundary conditions come before happy paths, each generated unit is verified before the next is built on it, and the same specification yields the same code regardless of which AI session runs it. The factory exists to make those principles operational rather than aspirational.

The two layers: DocSpec and CodeSpec

The name pairs the two specification layers the factory is built on.

• DocSpec is structured, schema-validated Markdown. Each artifact type in the

process — vision, requirements, architecture, an implementation spec, a test spec — has a corresponding DocSpec schema, so a document can be validated for completeness and its requirements, constraints, and decisions extracted programmatically. DocSpec sits on a document scanner that parses the structured Markdown into a typed model. - CodeSpec is the abstract interface for the application: the contract the implementation must satisfy. It is produced from the specifications and consumed by the implementation phase, so the generated code has a precise target rather than a prose description to interpret.

Together they give the factory its traceability spine: requirement → DocSpec → CodeSpec → implementation → test, each step validatable against the last.

The creation flow

Applications are produced through a staged flow with quality gates between phases — each phase has defined inputs, activities, outputs, and a gate that must hold before the next begins:

1. Project Idea — free-form vision and ideas. 2. Project Definition — a structured overview (a DocSpec). 3. Detailed Specifications — the full set of typed documents (current situation, requirements catalogue, business processes, business data model, authorization concept, technical requirements, use cases, UI prototype, rollout, quality plan, and more). 4. CodeSpecs — a skeletal application that compiles but does not yet execute. 5. Test Derivation — test cases derived directly from the specifications. 6. Implementation — working code plus unit tests. 7. Business Acceptance — deployed, tested, accepted. 8. Multi-tenant (optional) — provisioning and subscription/quota integration.

This flow is what ai_build scripts in the framework: it drives the steps on tom_flow, draws on tom_brain for the AI specification and coding work through external interfaces, and both execute their dynamic code through D4rt.

The components and modules

The factory's tooling lives in the tom_specs_* projects (in the tom_ai/ai_build tree). They are not yet part of this site's component catalog, so they are described here in prose:

• tom_specs_core — the annotation library shared across the model and tooling.

It defines the section-identity and structural annotations (@SectionId, @SectionIdPattern, @Document, @Form, @ContentType, …) and the traceability annotations (@MapsTo, @DetailedIn, @SecondLevelSectionId) that carry a requirement forward through the document graph. - tom_specs_model — the typed Dart data model for every TomSpecs document. The Markdown templates are the human-readable face; the Dart model is the source of truth, with analyzer support. The Project Definition root is structurally complete (hundreds of uniquely-identified section classes), and all twelve Phase-3 document roots compile and aggregate it with full traceability annotations. - tom_specs_clitool — the analyzer-based tooling: a model outliner that renders the class tree from any document root, a validator that enforces the structural invariants (global section-id uniqueness, coverage, detail-mapping rules), and a JSON exporter that serialises the resolved model graph for the editor app. - tom_specs_editor — a Flutter app for browsing the document structures as trees and recording a structural review, persisted to YAML keyed by structural path. It consumes the model graph the CLI tool exports — thirteen document roots and roughly three thousand classes — so a reviewer walks the real typed model, not a copy. Its future direction is a full spec editor with Markdown import/export.

These build on the broader DocSpecs and CodeSpecs initiatives (the document scanner and schema layer, and the code-generation contract) and connect to the quality-gate and roles definitions that govern the process.

How it fits the rest of Tom

The Software Factory is the production line for business logic, and it is deliberately decoupled from the runtime guarantees. Tom Core enforces a uniform UI, internationalization, authentication, authorization, architecture, and deployment by construction — independent of how the business logic was generated. The factory produces only that business logic, on top of those guarantees. So an application's uniformity does not depend on the AI getting everything right; the factory's job is the domain-specific behaviour, and the framework supplies everything else.

> Maturity note. The process and artifact definitions are mature and the typed > object model, the analyzer-based tooling, and a first-cut editor are implemented > and tested. The factory is an actively implemented methodology, not only a > conceptual one.