# 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 ### CLI Arguments - The prose arguments carry `allow_hyphen_values`, via the `PROSE` constant in `command.rs`: `add --title`, `--description`, `--acceptance`, `--plan`, and the `comment` body. Ticket text quotes flag names constantly, and without it a criterion reading `--print is supported` is parsed as a flag and the whole ticket is refused with nothing written - **The trade:** on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why `due`, `priority`, `tags`, `owner` and `status` are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add `PROSE` to a new argument unless it holds prose - The ticket positionals (`show `, `mv `, `comment `) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title` - A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop - `add` has no positionals, so anything after a bare `--` is an unexpected argument and fails ### 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 - `quiet_broken_pipe()` runs first in `main`, restoring the default `SIGPIPE` disposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of making `println!` panic. Do not wrap prints to handle write errors and do not reinstate `SIG_IGN`; the exit codes are documented in the README ### 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_ordered`, `content_trim_colored`) handle markdown formatting - `show` renders the Metadata section as a two column table via `render_metadata_table`, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process - The title is printed once, by `cmd_show`. `content_trim_colored` skips the `# ` heading in the file content - Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes - `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`, 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