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.