timofreiberg/tdo

Operations

Parse $ARGUMENTS and dispatch:

| Argument pattern | Action | |---|---| | (empty) | Run tdo list. If there are any, ask the user what they want to do next. If none, say so. | | add <title> [--body TEXT] | Create a new todo (optionally with body) | | list | Run tdo list (open only — the default). Use tdo list --all only when the user asks about done todos. Note: listing triggers GC — done todos >7 days old are auto-deleted, stale assignments warn on stderr. | | count | Run tdo count (open only) or tdo count --all (include done). Prints the count as a plain number. | | show <query> | View a todo's full details | | done <query> | Mark a todo as done | | reopen <query> | Reopen a done todo | | edit <query> | Edit a todo's body | | delete <query> | Delete a todo | | assign <query> [name] | Assign a todo (optionally to a person) | | unassign <query> | Remove assignment from a todo | | refine <query> | Research and refine a todo through discussion | | Free-form task-shaped statement without a known verb | Treat as add <text> | | Free-form question ("do I have anything about X?") | Treat as list/show, not add |

Add

Run tdo add <title words> or tdo add <title words> --body "body text". It prints the assigned 4-char hex ID to stdout. Confirm creation to the user.

Use --body to set body text in the same command when the user provides details beyond the title. Newlines in the body are supported literally.

Titles are immutable after creation. To change a title, delete and recreate.

Show

Match the query to an ID (see "Matching queries to IDs"), then run tdo show <id>. It prints the todo's ID, title, status, timestamps, assignment, and body to stdout.

Matching queries to IDs

If the query is a hex ID or prefix (e.g. a3f9, a3), use it directly. Otherwise, run tdo list --all, match by title substring, and disambiguate with AskUserQuestion if needed.

Assign / Unassign

Match the query to an ID (see above), then run:

• tdo assign <id> (assign without a name)
• tdo assign <id> <name> (assign to a specific person)
• tdo unassign <id>

Confirm the result to the user.

Done / Reopen / Edit / Delete

Match the query to an ID (see above), then run the command:

• tdo done <id>
• tdo reopen <id>
• tdo edit <id> --body "new body content" (--body required for non-interactive use)
• tdo delete <id> --force (--force required for non-interactive use)

Confirm the result to the user.

Refine

1. Match the query to an ID (see "Matching queries to IDs")
2. Run tdo show <id> to read the todo's full content
3. Research before asking. Based on the TODO content, proactively gather context:
   • If files, functions, or modules are mentioned, read them
   • If related TODOs exist, read those too
   • If the TODO references a bug or behavior, look at the relevant code
   • Search the codebase for anything directly related to the TODO's subject Do NOT ask the user questions you could answer by reading code or files.
4. Present the current TODO content and a brief summary of what you found
5. Think critically about what's missing or unclear:
   • Is the problem or goal clearly defined?
   • Are there acceptance criteria or a definition of done?
   • Are there edge cases, constraints, or dependencies worth noting?
   • Is there relevant context (affected files, related TODOs, prior decisions)?
   • Could the TODO be split into smaller, more actionable items?
6. Use AskUserQuestion to ask clarifying questions — only things that require human judgment. Include your own suggestions where possible.
7. After the discussion, update the TODO body with refined content using tdo edit <id> --body "..."
8. Show the user the final version