{"id":"2d1e0d91-a119-41a0-82bf-35cfba690c41","slug":"open-agent-engine","kind":"skill","name":"open-agent-engine","summary":"The open-source compiler & multi-agent runtime for coding agents","owner":"jedmamosto","repoUrl":"https://github.com/jedmamosto/open-agent-engine","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-08-20T01:24:06.000Z","addedAt":"2026-10-22T01:41:56.432Z","logoUrl":"https://avatars.githubusercontent.com/u/124409966?u=a9ecba301f00a8d7940b41f7d6afca88d2ffce10&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T20:19:27.565Z","sample":false,"url":"https://conduits.dev/tools/open-agent-engine","language":"TypeScript","transports":["stdio"],"install":{"npm":"open-agent-engine"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Open Agent Engine 🚀\n\n> **The open-source compiler & multi-agent runtime for coding agents.**  \n> Write canonical agent architecture once (`.agents/`). Transpile into Claude Code, Cursor, Windsurf, Roo Code, Aider, and Linux Foundation AAIF native configurations in milliseconds.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![CI Status](https://img.shields.io/badge/Tests-136%20Passed-brightgreen.svg)]()\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)]()\n[![Node](https://img.shields.io/badge/Node-%3E%3D20.0.0-green.svg)]()\n\n---\n\n## 💡 Why Open Agent Engine?\n\nModern AI coding agents (Claude Code, Cursor, Windsurf, Roo Code, Aider) are powerful, but developers face massive friction:\n- **Prompt Drift & Context Exhaustion**: Giant monolithic prompt files blow past token limits, degrade reasoning, and invalidate prompt caching.\n- **Vendor Lock-in**: Every tool invents its own bespoke config format (`CLAUDE.md`, `.cursor/rules/*.mdc`, `.windsurfrules`, `.roomodes`, `.aider.conf.yml`).\n- **No Modular Skill Sharing**: No standard way to install, version, or share progressive disclosure agent skills.\n- **Cowboy Coding on Main**: Agents edit shared working directories without branch isolation, causing dirty git trees and collisions.\n\n**Open Agent Engine solves this with 4 core pillars:**\n\n```mermaid\nflowchart TD\n    Canonical[\"Canonical Core (.agents/)<br>(Personas, Rules &lt; 150 lines, Skills, Hooks)\"]\n    Compiler[\"agent-engine build<br>(Zero-loss Transpiler)\"]\n    \n    Canonical --> Compiler\n    \n    Compiler --> C1[\"Claude Code (CLAUDE.md)\"]\n    Compiler --> C2[\"Cursor (.cursor/rules/*.mdc)\"]\n    Compiler --> C3[\"Windsurf (.windsurfrules)\"]\n    Compiler --> C4[\"Roo Code (.roomodes)\"]\n    Compiler --> C5[\"Aider (.aider.conf.yml)\"]\n    Compiler --> C6[\"Universal AAIF (AGENTS.md)\"]\n```\n\n1. 🧙‍♂️ **Interactive Scaffolding Wizard (`init`)**: Sets up an AAIF-compliant multi-agent architecture in 1 second.\n2. ⚡ **Multi-Platform Compiler (`build`)**: Transpiles canonical `.agents/` AST into 6 native target configurations with zero loss.\n3. 📦 **SkillHub Package Manager (`skill`)**: \"shadcn for Agent Skills\" — install, author, and version progressive disclosure markdown skills directly in your repository.\n4. 🌿 **Ephemeral Worktree Engine (`worktree`)**: Windows-resilient Git worktree isolation with exponential lock retries and merge conflict rollback.\n\n---\n\n## ⚡ Quick Start\n\n### 1. Initialize Your Workspace\nIn any project directory, run:\n\n```bash\nnpx agent-engine init\n```\n\nThe interactive wizard asks you which AI coding tools you use and scaffolds the canonical `.agents/` directory:\n\n```text\n┌  Welcome to Open Agent Engine\n│\n◇  What is the name of your project?\n│  my-app\n│\n◇  Which AI coding platforms are you using?\n│  ◼ Claude Code (CLAUDE.md)\n│  ◼ Cursor (.cursor/rules)\n│  ◻ Windsurf (.windsurfrules)\n│\n└  ✔ Initialized your workspace! Generated native configs in 14ms.\n```\n\n### 2. Install Battle-Tested Agent Skills\nAdd skills directly from the built-in community catalog:\n\n```bash\n# Context snapshotting and session continuity\nnpx agent-engine skill add antigravity-handoff --build\n\n# Multi-pass automated code review gate\nnpx agent-engine skill add code-reviewer --build\n\n# Multi-subagent worktree coordination\nnpx agent-engine skill add subagent-coordinator --build\n```\n\n### 3. Compile Target Configurations\nRebuild native target files whenever you update skills or personas:\n\n```bash\nnpx agent-engine build\n```\n\n---\n\n## 🎓 The Educational Mental Model: From Cowboy Prompts to Canonical Architecture\n\nModern AI agent engineering requires unlearning the anti-pattern of **monolithic prompt dumping**. Open Agent Engine teaches and enforces a high-performance mental model:\n\n### 1. The 3-Level Progressive Disclosure Framework\nInstead of forcing 3,000+ tokens of instructions into every prompt, skills disclose context on demand:\n- **Level 1 (Metadata Index ~100 tokens)**: YAML frontmatter (`name`, `description`, `triggers`) stays in active context.\n- **Level 2 (Workflow Runbook ~500 tokens)**: Step-by-step markdown loaded into context *only when triggered*.\n- **Level 3 (Deterministic Assets 0 tokens)**: Auxiliary scripts and templates executed externally.\n\n> **💡 Token Economics**: Progressive disclosure reduces active token overhead by **90%** and keeps LLM prompt prefix caches hot (>95% hit rate).\n\n### 2. The 4-Stage Operational Workflow\n\n```mermaid\nflowchart LR\n    subgraph S1[\"1. Scaffold\"]\n        A1[\"init wizard\"]\n    end\n    subgraph S2[\"2. Equip\"]\n        A2[\"skill package mgr\"]\n    end\n    subgraph S3[\"3. Transpile\"]\n        A3[\"build compiler\"]\n    end\n    subgraph S4[\"4. Isolate\"]\n        A4[\"ephemeral worktrees\"]\n    end\n    S1 --> S2 --> S3 --> S4\n```\n\nFor more learning resources:\n- 🎈 **Beginner?** Read our [Simple Beginner Guide (ELI5)](agent_docs/beginners_guide.md).\n- 📖 **Deep Dive?** Read our [Architectural Workflow & Mental Model Guide](agent_docs/workflow_and_concepts.md).\n\n---\n\n## 📦 Canonical `.agents/` Architecture\n\nOpen Agent Engine enforces a clean, progressive disclosure folder structure:\n\n```text\n.agents/\n├── config.yaml          # Project configuration, targets, and skills registry\n├── personas/            # Active agent roles with AAIF frontmatter\n│   └── default.md       # Principal Systems Architect persona\n├── rules/               # Context-lean guidelines (strictly <150 lines)\n│   └── 000-base.md      # Foundational engineering invariants\n├── skills/              # Progressive disclosure capabilities (L1, L2, L3)\n│   ├── antigravity-handoff/\n│   ├── code-reviewer/\n│   └── subagent-coordinator/\n└── hooks/               # Tool execution safety guardrails\n    └── hooks.json\n```\n\n---\n\n## 🛠️ CLI Command Reference\n\n| Command | Description |\n| :--- | :--- |\n| `agent-engine init [dir]` | Interactive scaffolding wizard for new or existing repositories |\n| `agent-engine init -y` | Non-interactive fast setup with defaults |\n| `agent-engine build` | Transpile canonical core to all configured target platforms |\n| `agent-engine tour` | Interactive 2-minute terminal tour explaining the mental model |\n| `agent-engine explain <concept>` | Visual CLI breakdown of progressive disclosure, worktrees, or targets |\n| `agent-engine doctor --explain` | Pedagogical diagnostic linter explaining the \"Why\" behind all rules |\n| `agent-engine skill list` | List all installed workspace skills and validation status |\n| `agent-engine skill list --catalog` | List installed skills + available community catalog skills |\n| `agent-engine skill add <name>` | Install a skill from catalog, local path, or URL |\n| `agent-engine skill create <name>` | Scaffold a new progressive disclosure skill template |\n| `agent-engine skill remove <name>` | Remove an installed skill and update config |\n\n---\n\n## 🧩 Supported Platforms\n\n| Platform | Target Artifacts | Features Supported |\n| :--- | :--- | :--- |\n| **Claude Code** | `CLAUDE.md`, `.claude/agents/*.md`, `.claude/settings.json` | Subagents, Tool Hooks, Invariants |\n| **Cursor** | `.cursor/rules/*.mdc` | MDC Frontmatter, Globs, AlwaysApply |\n| **Windsurf** | `.windsurfrules`, `.windsurf/rules/*.md` | Character Budgets, Cascade Invariants |\n| **Roo Code / Cline** | `.roomodes`, `.clinerules` | Custom Mode Slugs, Tool Whitelisting |\n| **Aider** | `.aider.conf.yml`, `.aider.prompt.md` | Read-only Auto-commits, Formatting |\n| **Universal AAIF** | `AGENTS.md` | Linux Foundation AAIF Specification |\n\n---\n\n## 🧪 Testing & Verification\n\nOpen Agent Engine is thoroughly tested with a 100% passing test suite across all modules:\n\n```bash\n# Run Vitest test suite\npnpm test\n\n# Run TypeScript typechecks\npnpm typecheck\n```\n\n```text\nTest Files  20 passed (20)\n     Tests  136 passed (136)\n  Duration  7.69s\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are warmly welcomed! Please read our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before submitting pull requests.\n\n---\n\n## 📄 License\n\nOpen Agent Engine is open-source software licensed under the [MIT License](LICENSE).\n"}