ai-engineering 0.1.0

AI governance framework for secure software delivery

Open-source governance framework for AI-assisted software delivery

ai-engineering turns any repository into a governed AI workspace. One command installs quality gates, security scanning, and risk management — enforced locally through git hooks so problems are caught before code leaves your machine. It works with Claude Code, GitHub Copilot, Gemini CLI, and OpenAI Codex out of the box.

Install · Quick start · How it works · What you get · Governance root · Commands · AI providers · Contributing

Install (recommended)

pip install ai-engineering

Or with uv:

uv pip install ai-engineering

Requires Python 3.11+ and Git.

Quick start

cd your-project
ai-eng install .                           # bootstrap governance + git hooks
ai-eng doctor                              # verify everything is operational
git commit -m "first governed commit"      # quality gates run automatically

Install with a specific stack and IDE:

ai-eng install . --stack python --ide vscode

Your next commit after install is already governed — formatting, linting, and secret scanning run automatically.

How it works (short)

ai-engineering is a content framework, not a platform. The governance layer is Markdown, YAML, and JSON living inside your repository. The CLI (ai-eng) handles lifecycle operations — install, update, doctor, validate — while git hooks enforce quality and security at every commit and push.

your-project/
├── .ai-engineering/            ← governance root (content-first)
│   ├── standards/              ← rules for AI agents and quality gates
│   ├── skills/                 ← 45 procedural skills AI agents execute
│   ├── agents/                 ← 15 agent personas with behavioral contracts
│   ├── context/                ← project memory: specs, goals, learnings
│   └── state/                  ← decisions, risks, audit trail
├── .claude/commands/           ← 60 slash commands (Claude Code)
├── .github/prompts/            ← 45 prompt files (GitHub Copilot)
├── .github/agents/             ← 15 custom agents (GitHub Copilot)
├── GEMINI.md                   ← instruction file (Gemini CLI)
├── .git/hooks/                 ← quality gate hooks (auto-installed)
└── ...your code

Three ownership boundaries keep your content safe:

• Framework-managed — standards and baselines, updated by ai-eng update. Dry-run by default.
• Team-managed — your team's rules and overrides. Never overwritten by framework updates.
• Project-managed — specs, product goals, learnings. Never overwritten. Your project memory stays yours.

What you get

• Quality gates at every commit — ruff, gitleaks, semgrep, pip-audit, pytest, and ty run at the right stage. Problems are blocked before they reach the remote repository.
• Security scanning without CI — secrets, SAST/OWASP vulnerabilities, and dependency CVEs are detected locally on every push.
• Risk acceptance lifecycle — accept, track, and expire security risks with severity-based deadlines (critical: 15 days, high: 30, medium: 60, low: 90). Max 2 renewals per risk.
• 45 procedural skills — structured procedures for commit, PR, debug, refactor, code review, security assessment, architecture review, and more. AI agents read and execute them.
• 15 agent personas — behavioral contracts for principal engineer, architect, security reviewer, test master, debugger, and others. Each agent has identity, capabilities, and boundaries.
• Multi-provider from day one — same governance works with Claude Code (60 slash commands), GitHub Copilot (45 prompt files + 15 custom agents), Gemini CLI, and OpenAI Codex.
• Stack-aware enforcement — tailored rules for Python, .NET, and Next.js. Each stack has its own linting, testing, and security toolchain.
• Content integrity validation — 6 programmatic categories verify that governance files stay consistent across updates.
• Doctor diagnostics — one command checks framework health and auto-fixes missing hooks or tools.
• Framework updates without risk — ai-eng update previews changes. Add --apply to write them. Your team and project content is never touched.

The governance root — .ai-engineering/

When you run ai-eng install, a .ai-engineering/ directory is created in your repository. This is the single source of truth for all governance behavior. Everything is content — Markdown, YAML, JSON — readable by humans and AI agents alike.

Standards

Rules and conventions that AI agents and quality gates follow.

Standards use a two-layer model. The framework layer (standards/framework/) provides the baseline — coverage thresholds, complexity limits, security requirements. The team layer (standards/team/) is where you add overrides. Your team can raise the coverage threshold from 90% to 95%, add stricter linting rules, or define project-specific conventions. Framework updates never touch the team layer.

Each supported stack (Python, .NET, Next.js) has its own standards file with tailored rules for linting, formatting, testing, and dependency management.

Skills — 45 across 6 categories

Skills are step-by-step procedures written in Markdown that any AI agent can read and execute. They define what the agent does, when to trigger, how to execute, and what to output.

Category	Count	Highlights
Workflows	5	/commit, /pr, /acho, /cleanup, /self-improve
Dev	10	/dev:debug, /dev:refactor, /dev:code-review, /dev:test-runner, /dev:migration
Review	6	/review:architecture, /review:security, /review:data-security, /review:dast
Docs	5	/docs:changelog, /docs:explain, /docs:simplify, /docs:writer
Govern	12	/govern:create-spec, /govern:integrity-check, /govern:accept-risk, /govern:create-agent
Quality	6	/quality:audit-code, /quality:release-gate, /quality:sbom, /quality:test-gap-analysis

