Workflow — Backlog and Sprints

init generates a workflow from three files: the instruction file (CLAUDE.md or AGENTS.md), TASKS.md (what we're doing now), and BACKLOG.md (what we're doing later). Shared TASKS/BACKLOG are written once even with --harness both. Without structure, those files rot. TASKS.md balloons past 200 lines, BACKLOG.md becomes a dumping ground, and the same work package ends up in both files at once.

v1.10.0 ships three things to stop the rot: a typed work-package template, a path-scoped rule file Claude auto-loads when editing those files, and a PostToolUse hook that injects staleness warnings into context (five conditions).

The single rule

A work package (WP) lives in exactly one of BACKLOG.md or TASKS.md at any time.

• Pulled into a sprint → move (delete from BACKLOG, add to TASKS) in a single edit.
• Sprint closed → the WP leaves TASKS entirely (summarized into Completed Sprints) and does not return to backlog.
• A WP ID appearing in both files at once is a drift bug. The workflow hook catches it.

Everything else in this page enforces that rule.

BACKLOG.md template

init (and doctor --fix, when BACKLOG.md is missing) writes this structure:

# <project> — Backlog

> Single source of truth for future work. Rules in .claude/rules/workflow.md (Cursor: .cursor/rules/workflow.mdc).

## Priority definitions
| Priority | Meaning |
|---|---|
| **P0** | Blocks launch or an active sprint. Next sprint or sooner. |
| **P1** | Important for MVP. Pulled within 2–3 sprints. |
| **P2** | Post-MVP or nice-to-have. Review monthly. |
| **P3** | Parked idea. Review quarterly; delete if still untouched. |

## Work package template (copy this exactly)
### WP-NNN — <short imperative title>
- **Priority:** P0 | P1 | P2 | P3
- **Proposed:** YYYY-MM-DD
- **Stories / Docs:** links to specs, issues, or "none yet"
- **Depends on:** WP-MMM (empty if none)
- **Estimate:** XS (<1h) | S (half-day) | M (1–2 days) | L (full sprint) | XL (>1 sprint; must decompose)
- **Trigger to pull:** What has to be true before this moves into a sprint.
- **Definition of done:** Exactly what "done" looks like.

One-paragraph description.

## P0 — Next sprint
## P1 — Soon (within 2–3 sprints)
## P2 — Post-MVP / nice-to-have
## P3 — Parked
## Changelog

Every WP entry must include all 7 fields. Free-form entries are a drift signal. XL estimates must be decomposed before they can enter a sprint.

TASKS.md discipline

## Current Sprint holds only the active sprint's WPs. Between sprints it's empty. That's the canary that tells you the last sprint closed cleanly.

# <project> — Task Tracker

> Under 80 lines. Session log: 3 entries max. ## Current Sprint empty between sprints.

## Current Sprint
<!-- EMPTY. Pull WPs from BACKLOG.md when ready. Format: - [ ] WP-NNN — short title -->

## Completed Sprints
<!-- One line per sprint. Detail lives in git history. -->

## Session Log
<!-- Most recent first. Max 3 entries. -->

Path-scoped workflow rules

Claude Code auto-loads .claude/rules/workflow.md only when editing BACKLOG.md or TASKS.md:

---
paths: ["BACKLOG.md", "TASKS.md"]
---

# Backlog → Tasks → Sprint Workflow Rules
...

Cursor Agent uses .cursor/rules/workflow.mdc with globs: frontmatter for the same files. The rule body is the same single-rule / WP-template / sprint lifecycle contract.

Doctor flags MEDIUM when the file is missing; doctor --fix writes the harness-correct path.

Why path-scoped rules matter

A monolithic instruction file grows past the 200-line budget fast. Path-scoped rule files keep per-domain conventions close to the files they govern. Claude Code uses YAML paths: [...]; Cursor uses globs:.

init generates scoped conventions and workflow rules for the selected harness. Add your own — Swift rules under paths: ["ios/**"] or Cursor globs: ios/**, backend rules under api/**.

Sprint lifecycle

Starting a sprint

1. Pick the top-priority WPs from BACKLOG (P0 first, then P1 if P0 is empty).
2. Same edit: delete from BACKLOG.md, add to TASKS.md ## Current Sprint as - [ ] WP-NNN — short title.
3. Append to BACKLOG.md ## Changelog: YYYY-MM-DD: WP-NNN pulled into Sprint N.
4. Write your sprint plan (outline approach + success criteria).
5. Commit the pull + plan together.

Closing a sprint

1. All ## Current Sprint items checked off, or explicitly moved back to BACKLOG with rationale.
2. Run your review workflow. Verify tests, typecheck, and convention compliance before declaring done.
3. Add one-line summary to ## Completed Sprints.
4. Empty ## Current Sprint back to its placeholder comment.
5. Update ## Session Log (prune to 3 entries).
6. Append to BACKLOG.md ## Changelog: YYYY-MM-DD: Sprint N closed. WP-NNN done.

The workflow-check hook

init installs a staleness hook: Claude Code uses PostToolUse at .claude/hooks/workflow-check.sh; Cursor Agent uses postToolUse at .cursor/hooks/workflow-check.sh. It fires on every edit to BACKLOG.md or TASKS.md and warns (never blocks) on five conditions:

Warnings are injected into the model's context as PostToolUse additionalContext JSON — bare hook stdout only reaches the transcript view, so pre-v1.12 warnings were invisible to Claude. The hook still always exits 0: it informs, never blocks.

A second hook, sprint-open-check.sh, runs after git commit and warns (same JSON mechanism) when a commit pulls WPs into the sprint without deleting anything from BACKLOG.md — with a git commit --amend suggestion while the fix is still cheap.

Doctor flags LOW when either hook is missing; doctor --fix installs the scripts and settings entries together. Deeper batch audits (WP template completeness, stale P0 items, changelog silence) live in doctor's Workflow analyzer, which runs whenever BACKLOG.md exists.

Next