@projectplaceholders/agent-rules

One document decides how every agent works on this project, and pkit check proves the copies still agree with it.

The problem

Rules for coding agents live in a different file for every tool: CLAUDE.md, .cursor/rules/*.mdc, .github/copilot-instructions.md. Nobody keeps four files in step by hand, so they drift — and the drift has no symptom. Nothing fails when one of them still describes last month's architecture. The agent reads it, believes it, and writes code against a system that no longer exists; the result compiles, lints and passes its tests, because the rule it broke was never in the code to begin with.

How it works

AGENTS.md is the source of truth. Everything else is generated from it and carries a marker with a hash of its own contents:

<!-- pkit:generated from AGENTS.md · hash 09be26936712 · edit AGENTS.md and run `pkit context sync`; changes made here are lost -->

That hash is the whole design. Without it there is only "this file does not match what we would write now", and the two reasons for that need opposite responses:

| The file | The hash | What it means | What sync does | | --- | --- | --- | --- | | differs | matches its body | out of date; nobody touched it | rewrites it | | differs | does not match | somebody edited it by hand | leaves it, and reports it | | differs | absent entirely | the project wrote this file itself | leaves it, and reports it |

A fixer that quietly discards work is one people stop running. So pkit context sync never overwrites an edit unless you ask for it with --force, and pkit check turns red until the edit is either moved into AGENTS.md — where every tool gets it — or thrown away deliberately.

Copies, not pointers

Every adapter holds AGENTS.md verbatim rather than a reference to it. Referencing would be tidier, but only some of these tools resolve a reference to another file, and one that silently fails leaves the agent with no rules — the exact failure this package exists to prevent. A copy can go stale; that is detectable and repairable. Silence is not.

The copy is byte-for-byte the original, block markers and all. Any transform, however small, is a place where the copy can differ from the original without anyone noticing.

Layers

Rules arrive as blocks inside AGENTS.md, each marked <!-- BEGIN:pkit:<id> -->:

• core — always. Run pkit check before reporting done; use pkit map instead of a repo-wide search; where each layer of a feature goes; keep CONTEXT.md current.
• stack-next — only when the project depends on next.

Everything outside the markers belongs to the project and is never touched, including blocks other generators write. Next.js ships its own <!-- BEGIN:nextjs-agent-rules --> block into the same file, and adopting a second generator must not delete the first.

Rules the project does not use are not merely irrelevant. Every line is paid for on every task, and a document with skippable parts teaches the reader to skip.

Commands

pkit context sync            write AGENTS.md, then a copy for every tool
pkit context sync --force    overwrite copies that were edited by hand
pkit check                   fail while any copy disagrees with AGENTS.md

sync exits 1 when it left something alone, because a tool still running on rules nobody chose is not a success.