`ce-ai` — Compound Engineering CLI Orchestrator & Workflow FSM Engine

ce-ai is a fast, safe Rust CLI for orchestrating the Compound Engineering Plugin across 10 native AI agent harnesses (opencode, claude, pi, cursor, copilot, codex, grok, kimi, agy, fx) plus custom fallback mode. It governs the 7-stage Compound Engineering Flywheel via a stage-gated FSM (deterministic bookkeeping, atomic disk writes, automated documentation debt diagnostics, and validated checkpoints).

[!NOTE]
ce-ai orchestrates distributions of the open-source Compound Engineering Plugin — a suite of specialized skills, roles, and workflow guidelines for AI coding assistants.

Quick Path

1. Install the binary (pick one):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/mastepanoski/ce-ai/main/scripts/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/mastepanoski/ce-ai/main/scripts/install.ps1 | iex

# Homebrew (macOS & Linux) — auto-taps mastepanoski/ce-ai
brew install mastepanoski/ce-ai/ce-ai

# From source
cargo install --path .

Every release publishes SHA256SUMS.txt alongside its binaries — verify any
download before running it (ISO/IEC 27002 integrity control).

2. Install the plugin into your detected AI harness(es) (add --dry-run first if you want to preview it with no writes):

ce-ai install --harness all

3. Verify system health:

ce-ai doctor

4. Adopt your project and take your first step — new here? The Getting Started guide walks through ce-ai init-prj and your very first slash command (typed inside your AI chat, not the terminal) end to end. Already comfortable? Jump to the Quick Start Workflow Guide for the full 7-stage cycle.

First install hitting 403 Forbidden? GitHub allows 60 unauth requests/hour per IP. ce-ai install/upgrade queries api.github.com — without a token you can hit the limit. Set CE_AI_GITHUB_TOKEN=ghp_xxx (or GITHUB_TOKEN / gh auth login) or pin a release: ce-ai upgrade --to v1.26.0 / ce-ai install --source <path>.

Command	Purpose	Full guide
`ce-ai init-prj [path] [--tier full\|minimal]`	Adopt project with marker-delimited `AGENTS.md` block	Project Adoption Guide
`ce-ai deinit-prj [path]`	Surgically restore pre-adoption file state	Project Adoption Guide
`ce-ai install [--scope workspace\|--scope global]`	Install per harness or workspace-isolated	Installation & Coexistence
`ce-ai status` / `ce-ai doctor`	Inspect installed harnesses, adoption & health	—
`ce-ai skills list/resolve/doctor`	Query, resolve skills & check registry health	Skill Registry Guide
`ce-ai sync`	Reconcile drift against the SHA256 manifest	Sync & Upgrade Mechanisms
`ce-ai upgrade --to <tag>`	Upgrade the plugin to a release tag	Sync & Upgrade Mechanisms
`ce-ai models set/list/profile …`	Assign models per agent slot, snapshot profiles	Quick Start Workflow Guide
`ce-ai uninstall --harness <name>`	Restore pre-install configuration cleanly	Backup & Uninstall
`ce-ai archive [compact]`	Archive completed features and roll up historical changes	—
`ce-ai self-update`	Update ce-ai CLI binary to latest release	Sync & Upgrade Mechanisms

Documentation Map

Document	Audience	Intent
🌱 Getting Started	Absolute beginner	Tutorial — zero to your first slash command, no assumed knowledge
🚀 Quick Start Workflow Guide	Beginner	Tutorial — greenfield setup, first feature, bug fix, resumption
🎓 Compound Workflow Explained	Beginner	Explanation — strategy to code, 6-level hierarchy, OpenSpec vs Brainstorm
🎓 Documentation Debt & Hygiene	Beginner	Explanation — preventing AI hallucinations, OpenSpec lifecycle & archive compaction
📁 Project Adoption Guide	Both	How-to — non-destructive AGENTS.md adoption, de-init, tiers
🎓 Harnesses, Loops & Context Masterclass	Beginner	Explanation — what a harness is, MCP sidecars, token economics
🎓 Determinism & ce-ai Explained	Beginner	Explanation — what ce-ai guarantees, why LLM execution cannot be deterministic
🎓 Zero-Step Drift Recovery	Beginner	Explanation — eliminating 5–8 turns of observation lag via live RepoState sync
🔧 Installation & Coexistence	Both	How-to — scopes, non-destructive JSON merging, discovery
🔄 Sync & Upgrade Mechanisms	Both	How-to — drift repair, upgrades, rollbacks
⚡ Skill Registry Guide	Both	How-to / Reference — skill index, 4-tier precedence, resolution
💾 Backup & Uninstall	Both	How-to — backups, clean uninstall, state cleanup
🗂️ Harness Matrix	Reference	Reference — all supported harnesses (10 native + custom), config paths, merge strategies
🏛️ Architectural & Conceptual Guide	Senior	Explanation — adapter traits, scope hierarchy, atomic writes
🎮 FSM & Checkpoints Masterclass	Senior	Explanation — 7-stage cycle, savegames, sub-loops
⚖️ Checkpoints vs. Memory & Planning Files	Beginner	Explanation — why checkpoints are a validated CLI write, not an Engram/handoff note or a `task_progress.md`
🧭 Workflow Panel: Native vs Agent Skills	Beginner	Explanation — why the TUI dashboard runs some actions and only points to others
📐 OpenSpec specifications	Senior	Reference — archived SSOT package: proposal, exploration, design, spec, tasks
🧠 Solutions Library · Plans & Audits	Contributor	Reference — solved problems, architecture decisions, delivery history

Security, Governance & Quality Gates

Security policy: SECURITY.md — ISO/IEC 27001/27002, NIST CSF 2.0, vulnerability disclosure.
AI governance: AI_POLICY.md — ISO/IEC 42001, NIST AI RMF 1.0.
Disclaimer: DISCLAIMER.md — AI-co-created, experimental software under active development.
Contributing: CONTRIBUTING.md · Code of Conduct: CODE_OF_CONDUCT.md · Docs style guide: docs/references/docs-styling.md.
CI: GitHub Actions runs build + tests, clippy -D warnings, cargo audit, and a Docker E2E gate on every PR.
Local verification: cargo test (unit/integration) · make e2e (containerized E2E).

Acknowledgments

ce-ai takes deep inspiration from the open-source ecosystem: gentle-ai, Engram, CodeGraph, Context7, RTK, and Sequential Thinking.

License

Distributed under the MIT License.

ce-ai — Compound Engineering CLI Orchestrator & Workflow FSM Engine