todo-work

Work on a TODO Item

Companion to /todo. Surfaces pending items from TODO.md, lets the user pick one, optionally marks it as In progress, and proposes a hand-off to the downstream skill (/review-plan or /implement) by printing the exact command to run next.

Purpose

/todo is append-only — it captures items but never surfaces them back out. This skill closes the loop: read TODO.md, filter to pending items, pick one, and kick off work with a single interactive flow.

When to Use

• Picking the next item to work on from TODO.md
• Starting ad-hoc work captured earlier in the session
• Deciding whether an item needs plan validation before implementation

When NOT to Use

• Adding a new item → /todo
• Resuming an in-flight skill session → /resume-work
• Listing active work sessions (not TODO items) → /work-status

Arguments

/todo-work [item number]

item number (optional): 1-indexed position in the sorted pending list. If provided, skip the pick question and jump to the next-action question.

---

Process

Step 1: Locate and Read TODO.md

TODO_FILE="TODO.md"

If TODO.md does not exist in the project root, stop with:

No TODO.md found in the project root. Use /todo to add your first item.

Otherwise, read the full file with the Read tool.

Step 2: Parse Pending Items

Extract every ### {title} block. For each block, pull these fields (match case-insensitively, accept the value on the same line):

• **Status:** {status}
• **Priority:** {priority} (strip leading emoji)
• **Category:** {category}
• **Scope:** {scope}

