oaustegard/tracking-todos

Tracking Todos

Maintain a structured, persistent task list while working through multi-step requests. Track progress explicitly, mark completion honestly, and make the plan visible to Oskar.

When to Use

Use proactively when:

• Request requires 3+ distinct steps or actions
• User provides multiple tasks (numbered, comma-separated, or a list)
• Work spans multiple tool calls, file edits, or research phases
• Non-trivial planning would otherwise happen implicitly in your head
• User explicitly asks for a todo list

Skip when:

• Single, straightforward task
• Purely conversational or informational exchange
• Task completes in <3 trivial steps
• Quick fact lookup or recall

When in doubt, use it. Being explicit about multi-step plans makes failure modes visible.

Schema

Each todo has exactly three string fields:

• content — imperative form ("Run tests", "Fix auth bug")
• status — one of: pending, in_progress, completed
• activeForm — present continuous ("Running tests", "Fixing auth bug")

Both content and activeForm are required for every todo. The activeForm is what gets shown while a task is executing.

API

from todos import get_todos, write_todos, abandon, render

# Read current list
todos = get_todos()

# Replace entire list (Claude Code semantics — one call, whole list)
write_todos([
    {"content": "Fetch issue body", "status": "in_progress", "activeForm": "Fetching issue body"},
    {"content": "Draft fix plan", "status": "pending", "activeForm": "Drafting fix plan"},
    {"content": "Implement and test", "status": "pending", "activeForm": "Implementing and testing"},
])

# Display to Oskar
print(render())

# Discard remaining todos when starting fresh unrelated work
abandon()

write_todos() validates schema and that at most one item is in_progress. When every item is completed, it auto-clears the list (matches Claude Code behavior — done-state is empty-state).

Behavioral Rules

One in_progress at a time, strictly. Before starting work on a task, set it to in_progress. Never have two in_progress items simultaneously. The validator enforces this.

Mark complete IMMEDIATELY. Update to completed the moment the work is actually done. Don't batch completions at the end — that defeats the tracking purpose and erases information about when things were finished.

Only mark complete if FULLY done. If tests fail, if the implementation is partial, if you hit an unresolved error — keep the task in_progress and add a new task describing the blocker. Lying about completion status is the failure mode this tool exists to prevent.

Remove irrelevant tasks. If a task becomes obsolete (scope change, wrong approach), remove it entirely from the list rather than marking it done. The list should reflect actual remaining work.

Break complex tasks down. Vague items like "implement the feature" defeat the point. Prefer specific actions: "Add validator to route handler", "Write 3 test cases for edge inputs", "Run existing test suite".

Storage Model

Todos live in Muninn's config store under key active-todos (category=ops). This means:

• Survives container death within the same conversation
• Persists across conversations until explicitly cleared or auto-cleared when all done
• Cross-conversation persistence is a feature: unfinished work shows up next session as a nudge

If you start a conversation and find stale todos that don't apply, call abandon() to clear them.

Known Limitations

Single writer assumed. The storage uses read-modify-write without locking. If a scheduled CCotw task and a live conversation both call write_todos() concurrently, the second write wins. Muninn runs single-threaded within a conversation, and scheduled tasks (perch, zeitgeist) don't use this skill, so the assumption holds in practice. Don't use this skill from concurrent agents without adding a lock.

Global scope is intentional, not per-conversation. Unfinished work leaks into the next conversation by design — it's a nudge that something was left open. If stale todos from prior work become noise, call abandon() to clear.

Replace-whole-list API vs delta updates. Matches Claude Code's TodoWrite exactly. The LLM failure mode (forgetting items when rewriting the full list) is mitigated by the prompt, not by the API shape. If omissions become a pattern, re-render the current list before composing the new one.

Display Pattern

When the plan is substantive, show it to Oskar once after creating it, then rely on inline mentions rather than re-rendering the full list on every update. Noise defeats the signal.

▶ Fetching issue body
☐ Drafting fix plan
☐ Implementing and testing

Examples

Good use case — multi-file refactor:

write_todos([
    {"content": "Find all call sites of getCwd", "status": "in_progress", "activeForm": "Finding all call sites of getCwd"},
    {"content": "Rename occurrences in src/utils/", "status": "pending", "activeForm": "Renaming occurrences in src/utils/"},
    {"content": "Rename occurrences in src/agents/", "status": "pending", "activeForm": "Renaming occurrences in src/agents/"},
    {"content": "Run test suite", "status": "pending", "activeForm": "Running test suite"},
])

Bad use case — should not use:

User: "What's the current time in Tokyo?"
→ Single fact lookup. Skip todos.

Mid-work update (after finishing step 1, hitting a blocker in step 2):

write_todos([
    {"content": "Find all call sites of getCwd", "status": "completed", "activeForm": "Finding all call sites of getCwd"},
    {"content": "Rename occurrences in src/utils/", "status": "completed", "activeForm": "Renaming occurrences in src/utils/"},
    {"content": "Resolve type error in AgentContext after rename", "status": "in_progress", "activeForm": "Resolving type error in AgentContext after rename"},
    {"content": "Rename occurrences in src/agents/", "status": "pending", "activeForm": "Renaming occurrences in src/agents/"},
    {"content": "Run test suite", "status": "pending", "activeForm": "Running test suite"},
])

Note: the blocker became a new task rather than marking step 3 complete.