Files
worklane/assets/SKILL.md
T
Ansho ReiandClaude Opus 5 5b0bac9c2d (7bfb9fc) Add campaigns, a ticket container assigned through worklane assign, and bump to 0.12.0
There was no way to group the tickets that have to be finished together. A
goal such as a v1 release was either one ticket that could not describe its
parts, or a set of tickets with the goal restated in every description and
nothing tying them together.

A campaign is a file of its own under `.worklane/campaigns/`, with a title, a
description and metadata, and it sits in no status directory. Its state is
derived instead: open until every member is done. Deriving it means there is
no such thing as a done campaign holding an open ticket, and no second
forward-only ruleset beside `mv`'s. An empty campaign is neither open nor
done, since calling it done would make a container nothing has been filed
against the most complete thing on the board.

Membership is one field on the *member*, Campaign in the ticket Metadata,
written only by `assign`. The member list is deliberately not on the campaign:
that would put membership in two places and make one file that every
assignment edits, contended the moment two agents share a board. So `add`
gains no `--campaign` and neither does `set`.

`add` does not write the field either. Every ticket written before campaigns
existed has none, so the insertion path has to exist regardless, and leaving
it out of `add` means one path that is always exercised rather than two. That
is the Relations argument from 4179958, applied to a field instead of a
section. `set_or_insert_metadata_field` is the upsert and `METADATA_ORDER` is
its anchor list, the way `SECTION_ORDER` is `ensure_section`'s, so Campaign
lands beside Status rather than at the end and Status stays last. A file with
no Metadata heading is an error rather than an insertion, per 641e3d5.

The three tiers came out of `resolve_ticket` into `resolve_in`, shared by both
kinds. A campaign is addressed exactly the way a ticket is, and a second
resolver would be a second copy of the precedence rules to keep in step. Two
things fell out of that. `Found.dir` is the status for a ticket and empty for
a campaign, which is what drops the bracket from the ambiguity listing for
one. And `resolve_ticket` can now explain a search that names a campaign, so
`mv`, `show`, `chown` and everything else that takes a ticket give the same
reason instead of a bare "no ticket found" — one place rather than a check per
command. Only on the zero-match path, so an ambiguous ticket error is never
replaced by a complaint about a directory the caller never mentioned.

The stored value is the full uuid, per the same rule the Relations section
follows, and the title is resolved for display. `reference_cell` is now shared
between the two, so a dangling campaign and a dangling relation target are
both `_missing_` rather than each inventing a spelling. `Resolved` carries
what `content_trim` cannot render from the file alone: a struct rather than
two more parameters, so the next such field is one entry instead of an edit at
every call site.

`campaign show` lists done members, unlike `ls`, which leaves the done column
out of its listing. What is finished against what is left is the whole
question a campaign asks. `ls --campaign` is the other way round and keeps
every rule `ls` already has.

Deliberately out of scope. The derived progress figure is 1cb999f, now
recorded as blocked by this, since nothing here can compute it yet.
Unassigning needs a field cleared back to unset, which is 74904dc. And the
board gets neither a campaign tab nor a card marker: the detail view resolves
the field because it renders the body, and that is all. A marker would want a
read per reload and the four corners are already spent, which is the b8ce18c
reasoning; filed as 61879a4.

Twenty-four integration tests and eleven unit tests, covering assign,
reassign, the no-op, a dangling campaign, the ls filter, `mv` refusing a
campaign, insertion placement, and a handwritten section and unknown metadata
field surviving an assignment verbatim.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 00:52:57 +02:00

10 KiB

name, description
name description
worklane Manage tickets on a local worklane kanban board with the `worklane` CLI, backed by markdown files in a `.worklane/` directory. Use whenever you need to file, find, read, update, comment on or move a ticket, when asked what is on the board or what to pick up next, and when reporting work you are not going to do in the change at hand. Covers the four statuses, how a ticket is addressed, what belongs in each section, and the argument traps that silently swallow a flag.