Plus the free-text description (everything between the metadata block and the next --- or ### heading or end-of-file).

Keep only pending items. An item is pending if its status matches (case-insensitive): Proposed, Not started, Needs discussion. Skip anything else (In progress, Done, Completed, Archived, etc.).

If the item is missing any of the four metadata fields, treat the missing field as unknown — do not drop the item. Record which field was missing so the list display can flag it with (missing metadata).

Step 3: Sort

Sort pending items by priority (emergency → high → medium → low → unknown), with document order as tiebreaker. Number them 1..N in the sorted order; this number is what the optional [item number] argument selects and what the user sees in the list.

Priority sort key (higher wins):

• emergency = 4
• high = 3
• medium = 2
• low = 1
• anything else = 0

Step 4: Handle Empty Result

If zero pending items, stop with:

No pending TODO items. Use /todo to add one, or /work-status to see active work sessions.

Step 5: Pick Item

If $ARGUMENTS contains a positive integer N and 1 ≤ N ≤ count(pending): Use item N. Skip the inline list and AskUserQuestion entirely.

Otherwise (no numeric argument):

1. Print the full pending list inline, using the 1..N sorted index from Step 3.

   Header: Pending TODO items ({N} total):

   Format, one line per item:

   {N}. [{priority}] {title}{ (missing metadata) if any of the four fields was unknown}
   

   Example:

   Pending TODO items (7 total):
   1. [medium] Integrate playwright-engineer into /implement QA phase
   2. [medium] Knowledge Sync workflow implementation
   3. [medium] Consider changing todo list to JSON
   4. [medium] Update 'todo-work' skill to list existing items
   5. [low] Evaluate Garry Tan's plan mode prompt
   6. [low] Expand agent test coverage
   7. [low] Implement true action-based audit trail
   

   Titles only — no descriptions, categories, or scope in the inline list (those stay in the AskUserQuestion option descriptions for the top 3).

2. Then use AskUserQuestion to pick from the top 3 as quick-select shortcuts:

   • header: "Pick item"
   • question: "Which TODO item should we work on?"
   • options (up to 4 total: up to 3 items + Cancel; each item label is short, description shows priority + category + scope):
     • {title} / priority · category · scope
     • ... up to 3 items ...
     • Cancel / Don't start any item — exit
   • multiSelect: false

   The AskUserQuestion tool enforces a maximum of 4 options, so the pick list must stay at 3 items + Cancel. If more than 3 pending items exist, include this note above the question: "Showing top 3 as quick-select options. Use /todo-work {N} to jump to any item from the list above."

If the user picks Cancel, stop with: No item selected.

Step 6: Confirm Next Action

Display the selected item:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Selected: {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Priority: {priority}
Category: {category}
Scope:    {scope}
Status:   {status}

{description — if present}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then use AskUserQuestion:

• header: "Next action"
• question: "How do you want to start on this item?"
• options:
  • "Validate plan first (Recommended for non-trivial)" / "Hand off to /review-plan — architect and quality-guard review the plan before implementation"
  • "Implement directly" / "Hand off to /implement — skip plan review, go straight to coding"
  • "Just show details" / "Print the item and stop — no handoff, no status change"
• multiSelect: false

Step 7: Mark In Progress (unless show-details-only)

If the user chose Just show details: Skip to Step 9. Do not modify TODO.md.

Otherwise: Update the selected item's status line in TODO.md from its current value to In progress using the Edit tool.

Find the exact line by matching the heading + the Status line belonging to this item. Use this Edit pattern:

old_string:
### {title}

**Status:** {current_status}

new_string:
### {title}

**Status:** In progress

If the Edit fails (e.g., because {title} or {current_status} is not unique in the file), surface a warning and continue without updating — do not abort the handoff:

⚠️  Could not mark item as In progress (status line not unique in TODO.md).
    Handoff will proceed; update the status manually if needed.

Step 8: Create Isolated Worktree (skip for show-details-only)

If the user chose Just show details: Skip to Step 9. No worktree.

Otherwise: Create a git worktree off the remote default branch with a new feature branch so downstream code changes happen in isolation from the current working tree.

1. Derive a slug from the selected item's title:

   • Lowercase, ASCII only.
   • Drop filler words (the, a, an, to, for, of, add, update, fix).
   • Keep 2–5 meaningful words, joined with -.
   • Strip any character outside [a-z0-9-].
   • If the title contains a ticket-like prefix ([A-Z]+-[0-9]+), keep it as {TICKET}-{slug}. Otherwise use the slug alone (no prefix).

2. Detect the default remote branch and create the worktree:

   DEFAULT_BRANCH=$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|^origin/||')
   if [ -z "$DEFAULT_BRANCH" ] || [ "$DEFAULT_BRANCH" = "HEAD" ]; then
     DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | awk '/HEAD branch/{print $NF}')
   fi
   DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
   REPO_ROOT=$(git rev-parse --show-toplevel)
   
   if [ -f "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh" ]; then
     source "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh"
   elif [ -f "$HOME/.claude/shared/resolve-config.sh" ]; then
     source "$HOME/.claude/shared/resolve-config.sh"
   fi
   WT_ROOT=$(resolve_worktree_root 2>/dev/null || echo ".worktrees")
   WORKTREE_PATH="$REPO_ROOT/$WT_ROOT/{branch-suffix}"
   
   git fetch -q origin "$DEFAULT_BRANCH"
   git worktree add -b feature/{branch-suffix} "$WORKTREE_PATH" "origin/$DEFAULT_BRANCH"
   

   resolve_worktree_root reads worktree.root from .claude/configuration.yml when present, falling back to .worktrees/ — matching the pattern used by /refactor, /update-documentation, and /implement.

   Where {branch-suffix} is the value derived in step 1 (e.g., JIRA-123-webhook-support or broken-readme-link).

3. Enter the worktree using the EnterWorktree tool with path: {WORKTREE_PATH} (the absolute path from step 2). EnterWorktree with path: enters an already-registered worktree; git worktree add above registers it, so git worktree list will include this path. From this point the session is isolated.

4. If the worktree already exists (branch name collision), surface a warning and continue without creating one — the user can run the handoff command in the existing worktree manually:

   ⚠️  Worktree feature/{branch-suffix} already exists. Continuing in current tree.
       Switch manually with: cd $WT_ROOT/{branch-suffix}
   

5. If git fetch or worktree creation fails for any other reason, surface the error and continue with the handoff in the current tree — do not abort.

Step 9: Propose Hand-off

Print a hand-off block that shows the user the exact command to run next. Do not invoke another skill — slash commands are user-invoked; /todo-work stops after printing.

For Validate plan first → /review-plan:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Handing off to /review-plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Item:     {title}
Status:   {Proposed|Not started|Needs discussion} → In progress
Worktree: .worktrees/{branch-suffix}  (branch feature/{branch-suffix}, from origin/{default-branch})

Run next:

  /review-plan {title}
  {if description present:}
  {description}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For Implement directly → /implement:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Handing off to /implement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Item:     {title}
Status:   {Proposed|Not started|Needs discussion} → In progress
Worktree: .worktrees/{branch-suffix}  (branch feature/{branch-suffix}, from origin/{default-branch})

Run next:

  /implement {title}
  {if description present:}
  Context from TODO.md:

  {description}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If the worktree step was skipped (already exists or failed), drop the Worktree: line from the handoff block.

For Just show details:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Priority: {priority}
Category: {category}
Scope:    {scope}
Status:   {status}   (unchanged)

{description — if present}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Examples

Example 1: Pick interactively, validate plan first

/todo-work

Prints the full pending list inline (all N items, one per line with priority + title), then shows the AskUserQuestion with the top 3 as quick-select. User picks item #2 ("Add webhook support"). Chooses "Validate plan first". Skill updates status to In progress and prints the hand-off block with /review-plan Add webhook support (plus the description) as the suggested next command.

Example 2: Direct selection by number, implement directly

/todo-work 1

Jumps straight to item #1 ("Fix broken link in README"). User chooses "Implement directly". Status flips to In progress; the skill prints /implement Fix broken link in README as the next command to run.

Example 3: Show details only, no status change

/todo-work

User picks item #3, chooses "Just show details". No Edit to TODO.md, no hand-off — just prints the item details and stops.

Example 4: No pending items

/todo-work

Output:

No pending TODO items. Use /todo to add one, or /work-status to see active work sessions.

---

Error Handling

TODO.md missing

No TODO.md found in the project root. Use /todo to add your first item.

All items completed/in-progress (none pending)

No pending TODO items. Use /todo to add one, or /work-status to see active work sessions.

Argument out of range (e.g., /todo-work 99 when 5 items pending)

No item #99 — only 5 pending items. Re-run /todo-work to pick interactively.

Status line not unique when attempting mark-In-progress

Warn and continue with the handoff (see Step 7).

---

Notes

• Stateless — no .claude/work/ files; optionally reads worktree.root from .claude/configuration.yml (falls back to .worktrees/)
• Worktree isolation — creates .worktrees/{branch-suffix}/ on a new feature/{branch-suffix} branch off the remote default branch before handoff (skipped for Just show details); failures fall back to the current tree
• Read + targeted Edit — only touches TODO.md via one Status: line change
• Handoff is passive — prints the proposed next command; does not auto-launch a skill, because slash commands are user-invoked
• Priority ordering is stable — document order is the tiebreaker within a priority tier
• Missing metadata tolerated — items with partial fields are listed with an (missing metadata) marker, not dropped