agent-policy

Vendor-neutral CLI to keep AI coding-agent instruction files in sync and enforce commit attribution.

Why this exists

AI coding tools read different repository instruction files: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and more over time. Maintainers end up hand-editing three near-duplicate documents, or worse, one goes stale and the agents that rely on it quietly drift.

Separately, when AI assists with a commit, attribution is inconsistent or absent. Which model? Which prompt? Was this human-only or hybrid? You cannot audit what you do not record.

agent-policy solves both with one small tool:

• One canonical agent-policy.yaml is the source of truth.
• Generators produce AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md deterministically.
• A git commit-msg hook enforces an Assisted-by: footer with a simple, machine-readable format.

Install

npm install -g @47nation/agent-policy

Or run ad hoc:

npx @47nation/agent-policy init

Quick start

# 1. Scaffold the canonical config
agent-policy init

# 2. Edit agent-policy.yaml (sections, attribution, renderer paths)

# 3. Generate the instruction files
agent-policy sync

# 4. Install the commit-msg hook (one time per clone)
agent-policy install-hooks

# 5. Commit with attribution
git commit -m "feat: add widget

Assisted-by: claude:opus-4-7"

Example config

version: 1

project:
  name: my-repo

policy:
  sections:
    - id: overview
      title: Overview
      body: |
        Describe what this repo does.

attribution:
  assisted_by:
    required: true

renderers:
  agents_md:
    enabled: true
  claude_md:
    enabled: true
    concise: true
  copilot_instructions:
    enabled: true
    concise: true

See examples/full/agent-policy.yaml for a realistic example with section targeting and every option.

Example generated output

From examples/full/AGENTS.md:

<!-- Generated by agent-policy. Do not edit directly. Edit agent-policy.yaml instead. -->
<!-- agent-policy:hash=1c57397774466302 -->

# full-example

A realistic agent-policy config that exercises every renderer and every attribution option.

## Project overview

This repo is a worked example of an agent-policy setup...

Every generated file carries the banner and a content hash, so tooling can tell "user edited the generated file" apart from "policy changed."

Example commit attribution

Valid:

feat: add widget

Assisted-by: claude:opus-4-7

feat: hybrid

Assisted-by: claude:opus-4-7
Assisted-by: copilot:v1

chore: rename variable

Assisted-by: n/a

Invalid (hook blocks the commit):

fix: something

Assisted-by: just-an-agent-no-model-version

Commands

| Command | Purpose | |---|---| | agent-policy init | Scaffold agent-policy.yaml | | agent-policy validate | Parse and schema-validate the config | | agent-policy render | Render to stdout (useful for diff review) | | agent-policy sync | Render all enabled renderers to disk | | agent-policy sync --check | Drift-check for CI (exit 1 on drift) | | agent-policy check-commit <file> | Validate a commit message file | | agent-policy install-hooks | Install the commit-msg hook |

See docs/commands.md for flags and exit codes.

Claude Code integration (47nation)

A companion Claude Code plugin lives under integrations/claude-code/47nation/. It provides slash commands (/agent-policy:init, /agent-policy:sync, /agent-policy:check, /agent-policy:render) and a skill that teaches Claude the commit-attribution convention for your repo.

See docs/claude-code-integration.md for install instructions.

Development

git clone https://github.com/V-ivek/agent-policy
cd agent-policy
npm install
npm test          # vitest (68+ tests)
npm run typecheck # tsc --noEmit
npm run lint      # eslint
npm run build     # bundle to dist/cli.js

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md for dev setup and how to add a new renderer.

License

MIT — see LICENSE.