tom_ai_build — the TomSpecs release repository
Start here. This repository ships release 1 of TomSpecs: a structured, AI-assistable process for creating software systems, carried by a typed Specification Object Model (SOM) that is generated into nine languages (Dart, Python, Java, JavaScript, TypeScript, Go, Rust, C, C++) from a single Dart source model. With it you can author a specification document (a Solution Blueprint and its detail documents), validate it mechanically, and run the Phase-4 CodeSpecs extract pass that turns a validated specification into bounded, cited inputs for code generation.
What release 1 contains — and what it deliberately leaves out — is stated in RELEASE_NOTES.md.
Quickstart: author → validate → extract
The fastest way to see the whole loop is to reproduce the run this repository already carries: the Meridian Order Management
sample Solution Blueprint and the 26 CodeSpecs extracts generated from it, both committed under tom_som_conformance/. The commands below re-run that loop from a clean checkout; because the run is deterministic, your output reproduces the committed record byte for byte.
You need a Dart SDK (3.11 or later). Toolchains for the other eight languages are only needed for their runtimes — see
tom_specs_model/doc/som_toolchains.md.
git clone https://github.com/al-the-bear/tom_ai_build.git
cd tom_ai_build/tom_som_dart_v0
dart pub get1. Author a Solution Blueprint through the typed facade. This builds the Meridian sample in code and serializes it to both normative renditions — DocSpecs YAML and markdown:
dart run tool/build_shared_sample.dart
writes tom_som_dart_v0/documents/meridian_order_management.docspecs.yaml and .md. Open either file to see what an authored Solution Blueprint looks like on disk; open
tool/build_shared_sample.dart to see the same document authored through the typed API.
2. Validate it, then generate the CodeSpecs extracts:
dart run tool/build_meridian_extracts.dart
This runs the gate tiers in order — DocSpecs schema completeness, the instance-tier document validator
(validateDocument), routing totality, and DOMEN closed-choice completeness
(every enumeration-kind attribute's domainEnum must resolve to an authored DMENE
entry) — and only then runs the spec_codespecs_extract surface, writing one extract pair (.extract.yaml
of record + rendered .extract.md) per CodeSpecs area to tom_som_conformance/generated-doc/codespecs_extracts/
(52 files). Those extracts are the bounded, cited input the Phase-4 authoring agent works from.
3. Confirm the reproduction:
git diff --stat # clean = your run reproduced the committed record
Authoring your own document: start from the committed sample — copy the YAML and edit it, or copy
tool/build_shared_sample.dart and author through the typed facade — then run the same validate-and-extract tool over it. The markdown and YAML renditions are equivalent and loss-free in both directions.
The other eight languages
Every language ships a tom_som_<lang>_runtime (generic document runtime + DocSpecs schema validator + instance-tier
validateDocument + the spec_codespecs_extract surface) and a generated tom_som_<lang>_v0
typed facade. So a specification authored in the quickstart above can be read and validated in the reader's language of choice.
Per pair:
README.md— what the package is;readme_howtointegrate.md— every
dependency route and how to pin the version. - examples/ — runnable examples, executed by the test suites. -
run_tests.sh — builds and runs the package's full suite.
The cross-language proof lives in tom_som_conformance/: a shared corpus and golden logs that all nine runtimes must reproduce byte-identically.
tool/run_tests.sh per package, tom_som_conformance/tool/run_all_suites.sh --strict
for everything at once.
Documentation map
All hand-written TomSpecs documentation lives in tom_specs_model/doc/
— thirteen documents, each the single authority for its subject, catalogued by index.md. In reading order for a newcomer:
| Document | Read it for |
|---|---|
| tom_specs_project_flow.md | The process itself — the eight phases from project idea to production, quality gates, roles, iteration rules. |
| som_multiplatform_spec_model.md | The SOM: the nine-language generation, the runtime/facade split, the normative markdown and YAML serializations, the validator, packaging. |
| tom_specs_model_rules.md | How the Dart source model is authored — layout, annotations, structural invariants. |
| tom_specs_model_meta_schema.md | The on-disk shape of spec_model.meta.json, the class graph every runtime loads. |
| som_generator_config.md | The generator's config block — languages, output roots, document roots. |
| som_toolchains.md | Per-language toolchains needed to build and run the generated artefacts. |
| codespecs_mapping.md | CodeSpecs: which specification section feeds which code part — the parts catalogue, attribute surfaces, generation slices. |
| codespecs_derivation_contract.md | CodeSpecs: exactly what code comes out — per-marker derivation, naming rules, validator checks. |
| codespecs_prompt.md | How a Phase-4 run starts, and the quality gate that lets it refuse to. |
| tom_specs_editor_specification.md | The spec-authoring desktop app (not part of release 1). |
| tom_specs_reviewer_specification.md | The object-model review app (not part of release 1). |
| llm_and_d4rt_tools.md | The scripting/agent engine plane (not part of release 1). |
| llm_guidelines_specification.md | The in-editor agent's context prompt (not part of release 1). |
What is in this repository
Release members (the record is tom_specs_clitool/tool/release_set.yaml, held closed by a shipped dependency-closure gate):
- The Dart chain, published on pub.dev:
tom_specs_core,
tom_specs_model, tom_specs_clitool, tom_som_dart_runtime, tom_som_dart_v0,
tom_code_specs, tom_doc_scanner, tom_doc_specs (plus tom_core_codespecs, the one chain member housed outside this repository, in the
tom_core tree). - The sixteen non-Dart packages: the eight tom_som_<lang>_runtime
/ tom_som_<lang>_v0 pairs, shipped source-only in release 1. - The conformance harness:
tom_som_conformance.
Also in this tree, but not part of release 1: tom_spec_engine, tom_specs_reviewer,
tom_ai, tom_ai_build, tom_flow_cli, tom_flow_engine. See
RELEASE_NOTES.md for why.
License
BSD 3-Clause (see LICENSE); every release package also carries its own copy.