AI Engineering Loop

A Reusable, Framework-Agnostic AI Engineering Operating System for Safe Coding Agents

Move beyond linear AI pipelines and optimistic self-evaluation toward contract-driven execution, deterministic machine verification, independent adversarial review, and living project context.

Quickstart CLI

Run the CLI in any repository root without global installation:

# 1. Bootstrap .ai-engineering-loop/ context from repository discovery
npx ai-engineering-loop init

# 2. Check the validity, readiness, and baseline freshness of context
npx ai-engineering-loop status

# 3. Reconcile drifted context against repository non-destructively
npx ai-engineering-loop refresh

# 4. Verify context readiness and begin engineering loop
npx ai-engineering-loop run

# Optional: analysis without repository mutation
npx ai-engineering-loop run --mode report-only "audit this repository"

# Inspect spend controls; ASSISTED is the default
npx ai-engineering-loop policy show
npx ai-engineering-loop budget status
npx ai-engineering-loop policy set --review-profile lean
npx ai-engineering-loop context query createStudioRun
npx ai-engineering-loop context fast-path --json
npx ai-engineering-loop context diff-hunks --run <run-id>
npx ai-engineering-loop verification summarize --run <run-id>
npx ai-engineering-loop context compact --run <run-id>

# Author and observe deterministic workflow recipes locally
npx ai-engineering-loop studio

# Export a redacted, integrity-bound knowledge handoff
npx ai-engineering-loop handoff create --audience developer

# 5. Copy package host skills into ~/.claude ~/.grok ~/.gemini ~/.agents
#    Default: core pack (ai-engineering-loop skill, DA/Judge agents, commands).
#    Optional: --pack backend,design (saved for later syncs); --prune removes them again.
npx ai-engineering-loop sync-hosts
npx ai-engineering-loop sync-hosts --pack backend,design

# Read one packaged spec instead of the whole package source
npx ai-engineering-loop docs grill-policy --section "When to grill"

What It Does

1. Zero-Config Discovery (init): Analyzes repository topology (monorepo vs single app), package manifests (package.json, go.mod, Cargo.toml, etc.), frameworks, and test scripts to generate .ai-engineering-loop/ including glossary.md and adrs/.
2. Living Project Context: Tracks repository revisions and manifest checksums in metadata.json for instant drift detection. Stage 1 grill freezes a Goal Contract; Maker uses TDD at named seams; DA reports Spec vs Standards without merging them.
3. Multi-Agent Triad: Coordinates Maker (surgical diffs & tests), Devil's Advocate (independent adversarial review), and Judge (impartial evaluation & PASS certification).
4. Context Impact Assessment: Evaluates completed tasks (NONE, TARGETED, MAJOR) to keep project context fresh without expensive whole-repo re-analysis.
5. Grok CLI host: Native spawn_subagent for Devil's Advocate and Judge (TRUE_INDEPENDENT_AGENT). Disabled by GROK_SUBAGENTS=0.
6. Production runtime controls: REPORT_ONLY, human-approved ASSISTED, opt-in UNATTENDED, actual token ledgers, lean/standard/thorough review profiles, smart hunk-only context packs, a persistent kill switch, and locked disposable Maker worktrees.
7. Local Workflow Studio: A localhost-only authenticated DAG canvas with animated live stage state, token telemetry, explicit approvals, decision memory, atomic recipe installation, and redacted handoff export. It does not execute models or shell commands in the browser.

Grok CLI

Inside a Grok TUI session, /ai-engineering-loop uses repo-local .grok/agents/ types. Devil's Advocate and Judge spawn as sibling children (capability_mode: execute, no resume_from). Do not use caveman:cavecrew-reviewer as the loop reviewer.

Claude Code

Inside Claude Code, /ai-engineering-loop uses .claude/agents/ types via the Task tool. Pass only subagent_type, description, and prompt. Do not pass Grok keys (spawn_subagent, capability_mode, resume_from) — extra keys cause Kiro REQUEST_BODY_INVALID.

Antigravity IDE Integration

In Antigravity IDE or compatible agentic platforms, invoke the loop directly in chat:

• /ai-engineering-loop init — Bootstrap project context only.
• /ai-engineering-loop status — Check context health and living freshness.
• /ai-engineering-loop refresh — Reconcile drifted context files.
• /ai-engineering-loop <task> — Execute the full 8-stage engineering lifecycle.

Complete Documentation & Specifications

For the complete architectural specifications, project profiles (web-app, backend-api, mobile-app, library, monorepo), delivery adapters (GitLab, GitHub, Mattermost), and reference examples:

👉 Visit the GitHub Repository

License

MIT License — see LICENSE for details.