Files
worklane/AGENTS.md
T
2026-05-15 13:10:38 +02:00

2.8 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 (90)
  • 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

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