---

name: tsk description: Use tsk, the task tracker maintained alongside this repository, to inspect task queues, manage local task records, create agent follow-ups, audit task history, and sync refs/tsk task state. Use when Codex is working in this repo and needs to choose queued work, record TODOs, mark tasks done, or coordinate task state with users or other agents. #

tsk Skill for Codex #

Use tsk as the source of truth for local task work in this repository. Start by looking at the active queue, keep user-visible task state accurate, and prefer tsk records over ad hoc TODO comments or plan files.

Basic workflow #

tsk list
tsk show -t 12
tsk push -- "Fix parser panic
Reproduce with an empty input file, then add a regression test."
tsk push -e -- "Draft task"      # open $EDITOR before saving
tsk append -- "Follow up: document parser edge cases"
tsk append -e -- "Follow up"     # open $EDITOR before saving
tsk drop -t 12
tsk abandon -t 12

• tsk list prints the active queue top first.
• tsk show -t N renders a task; add -x to include properties as YAML front matter, or -R for raw task text.
• tsk push -- "title" creates a task at the top of the active queue.
• tsk append -- "title" creates a task at the bottom of the active queue.
• Add -e to push or append to open $EDITOR before saving the new task.
• tsk drop -x -t N records the current git commit in closed-on, marks work done, and removes it from the active queue. Use plain drop only when there is no implementing commit to record.
• tsk abandon -t N removes a task from the active queue without changing its status.
• All commands that reference a task may implicitly reference to task at the top of the active queue by omitting selectors. Favor using explicit selectors such as -t N or -t N

Creating and editing tasks #

Use a single argument for a title, or put a body after the first newline:

tsk push -- "Investigate flaky sync test
Seen in CI after git-pull merge reconciliation. Capture the failing command and
decide whether the merge driver or test fixture owns the fix."

Read the body from stdin when another command already produced the detail:

printf 'Failure details...\n' | tsk push -- "Record failing CI output" -b -

Read the whole task (title + body) from stdin with - as the title. Parsed the same way tsk edit parses its editor buffer: first line is the title, the remainder is the body. Round-trips a task across repos:

tsk show -t 9 -R | tsk push -      # import a task from another clone
tsk show -t 9 -R | tsk append -    # ...or append it to the bottom

Edit an existing task interactively with $EDITOR, or replace only the body non-interactively with -b. Use -b - to read the replacement body from stdin:

tsk edit -t 12
tsk edit -t 12 -b "New body text"
printf 'New body from a script\n' | tsk edit -t 12 -b -

Reopen completed work when it becomes active again:

tsk reopen -t 12
tsk reopen --no-queue -t 12

Task text syntax #

The first line is the title. The remaining lines form the body. Line breaks stay intact. Task text uses these markers, not standard Markdown emphasis:

