{"id":50525485,"url":"https://github.com/sidrat2612/agent-policykit","last_synced_at":"2026-06-03T07:31:01.773Z","repository":{"id":359099364,"uuid":"1244379015","full_name":"sidrat2612/agent-policykit","owner":"sidrat2612","description":"For teams using multiple AI coding agents: detect the repo stack, generate Copilot, Claude, Cursor, Codex, Aider, and Gemini instruction files from one policy, and update them safely.","archived":false,"fork":false,"pushed_at":"2026-05-20T14:20:42.000Z","size":335,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T14:59:52.213Z","etag":null,"topics":["ai","aider","claude-code","cli","codex","coding-agents","copilot","cursor","gemini","governance","instructions","policy","security"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/agent-policykit/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sidrat2612.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T07:59:22.000Z","updated_at":"2026-05-20T14:21:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sidrat2612/agent-policykit","commit_stats":null,"previous_names":["sidrat2612/agent-policykit"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sidrat2612/agent-policykit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Fagent-policykit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Fagent-policykit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Fagent-policykit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Fagent-policykit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sidrat2612","download_url":"https://codeload.github.com/sidrat2612/agent-policykit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Fagent-policykit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33853983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","aider","claude-code","cli","codex","coding-agents","copilot","cursor","gemini","governance","instructions","policy","security"],"created_at":"2026-06-03T07:30:59.445Z","updated_at":"2026-06-03T07:31:01.767Z","avatar_url":"https://github.com/sidrat2612.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eagent-policykit\u003c/h1\u003e\n  \u003cp\u003e\n    \u003cstrong\u003eOne engineering policy in. Agent-specific instruction files out.\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    For teams using multiple AI coding agents in the same repository.\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/sidrat2612/agent-policykit/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/sidrat2612/agent-policykit/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sidrat2612/agent-policykit/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/sidrat2612/agent-policykit\" alt=\"License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sidrat2612/agent-policykit/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/sidrat2612/agent-policykit?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n`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.\n\n\u003e 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.\n\n## Why?\n\nMost 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.\n\n`agent-policykit` solves that with a compiler-style workflow:\n\n| Situation | Without agent-policykit | With agent-policykit |\n|-----------|-------------------------|----------------------|\n| Multiple agents in one repo | Prompt files drift and contradict each other | One shared policy generates all outputs |\n| Stack-specific guidance | Generic prompts ignore framework and project type | Packs inject Python, FastAPI, monolith, SDK, and other stack context |\n| Standards change | Manual edits across many files | `diff` and `update` regenerate safely |\n| Security guidance changes | Accidental weakening or deletion is easy | Security downgrade blocking prevents silent removal |\n\n## Who it is for\n\n- Engineering teams standardizing AI coding assistants across multiple repositories\n- Platform and enablement teams managing secure defaults and review expectations\n- Consultancies supporting different clients, stacks, and agent tools\n- Open-source maintainers who want contributors using different agents to follow the same repo rules\n\n## Quickstart\n\nInstall from PyPI:\n\n```bash\npip install agent-policykit\n```\n\nOr install the latest version directly from GitHub:\n\n```bash\npip install \"git+https://github.com/sidrat2612/agent-policykit.git\"\n```\n\n### CLI\n\nCommon CLI commands:\n\n- `agent-policykit init` detects the stack and writes `[tool.agent-policykit]` into `pyproject.toml`.\n- `agent-policykit generate` compiles the merged policy bundle and writes all configured agent files.\n- `agent-policykit diff` previews pending changes before regeneration.\n- `agent-policykit update` refreshes existing generated files while preserving user-owned sections.\n- `agent-policykit validate` checks bundled packs for structural correctness.\n\nMinimal flow:\n\n```bash\nagent-policykit init\nagent-policykit generate\nagent-policykit diff\nagent-policykit update\n```\n\n### Config File\n\nGenerated and manual workflows both use the same project config:\n\n```toml\n[tool.agent-policykit]\ntargets = [\"copilot\", \"agents-md\", \"cursor\", \"claude-code\"]\nlanguages = [\"python\", \"typescript\"]\nframeworks = [\"fastapi\", \"nextjs\"]\nproject_type = \"api_service\"\nreview_mode = false\n```\n\nRecommended config shape:\n\n- Set `targets` to the agent files your repository actually needs.\n- Set `languages`, `frameworks`, and `project_type` explicitly when auto-detection is not enough.\n- Use `review_mode = true` or `--mode review` when you want stricter reviewer behavior in generated instructions.\n\n## What Gets Written\n\n`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.\n\nTypical outputs include:\n\n| Target | Output |\n|--------|--------|\n| GitHub Copilot | `.github/copilot-instructions.md` |\n| GitHub Copilot path-scoped | `.github/instructions/*.instructions.md` |\n| Portable AGENTS | `AGENTS.md` |\n| Claude Code | `CLAUDE.md` plus `.claude/rules/shared.md` |\n| Cursor | `.cursor/rules/project.mdc` |\n| Aider | `CONVENTIONS.md` and `.aider.conf.yml` |\n| Gemini CLI | `GEMINI.md` |\n| Compatibility exports | `AGENT_POLICY.\u003ctarget\u003e.md` |\n\nThis is the core behavior: inspect repo context, compile one policy bundle, then write the file shape each agent actually consumes.\n\n## How It Works\n\n`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.\n\nExecution flow:\n\n1. Detect languages, frameworks, project type, existing targets, and path-scoped instruction surfaces.\n2. Load governance, language, framework, and project-type YAML packs.\n3. Merge them into one `PolicyBundle` using priority rules.\n4. Validate IDs, coverage, and structural integrity.\n5. Render target-native files through the adapter registry.\n6. Diff or update existing files using managed sections and downgrade protection.\n\n### What it does\n\n- Detects repository context instead of forcing one generic prompt onto every project\n- Compiles YAML rule packs into one merged policy bundle\n- Renders native instruction files for Copilot, Claude Code, Cursor, Codex, Aider, Gemini CLI, and compatibility targets\n- Generates path-scoped outputs for tools that support scoped instructions\n- Preserves user-owned content outside managed sections during updates\n- Blocks accidental security-rule removal unless `--force` is used\n- Condenses outputs automatically when target limits require it\n\n### What it does NOT do\n\n- Does not call external LLM APIs\n- Does not execute code from packs\n- Does not replace the execution engine of Copilot, Claude Code, Cursor, Codex, or other agents\n- Does not silently overwrite everything in existing instruction files\n- Does not pretend every repo needs the same policy\n\n### How the workflow behaves in practice\n\n1. `agent-policykit init` detects the repository and writes project config into `pyproject.toml`.\n2. `agent-policykit generate` compiles the merged policy bundle and writes the configured agent files.\n3. `agent-policykit diff` shows exactly what would change on regeneration.\n4. `agent-policykit update` refreshes managed sections while preserving user-owned content.\n\nThat means the tool behaves less like a prompt template and more like a code generator with safety checks.\n\n## Supported Agents\n\n### Tier 1 targets\n\n| Agent | Output file(s) |\n|-------|----------------|\n| GitHub Copilot (repo-wide) | `.github/copilot-instructions.md` |\n| GitHub Copilot (path-scoped) | `.github/instructions/*.instructions.md` |\n| AGENTS.md (portable) | `AGENTS.md` plus nested per-subproject files |\n| Cursor | `.cursor/rules/project.mdc` |\n| Claude Code | `CLAUDE.md` plus `.claude/rules/shared.md` and scoped rule imports |\n| Aider | `CONVENTIONS.md` and `.aider.conf.yml` |\n| OpenAI Codex | `AGENTS.md` (size-aware, up to 32 KiB) |\n| Gemini CLI | `GEMINI.md` |\n\n### Tier 2 exported compatibility files\n\n- Generic markdown fallback: `AGENT_POLICY.md`\n- RooCode: `AGENT_POLICY.roocode.md`\n- Windsurf: `AGENT_POLICY.windsurf.md`\n- Zed: `AGENT_POLICY.zed.md`\n- Warp: `AGENT_POLICY.warp.md`\n- Junie: `AGENT_POLICY.junie.md`\n- Devin: `AGENT_POLICY.devin.md`\n- Amp: `AGENT_POLICY.amp.md`\n- Augment Code: `AGENT_POLICY.augment-code.md`\n- Factory: `AGENT_POLICY.factory.md`\n- Jules: `AGENT_POLICY.jules.md`\n- goose: `AGENT_POLICY.goose.md`\n- opencode: `AGENT_POLICY.opencode.md`\n- Phoenix: `AGENT_POLICY.phoenix.md`\n- Semgrep: `AGENT_POLICY.semgrep.md`\n- Ona: `AGENT_POLICY.ona.md`\n\n## Safety Guarantees\n\n- **Security downgrade blocking**: removing generated security rules requires `--force`.\n- **Managed-section ownership**: user-written content outside managed blocks is preserved.\n- **Structured conflict notes**: non-security rule removals are surfaced instead of disappearing silently.\n- **Size-aware rendering**: outputs are condensed when targets have practical size limits.\n- **Dry-run support**: `diff` is non-destructive, and `generate` and `update` support `--dry-run`.\n\n## Pack Coverage\n\n| Category | Count | Examples |\n|----------|-------|----------|\n| Governance | 8 packs | architecture, base, compliance, operations, output contract, review, security, testing |\n| Languages | 28 packs | Python, TypeScript, Java, Go, C#, Rust, Ruby, PHP, Kotlin, Swift, and more |\n| Frameworks | 13 packs | FastAPI, Django, Flask, Express, NestJS, Next.js, Spring Boot, Rails, and more |\n| Project types | 9 packs | API service, web app, microservice, worker, CLI tool, SDK, monolith, and more |\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `init` | Interactive setup that detects stack and writes config |\n| `detect` | Print detected languages, frameworks, project type, and existing targets |\n| `generate` | Full pipeline: detect, load, merge, render, and write |\n| `update` | Regenerate and merge safely against existing files |\n| `diff` | Show the unified diff of pending changes |\n| `validate` | Validate all loaded packs for structural correctness |\n\n### Flags\n\n- `--target \u003cname\u003e` limits output to specific adapter targets and is repeatable.\n- `--mode review` activates the stricter reviewer overlay.\n- `--dry-run` shows changes without writing files.\n- `--force` overrides security-downgrade blocking.\n- `--verbose` or `-v` enables detailed detection output.\n\n## Review Mode\n\nGenerate reviewer-oriented instructions with:\n\n```bash\nagent-policykit generate --mode review\n```\n\nThis tells downstream agents to act like strict reviewers: skeptical, technically demanding, and explicit about missing safeguards.\n\n## Documentation\n\n- [Architecture](docs/architecture.md) for system design, merge flow, and production guardrails\n- [Supported agents](docs/supported-agents.md) for output contracts per target\n- [Language packs](docs/language-packs.md) for stack coverage details\n- [Framework packs](docs/framework-packs.md) for framework-specific rule coverage\n- [Project types](docs/project-types.md) for architecture-specific pack behavior\n\n## Examples\n\nThe repository ships real example fixtures that are used in tests. These are the best way to see how the workflow actually behaves.\n\n### FastAPI service\n\nFixture: [`examples/fastapi-service/`](examples/fastapi-service/)\n\nWhat it represents:\n\n- Python\n- FastAPI\n- API service\n\nSuggested command:\n\n```bash\ncd examples/fastapi-service\nagent-policykit detect\nagent-policykit generate \\\n  --target copilot \\\n  --target copilot-path \\\n  --target agents-md \\\n  --target generic-markdown \\\n  --target claude-code \\\n  --target cursor \\\n  --target aider \\\n  --target gemini-cli \\\n  --dry-run\n```\n\nValidated outputs:\n\n- `.github/copilot-instructions.md`\n- `.github/instructions/project.instructions.md`\n- `AGENTS.md`\n- `AGENT_POLICY.md`\n- `CLAUDE.md`\n- `.cursor/rules/project.mdc`\n- `CONVENTIONS.md`\n- `.aider.conf.yml`\n- `GEMINI.md`\n\n### Next.js app\n\nFixture: [`examples/nextjs-app/`](examples/nextjs-app/)\n\nWhat it represents:\n\n- TypeScript\n- Next.js\n- Web app\n\nSuggested command:\n\n```bash\ncd examples/nextjs-app\nagent-policykit detect\nagent-policykit generate \\\n  --target copilot \\\n  --target copilot-path \\\n  --target agents-md \\\n  --target generic-markdown \\\n  --target cursor \\\n  --target claude-code \\\n  --target gemini-cli \\\n  --dry-run\n```\n\nValidated outputs:\n\n- `.github/copilot-instructions.md`\n- `.github/instructions/project.instructions.md`\n- `AGENTS.md`\n- `AGENT_POLICY.md`\n- `.cursor/rules/project.mdc`\n- `CLAUDE.md`\n- `GEMINI.md`\n\n### Rails monolith\n\nFixture: [`examples/rails-monolith/`](examples/rails-monolith/)\n\nWhat it represents:\n\n- Ruby\n- Rails\n- Monolith\n\nSuggested command:\n\n```bash\ncd examples/rails-monolith\nagent-policykit detect\nagent-policykit generate \\\n  --target copilot \\\n  --target copilot-path \\\n  --target agents-md \\\n  --target generic-markdown \\\n  --target claude-code \\\n  --target cursor \\\n  --dry-run\n```\n\nValidated outputs:\n\n- `.github/copilot-instructions.md`\n- `.github/instructions/app.instructions.md`\n- `AGENTS.md`\n- `AGENT_POLICY.md`\n- `CLAUDE.md`\n- `.cursor/rules/project.mdc`\n\n### What these examples show\n\n- Detection changes based on repo context instead of using one fixed prompt.\n- Output targets can differ by stack and by target selection.\n- Path-scoped instruction files are generated when the repo structure supports them.\n- The same policy model produces different file formats without duplicating the source policy.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nDevelopment setup:\n\n1. Clone the repository from `https://github.com/sidrat2612/agent-policykit.git`.\n2. Change into the `agent-policykit` directory.\n3. Create and activate a virtual environment with `python -m venv .venv` and `source .venv/bin/activate`.\n4. Install dev dependencies with `pip install -e \".[dev]\"`.\n5. Run checks with `pytest`, `ruff check src/ tests/`, and `mypy src/agent_policykit --ignore-missing-imports`.\n\n## Community\n\n- Read [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), [SUPPORT.md](SUPPORT.md), and [SECURITY.md](SECURITY.md).\n- Use public GitHub issues and pull requests for bugs, proposals, and design discussion.\n- Keep private reporting for security and conduct matters only.\n- These community docs follow guidance from [Open Source Guides](https://opensource.guide/).\n\n## License\n\n[MIT](LICENSE) — use it anywhere.\n\n## Appreciation\n\nSpecial thanks to my good friend Arijeet Ganguli for taking the ideas behind `agent-policykit`, which is primarily focused on solo developers and small teams, and building an enhanced enterprise-oriented version for larger governance and control-plane needs: [Agentra](https://github.com/arijeetganguli/Agentra).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt for teams that want one policy across many coding agents.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidrat2612%2Fagent-policykit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsidrat2612%2Fagent-policykit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidrat2612%2Fagent-policykit/lists"}