ai-engineering

Open-source AI governance framework

47 skills. 10 agents. 4 IDEs. One governed workflow.

AI governance that developers actually want -- for teams that ship.

ai-engineering turns any repository into a governed AI workspace. Governance is content-first: policies, skills, agents, runbooks, and specs all live as versioned files inside the repo -- no hosted control plane, no vendor lock-in. It works across Claude Code, GitHub Copilot, OpenAI Codex, and Gemini CLI from the same repository.

Install · Quick Start · What You Get · How It Works · CLI · Slash Commands · Inspirations · Contributing

Install

Prerequisites: Python 3.11+ and Git.

Recommended: pipx (isolated, global)

pipx install ai-engineering

Alternative: uv

uv tool install ai-engineering

Fallback: pip (requires a virtual environment)

python -m venv .venv && source .venv/bin/activate
pip install ai-engineering

Verify

ai-eng version

Update to latest version

# pipx
pipx upgrade ai-engineering

# uv
uv tool upgrade ai-engineering

# pip
pip install --upgrade ai-engineering

After upgrading, run ai-eng update in each project to pull the latest skills, contexts, and runbooks, then ai-eng doctor to verify.

Quick Start

cd your-project
ai-eng install .
ai-eng doctor

install scaffolds the governance root, detects your stack, and mirrors skills to every configured IDE. It also auto-installs missing tools (ruff, gitleaks, ty, pip-audit) via your OS package manager. doctor validates the installation, checks tooling, and reports anything that needs attention.

See GETTING_STARTED.md for the full tutorial.

Migration -- spec-101 install contract (BREAKING)

Starting with this release ai-eng install and ai-eng doctor --fix --phase tools enforce a hard, data-driven contract. If you are upgrading from a pre-spec-101 install, walk through this section once.

EXIT 80 / EXIT 81 -- hard fail on missing tooling

Two reserved exit codes replace the previous best-effort silent pass:

Migration: remove any ai-eng install || true shielding from your CI scripts. The framework now surfaces failures explicitly so you can fix them, not paper over them. If a tool is genuinely unsupported on a host OS, declare it via platform_unsupported (tool-level, max 2 of 3 OSes) or escalate via platform_unsupported_stack (stack-level, may list all 3) -- both require a non-empty unsupported_reason (D-101-03 + D-101-13). See .ai-engineering/manifest.yml > required_tools for working examples.

platform_unsupported -- tool vs stack scope

Two governance keys control where unsupported markers may appear:

• platform_unsupported lives on a single tool inside a stack's tool list. Caps at 2 of 3 OSes; using it for all 3 is rejected by the model validator. Example: semgrep carries platform_unsupported: [windows].
• platform_unsupported_stack lives on the entire stack block when the whole toolchain has no native binaries on a given OS. May list all 3 OSes. Example: the swift stack carries platform_unsupported_stack: [linux, windows] because swiftlint and swift-format ship for macOS only.

Both keys require an unsupported_reason field; the lint refuses an unreasoned escalation.

python_env.mode decision tree

python_env.mode defaults to uv-tool. Three values exist:

                       ┌──────────────────────────────────┐
Need a fresh worktree  │  uv-tool   (default, recommended)│
to be fast (< 30 s)?   │   tools install once into        │
                       │   ~/.local/share/uv/tools/       │
                       └──────────────────────────────────┘
                                       │
                                       ▼
                Need .venv/ for legacy   ┌──────────────────────────┐
                workflows                │  venv                    │
                (source .venv/bin/...)?  │   per-cwd .venv/         │
                                         │   classic, slow worktree │
                                         └──────────────────────────┘
                                       │
                                       ▼
                Want a single .venv      ┌──────────────────────────┐
                shared across worktrees  │  shared-parent           │
                (requires git repo)?     │   .venv at repo root,    │
                                         │   linked from worktrees  │
                                         └──────────────────────────┘

