
backlog
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-backlogRun it inside Claude Code after adding the marketplace with /plugin marketplace add farra/dev-agent-backlog.
Contents
Discovered from sourceSkills 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.orgexists 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
*** DONEin 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
** DONEbut 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-backlogto clean up
- Suggest running
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
| Command | When 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 commitor 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.mdif 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:
- Follow the
:DESIGN:link to the source design doc - Check the
#+STATUS:of that document - Scan its
* Taskssection for remaining** TODOor** WIPentries - 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.orgindex
- Prompt: "All tasks in [doc name] are complete. Update
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
| Command | When 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-doccreates a Task List - When completing work that involved Claude Tasks
Workflow
1. When Creating Claude Tasks
After creating one or more Claude Tasks:
- Read backlog.org's
* Current WIP>** Activesection - 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:
- Note the Task List ID being used
- After subagent completes, check for any new Tasks created
- 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
| Skill | Relationship |
|---|---|
backlog-update | Updates existing entries; this creates new ones |
backlog-resume | Reads :CLAUDE_TASK: links on session start |
Related Commands
| Command | Relationship |
|---|---|
/task-start | Creates Claude Task at execution time |
/queue-design-doc | Creates 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.orgin the project root, ORdocs/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
.mddesign 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 Categoriestable) - 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:
- Fill in Summary - one paragraph overview
- Fill in Motivation - why this matters, what problem it solves
- Fill in Design - options considered with tradeoffs
- Add Tasks - implementation work with
[PROJECT-NNN-XX]IDs - Add Questions - open issues as
** OPEN
For conversion: Use /new-design-doc <title> <source.md> to convert, then:
- Review the converted structure
- Verify task IDs are properly assigned
- Check that code blocks converted correctly
- 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 fromREADME.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-queuefor each selected task
What Makes a Good Design Doc
| Section | Good | Bad |
|---|---|---|
| Summary | "Add caching layer to reduce API latency" | "Caching stuff" |
| Motivation | Explains the problem and why it matters | Jumps to solution |
| Design | Shows 2-3 options with tradeoffs | Only shows chosen option |
| Tasks | Specific, actionable, has IDs | Vague, no IDs |
Conversion Rules Summary
| Markdown | Org-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.orgwith#+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:
| Template | Destination | Substitution |
|---|---|---|
readme-project.org | README.org | Replace PROJECT with prefix |
readme-design.org | docs/design/README.org | None |
org-setup.org | org-setup.org | Replace PROJECT with prefix |
backlog-template.org | backlog.org | Replace PROJECT with prefix |
design-doc-template.org | docs/design/000-template.org | Replace PROJECT with prefix |
changelog-template.md | CHANGELOG.md | None |
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 fordocs/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.orgindex - 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:
- Display the question and any context/options in its body
- Discuss with the user to reach a decision
- When decided:
- Change
** OPENto** DECIDED - Add
:DECIDED: [YYYY-MM-DD]property - Add decision rationale to the body
- Change
- 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:
- Surface the item with surrounding context
- Ask: "How should we resolve this?"
- 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:toAccepted - Update
docs/design/README.orgindex - Announce: "Document is now Accepted and ready for implementation"
If no:
- Leave as
Reviewfor 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-doclogic
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
| Markdown | Org-Mode |
|---|---|
# Heading | * Heading |
## Heading | ** Heading (under appropriate parent) |
### Heading | *** Heading |
Tasks
| Markdown | Org-Mode |
|---|---|
- [ ] Task text | ** TODO [PROJECT-NNN-XX] Task text |
- [x] Task text | ** DONE [PROJECT-NNN-XX] Task text |
Code
| Markdown | Org-Mode |
|---|---|
```rust | #+begin_src rust |
``` | #+end_src |
Frontmatter
| Markdown YAML | Org-Mode |
|---|---|
title: X | #+TITLE: X |
status: X | #+STATUS: X |
author: X | #+AUTHOR: X |
Questions/Decisions
| Markdown Pattern | Org-Mode |
|---|---|
**Open Question:** or - [ ] Question? in Questions section | ** OPEN Question? |
**Decision:** or - [x] Decided thing in Questions section | ** DECIDED Decided thing |
Links
| Markdown | Org-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 titlefor tasks (not markdown checkboxes)** OPEN/** DECIDEDfor questions:PROPERTIES:drawers for metadata (EFFORT, VERSION, etc.)#+SETUPFILE: ../../org-setup.orgfor 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 fordocs/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:
| Status | Action |
|---|---|
| Accepted | Proceed, will set to Active |
| Active | Proceed with note "already in progress" |
| Draft | Warn: "Document is still Draft. Queue anyway?" |
| Review | Warn: "Document is in Review. Queue anyway?" |
| Complete | Abort: "Document already Complete, no tasks to queue" |
| Archived | Abort: "Document was Archived" |
2b. Open Questions Check
Scan * Questions section for ** OPEN headings.
If any found:
- List each open question with its body text
- For each question, help the user decide:
- Show any options mentioned in the question body
- Ask for their decision
- Update the heading to
** DECIDEDwith:DECIDED: [YYYY-MM-DD]property - Add decision rationale
- 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:
- Surface each comment/note with context
- Ask: "Address this before proceeding? (yes/no/skip all)"
- If yes: help resolve and update document
- 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
** Activeif 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:wasAccepted(orDraft/Reviewand user confirmed), set toActive - Update
docs/design/README.orgindex 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
-
Parse backlog.org:
- Read
* Current WIPsection - 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
- Read
-
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
-
Classify each entry:
Classification Criteria Action validLinks work, no completion evidence Keep orphan:DESIGN:link broken (file/heading missing)Remove or fix stale-sourceSource doc task is DONE Remove stale-evidenceGit/changelog shows completed Review → Remove inconsistentBacklog status ≠ source status Sync no-linksNo :DESIGN:or other link propertiesWarn -
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) -
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
-
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]
-
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
-
Enumerate design docs:
- Find all
docs/design/[0-9]*.orgfiles - If pattern provided ($1), filter to matching docs
- Skip docs with
#+STATUS: Completeor#+STATUS: Archived
- Find all
-
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]
- Parse document header for
-
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
- For command tasks: check
- Git log: Search for task ID in commit messages
-
Classify each task:
confirmed-todo: No evidence of completionlikely-done: Strong evidence (git commit with ID, changelog entry)unclear: Partial evidence (related commits but no direct mention)
-
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]: -
Apply changes:
- For
likely-donetasks (if confirmed):- Change
** TODOto** DONE - Add
CLOSED: [YYYY-MM-DD]timestamp (today's date) - Add
:RECONCILED:property with evidence source - Add
:COMPLETED_BY: reconciliationto indicate auto-detected
- Change
- For
-
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
-
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:
-
Reconcile README.org index:
- Parse
docs/design/README.orgto 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
- Parse
-
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 Type | Confidence | Auto-apply? |
|---|---|---|
| Git commit mentions exact task ID | High | Yes |
| CHANGELOG entry mentions task ID | High | Yes |
| Git commit describes same work | Medium | Review |
| CHANGELOG entry describes same work | Medium | Review |
| Source code exists for feature | Medium | Review |
| File timestamps suggest done | Low | No |
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
-
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
- Look for
-
Gather attribution:
- Ask: "Who completed this task? (claude-code / human)"
- Look for current transcript in
~/.claude/projects/directory
-
Update source document:
- Change
** TODOto** 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
- Change
-
Remove from backlog.org:
- Delete the task entry from Active section
-
Prompt for CHANGELOG.md:
- Ask: "Add to CHANGELOG.md? (Added/Changed/Fixed/Removed/Skip)"
- If not Skip, add entry under
## [Unreleased]in appropriate section
-
Check for document completion:
- Scan the source design doc's
* Taskssection - Count remaining
** TODOand** WIPentries - If zero remaining (all are
** DONE):- Prompt: "All tasks in this design doc are complete. Mark document as Complete?"
- If yes: set
#+STATUS: Completein design doc - Update
docs/design/README.orgindex
- Scan the source design doc's
-
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
-
Find task in backlog.org under
* Current WIP>** Active:- Look for
*** TODO [$1]entry
- Look for
-
Move to Blocked section:
- Cut the task from
** Active - Paste under
** Blocked - Add
:REASON:property with the provided reason
- Cut the task from
-
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:
| Flag | Property | Example 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
- Task originated in GitHub: Issue created in GitHub, now tracking in backlog
- Retroactive design doc: Quick fix now being formalized in a design doc
- Cross-session work: Adding Claude Task link for coordination
- 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
-
Find the task in design docs:
- Look in
docs/design/*.orgfor the task ID - Task IDs follow pattern
[PROJECT-NNN-XX]
- Look in
-
Extract task info:
- Full heading
:EFFORT:property if present- Source file path
-
Add to backlog.org:
- Insert under
* Current WIP>** Activesection - Use this format:
- Insert under
*** 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)
-
Update source doc status:
- Read the source design doc's
#+STATUS:header - If status is
Accepted, change toActive(work has begun) - If status is
DraftorReview, leave as-is (task can still be queued) - Update
docs/design/README.orgindex if status changed
- Read the source design doc's
-
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 $ARGUMENTSfirst 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-codeto: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:
-
Create Claude Task with:
- ID matching the task ID (e.g.,
DAB-001-01) - Title from the task heading
- Status: in_progress
- ID matching the task ID (e.g.,
-
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