Files
worklane/AGENTS.md
T
Ansho ReiandClaude Opus 5 b7781a830c (482ff01) Grey unset Due and Owner in ls, and bump to 0.1.2
display_ticket_items printed both fields raw, so a ticket with no due date
showed _Not set_ in the default foreground. show already honoured the
guideline through colorize_metadata, leaving the listing as the one place
that ignored it. Reuses is_unknown_value rather than matching the markers
a second time.

Grey is indexed colour 8 in the 256-colour form. Two SGR spellings were
tried against a real terminal and both read as white: 90 leans on the
palette's bright-black slot, and 37 can sit right on top of the default
foreground. \x1b[38;5;8m is byte for byte what crossterm emits for
ratatui's Color::DarkGray, which is the grey frig and pantop already use
for dimmed rows, so this is the spelling known to render here. Pinned by a
test and written down in AGENTS.md, since only an eye in a real terminal
would catch it drifting back.

Patch bump covering the three colour tickets, 9991698, 934bf1a and this
one, as one body of work: nothing new, three places where output did not
do what the guideline said.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-20 15:24:42 +02:00

4.2 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, 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

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)
  • 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

Color Guideline

  • UUID → red (31)
  • Status → orange (33)
  • Timestamp → cyan (36)
  • Title → green (32)
  • Unknown values (_None_, _Not set_) → grey (38;5;8)
  • 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_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 filename
  • parse_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 --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