---
name: agent-guidance-factory
description: >-
  Create, refresh, audit, or migrate repository agent guidance files such as
  AGENTS.md, AGENTS.override.md, CLAUDE.md, .claude/rules, and Cursor rules.
  Use when a repo needs durable coding-agent instructions, instruction
  load-order decisions, nested guidance, or cleanup of bloated or stale agent
  docs. Do not use for ordinary human README or CONTRIBUTING docs unless they
  must feed agent guidance.
---

# Agent Guidance Factory

Create source-controlled instructions that coding agents actually load and can
follow. These files guide behavior; they do not replace linters, hooks, tests,
permissions, or other enforcement.

Read `references/agent-guidance-files.md` before creating, migrating, or
materially changing `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or
`.cursor/rules/`.

## Route

1. Identify the target agents and existing surfaces. Prefer portable
   `AGENTS.md` for shared repository guidance. Use `CLAUDE.md` only for
   Claude Code-specific behavior, and Cursor rules when structured metadata,
   glob attachment, or Team/User/Project rule behavior is required.
2. Choose scope deliberately: root for every task in the repo, nested files for
   subtrees with different commands or constraints, and override files only
   when the target agent documents that override behavior.
3. Inspect the repo before writing: root layout, build/test/lint scripts, CI,
   docs, config, existing guidance files, PR templates, and recent commit
   messages. Verify commands from source files rather than inventing them.
4. Write concise, directive Markdown. Include only durable facts and workflows
   that matter in most relevant sessions: layout, exact commands, coding
   conventions, test expectations, security/configuration boundaries, review
   expectations, and completion proof.
5. Keep hot guidance small. Include repo evidence only when it changes an
   agent action, boundary, command, style rule, test rule, or contribution
   workflow. Move long procedures, architecture notes, release runbooks, and
   rare variants into linked docs or skills.
6. Preserve and reconcile existing rules. If instructions conflict, stop and
   ask unless source evidence makes one rule clearly stale.
7. Validate with the repo's normal checks and any agent-specific visibility
   proof that is cheap and safe for the current host.
8. For monorepos, many guidance files, or density/scale work, use the scale
   pipeline in `references/agent-guidance-files.md` before editing.

## Content Rules

- Use repository-relative paths and portable commands.
- Keep repository-facing text English and ASCII unless the file already has a
  clear different character set.
- Do not include secrets, private project names, personal names, local absolute
  paths, credentials, live tokens, or unverified service details.
- Do not promise automatic enforcement. Point to scripts, hooks, CI, tests, or
  review gates when a rule must be enforced.
- Add a rule after repeated agent mistakes, recurring review feedback, or a
  stable project convention that a new contributor would need.
- Remove stale guidance when commands, frameworks, ownership, or release flows
  change.

## Suggested Sections

Use only sections supported by evidence from the repository:

- Repository Map
- Build, Test, And Dev Commands
- Coding Style And Naming
- Testing And Verification
- Security And Configuration
- Git, Review, And Completion Rules
- Agent-Specific Notes

## Report

State the guidance files changed, why that scope was chosen, which source facts
were verified, which checks ran, whether any agent visibility was verified, and
what remains intentionally out of scope.