Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (49 loc) · 3.46 KB

AGENTS.md

File metadata and controls

58 lines (49 loc) · 3.46 KB

Agent Playbook

This repository is optimised for collaboration with human developers and code-generating agents. Follow the checklist below to keep contributions consistent and automation-friendly.

1. Discoverability

  • Read docs/index.d.ts first. It lists every exported symbol with use cases, performance notes, and import paths.
  • Use src/index.ts for ESM imports. Category folders mirror the sections in the type definitions (procedural, spatial, ai, etc.).
  • Examples in examples/ show runnable TypeScript snippets for quick verification.
  • Find open work in ROADMAP.md (milestones + checklists) and on the GitHub issue tracker. treat unchecked roadmap items or open issues as the authoritative task list; confirm scope with the current milestone before starting.

2. Contribution Workflow

  1. Create a feature branch (feature/<topic>).
  2. For each feature/fix:
    • Implement runtime code in src/<category>/.
    • Update docs/index.d.ts with the same structure (description, “Use for”, performance, import path).
    • Add or update tests in tests/ (Vitest) and, when applicable, a runnable example in examples/.
  • Update documentation touchpoints (README.md, PROJECT_DESCRIPTION.md, ROADMAP.md) if scope or roadmap changes.
    • Mark relevant roadmap checkboxes and reference/close GitHub issues when tasks are delivered.
  1. Run the full quality gate before committing: 
    npm run lint
npm run typecheck
npm test
npm run build
  2. Commit changes atomically with descriptive messages (e.g., feat: add behaviour tree module).
  3. Open a pull request targeting main.

3. Development Principles

  • YAGNI: deliver only what is needed for the active milestone or issue.
  • DRY: centralise shared utilities/configuration; avoid copy/paste implementations.
  • SOLID: keep modules cohesive with clear responsibilities and exported APIs.
  • Assert + guard: assert internal invariants, validate external inputs, and surface friendly errors.
  • Clear boundary: consumers interact through src/index.ts exports and the contract documented in docs/index.d.ts.
  • Prefer early returns/guard clauses for readability.
  • Keep functions small and well named; comment only when additional context adds value.
  • Ship tests alongside code changes and ensure CI passes before merging.
  • Use readable fixtures and golden files when they clarify behaviour.

4. Coding Guidelines

  • Use modern TypeScript, strict typing, and keep functions pure when possible.
  • Provide rich JSDoc (description, “Useful for” line, typed params/returns, runnable @examples).
  • Default to ASCII and keep comments concise.
  • Prefer options objects for functions with more than three parameters.
  • Handle edge cases gracefully; expose internal helpers through __internals only when needed for testing.

5. Testing Philosophy

  • Every new algorithm must ship with unit coverage exercising typical and edge scenarios.
  • When randomness is involved, use deterministic seeding to keep tests reproducible.
  • Example snippets should run without external dependencies (Node 18+).

6. LLM-Friendly Design

  • Maintain consistent naming and file structure so LLMs can map docs/index.d.ts descriptions to actual implementations.
  • Provide narrative comments only for non-obvious logic; avoid redundant remarks.
  • Keep exports centralised in src/index.ts to simplify import instructions in prompts.

Following this playbook keeps the codebase predictable for both humans and automated agents.