Task Management — The System That Thinks For You

Todoist is the task layer. The agent is the gardener.

Philosophy

Three systems, one practice:

Getting Things Done (David Allen): Your brain is for having ideas, not holding them. Capture everything immediately. Process to next physical action. If it takes < 2 min, do it now. Weekly review is sacred.

Shape Up (Ryan Singer, Basecamp): Work expands to fill the time available. Set appetite (how much time is this worth?), not estimates. Projects are bets with fixed timelines, not open-ended backlogs. If it's not worth betting on, kill it.

Tiny Habits (BJ Fogg): Behavior change = anchor moment + tiny behavior + celebration. "After I [existing routine], I will [tiny version of new habit]." Make it stupidly small. Celebrate immediately. Let it grow naturally.

What This Means In Practice

Every task is a next physical action. Not "research X" but "spend 20 min reading the X docs." Not "fix the bug" but "reproduce the bug in a test."
Inbox is a capture buffer, not a todo list. Process it to zero. Each item gets: do it (< 2 min), schedule it, delegate it, someday it, or delete it.
Projects have appetite. "2 weeks, small batch" or "6 weeks, big batch." If a project has been open for 3x its appetite with no progress, it's a zombie. Kill it or re-scope.
Habits are anchored, not scheduled. "After morning coffee → shoulder warm-up" not "Do exercises at 7am." The anchor is the trigger.
Less is more. A clean list with 5 clear next actions beats 50 vague intentions. Ruthlessly prune. If you haven't touched it in 2 weeks and it's not scheduled, it doesn't matter.

Todoist Adapter

Credentials

# API token from https://app.todoist.com/app/settings/integrations/developer
# Stored in agent-secrets
export TODOIST_API_TOKEN=$(secrets lease todoist_api_token --raw)

Read

todoist-cli today                    # What's due today
todoist-cli inbox                    # Needs triage
todoist-cli list                     # All active tasks
todoist-cli list --filter "p1"       # Todoist filter query (priority 1)
todoist-cli list --project ID        # Tasks in a project
todoist-cli list --label review      # Tasks with a label
todoist-cli projects                 # All projects
todoist-cli sections --project ID    # Sections in a project
todoist-cli labels                   # All labels
todoist-cli show ID                  # Task detail + comments
todoist-cli review                   # Daily standup: today, inbox, overdue, project breakdown

Write

# Create a task
todoist-cli add "Title" --due today --description "Details" --project ID

# With labels, priority, deadline
todoist-cli add "Ship feature" --due "next monday" --priority 3 --labels agent,urgent --deadline 2026-03-01

# Complete
todoist-cli complete ID

# Update
todoist-cli update ID --content "New title" --due tomorrow --description "Updated notes"

# Move between projects
todoist-cli move ID --project ID

# Delete permanently
todoist-cli delete ID

# Reopen a completed task
todoist-cli reopen ID

# Create a project
todoist-cli add-project "Project Name" --color blue

# Create a section
todoist-cli add-section "Section Name" --project ID

Priority Convention

Use Todoist's native p1–p4. The API inverts these: --priority 4 = p1 (red) in the UI.

UI	API	Meaning	Agent rule
p1 🔴	`--priority 4`	Urgent / today	Blocking something. Do it now or escalate.
p2 🟠	`--priority 3`	High / this week	Next up. Agent picks from these first.
p3 🔵	`--priority 2`	Medium / this cycle	Scheduled work. Gets done when p1-p2 clear.
p4 ⚪	`--priority 1`	Backlog	Someday/maybe. Reviewed weekly, killed if stale.

SOP: When creating agent tasks from ADRs or session work, always set priority. Default to p3. Promote to p2 if it unblocks other work. p1 is rare — something is broken or blocking Joel.

Schedule Mapping

Todoist	GTD Context	CLI Flag
Inbox (no project)	Captured, not processed	(default)
`--due today`	Committed — doing it today	`--due today`
`--due "next week"`	Scheduled	`--due "next monday"`
No due date	Next action, no date pressure	(omit --due)
Label: `someday`	Maybe/later — reviewed weekly	`--labels someday`
`--due "every day"`	Recurring habit	`--due "every day"`

Structure

Concept	Todoist	Rule
Project	Project	Finite goal with appetite. Has a "done" state. Archive when complete.
Section	Section	Group within a project. Optional — keep flat until complexity demands it.
Task	Task	Next physical action. Concrete, verb-first.
Habit	Recurring task	`--due "every day"` or `"every friday at 5pm"`. Anchored to routine.
Context	Label	Lightweight tags: `review`, `agent`, `someday`, `waiting`.

