AgenticOS

🌱 Where AgenticOS Came From

AgenticOS started as an experiment after learning about the Agent Skills paradigm: if an AI coding agent can be equipped with specialized knowledge and repeatable task workflows, could the same principle be applied to software engineering itself?

AI coding assistants are capable of generating syntax rapidly. However, building reliable, long-lived software requires more than raw model intelligence—it requires engineering context, deterministic boundaries, verification discipline, and institutional memory.

What began as an exploration evolved into a cohesive, open-source engineering operating system:

• Developer CLI (agentic-os): Lightweight, zero-dependency toolkit for bootstrapping, environment health checks, starter archetypes, and multi-agent IDE integration.
• 30+ Modular Skills encoding procedural engineering workflows and decision matrices.
• Deterministic Guardrails & Hooks that block unisolated or broken environments before commands execute.
• Project Memory & MCP Schemas for persisting durable architectural decisions across sessions.
• Adaptive Documentation scaling documentation depth to actual project complexity.
• Automated Verification & Secret Scanners maintaining a strict zero-secret invariant.
• 5 Production Starter Archetypes providing clean foundations across services, ML, and fullstack apps.

Note: AgenticOS is an independent open-source project inspired by the broader agent skills movement and is not affiliated with, sponsored by, or endorsed by Anthropic.

⚡ The Problem: Speed Without Structure

Modern AI coding agents generate code at extraordinary speed. But without explicit engineering standards and guardrails, they behave like hyper-productive junior developers:

• Fast ≠ Reliable: They install unpinned packages globally, polluting system environments and breaking neighboring projects.
• Correct ≠ Maintainable: They produce 2,000-line monolithic files instead of clean, layered domain boundaries.
• Passing Tests ≠ Architecture-Compliant: They bypass dependency injection, hardcode configuration values, and skip error handling.
• Generated ≠ Production-Ready: They omit rollback plans, expose sensitive keys in manifests, and hallucinate unbuilt features in documentation.

AI coding agents can write code. They still need engineering discipline.

💡 The Thesis

AgenticOS treats engineering discipline as infrastructure for AI agents.

The goal of AgenticOS is not to add bureaucracy or slow coding agents down. The goal is to make sound engineering behavior reusable, deterministic, and repeatable—turning ad-hoc prompt reminders into executable system invariants.

🚀 Quickstart

Get started with AgenticOS in under 60 seconds using the agentic-os developer CLI.

1. Install AgenticOS

pip install agentic-engineering-os

2. Option A: Bootstrap into an Existing Project

Initialize invariant rules, 30+ engineering skills, and deterministic hooks in your current workspace:

# Bootstrap AgenticOS assets into the workspace
agentic-os init

# Verify environment isolation & toolchain health
agentic-os doctor

# Configure AI assistant adapters (Antigravity, Cursor, Copilot, Claude)
agentic-os ide configure --target all

3. Option B: Scaffold from a Verified Starter Archetype

Create a new, production-ready project pre-configured with virtualenv isolation, tests, and formatting:

# List available starter templates
agentic-os new --list-templates

# Scaffold a FastAPI microservice with test suite and isolation
agentic-os new my-api-service --template python-service

# Initialize environment and run tests
cd my-api-service
uv venv .venv --python 3.12
uv sync
uv run pytest -v

🛠️ Developer CLI Reference

The agentic-os CLI is built using standard-library Python (zero heavy runtime dependencies) and works seamlessly across Windows, macOS, and Linux.

Commands Overview

Operational Safety & Flags

• Dry-Run Mode (-n / --dry-run): Previews all actions and file operations without writing any bytes to disk (exits with code 0).
• Conflict Safety & Force Mode (-f / --force): If an existing file contains conflicting modifications, operations safely halt (exit code 1) to prevent data loss unless --force is explicitly provided.
• Idempotent Execution: Running init, configure, or new repeatedly on clean or matching targets automatically skips identical files ([SKIP] (identical)) and exits cleanly with code 0.

🏛️ Architecture

AgenticOS decouples engineering into clear, specialized operational layers:

                        HUMAN / DEVELOPER
                                │
                                ▼
                       DEVELOPER CLI
                     (agentic-os entrypoint)
                                │
                                ▼
                      ┌──────────────────┐
                      │    AGENTS.md     │
                      │ Always-on rules  │
                      └────────┬─────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
           SKILLS            HOOKS             MCP
         Knowledge        Enforcement      Tools/Memory
         (30+ modules)    (Python engine)  (Graph schemas)
              │                │                │
              └────────────────┼────────────────┘
                               ▼
                           SUBAGENTS
                          Delegation
                               │
                               ▼
                        AI CODING AGENT
                               │
                               ▼
                       VERIFIED SOFTWARE
                               │
                               ▼
                      EMPIRICAL BENCHMARKS