Syntax	Meaning
!important!	Bold
*optional*	Italic
_required_	Underline
~obsolete~	Strikethrough
=warning=	Highlight
`cargo test`	Inline code
[docs](https://example.com)	External link
<https://example.com>	Raw URL link
[[tsk-12]]	Task link in the active namespace
[[claude/tsk-3]]	Task link in another namespace
[> provision database <]	Create a new dependency task

Keep inline markers on one line. Separate marked text from adjacent text with whitespace or punctuation.

tsk push -- "Deploy service
Run \`cargo test\`. See [docs](https://example.com) and [[tsk-12]].
Blocked by [> provision database <]."
tsk follow -t 12           # list links
tsk follow -t 12 -l 1      # open the first link

On save, [> title <] creates a task and becomes a task link. It also sets the protected depends-on and blocks properties. Ordinary task links reference existing tasks without creating dependencies. Use tsk show -R to print the text without rendering its markers.

Queue order #

Move important work up and park lower-priority work at the bottom:

tsk prioritize -t 9
tsk deprioritize -t 15
tsk swap
tsk rot
tsk tor

• prioritize moves a task to the top of the active queue.
• deprioritize moves a task to the bottom.
• swap, rot, and tor are quick stack operations for the top tasks.

History and audit #

Every task, namespace, and queue is backed by git history:

tsk log task -t 9
tsk log namespace
tsk log namespace claude
tsk log queue
tsk log queue review

Use logs to understand who changed task text, id bindings, or queue order before you overwrite or reorganize work.

Sharing, assigning, and inboxes #

Share a task into another namespace when another user or agent needs a local id for the same underlying task:

tsk share claude -t 9

Assign a task from the active queue to another queue's inbox:

tsk assign review -t 9
tsk assign review -t 9 -R ""

The -R "" form skips the default auto-push. Without it, assign tries to push the relevant refs/tsk/* refs to the default remote.

Work an inbox from the receiving queue:

tsk queue switch review
tsk inbox
tsk accept
tsk accept -t 9
tsk accept review-1
tsk reject review-2
tsk inbox -R ""
tsk accept review-1 -R ""
tsk reject review-2 -R ""

• tsk inbox lists pending items for the active queue and auto-pulls first by default.
• tsk accept [key] moves an inbox item onto the active queue; with no key, it accepts the top inbox item.
• tsk accept -t N moves an open task with no queue assignment onto the active queue.
• tsk reject [key] returns an inbox item to its source queue's inbox.
• Use -R "" on inbox, accept, or reject to skip the default remote action.

Namespaces #

Namespaces control human-readable task ids such as tsk-12. The same stable task can be bound into multiple namespaces with different local ids.

tsk namespace current
tsk namespace list
tsk namespace switch claude
tsk switch tsk
tsk namespace tasks
tsk namespace tasks claude

• namespace current prints the active namespace.
• namespace list lists known namespaces.
• namespace switch <name> changes the active namespace; tsk switch <name> is shorthand.
• namespace tasks [name] lists every task bound in a namespace, independent of queue membership.

Use a separate agent namespace such as claude when you need agent-owned ids or follow-up bookkeeping that should not disturb the user's namespace.

Queues #

Queues are ordered work stacks. Task lifecycle comes from the protected status property, not queue membership. Keep the user's queue focused; put agent-created follow-ups in an agent queue when they are not part of the current request.

tsk queue current
tsk queue list
tsk queue switch claude
tsk --queue review list

• queue current prints the active queue.
• queue list lists known queues.
• queue switch <name> changes the active queue.
• --queue <name> overrides the active queue for one invocation.

Example agent follow-up:

tsk queue switch claude
tsk push -- "Add regression test for imported task conflict
The current change fixed the bug, but there is no test covering an imported task
whose namespace id collides after git-pull."
tsk queue switch tsk

Remote sync #

Use tsk sync commands for refs/tsk/*; plain git fetch can overwrite task refs without running tsk's reconciliation logic.

tsk remote default
tsk remote set-default origin
tsk git-setup -r origin
tsk git-pull
tsk git-pull --rebase
tsk git-push

• git-setup configures refspecs for sharing refs/tsk/*.
• git-pull fetches and reconciles divergent task histories.
• git-push pushes task refs to the default or supplied remote.

Agent rules of thumb #

• Run tsk list before choosing work unless the user gave an explicit task.
• Commit completed code changes before dropping the task. Include the human-readable task id at the bottom of the commit message body, then drop the task with ./target/release/tsk drop -x -t N so closed-on records the implementing commit. Drop without -x only when the user explicitly confirms or there is no code commit.
• Treat properties and queue changes as user-visible state.
• Prefer tsk push in an agent queue for follow-up work instead of adding unrelated TODO comments in code.
• When creating an overarching task that is composed of many smaller tasks, use the shorthand by writing a title between [> and <]. For example, blocked by [> provision database <] creates a new task titled provision database, replaces that text with an internal link such as [[tsk-12]], and records protected depends-on / blocks properties between the two tasks.
• Update tasks with information discovered during implementation. This can be later discovered and referenced using tsk namespace tasks -b and filtered with text filtering tools.