---
name: backlog
description: Markdown task backlog and project roadmap (backlog/{todo,doing,done,failed}/, backlog/ROADMAP.md) for adding, advancing, recording progress, rescuing, cancelling, retrying, failing, maintenance, or reflecting on backlog priorities and roadmap direction.
license: Apache-2.0
---

# Backlog

A task tracker shaped like a maildir. Each task is one markdown file; its directory is its state. Tasks move forward through a pipeline of directories; there is no backward verb.

- `backlog/todo/`   — available to claim
- `backlog/doing/`  — claimed, in flight
- `backlog/done/`   — completed (and cancelled — the log line discriminates)
- `backlog/failed/` — dead-letter for tasks that couldn't proceed (created on demand)

The default pipeline is `todo → doing → done`. A project may add intermediate in-flight directories (e.g. `reviewing/`) by declaring the pipeline in `backlog/AGENTS.md`. See `references/pipeline.md`.

To claim is to advance from `todo/` to the first in-flight dir. The backend declared by `backlog/AGENTS.md` provides the lock mechanism — `maildir-git` lets racing `git mv`s collide at merge; `maildir-shared` uses an atomic create in a git-common-dir shared directory so the race is caught at claim time across worktrees.

## Slash invocation

Invokable as `/backlog <subcommand> [args]`. The canonical mechanism is `scripts/backlog.sh` — it reads `backlog/AGENTS.md`, detects the backend, and dispatches. Agents should prefer the script over re-implementing bash inline.

| Subcommand | Script call | Semantics |
|---|---|---|
| `/backlog setup` | `scripts/backlog.sh setup --backend=<maildir-git\|maildir-shared\|github-issues\|jira\|gitea>` | One-time scaffold: for maildir backends, creates dirs, AGENTS.md, ROADMAP skeleton, symlinks + .gitignore for `maildir-shared`; for `github-issues`, creates static labels on the remote; for `jira`, writes the Jira project/JQL/status mapping expected by the Atlassian CLI adapter; for `gitea`, creates labels on the Gitea repo (reached via a `gitea` git remote + a `tea` login) and writes a `## Gitea` section holding only the remote/login names — no server URL or token. Remote backends write AGENTS.md + ROADMAP skeleton (no local task tree). Backend flag is **required** — the script refuses without it and prints a heuristic hint based on `git worktree list`. |
| `/backlog add <slug> [category]` | `scripts/backlog.sh add <slug> [category]` | Create new task in `todo/` |
| `/backlog take [slug]` | `scripts/backlog.sh take [slug]` | Claim from `todo/` (auto-pick if no slug) |
| `/backlog advance <slug>` | `scripts/backlog.sh advance <slug>` | One forward step along the pipeline |
| `/backlog progress <note>` | `scripts/backlog.sh progress "<note>"` | Append a progress line to the current claim |
| `/backlog cancel <slug> <reason>` | `scripts/backlog.sh cancel <slug> "<reason>"` | Abandon an in-flight task |
| `/backlog fail <slug> <reason>` | `scripts/backlog.sh fail <slug> "<reason>"` | Dead-letter an in-flight task |
| `/backlog rescue <slug>` | `scripts/backlog.sh rescue <slug>` | Take over a stale claim |
| `/backlog retry <slug> <reason>` | `scripts/backlog.sh retry <slug> "<reason>"` | Move from `failed/` back to `todo/` |
| `/backlog status` | `scripts/backlog.sh status` | Counts per state + recent in-flight |
| `/backlog maintain` | read `references/maintain.md` | Advisory walk over buckets (agent-judgment, no script) |
| `/backlog worker` | follow `references/worker-loop.md` | Full loop: load + maintain + rank + claim + execute + close |
| `/backlog` (no args) | — | Skill loads; agent infers intent from conversation context |

The script is `scripts/backlog.sh` in this skill's base directory. Semantics for each verb live in `references/worker.md`; mechanism details (what the script actually does) live in `references/backends/<name>.md`. The test harness `scripts/test.sh` exercises the maildir backends end-to-end including a real `git worktree`-based race test, and syntax-checks every bundled script.

## File shape

Above the divider: what the author meant. Below: what the workers did.

Two halves, divided by `---` with blank lines around it so markdown renders it as a horizontal rule.

```markdown
---
priority: 2
dependencies:
  other-task-slug: "why we depend on it"
---

# Task Title

[problem statement, key decisions, phases, acceptance criteria]

---

- 2026-05-16T14:22:00Z advanced to=doing claimer=conductor:austin-v3 branch=feat/foo
- 2026-05-16T16:45:00Z progress | auth prototype passing locally
- 2026-05-17T11:03:00Z advanced to=done | PR=https://github.com/.../pull/123
```

Frontmatter and description above the divider are author-set and frozen after first commit (one exception: `retry` may edit them, since retry IS a correction). Below the divider is an append-only event log written by workers — see `references/worker.md` for the verb recipes that maintain it.

## Frontmatter (optional)

Every field has a default, so a minimal task can omit frontmatter entirely:

```markdown
# Quick fix

The login button is misaligned on mobile.

---
```

Defaults: `priority=999`, `timeout=7d`, `dependencies={}`. Add fields above the title to override.

