# 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//` directories ## Ticket File Format - Filenames: `_.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//.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`, 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