Worked examples

Four days with taskr

Each of these is a whole scenario, commands and output, against an invented billing project. None of them adds a tool to your loop — they are the same five verbs reached for in different orders.

A model handoff

The case taskr exists for: your strongest model reads the problem and writes the plan, a cheaper one executes it, and nothing is spent rebuilding context in between. Neither model has to know the other exists — they meet on the issue.

Morning: the planner takes it

It reads the code, settles the design, and leaves both on the issue rather than in its own head. The spec's body is uploaded, not its path — the next agent has the issue and not your checkout.

The park reason is handoff, which is a different claim from blocked: nothing is stuck, the work is staged for someone else.

Afternoon: the builder resumes cold

That packet is the product. A fresh session, a different model, possibly a different machine — and it starts at the same commit, with the plan, the spec and a sentence saying what to do next. No prompt engineering, no pasted context, no "catch me up".

Moving the steps is what makes the next resume land somewhere real: each one records the commit it moved at, so the packet can say step 2 of 3, in progress since 4c8656a rather than describing progress in prose.

A solo day

One person, one agent. The whole shape of a working morning:

next ranks and says why. The block underneath is the part no queue can rank — checks only a person can run — so it is printed after the answer rather than mixed into it.

Then the thing that actually goes wrong on a real day: while fixing one bug you find another. Do not fix it inline, and do not save it for your final message, where it evaporates the moment the conversation ends.

The brief is the whole point. It gets read cold, days later, by someone with none of your context: a file:line, what is wrong, what you already ruled out, and how to tell when it is done. Two minutes now against an hour of re-derivation later.

Triage: is the report still real?

next only ranks issues with an actionable verdict, so a freshly imported backlog has plenty of open work and an empty queue. Someone has to say which reports are real. That is one verb, and it lists before it records:

Each row says why it is there. new has never been looked at. rot means the branch moved under it — the two SHAs are the snapshot the issue was filed against and where the repo is now. expired means a verdict aged out; they last a fortnight. ls is not a triage surface — it shows no verdicts and no reasons — and neither is next --untriaged, which is the ready pool and drops blocked issues and stale verdicts alike.

-e names where you looked: a file:line, a commit, a full URL. A verdict without evidence is the next reader's dead end. Only actionable puts an issue into next; already_fixed and stale say the work is not needed, and needs_info says it cannot be judged yet.

Checks as done-when

Some work cannot be verified when it is written. It needs a deploy, a production run, or an action only a person may take. A check records that condition on the issue so the issue can never read as done-but-unverified.

--human names who should carry out the procedure, not who records it. That distinction is what puts a check into the "needs a human" block of taskr next and onto the app's checks screen.

Then the close gate does its job:

Numbers go in as numbers — --measure takes typed values so two runs can be compared, and a failure keeps the check pending rather than settling it, because the latest run decides. Closing anyway is --despite-checks, and each pending check is recorded as skipped on the ledger rather than quietly dropped.

Onboarding a repo

Writes are refused against a repo taskr does not know, and taskr context says so rather than failing quietly — an issue filed against an unclaimed checkout cannot be ranked, scoped or resumed. Note where the hint sends you: at the taskr-onboarding skill, not at a person. It names the things registration needs, which is what lets the agent standing in the repo do this itself rather than handing you a task:

Two commands, two different claims: init creates the project and its ref prefix, attach says this checkout is one of its repos. Attach defaults both arguments to what it reads from .git, which is why it takes none.

In a monorepo, a project owns a directory rather than the whole repo, and one repo can carry several:

Setting the conventions at init is worth the extra flags. The branch shape, the commit style and the branch PRs target are printed by taskr project ls and beside the project in every taskr context, which is how an agent follows your house style without being told twice.

• Start here Install, authenticate, register a repo, close your first issue.
• CLI reference Every verb and flag used above, and the rest of them.