Design doc driven task management for human-agent collaboration
npx claudepluginhub farra/dev-agent-backlogDesign doc driven task management for human-agent collaboration
farraShare bugs, ideas, or general feedback.
Claude plugin for org-mode based spec-driven development for humans and AI agents alike. dev-agent-backlog is built on two key concepts:
backlog.org as hub: a project level org-mode file (human and machine readable) that links tasks to wherever they live, tracking work-in-progress.
design docs system: RFC/RFD-style org-mode documents where humans and agents think through problems before executing. Critically: 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 project
Then initialize your project:
# Interactive setup (recommended)
/backlog:setup
# Or just say: "Set up design docs for this project"
The setup will:
ACME)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:
** TODO [ID] headings** OPEN / ** DECIDEDA single backlog.org serving as the active working surface:
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 propertiesProactive 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 discussionsDraft → 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