By name: rules-manager
description: Create and maintain agent rules in AGENTS.md and .agents/rules/. Use for project rules, conventions, constraints, rule indexes, or requests to add or optimize agent rules.
argument-hint: "[init | add | optimize | task description]"
Two-tier system:
- AGENTS.md — Always loaded. Acts as the index + universal rules.
- .agents/rules/*.md — Modular rule files for focused topics (changelog, testing, deployment, etc.).
CRITICAL invariant: Every file in .agents/rules/ must be referenced in AGENTS.md so agents know it exists. AGENTS.md without a reference = orphaned rule = invisible to agents.
project-root/
├── AGENTS.md # Index + universal rules (always loaded)
└── .agents/
└── rules/
├── changelog.md # Rule for changelog management
├── testing.md # Rule for tests
└── deployment.md # Rule for deployment
AGENTS.md must contain a ## Rules section listing each .agents/rules/*.md file with a one-line description.
# Project Name
Short description (1-2 lines).
## Tech Stack
- [Non-obvious tech only]
## Commands
- `[dev]` - Dev server
- `[test]` - Run tests
## Rules
The detailed rules live in `.agents/rules/`. Read the relevant file before acting:
- **Changelog** - [.agents/rules/changelog.md](.agents/rules/changelog.md) - When/how to update CHANGELOG.md
- **Testing** - [.agents/rules/testing.md](.agents/rules/testing.md) - Test conventions and coverage
- **Deployment** - [.agents/rules/deployment.md](.agents/rules/deployment.md) - Deploy checklist
## Universal Rules
- [2-3 critical rules that apply everywhere]
The ## Rules section is the index. Each bullet = one file in .agents/rules/. The ## Universal Rules section holds short, project-wide constraints that don't deserve their own file.
# [Rule Title]
Short purpose statement (1 line).
## When this applies
- [Specific triggers - what task/context loads this rule]
## Rules
- [Specific, actionable rule]
- [Another rule with example if format matters]
## Example
[3-5 line concrete example, only if needed]
Size target: 20-60 lines per rule file. If longer, split into multiple files.
NO: "Update changelog properly"
YES: "Append entry to CHANGELOG.md under ## Unreleased before every PR. Format: - [type] description (#PR)"
Prohibitions beat positive guidance:
NO: "Try to write tests"
YES: "NEVER merge without a passing test for the changed behavior"
Emphasis hierarchy: CRITICAL > NEVER > ALWAYS > IMPORTANT
- Lead each section with the most critical rule
- Use bold + keyword for non-negotiables:
**CRITICAL**: Never commit secrets
Do NOT include:
- Generic best practices ("write clean code", "DRY", "SOLID")
- Linter-enforced rules (ESLint, Prettier, Biome already do this)
- Things the agent discovers from the code (file structure, framework defaults)
- Marketing or vision statements
- Verbose paragraphs - one line is almost always enough
/rules-manager init - Bootstrap AGENTS.md + .agents/rules/
When the argument contains init:
- Detect project context - Read
package.jsonor equivalent for name, stack, scripts. - Check existing files - If
AGENTS.mdor.agents/rules/already exists, read them and ASK before overwriting. - Create skeleton - Write AGENTS.md with empty
## Rulesindex, ready to populate. - Create
.agents/rules/directory - Empty for now. New rules added viaaddworkflow.
Target AGENTS.md size at init: under 40 lines.
/rules-manager add <name> - Add a new rule
When the argument starts with add:
- Confirm name - Slugify (e.g., "changelog management" ->
changelog). Ask user if unclear. - Read existing AGENTS.md - Confirm it exists. If not, run
initfirst. - Ask the user for rule content - What does the rule enforce? When does it apply? Any examples?
- Write
.agents/rules/<name>.md- Use the rule file template. Keep it 20-60 lines. - Update AGENTS.md
## Rulessection - Add a one-line bullet pointing to the new file:- **<Title>** - [.agents/rules/<name>.md](.agents/rules/<name>.md) - <one-line purpose> - Verify the link - Make sure the path in AGENTS.md exactly matches the created file.
CRITICAL: Step 5 is non-negotiable. A rule file without an index entry is invisible.
/rules-manager optimize - Audit and clean up
When the argument contains optimize:
- Inventory - List AGENTS.md and every file in
.agents/rules/. - Check the index - For each file in
.agents/rules/, verify there's a matching bullet in AGENTS.md## Rules. Flag missing entries. - Check for orphans - For each AGENTS.md bullet, verify the file exists. Flag broken links.
- Apply bloat removal - For each rule file, remove:
- Linter-enforced rules
- Generic best practices
- Verbose explanations (compress to one line)
- Things derivable from code
- Compress - Paragraphs to bullets, multi-line rules to single lines.
- Show diff and ask before applying.
Target sizes:
- AGENTS.md: under 80 lines
- Each rule file: under 60 lines
Default - Add a rule based on description
When the argument is a free-form task (e.g., "add a rule about how we tag releases"):
- Treat as
addwith auto-derived name. - Ask the user 1-2 clarifying questions if the rule scope is unclear.
- Follow the
addworkflow.
- ALWAYS update AGENTS.md
## Rulesindex when creating a file in.agents/rules/ - NEVER create a rule file without confirming with the user what it should contain
- NEVER overwrite existing AGENTS.md or rule files without asking
- Default to short rule files (20-60 lines). Split if larger.
- When user asks "create a rule", default to creating a file in
.agents/rules/(not inline in AGENTS.md), unless the rule is 1-2 lines and fits the universal section.
- Examples: references/examples.md - Sample rule files (changelog, testing, deployment)
- AGENTS.md vs CLAUDE.md: references/agents-vs-claude.md - When to use which format