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>
20 KiB
20 KiB
AGENTS.md
Project Structure
src/main.rs- dispatch, the SIGPIPE reset, and the TUI event loopsrc/command.rs- CLI argument definitions using clap derivesrc/handlers.rs- onecmd_*per subcommandsrc/util.rs- the ticket format, resolution, rendering and the palettesrc/tui.rs- board state, the change digest, and the ratatui drawsrc/install.rs- the embedded agent assets and the compare-and-refuse installassets/SKILL.md- the agent skillinstall-skillships, embedded withinclude_str!tests/- Integration tests usingassert_cmdandassert_fs, one file per command- Unit tests live beside the code in
#[cfg(test)] mod tests, inutil.rs,handlers.rsandtui.rs - Ticket files stored as
.mdin.worklane/<status>/directories
Ticket File Format
- Filenames:
<uuid_v4>_<slug>.md - The slug is the title through
slug(): lowercased, alphanumerics plus-and_kept, spaces turned into dashes.Ticket 06lands as<uuid>_ticket-06.md. Derive fixture filenames throughslug(), never by hand - Metadata fields parsed by
parse_ticket_field():ID,Priority,Tags,Due,Owner,Created At,Status - Format:
**Field Name**: value - Ticket structure:
# Title→## Description→## Acceptance Criteria→## Implementation Plan→## Metadata - Comments stored in
.worklane/comments/<ticket_uuid>/<timestamp>.mdwith**Comment**,**Author**,**Time**fields
Status Workflow
backlog → committed → reviewing → done
How to use worklane is in assets/SKILL.md, not here. That document is what
worklane install-skill ships, so it is the one place the flow, the move-as-you-work
rule and the argument traps are written down. Read it before working a ticket in this
repo. Do not restate any of it in this file: a second copy is a copy that goes stale,
and this file is for what someone changing worklane's own code needs.
Testing
- Run:
cargo test - Tests use
assert_cmdandassert_fsfor CLI testing setup_worklane()creates temp.worklane/with all four status folders pre-createdcreate_ticket()writes fully-formed markdown files directly (no--separator for positional args in test commands)
Coding Guidelines
Rust Style
- Use
if matches!(expr, Variant)instead ofif let Some(Variant) = exprfor enum variant matching - Use
if let Some(x) = exprinstead ofif let Some(Some(x)) = expr— drop unnecessary nesting - Prefer explicit
matchoverunwrap_or_default()for clarity - Use
unwrap_or_else(|| expr)for lazy defaults,unwrap_or(val)for eager defaults - Use
anyhow!()with context strings that include identifying info (e.g. UUID, title) not bare values
CLI Arguments
- The prose arguments carry
allow_hyphen_values, via thePROSEconstant incommand.rs:add --title,--description,--acceptance,--plan, and thecommentbody. Ticket text quotes flag names constantly, and without it a criterion reading--print is supportedis parsed as a flag and the whole ticket is refused with nothing written - The trade: on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why
due,priority,tags,ownerandstatusare deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not addPROSEto a new argument unless it holds prose - The ticket positionals (
show <id>,mv <ticket>,comment <ticket>) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with--, as inmv --status committed -- -leading-title - A bare
--is a value when it follows an option (--title --stores--) and clap's end-of-options marker when it sits in a positional. So acommentbody of exactly--needs its own separator,comment <ticket> -- --. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop addhas no positionals, so anything after a bare--is an unexpected argument and fails- A paragraph break in a description is an empty
--descriptionvalue.cmd_addjoins the values with a single newline, so-d "First." -d "" -d "Second."writes the blank line.trim_blank_ends()drops blank values at either end, so a break never lands against a section heading, and an all-blank description reads as no description. Interior runs are kept verbatim rather than collapsed --acceptanceand--planare lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only--descriptionpreserves blanks
Editing a Ticket
setreplaces a field,appendadds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, andappendonly offers the sections that hold multiple lines- One field, one writer.
sethas no--owner(that ischown's, once it exists) and no--status(that ismv's). Do not add either - Sections are a table in
util.rs:DESCRIPTION,ACCEPTANCE,PLAN, each with a heading, a label, the placeholderaddwrites when empty, and aSectionKind. Adding a section later is one entry, not edits in both commands - Everything is targeted line surgery, never a regenerated file. That is what keeps a ticked criterion ticked and a handwritten
## Notessection intact when an unrelated field changes.section_body()finds the lines to touch,set_metadata_line()does the metadata, and every other byte is copied through - Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read
_No description provided._above its description - An empty value is a paragraph break for the three sections and a usage error for the scalars, via
non_emptyincommand.rs. Clearing a field is not supported yet, and the error says so rather than guessing - No-op detection compares the whole file before and after each edit, so a field set to the value it already holds is reported unchanged and nothing is written
find_ticket_file()matches on the uuid, never the title. Duplicate titles are allowed, so a title scan can land on a different ticket than the one resolved:mv <uuid-of-second>used to move the first ticket sharing its titlewrite_then_replace()is the only way a ticket file is written. Content first, rename second, so a failure leaves a correct ticket under a stale name rather than a half-written one
Checking Off a Criterion
checkanduncheckare separate commands, not one verb with a flag. They shareCheckArgsandcmd_check(args, checked)criteria()is scoped to the Acceptance Criteria section and counts only checkbox lines, so a checkbox written into a description is not a criterion and a handwritten line inside the section takes no numberset_criterion()splices only the character between the brackets. Rebuilding the line would normalise its indentation and whatever spacing followed the checkbox- The criterion argument is an index first, a substring second, so a criterion whose text is literally
2is reachable only by substring - A number out of range is a bad index, not a failed substring search, and says so.
is_index()makes that distinction - Any listing of a subset must keep the real numbers, via
numbered_criteria(). Renumbering the matches from one contradicts the advice to use the number and points at the wrong criterion - With the criterion omitted: prompt when stdin is a terminal, otherwise return the numbered list as an error. Never prompt unconditionally, the opencode wrapper has no tty and would block on a stdin that never closes. This is the same choice
resolve_ticketmakes for an ambiguous match, and for the same reason shownumbers the criteria as1. [x] text, so the index is visible where the ticket is read. The number replaces the list marker rather than joining it
The Board View
worklanewith no subcommand andworklane tuiboth open it, the way a barefrigdoes.Cli::commandis therefore anOption- The worklane directory is looked for before the terminal, so running outside one gives the usual "No .worklane directory found" rather than a complaint about the tty. Both errors stay reachable and both are testable without a pty
- A missing tty is refused with a message naming a subcommand. Raw mode on a pipe fails with a bare "No such device or address (os error 6)", which explains nothing
- The watch looks at files, not directories. A directory's mtime only moves on create and rename, so a ticket edited in place would be missed.
digest()hashes every ticket and comment file's path, length and mtime. Comment files are in it because a comment added elsewhere has to reach the detail view - The digest guards the rescan, not the draw. ratatui diffs its buffer, so drawing every iteration is free; reading the tree every iteration is not
notifyis deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387- Cards come from
collect_ticket_items, the same sourcelsuses, so there is no second parser.TicketItem::pathexists for the detail view - The detail view scrolls on
pgupandpgdn, not on up and down. Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them - The scroll offset is clamped against the wrapped line count, from
Paragraph::line_count, which is whyratatuicarries theunstable-rendered-line-infofeature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed - The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does not reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
- Columns scroll to keep the selected card in view.
Board::offsetsholds one offset per column, parallel tocolumnsand resized in step byreload, so a column you leave stays where it was. The keypress aligns the focused column viafollow_selection(screen), taking the screen size for the same reasonscroll_detaildoes: the visible height belongs to the terminal, which only the caller measures between draws - Card heights are measured on
card_lines, never assumed, on both the keypress and the draw side (card_height, and thestartsvec as the cards are built). An alignment that trusted a fixed card height would drift from the renderer the first time the card changed shape - The draw aligns the focused column again on its own geometry, so a resize between keypress and frame cannot hide the selection, and caps every column against blank space past its last card. The stored value may go stale after a tick shrinks the column; that is fine, because what is drawn is corrected immediately and the next navigation writes the correction back
- Entering another column follows the selection rather than resetting to its top. The card index carries across columns, so a reset would open the column with the highlight below the fold whenever it was — the opposite of the detail view's reset-on-selection-move, where each ticket genuinely starts at its own top. The index is shared and clamps permanently when a shorter column pulls it down, so a column you return to follows the selection to where it now sits rather than holding your old place
- The footer names only keys that work. It read
↑↓ scrollwhen nothing scrolled at all, which sends the reader looking for their own mistake. A UI that misdescribes itself is worse than one that is merely incomplete - The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes.
content_trimandformat_comments_withtake the colour decision for that reason - Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
Shipping the Agent Assets
- The skill is embedded with
include_str!fromassets/SKILL.md, not copied by an install script.cargo installplaces binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it - One install path serves both agents:
~/.claude/skills/worklane/SKILL.md. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own~/.config/opencode/skill/. Verified against opencode 1.15.10, whose built-incustomize-opencodeskill documents the table and whoseopencode debug skilllists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain Assetcarries the content, the path under its root and the word used in messages, soinstall-tooladds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module isinstall.rsand notskill.rsinstall()takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirectsHOMEfor the same reason- A modified copy is refused, not overwritten. Someone may have edited it on purpose, and the message names
--printso it can be diffed and--forceso it can be replaced. A read error is not treated as absent either: the write reports the real reason - Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every
worklane <x>the skill shows has to be a real subcommand, and every subcommand outsideNOT_FOR_AGENTShas to appear in the skill. The last one catches a new command that nothing tells an agent about install-skilllooks for no board. The skill is what teaches an agent worklane, so needing a.worklaneto install it would put it out of reach exactly when it is wanted- The assets under
.opencode/are the user's, not this repo's to ship. Do not embed or install them
Color and Output
- Use
color_text()for coloured output — it respectsshould_use_colors()(terminal detection), andpaint()is the same with the decision passed in - The palette is the
Colorenum, not a string.Color::ansi()gives the CLI its SGR sequence andFrom<Color> for ratatui::style::Colorgives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is howmagentacame to be undefined - Reset color with
\x1b[0mafter colored text - Bold uses
\x1b[1;35m(magenta bold) - Always test color output works correctly in both terminal and pipe modes
quiet_broken_pipe()runs first inmain, restoring the defaultSIGPIPEdisposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of makingprintln!panic. Do not wrap prints to handle write errors and do not reinstateSIG_IGN; the exit codes are documented in the README
Color Guideline
- UUID → red (31)
- Status → orange (33)
- Timestamp → cyan (36)
- Title → green (32)
- Unknown values (
_None_,_Not set_) → grey (38;5;8) - Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground.
\x1b[38;5;8mis byte for byte what crossterm emits for ratatui'sColor::DarkGray, the grey frig and pantop use for dimmed rows
Code Organization
- Colorization functions (
colorize_line,colorize_ordered,content_trim_colored) handle markdown formatting showrenders the Metadata section as a two column table viarender_metadata_table, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width.paint()iscolor_text()with the colour decision passed in, which is what lets a test render both ways in one process- The title is printed once, by
cmd_show.content_trim_coloredskips the#heading in the file content - Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
resolve_ticket()scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filenameparse_ticket_field()handles extracting metadata values from markdown formatmove_ticket_file()stages the updated content in a temp file under.worklane/, renames it over the source, and only then renames the file into the target directory. Do not reorder these: renaming first and writing second leaves a ticket in its new directory claiming the old status, and writing to the target then deleting the source puts it in two directories at once. The temp lives outside the status directories so a leftover is never read as a ticket. A failure at the last step leaves the ticket in its old directory with a Status one move ahead, which the nextmvcorrects- Field lookup, read and write, is scoped to the lines under the
## Metadataheading and anchored to the start of the line. Prose above it is free text: tickets in this repo quote field markers in their descriptions, and an unscoped search reads or rewrites those instead.set_status_field()carries the same scoping
Ticket Resolution
resolve_ticket()returns(status, title, content)tuple- Three tiers, evaluated in order: UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the three reported an exact prefix match as ambiguous against whichever title mentioned it
- The UUID tier applies from
MIN_ID_SEARCH(4) characters up. Not 8:lsprintsSHORT_ID_WIDTH(7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, soshow 641is a title search - The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
- Ambiguous matches (multiple results) print options and exit(1)
- Never return empty strings for required fields — use
_Not set_or_None_as defaults
Git Workflow
- Commit format:
([ticketID]) [short description] - Use
--fixupfor incremental changes - Test before moving to reviewing status
Version Bumps
- Before every commit, decide whether the change warrants a version bump in
Cargo.toml - Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
- No bump for docs-only, tests-only or
--fixupcommits - When one body of work spans several commits, bump once on the final commit rather than on each
- Bump
Cargo.tomland theworklaneentry inCargo.locktogether, in the commit that carries the bump - Every bump gets a matching annotated tag,
v<version>, on the bump commit — a bumped version is never left untagged - Tag locally only; never push a tag unless asked
worklane --versionreports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another