Records the rule in the Git Workflow section: decide whether a change warrants a bump, ask before making one, no bump for docs, tests or fixups, and bump once on the final commit when work spans several. Docs only, so no bump for this one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
72 lines
3.7 KiB
Markdown
72 lines
3.7 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`, `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
|
|
|
|
### Color Guideline
|
|
- UUID → red (31)
|
|
- Status → orange (33)
|
|
- Timestamp → cyan (36)
|
|
- Title → green (32)
|
|
- Unknown values (`_None_`, `_Not set_`) → grey (90)
|
|
|
|
### 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
|
|
- `worklane --version` reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another
|