Priority lived in tags, as p1 to p3, which ls could neither sort nor filter on, nothing validated, and a typo like P1 passed silently. ls sorted by title only, so a backlog of any size gave no ordering signal. Levels are 1 to 5 with 1 most urgent, matching what the tags meant. Omitting the flag leaves the field _Not set_, like Due and Owner: there is no implicit middle level, because a priority nobody chose is worse than none. clap rejects anything outside the range before a ticket is written. Priority parses to three states rather than two. A stored value outside the range is Invalid, kept distinct from Unset, so a typo cannot read as "no priority": it shows as ? and sorts just ahead of the unset tail. ls sorts on priority and falls back to the old title sort, and --priority filters, composing with the status filter in both the grouped and the filtered listing. TicketItem becomes a struct, since a sixth tuple field was past reading. Migrated the 31 tickets already carrying p1 to p3 tags: the level moves to the field and the tag is dropped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
75 lines
4.2 KiB
Markdown
75 lines
4.2 KiB
Markdown
# 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)
|
|
- 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
|