backlog - Task Management Plugin

Manage your tasks/ directory backlog and git worktrees for autonomous agent execution with memory-enabled agents that survive context compaction.

v5.0 Design Principle: Exit Permission ≠ State Transition

Important: In v5.0, we separated two concepts that were previously conflated:

Exit Permission - Whether the stop hook allows the agent to exit the session
State Transition - Changing task status in INDEX.md

Promise Tags (Exit Signals Only)

Promise	Meaning
`<promise>PHASE_DONE</promise>`	"I finished my assigned phase, let me exit"
`<promise>BLOCKED: reason</promise>`	"I can't proceed, let me exit"

These signals ONLY control whether the stop hook allows exit. They do NOT change task status.

State Transitions (Explicit Commands Only)

Command	From Status	To Status
`/backlog:launch`	Ready	In Progress
`/backlog:work`	Ready	In Progress
`/backlog:review`	In Progress	In Review
`/backlog:complete`	In Progress/In Review	Complete

You control the workflow. Agent exit does not trigger /backlog:complete.

Installation

/plugin marketplace add cyotee/cyotee-claude-plugins
/plugin install backlog@cyotee

Commands

`/backlog`

Display a summary table of all tasks from the tasks/ directory.

Aliases: /backlog:status

What it does:

Scans for tasks/ directories in the repository
Reads tasks/INDEX.md or scans task directories
Generates a status table of all tasks
Shows summary counts (completed, ready, blocked)
Recommends the next task to work on

Example output:

# Backlog Status - [Layer Name]

| # | Title | Status | Worktree | Dependencies | Created |
|---|-------|--------|----------|--------------|---------|
| [P]-1 | Feature One | ✅ complete | - | - | 2026-01-05 |
| [P]-2 | Feature Two | 🚀 in_progress | `feature/two` | [P]-1 | 2026-01-08 |
| [P]-3 | Feature Three | 🆕 pending | - | [P]-2 | 2026-01-10 |

Summary:
- ✅ Complete: 1
- 🚀 In Progress: 1
- 🆕 Pending: 1

Recommended next: [P]-3 (after [P]-2 completes)

`/backlog:read <task-id>`

Display the full content of a specific task.

What it does:

Parses task ID (e.g., P-5 or just 5)
Detects layer from prefix or current directory
Reads PRD.md, PROGRESS.md, and REVIEW.md
Displays formatted task summary

Example usage:

/backlog:read P-5

`/backlog:launch <task-id>`

Create a git worktree and launch a memory-enabled agent for a task.

What it does:

Reads the task from tasks/[ID]/PRD.md
Checks worktree state (new, existing clean, existing dirty, behind main)
Creates worktree using ./scripts/wt-create.sh if needed
Generates PROMPT.md in worktree root with:
- Memory protocol instructions
- Task summary and key requirements
- Context management (/compact and reload instructions)
- Completion criteria
Creates or preserves PROGRESS.md in tasks/[ID]/ with:
- Checkpoints section for resumable state
- Work log for tracking actions
Updates task status to in_progress
Updates tasks/INDEX.md
Outputs launch instructions for the human

Worktree States:

State	Action
Doesn't exist	Create new worktree, fresh PROMPT.md and PROGRESS.md
Exists, clean	Ask about PROMPT.md (review/regenerate/keep), preserve PROGRESS.md
Exists, dirty	Warn about uncommitted changes, ask how to proceed
Behind local main	Suggest `git merge main` before continuing

Example usage:

/backlog:launch I-5

Example output:

================================================================================
# Task I-5: Protocol DETF System
================================================================================

**Status:** in_progress
**Worktree:** /path/to/repo-wt/feature/protocol-detf
**Dependencies:** None

## Launch Commands

Run these commands to start the agent:

    cd /path/to/repo-wt/feature/protocol-detf
    claude --dangerously-skip-permissions

## Start the Agent

Once Claude Code is running, enter this command:

    /ralph-loop:ralph-loop "Read PROMPT.md and follow its instructions. This file tells you which other files to read and how to track your progress." --completion-promise "PHASE_DONE" --max-iterations 15

