From f271c7da8f945e076bcdc2861305246f55bb3ca3 Mon Sep 17 00:00:00 2001 From: Noah Pederson Date: Fri, 15 May 2026 09:51:08 -0500 Subject: [PATCH] Add skill subcommand --- SKILL.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 6 ++ 2 files changed, 203 insertions(+) create mode 100644 SKILL.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..76c72a1 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,197 @@ +# tsk Skill for Coding Agents + +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. + +## Basic workflow + +```sh +tsk list +tsk show -T tsk-12 +tsk push -- "Fix parser panic +Reproduce with an empty input file, then add a regression test." +tsk append -- "Follow up: document parser edge cases" +tsk drop -T tsk-12 +``` + +- `tsk list` prints the active queue top first. +- `tsk show -T tsk-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. +- `tsk drop -T tsk-N` marks work done and removes it from the active queue. + +## Creating and editing tasks + +Use a single argument for a title, or put a body after the first newline: + +```sh +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: + +```sh +printf 'Failure details...\n' | tsk push -- "Record failing CI output" -b - +``` + +Reopen completed work when it becomes active again: + +```sh +tsk reopen -T tsk-12 +``` + +## Queue order + +Move important work up and park lower-priority work at the bottom: + +```sh +tsk prioritize -T tsk-9 +tsk deprioritize -T tsk-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: + +```sh +tsk log task -T tsk-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: + +```sh +tsk share claude -T tsk-9 +``` + +Assign a task from the active queue to another queue's inbox: + +```sh +tsk assign review -T tsk-9 +tsk assign review -T tsk-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: + +```sh +tsk queue switch review +tsk inbox +tsk accept +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. +- `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. + +```sh +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 ` changes the active namespace; `tsk switch ` 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. Keep the user's queue focused; put agent-created +follow-ups in an agent queue when they are not part of the current request. + +```sh +tsk queue current +tsk queue list +tsk queue create claude +tsk queue create review -p +tsk queue switch claude +tsk --queue review list +``` + +- `queue current` prints the active queue. +- `queue list` lists known queues. +- `queue create ` creates a queue; add `-p` to allow other queues to pull + from it. +- `queue switch ` changes the active queue. +- `--queue ` overrides the active queue for one invocation. + +Example agent follow-up: + +```sh +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. + +```sh +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. +- Use `./target/release/tsk` after rebuilding this repo, because an installed + `tsk` may lag behind local changes. +- Drop a task only after the work is committed or the user explicitly confirms. +- 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. diff --git a/src/lib.rs b/src/lib.rs index 84e79c9..a4d611a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -243,6 +243,8 @@ enum Commands { #[arg(short = 's')] shell: Shell, }, + /// Print coding-agent usage guidance for tsk. + Skill, } #[derive(Subcommand)] @@ -534,6 +536,10 @@ fn dispatch(cli: Cli) -> Result<()> { generate(shell, &mut Cli::command(), "tsk", &mut io::stdout()); Ok(()) } + Commands::Skill => { + io::stdout().write_all(include_bytes!("../SKILL.md"))?; + Ok(()) + } } } -- knotmirror 0.0.1