Ansho ReiandClaude Opus 5 0f0767ac00 (8556048) Take a relation off with relate --clear, and bump to 0.32.0
`relate` only added. A `--blocked-by` pointed at the wrong ticket was on that
ticket forever, refusing every move it made until the target was done or `-f`
was passed again, and a target that was deleted did not clean up either: the
board carried a dead edge that nothing could clear and every later read of the
ticket paid for.

`--clear <kind> <target>` takes one off. It is on `relate` rather than on `set`
for the reason `RELATIONS` is out of `section_args`: a relation names a target
that has to be resolved first, so one writer owns both directions, the way
`chown` owns setting an owner and clearing one. It names the target and not
just the kind, because a ticket can hold several relations of one kind and
emptying all of them is not what anybody is asking for. That is also why it is
not spelled the way `set --clear` is, which names a field and empties it whole.

Both spellings of the kind are taken, `blocked-by` from the flag and
`blocked by` from the label: both are in front of the reader, the flag being
what recorded the relation and the label what `show` prints and the file
stores, so refusing the printed form would trap anyone clearing a row they had
just read. `RelationKind::flag` is a match rather than a `replace` on the
label, so the flag, the `--clear` value and the completion list cannot drift.

`find_relation` searches the ticket's own edges by id prefix before it searches
the board, and that order is the feature rather than an optimisation: no search
of the board reaches a target whose ticket is gone, so the stored-target tier
is the only thing that can clear a dangling edge, which is the case most likely
to need clearing. Two stored targets under one prefix name the candidates
instead of guessing, as an ambiguous ticket search already does.

An edge the ticket does not hold reports no change, and a target naming nothing
at all is an error. The two are different facts: the first is the state the
caller asked for, and the second is a typo that a no-op would swallow. The
resolver's own reason is carried through, so an ambiguous search says it is
ambiguous rather than being reported as nothing found.

Recording and clearing the same relation in one call is refused, and the check
runs on what was *asked* for and not on what would be written. A relation
already in the file is not among the additions, so comparing against those
would have let `--blocked-by X --clear blocked-by X` quietly remove it.

Removals rewrite the section from what is left and additions are appended to
that, in that order and in two passes: a call with no `--clear` then takes
exactly the path it always took. The last edge leaves the placeholder, which is
the line `append` treats as no content, so the next `relate` replaces it rather
than writing underneath it.

The two values are one flag, so clap cannot type them apart. `num_args = 2` is
per occurrence, which makes an odd number a usage error and every chunk a full
pair, and `cleared` parses the kind before the ticket is resolved. Nothing is
logged, in either direction, since `relate` never has: a log recording only the
destructive half would read as though the additions had never happened.

`chowns_clear_is_completed_with_tickets_and_sets_is_not` found the first rule
carrying `-l clear` and there are now three, on three commands, each taking
something different. It is `each_clear_flag_is_completed_for_its_own_command`,
scoped per command, and `relate --clear` offers the kinds rather than a board
listing, since tickets where the kind goes would be candidates it refuses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 12:13:37 +02:00
2026-05-14 20:41:40 +02:00
2026-08-24 11:03:28 +02:00

Worklane

Worklane is a local Kanban flow for agentic software development.

Commands