worklane

A kanban board as files. Every ticket is one markdown file in .worklane/<status>/, named <uuid>_<slug>.md, and comments live in .worklane/comments/<uuid>/. The CLI is the only thing that writes there: do not hand-edit or hand-place a file, because the filename, the Status field and the directory have to agree and the commands are what keep them agreeing.

Commands walk up from the working directory to find the nearest .worklane, so run worklane inside the repo the ticket belongs to. Which directory you run it in is what decides which board the ticket lands on.

worklane with no subcommand opens an interactive board and needs a terminal. It is for a person, not for you: it takes over the screen and does not return until quit.

The flow

backlog → committed → reviewing → done

Move the ticket as you work it, not afterwards. worklane mv <id> --status committed before writing any code, and --status reviewing once it is done and the tests pass. The board is then true while the work is in progress, not only after it lands, which is the whole point of having a committed column.

Only one stage at a time is allowed, so a ticket left in backlog until the end cannot go straight to reviewing and has to be walked through committed anyway. Doing it up front is the same two commands in a more useful order. -f allows a backward or skipping move, for correcting a mistake.

A move is also refused while the ticket is blocked by one that is not done yet, see Relating tickets.

Reading the board

worklane ls                      # every status, counts then tickets
worklane ls backlog              # one status
worklane ls --priority 1         # only the most urgent
worklane show 1b78a24            # one ticket, body and comments

ls prints a seven-character id per ticket. That is what you address it by.

Working a ticket

worklane mv 1b78a24 --status committed
worklane check 1b78a24 3                      # tick acceptance criterion 3
worklane check 1b78a24 "the footer describes"  # or a substring of it
worklane uncheck 1b78a24 3
worklane comment 1b78a24 "Found the cause: the offset was never passed to the widget."
worklane mv 1b78a24 --status reviewing

Criteria are numbered by show. With the criterion omitted, check prompts when there is a terminal and otherwise fails with the numbered list, so always pass the criterion when you are not sitting at a prompt.

Filing a ticket

worklane add \
  --title "The tui detail view cannot scroll" \
  --description "Opening a ticket and pressing down moves to the next one instead." \
  --description "" \
  --description "Up and down are bound to select_card unconditionally, src/main.rs." \
  --acceptance "PageUp and PageDown scroll the detail view" \
  --acceptance "The footer describes the keys that exist" \
  --plan "Add a scroll offset to Board and pass it to Paragraph::scroll" \
  --plan "Clamp against the wrapped line count, not the raw line count" \
  --priority 2 --tags bug,tui

add always lands in backlog. Nothing is created without --title.

  • --description is the case for the ticket: the symptom, then what is actually wrong, naming the files, functions and settings involved. Repeat the flag for more lines; an empty --description "" between two values is a paragraph break.
  • --acceptance takes one criterion per flag, each a statement that can be checked off as true or false.
  • --plan takes one step per flag, numbered for you.
  • --priority runs 1 (most urgent) to 5 (least), and is left unset if omitted.

Editing afterwards, on a ticket in any status:

worklane set 1b78a24 --priority 1              # replace a field
worklane set 1b78a24 --title "A better title"   # renames the file, keeps the uuid
worklane append 1b78a24 --acceptance "One more criterion"
worklane append 1b78a24 --description "What was learned since."
worklane chown alice 1b78a24                    # hand the ticket to someone

set replaces, append adds. Neither has --owner or --status: owner is chown's and status is mv's, so each field has exactly one writer. A field set to the value it already holds is reported unchanged and nothing is written.

chown takes the user first and the ticket second, after Unix chown, which is the one command here that does not start with the ticket. The user is free text and is checked against nothing. Swap the two and the call fails, because the username has to resolve as a ticket.

worklane init creates .worklane/ with the four status directories and the campaigns directory beside them, for a repo that has no board yet.

Relating tickets

