Files
worklane/AGENTS.md
T
Ansho ReiandClaude Opus 5 ab1dae098c (641e3d5) Scope metadata field lookup to the Metadata section, and bump to 0.2.1
parse_ticket_field searched every line of the file with contains, and
set_status_field rewrote the first line starting with the Status marker
wherever it sat. Tickets in this repo quote field markers in their
descriptions, so a description list shaped like metadata was read in place
of the real value and rewritten by mv, leaving the metadata stale.

Both now scan only the lines under the Metadata heading and match on a line
prefix rather than a substring. A file with no Metadata heading has no
fields, so mv reports the missing Status field instead of editing prose.

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

4.7 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

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

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