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-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add thlandgraf/cc-marketplace.

Contents

Discovered from source

Skills 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.md
  • 042-add-dark-mode-support.md
  • 123-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

StatusDirectoryMeaning
opentodo/open/Not started
wiptodo/wip/Work in progress
donetodo/done/Completed

Status in file header must match the directory location.

Header Fields

FieldFormatExample
Statusopen/wip/donewip
Priorityhigh/medium/lowhigh
Assigneename or "unassigned"Thomas Landgraf
CreatedYYYY-MM-DD2026-01-21
StartedYYYY-MM-DD HH:MM2026-01-21 14:30
CompletedYYYY-MM-DD HH:MM2026-01-21 18:45
Branchid-slug042-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

CommandPurpose
/todo:add <desc>Create new task in open/
/todo:start [id]Move to wip/, create branch
/todo:updateLog 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.

  1. Extract keywords from new task title (ignore stop words like "the", "a", "fix", "add", "update")

  2. 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
    
  3. Only consider tasks as related if they match 2+ keywords OR share the same component/module

  4. 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

ConditionResponse
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/ or done/, 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

ConditionResponse
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

Sponsors

Details

Marketplace
thlandgraf/cc-marketplace
Source
plugins/todo
Author
Thomas Landgraf
Category
Community
License
MIT
Keywords
todo, tasks, project-management, git, workflow

More from thlandgraf/cc-marketplace

All 4