Agentic OS

"Done." — your AI coding agent, about code it didn't test.
A rules file asks your agent to behave. Agentic OS checks that it did — leaked secrets and a green check over zero tests fail your git hooks and CI; a skipped review or phase shows up when the validator reads the work trail. Backstops you control, not the agent's own word.

A governance-first layer for AI coding agents — guardrails and a gated workflow for Claude Code, Codex, Cursor, Copilot, Antigravity, or any Markdown-reading agent.

 ·  繁體中文 · Contributing · Changelog

_{It checks the evidence behind what your AI coding agent claims — secrets, tests, reviews — through your git hooks and CI. Here's a gate firing:}

The /bootstrap, /review, and /ship above are plain text prompts — your agent maps them to the workflow files in the repo, so they run the same in Cursor or Codex as in Claude Code.

Or run a gate yourself, no install — the credential scan that catches a leaked key before it reaches git history:

bash demo/run.sh          # Windows (PowerShell): pwsh demo/run.ps1

  An AI agent wrote this file and reported: "Done — config added."
  ----------------------------------------------------------------
    DB_HOST=prod.internal
    aws_access_key_id = AKIA****************
  ----------------------------------------------------------------

  Without a gate, that commit lands and the key is in git history forever.
  Agentic OS runs this before the commit is allowed:

    $ scan_credentials.py config.env

CREDENTIAL PATTERN(S) DETECTED (values redacted):
  config.env:2: aws-access-key-id
Rotate the exposed secret, remove it from the change, then retry.

  Commit BLOCKED. The agent said "done"; the machine said no — and it
  redacted the value instead of echoing your secret back at you.

Your agent can still cut a corner. What it can't do is get a leaked secret, a green check over zero tests, or a skipped review past the hooks and CI — those run whether it cooperates or not. The key above is generated at runtime and redacted on output, so the demo never stores a real secret.

Rules vs. enforcement

A rules file — Cursor Rules, a plain AGENTS.md — is a prompt the agent can ignore. Agentic OS keeps that discipline (plan before editing, no unasked-for refactors) and adds a layer the agent doesn't control:

The third row is the part a rules file can't reach: validate.sh parses each task's work log and fails if a required phase was skipped or its evidence is missing. The local pre-commit hook is opt-in and you can --no-verify past it; the three required CI checks (Framework Validation, ShellCheck, Check Markdown Links) are the floor that can't be skipped — they must pass before any PR merges. The security scanning jobs (credential scan, SAST, dependency audit) run on every PR but are not required merge checks unless you add them to branch protection. The Security badge above is this repo running the same credential and SAST gates on its own every push.

Sits under what you already have

Agentic OS is the enforcement layer. A rules file or a skill pack tells your agent how to behave; this is the part that checks it actually did - in your git hooks and CI, where the agent's own report doesn't get a vote. Already have those? Keep them. This sits underneath and turns the discipline they ask for into a check that can fail your commit or your build.

Gated phases, scaled to risk

Every task runs a gated workflow, and the rigor scales to the risk. Skip a phase and validate.sh fails — but a typo doesn't run the same gauntlet as a feature:

  tiny-fix    classify --> execute --> evidence --> done
  quick-win   bootstrap --> plan --> implement --> evidence --> ship
  feature     bootstrap --> spec --> plan --> implement --> review --> test --> ship

  And the ship gate is not a formality:

  ship attempt --> [ no review/test evidence ] --> BLOCKED
  ship attempt --> [ evidence on record ]      --> SHIPPED

  The agent can still cut a corner. It just can't cut this one
  past a check it doesn't control.

The full set of paths, by classification:

What you get

.agentcortex/context/
├── current_state.md          # Global project state (single source of truth)
└── work/
    └── <branch-name>.md      # Per-task work log (isolated, evidence + gate receipts)

Works with your agent

Either way the real floor is the same: the git hooks and CI don't care which agent you run.

Quick start

git clone https://github.com/KbWen/agentic-os.git
./agentic-os/installers/deploy_brain.sh --dry-run /path/to/your-project   # preview, no changes
./agentic-os/installers/deploy_brain.sh /path/to/your-project             # deploy

Then tell your agent: "Read AGENTS.md and follow it. Do not claim completion until /review and /test pass." — followed by /bootstrap and your task.

Existing files are never overwritten (saved as .acx-incoming sidecars to merge). Windows / no-Python mode, updating, customizing without conflicts, turning the CI floor into a required check, and the full entry-point templates → docs/INSTALL.md.

Running the tests

# Fast local loop — mirrors what CI runs; skip the slow subprocess tests
python -m pytest tests/ci/ tests/guard/ .agentcortex/tests/ -m "not slow"

Full details and the slow suite → CONTRIBUTING.md.

FAQ

What is Agentic OS? An open-source governance framework for AI coding agents. It gives agents like Claude Code, Codex, Cursor, Copilot, and Antigravity a repeatable workflow — plan, build, review, test, ship — and enforces gates so they can't skip steps or call a task "done" without verifiable evidence.

How do I stop an AI agent from skipping tests or shipping unverified code? That's the core of it. The credential scan, the test suite, and the phase/evidence validator run in your git hooks and CI — so a leaked secret, a missing test, or a skipped review fails the commit or the build, regardless of what the agent reports. The agent can still cut a corner; it just can't get that corner past the checks it doesn't control.

How is it different from Cursor Rules or a plain AGENTS.md file? A rules file tells the agent how to behave, and the agent can ignore it. Agentic OS adds the workflow and the checks that hold it to that behavior: phase sequencing, evidence requirements, scope discipline, and a single source of truth that remembers decisions across sessions. The skills and discipline are still guidance the agent follows; what's enforced is the part that fails your commit or CI — leaked secrets, missing tests, a skipped phase.

Does it lock me into one AI vendor? No. It's model-agnostic Markdown — native entry points for Claude Code (CLAUDE.md), Codex (AGENTS.md), and Gemini / Antigravity (GEMINI.md), and it works with Cursor, Copilot, and any other LLM agent through the same workflow files.

Is it free? Yes — MIT licensed. Fork it and ship it.

Docs

Contributing

See CONTRIBUTING.md — guidelines for contributing as a human or an AI agent.

License

MIT. See LICENSE.

_{A governance-first layer for AI coding agents. Contributions and feedback welcome.}