The board is where a ticket is found and the CLI is where it is acted on, and the only thing joining them was seven characters retyped off the screen. y reads as yank to the readers a keyboard board is for, and was the letter left after q, esc, enter, space, hjkl, the arrows, pgup, pgdn, tab, backtab, d and / took theirs. The mechanism was chosen against ssh, which is where a board is often read. OSC 52 crosses the connection, because it is the terminal at the reader's own end that owns the clipboard. A crate wants X11 and Wayland libraries at build time and, on X11, hands the selection to the process that set it: copy an id, quit, and the paste buffer is empty, which is precisely the flow this key exists for. Shelling out to wl-copy, xclip or pbcopy is platform sniffing plus a spawn, and does nothing where none of them is installed. crossterm 0.28 is what ratatui 0.29 pins and ships no clipboard command, so the sequence and its base64 are twenty lines in src/clipboard.rs, pinned on the RFC 4648 vectors. The cost is recorded rather than hidden, in AGENTS.md under The Copy Key: a terminal that ignores OSC 52 ignores it silently, and tmux needs set-clipboard on. What clipboard::copy reports is whether the sequence was written, and the footer says no more than that. There is no reply to read either, since the query form is refused by most emulators. What is copied is ticket.id, the seven characters the card already prints and every command already resolves, decided by Board::copy_text so the string is a question the suite can ask without a clipboard. None on an empty column: an empty string would take away whatever the reader had there and give nothing back. The project is left off even on the merge tab, since a second word would have to be deleted out of every paste. Board::copy_selected_id takes the clipboard as an argument, clipboard::copy from the dispatch and a closure from a test, which is what makes the hit and the refusal both drivable. A failure is said in the footer rather than returned: there is nobody above it to handle one, and an error swallowed there would look exactly like a copy that worked until the paste came out wrong. Notice is the board's first channel for saying something in words, and it has to be, because a copy leaves nothing on screen to look at. failed means nothing reached the clipboard, so an empty column and a refused write are one answer to the reader, both in brightred like the search's no match. It takes the whole footer row, since a message squeezed in beside the keys would move every key in it. Cleared by the next keypress rather than on a timer: no clock on the board, no wakeup in the loop, and never in tick, which runs four times a second. clear_notice goes ahead of search_key as well as the arms, because a key typed into a query is still a key. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
59 KiB
59 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/campaign.rs- the campaign file format, its resolution, its index and its memberssrc/tui.rs- board state, the change digest, and the ratatui drawsrc/clipboard.rs- the OSC 52 write and the base64 it carries, the board's only way out to the clipboardsrc/install.rs- the embedded agent assets and the compare-and-refuse installassets/SKILL.md- the agent skill for the CLI itself, embedded withinclude_str!assets/REVIEW.md- the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach;SKILL.mdkeeps its name because the role it teaches is the CLIassets/PLAN.md- the agent skill for grooming the whole board: priorities, due dates, tags and campaignstests/- 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 - Campaign files stored as
.mdin.worklane/campaigns/, which is beside the status directories and deliberately not instatus_dirs()
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,Campaign,Status.Campaignis the one no ticket is born with:adddoes not write it, so it is inserted on demand - 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-created, pluscampaigns/incmd_campaign.rs, which is also where the on-demand creation is tested from a board without itcreate_ticket()writes fully-formed markdown files directly (no--separator for positional args in test commands)cargo clippy --all-targetsis clean. Keep it clean, and do not silence a lint that is pointing at something real. The only twoallows in the tree sit on thecreate_ticketfixtures incmd_mv.rsandcmd_show.rs, each carrying the reason and what would replace it
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 - A command whose arguments run past a handful takes a clap
Argsstruct, not an inline variant with a matching parameter list:AddArgs,SetArgs,AppendArgs,CheckArgs.addwas nine positional parameters threaded frommainbefore it becameAddArgs, and the handler destructures the struct so the body reads the same as before
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 --dueis validated at parse time byiso_date, the way--priorityis bypriority_level. A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars withoutPROSE. One parser servesaddandset: the field has one definition of what it accepts, and validating onlyaddwould leavesetopen, which is the command a grooming sweep actually uses- The shape is checked before chrono is asked.
%Y-%m-%daccepts an unpadded2026-8-9, which would be stored exactly as typed and sort before2026-10-01in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting - Strict on the way in, tolerant on the way out.
util::due_datestill cuts2026-12-31T09:30:00Zdown to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake - An empty
--duekeepsnon_empty's message about clearing rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is that clearing is not supported yet - 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) and no--status(that ismv's). Do not add either chowntakes the user first and the ticket second, after Unixchown, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left toresolve_ticket, which refuses a bare username as a ticket. No argument is inspected to see whether it also names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the usernamecmd_chownisset_metadata_fieldplussave_ticket, with the same whole-file no-op comparisonsetuses and the samereport()output, so nothing about writing a field lives twice- 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
Relating Tickets
- The Relations section is
relate's alone.RELATIONSis in the section table but deliberately out ofsection_args, sosetandappendcannot reach it: a relation names a target that has to be resolved to a uuid first, and a prose flag would let an unresolvable line into the one section that is read back by machine. Same rule as Owner and Status, one field one writer adddoes not write the section. The plan on 4179958 asked for it in the ticket writer; it is out on purpose. A_No relations._block in every new ticket is noise in everyshow, and the insertion path has to exist regardless for every ticket written before the section did, so leaving it out means one path that is always exercised rather than two- The full uuid is stored, not the seven characters
lsprints. It resolves without a scan and cannot turn ambiguous as the board grows.showrenders the short id and the target's title instead: the file is the machine's copy, the output is the reader's - One direction is stored and the inverse is derived.
blocked bygoes on the gated ticket rather thanblockson the blocker, because the gated ticket is the one whose move is refused and whose author knows about the dependency.relates tois symmetric and is written once, on whichever end the caller ran it from.RelationIndex::inboundfinds the far end by scanning, which is what keepsrelatea single-file write - A line in the section that is not a relation is an error naming the ticket, not a line quietly dropped. Nothing but
relatewrites there, so a bad line means a hand-edited file. The TUI is the deliberate exception:detail_offalls back to no block, since one corrupt ticket must not take the whole board down - The block is built outside
content_trimand passed in. Half of it comes from other tickets andcontent_trimhas only the body. It is spliced over the stored lines where the file has the section, and injected ahead of the metadata where it does not, because a ticket that is only pointed at has no section of its own and still has relations to show ensure_sectioninserts againstSECTION_ORDER, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten## Notesbetween the plan and the metadata therefore keeps its place, and Metadata is in that list as an anchor rather than as something anything appends to- The blocker check runs on every move, after the already-in-that-status return and behind
force. An open blocker is a reason not to start and a reason not to finish, and one rule is easier to hold than a table of which transitions care. A move to the status the ticket is already in is not a move, so it is not refused.-fnow bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true - A blocker that is not on the board warns and allows the move. Refusing would wedge the ticket with no way out but
-f, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names every open blocker, since clearing the one that happened to be printed would leave the ticket blocked - Left out on purpose: removing a relation, which 4179958 assigns to 74904dc. The blocked marker on the card landed in b8ce18c, and it cost no scan of the board: the blockers ride along on the read that already builds the cards. See The Board View
Campaigns
- A campaign's state is derived, never stored. Open until every member is done, computed by
Standingfrom the members. AStatusfield on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is nocampaign mvand no forward-only ruleset besidemv's - A campaign with no members is neither open nor done.
Standing::state()returnsNonethere, and both callers printno members. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist - Membership is one field on the member,
Campaignin the ticket Metadata, written only byassign. The member list is deliberately not on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. Soaddhas no--campaignandsethas no--campaign, the same rule as Owner and Status - The full uuid is stored and the title is resolved for display, as the Relations section already does.
reference_cellis shared between the two, so a dangling campaign and a dangling relation target are both spelled_missing_rather than each inventing a spelling adddoes not write the field. Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out ofaddmeans one path that is always exercised rather than two. Same reasoning as the Relations sectionset_or_insert_metadata_field()is the upsert, andMETADATA_ORDERis its anchor list, the waySECTION_ORDERisensure_section's. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no## Metadataheading is an error, not an insertion: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads- The three tiers are
resolve_in(), shared by tickets and campaigns. A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step.Found.diris the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one resolve_ticketexplains a search that names a campaign, rather than each command doing it. One place, somv,show,chownand everything else that takes a ticket give the same reason instead of a bare "no ticket found". Checked only on the zero-match path, so it costs nothing normally, and only when exactly one campaign matches: an ambiguous ticket error must not be replaced by a complaint about a directory the caller never mentionedResolvedcarries whatcontent_trimcannot render from the file. The relations block and the campaign cell both come from elsewhere on the board. A struct rather than two more parameters, so the next such field is one entry here instead of an edit at every call sitecampaign showlists done members, unlikels, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks, so hiding half the answer is not an option.ls --campaignis the other way round: it is the ordinary board filtered, and keeps every rulelsalready hascampaign lsscans the status directories once per campaign to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice- The TUI gets neither a campaign tab nor a card marker, for now. The detail view resolves the field because it renders the body, and that is all. A marker on a card would want a campaigns read per reload, which is more than the blocked mark cost: that one reads the ticket's own Relations section on the pass that already builds the card, and a campaign title is in another directory
campaign_body()builds the file fromDESCRIPTIONandMETADATA_HEADINGrather than its own string literals, so the two file formats cannot drift apart on the spelling of a heading. A campaign has no acceptance criteria (its definition of done is derived), no implementation plan and no Status- The campaigns directory is created by
initand on demand bycampaign add, since every board made before campaigns existed has none and aworklane initover a live board to get one would be a strange thing to have to do
The Board View
- The board is for a person, and only for a person. Scripts and agents drive worklane through the CLI, which is what
assets/SKILL.mdteaches and what the integration tests pin. Nothing parses the drawn frame, so its layout is free to change: a new row on a card, a moved corner, a different colour or a hidden column breaks no caller. Judge a change here on whether it reads well, not on what it might break, and do not preserve a layout for compatibility's sake. What the CLI prints is the opposite case and is not covered by this 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 qandescare one key: close what is open, quit when there is nothing left to close.qused to setshould_quitoutright, so a reader who pressed it to put a ticket away lost the board instead, which is not whatqdoes anywhere else that lays a document over a list. One match arm inmain.rs, not two: two arms carrying one rule is how a later edit changes it for one key and not the other- The rule is
Board::dismiss, not the match arm. The dispatch inmain.rsis not reachable from a test, so anything decided there is undecidable by the suite. The arm is the line that names the keys and nothing else.the_dispatch_gives_q_and_esc_one_arm_and_leaves_ctrl_c_quittingscansmain.rsfor what the arm cannot say for itself, over whitespace-collapsed source so rustfmt cannot fail it - The footer's last slot always answers how to get out, and with a ticket open the honest answer is
ctrl-c, the only key left that quits in one press. Going on sayingq quitthere would be 1b78a24 in the other direction: a footer describing a key by what it used to do - The overlay names its ticket on the border, not at the head of the paragraph.
Board::detailis aDetailcarrying the title, the id and the text, because the name has to travel beside the body rather than inside it:content_trimdrops the#heading on purpose, sincecmd_showprints it, and anything in the paragraph scrolls away detail_titlecuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket- 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
- A card is four corners with the title between them: mark and short id top left, due top right, owner bottom left, criteria count bottom right. The two numbers are in corners because that is where the eye goes for one, and both were invisible at the end of a line of prose
- The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
- A card's height therefore depends on the column's width, so
card_linesandcard_heightboth take it.column_areasis shared between the draw andfollow_selectionfor the same reason:Ratiohands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts - A corner that will not fit is dropped whole, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
- The criteria count is a field on
TicketItem, filled incollect_ticket_itemswhere the file is already being read, and counted throughcriteria()so a checkbox in a description is not counted here or numbered byshow. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something.Nonerather than[0/0]for a ticket with no criteria - The tags go under the title, dimmed, each prefixed with
#. The field was invisible on the board: nothing said a ticket was taggedbugwithout opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one tagsis a field onTicketItem, filled incollect_ticket_itemsthroughparse_tags, for the reason the criteria count is.parse_tagssplits the comma-separated field into whole trimmed values, so a caller asking forbugis not answered bybugfix, and reads absent,_None_and empty as the same answer- A held-up card carries
×after its id, in brightred. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does - The mark goes after the id, not before it. Ahead of the id it would push every id in the column out of line whenever one card was blocked, which costs more than one card's state is worth. It is measured before the project label and the due date, so both give way to it: those are context for a ticket somebody can start, and this is the one thing on a card that says not to. Dropped whole when the row cannot hold the identity and the mark together, the rule a corner follows
blockedis onCard, not onTicketItem. The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the wayprojectis. Whatcollect_ticket_itemsfills is the ticket's ownuuidand itsblockers, both read off the file it is already holding;mark_blockedthen walks the four columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw- A blocker the board does not hold marks nothing, the answer
mvalready gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exceptiondetail_ofmakes for the same reason:showandmvare where a hand-edited file is reported, and a board that will not draw because one ticket is malformed is the worse failure - The merge carries the flag rather than recomputing it.
relateresolves its target inside one.worklane, so a blocker in another project is not a relation anything can record; resolving over the merged columns would let one project's uuid match another project's ticket. That is b8ce18c's fourth plan step and the answer is no project_labeltakes the width the row has already spent, measured off the spans, rather than adding up the widths those spans are supposed to have. The hand-written version left out the space after the priority mark, so a cut label was handed one cell more than the column had;the_project_label_leaves_the_row_inside_the_columnpins itdue_datecuts a due value back to its date only when it has one. The field is not validated (daa0e79), so it can hold a time or free text, and taking the first word regardless would turn "next friday" into "next"- Done is hidden until
dasks for it. Not a new opinion:lsalready counts done in its summary and leaves it out of the listing. Done only grows, so a quarter of the width was going to the column least often read. The footer carries its count while it is hidden, which is the board's version of that summary line - Hiding is a change to what is drawn, never to what is read.
reloadstill scans the done directory anddigeststill watches it, so the footer count is right and revealing the column needs no rescan. Do not "optimise" that into a conditional scan visible()returns a prefix ofcolumns, not a filter, which is what keepscolumnandoffsetsvalid as indices into either. It is derived from whereDONEactually sits rather than assuming the last slot, andthe_done_column_is_lastpins the assumption. A status inserted after done would otherwise hide two columns in silence- Hiding the column under the selection moves the selection to the last drawn column and closes an open detail view. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing done again is a no-op for the selection, since a column is appended rather than inserted
- The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
- Assert a column heading against the top border row, not the whole screen. The footer names done too, so
screen.contains("done (0)")passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden;headings()andfooter()exist so the next one does not.headings()locates the row throughboard_area()rather than taking row zero, since the tab row sits above it when more than one board is monitored
The Search Prompt
search: Option<Search>is the whole mode, the shapedetailuses: "the prompt is open" and "what is in it" cannot disagree, and closing it leaves nothing to reset.Searchalso carriesmissed, set when enter found nothing and cleared by the next edit, since the message is about the query that missed- The prompt swallows every key it is given.
Board::search_keyruns ahead of the action arms inmain.rsand reports what it took, rather than every arm below asking whether a search is open. Typingdinto a query must not toggle done andqmust not quit; with no prompt open it takes nothing, so the dispatch is unchanged for every other state. The rule is onBoardfor the reasondismissis: the arm is not reachable from a test ctrl-cis the one key it declines, because a terminal application always honours it and a prompt that ate it would leave no way off the board. Every other control combination is swallowed and does nothing: it must not type its letter, and it must not fall through either, since the action arms match on the code alone andctrl-dwould reach the one bound tod- Esc is consumed by the search before it can mean anything else, which is the collision e7612de left behind:
escandqclose the overlay, and both have to lose to an open prompt. It falls out of the pre-branch rather than being ordered by hand first_matchsearches the visible columns, every card in them, not the rows on screen. A query that answered differently on a tall terminal and a short one is not a search, and the jump scrolls the match into view anyway. Hidden columns stay out: with done hidden, a match there would put the highlight on a ticket that is not on the board. Reading order is column by column, then top to bottom- Id and title only, per 3b16540, both lowercased. The title has to be case insensitive to be worth typing, and giving the id the same treatment lets a pasted id match whatever case it was copied in. An empty or all-space query matches nothing rather than everything
- The jump goes through
select_at, the tailselect_cardalready used.follow_selectionscrolls the column the card is in, and the offsets are per column and on theTab, so a jump across columns moves the right one;refresh_detailkeeps an open overlay on the ticket the selection names. A second version of either is how a jump comes to scroll differently from the arrow keys - A hit closes the prompt and a miss keeps it open, marked, with the selection untouched. The query can then be corrected in place instead of retyped from
/. Doing nothing visible is what makes a reader retype a query that was already right - The prompt takes the whole footer row, because the key list it replaces describes nothing that currently works while every key is going into the buffer. The typed query is drawn in the default foreground and the keys in grey: one is content, the other is chrome.
no matchis brightred beside the query it is about, since grey chrome is what a reader skips - The real terminal cursor goes after the query, not a glyph standing in for one. ratatui shows the cursor only for a frame that asked for it, so
set_cursor_positionis also what says "you are typing" while the query is still empty. Clamped to the row, so a query longer than the terminal leaves it on the last cell - Both closed footers name
/, since the jump works with a ticket open as well: it moves the selection and the overlay follows - Out of scope on purpose, each its own ticket once the input mode exists:
nandNfor the next and previous match, searching the description, tags or owner, regex, and filtering the board down to matches rather than selecting one
The Copy Key
ycopies the selected card's short id, over OSC 52 written by hand. The board is where a ticket is found and the CLI is where it is acted on, and the only thing joining them was seven characters retyped off the screen.yreads as yank to the readers a keyboard board is for, and was the letter left:q,esc,enter,space,hjkl, the arrows,pgup,pgdn,tab,backtab,dand/were taken- The mechanism was chosen against ssh, which is where a board is often read. An escape sequence is the only one of the three ways that crosses the connection, since it is the terminal at the reader's end that owns the clipboard. A crate (
arboardand its kind) wants X11 and Wayland libraries at build time, and on X11 the selection belongs to the process that set it: copy an id, quit, and the paste buffer is empty, which is precisely this flow. Shelling out towl-copy,xcliporpbcopyis platform sniffing plus a process spawn, and does nothing on a machine where none of them is installed or on the far end of a connection. crossterm 0.28 is what ratatui 0.29 pins and it ships no clipboard command, and the backend types have to match whatever ratatui pins, so a newer crossterm cannot be picked up on its own - The cost is paid knowingly: a terminal that ignores OSC 52 ignores it silently, and tmux needs
set-clipboard on. Whatclipboard::copyreports is whether the sequence was written, not whether it was honoured, and the footer message says no more than that. There is no reply to read: the query form of OSC 52 is refused by most emulators as a security matter, so nothing better is available to us - Base64 is twenty lines here rather than a dependency, because the only thing that goes through it is a seven-character id. Pinned on the RFC 4648 vectors, which cover both padding forms, since a wrong encoder would put plausible-looking rubbish on the clipboard
cand notp: the clipboard proper, not the X11 primary selection, since this is pasted into a command line. Terminated with BEL, which is what tmux documents and what every emulator that implements this at all accepts- What is copied is
ticket.id, the seven characters the card prints, not the full uuid: they are what stops the retyping and whatshow,mvandcommentall resolve. Decided byBoard::copy_textrather than inside the arm that copies, so the string is a question the suite can ask without a clipboard.Noneon an empty column, since an empty string would take away whatever the reader had there and give nothing back - The project is left off even on the merge tab, where the id alone is not an address. This goes onto a clipboard to be pasted into a command line, and a second word in it would have to be deleted every time; running the command in the wrong project fails to resolve rather than acting on the wrong ticket
- The clipboard is handed to
Board::copy_selected_idas an argument,clipboard::copyfrom the dispatch and a closure from a test. That is what makes both answers drivable, and it keeps the terminal write out of the board state - A failure is said in the footer, not returned. There is nobody above it to handle one: the board goes on being drawn, and an error swallowed there would look exactly like a copy that worked until the paste came out wrong
Noticeis the board's one channel for saying something in words, since a copy leaves nothing on screen to look at.failedmeans "nothing reached the clipboard" rather than "an error occurred", so an empty column and a refused write are one answer to the reader, both in brightred for the reasonno matchis- It takes the whole footer row, on a weaker reason than the prompt's: every key still works while a notice is up. It is that a message squeezed in beside the key list would move every key in it, and the row is the only part of the board that is not a ticket. Drawn after the prompt, which is an input and cannot be covered
- The notice is cleared by the next keypress, not by a timer. No clock on the board and no wakeup in the loop, and the moment the reader does anything else the message has been read or was never going to be. Doing nothing leaves it up, which is the one state where it is still worth reading.
Board::clear_noticeruns ahead ofsearch_keyas well as the arms, since a key typed into a query is still a key, and it must never move intotick: the board redraws four times a second and a notice cleared there would never be read
Monitoring Several Boards
worklane tui <path>...takes any number of paths, each resolved throughfind_worklane_dirthe way the working directory is: the first.worklaneat or above it. No path is the working directory, so a bareworklaneandworklane tuiare unchanged- The failure names the path that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare
worklanehas no path to name and keeps the message every other command gives, which is what its integration test asserts - Two paths inside one project resolve to the same
.worklaneand are monitored once.projects()dedupes on the resolved directory, not on the argument Tabowns the selection,column,cardandoffsets, notBoard. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to.Board::current()is the tab in view, andshow_donestays on the board because it is a preference about the flow rather than about a project- The tabs are fixed for the run: a project cannot be added or dropped without restarting, so
Board::newbuilds the tab list once andreloadonly refills each tab's columns.reloadclamps every tab, andselect_tabclamps again on arrival, because done may have been hidden while another tab was in view - The merge tab goes first and is where the view opens: it is the reason to monitor several boards at once. It is materialised in
reload, from the cards already read, rather than computed per draw — the same reason the criteria count is filled incollect_ticket_items - The merge is sorted, through
by_priority_then_titleinutil.rs, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. That comparator is exported for this and is the onecollect_ticket_itemsuses, so the two orders cannot drift Cardwraps aTicketItemwith the project it came from,Someonly on the merge tab. Decided at reload rather than passed down tocard_linesas a "which tab is this" flag.TicketItemis thereforeClone: the merge holds a second copy rather than re-reading every tree- The project follows the id, on the card and on the overlay border. Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live.
project_labeltakes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is whatcorner_linedrops tabandshift+tabcycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns tookhjkland the arrows- The tab row is drawn only when there is more than one board, so a single board is the view it has always been.
frame_rows()gives itLength(0)otherwise, which keeps the row indices the same for both cases and is shared withcard_widthandcolumn_text_heightfor the reasoncolumn_areasis: geometry reproduced by hand drifts from the draw digest_ofhashes each board'sdigestinto one value, so a change in any of them redraws. Do not watch only the first
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.reviewing-agent.mdthere is the prior art the review skill grew out of and is deliberately left in place: its content is now inassets/REVIEW.md, but deleting a file under.opencode/is not this repo's call. Whether the stale copies there go is b2c5531's question install-skillwrites every shipped document, and the name narrows it. One document teaches the CLI and the others teach a job done with it, so a person who learned the invocation before a document existed still receives it. Requiring a name per document would mean a new skill silently never arrives for anyone who does not read the changelog--printrequires the name. It exists so a modified copy can be diffed, and a diff is against one document; printing them concatenated would be neither of them. The unnamed case errors with the list of names rather than guessing, the same choice thecomment --body makes- The refusal message names the document it is about,
install-skill worklane --print, since with several installed "compare with --print" does not say compare what - A refused document does not stop the ones behind it. The loop reports an outcome per document and the "pick it up on their next session" line is printed once, and only when something was actually written
- A role skill is its own document, not a section of
SKILL.md. The frontmatter description is the whole of what decides whether a skill loads, and one description cannot name both "anything touching a ticket" and "only when a review is asked for" without fitting neither. It is also why the review document does not restate the CLI: it says to read theworklaneskill too - The review skill's own rules are guarded by
the_review_skill_keeps_the_decisions_that_define_it, because each of them is a line an edit could drop without breaking anything: the reviewer never ticks a criterion (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), never moves the ticket (mvbelongs to whoever does the work, the reviewer's half is the recommendation), and never reviews the working tree when no commit names the ticket (it says what it searched for and stops, since an untraceable ticket inreviewingis itself the finding) - The plan skill is the one that can do damage, so its rules are the ones under test.
set --tagsreplaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable.the_plan_skill_keeps_the_rules_that_bound_a_sweeppins propose-then-apply and those two traps, because a document that loses them still reads like a plan .opencode/agent/feature-planner-agent.mdis deliberately not folded intoPLAN.md. It decomposes a feature request into new tickets, which is intake;PLAN.mdorders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own documentevery_agent_facing_subcommand_is_documentedstays onSKILLalone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document withinitand campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
Color and Output
- Use
color_text()for coloured output — it respectsshould_use_colors()(terminal detection), andpaint()is the same with the decision passed in color_text()is for the CLI's own printing only. Anything reachable fromcontent_trimtakes the decision as an argument and callspaint(), because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes.nothing_the_body_renders_asks_the_terminal_for_the_colour_decisionscans this file and fails on a new caller; the allowlist isambiguous, which builds a failed-search message for stderr- A function that takes an
enabledflag must use it all the way down.colorize_boldhonoured its flag on the early return and then askedshould_use_colors()for the bold run, which made the flag a lie in half the function - A test that asserts an absence has to be paired with one that asserts the presence. The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so
should_use_colors()was false and the leaking branch was never taken. The pair is nowcontent_trim(.., false)has no escape andcontent_trim(.., true)still colours, which pins the flag as the only thing that decides - 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
- The palette splits in two: seven colours that each mean one thing, and
TAG_COLORS, the eight a tag may be drawn in. A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour inTAG_COLORS, and do not draw a tag in one outside it tag_color()is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, becauseBugandbugare two different tags to the field and to every search- The hash is FNV-1a written out here, not
DefaultHasher. std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for.the_tag_mapping_is_pinnedfails on any change to it, so a repaint is a decision rather than a surprise - The index is multiply-shift, not
% TAG_COLORS.len(). The length is a power of two, so a modulus keeps only the low three bits of the hash, and FNV-1a's low bits carry only the low bits of the input bytes: multiplication cannot move information downwards. Under a modulus every pair of tags differing above bit 2,bugandBUGamong them, landed in one slot regardless of the rest of the string. It looked like a good palette on this board, two colliding cards out of sixty-four, because the vocabulary had been folded into a handful of slots. Taking the top bits of a 128-bit product uses the whole hash - Eight tag colours means roughly one card in five shows two tags alike. That is arithmetic and is accepted: the colour groups a tag across cards, it does not tell two tags apart within one, and the tag text is beside it either way. Do not widen the list to chase the number on one board
- 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_ordered,colorize_bold,content_trim_colored) handle markdown formatting.colorize_lineis gone: it was apubalias forcolorize_boldwith one caller, and the only thing it added was asking the terminal 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
- Changed output means the CLI's output. That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
- 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