agent-prompts-warmup

Agent Prompts Warmup

Agent instruction files ensure every coding agent (Claude Code, Codex, Copilot, Cursor, Gemini, Windsurf/Anti-Gravity) reads the same project rules when working on this codebase.

Architecture

Single source of truth: AGENTS.md

All other files are copies, synced automatically:

File	Agent(s)
AGENTS.md	Codex CLI, GitHub Copilot (source of truth)
CLAUDE.md	Claude Code
GEMINI.md	Gemini CLI, Jules, Anti-Gravity
.cursorrules	Cursor
.windsurfrules	Windsurf / Anti-Gravity (legacy)

Sync mechanisms (4 layers):

1. scripts/postbuild.mjs — npm run build copies AGENTS.md → all targets
2. scripts/pre-commit — git hook blocks commit if any file has drifted
3. tests/integration/agent-docs-consistency.test.ts — npm test fails on drift
4. CI — GitHub Actions runs npm test on push/PR to main

When To Use This Skill

1. FRE Audit (first run in a new clone/worktree)

Run a full scaffolding check:

/agent-prompts-warmup audit

Checklist to verify:

• AGENTS.md exists and is non-empty
• All target files exist: CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules
• All targets are byte-identical to AGENTS.md (diff -q)
• scripts/postbuild.mjs has cpSync lines for all targets
• tests/integration/agent-docs-consistency.test.ts tests all targets
• scripts/pre-commit exists and checks all targets
• .git/hooks/pre-commit is installed and executable (run npm run prepare if not)
• package.json files field includes AGENTS.md, CLAUDE.md, GEMINI.md, docs
• package.json has "prepare" script that installs the hook

If anything fails: fix it immediately. The fix is usually npm run build (syncs files) or npm run prepare (installs hook).

2. After Editing Instructions

When the user edits AGENTS.md (or asks you to):

1. Edit only AGENTS.md — never edit the copies directly
2. Run sync: node scripts/postbuild.mjs (or npm run build)
3. Verify: npm test -- tests/integration/agent-docs-consistency.test.ts
4. Confirm all 5 files are identical

3. Adding a New Agent Target

When a new coding agent emerges that reads a different file:

1. Identify the file name the agent reads (e.g., .devinrules, CLINE.md)
2. Update scripts/postbuild.mjs — add cpSync("AGENTS.md", "<new-file>");
3. Update tests/integration/agent-docs-consistency.test.ts — add expect(readFileSync("<new-file>", "utf-8")).toBe(agents);
4. Update scripts/pre-commit — add the new file to the TARGETS array
5. Create the file: cp AGENTS.md <new-file>
6. If it should be npm-published: add to package.json files array
7. Run npm test to verify
8. Update this skill's mapping table above

Troubleshooting

"ERROR: CLAUDE.md has drifted from AGENTS.md" → Someone edited a copy instead of AGENTS.md. Fix: cp AGENTS.md CLAUDE.md (or whichever file drifted). Then check if the edit in the copy should be applied — if so, edit AGENTS.md first, then npm run build.

Pre-commit hook not running → npm run prepare to reinstall. Or manually: cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

CI failing on agent docs → npm run build && npm test locally. If it passes locally but fails in CI, check that the build step runs before test in the workflow.

Current Mapping Reference

// scripts/postbuild.mjs
cpSync("AGENTS.md", "CLAUDE.md");       // Claude Code
cpSync("AGENTS.md", "GEMINI.md");       // Gemini CLI / Jules / Anti-Gravity
cpSync("AGENTS.md", ".cursorrules");    // Cursor
cpSync("AGENTS.md", ".windsurfrules"); // Windsurf / Anti-Gravity (legacy)