Local task management (tasukura). Add tasks, list, change status, and record progress. Use /task for task operations, /progress for progress logging. Also refer to this skill when proactively recording progress on commits or design decisions.
Local SQLite-based task management CLI designed for AI coding agents. Track tasks and record progress.
Always execute the tk command directly.
# Correct (only this is allowed)
tk show <id>
tk list
tk add "Title" --description "..."
# Forbidden (never do this)
python -m tk ...
uv run tk ...
python tools/tk/main.py ...
tk is a CLI command registered in PATH. Execution via python -m, uv run, or python is strictly prohibited.
| Command | Description |
|---|---|
tk add "Title" --description "..." [--source-id ID] [--source TYPE] [--parent ID] [--next-action "..."] [--top] [--after ID] |
| Add a task (description is required. --top for top position, --after to insert after a specific task) |
tk list [--status todo,in_progress] [--source TYPE] [--flat] | List tasks (tree view by default) |
tk update <id> [--title "..."] [--description "..."] [--next-action "..."] [--source-id ID] [--source TYPE] | Update task fields |
tk status <id> <new_status> | Change status (todo/in_progress/in_review/done) |
tk log <id> --summary "..." [--details "..."] [--remaining "..."] [--next-action "..."] | Record progress |
tk rank <id> [--after ID] | Change display order (no args = move to top, --after = place after specified task) |
tk board [--status todo,in_progress] | Kanban board view by status |
tk show <id> | Show task details + logs + children |
IDs can be shortened — type just enough characters to uniquely identify a task.
| Field | Description |
|---|---|
title | Task name (short) |
description | Goal, acceptance criteria, and background (required) |
next_action | Next step to take. Displayed as -> in tk list |
status | todo / in_progress / in_review / done |
position | Display order (lower = higher priority. Change with tk rank) |
source_id | External source identifier (e.g. PROJ-123, #456) |
source | Source type (e.g. jira, github, linear) |
parent_id | Parent task ID. Supports multiple levels |
/task — Task OperationsInterpret user intent and execute the appropriate command:
tk add (confirm description with user)tk listtk status <id> in_progresstk status <id> in_reviewtk update <id> --next-action "..."tk rank <id>tk rank <id> --after <other_id>Set status to in_review when:
in_review = no action needed from you; waiting on someone else.
When adding with --source-id and --source, always retrieve the source description first and include it verbatim (no summarization) in the tk description. All information from the source (background, requirements, steps, links, etc.) must be preserved in the tk description.
Steps:
--description. Do not summarize--next-action/progress — Progress LoggingRecord progress based on user instruction or your own judgment:
tk list --status in_progress to find active taskstk log to record progress on the relevant tasktk status to change status if needed--next-action if the next step has changedRecord progress without user instruction at these moments:
Steps:
tk list --status todo,in_progress to find the relevant tasktk log <id> to recordLogs should contain enough context for another AI agent to pick up or resume the task.
--detailsA log with only --summary is insufficient. --details is mandatory.
--summary: One-line description of what was done or what happened--details (required): Include:
--remaining: Remaining work or blockers--next-action: Update the task's next action (updates the task record simultaneously)Bad (insufficient):
tk log <id> --summary "Created 7 tickets in JIRA"
Good (detailed):
tk log <id> --summary "Completed investigation and ticketing for auth module refactor" \
--details "Investigated the full repository and created 3 tickets:
1. PROJ-101: Extract shared validation logic - utils.py overlap ~90%
2. PROJ-102: Unify error handling - identified inconsistent response format
..."
Logs may be forwarded to external systems, so write them clearly enough for third parties to understand.