Set the value in .ai-engineering/manifest.yml:

python_env:
  mode: uv-tool   # or: venv | shared-parent

A full reference (.ai-engineering/contexts/python-env-modes.md) covers migration commands and trade-offs.

14 stacks covered by required_tools

A single manifest.yml > required_tools block drives both ai-eng install and ai-eng doctor --fix. The 14 supported stacks are:

Plus a universal baseline block (gitleaks, semgrep, jq) that applies to every stack.

First-run banner

The first install after upgrading prints a one-shot BREAKING banner to stderr. The banner mentions EXIT 80/81, the python_env.mode flip, and the 14-stack scope. It only fires once per project -- the flag persists in .ai-engineering/state/install-state.json (breaking_banner_seen).

What You Get

47 Skills

Skills are slash commands that encode team workflows as repeatable, governed procedures. Each skill carries its own trigger patterns, validation gates, and output contracts.

10 Agents

Agents are role-based specialists that skills dispatch to. Each agent has a defined mandate, boundaries, and output contract.

14 Runbooks

Self-contained Markdown automation contracts. Each runbook carries its own purpose, cadence, hierarchy rules, and expected outputs. All are human-in-the-loop: they prepare work items but never touch code.

Contexts

14 language contexts (bash, C++, C#, Dart, Go, Java, JavaScript, Kotlin, PHP, Python, Rust, SQL, Swift, TypeScript) and 15 framework contexts (Android, API Design, ASP.NET Core, Backend Patterns, Bun, Claude API, Deployment Patterns, Django, Flutter, iOS, MCP SDK, Next.js, Node.js, React, React Native) ship with the framework. These are loaded at session start based on your project's detected stack and applied to all code generation and review.

Quality Gates

Enforced on every commit, not just in CI.

Tooling: ruff + ty (lint/format), pytest (test), gitleaks (secrets), pip-audit (deps).

How It Works

ai-eng install . creates a governance root alongside IDE-specific mirrors:

your-project/
├── .ai-engineering/          # governance root
│   ├── contexts/             # language, framework, and team context
│   ├── runbooks/             # automation contracts
│   ├── runs/                 # autonomous execution state
│   ├── scripts/              # hooks and helpers
│   ├── specs/                # active spec and plan
│   ├── state/                # decisions, events, capabilities
│   └── LESSONS.md            # persistent learning across sessions
├── .claude/                  # Claude Code skills + agents (canonical)
├── .codex/                   # OpenAI Codex mirror
├── .gemini/                  # Gemini CLI mirror
├── .github/                  # GitHub Copilot mirror
├── AGENTS.md                 # Codex instruction file
├── CLAUDE.md                 # Claude Code instruction file
└── GEMINI.md                 # Gemini CLI instruction file

Three ownership boundaries

Multi-IDE mirroring

.claude/ is the canonical surface. Running ai-eng sync regenerates all other IDE mirrors (.codex/, .gemini/, .github/) from the canonical source. One set of skills, consistent behavior across all four IDEs.

CLI Commands

Slash Commands

Skills are invoked as slash commands inside your IDE. The two primary flows:

Spec-driven flow

The default path for planned work after install and health-check:

/ai-start  -->  /ai-brainstorm  -->  /ai-plan  -->  /ai-dispatch  -->  /ai-verify  -->  /ai-pr
  (start)       (spec)              (plan)        (execute)          (evidence)       (ship)

Backlog-driven flow

Autonomous execution against a work-item backlog:

/ai-run  -->  intake  -->  explore  -->  waves  -->  /ai-pr
 (start)    (filter)    (context)    (execute)     (ship)

Key commands

Standing on the shoulders of...

ai-engineering builds on ideas, patterns, and principles from these projects:

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, code style, testing, and pull request guidelines.

Code of conduct

This project follows the Contributor Covenant Code of Conduct. See CODE_OF_CONDUCT.md.

License

MIT. See LICENSE.