agent-policykit detects the stack in a repository, merges governance with language, framework, and project-type rules, and writes the exact instruction files each coding agent expects.

If your repo has Copilot, Cursor, Claude Code, Codex, Aider, or Gemini users, agent-policykit keeps them aligned on the same security, architecture, testing, and review guidance without hand-editing separate prompt files.

Why?

Most teams that adopt AI coding assistants hit the same problem quickly: every tool wants a different file, a different format, and a different maintenance path.

agent-policykit solves that with a compiler-style workflow:

Who it is for

• Engineering teams standardizing AI coding assistants across multiple repositories
• Platform and enablement teams managing secure defaults and review expectations
• Consultancies supporting different clients, stacks, and agent tools
• Open-source maintainers who want contributors using different agents to follow the same repo rules

Quickstart

Install from PyPI:

pip install agent-policykit

Or install the latest version directly from GitHub:

pip install "git+https://github.com/sidrat2612/agent-policykit.git"

CLI

Common CLI commands:

• agent-policykit init detects the stack and writes [tool.agent-policykit] into pyproject.toml.
• agent-policykit generate compiles the merged policy bundle and writes all configured agent files.
• agent-policykit diff previews pending changes before regeneration.
• agent-policykit update refreshes existing generated files while preserving user-owned sections.
• agent-policykit validate checks bundled packs for structural correctness.

Minimal flow:

agent-policykit init
agent-policykit generate
agent-policykit diff
agent-policykit update

Config File

Generated and manual workflows both use the same project config:

[tool.agent-policykit]
targets = ["copilot", "agents-md", "cursor", "claude-code"]
languages = ["python", "typescript"]
frameworks = ["fastapi", "nextjs"]
project_type = "api_service"
review_mode = false

Recommended config shape:

• Set targets to the agent files your repository actually needs.
• Set languages, frameworks, and project_type explicitly when auto-detection is not enough.
• Use review_mode = true or --mode review when you want stricter reviewer behavior in generated instructions.

What Gets Written

agent-policykit writes plain-text instruction files directly into the repository so they can be reviewed, diffed, and committed like any other source-controlled artifact.

Typical outputs include:

This is the core behavior: inspect repo context, compile one policy bundle, then write the file shape each agent actually consumes.

How It Works

agent-policykit is a policy compiler and safe updater. It does not replace your coding agent. It makes the instructions those agents read consistent and maintainable.

Execution flow:

1. Detect languages, frameworks, project type, existing targets, and path-scoped instruction surfaces.
2. Load governance, language, framework, and project-type YAML packs.
3. Merge them into one PolicyBundle using priority rules.
4. Validate IDs, coverage, and structural integrity.
5. Render target-native files through the adapter registry.
6. Diff or update existing files using managed sections and downgrade protection.

What it does

• Detects repository context instead of forcing one generic prompt onto every project
• Compiles YAML rule packs into one merged policy bundle
• Renders native instruction files for Copilot, Claude Code, Cursor, Codex, Aider, Gemini CLI, and compatibility targets
• Generates path-scoped outputs for tools that support scoped instructions
• Preserves user-owned content outside managed sections during updates
• Blocks accidental security-rule removal unless --force is used
• Condenses outputs automatically when target limits require it

What it does NOT do

• Does not call external LLM APIs
• Does not execute code from packs
• Does not replace the execution engine of Copilot, Claude Code, Cursor, Codex, or other agents
• Does not silently overwrite everything in existing instruction files
• Does not pretend every repo needs the same policy

How the workflow behaves in practice

1. agent-policykit init detects the repository and writes project config into pyproject.toml.
2. agent-policykit generate compiles the merged policy bundle and writes the configured agent files.
3. agent-policykit diff shows exactly what would change on regeneration.
4. agent-policykit update refreshes managed sections while preserving user-owned content.

That means the tool behaves less like a prompt template and more like a code generator with safety checks.

Supported Agents

Tier 1 targets

Tier 2 exported compatibility files

• Generic markdown fallback: AGENT_POLICY.md
• RooCode: AGENT_POLICY.roocode.md
• Windsurf: AGENT_POLICY.windsurf.md
• Zed: AGENT_POLICY.zed.md
• Warp: AGENT_POLICY.warp.md
• Junie: AGENT_POLICY.junie.md
• Devin: AGENT_POLICY.devin.md
• Amp: AGENT_POLICY.amp.md
• Augment Code: AGENT_POLICY.augment-code.md
• Factory: AGENT_POLICY.factory.md
• Jules: AGENT_POLICY.jules.md
• goose: AGENT_POLICY.goose.md
• opencode: AGENT_POLICY.opencode.md
• Phoenix: AGENT_POLICY.phoenix.md
• Semgrep: AGENT_POLICY.semgrep.md
• Ona: AGENT_POLICY.ona.md

