Skip to content

README.md

Latest commit

 

History

History
408 lines (305 loc) · 17.5 KB

README.md

File metadata and controls

408 lines (305 loc) · 17.5 KB

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
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)

Task Lifecycle

Design Doc                    Backlog
┌──────────────────┐          ┌──────────────────┐
│ ** TODO [ID]     │─checkout→│ *** TODO [ID]    │
│                  │          │ :SOURCE: link    │
└──────────────────┘          │ progress notes   │
                              └────────┬─────────┘
                                       │ work
                                       ▼
                              ┌──────────────────┐
                              │ *** DONE [ID]    │
                              └────────┬─────────┘
                                       │ reconcile
                                       ▼
┌──────────────────┐          ┌──────────────────┐
│ ** DONE [ID]     │←─────────│ (removed)        │
│ :VERSION: v1.0   │          └──────────────────┘
└──────────────────┘
  1. Queue: Add task to backlog with link property (:DESIGN:, :GITHUB:, etc.)
  2. Work: Add progress notes, update :HANDOFF: for session continuity
  3. 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:

Getting Started

Quick Start (Recommended)

With the Claude Code plugin installed:

# In your project directory
/backlog:setup

The setup skill will:

  1. Ask for your project prefix (e.g., ACME)
  2. Create the directory structure
  3. Write template files with your prefix
  4. Explain what was created

Legacy: Bootstrap Script

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-project

Customize org-setup.org

Edit the tags for your project:

#+TAGS: p0 p1 p2 | frontend backend infra

Create Your First Design Doc

Use the slash command:

/backlog:new-design-doc Your Feature Name

Or manually:

cp docs/design/000-template.org docs/design/001-first-feature.org

Start Using the Workflow

With 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-queue to check out
  • Edit backlog.org for progress notes
  • Manually reconcile when done

For Emacs Users

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

With use-package and :vc (Emacs 29+)

(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)))

With straight.el

(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)

Available Commands

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.

For Claude Code Users

Install the plugin once, use in any project:

/plugin marketplace add farra/dev-agent-backlog
/plugin install backlog@dev-agent-backlog  --scope project

Installation Scopes

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.

Slash Commands

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

Skills (Auto-triggered)

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

Task Properties

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

Task ID Format

[PROJECT-NNN-XX]
   │      │   │
   │      │   └── Task sequence (01, 02, ...)
   │      └────── Design doc number (001, 002, ...)
   └───────────── Project prefix (DAB, GF, ...)

Document Numbering

Documents are numbered sequentially (001, 002, 003...). Use #+CATEGORY: in the document header to classify documents. Valid categories are defined in each project's README.org (* Document Categories table). The defaults are:

Category Description
feature Core product functionality
infra Infrastructure, tooling, CI/CD
architecture System design, strategy, north star docs
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

Projects can customize these categories in their README.org.

Philosophy

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

Relation to Spec-Driven Development

Spec-driven development (SDD) emerged in 2025 as a name for the practice of writing structured specifications before asking AI agents to generate code. Tools like AWS Kiro and GitHub Spec Kit popularized the approach, and there's active community debate about where specs end and code begins.

dev-agent-backlog shares the core SDD insight: AI agents produce better work when given structured planning documents rather than ad-hoc prompts. Where we differ is in how that structure should work:

Concern Typical SDD (Kiro, Spec Kit) dev-agent-backlog
Spec structure Separate files (requirements, design, tasks) Single design doc with all context inline
Source of truth Specs may be primary or disposable Design doc is permanent archive; backlog is transient
Design refinement Human reviews AI-generated specs Explicit OPEN / DECIDED workflow for questions
Task lifecycle Check off in task file Checkout to backlog, reconcile back on completion

We think of design docs as thinking tools and permanent records, not just prompts for code generation. The OPEN questions workflow forces explicit resolution before implementation. The backlog separation keeps session-specific noise out of the design record.

For more detail, see 014 - Spec-Driven Development Research.

Learn More

The system documents itself using design docs:

and so on.

Prior Art

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

License

Apache 2

Contributing

This system documents itself using itself. See docs/design/ for the design documents and backlog.org for current work.