integrations/AGENTS.md

# AGENTS.md

This file provides guidance to coding agents working in this repository.

## Mission

`integrations` is an early-stage repository for integration work across Rust, Python, and Haskell-related research notes.

At the time of writing, the repository is still close to a template scaffold. Some names and files still reflect that origin. Treat the current codebase as incomplete infrastructure unless the user says otherwise.

Priorities, in order:

1. Keep changes aligned with the actual repository state.
2. Prefer small, targeted edits over broad cleanup.
3. Preserve a clear separation between code, tooling, and research notes.
4. Keep documentation factual and easy to scan.

## Current Repository State

- The Rust code lives under `rust/` rather than the usual `src/` layout.
- The repository still contains some scaffold residue, but the main Rust crate naming should match `integrations`.
- `README.md` is minimal and does not define a stable product scope yet.
- `pyproject.toml` sets up a Python environment with `maturin[zig]` and `numpy`.
- `haskell/notes/` contains project review notes.
- `tmp/` contains temporary or inspected repositories and should not be treated as product code unless the user asks for that specifically.

Do not assume the repository is complete or internally consistent.

## Directory Guide

- `rust/`
  - Main Rust sources.
  - Current files include CLI and logging scaffolding.
  - Keep changes here minimal and consistent with the existing file layout unless the user asks for restructuring.

- `haskell/notes/`
  - Notes and reviews of Haskell-related projects or integration experiments.
  - Use `haskell/notes/_template.md` as the default format.
  - Write in a factual review style.

- `tmp/`
  - Scratch space, cloned repos, and inspection targets.
  - Do not treat files here as part of the maintained codebase unless the task explicitly targets them.

- `Makefile`
  - Project convenience commands.
  - Some targets may still reflect template assumptions.

- `.pre-commit-config.yaml`
  - Hook configuration for formatting, linting, and tests.

## Core Rules

- Use English for code, comments, docs, tests, and notes.
- Keep edits scoped to the user request.
- Do not perform broad template cleanup unless the user asks for it.
- Do not remove template residue just because it is present.
- When you find template leftovers, note them if relevant, but do not expand scope without approval.
- Add comments only when they clarify non-obvious behavior.
- Keep documentation factual. Do not use poetic wording or decorative language.

## Rust Conventions

- Target the toolchain in `rust-toolchain.toml`.
- Follow existing lint expectations from the `Makefile`.
- Avoid `unwrap()` and `expect()` in production code unless there is a clear justification.
- Prefer explicit error handling with `Result`.
- Prefer simple APIs and small modules over speculative abstraction.
- Use `tracing` consistently where logging is already part of the flow.

## Python Conventions

- Treat `pyproject.toml` as environment support for the repository, not as proof that a Python application exists.
- Do not add Python dependencies unless the task requires them.
- Keep Python-related changes minimal and tied to integration needs.

## Notes Conventions

Applies to files under `haskell/notes/`:

- Use Title Case for headings.
- Write like a reviewer.
- Keep the tone factual and direct.
- Avoid colorful adjectives and adverbs.
- Prefer short paragraphs and short lists.
- State strengths, weaknesses, and status directly.
- If something is incomplete, fragile, or early, say so plainly.

## Validation

Validate as narrowly as possible.

For Rust changes, prefer the smallest relevant check first. Examples:

1. `cargo test` for the affected crate or module
2. `cargo clippy` if the Rust workspace is in a runnable state
3. `cargo fmt --check` or `cargo fmt`

If the repository is missing required manifests or is otherwise not runnable, do not fix unrelated scaffolding unless the user asks. Report the limitation clearly.

For notes-only changes, no build validation is required.

## Change Design Checklist

Before editing:

1. Confirm whether the target is maintained code, tooling, notes, or scratch material.
2. Check whether the repository state supports validation.
3. Keep the change limited to the stated task.

Before finishing:

1. Verify the requested files were updated.
2. Run targeted validation when it applies.
3. Call out any template residue or missing infrastructure that affects confidence.

## Review Guidance

When reviewing or summarizing work in this repository:

- Focus on correctness, maintainability, and scope control.
- Distinguish between template residue and task-specific issues.
- Do not recommend broad cleanup unless it is required.
- Keep findings concise and factual.

## Practical Notes For Agents

- The current repository is not a finished product. Avoid assumptions about intended architecture.
- `tmp/` is usually for inspection work, not implementation work.
- `haskell/notes/` is part of the maintained repo and should stay consistent in tone and format.
- If the user asks for project-level cleanup, identify template leftovers first and then propose a scoped plan.