# AGENTS.md

Guidelines for AI agents working in this Advent of Code repository.

## Project Overview

Gleam-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.

## Commands

```console
$ gleam build           # Compile the project
$ gleam test            # Run all tests
$ gleam run             # Run all available days with comparison (default)
$ gleam run -- <day>    # Run specific day with comparison
$ gleam run -- -e       # Run with example input (--example)
$ gleam run -- <day> -n # Run without comparison, mine/ only (--no-compare)
$ gleam run -- 1 -en    # Flags can be combined
```

## Code Organization

```
src/
├── aoc.gleam            # CLI entry point, argument parsing, day dispatch
├── compare.gleam        # Benchmarking harness for mine/ vs llm/ comparison
├── utils.gleam          # Input file reading utilities
└── internal/
    ├── mine/            # Human-written solutions
    └── llm/             # LLM-generated solutions

input/
├── dayXX.txt            # Real puzzle input
└── dayXX_example.txt    # Example input from problem description

test/
└── aoc_test.gleam       # Tests for both implementations
```

## Documentation

When making changes that affect CLI usage, project structure, or workflows, update the relevant documentation (this file and README.md) to reflect those changes.

## Adding a New Day

1. 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`.
2. 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.
3. 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`.
4. Wire up dispatch in `src/aoc.gleam`:
   - Add import: `import internal/mine/dayXX as mine_dayXX`
   - Add case to `run_parts`
5. Wire up comparison in `src/compare.gleam`:
   - Add imports for both implementations
   - Add `pub fn dayXX(input: List(String)) -> Nil` function
   - Add case to `run_comparison` in aoc.gleam
6. Add the day number to `available_days` in `src/aoc.gleam`
7. Add tests in `test/aoc_test.gleam`

## Conventions

- Naming: `mine_dayXX` and `llm_dayXX` for imports to distinguish implementations
- Types: Define custom types for domain concepts (Movement, Rotation, etc.)
- Constants: Use module-level `const` for magic numbers (e.g., `const starting_position = 50`)
- Pipeline style: Heavy use of `|>` operator for data transformation