Skip to main content
rule CX Codex

backlog — Claude Code rule for task status tracking

This rule keeps task statuses aligned across BACKLOG.md and TASK_STATUS.md and sets checks for moving work to merged. Use it in projects that track tasks in these files.

Apache-2.0 ★ 121 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/backlog.md
Open on GitHub

What backlog does

Every status change must appear in both files before the turn ends, and a task cannot enter Active Wave without a matching TASK_STATUS.md entry. Moving a task to merged requires QA evidence recorded in TASK_STATUS.md. A PostToolUse hook runs the validator after edits, so check its output before continuing.

For cross-repository gates, the rule uses Blocked by: and docs/REPO_MAP.md; this is distinct from Depends on: for work in the same repository. Task IDs are sequential, and retired IDs stay retired. The validator skips archived tasks, so active work belongs elsewhere.

Acceptance criteria must not claim a verification command or expected output that has not been tested. Record the observed result, or mark the check UNEXECUTED. For Claude Code, place the rule at .claude/rules/backlog.md.

What it helps with

  • keep statuses aligned in BACKLOG.md and TASK_STATUS.md
  • require QA evidence before marking a task merged
  • check cross-repository gates before a merge
  • avoid reusing retired task IDs
  • flag unrun checks in acceptance criteria

Example prompts for the agent

  • Check whether task statuses match in BACKLOG.md and TASK_STATUS.md.
  • Before marking this task merged, verify its QA evidence in TASK_STATUS.md.
  • Review this task’s Blocked by: entries using docs/REPO_MAP.md.

How to install backlog

Manually: put the files in place

.claude/rules/backlog.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about backlog

How do I install backlog in Claude Code?

Add the rule file to the project at .claude/rules/backlog.md.

What does the backlog rule do?

It sets requirements for syncing BACKLOG.md with TASK_STATUS.md, recording QA evidence before merged, and handling cross-repository blockers.

How is Blocked by: different from Depends on:?

Blocked by: defines a cross-repository merge gate resolved through docs/REPO_MAP.md. Depends on: refers to a dependency within the same repository.

Source text

backlog.md · Apache-2.0
---
paths:
  - "BACKLOG.md"
  - "TASK_STATUS.md"
---

# Backlog and Task Status Rules

- Every status change in BACKLOG.md must be mirrored in TASK_STATUS.md active tasks (and vice versa) before the turn ends.
- Never set status to `merged` without QA evidence recorded in TASK_STATUS.md.
- Never add a task to BACKLOG.md Active Wave without a matching entry in TASK_STATUS.md.
- After any edit to these files, the validator runs automatically via PostToolUse hook — check its output before proceeding.
- Archived tasks in `## Wave N — Archived` are not compared by the validator; do not put active tasks there.
- Task IDs are sequential integers (T-NNN). Never reuse a retired ID.
- `- **Blocked by:** <repo>/T-NNN` declares a cross-repo merge gate: the validator resolves `<repo>` via `docs/REPO_MAP.md` and blocks (or warns) merge until the referenced task in that repo is `merged`. Do not confuse with same-repo `Depends on:`.
- No-blockers convention: when a task has no cross-repo blockers, either omit the `Blocked by:` field entirely or set it to the standard em-dash (`—`) or plain hyphen (`-`) placeholder — both are treated as "no blockers", never as `blocked_by_unresolvable`. The gate only evaluates `Blocked by:` at gated statuses (`ready_for_qa`, `qa_passed`, `merged`), so a genuinely malformed value will not be reported until the task reaches one of those statuses.
- `- **Hold:** <what> — <why> (<since>)` (DR-005) marks a task as deliberately held, never mandatory and its absence is never a finding. It may downgrade ONLY `blocked_by_open`, and never a FAILURE-severity finding — `merged` × unmerged-blocker stays FAILURE/exit 2 regardless. It can never touch `merged_missing_commit_field`, evidence-completeness, mirror/sync-status, duplicate-entry detection, `config_check`, or `stale_verified` — see `HOLD_DOWNGRADABLE_CHECKS` in `mavp-validator.js`, a whitelist, not a blacklist of protected checks.
- Never register a verification command, named mutant, or expected-output claim in acceptance criteria without executing it first — quote the observed output, or label it `UNEXECUTED — verify before relying`. See `docs/core/ORCHESTRATION_RULES.md` — "Executed-check rule" for the full rule, the fixture-vs-live-reproduction distinction, and why no mechanical enforcement exists.
- **Task-ID citation discipline (T-593)** — `getNextTaskId()` (`scripts/mavp-operator-lib.js`) scans both artifacts for the highest heading with an anchored `/^###\s+T-(\d+)/gm`: it only matches a real heading sitting at the very start of a line. After T-593, a backticked, **mid-line** citation of another task's heading — e.g. a mid-sentence, backticked example such as `T-900` quoted inside a Problem/Notes bullet — is SAFE and will never be scanned. The residual ban is narrower and still real: never write the literal shape `###` immediately followed by `T-` and digits as the FIRST characters of a line anywhere in `BACKLOG.md` or `TASK_STATUS.md`, including inside a fenced code block — the scan is line-based with no fence-tracking, so a line-initial match there is indistinguishable from a real heading and will mint a duplicate/jumped ID. A mint-time tripwire (non-blocking stderr warning naming both values) covers this fenced-block residual when it slips through; it is a safety net, not a license to write the shape carelessly.

© yahor-punko · Apache-2.0 · yahor-punko/mavericks-os

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set16

The whole set →
validate validate runs the MavP validator to verify artifact synchronization between BACKLOG.md and TASK_STATUS.md before starting new tasks. CX Codex +1 ★ 121repo stars product-docs The product-docs subagent creates and updates internal project documentation: agent specs, process templates, and decision artifacts. CX Codex ★ 121repo stars technical-writer technical-writer — a Mavericks OS subagent focused on user-facing docs. Prepares getting started guides, API references, and release notes without editing project code. CX Codex ★ 121repo stars ux ux reviews interfaces, CLI output, and documents for clarity and scan order. It returns recommendations without editing files. CX Codex ★ 121repo stars ui-designer An autonomous UI designer that inspects Figma files, extracts tokens, creates Code Connect mappings, and exports assets. It never touches source code. CX Codex ★ 121repo stars frontend-design frontend-design — a subagent for production web UI implementation in Claude Code and Codex. Builds responsive interfaces with intentional typography, CSS variables, and zero generic SaaS styling. CX Codex ★ 121repo stars security-reviewer security-reviewer audits changed code for security issues and reports specific fixes. Use it when work touches API routes, file parsers, authentication, or third-party integrations. CX Codex ★ 121repo stars analyst analyst — a subagent for outside research: libraries, competitor moves, pricing, standards. It returns a structured brief to help you decide, not a pile of links. CX Codex ★ 121repo stars

Project sponsors

Companies that keep this analytics open