Adapt. Validate at runtime. Verify relentlessly. Compound carefully.
A framework-agnostic harness that helps turn LLMs into a self-monitoring, self-improving, wrong-route-blocking agentic workforce.
Quick Start · Features · Comparison · Architecture · v5.0 Protocols · Contributing
Agentic AI projects fail for the same 18 reasons, again and again:
- Agents hallucinate DAG transitions and call the wrong tools.
- State drifts silently between sessions.
- Workers claim "done" without evidence.
- Context bloat causes forgetting.
- Embarrassing artifacts get committed to production.
- No one knows what the active wave is after a crash.
- Duplicate or contradictory rows appear in state files.
- Old processes run with wrong parameters.
- Documentation links point nowhere.
- Metrics are stated two different ways.
- Configs silently revert.
- Errors are swallowed by fallback code.
- READMEs show stale results.
- Two workers edit the same file.
- New sessions have no idea where things are.
- Orchestrators hit token limits and lose state.
- Routes are tampered with or undetected.
- Unauthorized tool calls cause destructive actions.
Existing frameworks (LangGraph, CrewAI, AutoGen) give you primitives. Adaptoid OS adds the control stack that helps prevent, detect, and heal these failures before they ship.
curl -sSL https://raw.githubusercontent.com/Srujan0798/Adaptoid-OS/main/install.sh | bashgit clone https://github.com/Srujan0798/Adaptoid-OS.git ~/adaptoid-os
cd ~/adaptoid-os
bash validators/dogfood.sh # verify the kit
bash validators/preflight.sh # verify your projectpython3 ~/adaptoid-os/adaptor/engine.py \
--brief "Convert RFQ PDFs to structured BOQ" \
--output ./my-projectThe engine detects archetype, consults the ecosystem library, generates structure, copies validators, and runs preflight — all locally, no network, no AI session required.
| 🔒 Safety | 🚀 Speed | 🧠 Intelligence |
|---|---|---|
| Route Sentinel (pre-execution blocking) | 11 archetypes = instant fit | Typed PROJECT-INTENT.md |
| VaultMMU (SHA-256 hash chain) | 5 core workflow templates | 18 failure modes with validators |
| OAP Security (deterministic policies) | Slash commands with cost caps | Self-improvement protocol (GEPA + Hermes) |
| 18 executable validators | Parallel conductor pattern | Living-folder memory bank |
| 7-layer verification stack | Engine-driven project generation | v5.0 self-monitoring & evolution layer |
A single giant markdown bloats the context window. Agents read it once, then forget the middle, then contradict it.
Adaptoid OS uses progressive disclosure:
- Kernel (~2K tokens) — loaded every session
- Protocols — loaded on trigger
- Failure Modes — loaded when symptom appears
- Ecosystem — pulled like books from a shelf, then closed
Adaptoid OS is not a replacement for the frameworks below. It is a harness layer you can use with or without them.
| Dimension | LangGraph | CrewAI | AutoGen | Adaptoid OS |
|---|---|---|---|---|
| Primary focus | Stateful graphs | Role-based crews | Conversational agents | Control stack / harness |
| Framework agnostic | LangChain ecosystem | CrewAI | Microsoft ecosystem | ✅ Sovereign core + optional bridges |
| Typed intent capture | Manual | Manual | Manual | ✅ PROJECT-INTENT.md + JSON Schema |
| Failure-mode library | — | — | — | ✅ 18 FMs + validators |
| Deterministic safety layer | Checkpoints | — | — | ✅ Route Sentinel + VaultMMU + OAP |
| Living-folder memory | In-graph | In-crew | In-chat | ✅ Markdown + SQLite + Obsidian-ready |
| Self-validation | — | — | — | ✅ dogfood + preflight validators |
| Self-monitoring / consciousness | — | — | — | ✅ Consciousness Core protocol |
| Proactive assistant mode | — | — | — | ✅ Proactive Assistant protocol |
| Self-improving evolution | — | — | — | ✅ Evolution Engine protocol |
LangGraph is excellent for durable, resumable graphs. Use Adaptoid's claw_bridge/langgraph_adapter.py when you want to export a plan to LangGraph.
CrewAI is great for quick role-based demos. Use the crewai_adapter.py when that model fits.
AutoGen shines for conversational multi-agent debate. Use the autogen_adapter.py for those waves.
Adaptoid OS focuses on the layer those frameworks do not: a failure-mode-aware control stack that stays independent.
The v5.0 protocol layer adds self-monitoring, durable memory-identity, safe evolution, proactive assistance, and workflow patterns on top of the v4.0 kernel. It is a protocol layer, not a franchise claim.
| Protocol | One-liner |
|---|---|
| Consciousness Core | Self-monitoring, runtime introspection, and honest status reporting. |
| Memory-Identity | Persistent agent identity, session continuity, and memory-integrity rituals. |
| Evolution Engine | Experimental prompt, skill, and workflow evolution with falsification gates. |
| Proactive Assistant | Proactive assistant mode: anticipate, surface, escalate, never interrupt. |
| Hidden Gems | Discover, evaluate, and integrate lesser-known tools and patterns. |
| Fable 5 Workflows | The v5.0 workflow library for long-horizon, multi-agent, and self-improving tasks. |
| Super-Prompt | Meta-prompt system for composing, versioning, and testing system prompts. |
See protocols/super-adaptoid/README.md for the full layer overview.
┌─────────────────────────────────────┐
│ Layer 3: v5.0 Protocols │
│ consciousness · memory · evolution │
├─────────────────────────────────────┤
│ Layer 2: Public Product │
│ README · docs/launch · ecosystem │
├─────────────────────────────────────┤
│ Layer 1: Adaptoid Kernel (v4.0) │
│ principles · protocols · validators│
└─────────────────────────────────────┘
The 7-Layer Verification Stack:
- L1 Schema validation (<50µs)
- L2 Deterministic / evidence grounding (<100µs)
- L3 LLM self-check
- L4 Critic / cross-verify
- L5 Source grounding / sandbox execution
- L6 VaultMMU state hash
- L7 Route Sentinel pre-route blocking
adaptoid-os/
├── README.md ← you are here
├── AGENTS.md ← cold-start contract (read first!)
├── INDEX.md ← agent navigation table
├── 00-INVOCATION.md ← paste-and-go prompt
├── CHANGELOG.md
├── ROADMAP.md
│
├── kernel/ ← ALWAYS loaded (~2K tokens)
│ ├── PRINCIPLES.md 12 non-negotiable laws
│ ├── TWO-TIER.md Brain/Hands/Session
│ └── ANTI-HALLUCINATION.md drift prevention
│
├── philosophy/ ← the Three Pillars
│ ├── LLM-as-OS.md
│ ├── freedom-responsibility.md
│ └── harness-engineering.md
│
├── patterns/ ← 10 extracted best practices
│ ├── parallel-conductor.md
│ ├── six-enforced-questions.md
│ ├── closed-learning-loop.md
│ └── ...
│
├── failure-modes/ ← 18 real failures + prevention
│ ├── FM-01-state-drift.md
│ ├── FM-16-wrong-route.md
│ ├── FM-17-tampered-state.md
│ └── ...
│
├── protocols/ ← load on trigger
│ ├── route-sentinel.md
│ ├── vault-mmu.md
│ ├── oap-security.md
│ ├── self-improvement.md
│ └── super-adaptoid/ v5.0 consciousness + evolution protocols
│
├── archetypes/ ← 11 adaptation profiles
├── workflows/ ← 5 core + domain YAML
├── slash-commands/ ← named orchestrator API
├── memory-bank/ ← living folder memory
├── validators/ ← 20+ executable scripts
├── templates/ ← project skeleton
├── docs/launch/ ← v5.0 positioning + growth playbook
├── reference/ecosystem/ ← DevKit library
├── setup/harness/ ← Docker Compose stack
└── schemas/ ← JSON Schema specs
read kernel/ → detect archetype → pick tier → generate structure
→ run validators/preflight.sh → dispatch wave-1 → workers execute
→ review (evidence required) → merge → ship → next wave
→ on ANY anomaly: consult failure-modes/ → add validator
We welcome contributions! See CONTRIBUTING.md for guidelines.
Every critical bug found in production → add a new FM file + regression test + validator. The library only grows.
MIT — see LICENSE
⭐ Star this repo if it saves you from one agentic failure.
A design-first harness built from real project post-mortems, research synthesis, and ecosystem gap analysis. Every claim links to a validator or ADR.