Files
worklane/AGENTS.md
T
Ansho ReiandClaude Opus 5 bbb1568a0f (eadaca9) Add check and uncheck for one acceptance criterion, and bump to 0.6.0
Criteria are stored as - [ ] lines and nothing could tick one, so marking
progress meant replacing the whole list through set, losing the state of every
other item.

check and uncheck are separate commands rather than one verb with a flag,
sharing CheckArgs and cmd_check. The criterion is an index first and a substring
second, so a criterion whose text is literally "2" is reachable only by
substring. A number out of range is reported as a bad index rather than as a
substring that missed.

Only the character between the brackets is spliced, so the text keeps whatever
indentation and spacing it had. Criteria are counted inside the Acceptance
Criteria section only, so a checkbox written into a description is not a
criterion and a handwritten line in the section takes no number.

With the criterion omitted, the criteria are listed and the number asked for
when stdin is a terminal. Where it is not, the same list comes back as an error
instead. Prompting regardless would leave the opencode wrapper blocked on a
stdin that never closes, and that is the choice resolve_ticket already makes for
an ambiguous match, for the same reason: the wrapper keeps stderr and throws on
the code, so a list printed to stdout would be discarded.

Any listing of a subset keeps the real numbers. Renumbering the matches from one
would contradict the advice to use the number and point at the wrong criterion.

show now numbers the criteria as "1. [x] text", so the index is visible where
the ticket is read. That also drops a manual prefix strip, so clippy is one
warning below where it started.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-21 10:46:07 +02:00

12 KiB

AGENTS.md

Project Structure

  • src/main.rs - All application logic
  • src/command.rs - CLI argument definitions using clap derive
  • tests/ - Integration tests using assert_cmd and assert_fs
  • Ticket files stored as .md in .worklane/<status>/ directories

Ticket File Format

  • Filenames: <uuid_v4>_<slug>.md
  • 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>.md with **Comment**, **Author**, **Time** fields

Status Workflow

backlog → committed → reviewing → done

Testing

  • Run: cargo test
  • Tests use assert_cmd and assert_fs for CLI testing
  • setup_worklane() creates temp .worklane/ with all four status folders pre-created
  • create_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 of if let Some(Variant) = expr for enum variant matching
  • Use if let Some(x) = expr instead of if let Some(Some(x)) = expr — drop unnecessary nesting
  • Prefer explicit match over unwrap_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 the PROSE constant in command.rs: add --title, --description, --acceptance, --plan, and the comment body. Ticket text quotes flag names constantly, and without it a criterion reading --print is supported is 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, owner and status are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add PROSE to 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 in mv --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 a comment body 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
  • add has no positionals, so anything after a bare -- is an unexpected argument and fails
  • A paragraph break in a description is an empty --description value. cmd_add joins 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
  • --acceptance and --plan are lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only --description preserves blanks

Editing a Ticket

  • set replaces a field, append adds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, and append only offers the sections that hold multiple lines
  • One field, one writer. set has no --owner (that is chown's, once it exists) and no --status (that is mv's). Do not add either
  • Sections are a table in util.rs: DESCRIPTION, ACCEPTANCE, PLAN, each with a heading, a label, the placeholder add writes when empty, and a SectionKind. 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 ## Notes section 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_empty in command.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 title
  • write_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

  • check and uncheck are separate commands, not one verb with a flag. They share CheckArgs and cmd_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 number
  • set_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 2 is 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_ticket makes for an ambiguous match, and for the same reason
  • show numbers the criteria as 1. [x] text, so the index is visible where the ticket is read. The number replaces the list marker rather than joining it

Color and Output

  • Use color_text() helper for colored output — it respects should_use_colors() (terminal detection)
  • Color codes are defined in get_color(): red (31), cyan (36), orange (33), green (32), grey (38;5;8), magenta (1;35), brightred (38;5;9)
  • Reset color with \x1b[0m after 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 in main, restoring the default SIGPIPE disposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of making println! panic. Do not wrap prints to handle write errors and do not reinstate SIG_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;8m is byte for byte what crossterm emits for ratatui's Color::DarkGray, the grey frig and pantop use for dimmed rows

Code Organization

  • Colorization functions (colorize_line, colorize_ordered, content_trim_colored) handle markdown formatting
  • show renders the Metadata section as a two column table via render_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() is color_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_colored skips 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 filename
  • parse_ticket_field() handles extracting metadata values from markdown format
  • move_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 next mv corrects
  • Field lookup, read and write, is scoped to the lines under the ## Metadata heading 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: ls prints SHORT_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, so show 641 is 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 --fixup for 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 --fixup commits
  • When one body of work spans several commits, bump once on the final commit rather than on each
  • Bump Cargo.toml and the worklane entry in Cargo.lock together, 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 --version reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another