Ordo defines the model for artifact-first, stage-aware, AI-assisted development.

Ordo defines semantic truth for:

• stages
• artifacts
• semantic state
• validation
• gates
• finalization meaning

This repository is the reference implementation of that semantic layer. Workflow execution and operator surfaces live in a separate runtime layer.

Ordo is the semantic layer behind an Ordo-managed workflow.

More concretely, it is the system layer that keeps artifact-driven work in a known, controlled state while execution continues elsewhere.

It defines:

• the artifact model for canonical, domain, decision, and session
• stage semantics and semantic state
• truth, gate, and finalization rules
• authority boundaries for evidence, accepted decisions, promotion candidates, canonical truth, and compiled context views
• semantic rendering for plan/build artifacts
• reference docs and reference tooling around the model

Current implementation note:

• flat-workspace finalization meaning is implemented
• docs-layout finalization is still transitional

Ordo is not the main workflow and orchestration layer.

It does not own:

• staged execution control
• agent and tool invocation
• retries, resume, and runtime recovery
• operational approval routing
• the main user-facing CLI/TUI experience

Those belong to a separate runtime layer.

• canonical: current durable repo-wide truth, curated over time
• domain: bounded contracts and operating boundaries
• decision: explicit architectural commitments
• session: bounded exploratory or implementation work plus the current session summary

Ordo also defines a few semantic lifecycle rules that the runtime must respect.

• canonical is current truth, not immutable history
  • immutable project history belongs in finalized reports and canonical history records
• session is a living project summary, not an append-only log
  • it should keep current intent, current stage, accepted decisions, latest outcome, and next actions aligned with the present workflow state
• rerunning an earlier stage invalidates downstream truth derived from the older path
  • downstream artifacts after that stage become stale and must stop contributing to semantic state
  • runtimes are therefore expected to maintain a coherent current artifact set by clearing, replacing, or otherwise withdrawing stale downstream artifacts
• finalize and canonical curation are separate meanings
  • finalize closes bounded project execution
  • promote-knowledge is the primary explicit boundary for accepting repo-wide current truth
  • promote-canonical and promote_canonical remain compatibility names for existing tooling and artifacts
• cross-run memory and retrieval are split by responsibility
  • Ordo defines authority semantics for source artifacts and compiled context views
  • a runtime layer executes retrieval, selection, context injection, and usage tracing

• Ordo defines the model.
• Ordo defines semantic truth.
• A separate runtime layer executes workflows around that model.
• Operator-facing CLI, TUI, web, and automation surfaces belong outside this repository.

More detail lives in docs/relationship-to-ordo-flow.md.

If you only read four things before evaluating the model, read these:

1. Decision taxonomy
   • what counts as a real decision vs an open question vs scaffold
2. Canonical operations
   • when current truth should be promoted and how subject/scope are chosen
3. Finalize and drift
   • how stale downstream artifacts are handled and what finalize actually means
4. Happy path demos
   • two short walkthroughs that show the model in practice

If you want the system boundary after that, read docs/deterministic-boundary.md.

• model and semantic reference: this repository
• workflow and orchestration layer: separate runtime layer

• pkg/core: semantic core package used for workspace opening, artifact resolution, validation, semantic state, finalization meaning, and plan/build rendering
• internal/cli: reference CLI and governance tooling around the model; this is not the main product CLI
• docs/: model, stages, artifacts, truth/gates, and relationship references
• cmd/ordo: reference CLI entrypoint

This repository should read as a model and reference repository first.

The CLI still exists and is useful, but it is not the primary product surface. The primary product surface belongs to the separate runtime layer.

This repository is public as a semantic model and reference implementation.

Stable public commitments:

• artifact roles and authority boundaries
• accepted bounded truth versus promoted repo truth
• finalize and knowledge promotion as separate lifecycle meanings
• compiled context views are evidence-linked views, not truth sources

Evolving implementation surfaces:

• pkg/core Go APIs
• reference CLI command shape and output text
• transitional docs-layout finalization behavior

Use pkg/core as a reference implementation API for now, not as a v1-stable library contract.

The ordo CLI remains useful for reference and governance-oriented tasks such as:

• initializing repository-local Ordo docs
• creating canonical/domain/decision/session artifacts
• compiled context view generation and reference workflow scaffolding
• indexing and navigation
• session and decision governance helpers

Build locally with:

go build -o ordo ./cmd/ordo
./ordo --help

go test ./...
go build ./cmd/ordo

• semantic core and reference repository
• evolving split with the runtime layer
• not positioned as the main workflow and orchestration layer