ruleprobe: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working on the RuleProbe codebase.

RuleProbe verifies whether agents follow instruction files. This file is the instruction file for agents working on RuleProbe itself. It is parsed by RuleProbe in the self-check workflow, so every rule below is written to be machine-verifiable.

Project

• Repository: https://github.com/moonrunnerkc/ruleprobe
• Package: https://www.npmjs.com/package/ruleprobe
• Language: TypeScript (strict)
• Runtime: Node.js >= 18
• License: MIT

Build and Test

• Use npm as the package manager. Do not switch to pnpm, yarn, or bun.
• Use vitest as the test runner. Do not introduce jest or mocha.
• Run npm test before declaring any change complete.
• Run npm run build to verify the TypeScript compile is clean.
• A package-lock.json must exist at the repo root.
• Pinned dependency versions are required in package.json (no ^ or ~ ranges).

Code Style

• Use TypeScript strict mode. Never disable strict checks.
• Never use any. Use unknown and narrow, or define a precise type.
• Always use named exports. Never use default exports.
• Use camelCase for variables and functions.
• Use PascalCase for types, interfaces, and classes.
• Use kebab-case for filenames.
• Prefer const over let.
• Prefer interface over type for object shapes.
• Prefer async/await over .then() chains.
• Never use console.log in production code. Use the structured logger.
• Never use eval.
• No magic numbers without a named constant or inline comment justifying the value.
• No em dashes anywhere in source, comments, docs, or commit messages. Use commas, colons, semicolons, parentheses, or separate sentences.
• Files must stay under 300 lines. If a file approaches the limit, decompose it.
• Add full JSDoc to every exported function, class, and type.
• Avoid nested ternaries. Use early returns to flatten control flow.

Architecture Boundaries

• Parser code lives under src/parser/. Do not call verifier code from the parser.
• Verifier engines live under src/verifiers/. Each engine exports a single entrypoint that returns VerificationResult[].
• The semantic tier lives under src/semantic/. Source code must never leave the user's machine. Only numeric AST vectors, opaque sub-tree hashes, boolean flags, and rule text may be sent to an LLM.
• The CLI lives under src/cli/. Commands compose pipeline functions; they do not contain pipeline logic.
• Shared types live under src/types/. Do not duplicate type definitions across modules.