1# AGENTS.md
 2
 3Guidelines for AI agents working in this Advent of Code repository.
 4
 5## Project Overview
 6
 7Gleam-based Advent of Code solutions with two parallel implementation tracks (`mine/` and `llm/`) for comparing human vs LLM-generated solutions side-by-side with benchmarking.
 8
 9## Commands
10
11```console
12$ gleam build           # Compile the project
13$ gleam test            # Run all tests
14$ gleam run             # Run all available days with comparison (default)
15$ gleam run -- <day>    # Run specific day with comparison
16$ gleam run -- -e       # Run with example input (--example)
17$ gleam run -- <day> -n # Run without comparison, mine/ only (--no-compare)
18$ gleam run -- 1 -en    # Flags can be combined
19```
20
21## Code Organization
22
23```
24src/
25├── aoc.gleam            # CLI entry point, argument parsing, day dispatch
26├── compare.gleam        # Benchmarking harness for mine/ vs llm/ comparison
27├── utils.gleam          # Input file reading utilities
28└── internal/
29    ├── mine/            # Human-written solutions
30    └── llm/             # LLM-generated solutions
31
32input/
33├── dayXX.txt            # Real puzzle input
34└── dayXX_example.txt    # Example input from problem description
35
36test/
37└── aoc_test.gleam       # Tests for both implementations
38```
39
40## Documentation
41
42When making changes that affect CLI usage, project structure, or workflows, update the relevant documentation (this file and README.md) to reflect those changes.
43
44## Adding a New Day
45
461. Create `src/internal/mine/dayXX.gleam` with `pub fn part1(input: List(String)) -> Int` and `pub fn part2(input: List(String)) -> Int` and bodies of just `todo`.
472. Create `src/internal/llm/dayXX.gleam` with the same interface. Make sure to include the `//// Authored-by: [Model] via Crush` header that you're told to use for commits.
483. Ask the user to paste the input for `input/dayXX_example.txt`, then download the contents of `https://adventofcode.com/2025/day/XX/input` to `input/dayXX.txt`.
494. Wire up dispatch in `src/aoc.gleam`:
50   - Add import: `import internal/mine/dayXX as mine_dayXX`
51   - Add case to `run_parts`
525. Wire up comparison in `src/compare.gleam`:
53   - Add imports for both implementations
54   - Add `pub fn dayXX(input: List(String)) -> Nil` function
55   - Add case to `run_comparison` in aoc.gleam
566. Add the day number to `available_days` in `src/aoc.gleam`
577. Add tests in `test/aoc_test.gleam`
58
59## Conventions
60
61- Naming: `mine_dayXX` and `llm_dayXX` for imports to distinguish implementations
62- Types: Define custom types for domain concepts (Movement, Rotation, etc.)
63- Constants: Use module-level `const` for magic numbers (e.g., `const starting_position = 50`)
64- Pipeline style: Heavy use of `|>` operator for data transformation