agent-directives

Central source of truth for agentic-coding conventions shared across projects, one subdirectory per stack:

stacks/
└── example-stack/
    └── AGENTS.md

Each stacks/<name>/AGENTS.md is shared directives in the plain-markdown agents.md format that Claude Code, Codex CLI, Cursor, Aider, Copilot, Windsurf, and others all read natively. No import/include syntax exists in that standard, so this file must be self-contained — consuming projects generate their own final AGENTS.md by concatenating a stack's file with their project-specific additions (see below), rather than referencing it.

Add a new stack by creating stacks/<new-name>/AGENTS.md.

Consuming: directives (AGENTS.md)

Other coding tools don't understand @import — they just read AGENTS.md as plain text. So each project generates a single, fully-inlined AGENTS.md at its root by combining the relevant stack's file with its own additions. No submodule: sync-agents-md.sh fetches the pinned ref straight from this repo's git remote at run time, into a throwaway temp clone.

1. Copy sync-agents-md.sh into your project once (e.g. scripts/sync-agents-md.sh). The repo URL is already hardcoded in it.

2. Create .agent-shared-version at the project root, pinning a ref and which stack applies:

   v1.0.0 stacks/example-stack
   

3. Write project-specific additions in AGENTS.project.md at the project root (optional — omit if none).

4. Generate the real AGENTS.md:

   scripts/sync-agents-md.sh

   This commits nothing itself; commit the generated AGENTS.md yourself — it's the file every tool actually reads, so it must exist in the repo, not just be generated on demand. If CLAUDE.md doesn't exist yet, the script creates one containing @AGENTS.md; if it already exists, it's left untouched so any Claude-specific additions you've added stay put.

Re-run scripts/sync-agents-md.sh and commit the result whenever AGENTS.project.md changes, or after bumping the ref in .agent-shared-version:

# edit .agent-shared-version to the new tag, then:
scripts/sync-agents-md.sh
git add .agent-shared-version AGENTS.md
git commit -m "bump agent-directives to <new-tag>"

Versioning

Tag releases (git tag v1.1.0) so consuming projects can pin the ref in .agent-shared-version to a specific tag instead of tracking a moving branch.