backlog

Manage markdown task backlogs through a maildir-style directory pipeline with git-based claiming.

1|Updated Nov 11, 2012
One-click install
npx skills add https://github.com/fairchild/dotfiles --skill backlog-fairchild
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: backlog
Source: https://github.com/fairchild/dotfiles/tree/main/agents/shared/first-party-skills/backlog
Command: npx skills add https://github.com/fairchild/dotfiles --skill backlog-fairchild

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Coordinating deferred work across multiple AI agents and sessions is error-prone: tasks get double-claimed, progress context is lost between sessions, and there is no honest record of what was tried, cancelled, or failed. This Skill provides a file-based task tracker where each task is one markdown file and its directory (todo/doing/done/failed) is its state, with git operations acting as the claim lock. ## Core Features & Use Cases - Maildir-style task pipeline: Tasks move forward through todo → doing → done directories via slash commands like /backlog add, /backlog take, /backlog advance, /backlog progress, /backlog cancel, /backlog fail, /backlog rescue, and /backlog retry, with an append-only timestamped event log in each file. - Multiple storage backends: Choose between maildir-git (fully git-tracked), maildir-shared (atomic cross-worktree claims via a shared git-common-dir), github-issues (tasks as GitHub Issues via gh), or jira (work items via Atlassian CLI acli). - Race-safe claiming and stale-claim rescue: Claiming uses git mv collisions or atomic file creation so racing agents collide instead of double-working, and timed-out claims can be rescued after a configurable timeout. - Roadmap and reflection: A backlog/ROADMAP.md layer captures intent, principles, and named priority arcs that tasks link to via arc: frontmatter. - Use Case: An agent team working across git worktrees runs /backlog take to auto-claim the highest-priority unblocked task, logs progress notes as it works, and advances the task to done/ with a PR link when finished. ## Quick Start Ask the agent to set up a backlog in the current repository with the maildir-git backend and add your first task, for example: "Run /backlog setup with the maildir-git backend, then add a task called fix-login-alignment."

Frequently Asked Questions about backlog

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a markdown task backlog for AI agents?▼

Run the setup subcommand with a backend flag, such as scripts/backlog.sh setup --backend=maildir-git. This creates the todo/doing/done directories, an AGENTS.md convention file, and a ROADMAP skeleton, then commits them to git.

How do multiple agents claim tasks without conflicts?▼

Claiming is a forward move from todo/ into the first in-flight directory, and the backend provides the lock. With maildir-git, racing git mv operations collide at merge; with maildir-shared, an atomic O_EXCL file create in a shared git-common-dir catches the race at claim time across worktrees.

Can I use GitHub Issues or Jira as the backlog storage?▼

Yes, the skill ships github-issues and jira backends alongside the local maildir ones. The github-issues backend maps pipeline states to labels and worklog comments via the gh CLI, while the jira backend maps states to Jira statuses and comments via the Atlassian CLI (acli).

What happens when a claimed task is abandoned or times out?▼

The rescue verb lets another agent take over an in-flight task whose claim has exceeded its timeout (default 7 days, settable per task in frontmatter). The script verifies staleness from the last advanced or rescued log line and refuses if the claim is still active.

What are the limitations of the maildir backlog approach?▼

There is no backward verb: a task that cannot proceed must be failed with a reason and later retried deliberately, and cancelled tasks land in done/ discriminated only by their log line. Remote backend integration tests are also not yet implemented; the test harness covers only the maildir backends.