Skip to content

README.md

Latest commit

 

History

History
106 lines (76 loc) · 3.87 KB

README.md

File metadata and controls

106 lines (76 loc) · 3.87 KB

Workstreams

This directory exists to make parallel implementation safe.

Model

  • one ADR can have one or more implementation workstreams
  • one chat thread should usually work on one workstream
  • one active workstream should usually have one dedicated branch and one dedicated git worktree
  • workstreams.yaml is the machine-readable registry
  • the files in this directory are the human-readable handoff documents
  • protected release files are reconciled later on main, not continuously on every branch
  • active workstreams must declare an ownership_manifest in workstreams.yaml

Branch Boundaries

Workstream branches are expected to update:

  • implementation code for their own scope
  • their own ADR changes if needed
  • their own runbook material
  • their own workstream file
  • their own workstreams.yaml entry
  • surfaces declared in their ownership_manifest as exclusive or shared_contract
  • validation surfaces when their work changes the minimum merge gate

Workstream branches should avoid updating:

  • VERSION
  • changelog.md and docs/release-notes/
  • canonical observed-state sections in versions/stack.yaml
  • top-level integrated summaries in README.md
  • any path that is outside the branch's declared ownership manifest

Those are integration surfaces and should normally be updated only when work is merged to main.

Canonical Truth Metadata

When a workstream should feed the integration-only canonical outputs, add a canonical_truth block to its workstreams.yaml entry.

  • changelog_entry supplies one assembled ## Unreleased bullet
  • release_bump declares the minimum repo version bump for that workstream
  • included_in_repo_version stays null until the release manager cuts the version that includes the workstream
  • latest_receipts maps capability IDs to the live-apply receipt that should appear in versions/stack.yaml

Minimum Merge Gate

Before a workstream is merged to main, the minimum repository validation command is:

make validate

If a workstream intentionally adds a new validation stage, update the validation script, CI workflow, and the validation runbook in the same change.

Required Fields Per Workstream

Each workstream document should record:

  • ADR reference
  • branch name
  • worktree path
  • status
  • dependencies
  • conflicting workstreams
  • shared surfaces
  • intended files to touch
  • live surfaces to touch
  • verification commands
  • merge criteria
  • the machine-readable manifest lives beside it in workstreams.yaml

Ownership Modes

  • exclusive: only one active workstream may mutate the surface
  • shared_contract: multiple workstreams may mutate the surface only through a declared contract id
  • generated: the surface is reserved for generators or integration assembly, not branch-local edits
  • read_only: the workstream may depend on the surface but may not modify it

Status Meanings

  • ready: queued and available to pick up
  • in_progress: actively being implemented in a branch
  • blocked: cannot continue until a dependency or external input is resolved
  • implemented: repository implementation is complete but not yet treated as merged canon
  • ready_for_merge: implementation is complete and waiting for integration
  • merged: merged to main
  • live_applied: merged and applied to the real platform

Starting A Workstream

Preferred entry point:

make start-workstream WORKSTREAM=adr-0011-monitoring

This uses scripts/create-workstream.sh to:

  • read the branch and worktree path from workstreams.yaml
  • create the worktree if it does not exist
  • attach it to the correct codex/ branch

Template

Use TEMPLATE.md for new workstreams.