Generate project-specific AGENTS.md and rule files

Agents Generator generates a project-specific AGENTS.md and companion rules by analyzing a codebase, supporting full, minimal, update and dry-run modes with package-manager detection, monorepo support, backups, managed blocks, confidence scoring and command validation. It writes or updates AGENTS.md, .agents/rules/, optional platform instruction files and timestamped backups, so it reads detected inputs and proposed outputs first and gets approval before changing target files.

From a project using Bun, Next.js 16, Tailwind, Vitest and Server Actions, it would produce an AGENTS.md with real setup commands (bun install, bun dev, bun run test:run, bun doctor), a verification cycle (bunx tsc --noEmit then lint then test then doctor), and project-specific conventions, alongside .agents/rules/ files for architecture (with an ASCII diagram of real directories and exact versions), frontend patterns, server actions (naming the actual function and type names it found), testing (citing the real test count), git workflow and spec-driven-development workflow - while explicitly not generating rules for stacks the project doesn't have, such as a backend or database file with no NestJS or ORM present.

Mode selection follows what the user asks for: minimal produces a single ~30-line AGENTS.md with no rule files; full produces AGENTS.md plus .agents/rules/*.md and is the default; update diffs the existing files against the current stack and regenerates only what changed; and dry-run runs full detection without writing anything, showing the detection summary, the files that would be created, skipped rules and a sample of the output.

Use it when a project's agent instructions should come from the actual codebase rather than a generic template, and especially after the stack changes. Do not use it to invent conventions without inspecting the target project, to overwrite instructions outside the user's intended scope, or to treat its generated guidance as a substitute for human review. Generated instructions are proposals requiring human review; command validation only covers what's visible in the project and cannot prove a command works in every environment; and documenting a project script does not authorize running it.

Its hard rules: read before writing, but never read secrets - it reads package.json, non-secret config and directory structure, but never opens .env, .env.local or credential stores, deriving environment-variable names only from .env.example placeholders or process.env.NAME references in source, never their values; detect the package manager first from its lockfile (bun.lock, pnpm-lock.yaml, package-lock.json, yarn.lock) and never default to npm; generate only what applies, skipping backend or database rules when there's no backend or ORM; never execute project scripts by default, only detecting and documenting candidate format/lint commands for the user to review and separately authorize; validate that every command in the output exists as a real package.json script key; scan for and reject any leftover placeholder text ({{, TODO, add here, ...); and back up any existing files to .agents/backups/ with a timestamp before overwriting.

Its execution steps: find the project root via git rev-parse --show-toplevel, detect the package manager, read package.json and non-secret config, then branch by mode. Full mode reads a full AGENTS.md template covering 25+ sections and fills every placeholder with real project data, wraps the generated content in <!-- AGENTS-GENERATED-START/END --> markers, generates a matching rule file per applicable category, and conditionally generates a thin CLAUDE.md or platform-specific instruction files if those are detected. Minimal mode reads a 30-line standard template and writes a single file. Update mode backs up, re-detects project state, and regenerates only the categories that changed. Post-generation, it reports detected format/lint commands as unexecuted candidates, re-scans for placeholders, re-verifies every command against package.json scripts, warns if AGENTS.md exceeds 300 lines (and recommends moving content to rule files past 500), and summarizes all changes in conventional-commit format alongside a detection/generation/skip report and a confidence score.

Beyond AGENTS.md (which it treats as the universal standard), it writes a platform file only for a tool it detects in the project: .cursorrules for Cursor, .github/copilot-instructions.md for GitHub Copilot, GEMINI.md for Gemini CLI, .windsurfrules for Windsurf, and a thin CLAUDE.md that just points back to AGENTS.md for Claude Code. Each file is written in the style of its tool: Cursor gets progressive disclosure with severity levels and BAD/GOOD code examples, Copilot a short flat file because of its limited context window, Gemini a second-person system-prompt style, and Windsurf progressive disclosure with cascade rules. Codex needs no separate file, since it natively supports AGENTS.md; opencode is a listed tool that gets no platform file of its own.

It suits teams who want an AI agent's project instructions to match their actual toolchain and conventions rather than a generic placeholder template.