This file provides guidance to AI Agents when working with code in this repository.
IMPORTANT: This project uses trx for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other trackers.
Check ready work:
trx readyCreate new issues:
trx create "Issue title" -t bug|feature|task|epic|chore -p 0-4Claim and update:
trx update <id> --status in_progress
trx update <id> --priority 1Complete work:
trx close <id> -r "Completed"- Check ready work:
trx ready - Claim task:
trx update <id> --status in_progress - Implement + test
- If new follow-up work appears: create a new trx issue and reference parent in description
- Complete:
trx close <id> -r "Done" - Commit tracking metadata with code: include
.trx/changes in the same commit
- ✅ Use trx for all tracking
- ✅ Update status as you work (
open->in_progress->closed) - ✅ Keep
.trx/committed with related code changes - ❌ Do not create markdown TODO trackers
- ❌ Do not use parallel tracking systems
NEVER PUBLISH TO PACKAGE REPOSITORIES WITHOUT EXPLICIT PERMISSION: Under no circumstances should you publish any packages to cargo/homebrew/npm or any other public registry without explicit permission from the user. This is a critical security and trust boundary that must never be crossed.
No Backwards Compatibility: We never care about backwards compatibility. We prioritize clean, modern code and user experience over maintaining legacy support. Breaking changes are acceptable and expected as the project evolves. This includes removing deprecated code, changing APIs freely, and not supporting legacy formats or approaches.
No "Modern" or Version Suffixes: When refactoring, never use names like "Modern", "New", "V2", etc. Simply refactor the existing things in place. If we are doing a refactor, we want to replace the old implementation completely, not create parallel versions. Use the idiomatic name that the API should have.
Strong Typing Over Type Erasure: We strongly prefer type-safe code over type-erased patterns. Avoid using AnyCodable, [String: Any], AnyObject, or similar type-erased containers. Instead:
- Use enums with associated values for heterogeneous types
- Create specific types for data structures
- Use generics where appropriate
- Prefer compile-time type checking over runtime casting
Cross-Platform compatibility: This project targets Windows 11, Linux and macOS 14.0 (Sonoma) and later. Do not add availability checks for macOS versions below 14.0.
File Headers: Use minimal file headers without author attribution or creation dates:
- Omit "Created by" comments and dates to keep headers clean and focused
In the crate folder where the rust code lives:
- Crate names are prefixed with xtr-. For example, the core folder's crate is named xtr-core
- When using format! and you can inline variables into {}, always do that.
- Install any commands the repo relies on (for example just, rg, or cargo-insta) if they aren't already available before running instructions here.
- Always collapse if statements per https://rust-lang.github.io/rust-clippy/master/index.html#collapsible_if
- Always inline format! args when possible per https://rust-lang.github.io/rust-clippy/master/index.html#uninlined_format_args
- Use method references over closures when possible per https://rust-lang.github.io/rust-clippy/master/index.html#redundant_closure_for_method_calls
- When writing tests, prefer comparing the equality of entire objects over fields one by one.
Run just fmt automatically after making Rust code changes; do not ask for approval to run it. Before finalizing a change to xtr, run just fix -p (in the root directory) to fix any linter issues in the code. Prefer scoping with -p to avoid slow workspace‑wide Clippy builds; only run just fix without -p if you changed shared crates. Additionally, run the tests:
- Run the test for the specific project that was changed. For example, if changes were made in xtr-cli, run cargo test -p xtr-cli.
- Once those pass, if any changes were made in common, core, or protocol, run the complete test suite with cargo test --all-features. When running interactively, ask the user before running just fix to finalize. just fmt does not require approval. project-specific or individual tests can be run without asking the user, but do ask the user before running the complete test suite.
What to Look For:
-
Common Agent Mistakes:
- Missing required parameters or incorrect parameter usage
- Misunderstanding of command syntax or options
- Attempting unsupported operations
- Confusion about tool capabilities or limitations
-
Actual Bugs:
- Crashes, errors, or unexpected behavior
- Missing functionality that should exist
- Performance issues or timeouts
- Inconsistent behavior across similar commands
-
UX Improvements:
- Unclear error messages that could be more helpful
- Missing hints or suggestions when agents make mistakes
- Opportunities to add guardrails or validation
- Places where agents get stuck in loops or retry patterns
-
Missing Features:
- Common operations that require multiple steps but could be simplified
- Patterns where agents work around limitations
- Frequently attempted unsupported commands
How to Analyze:
- Read through the entire log systematically
- Identify patterns of confusion or repeated attempts
- Note any error messages that could be clearer
- Look for places where the agent had to guess or try multiple approaches
- Consider what helpful messages or features would have prevented issues
Output Format:
- List specific bugs found with reproduction steps
- Suggest concrete improvements to error messages
- Recommend new features or commands based on agent behavior
- Propose additions to system/tool prompts to guide future agents
- Prioritize fixes by impact on agent experience
Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
Awesome CLIs (adhere to these rules when applicable):
Design & UX • Prefer subcommands for verbs (tool add, tool list) and keep each one focused. • Be composable: read from stdin, write to stdout, errors to stderr, use clear exit codes. • Ship sensible defaults; require as few flags as possible. • Destructive ops: provide --dry-run, prompt only on TTY, support --yes/--force. • Errors that teach: show cause + fix, suggest near-miss flags/values.
Help & Discoverability • Fast -h/--help with one-liners; rich help with examples. • --version prints semver; note deprecations. • Offer completions generator (tool completions bash|zsh|fish|powershell) and man page/README snippet.
I/O & Formats • Human output by default; machine output via --json/--yaml (stable schema). • Respect NO_COLOR/FORCE_COLOR; auto-disable color when not a TTY. • Verbosity controls: -q/--quiet, stackable -v, --debug, --trace. • Progress bars/spinners only on TTY; provide --no-progress.
Config & Environment • Clear precedence: flags > env > config file. • Use XDG dirs on Unix; sensible Windows paths; --config PATH. • config init, config show (effective config with sources).
Performance & Reliability • Fast startup; lazy-load heavy parts. • Timeouts & retries where networked; --parallel N, --timeout. • Idempotent behavior; --keep-going and --fail-fast.
Security & Privacy • Never print secrets by default; mask in logs (--redact). • Support secrets via env/secret stores; avoid writing to shell history (suggest ENV_VAR=… tool …).
Packaging & Distribution • Cross-platform builds; reproducible releases; signed artifacts. • Easy install paths (Homebrew/Scoop/AUR/pkg managers) or single static binary. • Optional self-update and gentle version-checks (opt-out env).
Observability & Testing • Logs to stderr with timestamps on --debug/--trace. • --profile to show timing breakdowns. • Golden tests for text output; schema tests for JSON; fuzz your flag parser.
Accessibility & Internationalization • Avoid ASCII art; provide --no-emoji. • High-contrast, monochrome-friendly output. • English fallback; locale-aware messages (if you localize).
Standard Flag Kit (copy these across subcommands)
-h, --help · -V, --version · -q, --quiet · -v (stackable) · --debug · --trace · --json/--yaml · --no-color (and honor NO_COLOR) · --dry-run · -y, --yes/--force · --config PATH · --no-progress · --timeout SEC · --parallel N
Bonus power moves • Context-aware help (suggest flags based on partial input). • Interactive wizards (init, login) gated behind TTY; pure flags otherwise. • Plugin system: discover commands from $PATH like tool-foo → tool foo. • Generate shell completions dynamically from your parser so help & completion never drift.