## Files Created/Updated

- PROMPT.md (worktree root) - Agent instructions with memory protocol
- tasks/I-5/PROGRESS.md - Work log and resumable state

## When Complete

The agent will output `<promise>PHASE_DONE</promise>` when done.

Then return to this session and choose your next step:

    /backlog:review I-5      # Transition to code review mode
    # OR
    /backlog:complete I-5    # Skip review, mark complete

================================================================================

Memory Protocol:

The generated PROMPT.md instructs the agent to:

Read CLAUDE.md, PRD.md, and PROGRESS.md on every iteration
Update PROGRESS.md after each significant action
When context gets long: update PROGRESS.md, run /compact, then re-read all files
Use the Checkpoints section in PROGRESS.md for resumable state

This allows agents to survive context compaction and resume work across sessions.

`/backlog:complete [task-id] [--push]`

Finalize a completed task using a two-phase workflow for smooth completion.

Two-Phase Workflow:

Phase 1: Prepare from Task Worktree

Run from the task's worktree (NOT main):

Commits all final changes (EXCEPT PROMPT.md which is auto-excluded)
Rebases the worktree branch onto local main
Marks task as "Pending Merge" in INDEX.md
Displays instructions to run Phase 2 from main

Phase 2: Finalize from Main Worktree

Run from the main worktree:

Verifies task is "Pending Merge" and fast-forward is possible
Fast-forward merges main to include the task's commits
Marks task as "Complete" in INDEX.md
Updates dependent tasks (unblocks blocked tasks)
Archives task files to tasks/archive/
Removes the worktree and branch automatically
Displays completion summary with unblocked tasks

Key Benefits:

✓ PROMPT.md automatically excluded from commits
✓ Clean linear history (fast-forward only)
✓ Automatic worktree cleanup
✓ Automatic task archival
✓ Dependency cascade updates
✓ Safe rollback between phases

Arguments:

Argument	Description
`<task-id>`	Task ID (e.g., CRANE-003) - optional, prompts if not provided
`--push`	Push main to origin after merge (Phase 2 only)

Example:

# Phase 1: In task worktree
$ /backlog:complete CRANE-003
# → Commits changes, rebases, marks "Pending Merge"

# Phase 2: In main worktree
$ /backlog:complete CRANE-003 --push
# → Merges, archives, cleans up, unblocks dependents

`/backlog:prune [task-id] [--all]`

Archive completed and reviewed tasks.

What it does:

Identifies tasks with status: complete and passing review
Moves task directories to tasks/archive/
Updates tasks/INDEX.md
Outputs cleanup instructions for worktrees

Arguments:

Argument	Description
`<task-id>`	Specific task to archive (e.g., P-5)
`--all`	Archive all completed tasks

`/backlog:list [--worktrees-only]`

List all unarchived tasks with their status, dependencies, and worktrees.

Aliases: /backlog:worktrees (with --worktrees-only)

What it does:

Reads tasks/INDEX.md and builds dependency graph
Computes effective status for each task (blocked if deps incomplete)
Cross-references with git worktrees
Displays unified task list with status icons

Example output:

═══════════════════════════════════════════════════════════════════
 TASK LIST: IndexedEx

| ID | Title | Status | Dependencies | Worktree |
|----|-------|--------|--------------|----------|
| IDXEX-001 | Core infrastructure | ✅ Complete | - | - |
| IDXEX-002 | Registry system | 🚀 In Progress | - | feature/registry |
| IDXEX-003 | Fee collector | ❌ Blocked | IDXEX-002 | - |
| IDXEX-004 | Vault types | 🆕 Ready | IDXEX-001 | - |

## Summary

Total: 4 tasks
✅ Complete: 1 | 🚀 In Progress: 1 | 🆕 Ready: 1 | ❌ Blocked: 1

## Next Actions

Ready to start:
- /backlog:launch IDXEX-004

Currently blocked:
- IDXEX-003: Waiting on IDXEX-002
═══════════════════════════════════════════════════════════════════

