See it work, then use it

The quickest way to understand TomSpecs is to watch one small project go from idea to code. After that, the Dart packages on pub.dev let you validate, read and write specification documents in your own project.

You need the Dart SDK 3.11 or newer and git.

1 · Watch one project go from idea to code

The walkthrough sample takes a small project through Phases 1 to 6: the free-form idea, the Blueprint, two detailed specifications, the CodeSpecs trio, the derived tests and the implementation - with all six gates actually run, and a failing gate stopping the walk.

git clone https://github.com/al-the-bear/tom_ai_build.git
cd tom_ai_build/tom_specs_samples/full_lifecycle_walkthrough
dart pub get
dart run

It stops at G6 and says why: Phases 7 and 8 need a deployment and a human signature, which a sample cannot carry. Read its README beside the output.

2 · Validate a specification document

Add the packages to a Dart project - the runtime and the generated model for reading and writing documents, the CLI tools as a dev dependency:

dart pub add tom_som_dart_v0 tom_som_dart_runtime dev:tom_specs_clitool

Then check a document on all three tiers - it decodes against the model, it is complete against its DocSpecs schema, its values and references are valid. The tool takes a *.docspecs.yaml or a rendered *.md of any of the fourteen document types and detects which one it is:

dart run tom_specs_clitool:validate_spec my_blueprint.docspecs.yaml

validate_spec my_blueprint.docspecs.yaml — root D00SolutionBlueprint (SBP), schema solution-blueprint
decode   0 finding(s)
schema   0 finding(s)
instance 0 finding(s)
validate_spec: all three tiers clean

No document of your own yet? The Meridian Order Management Blueprint is a complete example to validate, read and change. Exit code 0 means clean, 1 findings, 2 bad usage; --json writes a machine-readable report, --markdown-out the Markdown rendition.

3 · Write a document in code

A document is a sparse tree addressed by section-id paths. This writes two values into a Solution Blueprint and serializes it to the YAML form the validator reads:

import 'package:tom_som_dart_runtime/tom_som_dart_runtime.dart';
import 'package:tom_som_dart_v0/tom_som_dart_v0.dart';

void main() {
  final doc = SpecDocument();
  doc.setContent('SBP/content', 'A platform that unifies our order systems.');

  const metrics = 'SBP/currentLandscape/CUOPME-OPER-LST';
  final item = doc.addListItem(metrics);
  doc.setContent('$item/content', 'Average order turnaround: 4.2 days.');

  print(SpecDocumentYaml.encode(
      document: doc, tree: d00SolutionBlueprintMetaTree, modelVersion: '1.0'));
}

The same document can be written through the generated typed classes, with named getters and setters instead of paths, and inspected through the model's metadata. The package's examples show all three access paths side by side.