dev-agent-backlog

dev-agent-backlog

Claude plugin for org-mode based spec-driven development for humans and AI agents alike. dev-agent-backlog is built on two key concepts:

1. 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.

2. 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.

Installation (Claude Code Plugin)

# 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:

1. Ask for your project prefix (e.g., ACME)
2. Create the directory structure
3. Write template files
4. 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!

Why This Exists

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.

Components

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.

Design Documents

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

Backlog

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

Agent Integration

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 commits
• backlog-resume - Surfaces WIP tasks and handoff notes on session start
• claude-tasks-sync - Ensures Claude Tasks are cross-referenced in backlog.org
• new-design-doc - Suggests creating design docs during architecture discussions

The Workflow

Document Status Lifecycle

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