# Advent of Code Rust Agent Guidelines

## Workflow

### Problem Solving Process
1. **Read & Analyze**: Read puzzle description from `data/puzzles/<day>.md`
2. **Add Example Input**: Copy example from puzzle into `data/examples/<day>.txt`
3. **Implement Part 1**:
   - Write solution in `src/bin/<day>.rs`
   - Update test assertion with expected example output
   - Run `cargo test --bin <day>` to verify
4. **Test & Submit Part 1**:
   - Run `cargo solve <day> --release` to get answer
   - Submit with `cargo solve <day> --release --submit 1`
5. **Download Part 2**: Run `cargo download <day>` to fetch Part 2 description
6. **Implement Part 2**:
   - Add solution to `part_two()` function
   - Update test assertion
   - Run `cargo test --bin <day>` to verify
7. **Test & Submit Part 2**:
   - Run `cargo solve <day> --release` 
   - Submit with `cargo solve <day> --release --submit 2`
8. **Cleanup**: Run `cargo fmt && cargo clippy --bin <day>` to ensure code quality
9. **Commit**: Commit solution using conventional commits format
    - `<type>[optional scope]: <description>`, where types include: `fix:`, `feat:`, `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.

### Git Workflow
- **Commit Format**: `feat(day<NN>): solve part 1 and 2` or `feat(day<NN>): solve part 1`
- **Commit After**: Complete solutions (both parts if possible) with tests passing
- **Message Examples**:
  - `feat(day01): solve part 1 and 2`
  - `feat(day02): solve part 1`
  - `refactor(day01): optimize solution performance`
  - `docs: update AGENTS.md with workflow`

## Commands
- **Run Solution**: `cargo solve <day>` (e.g., `cargo solve 01`). Use `--release` for optimized builds.
- **Submit Solution**: `cargo solve <day> --release --submit <part>` (auto-submits via aoc-cli)
- **Scaffold Day**: `cargo scaffold <day>` to generate `src/bin/<day>.rs` and input files.
- **Download Puzzle**: `cargo download <day>` to fetch puzzle description and input.
- **Test**: `cargo test` runs all tests. To test a specific day: `cargo test --bin <day>`.
- **Lint & Format**: Always run `cargo clippy` and `cargo fmt` before finishing a task.

## Code Style & Conventions
- **Formatting**: Strictly follow `rustfmt` defaults.
- **Naming**: `snake_case` for functions/variables, `PascalCase` for structs/enums/traits.
- **Error Handling**: Prefer `Result` propagation (`?`) over `unwrap()`. Handle errors gracefully.
- **Structure**: Solutions reside in `src/bin/`. Shared logic goes in `src/lib.rs` or modules.
- **Imports**: Group standard library, external crates, and internal modules separately.
- **Performance**: This is AoC; prioritize correctness first, then optimization (zero-cost abstractions).
- **Return Types**: Use appropriate types (`u32`, `u64`, `i32`, etc.) based on problem constraints.
- **Comments**: Add comments for complex algorithms or non-obvious logic.