run-todos

name	run-todos
description	Implement [ready]-tagged TODO items with commits. Use after /list-todos has clarified requirements and marked items as ready.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Task

Run TODOs Skill

Implement TODO items that have been marked as [ready] in TODOS.md.

Workflow

Copy this checklist and track progress:

Run TODOs Progress:
- [ ] Step 1: Directory guard check
- [ ] Step 2: Find [ready] items
- [ ] Step 3: User selection
- [ ] Step 4: Git workflow setup
- [ ] Step 5: Implementation loop (per item)
- [ ] Step 6: Update TODOS.md with completion
- [ ] Step 7: Generate summary report

Directory Guard

Before starting, confirm TODOS.md exists in the current working directory.

• If it does not exist, STOP and tell the user to create TODOS.md or cd into their project directory.

Context Check

Before starting: If context is below 40% remaining, run /compact first. This ensures the full command instructions remain in context throughout execution.

Find [ready] Items

1. Read TODOS.md
2. Find all items containing the [ready] tag
3. Exclude items that are already checked (- [x]) or have — DONE

If no [ready] items found:

NO READY ITEMS
==============
No items tagged [ready] found in TODOS.md.

To mark items as ready:
1. Run /list-todos
2. Go through Q&A to clarify requirements
3. Confirm readiness when asked

Or manually add [ready] tag to items you want to implement.

User Selection

Show the list of [ready] items and let user select:

READY ITEMS
===========
Found {N} items tagged [ready]:

1. {item title 1}
2. {item title 2}
3. {item title 3}

Which items would you like to implement?

Use AskUserQuestion:

Question: "Which items would you like to implement?"
Header: "Selection"
Options:
  - Label: "All items"
    Description: "Implement all {N} ready items in sequence (Recommended)"
  - Label: "Select specific items"
    Description: "Choose which items to implement"
  - Label: "Cancel"
    Description: "Exit without implementing"

If "Select specific items", use AskUserQuestion with multiSelect:

Question: "Select items to implement:"
Header: "Items"
Options:
  - Label: "1. {item 1 title}"
    Description: "{priority if present}"
  - Label: "2. {item 2 title}"
    Description: "{priority if present}"
  ... (up to 4 items per question, use multiple questions if more)
multiSelect: true

If "Cancel", exit the command.

Git Workflow

Check for Unpushed Commits

Before creating a branch:

CURRENT_BRANCH=$(git branch --show-current)
UNPUSHED=$(git rev-list --count @{upstream}..HEAD 2>/dev/null || echo "no-upstream")

If UNPUSHED > 0, use AskUserQuestion:

Question: "You have {UNPUSHED} unpushed commit(s) on `{CURRENT_BRANCH}`. Push before creating todo branch?"
Header: "Unpushed"
Options:
  - Label: "Yes, push first"
    Description: "Push current commits before starting (Recommended)"
  - Label: "No, continue anyway"
    Description: "Create branch from unpushed state"

Create Branch

# If working tree is dirty, stage and commit tracked changes first
git add -u && git diff --cached --quiet || git commit -m "wip: uncommitted changes before todo implementation"

# Create todo implementation branch
git checkout -b todo-impl-$(date +%Y-%m-%d)

Note: Use git add -u (tracked files only) to avoid accidentally staging secrets, build artifacts, or other untracked files. If untracked files need to be included, stage them by name.

Verify branch creation: Run git branch --show-current and confirm it matches todo-impl-{date}. If the checkout failed (e.g., branch already exists), append a suffix: todo-impl-{date}-2.

Implementation Loop

For each selected item:

1. Show Item Context

IMPLEMENTING: {item title}
===========================

{Full item text from TODOS.md}

{If clarifications exist:}
Clarifications:
- {Q1}: {A1}
- {Q2}: {A2}

2. Clarity Cross-Check

Before implementing, verify the item has sufficient detail. Check for both:

• Description length: Is the item a one-liner with no context beyond the title?
• Clarifications section: Does a **Clarifications (from Q&A ...)** block exist for this item in TODOS.md?

If the item has NEITHER a multi-sentence description NOR a clarifications section, flag it to the user:

⚠ THIN REQUIREMENTS
This item has no clarifications and a minimal description:
  "{item title}"

Implementing without clear requirements risks building the wrong thing.

Use AskUserQuestion:

Question: "'{item title}' has minimal requirements. How should we proceed?"
Header: "Thin reqs"
Options:
  - Label: "Clarify now"
    Description: "Ask questions before implementing (Recommended)"
  - Label: "Implement anyway"
    Description: "Proceed with best judgment based on available context"
  - Label: "Skip this item"
    Description: "Move to the next item"

