Skip to content
decree

sprint execution — track active work without merge conflicts

decree sprint tracks what is actively being built without turning sprint state into one shared merge-conflict file. In v3, the sprint store is a directory: state.yaml for lifecycle state, one live/<DOC-ID>.yaml file per membership, and one closed/<SPRINT-ID>.yaml archive per closed sprint.

Scenario Two worktrees both create or finish sprint items while the sprint is active.

Without decree

With a single decree/sprints/ledger.yaml, every worker edits the same YAML list. The SPEC file and its sprint enrollment must land together, so parallel work turns into a merge-conflict queue. A finished item also has to wait for full sprint rollover before it can be recorded as done.

With decree

Each active item owns one live/<DOC-ID>.yaml file. Completing one item rewrites only that item, records a snapshot, and moves it out of the open sprint scope:

Terminal window
$ decree sprint complete SPEC-00000000000000000000000001 --commit abc1234
[sprint] recorded completed outcome for SPEC-00000000000000000000000001 (primary 2/2)
✓ sprint item completed
→ exit 0

VALUE Routine sprint work becomes a file union: different worktrees add or complete different documents by touching different paths.

HONESTY Rollover is still an integration ceremony. v3 removes the routine ledger hotspot; it does not introduce multiple active sprints or per-worktree lanes.

Operator flow

Section titled “Operator flow”

The HTML board is for the human orchestrator, not an agent protocol. Agents should use the CLI or MCP tools so their loop can branch on exit codes and JSON. A typical parallel sprint looks like this:

  1. Refresh the read-only board when a human wants the current picture.

    Terminal window
    decree generate-html --output decree-board.html
    decree sprint move SPEC-01KT22NMS0D19VMD8VPK4D2MNX --to active

    Open the file locally, choose an open sprint item, and assign that document ID to an agent. The board is an inspection surface: it does not mutate sprint state. Use sprint move when a backlog or draft-pool item becomes current-sprint work.

  2. Let the first worker scope itself to one item.

    Terminal window
    decree ddd --doc SPEC-01KT22NMS0D19VMD8VPK4D2MNX
    decree intent-check --plan "implement token storage" \
      --files src/auth/tokens.py \
      --under SPEC-01KT22NMS0D19VMD8VPK4D2MNX

    The agent starts only after the governing scope and plan check are clear.

  3. Start another worker in another worktree on a different sprint item.

    Terminal window
    git worktree add ../my-app-token-rotation -b work/token-rotation
    cd ../my-app-token-rotation
    decree ddd --doc SPEC-01KW2BEQ5J7JWM93K4YAS9GZAB

    Because each sprint membership is its own live/<DOC-ID>.yaml, the two workers do not race on one shared ledger.yaml.

  4. Record completion per item, then integrate.

    Terminal window
    decree sprint complete SPEC-01KT22NMS0D19VMD8VPK4D2MNX --commit abc1234
    decree lint

    After branches merge, the orchestrator runs decree lint, refreshes the board if useful, and performs rollover once from the integration branch.

Run it

Section titled “Run it”

The active sprint reports open work from the v2 directory store:

Terminal window
$ decree sprint status
✓ sprint status reported
Sprint mode: active
Active: SPRINT-00000000000000000000000001 Sprint 1 (1 items)


Tasks:
  SPEC-00000000000000000000000001 (manual)
Backlog: 0 items
Draft pool: 0 items
→ exit 0

How it composes

Section titled “How it composes”
  • decree progress and decree ddd default to the active sprint’s open items when sprint mode is enabled. Use --corpus for the whole repository, or --sprint ID to include resolved active items.
  • decree sprint complete DOC-ID records a completed outcome mid-sprint after the document’s primary acceptance criteria reach 100%.
  • decree sprint drop DOC-ID --reason TEXT records an auditable dropped outcome.
  • decree sprint move DOC-ID --to active|backlog|draft-pool promotes backlog or draft-pool work into the active sprint, or moves an open active item out with a reason.
  • decree sprint rollover --outcomes FILE closes the still-open items and folds completed or dropped items into the archive.
  • decree migrate sprint-ledger --apply converts old v1 repositories and removes the monolithic ledger.yaml.

When you’d reach for this

Section titled “When you’d reach for this”
  • Parallel agent worktrees — each agent owns its SPEC file and its one sprint membership file.
  • Mid-sprint review — finished work can leave the open progress scope without closing the whole sprint.
  • Release cleanup — migrate old projects once, then let decree lint enforce the v2 invariants.

Exit codes

Section titled “Exit codes”

Sprint commands exit exit 0 clean · advisory-only when the operation is valid. Invalid state, such as trying to complete an item below 100% primary progress or running sprint commands against an unmigrated v1 ledger, exits exit 2 config error as a configuration/usage error rather than a governance finding.

Next: the lifecycle for corpus validation, or decree by example for the full governance loop.