Safety Guarantees

• Security downgrade blocking: removing generated security rules requires --force.
• Managed-section ownership: user-written content outside managed blocks is preserved.
• Structured conflict notes: non-security rule removals are surfaced instead of disappearing silently.
• Size-aware rendering: outputs are condensed when targets have practical size limits.
• Dry-run support: diff is non-destructive, and generate and update support --dry-run.

Pack Coverage

CLI Reference

Flags

• --target <name> limits output to specific adapter targets and is repeatable.
• --mode review activates the stricter reviewer overlay.
• --dry-run shows changes without writing files.
• --force overrides security-downgrade blocking.
• --verbose or -v enables detailed detection output.

Review Mode

Generate reviewer-oriented instructions with:

agent-policykit generate --mode review

This tells downstream agents to act like strict reviewers: skeptical, technically demanding, and explicit about missing safeguards.

Documentation

• Architecture for system design, merge flow, and production guardrails
• Supported agents for output contracts per target
• Language packs for stack coverage details
• Framework packs for framework-specific rule coverage
• Project types for architecture-specific pack behavior

Examples

The repository ships real example fixtures that are used in tests. These are the best way to see how the workflow actually behaves.

FastAPI service

Fixture: examples/fastapi-service/

What it represents:

• Python
• FastAPI
• API service

Suggested command:

cd examples/fastapi-service
agent-policykit detect
agent-policykit generate \
  --target copilot \
  --target copilot-path \
  --target agents-md \
  --target generic-markdown \
  --target claude-code \
  --target cursor \
  --target aider \
  --target gemini-cli \
  --dry-run

Validated outputs:

• .github/copilot-instructions.md
• .github/instructions/project.instructions.md
• AGENTS.md
• AGENT_POLICY.md
• CLAUDE.md
• .cursor/rules/project.mdc
• CONVENTIONS.md
• .aider.conf.yml
• GEMINI.md

Next.js app

Fixture: examples/nextjs-app/

What it represents:

• TypeScript
• Next.js
• Web app

Suggested command:

cd examples/nextjs-app
agent-policykit detect
agent-policykit generate \
  --target copilot \
  --target copilot-path \
  --target agents-md \
  --target generic-markdown \
  --target cursor \
  --target claude-code \
  --target gemini-cli \
  --dry-run

Validated outputs:

• .github/copilot-instructions.md
• .github/instructions/project.instructions.md
• AGENTS.md
• AGENT_POLICY.md
• .cursor/rules/project.mdc
• CLAUDE.md
• GEMINI.md

Rails monolith

Fixture: examples/rails-monolith/

What it represents:

• Ruby
• Rails
• Monolith

Suggested command:

cd examples/rails-monolith
agent-policykit detect
agent-policykit generate \
  --target copilot \
  --target copilot-path \
  --target agents-md \
  --target generic-markdown \
  --target claude-code \
  --target cursor \
  --dry-run

Validated outputs:

• .github/copilot-instructions.md
• .github/instructions/app.instructions.md
• AGENTS.md
• AGENT_POLICY.md
• CLAUDE.md
• .cursor/rules/project.mdc

What these examples show

• Detection changes based on repo context instead of using one fixed prompt.
• Output targets can differ by stack and by target selection.
• Path-scoped instruction files are generated when the repo structure supports them.
• The same policy model produces different file formats without duplicating the source policy.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

Development setup:

1. Clone the repository from https://github.com/sidrat2612/agent-policykit.git.
2. Change into the agent-policykit directory.
3. Create and activate a virtual environment with python -m venv .venv and source .venv/bin/activate.
4. Install dev dependencies with pip install -e ".[dev]".
5. Run checks with pytest, ruff check src/ tests/, and mypy src/agent_policykit --ignore-missing-imports.

Community

• Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, and SECURITY.md.
• Use public GitHub issues and pull requests for bugs, proposals, and design discussion.
• Keep private reporting for security and conduct matters only.
• These community docs follow guidance from Open Source Guides.

License

MIT — use it anywhere.

_{Built for teams that want one policy across many coding agents.}