Governance Framework for AI Coding Agents: Agentic OS
Agentic OS is a governance framework designed to enforce structured workflows for AI coding agents, ensuring accountability and compliance at every stage of development. Unlike traditional rules files or agent prompts, which can be ignored, Agentic OS introduces a layer of machine-enforced discipline. This framework operates by validating evidence at each step of a predefined workflow, preventing incomplete or misleading claims from progressing without substantiation.
The core principle of Agentic OS is that an AI agent’s assertion of completion—such as 'Done'—is insufficient without verifiable evidence. This is achieved through a combination of git hooks, continuous integration (CI) checks, and a centralized validator that scrutinizes the work trail left by the agent. The system does not rely on the agent’s self-reporting but instead enforces rules through automated checks that are independent of the agent’s cooperation.
The framework is built to integrate seamlessly with existing development pipelines, adding an enforcement layer beneath tools like git hooks and CI. This ensures that even if an agent attempts to bypass checks, the underlying infrastructure will catch violations before they reach the codebase or production environment.
Agentic OS is compatible with major AI coding agents, including Claude Code, OpenAI Codex, Google Antigravity, Cursor, and GitHub Copilot. Its design is model-agnostic, relying on plain-text Markdown files (such as AGENTS.md) to define rules and workflows. This cross-platform compatibility means that governance policies remain consistent regardless of the agent being used, reducing the need for manual adjustments across different tools.
The framework’s workflow is divided into five primary phases: plan, build, review, test, and ship. Each phase requires tangible evidence before the agent can proceed to the next. For example, a 'ship' phase cannot be completed without proof of testing, review, and adherence to security standards.
How It Works
Agentic OS operates through a combination of pre-commit hooks, CI checks, and a centralized validator that collectively enforce governance rules. Here’s how it functions in practice:
- Rules Definition: Governance policies are defined in plain-text files (e.g., AGENTS.md), which specify the required phases, evidence, and guardrails for different types of tasks. These files serve as prompts for the AI agent but are not enforceable on their own.
- Evidence Collection: As the agent progresses through each phase (e.g., planning, building, reviewing), it generates evidence—such as test results, code reviews, or security scans—that must be recorded in a work log.
- Validation Checks: Before an agent can mark a task as complete, the system validates the evidence against predefined criteria. For instance, a 'test' phase must include actual test execution logs, not just a claim that tests were run.
- Git Hooks and CI Enforcement: Pre-commit hooks and CI pipelines act as the final gatekeepers. For example, a credential scan (scancredentials.py) checks for leaked secrets before they are committed to the repository. Similarly, CI checks ensure that tests are actually run and that all required phases are completed with valid evidence.
- Cross-Agent Consistency: The framework uses a unified set of governance files that work across different AI agents. This means that whether you’re using Claude Code, Codex, or Cursor, the same rules and workflows apply. The agent maps plain-text prompts (e.g., /bootstrap, /review) to the corresponding workflow files in the repository, ensuring consistency in execution.
One of the key innovations of Agentic OS is its risk-based scaling of rigor. Not all tasks require the same level of scrutiny.
- A tiny-fix (e.g., correcting a typo) follows a simplified workflow: classify → execute → evidence → done. This minimizes overhead for low-risk changes.
- A quick-win (e.g., a minor feature) requires bootstrap → plan → implement → evidence → ship, ensuring basic planning and testing are completed.
- A feature or architecture-change undergoes a rigorous process: bootstrap → spec → plan → implement → review → test → handoff → ship. This includes security reviews, testing, and documentation to mitigate higher risks.
Use Cases
Agentic OS is particularly valuable in environments where AI coding agents are used extensively, but governance and accountability are critical.
- Open-Source Projects: Projects relying on AI-assisted development can use Agentic OS to prevent accidental introductions of vulnerabilities (e.g., leaked credentials) or incomplete implementations. The framework’s open-source license (MIT) and compatibility with multiple agents make it accessible to a wide range of communities.
- Security-Critical Applications: In domains like fintech, healthcare, or infrastructure, where code quality and security are paramount, Agentic OS provides an additional layer of assurance.
- The framework ensures that decisions and evidence are retained across sessions, reducing the risk of lost context or duplicated efforts.
- The framework’s transparency and evidence-based approach make it suitable for studying AI-assisted coding practices.
By scaling guardrails to the risk level of the task, Agentic OS avoids unnecessary overhead for simple changes while maintaining strict enforcement for critical work.
Key Features & Capabilities
Agentic OS introduces several features that address common pain points in AI-assisted development:
- Machine-Enforced Backstops: The framework catches critical failures that agents might overlook, such as:
- Leaked Secrets: The scancredentials.py tool blocks commits containing exposed credentials (e.g., AWS access keys) before they reach git history. This is enforced via pre-commit hooks and CI scans.
- False Test Claims: CI pipelines verify that tests are actually executed, not just claimed to pass. A green checkmark without test evidence fails the build.
- If evidence is lacking, the validator blocks progression to the next stage.
- Test-Driven Development (TDD): Automatically triggered for features or architecture changes, ensuring red-green-refactor cycles are followed.
- Memory and Handoff Persistence: Decisions and evidence are stored in a centralized state file (currentstate.md) and per-task logs (work/*.md).
- Cross-Platform Compatibility: Governance files (e.g., AGENTS.md) are model-agnostic and work across Claude Code, Codex, Cursor, Copilot, and Antigravity. This eliminates the need to rewrite rules for different agents.
- Risk-Adaptive Workflows: The rigor of the workflow scales with the task’s risk profile.
- Tiny Fixes: Minimal phases (classify → execute → evidence) to avoid overhead for low-risk changes.
- Features/Architecture Changes: Full workflow (bootstrap → spec → plan → implement → review → test → ship) to ensure thorough validation.
- Security and Compliance: Built-in tools like credential scanning, static application security testing (SAST), and dependency audits help prevent common vulnerabilities.
The framework also includes 14 predefined skills that auto-attach based on task type. These skills provide structured guidance without acting as rigid gates.
Implementation and Integration
Agentic OS is designed to integrate with minimal disruption to existing workflows.
- Cloning the Repository: Users clone the Agentic OS repository into their project.
- Deploying the Framework: The deploybrain.sh script (or deploy.ps1 for Windows) sets up git hooks, CI checks, and governance files. A dry-run option allows users to preview changes before applying them.
- Customization: Users can tailor governance rules by modifying AGENTS.md or other configuration files. The framework supports custom skills and workflows while maintaining compatibility with its core enforcement mechanisms.
- CI/CD Integration: The framework’s pre-commit hooks and CI checks can be added to existing pipelines. For example, the credential scanner and SAST tools can be configured as required merge checks or optional security scans.
- Fix for Bytecode Tracking: Release v1.8.27 resolved an issue where Python bytecode files (.pyc) were inadvertently committed during initial deployment. The fix ensures that only intended files are staged, preventing clutter in the repository.
- Credential Scan Reliability: Release v1.8.26 fixed a bug where the pre-commit credential scan could fail silently, allowing secrets to reach git history. The updated hook now probes scanner startability and falls back to a canonical control if execution errors occur.
- Runtime Guide Consistency: Release v1.8.25 aligned the Antigravity runtime guide with the current framework version, ensuring adopters receive accurate documentation.
The framework’s design ensures that governance is enforced by the machine, not the agent. This means that even if an agent attempts to bypass checks, the underlying infrastructure will intervene.
- An agent might claim a task is 'done' without testing, but the CI pipeline will fail if no test evidence is provided.
- An agent could skip a review phase, but the validate.sh script will detect the missing evidence and block progression.
- A leaked secret might slip past an agent’s oversight, but the credential scanner will catch it before the commit is finalized.
This separation of enforcement from the agent’s control is what sets Agentic OS apart from traditional rules files or prompts, which can be ignored or circumvented.