git / todo

updated October 21, 2026

I track tasks in a todo/ directory in version control rather than an external tracker. Storing plans in git keeps them next to the code and avoids separate access management.

Directory structure

Subdirectories represent task states:

• <owner>/: a queue for one person, ordered by that person.
• planned/: scheduled tasks that the project commits to do.
• triage/: an unowned backlog of ideas to evaluate.

Layout:

todo/
├── README.md
├── dan/
│   ├── 001-replace-sqlite-with-postgres.md
│   └── fix-session-leak.md
├── planned/
│   ├── 001-observability.md
│   └── 002-checks.md
└── triage/
    └── backup-replication.md

todo/README.md defines queue order and test requirements. Unassigned work belongs in planned/, owner queues hold assigned work, and speculative ideas wait in triage/. Active work lives on a branch in a git worktree.

Ordering and dependencies

The filesystem represents the dependency graph. A three-digit prefix sets execution order: 001- lands before 002-. Unnumbered sibling files represent parallel work. When priorities change, I renumber files with git mv.

A filename uses the imperative mood and names the component, such as 001-migrate-auth-to-go.md.

Inside a plan

Each file is a Markdown document with technical design and test steps. When a project ships in phases, I trim finished sections.

Review and lifecycle

I commit a new plan as an ordinary change. Teammates and agents review the plan before implementation starts.

When a task finishes, I delete the plan file:

todo: delete completed auth migration plan

Git history preserves the record. Finished plans leave the tree, so the repository stays clean. An agent reads todo/planned/ directly without an API key and implements the change in a worktree.

← All articles