| name | cwf-backlog-manager |
| description | Show or manipulate the project backlog/changelog. Examples: "what's in the backlog", "add a backlog entry for X", "retire item Y for task N". |
| user-invocable | true |
| allowed-tools | ["Bash"] |
Scope & Boundaries
This step: Use .cwf/scripts/command-helpers/backlog-manager to read or mutate BACKLOG.md / CHANGELOG.md from the repo root.
Not this step: Editing BACKLOG.md or CHANGELOG.md directly with Edit / Write (the helper enforces the heading-tree contract; direct edits skip validation and risk corrupting the format).
Context
Helper path: .cwf/scripts/command-helpers/backlog-manager (relative to git root).
Subcommands
Each invocation must use list-form arguments (separate Bash array elements), never an interpolated single-string command. Argument values containing shell metacharacters — $, backticks, (, ), ;, & — will be expanded if interpolated. Treat user input as opaque strings and pass them as separate elements.
validate [--all] [--strict]
Check the format of BACKLOG.md and CHANGELOG.md. Default: print first error and exit 1. --all prints every error. --strict escalates warnings to errors. Warnings always print.
.cwf/scripts/command-helpers/backlog-manager validate --all
list [--all-items]
Show active BACKLOG entries grouped by priority. Default: top 20 (no priority band split). --all-items shows everything.
.cwf/scripts/command-helpers/backlog-manager list
add --title=TITLE --task-type=TYPE --priority=PRI (--body=TEXT | --body-file=PATH) [--status=TEXT] [--identified-in=TEXT]
Append a new active entry to BACKLOG.md. --task-type ∈ feature|bugfix|hotfix|chore|discovery; --priority ∈ Very High|High|Medium|Low|Very Low.
Worked example with shell-metacharacter title (note the list form: each argument is separate, the title is not interpolated into a string):
.cwf/scripts/command-helpers/backlog-manager add \
--title='Test $(date)' \
--task-type=chore \
--priority=Low \
--body='Verify CLI passes argument literally'
The resulting BACKLOG entry's title will be the literal string Test $(date) — the $(date) is preserved verbatim because the title is a single Bash word (single-quoted), not a shell expression.
modify (--id=SLUG | --exact-title=TITLE) [--priority=PRI]
Edit an existing entry. v1 supports --priority only. --id resolves to the slug of the entry's title; --exact-title matches exactly.
.cwf/scripts/command-helpers/backlog-manager modify \
--id=add-delete-task-skill --priority=High
delete (--id=SLUG | --exact-title=TITLE) --confirm
Remove an entry outright. --confirm is required (use retire for completed work; delete is for typo cleanup).
.cwf/scripts/command-helpers/backlog-manager delete \
--exact-title='Bogus entry' --confirm
normalise [--dry-run]
Convert legacy Task-131 format (**Field**: paragraph metadata + ^---$ separators) to canonical heading-tree form. Idempotent — a re-run on canonical files writes nothing. Run this once after cwf-manage update if your repo predates the heading-tree refactor; the helper will refuse to validate **Field**:-style entries until you have. AC5a-d gates run before any write (cardinality, identity, required-key presence, ≥90% per-entry byte budget).
.cwf/scripts/command-helpers/backlog-manager normalise --dry-run
.cwf/scripts/command-helpers/backlog-manager normalise
retire (--id=SLUG | --exact-title=TITLE) --task=N [--note=TEXT]
Move a BACKLOG entry to CHANGELOG. The entry is appended as a #### <title> block under the implementing task's ### Retired Backlog Items subsection (the subsection is created if absent). Two-file atomic write; safe to re-run on crash.
.cwf/scripts/command-helpers/backlog-manager retire \
--id=fix-foo --task=132 --note='Implementation slightly altered scope'
Notes
- All subcommands (read and write) are valid for both LLM auto-invocation and explicit user invocation. There is no skill-side confirmation layer.
- Use
--help on any subcommand for the canonical usage string from the helper.
- Exit codes: 0 success; 1 validation/argument error; 2 path violation; 3 internal error.
Success Criteria
