From 4c11d779a7aef1088b3a866bd68ff8da1e947c54 Mon Sep 17 00:00:00 2001
From: Moises Valero <261577890+moisesvalero@users.noreply.github.com>
Date: Fri, 19 Jun 2026 15:23:53 +0200
Subject: [PATCH 1/2] docs: add agentchecker to agent instruction tools

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 8204dac5..39cc1d96 100644
--- a/README.md
+++ b/README.md
@@ -318,6 +318,10 @@ By adding selected `.mdc` files to `.cursor/rules/`, you can use these rules dir
 - [How-To Documentation](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/how-to-documentation-cursorrules-prompt-file.mdc) - Task-oriented guides and procedural documentation.
 - [README Best Practices](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/readme-best-practices-cursorrules-prompt-file.mdc) - README documentation with best practices integration.
 
+### Agent instruction tools
+
+- [agentchecker](https://github.com/moisesvalero/agentchecker) - CLI (`npx agentchecker`) that detects and fixes contradictions between `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, and GitHub Copilot instructions.
+
 ## Directories
 
 - [CursorList](https://cursorlist.com)

From f9b843a81bb764fc859db6fb842f27de24dc9fd3 Mon Sep 17 00:00:00 2001
From: Moises Valero <261577890+moisesvalero@users.noreply.github.com>
Date: Sun, 21 Jun 2026 21:42:54 +0200
Subject: [PATCH 2/2] docs: add agent instruction alignment rule for
 agentchecker

---
 README.md                                     |  4 --
 ...tion-alignment-cursorrules-prompt-file.mdc | 40 +++++++++++++++++++
 2 files changed, 40 insertions(+), 4 deletions(-)
 create mode 100644 rules/agent-instruction-alignment-cursorrules-prompt-file.mdc

diff --git a/README.md b/README.md
index 39cc1d96..8204dac5 100644
--- a/README.md
+++ b/README.md
@@ -318,10 +318,6 @@ By adding selected `.mdc` files to `.cursor/rules/`, you can use these rules dir
 - [How-To Documentation](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/how-to-documentation-cursorrules-prompt-file.mdc) - Task-oriented guides and procedural documentation.
 - [README Best Practices](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/readme-best-practices-cursorrules-prompt-file.mdc) - README documentation with best practices integration.
 
-### Agent instruction tools
-
-- [agentchecker](https://github.com/moisesvalero/agentchecker) - CLI (`npx agentchecker`) that detects and fixes contradictions between `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, and GitHub Copilot instructions.
-
 ## Directories
 
 - [CursorList](https://cursorlist.com)
diff --git a/rules/agent-instruction-alignment-cursorrules-prompt-file.mdc b/rules/agent-instruction-alignment-cursorrules-prompt-file.mdc
new file mode 100644
index 00000000..ffcd7b8a
--- /dev/null
+++ b/rules/agent-instruction-alignment-cursorrules-prompt-file.mdc
@@ -0,0 +1,40 @@
+---
+description: "Cursor rules for keeping AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions aligned across AI coding tools."
+globs: AGENTS.md,**/AGENTS.md,CLAUDE.md,**/.claude/CLAUDE.md,.github/copilot-instructions.md,.cursor/rules/**.mdc
+alwaysApply: false
+---
+
+# Agent instruction alignment
+
+When editing any agent instruction file in this repository, keep stack and workflow decisions consistent across all surfaces.
+
+## Canonical sources
+
+Treat `AGENTS.md` as the project-wide contract for humans and shared agents. Mirror its decisions in:
+
+- `.cursor/rules/*.mdc` for Cursor
+- `CLAUDE.md` or `.claude/CLAUDE.md` for Claude Code
+- `.github/copilot-instructions.md` for GitHub Copilot
+
+## Keep these fields aligned
+
+- Package manager (pnpm, npm, yarn, bun)
+- Linter and formatter (oxlint vs eslint, prettier vs biome)
+- Test runner and type checker
+- Runtime version constraints
+- Shell and environment expectations
+- Commit and comment conventions
+
+## Editing workflow
+
+1. Pick one source of truth (usually `AGENTS.md`).
+2. When changing stack or tooling rules, update every agent file in the same PR.
+3. Use identical wording for critical constraints (for example "never use npm").
+4. Run `npx agentchecker` before opening a PR to detect drift.
+5. Use `npx agentchecker --check-only` in CI to block contradictory merges.
+
+## Anti-patterns
+
+- Adding tool-specific exceptions without documenting them in all files
+- Duplicating long prose — link to `AGENTS.md` instead
+- Leaving stale instructions after migrating tooling