ai-engineering-loop 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,422 +1,220 @@
1
1
  <div align="center">
2
- <h1>AI Engineering Loop</h1>
3
2
 
4
- [![NPM Version](https://img.shields.io/npm/v/ai-engineering-loop.svg?color=cb3837)](https://www.npmjs.com/package/ai-engineering-loop)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
7
- [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
8
- [![Release](https://img.shields.io/badge/release-v1.7.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
3
+ # AI Engineering Loop
9
4
 
10
- **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
5
+ ### From idea to trusted code—without babysitting every command.
11
6
 
12
- *Featuring graduated safety modes, token budgets, isolated Maker worktrees, deterministic artifact gates, bounded secret-redacted context, and cheap-model escalation.*
7
+ Give your AI agent a goal. It plans the work, builds it, checks itself, challenges the result, and prepares a safe delivery. You get a visual workflow and a clear history instead of a wall of terminal output.
13
8
 
14
- [Overview](#overview--philosophy) • [Stage techniques](#stage-techniques) • [Runtime Capability Registry](#runtime-capability-registry--execution-modes) • [Verification Evidence](#verification-evidence-contract) • [CLI Commands](#cli-interface--commands) • [Grok CLI](#grok-cli-integration) • [Claude Code](#claude-code-integration) • [Antigravity](#antigravity-agent-integration) • [Lifecycle](#lifecycle-stages) • [Architecture](#architecture--5-layer-configuration) • [Project Profiles](#project-profiles) • [Repository Structure](#repository-structure) • [Reference Examples](#reference-examples) • [Contributing](#contributing)
9
+ [![npm](https://img.shields.io/npm/v/ai-engineering-loop?style=flat-square&color=28AD00)](https://www.npmjs.com/package/ai-engineering-loop)
10
+ [![GitHub release](https://img.shields.io/github/v/release/egagofur/ai-engineering-loop?style=flat-square&color=28AD00)](https://github.com/egagofur/ai-engineering-loop/releases)
11
+ [![license](https://img.shields.io/badge/license-MIT-181c19?style=flat-square)](LICENSE)
12
+
13
+ [Get started](#get-started-in-a-minute) · [See what it does](#one-workspace-from-idea-to-delivery) · [Open Workflow Studio](#meet-workflow-studio) · [Read the docs](core/)
15
14
 
16
15
  </div>
17
16
 
18
- ---
17
+ [![AI Engineering Loop Workflow Studio](docs/images/studio-hero.svg)](docs/images/studio-hero.svg)
19
18
 
20
- ## Overview & Philosophy
19
+ ## Software delivery that feels simple
21
20
 
22
- The AI Engineering Loop keeps one understandable path across four phases. Deterministic gates—not model confidence—decide when work can advance:
21
+ AI coding tools are fast, but important details can disappear between the prompt, the code, and the final answer. AI Engineering Loop gives every task one calm, repeatable path:
23
22
 
24
- [![AI Engineering Loop: task and context preparation flow into Specify, Make, Review, and Deliver phases. Failed verification or an ITERATE verdict returns work to Maker; PASS reaches delivery.](docs/images/engineering-loop-overview.svg)](docs/images/engineering-loop-overview.svg)
23
+ | You want | The Loop handles |
24
+ |---|---|
25
+ | **A clear outcome** | Turns the request into an agreed Goal before code changes |
26
+ | **Less supervision** | Guides your agent through planning, building, and checking |
27
+ | **Honest progress** | Shows what is ready, running, blocked, or waiting for approval |
28
+ | **Fewer surprises** | Tests happy paths, edge cases, and failure cases |
29
+ | **A trustworthy result** | Compares every claim with real evidence before delivery |
30
+ | **A useful history** | Keeps searchable Runs, decisions, artifacts, and proof |
25
31
 
26
- ---
32
+ You stay in control of the product decisions. Your AI agent takes care of the repetitive engineering ceremony.
27
33
 
28
- ## Stage techniques
34
+ ## Get started in a minute
29
35
 
30
- The 8-stage loop stays one OS. These techniques sit **inside** existing stages (they are not optional slash-command products):
36
+ Install it in any project:
31
37
 
32
- | Stage | Technique | Spec |
33
- |---|---|---|
34
- | 1 | Grill until the design-tree frontier is empty, then freeze the Goal Contract. Idea requests: menu, wait, then grill the pick. Chat `setuju` is not freeze; user-visible decisions must be numbered AC in the contract file. AC is a **failure table** (happy, empty/omit, boundary, sibling, error), not sunny path only. **Sloppy prompt** (no numbered AC): draft the Goal Contract file, show it, wait for freeze — do not Maker. Business-logic change: **blast radius** (lifecycle sketch, four pillars, ASCII picture) via `task-impact-inquiry` inside grill — not a second loop. Passing unit tests are not isolation proof. | `core/grill-policy.md` |
35
- | 1 | Ubiquitous language in `.ai-engineering-loop/glossary.md`; load-bearing choices in `.ai-engineering-loop/adrs/` | `core/repo-config-schema.md` |
36
- | 2 | Bugs: red repro → minimise → hypothesise → instrument → fix | `core/root-cause-analysis.md` |
37
- | 4 | Optional **Maker intern**: overlay `maker_intern`. Default `none`. Pick from the host catalog (`grok models` or `/models` if that command exists; numbered options). Do not type a model name. No custom endpoint. Imagine/video models are not intern picks. Unknown id → parent Maker (`INVOCATION_UNAVAILABLE`). Devil's Advocate and Judge stay on the parent. | `.ai-engineering-loop/workflow.md` |
38
- | 4–5 | Red-green at named **seams**; failure table (not happy path only); coverage is a map; no grep/tautology | `policies/tdd-policy.md` |
39
- | 5 | **Claimed vs Reality** table before DA. Missing file or empty Reality blocks Devil's Advocate. "Seems green" is not Reality. | `core/verification-loop.md` |
40
- | 6–7 | Spec vs Standards reported separately. Standards BLOCKER/HIGH iterate only when `hardConvention` is true | `policies/finding-policy.md` |
41
- | 0–8 | Stateful run ledger and deterministic artifact transitions; model claims cannot advance a stage | `core/artifact-gates.md` |
42
- | 0–8 | `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`; actual token budgets, kill switch, and locked Maker worktrees | `core/runtime-safety.md` |
43
- | any | Mid-loop stop writes `.ai-engineering-loop/tasks/handoff.md` | `core/handoff-policy.md` |
44
- | any | **Compact map** (host guidance, not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge. | host skills |
38
+ ```bash
39
+ npx ai-engineering-loop init
40
+ ```
45
41
 
46
- `init` now requires `glossary.md` and `adrs/README.md`. Repair fills missing files only; a filled glossary is never overwritten.
42
+ Then tell your coding agent:
47
43
 
48
- ---
44
+ > Use AI Engineering Loop to build this feature: **your idea here**
49
45
 
50
- ## Runtime Capability Registry & Execution Modes
46
+ That is the intended experience. You do not need to memorize the internal commands—the agent can operate the loop for you.
51
47
 
52
- The system maintains a strict distinction between **Configuration Support**, **Invocation Availability**, and **Execution Proof**:
48
+ Want the visual workspace?
53
49
 
54
- ```text
55
- ┌───────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────┐
56
- │ CONFIGURATION_SUPPORTED │ ──> │ INVOCATION_AVAILABLE │ ──> │ EXECUTION_PROVEN │
57
- │ (Config is recognized) │ │ (Callable tool is active) │ │ (Child LLM response seen) │
58
- └───────────────────────────┘ └───────────────────────────┘ └───────────────────────────┘
50
+ ```bash
51
+ npx ai-engineering-loop studio
59
52
  ```
60
53
 
61
- ### 5 Standard Execution Modes (Deterministic Priority):
62
-
63
- | Priority | Mode Name | Requires Independent LLM Execution? | Condition for Selection |
64
- |:---:|---|:---:|---|
65
- | **1** | **`TRUE_INDEPENDENT_AGENT`** | **YES** | Child session exists **AND** actual model response is captured **AND** context is independent. |
66
- | **2** | **`ISOLATED_AGENT_INSTANCE`** | **YES** | Programmatic SDK agent instance with verified independent model execution. |
67
- | **3** | **`FRESH_PROCESS_AGENT`** | **YES** | Separate OS process successfully executes an LLM agent with fresh context. |
68
- | **4** | **`CONTEXT_ISOLATION_ONLY`** | **NO** | Clean-Slate Artifact Isolation Barrier in same session (100% prompt history excluded on disk). |
69
- | **5** | **`UNAVAILABLE`** | **NO** | No review execution mechanism is available. |
70
-
71
- ### Truthful Reporting Disclosure:
72
- When `CONTEXT_ISOLATION_ONLY` is selected, the report strictly produces:
73
- ```text
74
- Execution Mode: CONTEXT_ISOLATION_ONLY
75
- Independent LLM Execution: NOT PROVEN
76
- Native Subagent Invocation: UNAVAILABLE
77
- Review Method: Clean-Slate Artifact Isolation Barrier
78
- ```
54
+ Workflow Studio opens locally in your browser. Your project and run evidence stay on your machine.
79
55
 
80
- ---
81
-
82
- ## Verification Evidence Contract
83
-
84
- A verification `PASS` is strictly invalid without concrete execution evidence. The system categorically rejects vague statements such as *"command was launched"* or *"test appears to have passed"*.
85
-
86
- ### Mandatory Execution Proof:
87
- - **`command`**: Exact CLI string executed.
88
- - **`executionIdentity`**: PID, execution hash, or system execution identifier.
89
- - **`startTime` & `endTime`**: Documented execution duration.
90
- - **`exitCode`**: Must be `0`.
91
- - **`stdout` & `stderr`**: Raw machine logs captured.
92
- - **`timeoutStatus`**: Must be `"COMPLETED"`.
93
- - **`testCounts`**: Explicit counts of passed, failed, and skipped tests.
94
- - **`assertionEvidence`**: Specific assertion proof matching the active Goal Contract's Acceptance Criteria.
95
-
96
- ---
97
-
98
- ## Dual-Axis Finding Model & Judge Decision Matrix
99
-
100
- The Devil's Advocate categorizes findings along separate **Validity**, **Severity**, and **Disposition** axes:
101
-
102
- ```json
103
- {
104
- "id": "DA-01",
105
- "topic": "correctness",
106
- "validity": "VALID",
107
- "severity": "BLOCKER",
108
- "disposition": "STRONG",
109
- "location": "src/services/payment.ts#L42-L58",
110
- "acceptanceCriteria": "AC-2",
111
- "failureScenario": "Under concurrent traffic, duplicate rows are inserted before the lock is acquired.",
112
- "evidence": "Missing SELECT FOR UPDATE in findByPaymentKey query.",
113
- "concreteAlternativeDiff": "```diff\n- const tx = await findByKey(key);\n+ const tx = await findByKeyWithLock(key, { mode: 'FOR UPDATE' });\n```"
114
- }
115
- ```
56
+ On first setup, `.ai-engineering-loop/` is added to your project’s `.gitignore` so plans and Run evidence stay private by default. Want to share that context with your team? Simply remove that line from `.gitignore`.
116
57
 
117
- ### Judge Decision Matrix:
118
- - **`VALID + BLOCKER / HIGH`** $\rightarrow$ **`ITERATE`** (Maker must apply concrete fix diff and add regression tests).
119
- - **`VALID + MEDIUM / LOW`** $\rightarrow$ **`ACCEPT / TRADEOFF`** (Merged; documented as acceptable tradeoff in MR notes).
120
- - **`INVALID`** $\rightarrow$ **`DISMISS`** (Reviewer hallucination disproven by code; cannot block delivery; signature recorded).
58
+ ## Meet Workflow Studio
121
59
 
122
- *Reviewer disposition (`STRONG`, `ACCEPTABLE`, `WEAK`) never overrides factual evidence.*
60
+ Workflow Studio makes agent work feel like a product, not a terminal session.
123
61
 
124
- ---
62
+ ### Build workflows visually
125
63
 
126
- ## Living Project Context
64
+ - Connect steps on an open canvas
65
+ - Add the next step directly from any node
66
+ - Rename nodes in place without breaking their identity
67
+ - Select, move, duplicate, or delete groups of nodes
68
+ - Import and export workflow JSON safely
69
+ - Create your own prompt-powered Agent nodes
127
70
 
128
- The `.ai-engineering-loop/` directory is **Living Context**, not a static wiki generated once.
71
+ ### Start with a Goal—not a vague prompt
129
72
 
130
- 1. **Post-Task Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
131
- 2. **Context Baseline (`metadata.json`)**: Tracks `repositoryRevision` (git commit SHA) and `manifestChecksums` for instant Level 0 (0ms) drift verification.
132
- 3. **Strict Context Isolation**: Decouples living project context from ephemeral task logs and loop execution states.
73
+ Write the task in plain language, add the outcomes that matter, and **Freeze** the Goal when it is ready. The agent cannot quietly move the finish line after work begins.
133
74
 
134
- ---
75
+ ### Follow every Run
135
76
 
136
- ## CLI Interface & Commands
77
+ Runs have human-friendly names instead of cryptic hashes. Search previous work, inspect decisions, view evidence, and see exactly where a workflow stopped.
137
78
 
138
- The CLI package is published on NPM as [`ai-engineering-loop`](https://www.npmjs.com/package/ai-engineering-loop) and operates against the current working directory.
79
+ ### Execute with confidence
139
80
 
140
- ```bash
141
- # Bootstrap .ai-engineering-loop/ context from repository discovery
142
- npx ai-engineering-loop init
81
+ The Execute button lives beside the workflow trigger. A Run starts only when the Goal, workflow, mode, and safety checks are ready.
143
82
 
144
- # Check the validity, readiness, and baseline freshness of context
145
- npx ai-engineering-loop status
83
+ ## One workspace from idea to delivery
146
84
 
147
- # Reconcile drifted context against repository non-destructively
148
- npx ai-engineering-loop refresh
85
+ The experience is organized into four simple moments:
149
86
 
150
- # Start or resume a stateful engineering run
151
- npx ai-engineering-loop run
152
- npx ai-engineering-loop run --mode report-only "audit this repository"
153
- npx ai-engineering-loop run --recipe bugfix --mode assisted "repair retry race"
87
+ 1. **Specify** — agree on what success and failure look like.
88
+ 2. **Make** — let the agent investigate, plan, and build.
89
+ 3. **Review** — verify the result and challenge unsupported claims.
90
+ 4. **Deliver** — ask for human approval before publishing.
154
91
 
155
- # Inspect the run ledger
156
- npx ai-engineering-loop state --json
92
+ Under the hood, these moments use eight evidence-backed stages. The rigor is there when you need it, but it does not have to dominate the experience.
157
93
 
158
- # Inspect policy, opt into unattended, and operate the token kill switch
159
- npx ai-engineering-loop policy show
160
- npx ai-engineering-loop policy set --allow-unattended true
161
- npx ai-engineering-loop budget status
162
- npx ai-engineering-loop budget pause
163
- npx ai-engineering-loop budget resume
94
+ `Specify (stages 0-1)` → `Make (stages 2-4)` → `Review (stages 5-7)` → `Deliver (stage 8)`
164
95
 
165
- # Record actual provider-reported usage after each model response
166
- npx ai-engineering-loop budget record --input 1200 --output 300 --model provider/model-id
167
- npx ai-engineering-loop budget status --node root-cause --estimate 4000
168
- npx ai-engineering-loop budget record --node root-cause --input 3000 --output 700 --model provider/model-id
169
-
170
- # Isolate unattended Maker, then capture only its diff
171
- npx ai-engineering-loop sandbox create
172
- npx ai-engineering-loop sandbox capture
173
-
174
- # Validate artifacts and advance stages
175
- npx ai-engineering-loop gate goal
176
- npx ai-engineering-loop gate report
177
- npx ai-engineering-loop gate maker
178
- npx ai-engineering-loop gate verification
179
- npx ai-engineering-loop gate review
180
- npx ai-engineering-loop escalation --json
181
- npx ai-engineering-loop gate judge
182
- npx ai-engineering-loop gate delivery
183
-
184
- # Build bounded model-visible context
185
- npx ai-engineering-loop context devil-advocate <files...>
186
- npx ai-engineering-loop context judge <files...>
187
-
188
- # Validate installation and the production evaluation catalog
189
- npx ai-engineering-loop doctor
190
- npx ai-engineering-loop eval
96
+ ## Bring your own AI agent
191
97
 
192
- # Inspect declarative workflow recipes without executing nodes
193
- npx ai-engineering-loop recipe list
194
- npx ai-engineering-loop recipe validate default --mode assisted
195
- npx ai-engineering-loop recipe explain default --mode assisted
196
- npx ai-engineering-loop recipe graph default --mode assisted
197
- npx ai-engineering-loop recipe simulate default --mode assisted
198
- npx ai-engineering-loop recipe catalog --json
199
- npx ai-engineering-loop recipe create api-bugfix --from bugfix
200
- npx ai-engineering-loop recipe inspect api-bugfix --json
201
- npx ai-engineering-loop recipe diff bugfix api-bugfix
202
- npx ai-engineering-loop recipe install candidate.json
203
- npx ai-engineering-loop recipe install candidate-v2.json --replace
204
-
205
- # Operate a custom node in an immutable recipe-bound run
206
- npx ai-engineering-loop node status
207
- npx ai-engineering-loop node start root-cause
208
- npx ai-engineering-loop node activity root-cause --message "Comparing failing evidence"
209
- npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
210
- npx ai-engineering-loop node approve delivery-approval --yes
98
+ AI Engineering Loop is designed to work with the tools developers already use:
211
99
 
212
- # Open the local workflow canvas (localhost-only, authenticated session)
213
- npx ai-engineering-loop studio
214
- npx ai-engineering-loop studio --port 4400 --no-open
100
+ - **Claude Code**
101
+ - **Grok CLI**
102
+ - **Gemini / Antigravity**
103
+ - Other agent hosts that can read project instructions and run local commands
215
104
 
216
- # Transfer redacted knowledge to another developer or agent
217
- npx ai-engineering-loop handoff create --audience developer
218
- npx ai-engineering-loop handoff inspect <run-id>.ael-handoff.json
219
- npx ai-engineering-loop handoff brief <run-id>.ael-handoff.json
105
+ The project includes ready-to-use skills and reviewer roles for supported hosts. Each host follows the same Goal, verification, review, and approval rules.
220
106
 
221
- # Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
222
- npx ai-engineering-loop sync-hosts
107
+ ## Create workflows that fit your team
223
108
 
224
- # Grill (or --type) a Stage 8 delivery adapter for this repo
225
- npx ai-engineering-loop generate-adapter
226
- npx ai-engineering-loop generate-adapter --type github
109
+ Start from a built-in workflow or make your own:
227
110
 
228
- # Grill (or --write) a loop overlay + empty lessons.md for this repo
229
- npx ai-engineering-loop generate-workflow
230
- npx ai-engineering-loop generate-workflow --write
231
- ```
111
+ - Product feature
112
+ - Bug fix
113
+ - Security review
114
+ - Repository audit
115
+ - Refactor
116
+ - Custom prompt-powered Agent workflow
117
+
118
+ Custom Agents can reference approved capabilities, MCP connections, input artifacts, and output formats. They do not receive hidden shell, filesystem, network, or secret access.
119
+
120
+ ## Safety without the scary dashboard
121
+
122
+ The Loop keeps a few promises:
123
+
124
+ - **Nothing ships only because an AI says “done.”**
125
+ - **Goals are frozen before implementation.**
126
+ - **Verification records the real command and result.**
127
+ - **A Devil’s Advocate challenges the work before the Judge decides.**
128
+ - **Sensitive context is bounded and redacted.**
129
+ - **Publishing in assisted mode needs human approval.**
130
+ - **The browser never silently runs arbitrary shell commands.**
131
+
132
+ Choose the level of autonomy that feels right:
232
133
 
233
- Every full run stores private local artifacts under `.ai-engineering-loop/runs/<run-id>/`. Usage, worktrees, locks, context packs, and logs are Git-ignored. Markdown remains the human contract; JSON sidecars follow the shipped `schemas/` and make stage claims deterministic. `ASSISTED` is the default and requires explicit human delivery approval. `UNATTENDED` is disabled until a human enables it. See [`core/runtime-safety.md`](core/runtime-safety.md), [`core/artifact-gates.md`](core/artifact-gates.md), [`SECURITY.md`](SECURITY.md), and [`SUPPORT.md`](SUPPORT.md).
134
+ | Mode | Best for |
135
+ |---|---|
136
+ | **Report only** | Explore a codebase without changing it |
137
+ | **Assisted** | Everyday work with human approval before delivery |
138
+ | **Unattended** | Trusted automation with stricter isolation and limits |
234
139
 
235
- Declarative recipes let an AI or future visual editor author a workflow graph without weakening the safety gates. Built-in presets and project recipes can be validated, explained, graphed, and simulated deterministically. `run --recipe` opts into an immutable, resumable DAG scheduler; legacy runs remain unchanged. See [`core/workflow-recipes.md`](core/workflow-recipes.md) and [`core/controlled-workflow-runtime.md`](core/controlled-workflow-runtime.md).
140
+ Assisted mode is the default. Unattended mode stays off until you deliberately enable it.
236
141
 
237
- The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, and preserves replaced versions locally. Workflow Studio is a thin local interface over that compiler and controlled runtime: a pannable and zoomable DAG canvas, drag-and-drop nodes, guarded visual connections, undo/redo, private per-project layouts, Stage 8 adapter selection, live activity and budget telemetry, explicit approval/retry controls, decision memory, and integrity-bound handoff export—without model or shell execution in the browser. See [`core/local-workflow-studio.md`](core/local-workflow-studio.md). The host-neutral agent protocol remains available in [`agents/recipe-builder.md`](agents/recipe-builder.md).
142
+ ## For people who want the controls
238
143
 
239
- Shipped adapters (Stage 8 only, after Judge PASS): `standard`, `github`, `gitlab`, `dot`. Catalog: `adapters/README.md`. Each team generates its own; do not copy a neighbour's pipeline.
144
+ The friendly workflow sits on top of a complete local CLI. You can inspect recipes, budgets, evidence, nodes, gates, policies, and handoffs whenever you need to.
240
145
 
241
- `sync-hosts` updates only hosts that already exist on the machine. DOT skills (`dot-dev-skill-router`, `dot-dev-workflow`) are updated only if they are already installed. `task-impact-inquiry`, `generate-adapter`, and `generate-workflow` are upserted onto Claude, Grok, and Gemini. After a copy, start a new session so the host reloads skill text. `/ai-engineering-loop` Stage 0 and `run` call `sync-hosts` so a published package bump reaches global host files without a manual copy.
146
+ <details>
147
+ <summary><strong>Show common CLI commands</strong></summary>
242
148
 
243
- ---
149
+ ```bash
150
+ # Project setup and health
151
+ npx ai-engineering-loop init
152
+ npx ai-engineering-loop status
153
+ npx ai-engineering-loop doctor
244
154
 
245
- ## Grok CLI Integration
155
+ # Start work
156
+ npx ai-engineering-loop run "describe the task"
157
+ npx ai-engineering-loop studio
246
158
 
247
- Grok CLI is a first-class host. `spawn_subagent` is a real independent child session (own context, no parent transcript unless `resume_from` is set). After a child id and model response are captured, the registry selects **`TRUE_INDEPENDENT_AGENT`**.
159
+ # Explore workflows
160
+ npx ai-engineering-loop recipe list
161
+ npx ai-engineering-loop recipe simulate default --mode assisted
248
162
 
249
- | Loop role | Grok `subagent_type` | Spawn rules |
250
- |---|---|---|
251
- | Orchestrator / Maker | parent session | Parent stays the orchestrator (Grok nesting depth is 1) |
252
- | Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `capability_mode: execute`, omit `resume_from` |
253
- | Judge | `judge` (fallback `general-purpose`) | Sibling of DA, never nested under DA |
163
+ # Inspect the active Run
164
+ npx ai-engineering-loop state --json
165
+ npx ai-engineering-loop node status
254
166
 
255
- Do **not** use `caveman:cavecrew-reviewer` as Devil's Advocate or Judge — its output schema is not the Finding Ledger.
167
+ # Emergency stop and resume
168
+ npx ai-engineering-loop budget pause
169
+ npx ai-engineering-loop budget resume
170
+ ```
256
171
 
257
- Repo-local Grok files:
172
+ See the [`core/`](core/) documentation for the full runtime, evidence, recipe, security, and adapter contracts.
258
173
 
259
- - `.grok/agents/devil-advocate.md` / `.grok/agents/judge.md`
260
- - `.grok/skills/ai-engineering-loop/SKILL.md`
261
- - `.grok/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
174
+ </details>
262
175
 
263
- Fallback: `GROK_SUBAGENTS=0` or `--disallowed-tools Agent` → `CONTEXT_ISOLATION_ONLY`, disclosed as such. Optional process fallback: `grok -p` → `FRESH_PROCESS_AGENT` only after a model response is captured.
176
+ ## Works locally, delivers anywhere
264
177
 
265
- See [docs/grok-cli-feasibility.md](docs/grok-cli-feasibility.md).
178
+ Your living project context and Run evidence are stored under `.ai-engineering-loop/` and kept out of normal commits by default. You can remove its `.gitignore` entry whenever you want to share that context. Delivery adapters support:
266
179
 
267
- ---
180
+ - Standard Git
181
+ - GitHub
182
+ - GitLab
183
+ - Custom team workflows
268
184
 
269
- ## Claude Code Integration
185
+ The same engineering flow stays consistent even when teams use different delivery tools.
270
186
 
271
- Claude Code is a first-class host. Use the **Task** (or **Agent**) tool with **only** `subagent_type`, `description`, and `prompt`.
187
+ ## Why open source?
272
188
 
273
- Do **not** pass Grok keys (`spawn_subagent`, `capability_mode`, `isolation`, `resume_from`). Extra keys are the usual cause of:
189
+ The rules that decide whether AI-generated work is trustworthy should be inspectable. AI Engineering Loop keeps its schemas, safety policies, verification logic, recipes, and agent prompts in the repository.
274
190
 
275
- ```
276
- API Error: 400 [kiro/claude-sonnet-5] REQUEST_BODY_INVALID
277
- ```
191
+ No hidden cloud control plane is required. No project source is uploaded by Workflow Studio.
278
192
 
279
- | Loop role | Claude Code `subagent_type` | Task keys |
280
- |---|---|---|
281
- | Orchestrator / Maker | parent session | n/a |
282
- | Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt`, wait (no background) |
283
- | Judge | `judge` (fallback `general-purpose`) | same, after DA returns |
284
-
285
- Parent writes `git diff` to a file and passes that path. DA is capped at 8 tool calls and skips css/generated blobs so review does not take tens of minutes.
286
-
287
- Repo-local Claude Code files:
288
-
289
- - `.claude/agents/devil-advocate.md` / `.claude/agents/judge.md`
290
- - `.claude/skills/ai-engineering-loop/SKILL.md`
291
- - `.claude/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
292
-
293
- On Kiro auto mode, pre-allow verification Bash or the safety classifier 400s the session. Copy `templates/repo-config/claude-permissions.json` into the target repo `.claude/settings.local.json` `permissions.allow` list. If Bash returns "cannot determine the safety", do not retry; switch permission mode to default and start a new session.
294
-
295
- See [docs/claude-code-feasibility.md](docs/claude-code-feasibility.md).
296
-
297
- ---
298
-
299
- ## Antigravity Agent Integration
300
-
301
- Antigravity uses `.agents/devil-advocate.md`, `.agents/judge.md`, and `.agents/workflows/ai-engineering-loop.md`. Same review budget as Claude Code and Grok: DA 8 tool calls, Judge 4, wait (no background), skip css/generated, never `browser_subagent`. If `invoke_subagent` is missing, disclose `CONTEXT_ISOLATION_ONLY`.
302
-
303
- When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
304
-
305
- - **`/ai-engineering-loop init`**: Initialize project context only (non-destructive bootstrap).
306
- - **`/ai-engineering-loop status`**: Check repository context health & baseline freshness.
307
- - **`/ai-engineering-loop refresh`**: Reconcile drifted context files non-destructively.
308
- - **`/ai-engineering-loop [task description]`**: Execute the full 8-stage engineering lifecycle with pre-task drift gate and post-task impact assessment.
309
-
310
- On Grok CLI the same slash command is provided by `.grok/commands/ai-engineering-loop.md` and runs Devil's Advocate / Judge as native subagents.
311
-
312
- ---
313
-
314
- ## Repository Structure
315
-
316
- ```text
317
- ai-engineering-loop/
318
- │
319
- ├── README.md # Operating system overview & architecture
320
- ├── LICENSE # MIT Open Source License
321
- ├── package.json # CLI package manifest
322
- │
323
- ├── bin/ # CLI execution entrypoints
324
- │ └── ai-engineering-loop.js # npx executable CLI (init, status, refresh, run, sync-hosts)
325
- │
326
- ├── lib/ # Core orchestration & decision engine
327
- │ ├── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
328
- │ ├── recipe.js # Declarative graph validator and deterministic compiler
329
- │ └── workflow-runtime.js # Resumable scheduler and hash-chained event ledger
330
- │
331
- ├── recipes/ # Built-in workflow presets; target repos may add their own
332
- │ ├── default.json # Current production loop represented as a graph
333
- │ └── audit.json # Read-only report workflow
334
- │
335
- ├── tests/ # Deterministic test suites
336
- │ ├── capability-selection.test.js # Unit tests for capability lifecycle & truthful selection
337
- │ ├── orchestration.test.js # Tests for isolation, Finding schema, Judge matrix
338
- │ └── grok-runtime.test.js # Grok spawn_subagent mapping, aliases, forbidden types
339
- │
340
- ├── .agents/ # Antigravity host adapter
341
- │ ├── devil-advocate.md
342
- │ ├── judge.md
343
- │ └── workflows/ai-engineering-loop.md
344
- │
345
- ├── .grok/ # Grok CLI host adapter
346
- │ ├── agents/devil-advocate.md # Native DA subagent type
347
- │ ├── agents/judge.md # Native Judge subagent type
348
- │ ├── skills/ai-engineering-loop/ # Grok skill (spawn protocol)
349
- │ └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
350
- │
351
- ├── .claude/ # Claude Code host adapter (Kiro-safe)
352
- │ ├── agents/devil-advocate.md # Task subagent type
353
- │ ├── agents/judge.md # Task subagent type
354
- │ ├── skills/ai-engineering-loop/ # Claude skill (Task keys only)
355
- │ └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
356
- │
357
- ├── core/ # Generic engineering loop specifications
358
- │ ├── orchestration-model.md # 3-stage capability lifecycle & execution priority
359
- │ ├── project-initialization.md # Auto-discovery & initialization lifecycle
360
- │ ├── context-refresh-policy.md # Progressive drift hierarchy & living baseline
361
- │ ├── context-impact-assessment.md # Post-task impact assessment (NONE, TARGETED, MAJOR)
362
- │ ├── goal-contract.md # Task contract schema & acceptance criteria
363
- │ ├── grill-policy.md # Stage 1 human alignment (design tree)
364
- │ ├── root-cause-analysis.md # Stage 2 diagnosis gates
365
- │ ├── handoff-policy.md # Mid-loop session handoff artifact
366
- │ ├── verification-loop.md # Dual-layer verification & Evidence Contract
367
- │ ├── definition-of-done.md # 5 pillars of Done & rejection triggers
368
- │ ├── iteration-policy.md # Bounded autonomous loop (MAX_ITERATIONS = 3)
369
- │ ├── escalation-policy.md # Deterministic human escalation triggers
370
- │ ├── judge-policy.md # Evaluation rules, triage audit, & verdicts
371
- │ ├── configuration-precedence.md # 5-layer precedence & conflict resolution
372
- │ ├── controlled-workflow-runtime.md # Immutable plan, scheduler, events, and recovery
373
- │ ├── workflow-recipes.md # Recipe safety backbone and AI authoring protocol
374
- │ └── repo-config-schema.md # Schema for target repo .ai-engineering-loop/
375
- │
376
- ├── profiles/ # Project archetype profiles
377
- │ ├── README.md # Profile catalog & auto-detection rules
378
- │ ├── web-app.md # Frontend web applications
379
- │ ├── backend-api.md # Backend APIs & microservices
380
- │ ├── mobile-app.md # Native & cross-platform mobile apps
381
- │ ├── library.md # Reusable SDKs & shared packages
382
- │ └── monorepo.md # Multi-package monorepo workspaces
383
- │
384
- ├── agents/ # Triad agent role specifications
385
- │ ├── maker.md # Maker agent: surgical diffs & unit tests
386
- │ ├── devil-advocate.md # Adversarial reviewer: dual-axis finding ledger & diffs
387
- │ └── judge.md # Judge agent: impartial magistrate on Validity + Severity
388
- │
389
- ├── policies/ # Operational schemas & algorithms
390
- │ ├── discovery-safety-policy.md # Secret protection & non-destructive discovery rules
391
- │ ├── finding-policy.md # Dual-axis finding schema & severity matrix
392
- │ ├── tdd-policy.md # Red-green at named seams
393
- │ ├── evidence-policy.md # 5-level evidence hierarchy & Verification Evidence Contract
394
- │ └── no-progress-policy.md # Finding signature hashing & stagnation detection
395
- │
396
- ├── adapters/ # Pluggable Stage 8 delivery (not a second OS)
397
- │ ├── README.md # Catalog: standard, github, gitlab, dot
398
- │ ├── generate-adapter/SKILL.md # Grill Q1-Q5, then write adapter.md
399
- │ ├── generate-workflow/SKILL.md # Grill Q1-Q6, then write workflow.md + lessons.md
400
- │ ├── standard/ # Generic git delivery (any forge)
401
- │ ├── github/ # gh pr / GitHub Issues
402
- │ ├── gitlab/ # glab mr (not the DOT pipeline)
403
- │ └── dot/ # DOT-specific GitLab + multi-branch + chat
404
- │
405
- └── templates/ # Starter templates for target repositories
406
- └── repo-config/ # Ready-to-copy .ai-engineering-loop/ files
407
- ├── config.md # Project identity & profile binding
408
- ├── architecture.md # Layers & boundary invariants
409
- ├── glossary.md # Ubiquitous language
410
- ├── adr-readme.md # ADR folder template
411
- ├── conventions.md # Code standards & forbidden patterns
412
- ├── verification.md # CLI test/lint/build commands
413
- ├── adapter.md # Configured release pipeline
414
- ├── workflow.md # Optional loop overlay hooks
415
- └── lessons.md # Optional confirmed process lessons
416
- ```
193
+ ## Documentation
194
+
195
+ - [Workflow Studio](core/local-workflow-studio.md)
196
+ - [Workflow recipes](core/workflow-recipes.md)
197
+ - [Runtime safety](core/runtime-safety.md)
198
+ - [Verification](core/verification-loop.md)
199
+ - [Controlled workflow runtime](core/controlled-workflow-runtime.md)
200
+ - [Security](SECURITY.md)
201
+ - [Support](SUPPORT.md)
417
202
 
418
- ---
203
+ ## Contributing
204
+
205
+ Ideas, workflow recipes, bug reports, and pull requests are welcome. Start with an issue or open a focused PR with a clear explanation of the user outcome.
206
+
207
+ ```bash
208
+ npm test
209
+ npm run doctor
210
+ ```
419
211
 
420
212
  ## License
421
213
 
422
- This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
214
+ MIT © [Ega Gofur](https://github.com/egagofur)
215
+
216
+ <div align="center">
217
+
218
+ **Let the agent handle the process. Keep your attention on the product.**
219
+
220
+ </div>