Command Description
worklane or worklane tui [path...] Opens the board: one column per status, redrawn when the tree changes. Read only. Opens with done and discarded hidden, their counts in the footer; d rotates hide both, show done, show both, and back around. Arrows or hjkl to move, enter for detail, pgup/pgdn to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, / to jump to the first ticket whose id or title matches, y to copy the selected ticket's short id to the clipboard, c to pick a campaign and filter the columns to its members, q to close whatever is open and then to quit. A card carries its campaign beside its tags, marked ~ and bold, and a comment count in its bottom right corner, the number then ❞ in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and q on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, enter gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first .worklane at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an all tab that merges them, with tab and shift+tab between them
worklane init Creates .worklane/ with backlog, committed, reviewing, done, discarded directories
worklane add Creates a ticket in backlog with --title, --description, --acceptance, --plan, --tags, --due, --owner, --priority flags. --due takes YYYY-MM-DD and refuses anything else at parse time
worklane ls [status] Lists tickets, sorted by priority then title. Optional positional status, and --priority <1-5>, --tag <tag> and --campaign <campaign>, which compose in any combination. --tag matches a whole value of the comma-separated Tags field, case sensitively, so --tag bug does not list a ticket tagged bugfix or one tagged Bug. --ids prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion
worklane show <id> Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three. Ends with the ticket's history: every comment on it and every change to its status, owner or tags, oldest first, each naming who made it
worklane mv <id> --status <target> [-f] Moves ticket between statuses. Default: forward only, one stage at a time. -f bypasses both restrictions. --status discarded is exempt and reachable from anywhere, for a ticket that will not be done; leaving discarded is a backward move and needs -f. Discarding is refused while open tickets are blocked by the ticket, -f overrides. Records a status entry in the ticket's history, after the move: a refused or no-op move records nothing. --actor names the writer of that entry
worklane set <ticket> Replaces fields with --title, --description, --acceptance, --plan, --tags, --due, --priority. At least one required. Changing the title renames the file, keeping the UUID. --clear <field> returns a field to unset instead, repeatable, taking due, tags, priority, description, acceptance or plan, and writing back exactly what add writes for a field it was never given. No title, which addresses the ticket, and no owner, which is chown's. Replacing and clearing the same field in one call is refused. --tags records a tags entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; --actor names the writer of that entry
worklane append <ticket> Adds to a section with --description, --acceptance, --plan. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last
worklane relate <ticket> Records an edge to another ticket with --blocked-by, --regression-of or --relates-to, each repeatable. At least one required. Only the ticket named is written; show derives the other end by scanning. mv refuses to move a ticket blocked by one that is not done, unless -f. --clear <kind> <target> takes an edge off instead, repeatable, the kind spelled either way, blocked-by or blocked by. The target resolves against the edges the ticket holds first, by id prefix, which is the only way to reach one whose ticket has been deleted, then as an ordinary ticket search. An edge the ticket does not hold reports no change; a target naming nothing at all is an error. Recording and clearing the same edge in one call is refused
worklane chown <user> <ticket> Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix chown. worklane chown --clear <ticket> returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user add falls back to. Records an owner entry in the ticket's history, with the owner before and after; --actor names who made the change, which is not the same as the user argument
worklane check <ticket> [criteria...] Ticks acceptance criteria, each by number as shown by show or by a substring. Several in one call, or all for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal
worklane uncheck <ticket> [criteria...] Unticks acceptance criteria, addressed the same way
worklane comment <ticket> <body> Adds a comment to a ticket by UUID or title. The author is --actor, or WORKLANE_ACTOR, or the git user, in that order
worklane campaign add Files a campaign in .worklane/campaigns/ with --title, --description, --codename and --owner. A campaign has no status: its state is derived, open until every member is done. --codename is one word to call it by, v1 or beaver, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by
worklane campaign set <campaign> Replaces --title, which renames the file keeping the uuid, --description and --codename. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs --force, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no --force: it is prose written to be revised. No --clear and no --owner
worklane campaign append <campaign> Adds a paragraph to a campaign's description with --description, which is required. The other half of campaign set --description, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level append, which resolves a ticket
worklane campaign ls Lists the campaigns as their short id, their codename, their title, how many members are done, and the state that count derives: [open] until every member is done and [done] after. A campaign nothing has been filed against reads no members and carries no state, being neither. --ids prints one per line as the id, a tab and the title, unstyled and without the counts, which read every ticket on the board, for a script or a completion
worklane campaign show <campaign> Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks
worklane assign <campaign> <ticket> Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after chown. A ticket is in at most one, so assigning one that already belongs somewhere moves it
worklane tags Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like ls --tag, so bug and Bug list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known
worklane completions <shell> Prints a completion script for fish, bash, zsh, elvish or powershell. See below
worklane install-skill [skill] Writes the embedded agent skills to ~/.claude/skills/<skill>/SKILL.md, which Claude Code and opencode both read. Four ship: worklane teaches the CLI, worklane-review reviews a finished ticket against the code that claims to close it, worklane-plan grooms the board as a whole, its priorities, due dates, tags and campaigns, and worklane-admin sets a board up and repairs one, its tag vocabulary and the faults a board can develop. Every document unless one is named. Leaves a modified copy alone unless --force; --print writes one to stdout instead and needs the name
worklane install-tool Writes the embedded opencode tool definitions to $XDG_CONFIG_HOME/opencode/tool/worklane.ts, or ~/.config/opencode/tool/ without it, where opencode loads them for every project. One file and so no name to pass. --force and --print behave as they do for a skill. opencode only: it registers the eleven worklane_* tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor @opencode-ai/plugin has to be on the machine

