Files
worklane/assets/SKILL.md
T
Ansho ReiandClaude Opus 5 ae3ee1bb9e Show the target's status beside the relation kind, and bump to 0.15.2
A row now carries two marks, kind then status: what sort of edge this is, then
how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`.
Two questions are asked of this block, which rows hold this ticket up and
whether the ones that do are finished, and one glyph could not answer both.

○ not started, ◐ under way, ● finished, in grey, orange, cyan and green: the
shape says how far the target has got and the colour tells the two middle
stages apart, since committed and reviewing are both half circles. Green is the
colour the priority ramp deliberately leaves out because it means a title; on a
one-cell mark with no title behind it nothing else wants it, and it is the
obvious colour for done. Orange keeps the meaning it already has, Status.

These are the priority meter's own circles, and what keeps a status from
reading as a level is width: the meter is always two cells, a status mark is
one. the_status_mark_is_one_cell_where_the_meter_is_two pins both halves, and a
card carries the meter and never a status mark while the block carries the
status mark and never a meter.

The kind mark survives a target the board cannot find and the status mark
cannot, since a kind is read from the ticket's own file and a status from the
board. ? holds the column so the id does not move when one target has gone, and
_missing_ is what says it is gone.

Committed and reviewing are told apart by colour alone, so a pipe cannot tell
them apart: both read as under way. Accepted, since ● and ○ are the two answers
usually wanted and show on the target settles the rest, and assets/SKILL.md now
says so outright rather than leaving an agent to work it out from a colourless
half circle.

RelationTarget is back, carrying the title and the status in one Option because
they come from the same lookup. It went out in 5ae9c7f when nothing read the
status and came back one commit later, which is what a field nothing reads
costs: right at the time, churn either way.

A patch: 0.15.0 was the arrival of a marked relations block and this is still
settling what it marks. Three minors in an hour would read as three features.

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

233 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: worklane
description: 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](#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 ls --tag bug # only the tickets carrying that tag
worklane show 1b78a24 # one ticket, body and comments
```
`ls` prints a seven-character id per ticket. That is what you address it by.
The filters compose in any combination, with each other and with the status positional:
`worklane ls backlog --tag bug --priority 1`. `--tag` takes one tag and matches it
against the whole values of the comma-separated `Tags` field, case sensitively, so
`--tag bug` finds neither a ticket tagged `bugfix` nor one tagged `Bug`. A ticket with no
tags matches none. A tag nothing carries lists nothing rather than failing, so when a
listing comes back empty check the spelling against a ticket you know is tagged.
## 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.
- **`--due`** takes `YYYY-MM-DD` and nothing else. Anything that is not a real calendar
date in that exact form, `2026-8-9` and `2026-02-30` included, is a usage error with
nothing written. The same parser guards `set --due`.
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.
`show` marks each row twice, kind then status. The kind is `×` for `blocked by` and
`blocks`, `→` for `relates to`, `←` for `regression of` and `regressed by`; both
directions of one kind carry one mark, and the label is what says which end you are on.
The status is the target's own: `○` backlog, `◐` committed or reviewing, `●` done, and
`?` for a target the board no longer holds. So `blocked by × ● (1b78a24)` is a blocker
that is finished and `blocked by × ○ (1b78a24)` is one nobody has started. The board
draws the same block.
Colour is what tells committed from reviewing, since both are `◐`, and **your output is a
pipe, so you do not get the colour**. Read `◐` as under way, and if it matters which
stage, `worklane show` on that target says so in its Status field. `●` and `○` are
unambiguous without it, which are the two answers usually being asked for.
## 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.