backlog

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:

1. Exit Permission - Whether the stop hook allows the agent to exit the session
2. 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:

1. Scans for tasks/ directories in the repository
2. Reads tasks/INDEX.md or scans task directories
3. Generates a status table of all tasks
4. Shows summary counts (completed, ready, blocked)
5. 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:

1. Parses task ID (e.g., P-5 or just 5)
2. Detects layer from prefix or current directory
3. Reads PRD.md, PROGRESS.md, and REVIEW.md
4. 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:

1. Reads the task from tasks/[ID]/PRD.md
2. Checks worktree state (new, existing clean, existing dirty, behind main)
3. Creates worktree using ./scripts/wt-create.sh if needed
4. Generates PROMPT.md in worktree root with:
   • Memory protocol instructions
   • Task summary and key requirements
   • Context management (/compact and reload instructions)
   • Completion criteria
5. Creates or preserves PROGRESS.md in tasks/[ID]/ with:
   • Checkpoints section for resumable state
   • Work log for tracking actions
6. Updates task status to in_progress
7. Updates tasks/INDEX.md
8. 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: