Imported from ztuit/voronoi_click (
AGENTS.md). Install upstream withnpx skills add ztuit/voronoi_click. Copyright stays with the author.
AGENTS PLAYBOOK Repository state: contains a Voronoi diagram web app (voronoi.html) with Docker build support. Purpose: quick-start for agentic contributors; prefer defaults provided here until project-specific scripts are added. Audience: automated coding agents and human maintainers. Principle: act safely, avoid destructive commands, document any assumptions.
Discovery-first checklist
- Run
lsor use glob to inventory files; avoid destructive commands. - If git appears later, read
README,package.json,pyproject.toml,Makefile,justfile,Cargo.toml,go.mod,Gemfile,mix.exs,requirements.txt. - Note language markers:
tsconfig.jsonfor TypeScript,Pipfile/poetry.lockfor Python,composer.jsonfor PHP,build.gradlefor Java/Kotlin,Cargo.tomlfor Rust. - Check hidden config:
.editorconfig,.prettierrc*,.eslintrc*,.ruff.toml,.flake8,.golangci.yml,.stylelintrc*. - Inspect CI:
.github/workflows/*.yml,azure-pipelines.yml,circle.yml,appveyor.ymlto mirror commands locally. - If Docker present, read
Dockerfileanddocker-compose*.ymlfor services and scripts. - Capture discovered commands and options back into this file.
Tooling rules
- Use provided project scripts before raw binaries; prefer
npm run <task>,pnpm,bun,yarn,poetry run,uv run,pipx,go run,cargo. - When unsure, run
npm test -- --runInBand --watch=false(JS),pytest -q(Python),go test ./...(Go),cargo test(Rust),bundle exec rspec(Ruby) as provisional defaults. - For single test in Jest/Vitest:
npm test -- <pattern>orvitest run <pattern>. - For single test in pytest:
pytest path/to/test_file.py::TestClass::test_name. - For Go single test:
go test ./... -run TestName. - For Rust single test:
cargo test test_name -- --nocapture. - Avoid
sudounless explicitly documented; prefer local tools. - Log command outputs succinctly; avoid dumping thousands of lines unless asked.
Build commands (update once project exists)
- Primary build: try project script order:
npm run build,pnpm build,bun run build,yarn build,go build ./...,cargo build,make build. - Production bundle checks: check for
npm run lint && npm run test && npm run buildin CI. - If
Dockerfilepresent, build withdocker build -t <app>:local .and run tests inside if CI mirrors it. - For this project: use
./build.sh buildto build the Docker image,./build.sh runto start on port 8080, ordocker compose up -d. - For monorepos, run workspace-aware commands (
pnpm -r,nx,turbo,lage); respect affected-only flags if defined. - Capture env vars required for build (API endpoints, feature flags) and use
.env.exampleif present; never invent secrets. - If build requires bootstrapping, look for
npm run prepare,pip install -e .,make deps,just setup. - When build caching exists (
.turbo,nx,bazel), avoid deleting caches unless troubleshooting. - If no build system, document compilation steps per language (e.g.,
tsc -p tsconfig.json,javac).
Lint/format commands (update once project exists)
- Try:
npm run lintorpnpm lint; fall back toeslint .,rome check,biome check. - Formatting:
npm run fmt,pnpm fmt,prettier . --check,prettier . --writeonly when directed. - Python linting defaults:
ruff check .,flake8,pylint; formatting:ruff format .orblack .. - Go:
golangci-lint run,go fmt ./...; Rust:cargo fmt --check,cargo clippy -- -D warnings. - CSS/SCSS:
stylelint "**/*.{css,scss,sass,less}". - If configuration files specify ignore patterns, honor them (e.g.,
.eslintignore,.prettierignore). - Do not auto-fix unless change is intentional; if large diffs, chunk commits logically.
Test commands (update once project exists)
- Preferred order:
npm test,pnpm test,bun test,yarn test,pytest,go test ./...,cargo test. - Single test guidance mirrored above; ensure deterministic flags (
--runInBand,--passWithNoTestsnot by default). - For integration/e2e: look for
playwright,cypress,selenium,k6,locustscripts. - Seed data or fixtures: check
README,docs/, orscripts/directories; do not mutate prod data. - If services required (DB, queue), prefer
docker compose up -d <service>with project-provided compose file. - Capture flaky tests with
--repeat-eachor--retriesonly when configured; avoid hiding failures.
Runtime/env expectations
- Node: prefer
.nvmrc,.node-version,enginesfield; use matching version vianvm/fnm/asdf. - Python: respect
.python-version,pyproject.tomlrequires-python; useuv,poetry,pipenv, orvenv. - Java: honor
java.versioninpom.xml/gradle.properties; usesdkmanif needed. - Rust: honor
rust-toolchain.toml; userustupto set toolchain. - Go: respect
goversion ingo.mod; avoid downgrading modules. - Keep
.envfiles local; never commit secrets; prefer.env.exampleupdates for new variables. - Record required services (Postgres, Redis, MinIO, S3 mocks) and startup commands.
Imports and module layout
- Use absolute imports when project provides base paths; otherwise prefer relative short paths.
- Keep import order: stdlib first, third-party second, internal last; alphabetize within groups when formatter allows.
- Avoid wildcard imports; import explicit symbols; keep tree shaking friendly (ESM).
- In TypeScript/JavaScript, default to ESM
import/export; avoidrequireunless file is CJS. - In Python, avoid relative dot-dot chains; prefer package-level imports; keep
__all__minimal. - Keep side-effect imports isolated (polyfills, global styles) near entrypoints.
- Remove unused imports; rely on linter warnings.
Formatting
- Follow
.editorconfigif present; default to spaces over tabs, newline at EOF. - Prefer Prettier defaults for JS/TS/MD/JSON/YAML unless project overrides.
- Limit line length to 100-120 chars if unspecified; break expressions for readability.
- Keep trailing commas enabled where supported to ease diffs.
- Ensure files end with a newline; keep consistent newline style (LF by default).
- Avoid committing generated artifacts unless project commits them intentionally (lockfiles are ok).
Types and nullability
- Prefer strict typing (
"strict": truein TS,mypy --strictin Python,go vet,cargo clippy). - Handle
null/undefinedexplicitly; avoidanyand casts; wrap unsafe external data with schemas (zod, yup, io-ts, pydantic). - For JSON parsing, define interfaces/models; validate user input and external responses.
- Avoid global mutable state; prefer dependency injection or parameter passing.
- Use discriminated unions over enums where ergonomic; keep DTOs immutable where possible.
- In Python, use
typing/typing_extensions; annotate functions and public attributes; prefer@dataclass(frozen=True)for value objects.
Naming conventions
- Functions/methods: verbs (
fetchUser,calculateTotal); boolean prefixed withis/has/should. - Constants: SCREAMING_SNAKE_CASE for immutable values;
PascalCasefor types/classes;camelCasefor variables/functions. - Files: match exported default where applicable (
userService.tsexportinguserService); tests mirror source path with.test/.spec. - Components: React/Vue/Svelte components in
PascalCase; hooks prefixeduse. - Database migrations: timestamped and descriptive; avoid collisions by using full UTC timestamp.
Error handling
- Fail fast on unexpected states; prefer explicit errors over silent returns.
- Wrap external IO (HTTP, DB, file) with retries/backoff only when required; surface actionable messages.
- Return typed errors or
Result-like structures when language supports; avoid throwing strings. - Log context (ids, parameters) without secrets; scrub PII according to policy.
- In APIs, map internal errors to appropriate HTTP status codes; avoid leaking stack traces in production responses.
- In CLI tools, use clear exit codes; document known failure modes in README or this file.
Testing discipline
- Keep unit tests fast and deterministic; isolate external calls with fakes/mocks.
- Name tests clearly; prefer Arrange-Act-Assert structure.
- For snapshot tests, keep snapshots small; update only after inspecting diffs.
- Add regression tests when fixing bugs; cite issue or scenario in test name.
- Avoid time-based flakiness; use fake timers where supported.
- Track coverage pragmatically; do not chase 100% if not mandated; prioritize critical paths.
Git and change management
- Keep commits scoped and descriptive; avoid mixing refactors with functional changes unless necessary.
- Do not amend others' commits; do not force push unless explicitly required.
- If repo becomes git-tracked, run
git statusbefore edits; avoid touching unrelated dirty files. - Include rationale in commit messages; reference issues when relevant.
- When adding dependencies, justify necessity; prefer smallest viable package; update lockfiles.
- Before PRs, run lint/test/build stack; mirror CI.
- If hooks modify files, re-run tests and include updated artifacts.
Docs and comments
- Update
AGENTS.mdwhen discovering real commands, config, or rules. - Keep comments for non-obvious intent, not obvious mechanics.
- Maintain
README/docs/if present; add ADRs for significant decisions. - Prefer Markdown tables/lists over walls of text for operational runbooks.
- Keep TODOs actionable with owners or issue links.
Security and secrets
- Never commit secrets; scrub tokens and passwords from logs.
- Use
.env.exampleto document new variables; include defaults only when safe. - Verify licenses for new dependencies if policy exists; prefer permissive licenses.
- Validate inputs at boundaries; sanitize user-generated content; escape HTML.
- Keep dependency upgrades minimal; run security scanners if configured (
npm audit,pnpm audit,pip-audit,cargo audit).
Performance
- Measure before optimizing; use profiling tools provided by stack.
- Avoid premature allocation; use streaming/iterators for large data sets.
- Cache results thoughtfully; invalidate on writes; avoid global caches without TTL.
- Prefer async/concurrent patterns where safe; avoid blocking the event loop in JS.
- For databases, batch queries; use prepared statements; monitor N+1 issues.
Operations
- If containers used, tag images clearly; avoid
latest. - Respect migration order; run migrations before app start when required.
- Keep health checks simple and fast; expose readiness vs liveness separately if supported.
- Log levels: DEBUG for development, INFO for normal ops, WARN/ERROR for actionable problems.
- Collect metrics if stack includes them (Prometheus/OpenTelemetry); keep spans cheap.
AI-specific guidance
- No Cursor rules found (
.cursor/rules/or.cursorrulesabsent); keep this noted until they appear. - No GitHub Copilot instructions file found (
.github/copilot-instructions.mdabsent). - Agents should re-run discovery regularly and refresh this document when project files arrive.
