From 13f9a0b4942c98f565ef41580b4034f6099b6dca Mon Sep 17 00:00:00 2001
From: Emil <emil28092005@gmail.com>
Date: Wed, 22 Jul 2026 21:34:11 +0300
Subject: [PATCH] Add repository contributor guidelines

---
 AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..031f60d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+SciMesh is a Python package for local molecular-similarity workloads. Source
+lives in `scimesh/`: `chemistry/` reads data and makes fingerprints,
+`workloads/` contains commands, and `core/` provides the workload protocol and
+registry. The worker daemon in `scimesh/worker/` is a coordinator client, not a
+database client. Tests live in `tests/`; task specifications in `docs/`; the
+roadmap is `PLAN.md`.
+
+## Build, Test, and Development Commands
+
+Create a virtual environment, install the package with development tools, and
+run the suite:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+Use `pytest tests/test_similarity_graph.py` to focus on one module. Exercise
+the public CLI with `scimesh help` or `scimesh similarity-search --help`.
+Run `python -m build` only when packaging is needed; install `build` first if
+it is not available.
+
+## Coding Style & Naming Conventions
+
+Target Python 3.10+ and use type hints for public functions, protocols, and
+data exchanged between modules. Use four spaces, `snake_case` for modules,
+functions, and variables, `PascalCase` for classes, and descriptive test names
+such as `test_graph_is_deterministic_across_block_sizes`. Keep CLI parsing in
+workload modules and register new workloads through `scimesh/core/registry.py`;
+do not add workload-specific logic to the main CLI.
+
+Prefer small standard-library dependencies. RDKit is the chemistry dependency.
+For worker/coordinator work, keep network payloads explicit and multi-line;
+never make the worker access PostgreSQL directly.
+
+## Testing Guidelines
+
+Use pytest and add a regression test for every defect. Similarity code must be
+checked against a small brute-force or fully sorted reference. Graph results
+must be deterministic, have no self-loops or duplicate pairs, and remain
+stable for different block sizes. Worker changes need success and failure
+tests: checksum mismatch, lease failure, upload failure, and safe reporting.
+Run the full `pytest` suite before committing.
+
+## Commit & Pull Request Guidelines
+
+Use short imperative commit subjects, for example `Add graph threshold mode` or
+`Fix worker result and lease contracts`. Keep one logical change per commit.
+In a pull request, state the problem, behaviour changed, tests run, and any API
+or documentation changes. Link the relevant `CTX-*` item in `PLAN.md` for
+distributed work. Do not commit datasets, generated CSV/PNG files, `.venv/`,
+tokens, or local worker artifacts.
+
+## Security & Protocol Rules
+
+Upload worker results through the coordinator before posting completion; never
+submit `file://` or `worker://` result URIs. Send failures to `/failure`, not
+`/result`. Do not log bearer tokens, raw tracebacks, or private local paths.