todo

Task Manager

Manage tasks stored in a single markdown file at $CYBERDECK_TASKS.

Guard

Before any operation, verify $CYBERDECK_TASKS is set:

1. Check the environment variable exists. If not, tell the user: "Set $CYBERDECK_TASKS to your tasks file path: export CYBERDECK_TASKS=$HOME/tasks.md"
2. If the file doesn't exist and the operation is add, create it (see File Creation below).
3. If the file doesn't exist and the operation is anything else, tell the user: "No tasks file found at $CYBERDECK_TASKS. Use /todo:todo add to create your first task."

Parse Arguments

Determine the operation from the first word of $ARGUMENTS:

• add → Add operation
• complete or done → Complete operation
• reopen → Reopen operation
• update → Update operation
• remove or delete → Remove operation
• list or report or ls → List operation
• No arguments → Default to list
• Anything else → Reject with an error: "Unknown command ''. Available commands: add, complete, reopen, update, remove, list"

Everything after the operation keyword is the payload.

Validation

Before executing any operation, validate metadata tags in the payload:

• @id(value) — reject if present in an add payload: "Task IDs are auto-assigned. Remove @id() and try again."
• @priority(value) — value must be one of: high, medium, low. Reject otherwise: "Invalid priority 'value'. Use high, medium, or low."
• @due(value) — value must be a valid date in YYYY-MM-DD format. Reject if the format is wrong or the date is invalid (e.g., 2026-13-45): "Invalid due date 'value'. Use YYYY-MM-DD format."
• @project(value) — value must be non-empty. Reject if empty: "Project name cannot be empty."

Task Matching

Several operations (complete, reopen, update, remove) need to find a task by the user's payload. Use this strategy consistently:

1. If the payload is @id(N) or a bare number N, match by task ID
2. Otherwise, perform a case-insensitive substring match against task descriptions (the text portion, ignoring @tag() metadata)
3. If zero matches: "No task matching '<payload>' in <section>"
4. If multiple matches: show a numbered list and ask the user to pick one
5. If exactly one match: proceed

Task IDs

Every task gets an auto-generated @id(N) tag (integer, monotonically increasing):

• On add: scan all tasks across all sections (Active, Completed, Removed) for existing @id() values. Assign the next integer after the highest found. If no IDs exist, start at 1.
• The @id() tag is placed at the end of the task line, after all other tags: - [ ] Description text @priority(medium) @created(2026-04-10) @id(3)
• IDs are permanent — they do not change when tasks are completed, removed, or reopened.
• Users can reference tasks by ID in any operation: /todo:todo complete 3 or /todo:todo complete @id(3)

Operations

add

Add a new task to the ## Active section.

1. Validate metadata tags (see Validation above)
2. Parse the payload for:
   • Task description (everything that isn't a metadata tag)
   • @project(name) — optional
   • @priority(high|medium|low) — default to @priority(medium) if not specified
   • @due(YYYY-MM-DD) — optional
3. Auto-generate @id(N) (see Task IDs above)
4. Auto-add @created(YYYY-MM-DD) with today's date
5. Construct the task line: - [ ] <description> <tags> @created(YYYY-MM-DD) @id(N)
6. Read the tasks file with the Read tool
7. Use the Edit tool to append the task line at the end of the ## Active section (before the next ## heading or end of file)
8. Update the updated date in the frontmatter to today
9. Confirm: show the exact task line that was added

complete

Mark an active task as completed.

1. Read the tasks file
2. Find tasks in the ## Active section
3. Match the payload against active tasks (see Task Matching above)
4. Move the matched task from ## Active to the top of ## Completed:
   • Change - [ ] to - [x]
   • Append @completed(YYYY-MM-DD) with today's date
5. Update frontmatter updated date
6. Confirm: show the completed task line

reopen

Move a completed or removed task back to Active.

1. Read the tasks file
2. Search for the matching task in ## Completed first, then ## Removed (see Task Matching above)
3. If zero matches in both sections: "No task matching '<payload>' in Completed or Removed"
4. Move the matched task to the bottom of ## Active:
   • Change - [x] or - [-] to - [ ]
   • Remove the @completed(YYYY-MM-DD) tag if present
   • Remove the @removed(YYYY-MM-DD) and @reason(...) tags if present
5. Update frontmatter updated date
6. Confirm: show the reopened task line

update

Modify an active task's description or metadata.

1. Read the tasks file
2. Parse the payload: the task identifier comes first (text, number, or @id(N)), followed by changes
3. Find the matching task in ## Active (see Task Matching above)
4. Determine what to change:
   • If the payload contains --desc "new description", replace the task's description text (the non-tag portion) with the new description
   • For each metadata tag in the payload (@priority(), @due(), @project()):
     • Validate it (see Validation above)
     • If the tag already exists on the task, replace its value
     • If the tag doesn't exist, add it
5. Update frontmatter updated date
6. Confirm: show the before and after task lines

remove

Remove an active task (move to Removed section with a reason).

1. Read the tasks file
2. Find the matching task in ## Active (see Task Matching above)
3. If the payload contains @reason(text), use it. Otherwise, ask the user for a brief reason (one line).
4. Move the matched task from ## Active to the top of ## Removed:
   • Change - [ ] to - [-]
   • Append @removed(YYYY-MM-DD) with today's date
   • Append @reason(<reason>)
5. Update frontmatter updated date
6. Confirm: show the removed task line

list

Display tasks with optional filters. Filters can be combined.

1. Read the tasks file

2. Parse filters from payload — multiple filters may be combined:

   • No payload or empty → show all active tasks
   • @project(name) → filter by project
   • @priority(high|medium|low) → filter by priority
   • @due → show tasks with due dates, sorted by due date (earliest first)
   • overdue → show tasks where @due() date is before today
   • completed → show tasks from ## Completed section
   • removed → show tasks from ## Removed section
   • all → show all sections (Active, Completed, Removed)

3. When multiple filters are present, apply all of them (logical AND). For example, /todo:todo list @project(keystone) @priority(high) shows only high-priority keystone tasks.

4. Preserve file order (the order tasks appear in the markdown) unless a sort is specified (e.g., @due filter sorts by earliest due date).

5. Format output as a bullet list. Each line starts with • followed by the task ID in dim gray, a —, then the task description and metadata:

   For active tasks:

   ## Active Tasks (N total)
   
   • 1 — Task description — @project(x) @priority(high) @due(2026-04-15)
   • 2 — Task description — @priority(medium)
   ...
   
   Summary: N active, N high priority, N overdue
   

   For overdue:

   ## Overdue Tasks
   
   • 1 — Task description — @due(2026-04-08) (2 days overdue) @project(x)
   ...
   

   The ID number and first — should be displayed in dim/gray so they recede visually. The task description should be normal weight.

6. Include summary stats at the bottom: total active, count by priority, overdue count

File Creation

When $CYBERDECK_TASKS file doesn't exist and the operation is add, create it with this template:

---
title: Tasks
updated: YYYY-MM-DD
---

# Tasks

## Active

## Completed

## Removed

Replace YYYY-MM-DD with today's date. Then proceed with the add operation.

Behavior Principles

• If all information is in $ARGUMENTS, execute without asking questions
• Only ask when genuinely ambiguous (multiple matches on complete/update/remove, or missing reason on remove)
• Be concise in confirmations — show what changed, nothing more
• Never rewrite the entire file — use Edit for targeted changes to preserve formatting and content
• Preserve the order of metadata tags on existing tasks when updating
• Show task IDs in list output so users can reference them in subsequent commands