task-management

name	task-management
displayName	Task Management
description	Manage Joel's task system in Todoist. Triggers on: 'add a task', 'create a todo', 'what's on my list', 'today's tasks', 'what do I need to do', 'remind me to', 'inbox', 'complete', 'mark done', 'weekly review', 'groom tasks', 'what's next', or when actionable items emerge from other work. Also triggers when Joel mentions something he needs to do in passing — capture it.
version	1.0.0
author	Joel Hooks
tags	["joelclaw","tasks","todoist","productivity","planning"]

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.

Personal action boundary

Todoist is Joel's actual GTD-style personal action list. Brain PARA holds project support material, areas, resources, receipts, and archives. Do not reproduce the PARA tree in Todoist.

Rules:

• Default action home is Joel's Tasks.
• Questions for Joel is for actual decisions only, not a dumping ground.
• The old Agent Work project is archived. Machine bookkeeping, infra follow-ups, legacy memory-review chores, and system chores do not belong in Todoist.
• System-bus Todoist mutations are disabled by default. TODOIST_AUTOMATION_WRITES_ENABLED=true is an emergency compatibility override, not normal operation.
• Agents may mutate Todoist through explicit todoist-cli commands when Joel asks to capture, schedule, move, complete, or delete a personal task.
• If the agent can do the work now, do it instead of tasking it.

Good human-facing tasks:

• "Ask Kristina for post-op follow-up appointment date"
• "Update Grzegorz on instructor chat progress"
• "Choose between A and B for launch pricing"

Bad human-facing tasks:

• "Investigate gateway retry chatter"
• "Review legacy memory proposal p-20260306-030" (historical retired workflow)
• "Build log query tool for LiveKit integration" when the agent can already do the work

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:

1. Do it — takes < 2 min? Just do it now. Complete the task.
2. Schedule it — todoist-cli update ID --due today or --due "next monday"
3. Move it — todoist-cli move ID --project ID
4. Someday/maybe — todoist-cli update ID --labels someday
5. 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):

1. Extract concrete next actions (verb-first, specific)
2. Decide the audience first: human, decision, or machine
3. Only human/decision work goes into Joel-facing Todoist views
4. Assign to the right project
5. Add descriptions with context (ADR refs, links, acceptance criteria)
6. Report what was created

Weekly Review

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

todoist-cli review

Then:

1. Process inbox to zero
2. Flag zombie projects (no activity in 2+ weeks)
3. Flag overdue tasks — reschedule or kill
4. Flag floating tasks (no due date) — still relevant?
5. 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. Do not create a machine chore in Joel's task list just to feel organized. 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
• Machine bookkeeping stays off Joel-facing surfaces: memory review, infra babysitting, retry cleanup, agent backlog

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:

1. Check the ADR's verification checklist for unchecked items
2. Each unchecked item → one Todoist task (verb-first, concrete)
3. Set priority based on leverage: does it unblock other ADRs? p2. Standalone? p3. Research? p3.
4. Label agent (agent can do it) or joel (needs human). Add joelclaw if it's system work.
5. Description includes ADR reference and enough context to pick up cold
6. 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")
• Machine-only bookkeeping anywhere in Todoist — keep it in Brain receipts, issues, or runtime state instead

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.
• Don't contaminate Joel-facing views with machine sludge — if Joel does not need to see it, it does not belong there.

Credits

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