A bare digit in a listing is easy to skip over. Levels render as a two-segment meter that empties as the level rises: ●● 1, ●◐ 2, ●○ 3, ◐○ 4, ○○ 5, with ·· for unset and ?? for a value outside the range. Only ●, ◐, ○ and · are used, because they are what frig draws for its status indicators and so are known to be in the terminal font. The first cut of this used the quadrant circles ◕ and ◔, which are in a quarter as many fonts, so terminals substituted them from a fallback that drew them oversized and the column came out ragged. Two cells of a three-level ramp gives five steps of ink, 2, 1.5, 1, 0.5, 0, without leaving that safe set. Tests pin the safe set, the equal width and the monotonic emptying. The mark carries the level on its own, because colour cannot. Output is colourless whenever it is piped, which is how the opencode tools and every script read it, and NO_COLOR turns it off in a terminal too. Colour only accentuates: brightred, red, orange, cyan, grey, skipping green because green means title. The number counts up while the meter empties, since 1 is the most urgent. That is the convention, but it reads as a bug unless written down, so it is in AGENTS.md and in the legend. Both the ramp and the legend come from priority_mark, and `ls --help` prints the legend, since nothing in a listing explains a mark. brightred is indexed like grey, for the same reason: it is the spelling that renders. Minor bump: two new flags, a new metadata field and a changed ls row, covering dca0b61 and this ticket. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4.4 KiB
4.4 KiB
AGENTS.md
Project Structure
src/main.rs- All application logicsrc/command.rs- CLI argument definitions using clap derivetests/- Integration tests usingassert_cmdandassert_fs- Ticket files stored as
.mdin.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>.mdwith**Comment**,**Author**,**Time**fields
Status Workflow
backlog → committed → reviewing → done
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
Color and Output
- Use
color_text()helper for colored output — it respectsshould_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[0mafter colored text - Bold uses
\x1b[1;35m(magenta bold) - Always test color output works correctly in both terminal and pipe modes
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_metadata,colorize_ordered,content_trim_colored) handle markdown formatting 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 format
Ticket Resolution
resolve_ticket()returns(status, title, content)tuple- Priority: exact UUID prefix (8+ chars) > title substring > filename substring
- 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