Filesystem-based task management with git integration - track tasks through open/wip/done lifecycle
- version
- 0.1.0
- GitHub stars
- 8
Install
/plugin install todo@digital-dividend-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add thlandgraf/cc-marketplace.
Contents
Discovered from sourceSkills 1
Todo Format Knowledge
Directory Structure
todo/
├── open/ # New tasks, not yet started
├── wip/ # Work in progress
└── done/ # Completed tasks
File Naming
Pattern: <ID>-<slug>.md
- ID: 3-digit zero-padded number (001, 042, 123)
- Slug: Kebab-case title, max 50 chars
Examples:
001-fix-login-bug.md042-add-dark-mode-support.md123-refactor-api-endpoints.md
Task File Structure
# <ID>: <Title>
**Status:** open | **Priority:** medium | **Assignee:** unassigned
**Created:** 2026-01-21 | **Branch:** <id>-<slug>
## Description
Brief description of the task.
## Tasks
- [ ] Task 1
- [ ] Task 2
- [x] Completed task
## Dependencies
- Depends on: 039, 041
- Blocks: 044
## PRD
<!-- Inferred from implementation decisions -->
## Implementation Log
<!-- Timestamped entries of work done -->
Status Values
| Status | Directory | Meaning |
|---|---|---|
open | todo/open/ | Not started |
wip | todo/wip/ | Work in progress |
done | todo/done/ | Completed |
Status in file header must match the directory location.
Header Fields
| Field | Format | Example |
|---|---|---|
| Status | open/wip/done | wip |
| Priority | high/medium/low | high |
| Assignee | name or "unassigned" | Thomas Landgraf |
| Created | YYYY-MM-DD | 2026-01-21 |
| Started | YYYY-MM-DD HH:MM | 2026-01-21 14:30 |
| Completed | YYYY-MM-DD HH:MM | 2026-01-21 18:45 |
| Branch | id-slug | 042-fix-login-bug |
Task Checkboxes
- [ ] Not started
- [x] Completed
Dependencies
Reference other tasks by ID only (no paths):
- Depends on: 039, 041
- Blocks: 044, 045
- Depends on: This task needs those tasks completed first
- Blocks: Those tasks are waiting on this task
Implementation Log Format
### 2026-01-21 14:30
**Files modified:**
- `src/auth/login.js` - Fixed token validation
- `tests/auth.test.js` - Added 3 test cases
**Notes:** Optional additional context
**Result:** In progress / Success / Failed
### 2026-01-21 18:45
**Completed** by Thomas Landgraf
**Summary:** Brief summary of accomplishment
PRD Section
The PRD (Product Requirement Definition) is inferred from implementation:
- Document decisions made during development
- Capture requirements that emerged from building
- Keep concise - bullet points preferred
Git Integration
- Branch naming:
<id>-<slug>(e.g.,042-fix-login-bug) - Manual commits: Plugin never auto-commits
- Clean state: Starting a task requires clean git working directory
Commands
| Command | Purpose |
|---|---|
/todo:add <desc> | Create new task in open/ |
/todo:start [id] | Move to wip/, create branch |
/todo:update | Log progress, update tasks |
/todo:done [id] | Move to done/, finalize |
Commands 4
Todo Add Command
Create a new task in todo/open/ with auto-incremented ID.
Workflow
1. Ensure Todo Directory Exists
Check for todo/ directory in project root. If not found, create structure:
todo/
├── open/
├── wip/
└── done/
2. Determine Next ID
Find the highest existing task ID across all directories:
find todo -name "[0-9]*.md" 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail -1
Next ID = highest + 1, zero-padded to 3 digits (001, 002, etc.)
3. Parse Description
From the ARGUMENT, extract:
- Title: First sentence or line (used for filename slug)
- Description: Full argument text
Generate slug from title: lowercase, spaces to hyphens, remove special chars.
Example: "Fix login bug in auth module" → fix-login-bug-in-auth-module
4. Search for Related Tasks (BEFORE asking questions)
Only suggest dependencies if there's actual similarity.
-
Extract keywords from new task title (ignore stop words like "the", "a", "fix", "add", "update")
-
Search existing open/wip tasks for keyword matches:
# Get keywords from title keywords=$(echo "<title>" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' ' ') # Search each keyword in existing tasks for kw in $keywords; do grep -ril "$kw" todo/open/ todo/wip/ 2>/dev/null done | sort | uniq -c | sort -rn -
Only consider tasks as related if they match 2+ keywords OR share the same component/module
-
Build related_tasks list with:
- Task ID
- Title (from first heading)
- Match reason (which keywords matched)
5. Ask Clarifying Questions
Use AskUserQuestion with multiSelect: true for dependencies:
questions:
- question: "What priority should this task have?"
header: "Priority"
multiSelect: false
options:
- label: "High"
description: "Urgent, blocks other work"
- label: "Medium (Recommended)"
description: "Normal priority"
- label: "Low"
description: "Nice to have, not urgent"
# ONLY show this question if related_tasks is NOT empty
- question: "Any dependencies on other tasks?"
header: "Dependencies"
multiSelect: true # Allow selecting multiple dependencies
options:
- label: "None"
description: "No dependencies, can start immediately"
# Add ONLY tasks from related_tasks list:
- label: "Task <ID>"
description: "<title> (matched: <keywords>)"
# ... more related tasks
IMPORTANT:
- Do NOT show dependency question if no related tasks found
- Do NOT suggest ALL existing tasks - only those with keyword/topic similarity
- Always include "None" as first option
- Show max 4 related tasks (most relevant first)
6. Search for Related Code Context
Use Grep to find related code (for populating the Tasks section):
- Search codebase for keywords from the title
- Identify files/modules that might need changes
7. Create Task File
Create file at todo/open/<ID>-<slug>.md:
# <ID>: <Title>
**Status:** open | **Priority:** <priority> | **Assignee:** unassigned
**Created:** <date> | **Branch:** <id>-<slug>
## Description
<full description from argument>
## Tasks
- [ ] <inferred task 1>
- [ ] <inferred task 2>
## Dependencies
- Depends on: <ids or "none">
- Blocks: <ids or "none">
## PRD
<!-- Inferred from implementation decisions -->
## Implementation Log
<!-- Auto-populated by /todo:update -->
8. Report Result
Output confirmation:
Created task: todo/open/<ID>-<slug>.md
# <ID>: <Title>
Priority: <priority>
Dependencies: <deps>
Use /todo:start <ID> to begin working.
Notes
- Never auto-commit: User controls git workflow
- ID format: Always 3 digits, zero-padded (001, 042, 123)
- Slug: Max 50 chars, kebab-case
- Get current date with:
date +%Y-%m-%d
Todo Done Command
Mark a task as complete. Move from todo/wip/ to todo/done/ and finalize the implementation log.
Workflow
1. Select Task
If ARGUMENT provided:
- Find task file matching the ID in
todo/wip/
If NO ARGUMENT:
- Try to infer from current git branch
- If not on task branch, list tasks in
todo/wip/and let user pick
2. Validate Completion
Read the task file and check:
- Are all tasks in the Tasks section complete?
[x]
If incomplete tasks remain:
Warning: Some tasks are not marked complete:
- [ ] Add tests
- [ ] Update documentation
Complete anyway?
Options:
- "Yes, close it" - proceed
- "No, keep working" - cancel
3. Final Log Entry
Add final entry to Implementation Log:
### <date> <time>
**Completed** by <user>
**Summary:** <brief summary of what was accomplished>
4. Update Task Header
**Status:** done | **Priority:** <unchanged> | **Assignee:** <user>
**Created:** <created> | **Started:** <started> | **Completed:** <now>
5. Move Task File
mv todo/wip/<id>-<slug>.md todo/done/
6. Report Result
Completed: <ID> - <Title>
Duration: <started> → <completed>
File: todo/done/<id>-<slug>.md
Implementation log preserved for future reference.
Optional: Branch Cleanup Hint
After marking done, suggest:
Task complete. You may want to:
1. Merge branch <id>-<slug> to main
2. Delete the branch: git branch -d <id>-<slug>
(These are not done automatically)
Error Handling
| Condition | Response |
|---|---|
| No tasks in wip/ | "No tasks in progress. Use /todo:start first." |
| Task not found | "Task not found in todo/wip/" |
| Task in open/ | "Task hasn't been started yet. Use /todo:start first." |
| Task already done | "Task is already complete" |
Notes
- Never auto-commit: Moving the file and updating it does not trigger git commit
- Never auto-merge: User handles git merge workflow
- Get current timestamp with:
date +"%Y-%m-%d %H:%M" - The completed task file serves as documentation for what was done
Todo Start Command
Move a task from todo/open/ to todo/wip/, create a git branch, and assign to current user.
Workflow
1. Check Git State
CRITICAL: Require clean git working directory before creating branch.
git status --porcelain
If output is non-empty, show error:
Error: Uncommitted changes detected. Please commit or stash changes before starting a new task.
Modified files:
<list of files>
2. Select Task
If ARGUMENT provided:
- Find task file matching the ID in
todo/open/ - Pattern:
todo/open/<ID>-*.md
If NO ARGUMENT:
- List all tasks in
todo/open/ - Use AskUserQuestion to let user pick one:
Which task do you want to start?
1. 001-fix-login-bug - Fix login bug in auth module
2. 002-add-dark-mode - Add dark mode support
3. 003-refactor-api - Refactor API endpoints
3. Validate Task
- Confirm task exists in
todo/open/ - If task is in
wip/ordone/, show appropriate error
4. Get User Info
git config user.name || whoami
5. Create Git Branch
Extract slug from filename and create branch:
git checkout -b <id>-<slug>
Example: Task 042-fix-login-bug.md → branch 042-fix-login-bug
6. Move Task File
Move from todo/open/ to todo/wip/:
mv todo/open/<id>-<slug>.md todo/wip/
7. Update Task File
Edit the task file to update:
**Status:** wip | **Priority:** <unchanged> | **Assignee:** <user>
**Created:** <unchanged> | **Started:** <now> | **Branch:** <id>-<slug>
Add to Implementation Log:
## Implementation Log
### <date> <time>
**Started** by <user>
8. Report Result
Started task: <ID> - <Title>
Branch: <id>-<slug>
Assignee: <user>
File: todo/wip/<id>-<slug>.md
Ready to work. Use /todo:update to log progress.
Error Handling
| Condition | Response |
|---|---|
| No tasks in open/ | "No open tasks. Use /todo:add to create one." |
| Task not found | "Task not found in todo/open/" |
| Task already in wip | "Task is already in progress" |
| Uncommitted changes | "Please commit or stash changes first" |
| Branch exists | "Branch already exists. Delete it or use different task." |
Notes
- Never auto-commit: Moving the file and updating it does not trigger git commit
- Get current timestamp with:
date +"%Y-%m-%d %H:%M"
Todo Update Command
Update the current task with implementation progress. Auto-detects work done via git diff and Claude session context.
Workflow
1. Identify Current Task
Primary: Infer from current git branch name
git branch --show-current
If branch matches pattern <id>-<slug>, find corresponding task in todo/wip/.
Fallback: If not on a task branch or no matching task:
- Check
todo/wip/for tasks - If exactly one task, use it
- If multiple, ask user to pick
- If none, offer to create new task (see step 1b)
1b. No Active Task - Offer to Create
If no task is active but work was detected:
No active task found, but you have uncommitted changes.
Would you like to:
1. Create a new task from this work
2. Cancel
If user chooses to create, invoke /todo:add workflow with inferred description.
2. Detect Work Done
From Git:
git diff --name-only HEAD
git diff --name-only --cached
Combine to get list of modified files.
From Session Context: Consider files that were edited during this Claude session (you have awareness of what files you modified).
3. Summarize Changes
For each modified file, briefly describe the change:
- New file: "Created - "
- Modified: "Updated - "
- Deleted: "Removed "
4. Ask for Additional Context
Use AskUserQuestion:
Detected changes in:
- src/auth/login.js
- tests/auth.test.js
Anything to add to the log? (optional)
Options:
- "Looks good" - proceed with auto-detected summary
- "Add details" - let user type additional notes
- "Skip this update" - cancel
5. Update Implementation Log
Append to the task file's Implementation Log section:
### <date> <time>
**Files modified:**
- `src/auth/login.js` - Fixed token validation
- `tests/auth.test.js` - Added 3 test cases
**Notes:** <user's additional context if provided>
**Result:** In progress
6. Update Task Checkboxes
Review the Tasks section and ask:
Current tasks:
- [ ] Investigate root cause
- [ ] Implement fix
- [ ] Add tests
Any tasks completed? (select all that apply)
Update checkboxes:
[ ]→[x]for completed tasks- Keep
[ ]for incomplete
7. Update PRD Section
If implementation decisions were made that clarify requirements:
- Ask user if PRD should be updated
- Add inferred requirements based on what was built
8. Report Result
Updated: <ID> - <Title>
Changes logged:
- <file1>
- <file2>
Tasks: 2/4 complete
Notes
- Never auto-commit: Updates to task file are not committed
- Get current timestamp with:
date +"%Y-%m-%d %H:%M" - Log format should be concise but informative for later catch-up
Hooks 2
Sponsors
Details
- Marketplace
- thlandgraf/cc-marketplace
- Source
- plugins/todo
- Author
- Thomas Landgraf
- Category
- Community
- License
- MIT
- Keywords
- todo, tasks, project-management, git, workflow
