# Agent Notes

> Concise operating instructions for autonomous work in this repo. Keep this file small so it fits into small-LLM context windows and remains useful for agents with limited token budgets.

## Project phase

Bootstrap. Intelligent machine-vision system for real-time defect detection on polyurethane shoe soles. Full context is in `docs/project_context.md`.

Before adding substantial code, pick and document the tech stack in `README.md` and create the matching manifest (e.g. `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`).

## Autonomous work rules

- Do not mutate git history (`git reset`, `rebase`, `push --force`) unless explicitly asked.
- Do not create pull requests, push commits, or change git remotes unless explicitly asked.
- Keep changes minimal and focused on the task at hand.
- Prefer editing existing files over creating new ones when it satisfies the requirement.
- Ask the user before deleting files, directories, or significant blocks of code.
- If a task is unclear or ambiguous, pause and ask for clarification instead of guessing.

## Context management for small LLMs

- Read `docs/project_context.md` at the start of each autonomous task.
- Before editing, read only the files directly related to the change. Avoid dumping large unrelated files into context.
- When touching multiple files, process them one logical step at a time and run verification after each step.
- Summarize long outputs before storing or returning them. Do not paste large logs verbatim unless specifically requested.
- If a command output is large, prefer to save it to a file and return a summary with the file path.

## Adding code

- Follow the style and conventions of the existing codebase once code exists.
- Add or update tests for new logic and run them before finishing.
- Do not commit secrets, credentials, large binaries, or generated build artifacts.
- Use dependency manifests and lockfiles; avoid global installs without user confirmation.
- If the project is Python, keep a virtual environment inside the workspace and do not install into the system Python.
- Prefer small, focused functions and modules. Avoid huge files that do not fit into small context windows.

## Documentation

- Update `README.md` when the stack, setup steps, or major architecture changes.
- Keep project documentation in `docs/`. Add design docs, API specs, runbooks, and ADRs there, not in `README.md`.
- Update `AGENTS.md` when repo-specific commands, conventions, testing quirks, or environment setup change.
- Write docstrings / comments only for non-obvious behavior; do not add noise.

## Verification habit

- Before declaring a task done, run the relevant check: tests, lint, typecheck, or build.
- If a check does not exist yet, state that it should be added rather than skipping verification.
- Record verification commands and results in the response so the user can reproduce them quickly.