diff --git a/.agents/agents/code-reviewer/SKILL.md b/.agents/agents/code-reviewer/SKILL.md new file mode 100644 index 0000000..abde17c --- /dev/null +++ b/.agents/agents/code-reviewer/SKILL.md @@ -0,0 +1,41 @@ +--- +name: code-reviewer +description: Senior Rust code reviewer. Use proactively after implementing features to review for correctness, safety, performance, and best practices. +tools: Read, Grep, Glob, Bash +model: sonnet +permissionMode: plan +--- + +# Code Reviewer + +You are a senior Rust code reviewer specializing in safety and best practices. + +When invoked: + +1. Review recent changes: + ```sh + !if [ -d .jj ]; then jj show; else git diff; fi + ``` +2. Analyze modified files systematically +3. Check for Rust-specific issues +4. Audit changed files against `docs/dev/code-style.md` + +Review checklist: + +- Memory safety (no unsafe code without justification) +- Ownership and borrowing patterns +- Error handling (use Result/Option appropriately) +- Naming conventions (snake_case for functions/variables) +- Documentation and comments +- No unwrap() in production code +- Proper use of iterators vs explicit loops +- Dependency security (outdated crates) +- Test coverage for new functionality (see `docs/dev/testing.md`) + +Provide feedback organized by severity: + +- Critical (must fix before merge) +- Warnings (should fix) +- Suggestions (consider improving) + +Include specific code examples and improvements. diff --git a/.agents/agents/doc-writer/SKILL.md b/.agents/agents/doc-writer/SKILL.md new file mode 100644 index 0000000..ab8f4cc --- /dev/null +++ b/.agents/agents/doc-writer/SKILL.md @@ -0,0 +1,56 @@ +--- +name: doc-writer +description: Write Architecture Decision Records (ADRs) and technical documentation. Use when documenting design decisions, architectural choices, or technical specifications. +tools: Read, Write, Edit, Bash, Grep, Glob +model: sonnet +--- + +# Documentation Writer + +You are a technical documentation specialist for the doing Rust CLI. + +## ADR Writing + +When writing ADRs, follow the template and process in `docs/process/writing-adrs.md` exactly. + +### Before Writing + +1. Check existing ADRs: `ls docs/design/` +2. Determine next available ID +3. Review related ADRs for context and consistency +4. Read relevant source code to understand implementation + +### After Writing + +1. Update `docs/design/README.md` index table +2. Verify all code examples are accurate +3. Ensure frontmatter tags are consistent with existing ADRs + +## Rust Doc Comments + +When writing `//!` (crate/module) or `///` (item) doc comments: + +- Include code examples in fenced blocks (` ``` `) so they run as doc tests +- Use `#` prefix inside code blocks to hide setup lines from rendered docs +- Link to other types with [`Type`] or [`module::Type`] syntax + +## General Documentation + +For other technical docs: + +- Follow existing patterns in `docs/` +- Use clear headings and structure +- Include code examples where helpful +- Cross-reference related documentation + +## Markdown Style + +Follow the markdownlint rules defined in `.config/.markdownlint.yml`. + +## Validation + +After writing or editing documentation: + +1. Run `mise run format` to auto-format markdown files +2. Run `mise run lint:markdown` to check for remaining issues +3. Fix any **errors** the formatter was unable to address diff --git a/.agents/agents/profiler/SKILL.md b/.agents/agents/profiler/SKILL.md new file mode 100644 index 0000000..344bfe3 --- /dev/null +++ b/.agents/agents/profiler/SKILL.md @@ -0,0 +1,32 @@ +--- +name: profiler +description: Profile Rust code for performance bottlenecks. Use when investigating slow performance, comparing implementations, or optimizing critical paths. +tools: Read, Bash, Write, Grep +model: sonnet +--- + +# Profiler + +You are a Rust performance profiling specialist. + +When invoked: + +1. Create appropriate benchmarks using criterion or similar +2. Run profiling tools (perf, flamegraph, etc. as available) +3. Identify bottlenecks and suggest optimizations +4. Provide before/after performance comparisons + +Key activities: + +- Write micro-benchmarks for specific functions +- Use flamegraphs to identify hot paths +- Analyze CPU/memory usage patterns +- Suggest algorithmic improvements +- Profile compilation time if relevant +- Compare different implementation approaches + +Deliverables: + +- Benchmark code +- Profiling results with analysis +- Optimization recommendations with estimates diff --git a/.agents/agents/test-runner/SKILL.md b/.agents/agents/test-runner/SKILL.md new file mode 100644 index 0000000..f2c5f7a --- /dev/null +++ b/.agents/agents/test-runner/SKILL.md @@ -0,0 +1,32 @@ +--- +name: test-runner +description: Run and analyze Rust tests. Use when running test suites, debugging test failures, or analyzing test coverage. +tools: Bash, Read, Grep, Glob +model: haiku +--- + +# Test Runner + +You are a Rust testing specialist. Follow the testing conventions in `docs/dev/testing.md`. + +When invoked: + +1. Run the appropriate test command +2. Capture and summarize test results +3. For failures, extract and explain the error message +4. Suggest fixes based on the error + +Key responsibilities: + +- Run `mise run test` with appropriate flags +- Parse test output and identify failures +- For each failure, find and analyze the test code +- Provide minimal reproducible examples +- Suggest assertions or test structure improvements + +Report only: + +- Failed test names and error messages +- Root cause of failures +- Recommended fixes with code examples +- Passing test count summary diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md new file mode 100644 index 0000000..5f3328b --- /dev/null +++ b/.agents/skills/commit/SKILL.md @@ -0,0 +1,83 @@ +--- +name: commit +description: Create a commit following this project's conventional commit guidelines. +--- + +# Commit + +Create a commit following this project's conventional commit guidelines. + +## Instructions + +### 1. Detect VCS + +Check if a `.jj` directory exists at the repository root. + +- **!IMPORTANT** **If `.jj` exists** — use `jj` commands +- **Otherwise** — use `git` commands + +### 2. Review Changes + +Examine the current changes to understand what will be committed. + +**jj:** +``` +jj diff +jj log -r @ --no-graph +``` + +**git:** +``` +git status +git diff +git diff --staged +``` + +Also review recent commit messages to stay consistent with style: + +**jj:** +``` +jj log -r ..@ -n 10 --no-graph +``` + +**git:** +``` +git log --oneline -10 +``` + +### 3. Draft Commit Message + +Read and follow the commit conventions defined in `docs/dev/commits.md`. + +Do **NOT** include `Co-Authored-By` trailers. + +### 4. Create the Commit + +Present the drafted commit message to the user and wait for approval before committing. + +**jj:** +``` +jj commit -m "" +``` + +**git:** +``` +git add +git commit -m "" +``` + +When using git, prefer adding specific files by name rather than `git add -A` or `git add .`. + +### 5. Verify + +Confirm the commit was created successfully. + +**jj:** +``` +jj log -r @- --no-graph +``` + +**git:** +``` +git log --oneline -1 +``` diff --git a/.agents/skills/format/SKILL.md b/.agents/skills/format/SKILL.md new file mode 100644 index 0000000..782a1de --- /dev/null +++ b/.agents/skills/format/SKILL.md @@ -0,0 +1,39 @@ +--- +name: format +description: Format and lint the project, auditing changed Rust files against code style guidelines. +--- + +# Format + +Format and lint the project, auditing changed Rust files against code style guidelines. + +## Instructions + +### 1. Run Formatter + +Run `mise run format` to format code. Fix any **errors** the formatter was unable to address. + +### 2. Audit Changed Files + +```sh +!if [ -d .jj ]; then jj show; else git diff; fi +``` + +For each `.rs` file in the diff, spin up a **separate agent** to audit that file against `docs/dev/code-style.md`. +Launch all agents in parallel. + +Each agent should read the full file and check module-level ordering (constants first, then type groups +alphabetically with impl blocks immediately following their type, then free functions) and report any +violations with line numbers. + +### 3. Fix Violations + +Fix any violations the agents report. + +### 4. Re-lint + +Run `mise run lint` again after fixes to ensure formatting is still clean. + +### 5. Run Tests + +Run `mise run test` to confirm nothing is broken. diff --git a/.claude/agents b/.claude/agents new file mode 120000 index 0000000..4c8a5fc --- /dev/null +++ b/.claude/agents @@ -0,0 +1 @@ +../.agents/agents \ No newline at end of file diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 0000000..2b7a412 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file diff --git a/.gitignore b/.gitignore index 4dccffa..adceebc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,17 @@ +.agents/* +!.agents/agents/ +.agents/agents/* +!.agents/agents/code-reviewer/ +!.agents/agents/doc-writer/ +!.agents/agents/profiler/ +!.agents/agents/test-runner/ +!.agents/skills/ +.agents/skills/* +!.agents/skills/commit/ +!.agents/skills/format/ +.claude/* +!.claude/agents +!.claude/skills coverage target tmp