Design doc driven task management with org-mode files, backlog workflow, and task tracking

version
1.0.0
GitHub stars
29

Install

/plugin install backlog@dev-agent-backlog

Run it inside Claude Code after adding the marketplace with /plugin marketplace add farra/dev-agent-backlog.

Contents

Discovered from source

Skills 5

Backlog Resume

This skill checks for in-progress work when starting a new session, implementing the "hook pattern" from gastown - if there's work on your hook, you should run it.

Prerequisites

Before triggering, check that backlog.org exists in the project root.

If backlog.org does not exist, do NOT trigger this skill. The project hasn't been set up with the backlog system yet. Silently skip - don't suggest setup or explain why the skill isn't running.

When to Offer This Workflow

Trigger conditions:

  • backlog.org exists in the project root, AND
  • Starting a new session in a project with backlog.org
  • User asks "what was I working on?", "resume", "continue"
  • User says "where did I leave off?"

Initial check: Read backlog.org and look for WIP tasks in the Active section.

Workflow

1. Check for WIP Tasks

Read * Current WIP > ** Active section in backlog.org.

Look for tasks with state WIP (work in progress).

2. Surface Handoff Notes and Claude Task State

For each WIP task found:

  • Read the :HANDOFF: property
  • Read recent progress notes (entries starting with [YYYY-MM-DD])
  • Check for :CLAUDE_TASK: property

If :CLAUDE_TASK: exists:

  • Note the Task List ID for cross-session coordination
  • Check if there are related Tasks or dependencies
  • This task has agent coordination enabled

3. Present Resume Option

If WIP task(s) found, display:

## Work in Progress

Found active work from previous session:

### [TASK-ID] Task Title

**Handoff notes:**
> <content of :HANDOFF: property>

**Recent progress:**
> <last progress note>

**Claude Task:** <task-list-id>/<task-id> (if present)

Continue working on this task?

The Claude Task link (if present) enables cross-session coordination. Follow the link to check for any updates from subagents or other sessions.

4. Quick Consistency Check

While reviewing backlog.org, perform a lightweight consistency check:

Stale entries:

  • If any tasks show *** DONE in backlog.org, they should have been removed
  • Suggest: "Found completed task [ID] still in backlog. Remove it?"

Design doc drift:

  • For WIP/TODO tasks with :DESIGN: links, spot-check the source doc
  • If the source doc shows the task as ** DONE but backlog shows TODO/WIP:
    • Suggest removing the stale backlog entry
  • If the design doc #+STATUS: is Complete but tasks are still in backlog:
    • Suggest running /reconcile-backlog to clean up

This catches drift early without running a full reconciliation.

5. If No WIP Tasks

Check if there are TODO tasks in Active section:

## Ready to Start

No work in progress. Active queue:

1. [TASK-ID-1] Task title
2. [TASK-ID-2] Task title

Start one of these tasks?

6. Handle Response

  • If user wants to continue: Run /task-start <task-id>
  • If user wants different task: Queue or start the requested task
  • If user declines: Proceed with whatever they want to do

Example

User: <starts session>

Claude: "Checking backlog.org for in-progress work...

## Work in Progress

Found active work from previous session:

### [DAB-005-01] Implement handoff notes

**Handoff notes:**
> Stuck on property format. Check org-mode docs for multi-line properties.

**Recent progress:**
> [2026-01-03] Started implementation. Template updated.

Continue working on this task?"

Related Commands

CommandWhen to use
/task-start <id>Resume the WIP task
/task-queue <id>Add a new task to Active
/task-hold <id> <reason>If task is blocked

Backlog Update Reminder

This skill reminds you to update backlog.org before commits or when finishing significant work. The backlog should reflect reality BEFORE the commit is made.

Prerequisites

Before triggering, check that backlog.org exists in the project root.

If backlog.org does not exist, do NOT trigger this skill. The project hasn't been set up with the backlog system yet. Silently skip - don't suggest setup or explain why the skill isn't running. Just proceed with the commit normally.

When to Offer This Workflow

Trigger conditions (only if backlog.org exists):

  • About to run git commit or create a commit
  • Exiting plan mode after completing implementation
  • User says "done", "finished", "let's commit", "wrap up"
  • Completing a significant piece of work

Initial check: Before proceeding with the commit, read backlog.org's Current WIP section to see what's in Active.

Workflow

1. Check Active Tasks

Read the * Current WIP > ** Active section in backlog.org.

Look for tasks related to the work just completed.

2. Update Progress Notes

If work relates to an Active task, add progress notes under that task:

*** TODO [PROJECT-NNN-XX] Task title
:PROPERTIES:
:DESIGN: [[file:...][...]]
:END:

Previous notes...

[YYYY-MM-DD] What was done, what remains.

3. Assess Task Status

After adding notes, consider:

  • Still in progress? Leave as TODO/WIP, notes are sufficient
  • Blocked? Suggest running /task-hold <id> <reason>
  • Complete? Suggest running /task-complete <id> [version]

Do NOT mark complete automatically - that's an explicit user action via /task-complete.

4. Check CHANGELOG.md

If significant user-facing changes were made:

  • Read CHANGELOG.md if it exists
  • Check if the change is already documented under ## [Unreleased]
  • If not, suggest adding an entry:
    • Added - New features
    • Changed - Changes to existing functionality
    • Fixed - Bug fixes
    • Removed - Removed features

5. Check Design Doc Status

If the work relates to an Active task with a :DESIGN: link:

  1. Follow the :DESIGN: link to the source design doc
  2. Check the #+STATUS: of that document
  3. Scan its * Tasks section for remaining ** TODO or ** WIP entries
  4. If all tasks are ** DONE:
    • Prompt: "All tasks in [doc name] are complete. Update #+STATUS: to Complete?"
    • If yes, update the design doc and docs/design/README.org index

This catches completed design docs even when /task-complete wasn't used formally.

7. Update Handoff Notes

If stopping work mid-task:

  • Update :HANDOFF: property with context for next session
  • Include: what was tried, where stuck, what to try next

8. Then Commit

Only after backlog.org and CHANGELOG.md are updated, proceed with the commit.

Related Commands

