convez.ai
AgenteDevOps & InfraestruturaIntermediário
KbWen

Agentic OS

KbWen/agentic-os

Governança estruturada para agentes de IA—sem pulos de fase, sem falsas conclusões

Ver no GitHub
BomPluginScore · de 0 a 100

Framework de governança para agentes de IA de codificação que impõe um fluxo de trabalho estruturado em cinco fases: planejar, implementar, revisar, testar e entregar. Previne que agentes pulem etapas, desviem do escopo ou finalizem tarefas sem evidência verificável, funcionando com Claude Code, Cursor, Copilot e outras ferramentas.

Instalação

$npx convez-ai KbWen/agentic-os

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
237
Forks
51
Acompanhando
4
Saúde
100%
Último commit
há 6 dias
Versão
v1.8.39
Issues abertas
12
Contribuidores
3

Casos de uso

  • Garantir qualidade de código gerado por agentes IA antes de produção
  • Implementar gates de segurança e revisão em workflows de desenvolvimento automatizado
  • Padronizar processos de entrega entre múltiplos agentes de IA (Claude, Copilot, Cursor)

Veredito

Solução madura e bem-estruturada que aborda um problema real: agentes de IA que saltam etapas e fingem conclusão sem evidência. O framework é portável, agnóstico de modelo e traz segurança operacional legítima para automação de código. Recomendado para equipes que delegam desenvolvimento a agentes e precisam de confiança verificável.

README

A tradução para o português deste README ainda está na fila.


The Problem

AI coding agents are powerful, but they need shared operating rules. Without structure, they can:

  • Skip steps — jump straight to code without planning or reviewing
  • Hallucinate completion — claim "done" without verifiable evidence
  • Drift from scope — refactor code nobody asked them to touch
  • Lose context — forget decisions across conversations, forcing re-derivation
  • Break things silently — no safety gates between "idea" and "production"

The Solution

Agentic OS is a portable governance framework that gives AI agents a repeatable engineering workflow. Install it into your project, and your AI agents gain:

flowchart LR
    U["User<br/>says"] --> G{"Gate<br/>Engine"}
    G -->|PASS| W["Workflow<br/>+ Skills"]
    W --> E{"Evidence<br/>Required"}
    E -->|PASS| S["Ship<br/>→ SSoT"]
    G -->|FAIL| X1["⛔ STOP"]
    E -->|FAIL| X2["⛔ STOP"]

    style U fill:#8b5cf6,color:#fff,stroke:none
    style G fill:#f59e0b,color:#fff,stroke:none
    style W fill:#3b82f6,color:#fff,stroke:none
    style E fill:#22c55e,color:#fff,stroke:none
    style S fill:#06b6d4,color:#fff,stroke:none
    style X1 fill:#ef4444,color:#fff,stroke:none
    style X2 fill:#ef4444,color:#fff,stroke:none

The idea behind every phase is the same: if there's no verifiable evidence, the task isn't done — and the gates enforce that, instead of trusting the agent to self-report honestly.


Features

Gate Engine & Phase System

Every task flows through mandatory phases. The AI cannot skip ahead.

flowchart LR
    B["/bootstrap"] --> P["/plan"]
    P --> I["/implement"]
    I --> R["/review"]
    R --> T["/test"]
    T --> S["/ship"]

    style B fill:#8b5cf6,color:#fff,stroke:none
    style P fill:#3b82f6,color:#fff,stroke:none
    style I fill:#22c55e,color:#fff,stroke:none
    style R fill:#f59e0b,color:#fff,stroke:none
    style T fill:#ef4444,color:#fff,stroke:none
    style S fill:#06b6d4,color:#fff,stroke:none
ClassificationRequired Phases
tiny-fixClassify → Execute → Evidence → Done
quick-winBootstrap → Plan → Implement → Evidence → Ship
featureBootstrap → Spec → Plan → Implement → Review → Test → Handoff → Ship
hotfixBootstrap → Research → Plan → Implement → Review → Test → Ship
architecture-changeBootstrap → ADR → Spec → Plan → Implement → Review → Test → Handoff → Ship