Skills are provider-agnostic — the same skill works in Claude Code, GitHub Copilot, Gemini CLI, and OpenAI Codex without modification.

Agents — 15 specialized personas

Agents are behavioral contracts for AI. Each agent has an identity, capabilities, activation rules, referenced skills, output contract, and boundaries.

Agent	Role
principal-engineer	Senior-level code review and standards enforcement
architect	Architecture analysis, design patterns, scalability
security-reviewer	Security assessment, OWASP, threat modeling
test-master	Test strategy, coverage analysis, test design
debugger	Systematic diagnosis, root cause analysis
quality-auditor	Quality gate enforcement, complexity and coverage checks
docs-writer	Documentation authoring and user-facing content
devops-engineer	CI/CD pipeline generation and delivery automation
orchestrator	Multi-phase execution coordination across agents
navigator	Strategic analysis for next specs and priorities
governance-steward	Governance lifecycle and standards evolution
platform-auditor	Full-spectrum audit orchestration
pr-reviewer	Headless CI pull request review
code-simplifier	Complexity reduction and readability improvements
verify-app	End-to-end verification and smoke testing

Activate any agent with /agent:<name> — for example, /agent:architect for architecture review or /agent:security-reviewer for a threat assessment.

Context — your project memory

Context is where your project lives. Product goals, active specifications, institutional learnings — all stored as Markdown files that AI agents read to understand your project.

The spec-driven delivery model tracks work through four documents:

• spec.md — what to build (requirements, scope, acceptance criteria)
• plan.md — how to build it (architecture decisions, approach, trade-offs)
• tasks.md — what to do (ordered, assignable, trackable tasks)
• done.md — what was done (completion log, learnings captured)

Any AI agent can resume work on any spec by reading _active.md → spec.md → tasks.md. No context is lost between sessions.

Context is project-managed — the framework never overwrites it.

State — decisions, risks, and audit trail

State files track runtime information automatically:

• decision-store.json — decisions persist across AI sessions with SHA-256 context hashing. No repeated questions — agents check the store before asking.
• audit-log.ndjson — append-only log of every governance event (gate results, commands executed, lifecycle transitions).
• install-manifest.json — what was installed, when, which version.
• ownership-map.json — who owns each path in the governance root.
• sources.lock.json — remote skill sources with checksum verification.

State is system-managed — maintained automatically by the CLI and git hooks.

Commands (reference)

Core commands you use daily:

ai-eng install [TARGET]           # Bootstrap governance in any project
ai-eng update [TARGET]            # Preview framework updates (dry-run)
ai-eng update [TARGET] --apply    # Apply framework updates
ai-eng doctor [TARGET]            # Diagnose and auto-fix framework health
ai-eng validate [TARGET]          # Validate content integrity
ai-eng version                    # Show installed version and lifecycle status

Additional command groups for stack/IDE management, quality gates, skills, maintenance, VCS configuration, and CI/CD are documented in the CLI reference.

AI provider setup

ai-engineering generates integration files for each AI provider during install.

Claude Code (recommended)

The framework generates CLAUDE.md (instruction file) and 60 slash commands in .claude/commands/. Run /commit to stage, validate, commit, and push. Run /agent:debugger to activate the debugger persona. All commands invoke canonical skill and agent files — no content is duplicated.

Gemini CLI

The framework generates GEMINI.md (instruction file) for Gemini CLI. It provides context and rules similar to CLAUDE.md. The same governance, skills, and conventions apply automatically.

GitHub Copilot

The framework generates .github/copilot-instructions.md, 45 prompt files in .github/prompts/, and 15 custom agents in .github/agents/. Use prompts like /commit or /dev-debug and agents like @security-reviewer or @architect directly in Copilot Chat.

OpenAI Codex

Codex CLI reads AGENTS.md natively — no separate instruction file needed. The same governance, skills, and conventions apply automatically.

Switch providers at any time — the governance layer is the same. Skills and agents are Markdown, not provider-specific code.

Configuration

ai-engineering uses a content-first approach — configuration lives in .ai-engineering/ as Markdown, YAML, and JSON files.

At install time, control which stacks and IDEs to enable via --stack and --ide flags. Add or remove them later with ai-eng stack and ai-eng ide commands.

Updates are dry-run by default. Run ai-eng update to preview, then ai-eng update --apply to write. The updater only touches framework-managed files.

Doctor remediation provides --fix-hooks to reinstall git hooks and --fix-tools to auto-install missing tools (ruff, ty, gitleaks, semgrep, pip-audit).

Risk lifecycle enforces severity-based expiry:

Severity	Expiry	Max renewals
Critical	15 days	2
High	30 days	2
Medium	60 days	2
Low	90 days	2

Expired risks block git push until you remediate or renew them.

Tooling baseline

Tool	Purpose
uv	Package and runtime management
ruff	Linting and formatting
ty	Type checking
pip-audit	Dependency vulnerability scanning
gitleaks	Secret detection
semgrep	Static analysis (SAST/OWASP)

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