cybara AGENTS.md

Cybara Agent Rules

Rules for any AI agent or contributor working in this repo. Follow them exactly; they override default habits. Deeper conventions live in CLAUDE.md.

Package Manager Policy (Strict)

• Bun is the only allowed JavaScript/TypeScript package manager and task runner.
• Always use Bun commands:
  • bun install
  • bun add <pkg>
  • bun remove <pkg>
  • bun run <script>
  • bun test
  • bunx <tool>
• Never use npm, npx, pnpm, yarn, or corepack.
• Treat bun.lock as the canonical lockfile.
• Prefer Bun-native APIs (Bun.spawn/Bun.spawnSync, Bun.file) over child_process/fs shell-outs.

Command Translation

• If docs or snippets mention npm-style commands, translate them to Bun equivalents before running.
• If a third-party instruction cannot run with Bun, stop and propose a Bun-compatible alternative.

TypeScript Type Safety

• Never use any — not in signatures, casts, generics, or as any. It is banned.
• Model real shapes with interface/type. For genuinely unknown input use unknown and narrow it before use (type guards, discriminated unions).
• Type every exported function's parameters and return value explicitly. Do not rely on inference across module boundaries.
• Avoid non-null assertions (!). Handle null/undefined with ?. and ??.
• No @ts-ignore / @ts-expect-error to silence real errors — fix the type instead. If a third-party type is missing, declare a local interface for the slice you use.
• Keep functions and route handlers returning consistent, fully-typed API shapes (snake_case fields for HTTP responses — see CLAUDE.md).

No Comments

• Write code with no comments. Names and structure carry the meaning.
• Do not add header blocks, JSDoc, inline // notes, or commented-out code.
• Never reference other products, competitors, or external projects anywhere in code or comments.
• The rare exception is a short /* ... */ note only when logic is genuinely non-obvious and cannot be made clear by renaming or restructuring; default to none.