🔒 Single Source of Truth Model

CLI Layer (agentic-os)
    ↓
Python Standard-Library Engines (doctor, init, templates, ide, guard)
    ↓
Canonical Repository Assets (Single Source of Truth)
    ├── .agents/skills/   (30+ modular domain skills)
    ├── hooks/            (environment guard isolation engine)
    ├── templates/        (5 production starter archetypes)
    └── AGENTS.md         (universal non-negotiable invariants)

Asset Integrity Invariant: The 30+ skills, 5 starter templates, and invariant rules are maintained as canonical filesystem assets. The CLI dynamically discovers, validates, and packages these assets directly from disk—they are never duplicated or hardcoded into Python source strings.

🔌 AI Agent & IDE Compatibility

AgenticOS provides first-class compatibility across major AI coding assistants and IDEs:

# Configure all IDE adapters simultaneously
agentic-os ide configure --target all

# Inspect IDE integration status
agentic-os ide doctor

🧩 Core Components

⚖️ Before vs. After AgenticOS

🔬 Empirical Evidence: Controlled Dependency Isolation

Can two concurrent projects with conflicting major dependencies (e.g., Pydantic v2.7.4 vs Pydantic v1.10.13) coexist in the same workspace without contaminating each other or modifying global Python?

Project A (Pydantic 2.7.4) ───┐
                               ├── Isolated (.venv / uv.lock) ──► Host Environment Clean
Project B (Pydantic 1.10.13) ─┘

In our controlled experiment across Windows, macOS, and Linux:

• Result: 8/8 verification metrics passed. Both projects resolved distinct lockfiles and executed in-environment tests concurrently with zero cross-project pollution observed under the tested conditions.
• Read the full scientific report: docs/case-studies/dependency-isolation.md.

📦 Starter Archetypes

AgenticOS includes 5 pre-configured, tested starter templates in templates/:

1. python-service: FastAPI microservice starter with Pydantic v2 validation, health probes, and pytest suite.
2. ai-ml: Tabular ML pipeline template with Scikit-Learn baselines, leak-free preprocessing, and evaluation tests.
3. rag-llm: Retrieval-Augmented Generation template with FAISS vector indexing, chunking, and typed query contracts.
4. fullstack: Complete fullstack application with React 19 SPA, Vite, FastAPI backend, and Docker Compose.
5. production-service: Enterprise microservice template with OpenTelemetry, structured JSON logging, correlation IDs, and multi-stage Dockerfile.

Scaffold any archetype instantly:

agentic-os new my-service --template production-service

🐕 Dogfooding & Repository Verification

AgenticOS is built and verified using its own engineering principles. Every pull request executes a self-verification test suite:

# Run CLI and repository self-verification suite
py ./tests/test_cli.py              # Validates CLI parser, doctor, init, template generator, and IDE adapters
py ./tests/validate_skills.py       # Validates YAML frontmatter, triggers & 6 Core Questions for all 30 skills
py ./tests/scan_secrets.py          # Scans repository for secrets, credentials, and sensitive tokens
py ./tests/test_templates.py        # Compiles all template code and validates test suite completeness
py ./tests/test_hooks.py            # Tests environment guard engine against unisolated and isolated projects
py ./tests/test_documentation.py    # Asserts 100% resolution of relative documentation cross-references

🛣️ Roadmap

• v1.0 (Foundation — Released): 30+ Modular Skills, Deterministic Hooks, MCP memory layer, 5 templates, multi-OS support, and self-verification suite.
• v1.1 (Developer Experience — Current): Developer CLI (agentic-os init, doctor, new, ide), automated archetype generator, and multi-agent IDE integration layer.
• v1.2 (Evidence & Benchmarks — Upcoming): Automated AgenticEval benchmark harness, empirical quality scorecards, and comparative evaluation suites.
• v2.0 (Ecosystem — Planned): Public skill registry, community plugins, multi-agent coordination protocols, and custom organization profiles.

See ROADMAP.md for detailed milestone tracking.

🤝 Contributing & Community

We welcome contributions from the community! Please review:

• CONTRIBUTING.md for our 6 Core Questions skill authoring standard.
• CODE_OF_CONDUCT.md for our community standards.
• SECURITY.md for our vulnerability disclosure policy and Zero-Secret Invariant.

📄 License

AgenticOS is open-source software licensed under the MIT License.