Engineering Guardrails

A constitution for AI behavior — safety invariants always loaded (AGENTS.md); deeper rules load by task tier and phase:

  • No Evidence = No Completion — narrative claims are not proof
  • Scope Discipline — unauthorized refactoring is strictly prohibited
  • Destructive Command Gate — rm -rf, git reset --hard, force pushes & co. are deny-by-default: blast radius + rollback plan covering untracked state + user confirmation first (canonical rule and full command list: AGENTS.md §Core Directives)
  • OWASP Top 10 Auto-Scan — security checks run during /implement and /review
  • Confidence Gate — AI must declare confidence at plan/implement; low confidence triggers escalation

14 Professional Skills

Skills auto-activate based on task classification and workflow phase:

SkillTriggerDescription
Test-Driven Developmentfeature, architecture-changeRed → Green → Refactor cycles
Systematic Debuggingbug encounter4-phase root cause analysis
Red Team / Adversarialreview, testClassification-based security analysis
API DesignAPI endpoints detectedEndpoint validation enforcement
Auth Securityauth code detectedHashing, tokens, rate limiting
Database Designmigration detectedForward-only ORM-aware migration safety
Frontend PatternsUI componentsComponent and state management patterns
Parallel Agent Dispatchingcomplex tasksCoordinated subagent execution
Subagent-Driven Developmentmulti-module tasksMulti-agent coordination
Karpathy Principlesall coding tasksBehavioral guardrails against common LLM coding mistakes
Production Readinessfeature, architecture-changePre-ship observability: error sinks, log strategy, rollback telemetry
Verification Before Completion/ship5-gate check: Scope → Quality → Evidence → Risk → Communication
Git Worktreesparallel branchesWorktree isolation workflows
Doc Lookupdocumentation neededDocumentation retrieval strategy

Single Source of Truth (SSoT)

Every project has one canonical state file. AI agents read it first, write to it last.

.agentcortex/context/
├── current_state.md          # Global project state (SSoT)
└── work/
    └── <branch-name>.md      # Per-task work log (isolated)
  • Work Logs track per-task progress, evidence, and gate receipts
  • SSoT tracks global decisions, lessons, and ship history
  • Handoff enables seamless AI-to-AI continuity across conversations

Multi-Agent Collaboration

Built for teams where multiple AI sessions work on the same codebase:

  • One Branch = One Owner — prevents concurrent Work Log corruption
  • Single-Writer Locking — atomic lock files block concurrent sessions per branch (configurable back to advisory)
  • Ship Guard — checks for SSoT conflicts before merging
  • Session Identity — every AI session writes its model name and timestamp

Three Entry Paths

Pick the one that matches your starting point (full opener templates in Quick Start §2):

Starting pointFirst commandFull chain
🆕 Brand-new project, multi-feature idea/spec-intakespec-intake → pick feature → bootstrap → app-init → plan → implement
🏗️ Existing repo, adopting Agentic OS/audit (read-only, zero risk)audit → app-init → spec-intake → quick-win → feature
🎯 Single concrete task on an established project/bootstrapbootstrap → plan → implement → review → test → ship

See the Lifecycle Benchmark (繁體中文) for real token consumption data across 6 development scenarios.

Token Efficiency

Designed for cost-effective models (Gemini Flash, Haiku, etc.):

  • Conditional Loading — tiny-fix skips guardrails (~5,000 tokens saved)
  • Skill Cache Policy — metadata-first loading, full SKILL.md only on cache miss
  • Phase Summary — compact 1-liner per phase for low-token resume
  • Read-Once Discipline — governance docs persist in context, never re-read

Quick Start

1. Install

Prerequisites:

DependencyRequired?Purpose
GitRequiredClone and deploy the framework
BashRequiredRun deploy & validate scripts (Git Bash from Git for Windows is enough on Windows)
Python 3.9+RecommendedEnables full validation (metadata, encoding, command sync checks)
SHA-256 toolRequired for deploysha256sum, shasum, or openssl (pre-installed on most systems)

