A task management system for human-agent collaboration, built on two ideas:
-
backlog.org as universal hub - Human-readable join table linking to tasks wherever they live. Both humans and agents read the backlog; agents follow links to their native primitives (Claude Tasks, Design Documents, GitHub, etc.).
-
Design docs for agent planning - RFC/RFD-style org-mode documents where humans and agents think through problems before executing. Context, decisions, and tasks in ONE place.
# Add the marketplace
/plugin marketplace add farra/dev-agent-backlog
# Install the plugin
/plugin install backlog@dev-agent-backlog --scope projectThen initialize your project:
# Interactive setup (recommended)
/backlog:setup
# Or just say: "Set up design docs for this project"The setup will:
- Ask for your project prefix (e.g.,
ACME) - Create the directory structure
- Write template files
- Update your CLAUDE.md
Other Agents: The design doc methodology works with any AI coding agent that can read/write files. The org-mode templates and workflow are agent-agnostic. We're exploring adapters for OpenAI Codex, Gemini CLI, and OpenCode. Contributions welcome!
Traditional task management (GitHub Issues, Jira, Linear) is designed for human-to-human collaboration. When AI coding agents enter the workflow, these systems create friction:
| Challenge | Traditional Systems | dev-agent-backlog |
|---|---|---|
| Context locality | Issue separate from design docs | Task lives in design doc |
| Atomic updates | API call separate from code | File change in same commit |
| API friction | Auth, rate limits, network | Direct file read/write |
| Source of truth | Issue is primary | Design doc is primary |
This system treats design documents as the source of truth. Tasks exist because of design decisions. The backlog is a working surface, not the canonical record.
After running /backlog:setup, your project will have:
your-project/
├── README.org # Project config (prefix, categories, statuses)
├── org-setup.org # Shared org-mode configuration
├── backlog.org # Working surface for active tasks
├── CHANGELOG.md # User-facing change log
└── docs/
└── design/
├── README.org # Index of design docs
├── 000-template.org
├── 001-feature.org
└── ...
The plugin provides commands and skills.
Org-mode files following an RFC/RFD pattern:
- Each document captures a decision and its rationale
- Tasks defined inline with
** TODO [ID]headings - Questions tracked with
** OPEN/** DECIDED
A single backlog.org serving as the active working surface:
- Tasks "checked out" from design docs
- Progress notes accumulate during work
- Completed tasks "reconciled" back to design docs
Claude Code plugin commands (all prefixed with backlog:):
/backlog:setup- Initialize design doc system in a project/backlog:new-design-doc <title>- Create a new design document/backlog:design-review <doc>- Review doc: resolve questions, finalize tasks/backlog:queue-design-doc <doc>- Queue all tasks from a design doc/backlog:task-queue <id>- Check out a task from design doc to backlog/backlog:task-start <id>- Begin work with context and handoff notes/backlog:task-complete <id> [version]- Reconcile completed task with attribution/backlog:task-hold <id> <reason>- Move task to blocked/backlog:task-link <id> --github|--claude-task|--bead|--design- Add link properties
Proactive skills (triggered automatically):
backlog-update- Reminds to update backlog and changelog before commitsbacklog-resume- Surfaces WIP tasks and handoff notes on session startclaude-tasks-sync- Ensures Claude Tasks are cross-referenced in backlog.orgnew-design-doc- Suggests creating design docs during architecture discussions
Draft → Review → Accepted → Active → Complete
│ │ │ │
│ │ │ └── /task-complete (when last task done)
│ │ └── /queue-design-doc or /task-queue
│ └── /design-review (resolve questions, finalize tasks)
└── /new-design-doc
| Status | Meaning |
|---|---|
| Draft | Under development, not ready |
| Review | Ready for feedback |
| Accepted | Approved, ready to implement |
| Active | Implementation in progress |
| Complete | Fully implemented and verified |
| Archived | No longer active (rejected/obsolete) |
Design Doc Backlog
┌──────────────────┐ ┌──────────────────┐
│ ** TODO [ID] │─checkout→│ *** TODO [ID] │
│ │ │ :SOURCE: link │
└──────────────────┘ │ progress notes │
└────────┬─────────┘
│ work
▼
┌──────────────────┐
│ *** DONE [ID] │
└────────┬─────────┘
│ reconcile
▼
┌──────────────────┐ ┌──────────────────┐
│ ** DONE [ID] │←─────────│ (removed) │
│ :VERSION: v1.0 │ └──────────────────┘
└──────────────────┘
- Queue: Add task to backlog with link property (
:DESIGN:,:GITHUB:, etc.) - Work: Add progress notes, update
:HANDOFF:for session continuity - Complete: Reconcile back to source (design doc, GitHub, etc.) and remove from backlog
backlog.org is a human-readable hub linking to tasks wherever they live.
backlog.org (hub)
│
┌────────────┬───────┴───────┬────────────┐
▼ ▼ ▼ ▼
Design Doc Claude Task GitHub Issue Bead
:DESIGN: :CLAUDE_TASK: :GITHUB: :BEAD:
With the Claude Code plugin installed:
# In your project directory
/backlog:setupThe setup skill will:
- Ask for your project prefix (e.g.,
ACME) - Create the directory structure
- Write template files with your prefix
- Explain what was created
Deprecated: Use the plugin instead. This script will be removed in a future release.
git clone https://github.com/farra/dev-agent-backlog.git
./dev-agent-backlog/bin/init.sh MYPREFIX ~/path/to/your-projectEdit the tags for your project:
#+TAGS: p0 p1 p2 | frontend backend infra
Use the slash command:
/backlog:new-design-doc Your Feature Name
Or manually:
cp docs/design/000-template.org docs/design/001-first-feature.orgWith Claude Code:
/backlog:task-queue PROJECT-001-01
/backlog:task-start PROJECT-001-01
# ... do the work ...
/backlog:task-complete PROJECT-001-01 v1.0
With Emacs:
- Position on a task heading
M-x backlog/task-queueto check out- Edit backlog.org for progress notes
- Manually reconcile when done
The elisp/workflow-commands.el package provides Emacs commands that complement the Claude Code plugin. Install it once in your Emacs config (not per-project).
(use-package workflow-commands
:vc (:url "https://github.com/farra/dev-agent-backlog"
:lisp-dir "elisp")
:after org
:bind (:map org-mode-map
("C-c q" . backlog/task-queue)))(straight-use-package
'(workflow-commands
:type git
:host github
:repo "farra/dev-agent-backlog"
:files ("elisp/*.el")))
(require 'workflow-commands)
(define-key org-mode-map (kbd "C-c q") #'backlog/task-queue)| Command | Description |
|---|---|
backlog/task-queue |
Queue task at point into backlog.org |
backlog/goto-design |
Jump to design doc via :DESIGN: property |
backlog/design-next-number |
Show next available doc number |
backlog/design-goto-doc |
Jump to design doc by number |
backlog/design-status-report |
Summary of doc statuses |
backlog/design-sync-status |
Update README.org table from actual statuses |
See backlog.org Setup section for agenda configuration.
Install the plugin once, use in any project:
/plugin marketplace add farra/dev-agent-backlog
/plugin install backlog@dev-agent-backlog --scope project| Scope | Recommended? | Notes |
|---|---|---|
--scope project |
Yes | Shared with collaborators via .claude/settings.json |
--scope local |
OK | Just you, just this repo |
--scope user |
No | Would trigger in every project, even without setup |
Why not user scope? The skills (like backlog-update) trigger on common actions
like commits. Without a backlog.org in the project, they'll fail or be confusing.
Project scope ensures the plugin only activates where it's been set up.
| Command | Description |
|---|---|
/backlog:setup |
Initialize design doc system in current project |
/backlog:new-design-doc <title> |
Create a new design document from template |
/backlog:design-review <doc> |
Review doc: resolve questions, finalize tasks |
/backlog:queue-design-doc <doc> |
Queue all tasks from a design doc |
/backlog:task-queue <id> |
Check out a task to backlog Active section |
/backlog:task-start <id> |
Begin work with context and handoff notes |
/backlog:task-complete <id> [version] |
Mark done with attribution |
/backlog:task-hold <id> <reason> |
Move task to Blocked section |
/backlog:task-link <id> <flags> |
Add link properties to existing task |
| Skill | Trigger | Behavior |
|---|---|---|
backlog-resume |
Session start | Checks for WIP tasks, surfaces handoff notes |
backlog-update |
Before commits | Reminds to update backlog, changelog, and handoff notes |
claude-tasks-sync |
Using Claude Tasks | Ensures cross-references exist in backlog.org |
new-design-doc |
Architecture discussions | Suggests creating design docs |
setup |
"Set up design docs" | Interactive project initialization |
Tasks in the backlog can link to multiple sources (all optional):
:DESIGN:- Link to canonical location in design doc:CLAUDE_TASK:- Link to Claude Task for cross-session coordination:GITHUB:- Link to GitHub issue:BEAD:- Link to Bead reference
Tasks also track:
:HANDOFF:- Notes for next session (what to try, where stuck):WORKED_BY:- Who has worked on this (claude-code, human)
Completed tasks in design docs also include:
:COMPLETED_BY:- Who marked it done:TRANSCRIPT:- Link to Claude conversation transcript
[PROJECT-NNN-XX]
│ │ │
│ │ └── Task sequence (01, 02, ...)
│ └────── Design doc number (001, 002, ...)
└───────────── Project prefix (DAB, GF, ...)
Documents are numbered sequentially (001, 002, 003...). Use #+CATEGORY: in
the document header to classify documents. Valid categories are defined in
README.org:
| Category | Description |
|---|---|
| feature | Core product functionality |
| infra | Infrastructure, tooling, CI/CD |
| research | Research, analysis, spikes |
| hygiene | Tech debt, chores, maintenance |
| incident | Bugs, outages, RCAs |
| security | Audits, vulnerabilities, hardening |
| data | Storage, pipelines, metrics |
| bs | Brainstorms, speculative ideas |
- Design docs as source of truth: Tasks exist because of design decisions
- Working surface pattern: Backlog is ephemeral; design docs are permanent
- Atomic operations: Task state and code versioned together
- Plain text everything: Git history is task history
- Agent-agnostic methodology: The org-mode templates and workflow work with any AI coding agent that can read/write files. The Claude Code plugin adds convenience, but the core system is portable.
The system documents itself using design docs:
- Design Doc Pattern - How design documents work
- Backlog Workflow - The checkout/reconcile workflow
- Plugin Architecture - Claude Code integration
This system evolved from dev-agent-work, an earlier experiment in agent-friendly task management. Key improvements in this version:
- Design docs as canonical source (not standalone task files)
- Checkout/reconcile workflow (vs direct task editing)
- Richer org-mode integration (queries, agenda views)
- Structured slash commands and skills, claude plugin format
Apache 2
This system documents itself using itself. See docs/design/ for the design documents and backlog.org for current work.