CommandWhen to suggest
/task-complete <id>Task is fully done
/task-hold <id> <reason>Task is blocked
/task-queue <id>Need to add a task to Active

Example

User: "Let's commit these changes"

Claude: "Before committing, let me check backlog.org...

I see [DAB-001-01] is in Active. We just implemented the directory
structure. Should I:
1. Add progress notes (still more to do)
2. Mark complete with /task-complete DAB-001-01
3. Proceed without updating (unrelated work)"

Claude Tasks Sync

This skill ensures Claude Tasks are cross-referenced in backlog.org. The backlog is the universal hub - humans read it directly, agents follow links to their native primitives.

Prerequisites

Before triggering, check that backlog.org exists in the project root.

If backlog.org does not exist, do NOT trigger this skill. The project hasn't been set up with the backlog system yet. Silently skip - Claude Tasks can still be used normally, they just won't be synced to a backlog.

Core Principle

Sync means cross-references, not content replication.

  • When Claude creates a Task, ensure backlog.org has an entry with :CLAUDE_TASK: link
  • Don't duplicate task descriptions - just ensure the link exists
  • Humans read backlog.org; agents follow links to Claude Tasks

When to Trigger

Trigger conditions:

  • Creating Claude Tasks (via TodoWrite or task management)
  • Spawning subagents that will create their own Tasks
  • After /queue-design-doc creates a Task List
  • When completing work that involved Claude Tasks

Workflow

1. When Creating Claude Tasks

After creating one or more Claude Tasks:

  1. Read backlog.org's * Current WIP > ** Active section
  2. For each Claude Task created:
    • Check if a matching backlog entry exists (by task ID or title)
    • If exists: add :CLAUDE_TASK: property if missing
    • If not exists: create minimal backlog entry with link

Minimal backlog entry:

*** TODO Task title
:PROPERTIES:
:CLAUDE_TASK: <task-list-id>/<task-id>
:EFFORT: M
:HANDOFF:
:WORKED_BY: claude-code
:END:

2. When Tasks Have Design Doc Origin

If the task originated from a design doc (has :DESIGN: property), preserve it:

*** TODO [DAB-012-08] Create sync skill
:PROPERTIES:
:DESIGN: [[file:docs/design/012-claude-tasks-integration.org::*Tasks][DAB-012-08]]
:CLAUDE_TASK: <task-list-id>/<task-id>
:EFFORT: M
:END:

Both links coexist - :DESIGN: for the spec, :CLAUDE_TASK: for agent coordination.

3. When Subagents Create Tasks

If spawning subagents:

  1. Note the Task List ID being used
  2. After subagent completes, check for any new Tasks created
  3. Ensure each new Task has a corresponding backlog entry

4. Link Format

The :CLAUDE_TASK: property format:

:CLAUDE_TASK: <task-list-id>/<task-id>

Or for referencing just the Task List:

:CLAUDE_TASK_LIST: <task-list-id>

What NOT To Do

  • Don't copy task descriptions from Claude Tasks to backlog
  • Don't mirror status changes automatically
  • Don't create duplicate entries - one per task
  • Don't remove :DESIGN: or other existing links

Example

Claude: [Creates Task "Implement authentication" via TodoWrite]

[Skill triggers]

Claude: "I've created a Claude Task for this work. Let me ensure
it's tracked in backlog.org...

Added to backlog.org Active section:
*** TODO Implement authentication
:PROPERTIES:
:CLAUDE_TASK: abc123/task-001
:EFFORT: M
:WORKED_BY: claude-code
:END:

The task is now visible to both humans (via backlog) and agents
(via Claude Task)."

Related Skills

SkillRelationship
backlog-updateUpdates existing entries; this creates new ones
backlog-resumeReads :CLAUDE_TASK: links on session start

Related Commands

CommandRelationship
/task-startCreates Claude Task at execution time
/queue-design-docCreates Task List for all design doc tasks

Design Doc Suggestion

This skill helps identify when a design document should be created and guides the process.

Prerequisites

Before triggering, check that the project has been set up with the backlog system.

Look for either:

  • backlog.org in the project root, OR
  • docs/design/ directory exists

If neither exists, do NOT proactively trigger this skill. The project hasn't been set up with the backlog system yet. Silently skip - don't suggest setup or explain why the skill isn't running.

Exception: If the user explicitly asks to "create a design doc" or similar, you may suggest running /backlog:setup first to initialize the system.

When to Offer This

Trigger conditions for NEW design doc:

  • Discussion involves significant architectural decisions
  • Multiple approaches are being weighed with tradeoffs
  • User mentions "RFC", "RFD", "design doc", "proposal"
  • User says "we should document this", "let me think through..."
  • A feature requires coordination across multiple components
  • Changes that will affect how others use the system

Trigger conditions for CONVERTING existing markdown:

  • User mentions "convert to org", "migrate to org-mode"
  • User has markdown design docs in docs/legacy/ or similar
  • User asks about integrating old documentation
  • Discussion references existing .md design documents
  • User says "we have an old RFC", "there's a markdown doc for this"

Proactive offers:

For new doc: "This seems like a significant design decision. Should I create a design doc to capture the motivation, options, and decision? That would help track the rationale and any implementation tasks."

For conversion: "I see there's an existing markdown document for this. Should I convert it to org-mode format? I can extract the tasks, assign IDs, and optionally queue them to the backlog."

Workflow

1. Confirm Scope

