Documentation

The reference documents

The TomSpecs documentation lives with its sources on GitHub. Each document is the single authority for its subject; this page says which one to read for which question.

Start with the walkthrough sample if you are new: it shows the whole method on one small project before you read any of these.

The method

Document	Read it for
Project flow	The whole process: the eight phases with inputs, activities and outputs, every gate with its criteria and check methods, quality inside a phase, review rounds, roles, tooling, the issue workflow and upgrade cycles.
Gate checklists	How a gate is executed: the generic checklists, a project's own checklist, the gate report and where its evidence is kept.

The specification object model

Document	Read it for
The SOM	What the model becomes in nine languages: the facade and runtime split, the metadata tree, the Markdown and YAML formats, schema generation, validation, review annotations and team review rounds.
Model rules	How the model is authored: classes and fields, forms, section ids, headlines, annotations, traceability and the structural invariants the validator enforces.
Metadata schema	The shape of `spec_model.meta.json`, the resolved class graph every runtime reads.
Outlines	The class tree of each of the fourteen document types, generated from the model.
Documentation index	All of it, including the generator configuration, the toolchains and every package's own documentation.

CodeSpecs

Document	Read it for
Starting prompt	When a Phase-4 run may begin: the mechanical checks, the per-area sufficiency verdict, and the todo tree it creates.
Mapping	Which specification section feeds which code part: the parts catalogue, the generation slices, the production model with its extract artifact, and the bidirectional link between documents and code.
Derivation contract	What code comes out: per annotation the inputs, the exact Dart emitted, the naming rules, a worked example, and the checks `validate_codespecs` runs.

Using the tools

Document	Read it for
Validating a document	`validate_spec`: the three tiers, fragments of one document, the JSON report.
CLI tools	Every command of `tom_specs_clitool`.
Dart facade	The typed access path in Dart, its tutorial and its examples. The other eight languages have the same pair of packages beside it.
DocSpecs	Schema validation of structured Markdown.
Agent workflow	How an agent in VS Code reads, edits and checks a specification and takes it through Phase 4, tool by tool.
Extension user guide	The Tom AI extension: chat, prompt queue, process view, todos and the rest.
Spec editor	The specification of the desktop editor, which is in development.