Every argument naming a campaign or a tag fell through to nothing: `campaign show <TAB>`, `assign <TAB>`, `ls --campaign <TAB>` and `ls --tag <TAB>`. Neither value had a listing a completion could parse. `campaign ls --ids` is the same flag and the same two fields as `ls --ids`, since it answers the same question about a different object. It skips the member counting the decorated listing does, because `members()` reads every ticket on the board and the caller is a shell on a keypress, and it prints nothing on an empty board where the decorated listing prints a sentence. Tags get a command rather than a mode on `ls`. `ls --tag <tag>` answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a `--tags` beside a `--tag` is one letter from a filter that means something else. `worklane tags` prints the tag, a tab and the count, alphabetical and case sensitive like the filter, so `bug` and `Bug` list separately and land next to each other. assets/PLAN.md used to tell the agent to count the vocabulary with a `show` per ticket; it now points here. The fish half gains `__worklane_nested_arg_of`, which matches a parent and a child, because `campaign show <TAB>` and `chown alice <TAB>` sit at the same token count and the two counting helpers cannot tell them apart. It also gains `__worklane_command_is`, which fixes a leak the campaign and tag rules would have joined. A bare `complete -c worklane -l tag` does not only complete that option's values, it tells fish the whole tool accepts `--tag`: `worklane init --<TAB>` offered `--blocked-by`, `--regression-of`, `--relates-to` and three others. `relate`'s three were already leaking that way, so all of them are scoped now rather than leaving a correctly scoped twin beside a wrong one. `__fish_seen_subcommand_from ls` is not the scope to use, since `campaign ls` is an `ls` fish has seen. The honesty tests grow to five lists and one walker, `every_argument`, since they differ only in the id they look for. Each asserts how many arguments it found, so a walker that stopped finding them fails rather than passing every assertion by never running it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
288 lines
15 KiB
Markdown
288 lines
15 KiB
Markdown
---
|
||
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).
|
||
|
||
`mv` stamps the time as it goes: `Committed On`, `Submitted On` and `Completed On`, one
|
||
field for the status the ticket is in now, shown by `show` among the rest of the
|
||
metadata. Only the current one is kept, so the stamp says how long the ticket has been
|
||
where it is, not how long each earlier stage took. Nothing else writes them, and moving
|
||
a ticket back removes the stamp of the status it left.
|
||
|
||
## 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.
|
||
|
||
`worklane ls --ids` prints the same tickets as an id, a tab and a title, one per line and
|
||
unstyled, with done included and the filters still applying. That is the form to parse
|
||
when you want the ids themselves: `worklane ls --ids | cut -f1`. The decorated listing is
|
||
for reading, not for cutting up.
|
||
|
||
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.
|
||
|
||
`worklane tags` answers the other question, the one `--tag` cannot: **what tags exist**.
|
||
One line per tag, alphabetical, as the tag, a tab and how many tickets carry it. Case
|
||
sensitive, like the filter, so `bug` and `Bug` list separately and land next to each
|
||
other, which is where a near-duplicate is spotted. Read it before inventing a tag, and
|
||
read it when a `--tag` filter comes back emptier than expected.
|
||
|
||
## 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 check 1b78a24 1 3 "the footer" # several in one call
|
||
worklane check 1b78a24 all # every criterion on the ticket
|
||
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 no criterion given, `check` prompts when there
|
||
is a terminal and otherwise fails with the numbered list, so **always pass the criteria
|
||
when you are not sitting at a prompt**.
|
||
|
||
One call takes as many terms as you like, mixing numbers and substrings, and `all` stands
|
||
for every criterion on the ticket. Use it when the work is done: it is one write instead
|
||
of one per box. `all` is a keyword, checked before the text, so a criterion whose own
|
||
words include "all" is reached by its number or by a longer substring.
|
||
|
||
**Every term is resolved before anything is written.** One term that matches nothing, or
|
||
matches more than one criterion, refuses the whole call and names that term, so the ticket
|
||
is never left half-marked. A criterion already in the state you asked for is reported
|
||
unchanged rather than refused, and a call that would change nothing writes nothing. Both
|
||
apply to `uncheck` exactly as they do to `check`.
|
||
|
||
## 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 set 1b78a24 --clear due # take a value away again
|
||
worklane set 1b78a24 --clear tags --clear plan # as many fields as you like
|
||
worklane append 1b78a24 --acceptance "One more criterion"
|
||
worklane append 1b78a24 --description "What was learned since."
|
||
worklane chown alice 1b78a24 # hand the ticket to someone
|
||
worklane chown --clear 1b78a24 # hand it back to nobody
|
||
```
|
||
|
||
`set` replaces, `append` adds, `--clear` empties. Neither `set` nor `append` 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, and so is a field cleared that was already unset.
|
||
|
||
**`--clear` takes the field as its value**, one of `due`, `tags`, `priority`,
|
||
`description`, `acceptance` or `plan`, and repeats. It writes back exactly what `add`
|
||
writes for a field it was never given: `_Not set_`, `_None_` for tags, and the section
|
||
placeholder. There is no `--clear title`, because a title addresses the ticket and names
|
||
its file. There is no `--clear owner` either: that is `chown --clear <ticket>`, which
|
||
takes the ticket in the flag since there is no user to give, and returns the field to
|
||
unset rather than to the git user. Replacing and clearing the same field in one call is
|
||
refused rather than resolved.
|
||
|
||
`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. `--clear` replaces both arguments with the ticket alone.
|
||
|
||
`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 ls --ids # id and title, tab separated, like ls --ids
|
||
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.
|
||
|
||
## Shell completions
|
||
|
||
```
|
||
worklane completions fish > ~/.config/fish/completions/worklane.fish
|
||
```
|
||
|
||
For the person's shell, not for you, and `bash`, `zsh`, `elvish` and `powershell` are
|
||
there too. Only fish completes ticket ids, which it does by running `worklane ls --ids`,
|
||
so a stale binary on PATH completes nothing and the fix is to reinstall it.
|
||
|
||
## 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, not a way to clear the field: use
|
||
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
|
||
the section either, and an all-blank one is refused with the `--clear` for it named.
|
||
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
|