Ask:

  • What's the one-sentence summary?
  • What category? (read valid categories from README.org's * Document Categories table)
  • Any specific options already being considered?
  • (If converting) Which markdown file should I convert?

2. Create the Document

For new docs: Use /new-design-doc <title> to scaffold, then:

  1. Fill in Summary - one paragraph overview
  2. Fill in Motivation - why this matters, what problem it solves
  3. Fill in Design - options considered with tradeoffs
  4. Add Tasks - implementation work with [PROJECT-NNN-XX] IDs
  5. Add Questions - open issues as ** OPEN

For conversion: Use /new-design-doc <title> <source.md> to convert, then:

  1. Review the converted structure
  2. Verify task IDs are properly assigned
  3. Check that code blocks converted correctly
  4. Offer to queue tasks to backlog

3. Use Org-Mode Properly

Remind yourself:

  • Documents are numbered sequentially (001, 002, ...) - check existing docs for next number
  • Add #+CATEGORY: to frontmatter (use categories from README.org)
  • Use ** TODO [PROJECT-NNN-XX] Task title (not markdown checkboxes)
  • Use ** OPEN Question / ** DECIDED Question (not plain text)
  • Add :PROPERTIES: for EFFORT, VERSION, DECIDED date
  • Reference the template: docs/design/000-template.org

4. Update Index

Add the new doc to docs/design/README.org in the appropriate section.

5. Queue Tasks (for conversions)

After converting, offer to queue extracted tasks:

  • List tasks with their new IDs
  • Ask which to queue to backlog Active section
  • Use /task-queue for each selected task

What Makes a Good Design Doc

SectionGoodBad
Summary"Add caching layer to reduce API latency""Caching stuff"
MotivationExplains the problem and why it mattersJumps to solution
DesignShows 2-3 options with tradeoffsOnly shows chosen option
TasksSpecific, actionable, has IDsVague, no IDs

Conversion Rules Summary

MarkdownOrg-Mode
## Heading* Heading
- [ ] Task** TODO [PROJECT-NNN-XX] Task
- [x] Task** DONE [PROJECT-NNN-XX] Task
```lang#+begin_src lang
[text](url)[[url][text]]

Files

  • Template: docs/design/000-template.org
  • Index: docs/design/README.org
  • Examples: Any existing docs/design/NNN-*.org

Setup Design Doc Backlog System

This skill helps users set up the design doc driven task management system in their project.

When to Use

Activate when the user says things like:

  • "set up design docs"
  • "initialize the backlog"
  • "configure design doc workflow"
  • "add task management with design docs"

Setup Process

1. Gather Information

Ask the user for:

  • Project prefix: A short uppercase identifier (e.g., ACME, GF, DAB) used in task IDs like [ACME-001-01]

Check if they already have:

  • A README.org with #+PROJECT_PREFIX: set (use that)
  • Existing docs/design/ directory (don't overwrite)
  • Existing backlog.org (don't overwrite)

2. Create Directory Structure

Create these directories if they don't exist:

docs/design/

3. Create Files from Templates

The templates are in the plugin's templates/ directory. Copy them with PROJECT substitution:

TemplateDestinationSubstitution
readme-project.orgREADME.orgReplace PROJECT with prefix
readme-design.orgdocs/design/README.orgNone
org-setup.orgorg-setup.orgReplace PROJECT with prefix
backlog-template.orgbacklog.orgReplace PROJECT with prefix
design-doc-template.orgdocs/design/000-template.orgReplace PROJECT with prefix
changelog-template.mdCHANGELOG.mdNone

Important: Check if files exist before writing. Ask the user before overwriting.

4. Update CLAUDE.md

Append or merge the following into the project's CLAUDE.md (create if needed):

## Design Doc Workflow

This project uses design docs for task management. Design docs live in `docs/design/`.

### Key Files
- `backlog.org` - Working surface for active tasks
- `docs/design/*.org` - Design documents (source of truth)
- `README.org` - Project config (prefix, categories, statuses)

### Workflow
1. Create design docs with `/backlog:new-design-doc`
2. Queue tasks with `/backlog:task-queue <id>`
3. Start work with `/backlog:task-start <id>`
4. Complete with `/backlog:task-complete <id>`

### Task ID Format
`[PREFIX-NNN-XX]` where:
- PREFIX = project prefix (e.g., ACME)
- NNN = design doc number
- XX = task sequence

5. Explain What Was Created

After setup, explain:

  • What files were created and their purpose
  • How to create a first design doc
  • Available commands (/backlog:new-design-doc, etc.)

Example Interaction

User: Set up design docs for this project

Claude: I'll help you set up the design doc backlog system.

What project prefix would you like to use? This is a short uppercase identifier
(like ACME, GF, or DAB) that will appear in task IDs like [ACME-001-01].

User: ACME

Claude: Great! Let me set up the backlog system with prefix ACME.

[Creates files...]

Done! I've created:
- README.org - Project config with categories and statuses
- org-setup.org - Shared org-mode configuration
- backlog.org - Your working surface for active tasks
- docs/design/README.org - Index of design documents
- docs/design/000-template.org - Template for new design docs
- CHANGELOG.md - For tracking releases

To create your first design doc, use:
  /backlog:new-design-doc "Your Feature Title"

This will create a numbered design doc with tasks you can then queue to your backlog.

Template Content

When writing files, read the template content from the plugin's templates directory and perform the PROJECT → prefix substitution.

Commands 10

Design Review

Guide design document $ARGUMENTS through the review process: Draft → Review → Accepted.

Process

1. Resolve Document

Find the design document from the identifier:

  • If number (e.g., 010, 10): Look for docs/design/010-*.org
  • If filename (e.g., 010-design-doc-metadata.org): Use directly
  • If path: Use as provided

Read the document and extract:

  • #+TITLE: for display
  • #+STATUS: for current state
  • #+CATEGORY: for context

2. Set Review Status

If #+STATUS: is Draft:

  • Change to Review
  • Update docs/design/README.org index
  • Announce: "Document is now in Review status"

If already Review or Accepted:

  • Continue with the review process

If Active, Complete, or Archived:

  • Abort: "Document is already past the review stage"

3. Review Open Questions

Scan * Questions section for ** OPEN headings.

For each open question:

  1. Display the question and any context/options in its body
  2. Discuss with the user to reach a decision
  3. When decided:
    • Change ** OPEN to ** DECIDED
    • Add :DECIDED: [YYYY-MM-DD] property
    • Add decision rationale to the body
  4. Continue to next question

If no open questions, proceed to step 4.

4. Review Design Sections

Scan * Design and * Decision sections for unresolved items:

  • Sub-headings: *** TODO, *** FIXME, *** Comment, *** Note
  • Inline markers: TODO:, FIXME:, XXX:

For each item found:

  1. Surface the item with surrounding context
  2. Ask: "How should we resolve this?"
  3. Update or remove the marker based on resolution

5. Review Tasks

Scan * Tasks section for ** TODO headings.

Present a summary:

  • List all tasks with their IDs, titles, and effort estimates
  • Identify any tasks that seem underspecified
  • Ask: "Are these tasks complete and ready for implementation?"

If tasks need refinement:

  • Help the user add, modify, or remove tasks
  • Ensure each task has an ID, clear title, and effort estimate

6. Final Confirmation

When all questions are decided and tasks are finalized:

Ask: "All questions are resolved and tasks are ready. Mark as Accepted?"

If yes:

  • Change #+STATUS: to Accepted
  • Update docs/design/README.org index
  • Announce: "Document is now Accepted and ready for implementation"

If no:

  • Leave as Review for further refinement
  • Summarize what was accomplished

7. Offer to Queue

If document was marked Accepted:

  • Ask: "Would you like to queue the tasks to backlog.org now?"
  • If yes: run /queue-design-doc logic

Status Transitions

Draft → Review → Accepted
  │       │         │
  │       │         └── Ready for implementation
  │       └── Questions being resolved, tasks being finalized
  └── Initial creation, not ready for review

Example

/design-review 010
/design-review 010-design-doc-metadata

Reviews design doc 010, resolves open questions, finalizes tasks, and moves to Accepted.

Files

  • Design docs: docs/design/*.org
  • Index: docs/design/README.org

New Design Doc

Create a new design document titled: $ARGUMENTS

Argument Parsing

Parse $ARGUMENTS to extract:

  • title: The design doc title (required)
  • source_path: Optional path to existing markdown file to convert

Examples:

  • /new-design-doc Error Recovery → title="Error Recovery", no source
  • /new-design-doc Error Recovery docs/legacy/error-handling.md → title="Error Recovery", source="docs/legacy/error-handling.md"

Process

1. Find Next Available Number

Look at existing files in docs/design/ to find the next available NNN:

  • List files matching [0-9][0-9][0-9]-*.org
  • Find the highest number
  • Use the next sequential number (no gaps, no category-based ranges)

2. Determine Category

Read valid categories from README.org (the * Document Categories table). Projects define their own categories there — always use the project's list, not defaults.

Ask the user which category applies, or infer from context.

3. Create the Document

If no source_path (new from template):

  • Copy from docs/design/000-template.org
  • Fill in header properties (see below)

If source_path provided (convert from markdown):

  • Read the markdown file
  • Convert to org-mode format (see Conversion Rules below)
  • Preserve existing content structure

Fill in header:

  • #+TITLE: - NNN -
  • #+AUTHOR: - Your Name (or prompt for author)
  • #+STATUS: - Draft
  • #+CATEGORY: - From step 2
  • #+CREATED: - Today's date [YYYY-MM-DD]
  • #+LAST_MODIFIED: - Today's date
  • #+SETUPFILE: ../../org-setup.org

4. Assign Task IDs

For new documents: Use placeholder pattern [PROJECT-NNN-01], [PROJECT-NNN-02], etc.

For converted documents:

  • Find all - [ ] and - [x] checkboxes
  • Convert to ** TODO [PROJECT-NNN-XX] / ** DONE [PROJECT-NNN-XX]
  • Assign sequential IDs starting at 01
  • Preserve the task description text

5. Update README.org Index

If docs/design/README.org exists:

  • Add a new row to the documents table: | NNN | [[file:NNN-slug.org][Title]] | Draft |

6. Offer to Queue Tasks

After conversion, offer to queue extracted tasks to backlog.org:

  • List the tasks found with their new IDs
  • Ask if user wants to queue any/all to Active section

7. Report

Output:

  • Path to new file
  • If converted: summary of what was transformed
  • List of tasks with their IDs
  • Remind to review and refine

Conversion Rules (Markdown → Org-Mode)

Structure

MarkdownOrg-Mode
# Heading* Heading
## Heading** Heading (under appropriate parent)
### Heading*** Heading

Tasks

MarkdownOrg-Mode
- [ ] Task text** TODO [PROJECT-NNN-XX] Task text
- [x] Task text** DONE [PROJECT-NNN-XX] Task text

Code

MarkdownOrg-Mode
```rust#+begin_src rust
```#+end_src

Frontmatter

Markdown YAMLOrg-Mode
title: X#+TITLE: X
status: X#+STATUS: X
author: X#+AUTHOR: X

Questions/Decisions

Markdown PatternOrg-Mode
**Open Question:** or - [ ] Question? in Questions section** OPEN Question?
**Decision:** or - [x] Decided thing in Questions section** DECIDED Decided thing

Links

MarkdownOrg-Mode
[text](url)[[url][text]]
[text](./file.md)[[file:file.org][text]] (update .md → .org)

Org-Mode Reminders

The document MUST use org-mode conventions:

  • ** TODO [PROJECT-NNN-XX] Task title for tasks (not markdown checkboxes)
  • ** OPEN / ** DECIDED for questions
  • :PROPERTIES: drawers for metadata (EFFORT, VERSION, etc.)
  • #+SETUPFILE: ../../org-setup.org for shared config

Examples

New from template:

/new-design-doc Error Recovery Improvements

Creates docs/design/019-error-recovery-improvements.org

Convert existing markdown:

/new-design-doc Cache Architecture docs/legacy/caching-proposal.md

Converts markdown to docs/design/020-cache-architecture.org, assigns task IDs

Files

  • Template: docs/design/000-template.org
  • Index: docs/design/README.org
  • Setup: org-setup.org
  • Backlog: backlog.org (for queuing extracted tasks)

Queue Design Doc

Queue all tasks from design document $ARGUMENTS into backlog.org Active section.

Process

1. Resolve Document

Find the design document from the identifier:

  • If number (e.g., 007, 7): Look for docs/design/007-*.org
  • If filename (e.g., 007-queue-design-doc.org): Use directly
  • If path: Use as provided

Read the document and extract title from #+TITLE:.

2. Pre-flight Checks

Before queuing tasks, validate the document is ready:

2a. Status Check

Read #+STATUS: header:

StatusAction
AcceptedProceed, will set to Active
ActiveProceed with note "already in progress"
DraftWarn: "Document is still Draft. Queue anyway?"
ReviewWarn: "Document is in Review. Queue anyway?"
CompleteAbort: "Document already Complete, no tasks to queue"
ArchivedAbort: "Document was Archived"
2b. Open Questions Check

Scan * Questions section for ** OPEN headings.

If any found:

  1. List each open question with its body text
  2. For each question, help the user decide:
    • Show any options mentioned in the question body
    • Ask for their decision
    • Update the heading to ** DECIDED with :DECIDED: [YYYY-MM-DD] property
    • Add decision rationale
  3. After all resolved, continue
2c. Decision Commentary Check

Scan * Decision and * Design sections for:

  • Sub-headings: *** Comment, *** Note, *** TODO, *** FIXME
  • Inline markers: TODO:, FIXME:, NOTE:, XXX:

If found:

  1. Surface each comment/note with context
  2. Ask: "Address this before proceeding? (yes/no/skip all)"
  3. If yes: help resolve and update document
  4. If no/skip: continue

3. Task Discovery

Find * Tasks section and collect all ** TODO headings:

  • Extract task ID from heading (pattern: [PROJECT-NNN-XX])
  • Extract title (rest of heading after ID)
  • Read :EFFORT: property
  • Read body text as description

Skip headings with states: DONE, HOLD, WIP

4. Backlog Integration

Read backlog.org and for each discovered task:

New Tasks (ID not in backlog)

Add to ** Active section:

*** TODO [TASK-ID] Task Title                                            :tags:
:PROPERTIES:
:DESIGN: [[file:docs/design/NNN-doc.org::*Tasks][TASK-ID in NNN-doc.org]]
:EFFORT: <from source>
:HANDOFF:
:WORKED_BY:
:END:

<description from source>
Existing Tasks (ID found in backlog)
  • Move to ** Active if currently in Blocked or Up Next
  • Update :EFFORT: if changed in source
  • Preserve existing :HANDOFF: and :WORKED_BY:
  • Preserve existing progress notes

5. Create Claude Task List

For each queued task:

  • Create a Claude Task with matching ID and title
  • Add :CLAUDE_TASK: property to the backlog entry linking to the task
  • Set dependencies if task order implies them (sequential tasks depend on previous)

This creates the coordination layer for multi-session/subagent work.

6. Update Document Status

After queuing tasks:

  • If #+STATUS: was Accepted (or Draft/Review and user confirmed), set to Active
  • Update docs/design/README.org index to reflect new status
  • Work has begun on this design doc

7. Enter Plan Mode

Present the tasks as a plan for execution:

## Plan: Implement [Document Title]

Based on design doc [NNN], executing these tasks:

- [ ] [DAB-NNN-01] First task
- [ ] [DAB-NNN-02] Second task
- [ ] [DAB-NNN-03] Third task

Claude Task List ID: <list-id>

Proceed with plan?

The plan, backlog tasks, and Claude Tasks are now synchronized - all represent the same work.

8. Summary Output

Display results:

## Queued: NNN - Document Title

**Pre-flight:**
- Status: Accepted ✓
- Questions: 2 DECIDED, 0 OPEN ✓
- Comments: None found ✓

**Tasks queued to Active:**
- [DAB-007-01] Task title (NEW)
- [DAB-007-02] Another task (UPDATED - was in Blocked)

**Skipped:**
- [DAB-007-03] Completed task (DONE)

**Claude Tasks:**
- Task List ID: <list-id>
- Tasks created: 2
- Plan mode: Active

Examples

/queue-design-doc 007
/queue-design-doc 7
/queue-design-doc 007-queue-design-doc
/queue-design-doc docs/design/007-queue-design-doc.org

Files

  • Design docs: docs/design/*.org
  • Backlog: @backlog.org (Current WIP > Active section)

Reconcile Backlog

Scan backlog.org for stale entries, broken links, and status inconsistencies. Cross-reference with design docs, git log, and CHANGELOG.md to identify completed or orphaned tasks.

Arguments

  • --dry-run (optional): Show what would change without making modifications

Process

  1. Parse backlog.org:

    • Read * Current WIP section
    • Extract all entries from ** Active, ** Blocked, ** Up Next
    • For each entry, capture:
      • Task ID (from heading)
      • Status (TODO, WIP, HOLD)
      • :DESIGN: link (if present)
      • :CLAUDE_TASK: link (if present)
      • :GITHUB: link (if present)
      • :HANDOFF: notes
      • :WORKED_BY: attribution
  2. Validate each entry:

    a. Link validation (if :DESIGN: present):

    • Parse the file path and heading target
    • Verify the linked file exists
    • Verify the heading/task exists in that file
    • Check task status in source doc

    b. Git evidence:

    • Search for task ID in commit messages:
      git log --oneline --all --grep="TASK-ID"
      
    • Look for completion indicators ("done", "complete", "finish")

    c. CHANGELOG evidence:

    • Search CHANGELOG.md for task ID mentions
    • Search for feature descriptions matching task
  3. Classify each entry:

    ClassificationCriteriaAction
    validLinks work, no completion evidenceKeep
    orphan:DESIGN: link broken (file/heading missing)Remove or fix
    stale-sourceSource doc task is DONERemove
    stale-evidenceGit/changelog shows completedReview → Remove
    inconsistentBacklog status ≠ source statusSync
    no-linksNo :DESIGN: or other link propertiesWarn
  4. Present findings:

    ## Backlog Reconciliation
    
    ### Orphan Entries (link broken):
    - [PROJECT-010-03] - File docs/design/010-*.org exists but heading not found
      Options: [r]emove / [f]ix link / [s]kip
    
    ### Stale Entries (source marked DONE):
    - [DAB-003-02] - Source doc shows DONE, backlog shows TODO
      Will remove from backlog.
    
    ### Stale Entries (completion evidence):
    - [DAB-007-01] - Git commit abc123: "Complete queue-design-doc command"
      Mark as completed? [y/n/skip]
    
    ### Inconsistent Status:
    - [DAB-005-04] - Backlog: TODO, Source: WIP
      Sync to source status (WIP)? [y/n]
    
    ### Valid Entries (no changes):
    - [DAB-011-06] - Active, links valid
    
    ### Warnings:
    - [DAB-012-05] - No :DESIGN: link (cannot validate against source)
    
  5. Apply changes (unless --dry-run):

    • Remove orphan entries (after confirmation)
    • Remove stale entries (source DONE → auto, evidence → confirm)
    • Sync inconsistent statuses
    • Log all removals to "Recently Completed" section
  6. Handle stale sections:

    • Check for entire sections that may be stale (e.g., "Superseded by Plugin")
    • If all entries in a section are stale, offer to remove the section
    • Example:
      Section "Superseded by Plugin (010)" has 10 entries, all stale.
      Remove entire section? [y/n]
      
  7. Generate report:

    ## Backlog Reconciliation Summary
    
    ### Entries Removed: 5
    - [DAB-003-02] (source DONE)
    - [DAB-005-01] (git evidence)
    - [PROJECT-010-01] through [PROJECT-010-03] (orphan - doc restructured)
    
    ### Entries Updated: 2
    - [DAB-005-04] TODO → WIP (synced with source)
    - [DAB-007-03] Fixed :DESIGN: link
    
    ### Sections Removed: 1
    - "Superseded by Plugin (010)" (all entries stale)
    
    ### Current State:
    - Active: 3 entries
    - Blocked: 0 entries
    - Up Next: 2 entries
    
    ### Warnings:
    - 2 entries have no :DESIGN: link (manually verify)
    

Entry Classification Logic

Entry
 │
 ├─ Has :DESIGN: link?
 │   ├─ Yes → File exists?
 │   │         ├─ Yes → Heading exists?
 │   │         │         ├─ Yes → Source status?
 │   │         │         │         ├─ DONE → stale-source
 │   │         │         │         ├─ Same as backlog → valid
 │   │         │         │         └─ Different → inconsistent
 │   │         │         └─ No → orphan
 │   │         └─ No → orphan
 │   └─ No → Check git/changelog
 │             ├─ Completion evidence → stale-evidence
 │             └─ No evidence → no-links (warn)
 │
 └─ Check git/changelog anyway (supplemental)

Removal Format

When removing entries, move task ID to "Recently Completed" section:

** Recently Completed (Reconciliation 2026-01-26)

- [DAB-003-02] Implement checkout flow (reconciled: source DONE)
- [DAB-005-01] Add changelog prompt (reconciled: git evidence)

Strictness Rules

  • Never delete without evidence: Every removal requires a reason
  • Preserve history: Removed task IDs go to "Recently Completed"
  • Warn on no-links: Entries without any link property are flagged
  • Confirm orphan removal: Broken links might be fixable

Files

  • Backlog: @backlog.org (Current WIP section)
  • Design docs: @docs/design/[0-9]*.org (for link validation)
  • Evidence: git log, @CHANGELOG.md

Example

/reconcile-backlog

Interactive reconciliation with confirmations and changes applied.

/reconcile-backlog --dry-run

Show what would change without modifying backlog.org.

Related Commands

  • /reconcile-design-docs - Reconcile design doc task statuses
  • /task-complete - Manually mark a task complete
  • /task-hold - Move a task to blocked status

Reconcile Design Docs

Scan design documents and cross-reference task statuses with evidence from git log, CHANGELOG.md, and source code. Automatically fix clear-cut cases and interactively review ambiguous ones.

Arguments

  • doc-pattern (optional): Glob pattern to filter docs (e.g., 007*, *workflow*). Defaults to all numbered docs.

Process

  1. Enumerate design docs:

    • Find all docs/design/[0-9]*.org files
    • If pattern provided ($1), filter to matching docs
    • Skip docs with #+STATUS: Complete or #+STATUS: Archived
  2. For each design doc (use subagents if >3 docs):

    • Parse document header for #+STATUS: and #+TITLE:
    • Find all task headings: ** TODO, ** WIP, ** HOLD
    • Extract task IDs matching pattern [PROJECT-NNN-XX]
  3. Gather evidence for each incomplete task:

    • Git log: Search for task ID in commit messages
      git log --oneline --all --grep="TASK-ID"
      
    • CHANGELOG.md: Search for task ID or related keywords
    • Source code: Check if described functionality exists
      • For command tasks: check .claude/commands/
      • For feature tasks: search for implementation patterns
  4. Classify each task:

    • confirmed-todo: No evidence of completion
    • likely-done: Strong evidence (git commit with ID, changelog entry)
    • unclear: Partial evidence (related commits but no direct mention)
  5. Present findings and auto-fix options:

    ## Design Doc: 007-queue-design-doc.org (Active)
    
    ### Likely Complete (will mark DONE):
    - [DAB-007-01] Create command file
      Evidence: git:abc123 "Add queue-design-doc command"
    
    ### Unclear (needs review):
    - [DAB-007-03] Add pre-flight checks
      Evidence: changelog mentions "pre-flight" but no task ID
    
    ### Confirmed TODO (no changes):
    - [DAB-007-04] Support batch mode
    
    Apply auto-fixes? [y/n]:
    
  6. Apply changes:

    • For likely-done tasks (if confirmed):
      • Change ** TODO to ** DONE
      • Add CLOSED: [YYYY-MM-DD] timestamp (today's date)
      • Add :RECONCILED: property with evidence source
      • Add :COMPLETED_BY: reconciliation to indicate auto-detected
  7. Interactive review for unclear items:

    • Present evidence for each unclear task
    • Ask: "Mark as DONE? [y/n/skip]"
    • If yes, apply same changes as step 6
  8. Check document status:

    • After processing tasks, count remaining incomplete tasks
    • If all tasks are DONE or HOLD:
      • Prompt: "All tasks complete. Mark doc as #+STATUS: Complete? [y/n]"
      • If yes, update #+STATUS: and #+LAST_MODIFIED:
  9. Reconcile README.org index:

    • Parse docs/design/README.org to get listed docs and their statuses
    • Compare against actual files in docs/design/:
      • Missing entries: Docs on disk but not in README.org
      • Stale status: README.org status differs from doc's #+STATUS:
      • Orphan entries: Listed in README.org but file doesn't exist
    • Present findings:
      ## README.org Index Reconciliation
      
      ### Missing from index (will add):
      - 013-reconciliation-commands.org (Draft)
      
      ### Status mismatch (will update):
      - 007-queue-design-doc.org: README says "Active", doc says "Complete"
      
      ### Orphan entries (will remove):
      - 099-deleted-doc.org (file not found)
      
      Apply index updates? [y/n]:
      
    • If confirmed, update README.org:
      • Add missing docs to appropriate section (Core System or new section)
      • Update status values to match actual #+STATUS:
      • Remove orphan entries
  10. Generate report:

## Reconciliation Summary

### Documents Processed: 8

### Auto-Applied Changes:
- [DAB-003-02] → DONE (git evidence)
- [DAB-005-01] → DONE (changelog evidence)
- 003-backlog-workflow.org → Complete

### User-Confirmed Changes:
- [DAB-007-03] → DONE

### README.org Index Updates:
- Added: 013-reconciliation-commands.org (Draft)
- Updated: 007-queue-design-doc.org (Active → Complete)

### No Changes Needed:
- 001-system-overview.org (already Complete)
- 002-design-docs.org (2 tasks still TODO)

### Warnings:
- 010-design-doc-metadata.org has tasks without IDs (3 untracked)

Evidence Confidence Levels

Evidence TypeConfidenceAuto-apply?
Git commit mentions exact task IDHighYes
CHANGELOG entry mentions task IDHighYes
Git commit describes same workMediumReview
CHANGELOG entry describes same workMediumReview
Source code exists for featureMediumReview
File timestamps suggest doneLowNo

Strictness Rules

  • Never downgrade: A DONE task is never changed back to TODO
  • Partial is partial: If 8/10 tasks are done, doc stays Active
  • Evidence required: No status changes without at least one evidence source
  • Preserve properties: Existing :EFFORT:, :VERSION: etc. are kept

Task Format After Reconciliation

Before:

** TODO [DAB-003-02] Implement checkout flow
:PROPERTIES:
:EFFORT: M
:END:

After:

** DONE [DAB-003-02] Implement checkout flow
CLOSED: [2026-01-26]
:PROPERTIES:
:EFFORT: M
:RECONCILED: git:abc123 "Add task-queue checkout command"
:COMPLETED_BY: reconciliation
:END:

Files

  • Design docs: @docs/design/[0-9]*.org
  • Evidence sources: git log, @CHANGELOG.md, source code
  • Index: @docs/design/README.org (reconciled: missing docs added, stale statuses updated)

Example

/reconcile-design-docs

Reconcile all design docs.

/reconcile-design-docs 010*

Reconcile only doc 010 and any matching the pattern.

Related Commands

  • /reconcile-backlog - Reconcile backlog.org entries
  • /task-complete - Manually mark a single task complete
  • /queue-design-doc - Queue tasks for execution

Task Complete

Mark task $1 as DONE and reconcile with source document.

Process

  1. Find task in backlog.org under * Current WIP > ** Active:

    • Look for *** TODO [$1] or *** WIP [$1] entry
    • Get :DESIGN: link to find canonical location (if present)
    • Note :WORKED_BY: value for attribution
  2. Gather attribution:

    • Ask: "Who completed this task? (claude-code / human)"
    • Look for current transcript in ~/.claude/projects/ directory
  3. Update source document:

    • Change ** TODO to ** DONE
    • Add CLOSED: [YYYY-MM-DD] timestamp
    • If version provided ($2), add :VERSION: property
    • Add :COMPLETED_BY: from step 2
    • Add :WORKED_BY: from backlog entry
    • Add :TRANSCRIPT: link if transcript found
  4. Remove from backlog.org:

    • Delete the task entry from Active section
  5. Prompt for CHANGELOG.md:

    • Ask: "Add to CHANGELOG.md? (Added/Changed/Fixed/Removed/Skip)"
    • If not Skip, add entry under ## [Unreleased] in appropriate section
  6. Check for document completion:

    • Scan the source design doc's * Tasks section
    • Count remaining ** TODO and ** WIP entries
    • If zero remaining (all are ** DONE):
      • Prompt: "All tasks in this design doc are complete. Mark document as Complete?"
      • If yes: set #+STATUS: Complete in design doc
      • Update docs/design/README.org index
  7. Confirm the reconciliation

Example

/task-complete DAB-001-01 v1.0

Marks DAB-001-01 as DONE with version v1.0.

Format in Source Doc

Before:

** TODO [DAB-001-01] Task title
:PROPERTIES:
:EFFORT: M
:END:

After:

** DONE [DAB-001-01] Task title
CLOSED: [2026-01-04]
:PROPERTIES:
:EFFORT: M
:VERSION: v1.0
:COMPLETED_BY: claude-code
:WORKED_BY: claude-code, human
:TRANSCRIPT: [[file:~/.claude/projects/.../conversation.md]]
:END:

Files

  • Backlog: @backlog.org (Current WIP section)
  • Follow :DESIGN: link to find canonical location (if present)

Task Hold

Move task $1 to blocked/hold status with reason: $2

Process

  1. Find task in backlog.org under * Current WIP > ** Active:

    • Look for *** TODO [$1] entry
  2. Move to Blocked section:

    • Cut the task from ** Active
    • Paste under ** Blocked
    • Add :REASON: property with the provided reason
  3. Confirm the move

Example

/task-hold DAB-001-01 Waiting for dependency release

Format in backlog.org

Before (in Active):

*** TODO [DAB-001-01] Task title
:PROPERTIES:
:DESIGN: [[file:...][...]]
:EFFORT: M
:END:

After (in Blocked):

*** TODO [DAB-001-01] Task title
:PROPERTIES:
:DESIGN: [[file:...][...]]
:EFFORT: M
:REASON: Waiting for dependency release
:END:

Files

  • Backlog: @backlog.org (Current WIP section)

Task Link

Add link properties to backlog task $ARGUMENTS.

Purpose

The backlog is a hub linking to tasks wherever they live. This command adds those links to existing tasks—connecting a backlog entry to its representations in other systems.

Usage

/task-link <task-id> --github <url>
/task-link <task-id> --claude-task <task-list-id>/<task-id>
/task-link <task-id> --bead <session>/<task>
/task-link <task-id> --design <path-to-design-doc>::*<heading>

Multiple links can be added at once:

/task-link DAB-012-02 --github https://github.com/org/repo/issues/15 --claude-task abc123/task-001

Process

1. Find Task in Backlog

Search backlog.org for the task ID in:

  • * Current WIP > ** Active
  • * Current WIP > ** Blocked
  • * Up Next

If not found, report error and suggest /task-queue to add it first.

2. Parse Link Arguments

Extract link type and value from arguments:

FlagPropertyExample Value
--github:GITHUB:https://github.com/org/repo/issues/15
--claude-task:CLAUDE_TASK:abc123/task-001
--bead:BEAD:session-xyz/task-002
--design:DESIGN:docs/design/012-doc.org::*Tasks

3. Format Link Properties

Convert to org-mode link format:

GitHub:

:GITHUB: [[https://github.com/org/repo/issues/15][#15]]

Claude Task:

:CLAUDE_TASK: abc123/task-001

Bead:

:BEAD: [[bead:session-xyz/task-002][bead ref]]

Design:

:DESIGN: [[file:docs/design/012-doc.org::*Tasks][DAB-012-02 in 012-doc.org]]

4. Update Task Properties

Add the new properties to the task's :PROPERTIES: drawer.

  • If property already exists, ask before overwriting
  • Preserve all existing properties
  • Add new properties in standard order: DESIGN, CLAUDE_TASK, GITHUB, BEAD, then metadata

5. Confirm Changes

Display the updated task:

## Linked: [DAB-012-02] Task Title

Added:
- :GITHUB: [[https://github.com/org/repo/issues/15][#15]]

Properties now:
- :DESIGN: [[file:...][...]]
- :CLAUDE_TASK: abc123/task-001
- :GITHUB: [[https://github.com/org/repo/issues/15][#15]]
- :EFFORT: M

Examples

# Link to GitHub issue
/task-link DAB-012-02 --github https://github.com/farra/dev-agent-backlog/issues/15

# Link to Claude Task
/task-link DAB-012-02 --claude-task dab-012/task-002

# Link to design doc (if task was added directly to backlog)
/task-link FIX-001 --design docs/design/015-bugfix.org::*Tasks

# Multiple links at once
/task-link DAB-012-02 --github https://github.com/org/repo/issues/15 --bead session-abc/task-002

Use Cases

  1. Task originated in GitHub: Issue created in GitHub, now tracking in backlog
  2. Retroactive design doc: Quick fix now being formalized in a design doc
  3. Cross-session work: Adding Claude Task link for coordination
  4. Multiple systems: Same task tracked in GitHub AND design doc

Files

  • Backlog: backlog.org

Task Queue

Queue task $ARGUMENTS into the backlog.org Active section.

Process

  1. Find the task in design docs:

    • Look in docs/design/*.org for the task ID
    • Task IDs follow pattern [PROJECT-NNN-XX]
  2. Extract task info:

    • Full heading
    • :EFFORT: property if present
    • Source file path
  3. Add to backlog.org:

    • Insert under * Current WIP > ** Active section
    • Use this format:
*** TODO [TASK-ID] Task Title
:PROPERTIES:
:DESIGN: [[file:docs/design/NNN-doc.org::*heading][TASK-ID in doc.org]]
:EFFORT: <from source>
:HANDOFF:
:WORKED_BY:
:END:

<brief description>
  • :HANDOFF: starts empty (populated during work)
  • :WORKED_BY: starts empty (updated by /task-start)
  1. Update source doc status:

    • Read the source design doc's #+STATUS: header
    • If status is Accepted, change to Active (work has begun)
    • If status is Draft or Review, leave as-is (task can still be queued)
    • Update docs/design/README.org index if status changed
  2. Confirm by showing the new entry

Files

  • Backlog: @backlog.org (Current WIP > Active section)
  • Design docs: docs/design/*.org

Start Task

Start or resume work on task $ARGUMENTS.

Process

1. Check if Task is in Backlog

Look for the task in backlog.org under * Current WIP > ** Active.

  • If found: proceed to step 2
  • If NOT found: run /task-queue $ARGUMENTS first to add it

2. Read Task Context and Handoff

From the task entry in backlog.org:

  • Read any existing progress notes
  • Check :HANDOFF: property for notes from previous session
  • Follow the :DESIGN: link to the design doc (if present)
  • Read the full task description and related context

If :HANDOFF: has content, display prominently:

## Resuming [$ARGUMENTS]

**Handoff from last session:**
> <handoff notes here>

2a. Update Attribution

  • Change task state from TODO to WIP
  • Add claude-code to :WORKED_BY: if not already present

2b. Create Claude Task (Execution Time Sync)

Create a Claude Task for this work and link it from backlog.org:

  1. Create Claude Task with:

    • ID matching the task ID (e.g., DAB-001-01)
    • Title from the task heading
    • Status: in_progress
  2. Add :CLAUDE_TASK: property to backlog entry:

    :CLAUDE_TASK: <task-list-id>/<task-id>
    

This is the "execution time" trigger for backlog → Claude Task sync. The Claude Task enables cross-session coordination if work spans multiple sessions.

3. Gather Related Context

Read the full design doc containing the task:

  • Motivation section (why this matters)
  • Design section (how it should work)
  • Related tasks (dependencies, sequence)
  • Open questions (blockers, decisions needed)

4. Prepare Implementation Plan

Create a plan with:

  • Goal: What we're trying to achieve
  • Approach: How we'll implement it
  • Files to modify: List of files we'll touch
  • Steps: Ordered implementation steps
  • Open questions: Anything that needs clarification

5. Present Plan for Review

Present the plan to the user for approval before beginning implementation.

Example

/task-start DAB-001-01

Files

  • Backlog: backlog.org (Current WIP > Active)
  • Design docs: docs/design/*.org

Sponsors

Details

Marketplace
farra/dev-agent-backlog
Source
plugin
Author
J. Aaron Farr
Category
Productivity
License
MIT
Keywords
design-docs, backlog, task-management, org-mode, workflow