{"id":51002128,"url":"https://github.com/lkimuk/ai-policy-runtime","last_synced_at":"2026-06-20T15:33:15.846Z","repository":{"id":357643484,"uuid":"1235435251","full_name":"lkimuk/ai-policy-runtime","owner":"lkimuk","description":"Generate better AI code with task-aware policies","archived":false,"fork":false,"pushed_at":"2026-05-29T10:01:10.000Z","size":3397,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-29T12:06:33.931Z","etag":null,"topics":["ai-coding","ai-tools","coding-assistant"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lkimuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"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-11T10:19:09.000Z","updated_at":"2026-05-29T10:01:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"62764364-5ef0-4ecb-9879-af6f55dc4941","html_url":"https://github.com/lkimuk/ai-policy-runtime","commit_stats":null,"previous_names":["lkimuk/ai-policy-runtime"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lkimuk/ai-policy-runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkimuk%2Fai-policy-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkimuk%2Fai-policy-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkimuk%2Fai-policy-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkimuk%2Fai-policy-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lkimuk","download_url":"https://codeload.github.com/lkimuk/ai-policy-runtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkimuk%2Fai-policy-runtime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34576043,"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-20T02:00:06.407Z","response_time":98,"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-coding","ai-tools","coding-assistant"],"created_at":"2026-06-20T15:33:15.659Z","updated_at":"2026-06-20T15:33:15.831Z","avatar_url":"https://github.com/lkimuk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![AI Policy Runtime banner](docs/assets/banner.png)\n\n# AI Policy Runtime\n\nGenerate better AI code with task-aware policies for Codex, Claude Code, and OpenCode.\n\nAI Policy Runtime gives your AI coding agent focused engineering rules for the\ntask at hand. It can guide implementation, review, refactoring, API design,\nperformance-sensitive work, Git workflows, CMake, Python, and post-task\nrefinement without making you rewrite prompts for every request.\n\nThe result is more consistent agent behavior across a workspace.\n\n## How it works\n\nAI Policy Runtime sits between the user's task and the coding agent. It reads\nthe current request, workspace signals, selected packs, and Skill DSL assets,\nthen compiles the relevant policy into a small task-specific rule set.\n\nThe agent does not receive the full Skill library. It receives the generated\nEffective Rules for the current task, rendered as prompt text and structured\nJSON. Those same rules can also be used after the agent acts for review,\nrefinement, and repair.\n\n## The Basic Workflow\n\n```text\nUser Task\n  ↓\nTask Analyzer\n  ↓\nStructured Context\n  ↓\nPolicy Compilation\n  - activate Skills and selected Packs\n  - apply dependencies and when / unless filters\n  - resolve conflicts\n  - reduce rules\n  ↓\nEffective Rules\n  - effective-prompt.md\n  - effective-rules.json\n  ↓\nAgent\n  ↓\nPost refinement\n  - review output\n  - apply refinement packs\n  - verify / repair when needed\n  ↓\nAgent\n  ↓\nWork done\n```\n\n1. The user sends a task to Codex, Claude Code, or OpenCode.\n2. The runtime analyzes the task and builds structured context.\n3. Matching Skills, selected Packs, dependencies, and rule conditions are\n   evaluated.\n4. Conflicts are resolved and redundant rules are reduced.\n5. Effective Rules are written to the workspace and injected into the agent.\n6. The agent works with the task-specific rules.\n7. Optional post-task refinement reviews the output and can run a constrained\n   second pass.\n\n## What It Does\n\n- Detects the task type and applies focused coding rules.\n- Shares one workspace configuration across Codex, Claude Code, and OpenCode.\n- Uses embeddings for stronger multilingual task matching.\n- Can run a post-task refinement pass before the agent finishes.\n- Shows the exact Effective Rules used for the latest prompt.\n\nC++ currently has the deepest coverage, including ownership, lifetime, bounds\nsafety, API design, modern C++, and low-latency work. Python, CMake, Git, and\ngeneral refinement packs are also included.\n\n## Install\n\n### VS Code\n\nInstall the **AI Policy Runtime** extension, then open its side bar in your\nworkspace.\n\nUse it with the Codex, Claude Code, or OpenCode extension you already use. Enable the\nruntime, select the agent, choose policy packs, and configure embeddings if you\nwant semantic task matching.\n\nFor Codex, trust the generated workspace hooks when Codex asks. Until the hooks\nare trusted, Codex will not run them, so AI Policy Runtime will appear enabled\nbut no rules will be injected.\n\nAfter updating the VS Code extension, reload the window and run\n**AI Policy Runtime: Validate Runtime**. Validation refreshes workspace hook\nfiles when they still point at an older extension runtime.\n\n### Command Line\n\n```powershell\nnpm install -g ai-policy-runtime\nai-policy doctor\n```\n\nConfigure a project for Codex:\n\n```powershell\nai-policy configure codex --root D:\\work\\project\n```\n\nConfigure a project for Claude Code:\n\n```powershell\nai-policy configure claude --root D:\\work\\project\n```\n\nConfigure a project for OpenCode:\n\n```powershell\nai-policy configure opencode --root D:\\work\\project\n```\n\nIn the VS Code extension, select `OpenCode` under Agents to generate the same\nproject-local OpenCode configuration from the bundled runtime.\n\nAfter updating the npm package, rerun `ai-policy configure codex` or\n`ai-policy configure claude` or `ai-policy configure opencode` for each\nworkspace that should use the new runtime. The command refreshes\n`.policy/config.json` and agent hook/plugin paths to the current installed\npackage.\n\n## Embeddings\n\nAI Policy Runtime uses embeddings for product-quality multilingual task\nmatching. You choose the provider:\n\n- **Auto**: use a configured OpenAI-compatible endpoint, otherwise use a\n  configured local model when available.\n- **OpenAI-compatible**: use an endpoint such as OpenAI, OpenRouter, or another\n  `/v1/embeddings` service.\n- **Local**: use a sentence-transformers model path that you provide.\n\nThe package does not include or download a local model by default.\n\nIf you want the CLI to use a remote embedding model immediately, configure an\nOpenAI-compatible endpoint through environment variables:\n\n```powershell\n$env:AI_POLICY_EMBEDDING_PROVIDER = \"openai-compatible\"\n$env:AI_POLICY_EMBEDDING_BASE_URL = \"https://openrouter.ai/api/v1\"\n$env:AI_POLICY_EMBEDDING_API_KEY = \"\u003cyour-api-key\u003e\"\n$env:AI_POLICY_EMBEDDING_MODEL = \"\u003cembedding-model\u003e\"\n```\n\nConfigure a local model from the CLI:\n\n```powershell\nai-policy embedding configure --root D:\\work\\project --provider local --model D:\\models\\paraphrase-multilingual-MiniLM-L12-v2\n```\n\nOr download the recommended default model:\n\n```powershell\nai-policy embedding configure --root D:\\work\\project --provider local --install\n```\n\nCheck the current embedding setup:\n\n```powershell\nai-policy embedding status --root D:\\work\\project\nai-policy embedding test --root D:\\work\\project\n```\n\nClean AI Policy Runtime workspace integration before uninstalling or when\nresetting a project:\n\n```powershell\nai-policy cleanup --root D:\\work\\project\n```\n\nCleanup removes AI Policy Codex/Claude/OpenCode integration entries,\n`.policy/config.json`, and generated `.policy/current` state. It keeps caches,\nlocal models, and unrelated agent settings.\n\n## Common Commands\n\n```powershell\nai-policy status --root D:\\work\\project\nai-policy resolve --pack cpp.safe_generation \"Implement this C++ API\"\nai-policy explain \"Review this change for ownership and lifetime risks\"\nai-policy validate\n```\n\n## Policy Packs\n\nIncluded packs:\n\n- `cpp.safe_generation`\n- `cpp.low_latency`\n- `cpp.code_review`\n- `cpp.library_api_design`\n- `cpp.modernization`\n- `cpp.production_refinement`\n- `python.best_practices`\n- `python.production_refinement`\n- `cmake.best_practices`\n- `cmake.production_refinement`\n- `git.best_practices`\n- `generic.production_refinement`\n\n## Custom Policy Directories\n\nProjects can layer team-specific Skills and Packs on top of the bundled policy\nlibrary without copying files into the package directories:\n\n```powershell\nai-policy resolve \"fix the deadlock\" `\n  --extra-skills D:\\team\\policy\\skills `\n  --extra-packs D:\\team\\policy\\packs\n```\n\nOr persist the paths in `.policy/config.json`:\n\n```json\n{\n  \"extraSkillsDirs\": [\"custom/skills\", \"../shared-policy/skills\"],\n  \"extraPacksDirs\": [\"custom/packs\"],\n  \"onDuplicate\": \"error\"\n}\n```\n\nRelative paths resolve from the configured policy root. Built-in `skills` and\n`packs` load first, then extra directories in order. Duplicate `skill_id` or\n`pack_id` values default to `error`; use `first_wins` or `last_wins` only when\nthe override is intentional. `ai-policy validate` checks the same duplicate\npolicy used by task analysis and rule activation.\n\n## Workspace Files\n\nAI Policy Runtime stores transparent project state in workspace files:\n\n- `.policy/config.json`\n- `.policy/current/effective-prompt.md`\n- `.policy/current/agent-hook-state.json`\n- `.codex/hooks.json` and `.codex/config.toml` when Codex is enabled\n- `.claude/settings.local.json` when Claude Code is enabled\n- `opencode.json` and `.opencode/plugins/ai-policy-runtime.js` when OpenCode is enabled\n\nThese files make the active policy visible and reproducible. Review them before\ncommitting workspace-specific settings; generated OpenCode plugin files include\nlocal runtime paths and are best kept out of source control.\n\n## Notes\n\n- AI Policy Runtime is not an LLM. It prepares task-aware policy context for AI\n  coding agents.\n- Local models are optional and user-configured.\n- Remote embedding requests are only used when you configure a remote provider\n  or credentials.\n- See [docs/usage.md](docs/usage.md) for CLI and advanced setup details.\n\n## Philosophy\n\nLarge rule libraries are useful for humans and tools, but they are noisy when\nsent directly to an agent. AI Policy Runtime treats policy as something to\ncompile, not paste.\n\nThe goal is to preserve useful complexity in the Skill library while giving the\nagent only the rules that matter for the current task. Packs expand candidate\nSkills, but conditions, conflict resolution, and reduction decide what becomes\neffective.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkimuk%2Fai-policy-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flkimuk%2Fai-policy-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkimuk%2Fai-policy-runtime/lists"}