Create target repository folders:
Roadmap
Actual repository roadmap
Completed and planned items are read from `docs/TASKS.md` at build time.
Expand `README.md` with:
Add `CONTRIBUTING.md`.
Add `CODE_OF_CONDUCT.md`.
Add `docs/specification.md`.
Add `docs/cli.md`.
Add `docs/generators.md`.
Add `docs/examples.md`.
A new reader can understand the project from the README without opening the PRD.
The comparison matrix is present in the README.
Empty placeholder directories are avoided unless they contain useful starter files.
Define common semantic object fields:
Create `schemas/semantic-object.schema.json`.
Create `schemas/entity.schema.json`.
Create `schemas/metric.schema.json`.
Create `schemas/domain.schema.json`.
Create `schemas/glossary-term.schema.json`.
Create `schemas/relationship.schema.json`.
Create `schemas/quality-expectation.schema.json`.
Define allowed lifecycle statuses.
Define allowed classification values.
Add schema examples for each object kind.
Add template YAML files for each object kind.
Every schema validates at least one positive fixture.
Every schema rejects at least one invalid fixture.
Every template has comments or obvious placeholder values.
All core schemas include `extensions`.
Create `examples/supply-chain/README.md`.
Add supply chain domains:
Add core entities:
Add core metrics:
Add glossary terms for core business concepts.
Add relationships across entities.
Add quality expectations for critical entities and metrics.
Add AI context fields for entities and metrics.
The supply chain example passes schema validation.
The supply chain example has no broken references.
At least three domains, five entities, and three metrics are represented.
Generated documentation from the example is useful to a business reader.
Choose CLI implementation language and package structure.
Create CLI package scaffolding.
Add local development setup instructions.
Implement command routing for:
Implement standard exit codes.
Implement consistent error formatting.
Add `--help` output for each command.
Add package metadata so the CLI can be installed locally.
Running `semantics --help` shows available commands.
Running an unknown command returns exit code `2`.
CLI commands accept a path argument.
CLI output is readable in local terminals and CI logs.
Implement recursive YAML file discovery.
Parse YAML files with source path tracking.
Select schema based on the `kind` field.
Build an in-memory semantic registry.
Normalize object ids.
Detect duplicate object ids.
Track object kind, path, and parsed content.
Add unit tests for registry loading.
Invalid YAML returns an actionable parse error.
Duplicate ids fail validation.
Unknown object kinds fail validation.
Source file paths appear in error messages.
Implement JSON Schema validation.
Implement required-field validation through schemas.
Implement reference validation for:
Implement classification validation.
Implement lifecycle status validation.
Add invalid fixtures for every validation rule.
Add tests for every validation rule.
`semantics validate examples/supply-chain` exits with `0`.
Invalid fixtures exit with `1`.
Validation messages include file path, rule id, and message.
Broken references identify both the source object and missing target.
Implement `SAC-LINT-001`: meaningful description.
Implement `SAC-LINT-002`: owner required.
Implement `SAC-LINT-003`: steward recommended for governed objects.
Implement `SAC-LINT-004`: quality expectations recommended for critical objects.
Implement `SAC-LINT-005`: AI context recommended for entities and metrics.
Implement `SAC-LINT-006`: consistent name casing.
Add severity handling for warnings and errors.
Add tests for each lint rule.
`semantics lint examples/supply-chain` exits with `0` or documented warnings only.
Lint output distinguishes errors from warnings.
Lint rule ids are stable and documented.
Implement generator interface.
Implement Markdown generator target.
Generate `index.md`.
Generate `domains.md`.
Generate `entities.md`.
Generate `metrics.md`.
Generate `glossary.md`.
Generate `relationships.md`.
Include source file paths in generated docs.
Include ownership, stewardship, governance, quality, and AI context.
Add generator tests with snapshot or fixture assertions.
`semantics generate examples/supply-chain --target markdown --output dist/docs` creates expected files.
Generated docs include all supply chain entities and metrics.
Generator fails clearly when the output path is invalid.
Add unit test framework.
Add positive schema fixtures.
Add negative schema fixtures.
Add registry tests.
Add validation tests.
Add lint tests.
Add generator tests.
Add integration test for the supply chain example.
Test command passes locally.
Tests can run without network access.
Test fixtures are small and easy to understand.
Add GitHub Actions workflow at `.github/workflows/validate.yml`.
Install CLI dependencies.
Run unit tests.
Run `semantics validate examples/supply-chain`.
Run `semantics lint examples/supply-chain`.
Run Markdown generation as a build check.
Upload generated docs as an optional artifact.
Workflow runs on pull requests.
Workflow runs on pushes to `main`.
CI fails on invalid YAML.
CI fails on broken semantic references.
Document semantic object model.
Document entity YAML.
Document metric YAML.
Document domain YAML.
Document glossary term YAML.
Document relationship YAML.
Document quality expectation YAML.
Document CLI usage.
Document generator usage.
Document extension model.
Document schema versioning.
Docs explain all fields used in templates.
Docs include copy-pasteable examples.
Docs distinguish Version 0.1 features from roadmap features.
README is complete.
PRD is complete.
Design doc is complete.
Task backlog is complete.
Core schemas are present.
Templates are present.
Supply chain example is present.
CLI validates schemas.
CLI validates cross-references.
CLI lints semantic definitions.
CLI generates Markdown docs.
Tests pass.
GitHub Actions workflow passes.
Release notes are drafted.
Version tag is created.
Add Mermaid diagram generator.
Add HTML documentation generator.
Add dbt Semantic Layer generator.
Add OpenMetadata generator.
Add AI context file generator.
Add additional industry examples.
Add semantic package manifest.
Add configurable lint rules.
Add `semantics diff`.
Add knowledge graph generation.
Add OpenMetadata integration tests.
Add dbt integration tests.
Add package dependency support.
Add richer metric formula validation.
Add VS Code extension prototype.
Stabilize specification versioning policy.
Add compatibility test suite.
Add vendor adapter API.
Add Databricks adapter.
Add Snowflake adapter.
Add Fabric adapter.
Add BigQuery adapter.
Add OpenMetadata adapter.
Add Apache Iceberg, Polaris, and Gravitino metadata mappings.
Publish formal specification documentation.
Expand README with positioning and comparison matrix.
Create core folder structure.
Create entity, metric, and domain schemas.
Create entity, metric, and domain templates.
Create a small supply chain example with three entities and two metrics.
Implement basic CLI validation.
Add GitHub Actions validation workflow.