How jasoncheroske/lab-os works
1. What this repository is
Lab OS is a source seed for creating and governing “labs” — structured engineering workspaces that combine architecture intent, implementation reality, evidence, and behavioral policy. It is not a product app; it is a repository generator plus governance framework.
2. Primary architecture goal
The repo’s core function is to produce a repeatable lab scaffold that can be initialized from a template, validated against a schema, promoted through maturity stages, and packaged as a release tarball. The architecture is centered on reproducible repository bootstrapping rather than runtime request handling.
3. Main artifact model
The lab itself is organized into four major content areas:
- intent/ for target architecture
- reality/ for implementation mapping
- delta/ for gaps between intent and reality
- evidence/ for readiness checks and ADR templates
- behavior/ for governance policy and signoffs
This is the core domain boundary: architecture, execution state, gap analysis, and governance are separated on disk.
4. Template-to-instance flow
The template/ directory is the canonical starting shape for a new lab. Scripts copy or initialize this structure into a target directory, creating a working lab instance with the same logical substructure. The root-level lab/ and the example labs under examples/ demonstrate the expected instantiated result.
5. Validation boundary
schema/lab.schema.json defines the structural contract for a lab. The validation scripts enforce that a target lab has the expected shape and metadata before it can be promoted or released. This makes the schema the main guardrail between “files on disk” and “acceptable lab state.”
6. Lifecycle and promotion flow
The repo models a maturity sequence with explicit stage promotion: experiment -> poc -> pilot -> production. The promote-stage.mjs script advances a lab only when the target stage is valid. That promotion boundary is important because it prevents accidental jumps in governance maturity.
7. Tooling subsystem
The executable logic lives in scripts/:
- initialization/bootstrap
- validation
- verification
- promotion
- tarball packaging
These scripts are the operational layer that turns the documentation and templates into working artifacts. package.json wires them into the npm command surface described in the README.
8. Release packaging path
The primary release artifact is an initialized lab tarball. scripts/build-lab-tar.mjs creates the distributable archive plus checksum, and the README treats this tarball as the main user-facing output for Phase 1 release. That means the release boundary is file-based distribution, not a hosted service or package registry.
9. Documentation architecture
docs/ is not incidental; it is a first-class subsystem. It is split into:
- architecture
- governance
- runbooks
- release
- ADRs
- reference
- backlog
This indicates the repo treats documentation as executable context for governance and adoption, not merely background material.
10. Examples as living fixtures
examples/minimal-lab and examples/hybrid-governance-lab are reference instances used to prove the framework works in different complexity levels. They function as architectural fixtures: one minimal, one more policy-heavy. The validation matrix in the README explicitly uses them as regression targets.
11. Tests and quality gate
tests/generation.test.mjs is the main automated check for generation behavior. Combined with validation commands in the README, the repo’s quality strategy is to verify that generated labs are structurally correct and that release artifacts are reproducible.
12. Operational and editor integration
The .cursor/ rules and skills directory provide optional editor-assisted bootstrap support, but they are not required for the repo to function. The important point is that the same initialization and verification path works through CLI or editor automation, so the architecture is tool-agnostic at the workflow level.
13. Overall data flow
The main flow is:
template + schema + scripts → initialized lab directory → validation against schema → promotion through maturity stages → tarball release.
Documentation and examples feed back into this flow by defining expected structure, governance policy, and release readiness criteria.
14. What to diagram
An accurate architecture diagram should show:
- the source seed repo as the control plane
- template/, schema/, and scripts/ as the core engine
- generated lab instances as the output plane
- docs/ as governance and operating knowledge
- examples/ and tests/ as verification fixtures
- release tarball generation as the external distribution boundary
Main entry points: lab Lab instance · scripts Scripts · docs Docs · lab.schema.json Lab schema
Components 19
Control Plane
Repository-level source seed, contract, and orchestration
- lab-os · Repository that generates and governs lab workspaces
- Lab manifest · Root lab configuration and metadata
lab.yaml - Lab schema · Structural contract for acceptable lab shape
schema/lab.schema.json
Lab Model
Canonical lab structure and instantiated examples
- Template · Canonical starting shape for new labs
template - Lab instance · Root instantiated lab structure
lab - Intent · Desired architecture and design intent
lab/intent - Reality · Observed implementation and mapping state
lab/reality - Delta · Gaps between intent and reality
lab/delta - Evidence · Readiness evidence and ADR templates
lab/evidence - Behavior · Governance policy and signoffs
lab/behavior
Tooling
Scripts and commands that generate, validate, and promote labs
- Scripts · CLI automation for init, validate, verify, promote, and package
scripts - Init lab · Initializes lab directories from the template
scripts/init-lab.mjs - Validate · Checks lab structure against the schema
scripts/validate-lab.mjs - Promote stage · Advances lab maturity through allowed stages
scripts/promote-stage.mjs - Build tarball · Creates distributable lab tarball and checksum
scripts/build-lab-tar.mjs
Knowledge Base
Documentation that defines architecture, governance, and operating guidance
- Docs · Architecture, governance, runbooks, release, ADR, and reference documentation
docs
Verification
Fixtures and tests that prove generation and release behavior
Distribution
Packaged release artifacts and boundaries
- Release tar · Packaged lab archive for distribution
Connections 26
- lab-os → Template: seeds · Repository template defines the starting structure
- lab-os → Lab schema: governs · Schema defines the valid lab contract
- lab-os → Scripts: operates via · Scripts implement repository workflows
- lab-os → Docs: documents · Docs describe architecture and governance
- lab-os → Examples: proves with · Examples demonstrate expected instantiated labs
- lab-os → Tests: verifies with · Tests validate generation behavior
- Template → Lab instance: materializes · Template is copied into an instantiated lab
- Lab manifest → Lab instance: describes · Manifest attaches metadata to the lab instance
- Lab instance → Intent: contains · Intent captures target architecture
- Lab instance → Reality: contains · Reality captures implementation mapping
- Lab instance → Delta: contains · Delta captures gaps and mismatches
- Lab instance → Evidence: contains · Evidence captures readiness checks and ADRs
- Lab instance → Behavior: contains · Behavior captures governance policy and signoffs
- Scripts → Init lab: executes · Bootstrap script initializes lab instances
- Scripts → Validate: executes · Validation script checks against schema
- Scripts → Promote stage: executes · Promotion script advances maturity stages
- Scripts → Build tarball: executes · Packaging script builds release artifact
- Validate → Lab schema: checks against · Validation enforces the lab contract
- Promote stage → Behavior: gates by · Promotion depends on governance maturity
- Build tarball → Release tar: produces · Build creates the distributable archive
- Examples → Lab instance: mirror · Examples act as reference lab instances
- Tests → Template: regressions for · Tests exercise generation from the scaffold
- Tests → Lab schema: asserts · Tests confirm generated structure matches contract
- Docs → Lab schema: defines · Architecture docs explain the lab contract
- Docs → Behavior: guides · Governance docs define policy and maturity
- Docs → Release tar: supports · Release docs describe packaging and launch readiness