(dd36e97) Add install-skill, shipping the agent skill in the binary, and bump to 0.8.0

worklane's agent instructions only existed for someone with the repo checked
out. Anyone who installed the binary with cargo install got no document at
all, because cargo install places binaries and nothing else.

The skill now lives at assets/SKILL.md and is embedded with include_str, so an
installed copy can never be a different version from the binary that describes
it. `worklane install-skill` writes it, `--print` sends it to stdout so a
modified copy can be diffed, and a copy that was edited is reported and left
alone unless --force: it may have been changed on purpose, and silently
discarding that is worse than stopping.

One path serves both agents, ~/.claude/skills/worklane/SKILL.md. That was
settled empirically rather than from documentation: opencode 1.15.10 loads
~/.claude/skills as an external skill source alongside its own
~/.config/opencode/skill, and with HOME pointed at a temp directory holding
only what install-skill wrote, `opencode debug skill` lists the document under
the name worklane. Writing opencode's own path as well would be two copies of
one document, free to drift, for no gain.

The document is new rather than the one under .opencode, which is the user's
and not this repo's to ship. The ticket-workflow prose moved out of AGENTS.md
into it, so how to use worklane has one writer, and AGENTS.md points there.

The mechanism is in install.rs rather than skill.rs, and install() takes its
root as an argument: install-tool is coming, it needs a different root and the
same compare-and-refuse logic, and passing the root is what lets the tests
install into a temp directory instead of the home of whoever runs the suite.

Three tests guard the document itself, which is the part that goes stale
quietly: the frontmatter has to parse, every `worklane <x>` it shows has to be
a real subcommand, and every subcommand outside NOT_FOR_AGENTS has to appear in
it, so a new command cannot ship invisible to an agent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-21 15:25:31 +02:00
co-authored by Claude Opus 5
parent f740e42d1c
commit 6178d7bd3d
10 changed files with 587 additions and 10 deletions
+143
View File
@@ -0,0 +1,143 @@
---
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.
## 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."
```
`set` replaces, `append` adds. Neither has `--owner` or `--status`: owner is its own
command's, and status is `mv`'s. A field set to the value it already holds is reported
unchanged and nothing is written.
`worklane init` creates `.worklane/` with the four status directories, for a repo that
has no board yet.
## 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 say it is a regression. 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 reference the neighbour by id.
## 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.