git / todo

updated October 21, 2026

I do not use an external project management tool such as Linear, Jira, or Trello. An external tracker separates the plan from the source code. Tasks in external tools become stale. The tracker requires separate permissions and browser tabs. Instead, I track work in a todo/ directory in version control.

Directory structure

The todo/ directory replaces the web board. 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.

Here is an example 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

A todo/README.md file summarizes the queue order and the test requirements. A plan in an owner queue has an assigned person. That person also resolves external blockers. Unassigned work belongs in planned/ when the team commits to it. Speculative ideas wait in triage/.

There is no in-progress/ directory. Active work lives on a branch in a git worktree. The worktree list and open change requests show active work.

Ordering and dependencies

The filesystem represents the dependency graph. A three-digit prefix sets an execution order. A plan named 001- lands before 002-. Unnumbered sibling files represent parallel work. A contributor can start any unnumbered task at any time. When priorities change, I renumber files with git mv.

A filename uses the imperative mood and names the specific component. For example, I name a file 001-migrate-auth-to-go.md rather than 001-auth.md.

Inside a plan

Each file is a plain Markdown document. A plan describes the technical design and the test steps. I do not commit screenshots to git. I use ASCII diagrams and tables in code blocks to keep the repository small. When a large project ships in phases, I trim finished sections from the plan.

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. Git history preserves the record. A commit message records the deletion:

todo: delete completed auth migration plan

The repository stays clean because finished plans leave the tree. An agent reads the local files directly. The agent does not require an API key or an external integration to read the backlog. The agent inspects todo/planned/ and reads the code. It implements the change in a worktree.

← All articles