Skip to content

Staging and slugs — where in-flight work lives

You're about to propose a spec change (Shape 1) or close gaps against one (Shape 2). Where does the in-flight state live? Not in the canonical spec files — that's the rule this page exists to explain.

Canonical specs never change mid-flight

An LLM-drafted or dev-drafted spec edit must never land on a main branch as golden state before a human signs off. So SDD skills never edit canonical spec files. Every proposed change is staged: written as a complete proposed file in a staging directory, reviewed on a feature MR, and applied to the canonical location only after every participating branch has merged.

The slug and the host repo

Each unit of work gets a date-prefixed slug (e.g. 2026-06-05-spec-docs-site) and one host repo — the repo where most of the code lands. The host carries branch sdd/{slug} and the staging directory; every other affected repo is a satellite carrying the same branch and a one-line HOST pointer stub.

<host-repo>/specs/staging/{slug}/
  rationale.md      # who & why — the four-part story behind the change
  specs/...         # FULL proposed file for each affected spec (not a diff)
  apply.json        # machine manifest: repos list + per-file base_blob guard
  edit.md           # human Before/After commentary for the MR reviewer
  tasks.md          # the commit-by-commit plan, once task-planned
  issue.json        # the dev-plan gap ids this slug adopts

Staging the full resulting file (never a prose diff) is what makes the final apply a deterministic copy rather than a fuzzy patch.

The atomic apply

Once all participating repos' sdd/{slug} branches have merged, the shipper runs helpful-scripts/sdd_apply_staged.py {slug}, which checks two guards — the all-merged barrier (no half-applied spec across repos) and the base_blob staleness guard (the canonical file hasn't drifted since staging) — then pushes the assembled spec to dev-env main. The staging directory is dropped afterwards; the durable record is the applied spec plus the merged MR.

What you can do now

  • Read any in-flight slug: find sdd/* branches across the sibling repos and open the host's staging directory — rationale.md first.
  • Tell where a slug is in its life from the staging dir's contents (rationale only → planning; tasks.md with pending tasks → implementing; all done → review/ship).