- **`priority`** — integer, 1 = highest. Default `999` (sorts after every declared priority). Declare a number when scheduling order matters.
- **`timeout`** — humanish: `4h`, `3d`, `2w`. Default `7d`. Clock anchors to the most recent `advanced` or `rescued` log line — each forward step gets its own stage budget under the same number. Use shorter for automated agent tasks; longer for tasks needing synchronous human input or external dependencies. Project-wide defaults can be stated in `backlog/AGENTS.md`.
- **`dependencies`** — map of slug → reason. Default empty. Declare only hard preconditions; a task is takeable when every dep slug resolves to a file under `done/`.

Additional keys an author writes are preserved but not interpreted by any recipe. Full schema, kinds table, and "reading state" queries: `references/agents-schema.md`.

## Add a task

Gather **slug** (kebab-case), **category** (`plan` / `followup` / `task-list` / `ideas`, filename suffix), and a description.

```bash
scripts/backlog.sh add <slug> [category]
# then edit backlog/todo/<slug>-<category>.md to fill in
# frontmatter (priority/timeout/dependencies) and the body
```

The script writes a skeleton file in `backlog/todo/` and commits with `add(<slug>-<category>)`. Edit the file in-place to fill in the spec (frontmatter + description); follow-up commits to the same file before claim are fine.

Quality: write enough that a fresh session can execute without ever having met you — specific paths, verification commands, deps declared if any. Commit before anyone can claim.

Outcome contract: by default, a claim ends with the worker opening a *merge-ready* PR — the user clicks, reviews, merges. The task is agent-done when its file lands in `done/` with an `advanced to=done | PR=<url>` log line; the human's merge closes the loop. Lead time from agent-done to merged is later trackable from that timestamp. If the task wants something else (draft PR for exploratory work, no PR for batched grooming, etc.), say so in the spec — the default is review-ready.

## Working the backlog

For advance, progress, cancel, fail, rescue, retry, status, and maintain — the verb semantics plus the rules workers must follow — see `references/worker.md`. The canonical implementation lives in `scripts/` (invoke `scripts/backlog.sh <verb>`); the backend declaration in `backlog/AGENTS.md` selects which implementation runs. Mechanism prose for each backend: `references/backends/<name>.md`. For extending the pipeline with intermediate dirs (e.g. `reviewing/`) and how `advance` reads the ordering, see `references/pipeline.md`.

## Roadmap and reflection

`backlog/ROADMAP.md` sits above the queue — Intent, Principles, Current Focus, Priorities (named arcs), Non-goals — and answers *why these tasks, in this order*. Tasks optionally link via `arc:` frontmatter. Shape and conventions: `references/roadmap.md`. For reflecting on the backlog, adding to the roadmap, or initializing one, load `references/reflect.md` and follow its posture.

## References

- `scripts/backlog.sh` — canonical dispatch entrypoint; reads `backlog/AGENTS.md` to detect backend
- `scripts/lib.sh` — shared helpers (pipeline parser, timeout parser, claimer detection, divider resilience)
- `scripts/backlog-maildir-git.sh` — maildir-git implementation
- `scripts/backlog-maildir-shared.sh` — maildir-shared implementation
- `scripts/backlog-github-issues.sh` — github-issues implementation
- `scripts/backlog-jira.sh` — Jira implementation over Atlassian CLI (`acli`)
- `scripts/backlog-gitea.sh` — Gitea implementation over `tea api` (self-hosted, GitHub-compatible forge)
- `scripts/test.sh` — full verb cycle + cross-worktree race harness on temp repos (maildir backends only)
- `scripts/test-gitea.sh` — offline gitea-backend harness over a mock `tea` (verb cycle, claim conflict, pagination); run separately from `test.sh`
- `references/worker.md` — verb semantics for workers (advance, progress, cancel, fail, rescue, retry, status, maintain)
- `references/worker-loop.md` — canonical `/backlog worker` recipe (load, maintain, rank, claim, execute, close, report)
- `references/backends/maildir-git.md` — default backend; mechanism docs for git-tracked maildir
- `references/backends/maildir-shared.md` — multi-worktree backend; mechanism docs for git-common-dir shared dir
- `references/backends/github-issues.md` — cross-machine backend; mechanism docs for `gh issue`-backed storage
- `references/backends/jira.md` — cross-machine backend; mechanism docs for Jira work item-backed storage via `acli`
- `references/backends/gitea.md` — self-hosted backend; mechanism docs for Gitea issue-backed storage via `tea api`
- `references/pipeline.md` — declaring the pipeline; how `advance` knows where to go; conventions for intermediate dirs
- `references/agents-schema.md` — frontmatter schema, log line format, kinds table, reading-state queries
- `references/parallel-agents.md` — distributed-systems patterns and design rationale
- `references/workflows.md` — `init` (first-time setup) and `migrate` (from earlier layouts)
- `references/maintain.md` — advisory walk buckets (mechanical maintenance)
- `references/roadmap.md` — `backlog/ROADMAP.md` shape and the `arc:` linkage convention
- `references/reflect.md` — critical-collaborative planning posture for reflecting on the backlog or editing the roadmap
- `references/README.md` — background, design philosophy, related projects