Todoist Filters (Pro)

Todoist's filter syntax is powerful. Use via todoist-cli list --filter:

todoist-cli list --filter "today | overdue"     # Due today or overdue
todoist-cli list --filter "p1 & !#Inbox"        # Priority 1, not in inbox
todoist-cli list --filter "no date"             # Floating tasks
todoist-cli list --filter "@review"             # Label: review
todoist-cli list --filter "assigned to: me"     # My tasks
todoist-cli list --filter "created before: -14d"  # Stale tasks

Agent Behaviors

Capture Immediately

When Joel says anything implying a task — "I need to...", "remind me to...", "we should...", "don't forget..." — capture it:

todoist-cli add "The thing Joel said"

Then confirm: "Captured → Inbox: 'The thing Joel said'"

Don't ask permission to capture. Ask permission before scheduling or assigning to a project. Capturing is free.

Process Inbox (GTD)

When asked to review or when inbox has items:

For each item, decide ONE of:

Do it — takes < 2 min? Just do it now. Complete the task.
Schedule it — todoist-cli update ID --due today or --due "next monday"
Move it — todoist-cli move ID --project ID
Someday/maybe — todoist-cli update ID --labels someday
Delete it — not worth doing. todoist-cli delete ID

Present as a batch decision: "Inbox has 4 items. Here's my triage..."

Create Tasks From Work

When actionable items emerge from other activities (transcribed photos, calendar events, project planning):

Extract concrete next actions (verb-first, specific)
Assign to the right project
Add descriptions with context (ADR refs, links, acceptance criteria)
Report what was created

Weekly Review

When Joel asks for weekly review, or triggered by the recurring Friday task:

todoist-cli review

Then:

Process inbox to zero
Flag zombie projects (no activity in 2+ weeks)
Flag overdue tasks — reschedule or kill
Flag floating tasks (no due date) — still relevant?
Ask: "What's the one thing that would make next week a win?"

Keep It Clean

Max 7 items due today. More than that = overcommitted. Push overflow.
Inbox should be zero after processing. Not "low" — zero.
Complete or kill. No task should linger more than 2 weeks without progress unless labeled someday.
Project names are outcomes. "Ship task integration" not "Task stuff."
Descriptions matter. Every task gets enough context that you can pick it up cold.

"Could the agent just do this?"

Before creating a task, ask: could joelclaw do this right now? If yes, do it and create a completed task as a record. Tasks are for humans; agents execute.

Agent does it: code changes, research, file operations, API calls, calendar updates
Agent drafts, Joel reviews: writing in Joel's voice, design decisions
Joel only: physical actions (shopping, exercise), phone calls, editorial taste

Fallback: Vault Checklists

If Todoist auth fails, use Vault markdown checklists:

- [ ] Task description
- [x] Completed task

Google Tasks via gog is available as secondary adapter.

SOP: ADR → Tasks

When an ADR is accepted or proposed, its remaining work should exist as Todoist tasks. This is how the system tracks what's actually next.

After an ADR sweep or session that produces action items:

Check the ADR's verification checklist for unchecked items
Each unchecked item → one Todoist task (verb-first, concrete)
Set priority based on leverage: does it unblock other ADRs? p2. Standalone? p3. Research? p3.
Label agent (agent can do it) or joel (needs human). Add joelclaw if it's system work.
Description includes ADR reference and enough context to pick up cold
Cross-reference: if a task completes the last item in an ADR, update the ADR to implemented

The loop: ADR sweep → tasks created → agent/Joel works tasks → tasks completed → ADR status updated → next sweep finds it clean.

Don't create tasks for:

Things the agent can do right now (< 5 min) — just do them
Deferred ADRs — they'll get tasked when un-deferred
Vague research — time-box it first ("Spend 30 min on X" not "Research X")

Anti-Patterns

Don't create vague tasks — "Look into X" is not a next action. "Spend 15 min reading X docs" is.
Don't let inbox accumulate — if it has > 10 items, triage before adding more
Don't over-organize — labels and sections add friction. Keep it flat until complexity demands structure.
Don't duplicate — check existing tasks before creating. Use todoist-cli list --filter to search.
Don't put agent context in task titles — keep titles human-readable. Put ADR refs and technical details in the description.

Credits

David Allen — Getting Things Done
Ryan Singer — Shape Up (Basecamp)
BJ Fogg — Tiny Habits
Todoist / Doist — official API and SDK

task-management