Arguments:

Argument	Description
`--worktrees-only`	Show only active worktrees (legacy behavior)

Status Icons:

Icon	Status	Description
✅	Complete	Task finished and merged
🚀	In Progress	Agent actively working
📋	In Review	Work complete, code review
🆕	Ready	All dependencies met, can start
❌	Blocked	Waiting on dependencies

Layer Detection

Layers are detected dynamically:

# Find all tasks/ directories
find . -type d -name "tasks" -not -path "*/node_modules/*" 2>/dev/null

For each discovered tasks/ directory:

Read tasks/INDEX.md for layer name and prefix
If not found, auto-detect from directory/repo name
Prefix is first letter of layer name (uppercase)

Task States

State	Icon	Description
pending	🆕	Ready to start, dependencies met
in_progress	🚀	Agent actively working
review	📋	Work complete, awaiting review
complete	✅	Reviewed and approved
blocked	❌	Waiting on dependencies

Scripts

The plugin includes submodule-aware worktree management scripts in scripts/:

`wt-create.sh`

Creates a worktree with proper submodule initialization:

"${CLAUDE_PLUGIN_ROOT}/scripts/wt-create.sh" <branch-name> [repo-root]

`wt-remove.sh`

Removes a worktree safely (handles submodules):

"${CLAUDE_PLUGIN_ROOT}/scripts/wt-remove.sh" <branch-name> [repo-root]

Why scripts instead of git wt -d?

Worktrees with submodules can't be removed without --force
Submodule pointers can become corrupt
Lock files cause "Another git process" errors
Nested submodules need fallback copying when git init fails

Requirements

git-wt or wt-create.sh: Git worktree helper
tasks/: Task directory (created by /design:init)

Workflow Integration

1. /design <feature>      # Create task in tasks/
2. /backlog               # View all tasks
3. /backlog:read I-5      # Read task details
4. /backlog:launch I-5    # Create worktree + PROMPT.md + PROGRESS.md
5. cd <worktree>          # Human switches to worktree
6. claude --skip-perms    # Human starts Claude Code
7. /up:prompt             # Agent reads PROMPT.md and works
8. (agent works)          # Agent executes, updates PROGRESS.md
9. <promise>PHASE_DONE    # Agent signals completion, exits
10. /backlog:review I-5   # (Optional) Transition to code review
11. (reviewer works)      # Reviewer checks code, writes REVIEW.md
12. <promise>PHASE_DONE   # Reviewer signals completion, exits
13. /backlog:complete I-5 # Mark complete, merge, cleanup

Key Points:

Steps 9 and 12 are agent exit signals (PHASE_DONE)
Steps 10 and 13 are YOUR commands (you control the workflow)
You can skip step 10 and go directly to step 13 if you don't want review

Memory Protocol Files

PROMPT.md (worktree root)

Generated by /backlog:launch. Contains:

Memory protocol instructions for the agent
Task summary extracted from PRD.md
Key requirements as bullet list
Context management instructions (/compact handling)
Completion criteria

PROGRESS.md (tasks/[ID]/)

Maintained by the agent. Contains:

Checkpoints section: Resumable state after /compact
- Current phase
- Files modified
- Test status
- Next action
Work Log: Reverse-chronological record of actions

Example PROGRESS.md structure:

# Progress: I-5 - Protocol DETF System

**Started:** 2026-01-11 14:30
**Status:** in_progress

## Checkpoints

**Current phase:** Implementing CHIR token
**Files modified:** contracts/tokens/CHIR.sol, test/CHIR.t.sol
**Tests passing:** 3/5 passing
**Next action:** Fix failing rebasing tests

---

## Work Log

### 2026-01-11 15:45 - Implemented base token

- Completed: CHIR ERC20 with mint/burn
- Files modified: contracts/tokens/CHIR.sol
- Next: Add rebasing logic
- Blockers: None

---

Requirements

ralph-loop plugin: For autonomous agent loops
git-wt or wt-create.sh: Git worktree helper
tasks/: Task directory (created by /design:init)

License

MIT