Environment

Variable Effect
WORKLANE_ACTOR Who every entry the CLI writes is attributed to: a comment, and the status, owner and tags entries mv, chown and set --tags record. Set it once, in the environment an agent runs in, and every call it makes is attributed to it instead of to the git user of whoever's machine it is on. --actor overrides it per call, an empty value counts as unset, and with neither supplied the author is the git user and then unknown. Free text, checked against nothing
NO_COLOR Set and non-empty turns colour off, whatever the value, per no-color.org. Colour is also off when output is not a terminal, and when TERM is dumb or empty
XDG_CONFIG_HOME Where install-tool looks for opencode's config root, $XDG_CONFIG_HOME/opencode, defaulting to ~/.config. install-skill does not follow it: ~/.claude is not an XDG path

Completions

worklane completions fish > ~/.config/fish/completions/worklane.fish

Also bash, zsh, elvish and powershell, though only fish gets the dynamic half.

The structure comes from clap, so new flags appear without anyone remembering to add them. The four statuses come with it, because a status is a value enum rather than a string. On top of that, fish asks worklane for the one thing only the board knows:

worklane show <TAB>              every ticket, id and title, done included
worklane mv <TAB>                the same, then --status <TAB> for the five
worklane chown alice <TAB>       the ticket, which is the second argument here
worklane chown --clear <TAB>     the ticket, which the flag carries here
worklane relate x --blocked-by <TAB>
worklane relate x --clear <TAB>   the three kinds, not a ticket: the kind comes first
worklane campaign show <TAB>     the campaigns, from `campaign ls --ids`
worklane assign <TAB>            the same, since a campaign comes first here
worklane ls --campaign <TAB>     and again
worklane ls --tag <TAB>          the tags, from `worklane tags`, with their counts

The tickets come from worklane ls --ids, the campaigns from worklane campaign ls --ids and the tags from worklane tags, one run per keypress, 2.5ms in release on a board of seventy-five tickets. Since fish runs whatever worklane is on PATH, completions need the installed binary to be current: an older one without --ids completes nothing. Re-run cargo install --path . after pulling.

tui is the one command whose argument is a path, so it is the one place fish still offers directories.

Exit codes

Code Meaning
0 Success
1 An error, such as no matching ticket or an ambiguous search
2 A usage mistake, such as an unknown flag, an unreal --due date, a priority out of range or a status that is not one of the four
141 Output was piped to a reader that stopped early, for example worklane ls | head -3

141 is 128 + 13, the shell's way of reporting death by SIGPIPE. Worklane restores the default signal disposition so a truncated pipe is quiet, the way head and sort are, rather than printing a panic. A script using set -o pipefail will see 141 for a case that is not a failure, so guard for it there.

Whether a truncated pipe reports 141 or 0 depends on the size of the output, not on the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer whole and the writer never learns the reader left, giving 0. Only output past that gets far enough to be cut off. Either way nothing is printed to stderr.

Releasing

make patch   # 0.27.1 -> next patch
make minor   # 0.27.1 -> next minor
make major   # 0.27.1 -> next major

Each bumps Cargo.toml and Cargo.lock, folds that bump into the last commit, and tags it v<version>. One action, so no bump is left untagged and no tag lands without a bump. In this repo it also appends , and bump to <version> to the commit's subject, the way the release commits before it read.

It refuses to run when the working tree is dirty, when HEAD is already tagged, or when HEAD is already pushed. The first asks you to decide whether that work belongs in the version; the other two mean the amend would orphan a tag or need a force push.

S
Description
No description provided
Readme
3.7 MiB
Languages
Rust 97.8%
TypeScript 1.9%
Makefile 0.3%