# poe2-agent
Rust library for AI-driven Path of Exile 2 build analysis. Published on crates.io as `poe2-agent`. Provides a ReAct-style tool-calling agent that answers questions about PoB builds via headless Lua integration.
## For Agents: Start Here
1. **Load `/project`** — Understand the project structure
2. **Load `/tickets`** — Understand how to find and complete work
3. **Check `.project/backlog/`** — Find your next task
## Project Structure
```
poe2-agent/
├── CLAUDE.md # You are here
├── .project/ # Tickets, systems, research
├── src/ # Library crate (core modules)
├── build-agent/ # Multi-step build generator (future)
│ ├── src/ # Agent reasoning logic
│ └── docs/ # Design docs, prompts, domain knowledge
├── vendor/ # PathOfBuilding-PoE2 (gitignored)
└── .claude/skills/ # Slash command definitions
```
This is one of three sibling repos:
| `poe2-agent` | AI agents for build analysis (this repo) |
| `poe2-build-helper` | Web application (uses this crate as a dependency) |
| `poe2-pob` | Path of Building web fork (future) |
## Module Structure
| `agent` | ReAct tool-calling agent loop (streams `AgentEvent` tokens/actions) |
| `llm` | OpenAI Responses API client (blocking and streaming) |
| `pob_parser` | Thread-safe PoB parser (runs `pob` on a dedicated OS thread) |
| `pob` | Path of Building 2 headless Lua VM integration |
| `query_agent` | Single-turn build Q&A agent (legacy, superseded by `agent`) |
| `knowledge` | Pre-summarized game mechanics for LLM prompt context |
| `wiki` | PoE2 wiki data fetcher with filesystem caching |
## Agentic SDLC Workflow
Every non-trivial feature follows this pipeline:
```
ticket → specs.md → plan.md → implement
```
| **Ticket** | *What* and *why* (product) | Goal, context, tasks, acceptance criteria |
| **specs.md** | *Exact contracts* (design) | DB schema, API shapes, error codes, edge cases, config |
| **plan.md** | *Implementation order* (exec) | Which files to touch, in what sequence, how to break into commits |
| **Implement** | *Code* (delivery) | Write code, tests, docs per the spec and plan |
- **Ticket** = don't over-detail; keep it product-level.
- **Specs** = where you catch design mistakes cheaply. Nail down schemas, response shapes, error handling, and edge cases *before* writing code.
- **Plan** = sequence the work, identify files, spot dependencies.
- **Implement** = write production-quality code per the spec. No stubs, no TODOs.
## Tech-Debt Log
Tracked in `.project/tech-debt.md`. Every conscious quality tradeoff — shortcuts, deferred cleanup, known fragility — gets logged there.
### When to write an entry
- You knowingly skip proper error handling, use a stub, or hardcode a value to ship faster
- You notice existing debt while working in an area (log it even if you don't fix it)
- A spec or plan forces a simpler-than-ideal solution due to scope constraints
Do **not** create a backlog ticket for debt — that's what the log is for. Tickets are for features and bugs; the debt log captures architectural regret.
### Entry format
```markdown
## [Short title]
- **Location:** `src/module.rs:42` (or module name if broad)
- **Debt:** What is suboptimal and why it matters
- **Reason incurred:** Why the tradeoff was made (time, complexity, unknowns)
- **Impact:** What degrades or breaks if this is never addressed
- **Priority:** low | medium | high
- **Logged:** YYYY-MM-DD
```
### When to consult it
- Before planning work in a module — check if existing debt affects your approach
- During `/finalize-ticket` — add any debt incurred or discovered during the ticket
- When something unexpectedly breaks — the debt log may explain why
## Coding Standards
- Rust 2021 edition, one concern per module
- `thiserror` for library errors, `anyhow` for application glue
- `tracing` for logging (never `println!`)
- Document public APIs
- BDD-style tests where applicable (Given/When/Then, fakes over mocks)
- Run `just precommit` before every commit (fmt check, clippy, tests)
- **Prefer finished, production-quality solutions over intermediate "get it working" code.** Agent labour is cheap; confusion from half-done implementations is not. Write robust, scalable code as if it's the final version — proper error handling, clean interfaces, real implementations instead of stubs or TODOs.
## Key Architecture Patterns
**ReAct agent loop** (`agent.rs`): User question → LLM (with tool definitions) → tool calls or text response → execute tools via PobParser → append results → loop until final answer.
**Thread-safe PoB** (`pob_parser.rs`): mlua's Lua VM is `!Send`, so `PobParser` runs it on a dedicated OS thread and communicates via channels. Consumers get a thread-safe async interface.
**Streaming**: Agent yields `AgentEvent::Token(string)` for streamed text and `AgentEvent::ToolCall { name }` for progress indication.
## Environment
```bash
# Required
export OPENAI_API_KEY="sk-..."
# PoB2 (if not already cloned)
git clone https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2.git vendor/PathOfBuilding-PoE2
```
## Skills Available
| `/project` | At the start of a session, before doing any work |
| `/tickets` | Before picking up, creating, or modifying tickets |
| `/finalize-ticket` | After completing any ticket — before moving on to the next task |
## Quick Reference
| `.project/backlog/` | Pending tickets (work to do) |
| `.project/done/` | Completed tickets |
| `.project/systems/` | Component state + improvement ideas |
| `.project/research/` | Investigation notes |
| `.project/tech-debt.md` | Known quality tradeoffs to revisit |
| `build-agent/docs/` | Agent design + domain knowledge |