Files
worklane/AGENTS.md
T
Ansho ReiandClaude Opus 5 3fcb0ddc0a Require a local tag alongside every version bump
Records the rule in the Version Bumps section: a bump carries a matching
annotated v<version> tag on the bump commit, kept local unless a push is
asked for. Tagged v0.1.1 on 8563218 retroactively, which was bumped
before the rule existed.

Docs only, so no bump and no tag for this one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-20 15:01:56 +02:00

3.9 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

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
  • 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