AGENTS.md

The init command for my Claude Code plugin needed a few things to happen in order: run a setup script, ask the user some configuration questions, apply the results. Not complicated. The skill file spelled out each step with code blocks and paths, and the agent understood all of it. Then it went its own way. Sometimes it called the CLI directly, skipping a wrapper script that checks prerequisites and preserves configuration state. Sometimes it finished step one and stopped, summarizing results without continuing. Sometimes it searched for a binary called speckit when the tool is called specify. The pattern was always the same: the agent extracted the intent (“initialize the project”) and chased it through whatever path looked reasonable, treating each instruction as a suggestion to optimize away.

The previous post in The Flock series covered what happens when agents get creative where they shouldn’t. This one covers a more fundamental problem: what happens when agents forget what they were doing, and then confidently make something up.

Every coding agent has its own context file. CLAUDE.md for Claude Code, .cursorrules for Cursor, .github/copilot-instructions.md for Copilot, GEMINI.md for Gemini CLI. If you work with more than one agent, you end up maintaining multiple files with 90% identical content. AGENTS.md is the attempt to end that.