AgenticOS — Deterministic AI Agent Orchestration¶

Open Source · Security Automation Framework · December 2025

View on GitHub

The Problem¶

AI coding assistants are powerful but unpredictable. Security teams need:

• Determinism: Same inputs produce same behavior
• Auditability: Every decision logged and explainable
• Control: No hidden behaviors or silent mutations
• Multi-provider support: Use the right AI for each task

Existing tools lack the governance layer needed for regulated environments and security workflows.

What I Built¶

Unified CLI (aos)¶

A single command interface that wraps all AgenticOS functionality:

aos                              # List profiles & workflows
aos q "What is XSS?"             # Quick question (clean output)
aos d "Fix the auth bug"         # Development task
aos auto "Write a security policy"  # Auto-route to best profile
aos -p myproject d "Add logging"    # Work on specific project

Core Architecture¶

flowchart LR
    subgraph CORE[AGENTICOS CORE]
        direction LR
        subgraph R[ROUTING]
            R1[Keyword Rules]
            R2[AI Classification]
            R3[Precedence Order]
            R4[Dry-run Mode]
        end
        subgraph E[EXECUTION]
            E1[Profile-based]
            E2[Provider Agnostic]
            E3[Timeout Control]
            E4[Structured Output]
        end
        subgraph P[PERSISTENCE]
            P1[Session Memory]
            P2[JSON Logs]
            P3[Delta Tracking]
            P4[Project Isolation]
        end
    end

    style CORE fill:#f8fafc,stroke:#334155,stroke-width:2px
    style R fill:#e8f4ea,stroke:#2e7d32,stroke-width:2px
    style E fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style P fill:#fef3c7,stroke:#d97706,stroke-width:2px

Script Breakdown¶

Provider Integration¶

Key Features¶

1. Deterministic Auto-Routing¶

Route prompts to the optimal profile using keyword rules or AI classification:

# Keyword-based (instant)
aos auto "Fix the SQL injection vulnerability"
# → Routes to 'dev' profile (matches: fix, vulnerability)

# AI-powered (smarter)
aos auto --smart "Help me understand NIST 800-53 controls"
# → Routes to 'grc' profile (AI classification)

2. Explainable Decisions¶

Every routing decision is logged with full reasoning:

{
  "timestamp": "2025-12-23T14:32:07Z",
  "action": "auto_route",
  "query": "Fix the authentication bug",
  "tokens": ["fix", "the", "authentication", "bug"],
  "matched_rule": "dev_fix",
  "target": {"type": "profile", "name": "dev"},
  "reason": "Rule matched: fix + bug keywords"
}

3. Project Isolation¶

Manage multiple projects with isolated configurations:

aos projects                     # List registered projects
aos -p portfolio d "Add page"    # Work on portfolio project
aos -p giap auto "Fix auth"      # Work on GIAP project

4. Health Validation¶

72 automated checks with self-repair capability:

aos doctor              # Run all checks
aos doctor --fix        # Auto-repair common issues
aos doctor --strict     # Treat warnings as failures

Checks include: - YAML syntax validation - Provider CLI availability - Directory permissions - Log schema conformance - Memory file integrity

5. Structured Output Modes¶

Control output format for different use cases:

Security Engineering Highlights¶

Audit-Grade Logging¶

Every execution produces machine-readable JSON logs:

{
  "run_id": "7c956f40-ada8-456c-8fbb-54c22de65b55",
  "profile": "dev",
  "provider": "codex",
  "timestamp_start": "2025-12-23T14:32:07Z",
  "timestamp_end": "2025-12-23T14:32:45Z",
  "exit_code": 0,
  "tags": ["profile:dev", "provider:codex", "memory:on"],
  "sections": {
    "plan": ["..."],
    "code_changes": ["..."],
    "verification": ["..."]
  }
}

No Hidden Behaviors¶

AgenticOS principles:

• No inference: Routing is explicit via rules or flags
• No magic: Every decision has a traceable reason
• No silent mutations: Prompts are never modified without logging
• No autonomous actions: Human triggers all executions

Memory Persistence¶

Session state persists across invocations:

.agents/memory/
├── profiles/          # Per-profile memory files
├── sessions/          # Daily session logs
├── summary.md         # Rolling summary
└── last-session.md    # Quick resume reference

Results & Metrics¶

Configuration Example¶

Profile Definition (agents.yaml)¶

profiles:
  dev:
    provider: codex
    description: Development assistant for coding tasks
    prompt_file: prompts/dev.md
    timeout: 120

  grc:
    provider: claude
    description: GRC and compliance writing
    prompt_file: prompts/grc.md
    timeout: 300

Auto-Routing Rules (router_auto_rules.json)¶

{
  "rules": [
    {
      "id": "security_policy",
      "match_any": ["policy", "compliance", "audit", "nist"],
      "route": {"type": "profile", "target": "grc"}
    },
    {
      "id": "code_fix",
      "match_any": ["fix", "bug", "error", "implement"],
      "route": {"type": "profile", "target": "dev"}
    }
  ]
}

Technical Skills Demonstrated¶

Security Automation¶

• Deterministic workflow orchestration
• Audit-grade logging pipelines
• Multi-provider API integration
• Session persistence and replay

Python Engineering¶

• CLI framework design (argparse)
• YAML/JSON configuration management
• Subprocess orchestration with timeout handling
• Regex-based output normalization

DevSecOps¶

• Self-healing health checks
• Project isolation patterns
• Provider-agnostic abstractions
• CI/CD-ready command structure

Use Cases¶

GRC Workflows¶

aos auto --smart "Draft a password policy for SOC 2"
aos -p giap g "Review control implementation evidence"

Security Development¶

aos d "Add input validation to prevent XSS"
aos auto "Fix the SQL injection in user_query()"

Quick Research¶

aos q "What are the OWASP Top 10 for 2025?"
aos q "Explain the difference between SAST and DAST"

Project Status¶

Status: Production-ready for personal/team use. Active development for additional workflows.

What This Proves¶

1. I can build secure automation — Not just use AI tools, but orchestrate them safely
2. I understand audit requirements — Every decision logged, every action traceable
3. I design for governance — Deterministic, explainable, no hidden behaviors
4. I build production-ready tools — 72 health checks, self-repair, multi-project support
5. I integrate multiple systems — Four AI providers, unified interface, 6 specialized profiles

Related Projects¶

• TraceLock™ — Multi-domain RF threat detection (uses similar logging patterns)
• GIAP™ — GRC automation platform (powered by AgenticOS)
• Homelab Infrastructure — Development environment

GitHub Repository Connect on LinkedIn Contact Me