`campaign add --codename` was the only writer of the field, so a campaign already on the board could not be given one without editing the file by hand -- which is every campaign filed before 0.20.0. A `campaign set`, not a flag on something narrower: the file has more than one editable thing, and the moment somebody wants to fix a typo in a title there would be a second command to design. It carries `--title`, which renames the file the way `set --title` does, and `--codename`, through the same parser `campaign add` takes. Built out of `set`'s own parts -- `set_title`, `apply`, `report`, and the whole-file no-op comparison -- so nothing about writing a field lives twice. The codename goes through `set_or_insert_metadata_field` rather than `set_metadata_field`: a campaign filed before the field existed has no such line, and those are exactly the campaigns this is for. That exposed a second thing -- `Codename` was not in `METADATA_ORDER`, so an inserted line landed at the end of the block while `campaign_body` writes it under the ID, two shapes of one file. It is in the list now, directly after ID. `save_ticket` split into `save_entry` with `save_ticket` and `save_campaign` as named wrappers, so a campaign gets the same write-then- rename a ticket has rather than a second copy of it. `write_then_replace` and `find_entry_file` take the noun, so a failure says "campaign" where it is one. No `--description`, filed as 32e98ab: `set` and `append` are a pair for a prose section, and replacing a description with no way to add a paragraph is the half that loses the rest of it. No `--owner` and no `--clear`, each for a reason recorded on the ticket. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
79 lines
9.0 KiB
Markdown
79 lines
9.0 KiB
Markdown
# Worklane
|
|
|
|
Worklane is a local Kanban flow for agentic software development.
|
|
|
|
## Commands
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, whose border carries a page indicator 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; while one is selected a frame above the columns names it and says how far it has got, and `q` on its border gives the whole board back. 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 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 |
|
|
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
|
|
| `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 |
|
|
| `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` |
|
|
| `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 |
|
|
| `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 |
|
|
| `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, and `--codename`. At least one required. The only way to change a campaign after it is filed, and the way a campaign filed before codenames existed gets one. No `--description`: replacing prose without an `append` to add a paragraph is half a pair |
|
|
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, 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. Three 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. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
|
|
|
|
## Completions
|
|
|
|
```sh
|
|
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 four
|
|
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 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.
|