No Python? The framework deploys and works without Python. Validation runs in degraded mode — Python-dependent checks report WARN instead of FAIL. Pass --no-python to suppress warnings: bash .agentcortex/bin/validate.sh --no-python

Install (first time):

# Clone Agentic OS
git clone https://github.com/KbWen/agentic-os.git

# Preview what will be deployed (no changes made)
./agentic-os/installers/deploy_brain.sh --dry-run /path/to/your-project

# Deploy into your project
./agentic-os/installers/deploy_brain.sh /path/to/your-project

Update (after first install): the installer lives inside your project. Run it from your project root — it reads the deploy manifest and auto-fetches the latest framework version from GitHub.

bash installers/deploy_brain.sh .

Existing files won't be overwritten. If your project already has AGENTS.md, CLAUDE.md, or other framework-managed files, they are preserved. The new framework version is saved as <filename>.acx-incoming sidecar. Review and merge manually — or ask your AI agent: "Merge each .acx-incoming into its target, preserving my project-specific content and adopting framework updates."

AI-agent install: If you're asking an AI assistant to install Agentic OS, point it to this README. The commands above are deterministic — no platform-specific heuristics required.

Optional local pre-commit validation: enable the bundled Git hook sample to run Agentic OS validation before each commit.

cp .githooks/pre-commit.guard-ssot.sample .githooks/pre-commit
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

On Windows, run the setup from PowerShell:

Copy-Item .githooks\pre-commit.guard-ssot.sample .githooks\pre-commit
git config core.hooksPath .githooks

The hook runs validate.ps1 from Git Bash on Windows when PowerShell is available, otherwise it runs validate.sh. Validator failures block the commit; guarded SSoT receipt warnings remain advisory.

# Clone Agentic OS (first time)
git clone https://github.com/KbWen/agentic-os.git

# Preview what will be deployed (no changes made)
powershell -ExecutionPolicy Bypass -File .\agentic-os\installers\deploy_brain.ps1 -DryRun C:\path\to\your-project

# Deploy into your project
powershell -ExecutionPolicy Bypass -File .\agentic-os\installers\deploy_brain.ps1 C:\path\to\your-project

# CMD alternative
.\agentic-os\installers\deploy_brain.cmd C:\path\to\your-project

Use the PowerShell entrypoint when possible. It resolves Git Bash directly and does not require a WSL distro. Git Bash is still required on Windows for shell-based deploy and validation scripts; the PowerShell entrypoint simply locates and invokes it for you.

# Already installed? Run from your project root to update:
powershell -ExecutionPolicy Bypass -File .\installers\deploy_brain.ps1 .

# Validation after install
powershell -ExecutionPolicy Bypass -File .\.agentcortex\bin\validate.ps1

# Lightweight validation when Python is not installed
powershell -ExecutionPolicy Bypass -File .\.agentcortex\bin\validate.ps1 -NoPython

# (Git Bash equivalent)
bash ./.agentcortex/bin/validate.sh --no-python

If you only want the governance templates (Markdown files) without running any tooling:

  1. Copy the .agent/, .agents/, and AGENTS.md files into your project
  2. Optionally copy .agentcortex/context/ and .agentcortex/templates/ for state management
  3. No Python, Bash, or other tools are needed — all governance is plain Markdown

1a. Customizing Without Conflicts (Fork or Clone)

However you adopt Agentic OS — fork the repo, or clone + deploy_brain.sh into your project — the same rule keeps upgrades painless: add your own files; never edit framework-owned files in place. Put your customizations where the framework guarantees never to touch them, and they survive both git pull upstream (fork) and the next deploy (clone):

You want to…Put it hereWhy it survives upgrades
Add project governance (narrow/disable a directive)AGENTS.override.md (project root) or ~/.agentcortex/AGENTS.override.md (personal)Loaded present-only at session start; framework never ships these files. MAY narrow/disable directives but cannot relax delivery gates.
Add your own skills.agents/skills/custom-<name>/SKILL.md (+ .agent/skills/custom-<name> metadata)custom-* is a reserved namespace the framework never ships → zero collision, never overwritten.
Adjust skill activation (pin/exclude).agentcortex/context/private/user-preferences.yamlGitignored, personal, loaded by bootstrap.

