voronoi_click

Imported from ztuit/voronoi_click (AGENTS.md). Install upstream with npx 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 ls or 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.json for TypeScript, Pipfile/poetry.lock for Python, composer.json for PHP, build.gradle for Java/Kotlin, Cargo.toml for Rust.
• Check hidden config: .editorconfig, .prettierrc*, .eslintrc*, .ruff.toml, .flake8, .golangci.yml, .stylelintrc*.
• Inspect CI: .github/workflows/*.yml, azure-pipelines.yml, circle.yml, appveyor.yml to mirror commands locally.
• If Docker present, read Dockerfile and docker-compose*.yml for 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> or vitest 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 sudo unless 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 build in CI.
• If Dockerfile present, build with docker build -t <app>:local . and run tests inside if CI mirrors it.
• For this project: use ./build.sh build to build the Docker image, ./build.sh run to start on port 8080, or docker 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.example if 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 lint or pnpm lint; fall back to eslint ., rome check, biome check.
• Formatting: npm run fmt, pnpm fmt, prettier . --check, prettier . --write only when directed.
• Python linting defaults: ruff check ., flake8, pylint; formatting: ruff format . or black ..
• 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, --passWithNoTests not by default).
• For integration/e2e: look for playwright, cypress, selenium, k6, locust scripts.
• Seed data or fixtures: check README, docs/, or scripts/ 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-each or --retries only when configured; avoid hiding failures.

Runtime/env expectations

• Node: prefer .nvmrc, .node-version, engines field; use matching version via nvm/fnm/asdf.
• Python: respect .python-version, pyproject.toml requires-python; use uv, poetry, pipenv, or venv.
• Java: honor java.version in pom.xml/gradle.properties; use sdkman if needed.
• Rust: honor rust-toolchain.toml; use rustup to set toolchain.
• Go: respect go version in go.mod; avoid downgrading modules.
• Keep .env files local; never commit secrets; prefer .env.example updates 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; avoid require unless 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 .editorconfig if 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": true in TS, mypy --strict in Python, go vet, cargo clippy).
• Handle null/undefined explicitly; avoid any and 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 with is/has/should.
• Constants: SCREAMING_SNAKE_CASE for immutable values; PascalCase for types/classes; camelCase for variables/functions.
• Files: match exported default where applicable (userService.ts exporting userService); tests mirror source path with .test/.spec.
• Components: React/Vue/Svelte components in PascalCase; hooks prefixed use.
• 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 status before 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.md when 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.example to 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 .cursorrules absent); keep this noted until they appear.
• No GitHub Copilot instructions file found (.github/copilot-instructions.md absent).
• Agents should re-run discovery regularly and refresh this document when project files arrive.