worklane relate 1b78a24 --blocked-by 4179958     # this one waits on that one
worklane relate 1b78a24 --regression-of 6d327df  # this one broke that one's fix
worklane relate 1b78a24 --relates-to 7bfb9fc     # neighbours, no dependency

One flag per kind, and each repeats. The ticket comes first and the flag says what it is to the target, so read the call as a sentence: relate A --blocked-by B means A waits on B. Only one side is stored, on the ticket you name, and show derives the other end for the ticket at the far side, so never record both directions.

--blocked-by is enforced: mv refuses to move a ticket while a ticket it is blocked by is not in done, whichever move it is, and names every open blocker. -f moves it anyway, beside the backward and skipping moves it already allows. The other two kinds are reference data and never refuse anything.

Recording a relation the ticket already holds reports no change. A ticket cannot relate to itself, and a target that later disappears shows as _missing_ rather than silently going away.

Campaigns

A campaign groups the tickets that have to be finished together: a release, a migration, anything whose parts are separate tickets but whose goal is one thing. It is a file of its own under .worklane/campaigns/, with a title and a description, and it sits in no status directory. Its state is derived instead, open until every member is done, so there is no such thing as a done campaign holding an open ticket.

worklane campaign add --title "v1 release" \
  --description "Everything that has to ship before the tag."
worklane campaign ls                    # every campaign and how far it has got
worklane campaign show "v1 release"     # its body, then its members by status
worklane assign "v1 release" 1b78a24    # put a ticket in it
worklane ls --campaign "v1 release"     # only that campaign's tickets

assign takes the campaign first and the ticket second, like chown, and is the only writer of the field. add has no --campaign and neither has set, so membership has one writer the way owner and status do.

A ticket is in at most one campaign, so assigning one that already belongs somewhere moves it rather than adding a second. Assigning it to the campaign it already names reports no change and writes nothing.

campaign show lists done members too, unlike ls, which leaves the done column out of its listing: a campaign is precisely the question of what is finished against what is left.

A campaign is addressed the way a ticket is, by uuid prefix, title or filename, but it is not a ticket. Passing one where a ticket is expected is refused with a message saying so, and there is no way to move a campaign, because it has no status to move.

Search the backlog before filing

Run worklane ls in the directory the ticket would land in and look for the same issue, including tickets already committed, in review or done. Search by the symptom and by the name of the function or setting involved, not only by your own phrasing of the title: an existing ticket will have been written from a different angle.

  • Already there and still open: add what you learned as a comment, not a second ticket.
  • Already there and closed, but the issue is back: file a new ticket naming the old id, and record it with relate <new> --regression-of <old>. There is no way to reopen one, and moving a done ticket back would destroy the record of the original fix.
  • Related but not the same: file it, and record it with relate <new> --relates-to <old> rather than only mentioning the id in prose.

Addressing a ticket

Every command that takes a ticket accepts, in this order of precedence:

  1. a UUID prefix, from four characters up
  2. a substring of the title
  3. a substring of the filename

The first tier that matches anything wins outright; the later tiers are not consulted. This matters because ticket titles quote other tickets' ids, and a flat search reported an exact id as ambiguous against whichever title mentioned it. An ambiguous match prints the candidates and exits 1 rather than guessing.

Traps

  • Prose arguments accept a leading hyphen: --title, --description, --acceptance, --plan and the comment body. A criterion reading --print is supported is stored, not parsed as a flag. The cost is that a genuinely mistyped flag there lands as content instead of failing, so read back what you wrote with worklane show.
  • --due, --priority, --tags, --owner and --status do not accept one, so a mistyped flag on those is a usage error and nothing is written.
  • A ticket argument that starts with a hyphen needs the flags first and a separator: worklane mv --status committed -- -leading-title.
  • A comment body of exactly -- needs its own separator: worklane comment 1b78a24 -- --.
  • An empty value for a scalar is a usage error. Clearing a field back to unset is not supported yet.
  • Piping is safe: worklane ls | head -3 exits on the closed pipe instead of panicking.