What NOT to do: editing a framework file in place (AGENTS.md, .agent/rules/*, .agent/workflows/*, a shipped skill body) causes merge conflicts on git pull upstream (fork) and is force-updated on the next deploy (clone). Framework skills are the one tolerant exception — if you edit one, deploy preserves your copy as a visible <file>.acx-incoming sidecar rather than silently overwriting it — but the cleaner pattern is always to copy it to a custom-<name> skill and edit that. Governance, security, and workflow files always force-update so you keep receiving fixes.

2. Start Working — Pick Your Entry Point

The right first command depends on your starting point. Always preface with:

"Read AGENTS.md and follow it. Do not claim completion until /review and /test pass."

Then add one of the following based on your situation:

A. Brand-new project, multi-feature idea — /spec-intake first

This is a brand-new project. My initial idea is:
[1–2 paragraphs describing the product and its features]

Please run /spec-intake to decompose this into a feature inventory.
After I pick the first feature, run /bootstrap → /app-init to establish
the tech stack ADR, then /plan and /implement.

B. Existing repository adopting Agentic OS — /audit first

This repo already has code; Agentic OS was just deployed.
Run /audit (read-only) to map the codebase, then /app-init to record
the tech stack ADR, then /spec-intake when I add features.

C. Single concrete task on an established project — /bootstrap directly

/bootstrap
[describe the single task]

Why this matters: a multi-feature raw idea routed straight to /bootstrap is classified as a single task, skipping the Feature Inventory and _product-backlog.md decomposition. The Intent Router auto-detects this in most cases, but explicit beats inferred.

3. Follow the Flow

The AI will classify your task and follow the required phases automatically:

You: "Add pagination to the user list API"

AI: [/bootstrap] → Classification: feature
    → Required: Bootstrap → Spec → Plan → Implement → Review → Test → Handoff → Ship
    → Loading skills: API Design, Test-Driven Development
    → ⚡ ACX

Commands

CommandPurpose
/bootstrapInitialize task, classify scope, create work log
/spec-intakeImport and decompose external specs
/specDefine verifiable specifications
/planCreate implementation plan with rollback steps
/implementExecute code changes (gate-protected)
/reviewLogic, security, and scope audit
/testVerify with minimal necessary tests
/handoffResumable state summary for next session
/shipConsolidate evidence, update SSoT, merge
/adrArchitecture Decision Record
/brainstormRapid solution exploration
/researchAutonomous research and recommendation
/auditRead-only system mapping
/retroRetrospective analysis
/decideRecord key decisions with reasoning
/hotfixEmergency fix escalation

Architecture

your-project/
├── AGENTS.md                    # Global AI governance directives
├── CLAUDE.md                    # Claude Code integration entry
│
├── .agent/                      # Agent Intelligence Layer
│   ├── config.yaml              # Governance constants
│   ├── rules/                   # Engineering & security guardrails
│   ├── skills/                  # Skill metadata (auto-trigger defs)
│   └── workflows/               # Workflow definitions (33 workflows)
│
├── .agents/skills/              # Full skill implementations (14 skills)
│   ├── test-driven-development/
│   ├── systematic-debugging/
│   └── ...
│
├── .agentcortex/                # Runtime & State Layer
│   ├── bin/                     # Deploy & validation scripts
│   ├── context/                 # SSoT + work logs
│   ├── docs/                    # Philosophy, platform guides, examples
│   ├── metadata/                # Skill registry & cache index
│   ├── templates/               # Reusable ADR/spec/README templates
│   └── tools/                   # Runtime tools (Python)
│
├── docs/                        # Project-level documentation
│   ├── specs/                   # Feature specifications
│   ├── adr/                     # Architecture Decision Records
│   └── architecture/            # Domain architecture docs
│
└── installers/                  # Cross-platform deploy wrappers
    ├── deploy_brain.sh          # Bash installer
    ├── deploy_brain.ps1         # PowerShell installer
    └── deploy_brain.cmd         # CMD installer

Platform Compatibility

PlatformStatusIntegration
Claude CodeNative supportCLAUDE.md entrypoint + Claude platform guide
OpenAI CodexNative supportAGENTS.md, Codex platform guide, and CLI delegation workflow
Google AntigravityNative supportIntent router + Antigravity runtime guidance
CursorCompatibleUses AGENTS.md / project-rule style guidance
GitHub CopilotCompatibleUses repository instructions and guardrail docs
Any LLM AgentCompatibleModel-agnostic Markdown workflows and evidence rules

Philosophy

Agentic OS is built on 10 non-negotiable principles:

#PrincipleMeaning
1AI Drives, Human AssistsAI follows phases autonomously; human confirms direction
2Never Skip PhasesSequential execution, not skip-to-end
3Constitution Over TaskGuardrails override any request
4No Evidence = No CompletionClaims without proof are rejected
5Correctness FirstCorrect > performant > clever
6Token EfficiencyMinimize cold-start cost, maximize context reuse
7Cross-Model ComplianceWorks with any AI model, no vendor lock-in
8Actionable DocumentationEvery doc must be directly usable
9Scope DisciplineOnly touch what was asked
10ExplainabilityEvery AI decision must be traceable

Documentation

Start with the document that matches what you are trying to do:

GoalStart HereWhy
Install or upgrade Agentic OSQuick Start, Migration GuideDeployment commands, update flow, and existing-project guidance
Choose the right AI modelModel Selection Guide, Lifecycle BenchmarkPractical model tradeoffs and measured token costs
Run disciplined agent workflowsAgent Philosophy, Testing ProtocolCore rules, evidence expectations, and verification standards
Use a specific platformCodex Platform Guide, Claude Platform GuidePlatform-specific loading, handoff, and compatibility notes
Understand governance internalsDocument Governance, Nonlinear ScenariosState, handoff, recovery, and documentation lifecycle rules
Extend skills safelySkill Ecosystem, Token GovernanceSkill packaging, trigger policy, and context budget control
DocumentDescription
Agent Philosophy10 core principles
Model Selection GuideFlash vs. Pro guidance
Testing ProtocolTesting standards
Project ExamplesNode.js & Python examples
Token GovernanceToken optimization strategies
Token Optimization QuickstartReduce token costs immediately (繁體中文)
Context BudgetContext window management
Migration GuideUpgrade an existing install
Codex Platform GuideCodex Web/App adaptation
Claude Platform GuideClaude Code integration
Nonlinear ScenariosRecovery from interrupted sessions
Lifecycle Benchmark6 real scenarios with token costs
生命週期基準測試Token 消耗量測(繁體中文)

FAQ

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

How is it different from Cursor Rules or a plain AGENTS.md file? A rules file tells the agent how to behave. Agentic OS adds the workflow and the gates that hold it to that behavior: phase sequencing, evidence requirements, scope discipline, and a single source of truth that remembers decisions across sessions. It's the difference between a prompt the agent might follow and a workflow it has to.

Which AI coding agents does it support? Any agent that can read Markdown instructions. It ships native entry points for Claude Code (CLAUDE.md) and Codex / Antigravity (AGENTS.md), and works with Cursor, GitHub Copilot, and other LLM agents through the same model-agnostic workflow files.

Do I need to know a specific programming language? No. The governance layer is plain Markdown. Python is optional — it only unlocks the deeper validation checks. Everything deploys and runs without it.

Does it lock me into one AI vendor? No. The workflows are model-agnostic Markdown, so the same governance works whether you switch between Claude, Codex, Gemini, or anything else.

Is it free? Yes — MIT licensed. Use it, fork it, ship it.


Contributing

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

License

MIT License. See LICENSE for details.


Ver o original no GitHub

Bom para

Relacionados