• "Clarify now" → ask clarifying questions via AskUserQuestion, then proceed to Step 3
• "Implement anyway" → proceed to Step 3
• "Skip this item" → record as skipped, move to next item

If the item has a description or clarifications, proceed directly to Step 3.

3. Implement

Implement the TODO item following project conventions:

• Read relevant existing code to understand patterns
• Write tests first if acceptance criteria exist
• Implement the feature/fix
• Run tests to verify

4. Verify (if criteria exist)

If the item has acceptance criteria or testable requirements:

• Run the relevant test suite
• Use auto-verify skill for automatable checks
• Report verification results

5. Update TODOS.md

After successful implementation:

1. Check the box: - [ ] → - [x]
2. Add completion suffix: — DONE ({short_commit_hash})

Before:

- [ ] **[P1 / Medium]** Add user auth endpoint [ready]

After:

- [x] **[P1 / Medium]** Add user auth endpoint [ready] — DONE (a1b2c3d)

Use the Edit tool to make this update.

6. Commit

Stage the specific files changed during implementation, plus TODOS.md:

git add {files created or modified during implementation} TODOS.md
git commit -m "todo: {item title (shortened if needed)}"

Do NOT use git add -A or git add . — stage files by name to avoid committing secrets (.env), credentials, or unintended artifacts.

Verify commit succeeded: Check exit code of git commit. If it fails (e.g., pre-commit hook rejection), fix the issue and create a new commit — do NOT use --amend.

Get the commit hash for the TODOS.md update:

COMMIT_HASH=$(git rev-parse --short HEAD)

7. Handle Failure

If implementation fails (tests don't pass, errors occur), use AskUserQuestion:

Question: "Implementation of '{item title}' failed. What would you like to do?"
Header: "Failed"
Options:
  - Label: "Skip this item"
    Description: "Continue with the next item (Recommended if blocked)"
  - Label: "Retry"
    Description: "Try implementing again with a different approach"
  - Label: "Abort session"
    Description: "Stop and leave remaining items for later"

Summary Report

After all items are processed (or aborted):

RUN-TODOS COMPLETE
==================

Branch: todo-impl-{date}

Completed: {N} items
{For each completed item:}
  ✓ {item title} ({commit_hash})

{If any skipped:}
Skipped: {N} items
{For each skipped item:}
  ✗ {item title} — {reason}

{If aborted early:}
Remaining: {N} items not attempted

TODOS.md updated with completion status.

Next: Review changes, then run:
  git push origin todo-impl-{date}

Ready to open a PR? Create one using your preferred workflow.

Archive Completed Items

After the summary report, count the total number of completed items (- [x]) in TODOS.md (including items completed in previous sessions).

If 10 or more completed items exist, offer to archive:

Question: "TODOS.md has {N} completed items. Archive them to keep the file manageable?"
Header: "Archive"
Options:
  - Label: "Yes, archive (Recommended)"
    Description: "Move completed items to TODOS-ARCHIVE.md"
  - Label: "No, keep as-is"
    Description: "Leave completed items in TODOS.md"

If "Yes, archive":

1. Read (or create) TODOS-ARCHIVE.md in the project root
2. Move all - [x] items (and their clarifications blocks) from TODOS.md to TODOS-ARCHIVE.md under a dated heading:

   ## Archived {YYYY-MM-DD}
   
   - [x] **[P1 / Medium]** Item title [ready] — DONE (a1b2c3d)
   - [x] **[P2 / Low]** Another item [ready] — DONE (e4f5g6h)
   

3. Remove the archived items from TODOS.md (keep section headings intact)
4. Stage and commit:

   git add TODOS.md TODOS-ARCHIVE.md
   git commit -m "chore: archive completed TODO items"
   

If fewer than 10 completed items, skip this step silently.

Error Handling

Situation	Action
TODOS.md does not exist in working directory	STOP and tell user to create TODOS.md or cd into their project directory
No [ready]-tagged items found in TODOS.md	Report "No ready items" with instructions on how to mark items as ready via /list-todos
Git branch creation fails (branch name already exists)	Append an incrementing suffix (e.g., todo-impl-2026-02-22-2) and retry
git commit fails due to pre-commit hook rejection	Fix the flagged issue (e.g., lint errors), re-stage, and create a new commit; do NOT use --amend
Implementation fails (tests do not pass or runtime errors)	Present failure details via AskUserQuestion with options: skip item, retry with different approach, or abort session

Notes

• Do NOT push automatically. Leave pushing to the human after review.
• One commit per item. Each TODO gets its own commit for traceability.
• Preserve [ready] tag. The tag stays even after completion for history.
• Short commit hashes. Use 7-character short hash in DONE suffix.