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. Solution Blueprint — a structured overview of the whole system (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.

TomSpecs release 1 carries the authoring, validation and Phase-4 extract loop: author a Solution Blueprint through the typed facade, validate it mechanically, and run the CodeSpecs extract that turns it into bounded, cited inputs for code generation. The flow driver that scripts the remaining steps (tom_ai_build, on tom_flow, drawing on tom_brain through external interfaces and executing dynamic code through D4rt) lives in the same tree but outside the release.

The components and modules

The factory's tooling ships as TomSpecs release 1 from the tom_ai_build repository (the tom_ai/ai_build tree) — the TomSpecs component in this site's catalog. At its centre is a typed Specification Object Model (SOM), written once in Dart and generated into nine languages (Dart, Python, Java, JavaScript, TypeScript, Go, Rust, C, C++). The Dart chain:

• tom_specs_core — the annotation vocabulary the source model is written in:

section identity and structure, and the traceability annotations that carry a requirement forward through the document graph. - tom_specs_model — the Dart source model, the single source of truth every language binding is generated from, plus the TomSpecs authority documents. - tom_specs_clitool — the generator and gate suite: SOM generation, outlines, the model validator, the citation gates and the release-closure gate. - tom_som_dart_runtime — the generic document runtime: path-keyed documents, the meta-model, schema and instance validation, and the CodeSpecs extract surface. - tom_som_dart_v0 — the generated, typed Dart facade over that runtime. - tom_doc_scanner and tom_doc_specs — the DocSpecs layer: the markdown structure parser and the schema validator built on it. - tom_code_specs — the CodeSpecs annotation framework (Cs* markers, cross-part references, back-trace annotations), with tom_core_codespecs in the Core tree supplying the CodeSpecs-only classes for the tom_core family.

The sixteen non-Dart runtime and facade packages (tom_som_<lang>_runtime / tom_som_<lang>_v0) ship source-only in the same repository, each building and passing its suite from a clean checkout. A conformance harness proves the languages agree: the committed Meridian Order Management sample Solution Blueprint and the CodeSpecs extracts generated from it reproduce byte for byte from a clean checkout.

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. TomSpecs release 1 (2026-09-04, BSD 3-Clause) is published > with a focus on Dart: the Dart chain is on pub.dev (tom_specs_model 1.3.x and > its companions), the other eight languages ship source-only. The specification > editor, the scripting/agent engine and the object-model review app are in the > same tree but deliberately not part of release 1, and the release-closure gate > refuses any dependency from a release member into them.