ai-engineering-loop 1.6.0 → 1.8.1

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,454 +1,218 @@
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.6.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
- ---
19
-
20
- ## Overview & Philosophy
21
-
22
- The AI Engineering Loop enforces clean architectural separation across three core layers:
23
-
24
- ```mermaid
25
- flowchart TD
26
- Start([User Task in Workspace]) --> PreCheck{Pre-Task Drift Check: metadata.json}
27
-
28
- PreCheck -->|Context Missing| AutoInit[Stage 0: Bootstrap .ai-engineering-loop/]
29
- PreCheck -->|Drift Detected| Reconcile[Stage 0: Reconcile Drifted Context]
30
- PreCheck -->|Context Fresh| GC[Stage 1: Goal Contract: Explicit Acceptance Criteria]
31
-
32
- AutoInit --> GC
33
- Reconcile --> GC
34
-
35
- subgraph CoreEngine [AI ENGINEERING OPERATING SYSTEM]
36
- GC --> RCA[Stage 2: Root Cause Analysis]
37
- RCA --> Plan[Stage 3: Implementation Plan]
38
- Plan --> MA[Stage 4: Maker Agent: Surgical Diff & Tests]
39
- MA --> DV{Stage 5: Deterministic Verification<br>Evidence Contract: Exit Code 0 & Full Logs}
40
-
41
- DV -->|Fail| MA
42
- DV -->|Pass| DA[Stage 6: Devil's Advocate Review<br>Capability Registry & Artifact Barrier]
43
-
44
- DA --> JD[Stage 7: Judge Agent: Impartial Magistrate<br>Validity + Severity Decision Matrix]
45
- end
46
-
47
- JD -->|VALID BLOCKER / HIGH: ITERATE| MA
48
- JD -->|INVALID: Dismissed / VALID LOW: Tradeoff| CheckDoD{All ACs Verified?}
49
-
50
- CheckDoD -->|Yes: PASS| ImpactEval{Post-Task Context Impact Assessment}
51
- ImpactEval -->|NONE: Typo, UI tweak| Adapter[Stage 8: Delivery Adapter: GitLab / GitHub]
52
- ImpactEval -->|TARGETED: Dep/route changed| PartialRefresh[Surgical Context Update] --> Adapter
53
- ImpactEval -->|MAJOR: Framework migration| FullRefresh[Full Context Reconciliation] --> Adapter
54
-
55
- Adapter --> TargetRepo[(Target Repository)]
56
- ```
17
+ [![AI Engineering Loop Workflow Studio](docs/images/studio-hero.svg)](docs/images/studio-hero.svg)
57
18
 
58
- ---
19
+ ## Software delivery that feels simple
59
20
 
60
- ## Stage techniques
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:
61
22
 
62
- The 8-stage loop stays one OS. These techniques sit **inside** existing stages (they are not optional slash-command products):
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 |
63
31
 
64
- | Stage | Technique | Spec |
65
- |---|---|---|
66
- | 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` |
67
- | 1 | Ubiquitous language in `.ai-engineering-loop/glossary.md`; load-bearing choices in `.ai-engineering-loop/adrs/` | `core/repo-config-schema.md` |
68
- | 2 | Bugs: red repro → minimise → hypothesise → instrument → fix | `core/root-cause-analysis.md` |
69
- | 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` |
70
- | 4–5 | Red-green at named **seams**; failure table (not happy path only); coverage is a map; no grep/tautology | `policies/tdd-policy.md` |
71
- | 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` |
72
- | 6–7 | Spec vs Standards reported separately. Standards BLOCKER/HIGH iterate only when `hardConvention` is true | `policies/finding-policy.md` |
73
- | 0–8 | Stateful run ledger and deterministic artifact transitions; model claims cannot advance a stage | `core/artifact-gates.md` |
74
- | 0–8 | `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`; actual token budgets, kill switch, and locked Maker worktrees | `core/runtime-safety.md` |
75
- | any | Mid-loop stop writes `.ai-engineering-loop/tasks/handoff.md` | `core/handoff-policy.md` |
76
- | 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 |
32
+ You stay in control of the product decisions. Your AI agent takes care of the repetitive engineering ceremony.
77
33
 
78
- `init` now requires `glossary.md` and `adrs/README.md`. Repair fills missing files only; a filled glossary is never overwritten.
34
+ ## Get started in a minute
79
35
 
80
- ---
36
+ Install it in any project:
81
37
 
82
- ## Runtime Capability Registry & Execution Modes
38
+ ```bash
39
+ npx ai-engineering-loop init
40
+ ```
83
41
 
84
- The system maintains a strict distinction between **Configuration Support**, **Invocation Availability**, and **Execution Proof**:
42
+ Then tell your coding agent:
85
43
 
86
- ```text
87
- ┌───────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────┐
88
- │ CONFIGURATION_SUPPORTED │ ──> │ INVOCATION_AVAILABLE │ ──> │ EXECUTION_PROVEN │
89
- │ (Config is recognized) │ │ (Callable tool is active) │ │ (Child LLM response seen) │
90
- └───────────────────────────┘ └───────────────────────────┘ └───────────────────────────┘
91
- ```
44
+ > Use AI Engineering Loop to build this feature: **your idea here**
92
45
 
93
- ### 5 Standard Execution Modes (Deterministic Priority):
94
-
95
- | Priority | Mode Name | Requires Independent LLM Execution? | Condition for Selection |
96
- |:---:|---|:---:|---|
97
- | **1** | **`TRUE_INDEPENDENT_AGENT`** | **YES** | Child session exists **AND** actual model response is captured **AND** context is independent. |
98
- | **2** | **`ISOLATED_AGENT_INSTANCE`** | **YES** | Programmatic SDK agent instance with verified independent model execution. |
99
- | **3** | **`FRESH_PROCESS_AGENT`** | **YES** | Separate OS process successfully executes an LLM agent with fresh context. |
100
- | **4** | **`CONTEXT_ISOLATION_ONLY`** | **NO** | Clean-Slate Artifact Isolation Barrier in same session (100% prompt history excluded on disk). |
101
- | **5** | **`UNAVAILABLE`** | **NO** | No review execution mechanism is available. |
102
-
103
- ### Truthful Reporting Disclosure:
104
- When `CONTEXT_ISOLATION_ONLY` is selected, the report strictly produces:
105
- ```text
106
- Execution Mode: CONTEXT_ISOLATION_ONLY
107
- Independent LLM Execution: NOT PROVEN
108
- Native Subagent Invocation: UNAVAILABLE
109
- Review Method: Clean-Slate Artifact Isolation Barrier
110
- ```
46
+ That is the intended experience. You do not need to memorize the internal commands—the agent can operate the loop for you.
111
47
 
112
- ---
113
-
114
- ## Verification Evidence Contract
115
-
116
- 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"*.
117
-
118
- ### Mandatory Execution Proof:
119
- - **`command`**: Exact CLI string executed.
120
- - **`executionIdentity`**: PID, execution hash, or system execution identifier.
121
- - **`startTime` & `endTime`**: Documented execution duration.
122
- - **`exitCode`**: Must be `0`.
123
- - **`stdout` & `stderr`**: Raw machine logs captured.
124
- - **`timeoutStatus`**: Must be `"COMPLETED"`.
125
- - **`testCounts`**: Explicit counts of passed, failed, and skipped tests.
126
- - **`assertionEvidence`**: Specific assertion proof matching the active Goal Contract's Acceptance Criteria.
127
-
128
- ---
129
-
130
- ## Dual-Axis Finding Model & Judge Decision Matrix
131
-
132
- The Devil's Advocate categorizes findings along separate **Validity**, **Severity**, and **Disposition** axes:
133
-
134
- ```json
135
- {
136
- "id": "DA-01",
137
- "topic": "correctness",
138
- "validity": "VALID",
139
- "severity": "BLOCKER",
140
- "disposition": "STRONG",
141
- "location": "src/services/payment.ts#L42-L58",
142
- "acceptanceCriteria": "AC-2",
143
- "failureScenario": "Under concurrent traffic, duplicate rows are inserted before the lock is acquired.",
144
- "evidence": "Missing SELECT FOR UPDATE in findByPaymentKey query.",
145
- "concreteAlternativeDiff": "```diff\n- const tx = await findByKey(key);\n+ const tx = await findByKeyWithLock(key, { mode: 'FOR UPDATE' });\n```"
146
- }
48
+ Want the visual workspace?
49
+
50
+ ```bash
51
+ npx ai-engineering-loop studio
147
52
  ```
148
53
 
149
- ### Judge Decision Matrix:
150
- - **`VALID + BLOCKER / HIGH`** $\rightarrow$ **`ITERATE`** (Maker must apply concrete fix diff and add regression tests).
151
- - **`VALID + MEDIUM / LOW`** $\rightarrow$ **`ACCEPT / TRADEOFF`** (Merged; documented as acceptable tradeoff in MR notes).
152
- - **`INVALID`** $\rightarrow$ **`DISMISS`** (Reviewer hallucination disproven by code; cannot block delivery; signature recorded).
54
+ Workflow Studio opens locally in your browser. Your project and run evidence stay on your machine.
153
55
 
154
- *Reviewer disposition (`STRONG`, `ACCEPTABLE`, `WEAK`) never overrides factual evidence.*
56
+ ## Meet Workflow Studio
155
57
 
156
- ---
58
+ Workflow Studio makes agent work feel like a product, not a terminal session.
157
59
 
158
- ## Living Project Context
60
+ ### Build workflows visually
159
61
 
160
- The `.ai-engineering-loop/` directory is **Living Context**, not a static wiki generated once.
62
+ - Connect steps on an open canvas
63
+ - Add the next step directly from any node
64
+ - Rename nodes in place without breaking their identity
65
+ - Select, move, duplicate, or delete groups of nodes
66
+ - Import and export workflow JSON safely
67
+ - Create your own prompt-powered Agent nodes
161
68
 
162
- 1. **Post-Task Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
163
- 2. **Context Baseline (`metadata.json`)**: Tracks `repositoryRevision` (git commit SHA) and `manifestChecksums` for instant Level 0 (0ms) drift verification.
164
- 3. **Strict Context Isolation**: Decouples living project context from ephemeral task logs and loop execution states.
69
+ ### Start with a Goal—not a vague prompt
165
70
 
166
- ---
71
+ 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.
167
72
 
168
- ## CLI Interface & Commands
73
+ ### Follow every Run
169
74
 
170
- 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.
75
+ Runs have human-friendly names instead of cryptic hashes. Search previous work, inspect decisions, view evidence, and see exactly where a workflow stopped.
171
76
 
172
- ```bash
173
- # Bootstrap .ai-engineering-loop/ context from repository discovery
174
- npx ai-engineering-loop init
77
+ ### Execute with confidence
175
78
 
176
- # Check the validity, readiness, and baseline freshness of context
177
- npx ai-engineering-loop status
79
+ The Execute button lives beside the workflow trigger. A Run starts only when the Goal, workflow, mode, and safety checks are ready.
178
80
 
179
- # Reconcile drifted context against repository non-destructively
180
- npx ai-engineering-loop refresh
81
+ ## One workspace from idea to delivery
181
82
 
182
- # Start or resume a stateful engineering run
183
- npx ai-engineering-loop run
184
- npx ai-engineering-loop run --mode report-only "audit this repository"
185
- npx ai-engineering-loop run --recipe bugfix --mode assisted "repair retry race"
83
+ The experience is organized into four simple moments:
186
84
 
187
- # Inspect the run ledger
188
- npx ai-engineering-loop state --json
85
+ 1. **Specify** — agree on what success and failure look like.
86
+ 2. **Make** — let the agent investigate, plan, and build.
87
+ 3. **Review** — verify the result and challenge unsupported claims.
88
+ 4. **Deliver** — ask for human approval before publishing.
189
89
 
190
- # Inspect policy, opt into unattended, and operate the token kill switch
191
- npx ai-engineering-loop policy show
192
- npx ai-engineering-loop policy set --allow-unattended true
193
- npx ai-engineering-loop budget status
194
- npx ai-engineering-loop budget pause
195
- npx ai-engineering-loop budget resume
90
+ 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.
196
91
 
197
- # Record actual provider-reported usage after each model response
198
- npx ai-engineering-loop budget record --input 1200 --output 300 --model provider/model-id
199
- npx ai-engineering-loop budget status --node root-cause --estimate 4000
200
- npx ai-engineering-loop budget record --node root-cause --input 3000 --output 700 --model provider/model-id
201
-
202
- # Isolate unattended Maker, then capture only its diff
203
- npx ai-engineering-loop sandbox create
204
- npx ai-engineering-loop sandbox capture
205
-
206
- # Validate artifacts and advance stages
207
- npx ai-engineering-loop gate goal
208
- npx ai-engineering-loop gate report
209
- npx ai-engineering-loop gate maker
210
- npx ai-engineering-loop gate verification
211
- npx ai-engineering-loop gate review
212
- npx ai-engineering-loop escalation --json
213
- npx ai-engineering-loop gate judge
214
- npx ai-engineering-loop gate delivery
215
-
216
- # Build bounded model-visible context
217
- npx ai-engineering-loop context devil-advocate <files...>
218
- npx ai-engineering-loop context judge <files...>
219
-
220
- # Validate installation and the production evaluation catalog
221
- npx ai-engineering-loop doctor
222
- npx ai-engineering-loop eval
92
+ `Specify (stages 0-1)` → `Make (stages 2-4)` → `Review (stages 5-7)` → `Deliver (stage 8)`
223
93
 
224
- # Inspect declarative workflow recipes without executing nodes
225
- npx ai-engineering-loop recipe list
226
- npx ai-engineering-loop recipe validate default --mode assisted
227
- npx ai-engineering-loop recipe explain default --mode assisted
228
- npx ai-engineering-loop recipe graph default --mode assisted
229
- npx ai-engineering-loop recipe simulate default --mode assisted
230
- npx ai-engineering-loop recipe catalog --json
231
- npx ai-engineering-loop recipe create api-bugfix --from bugfix
232
- npx ai-engineering-loop recipe inspect api-bugfix --json
233
- npx ai-engineering-loop recipe diff bugfix api-bugfix
234
- npx ai-engineering-loop recipe install candidate.json
235
- npx ai-engineering-loop recipe install candidate-v2.json --replace
236
-
237
- # Operate a custom node in an immutable recipe-bound run
238
- npx ai-engineering-loop node status
239
- npx ai-engineering-loop node start root-cause
240
- npx ai-engineering-loop node activity root-cause --message "Comparing failing evidence"
241
- npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
242
- npx ai-engineering-loop node approve delivery-approval --yes
94
+ ## Bring your own AI agent
243
95
 
244
- # Open the local workflow canvas (localhost-only, authenticated session)
245
- npx ai-engineering-loop studio
246
- npx ai-engineering-loop studio --port 4400 --no-open
96
+ AI Engineering Loop is designed to work with the tools developers already use:
247
97
 
248
- # Transfer redacted knowledge to another developer or agent
249
- npx ai-engineering-loop handoff create --audience developer
250
- npx ai-engineering-loop handoff inspect <run-id>.ael-handoff.json
251
- npx ai-engineering-loop handoff brief <run-id>.ael-handoff.json
98
+ - **Claude Code**
99
+ - **Grok CLI**
100
+ - **Gemini / Antigravity**
101
+ - Other agent hosts that can read project instructions and run local commands
252
102
 
253
- # Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
254
- npx ai-engineering-loop sync-hosts
103
+ The project includes ready-to-use skills and reviewer roles for supported hosts. Each host follows the same Goal, verification, review, and approval rules.
255
104
 
256
- # Grill (or --type) a Stage 8 delivery adapter for this repo
257
- npx ai-engineering-loop generate-adapter
258
- npx ai-engineering-loop generate-adapter --type github
105
+ ## Create workflows that fit your team
259
106
 
260
- # Grill (or --write) a loop overlay + empty lessons.md for this repo
261
- npx ai-engineering-loop generate-workflow
262
- npx ai-engineering-loop generate-workflow --write
263
- ```
107
+ Start from a built-in workflow or make your own:
264
108
 
265
- 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).
109
+ - Product feature
110
+ - Bug fix
111
+ - Security review
112
+ - Repository audit
113
+ - Refactor
114
+ - Custom prompt-powered Agent workflow
266
115
 
267
- 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).
116
+ Custom Agents can reference approved capabilities, MCP connections, input artifacts, and output formats. They do not receive hidden shell, filesystem, network, or secret access.
268
117
 
269
- 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: animated DAG state, 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).
118
+ ## Safety without the scary dashboard
270
119
 
271
- 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.
120
+ The Loop keeps a few promises:
272
121
 
273
- `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.
122
+ - **Nothing ships only because an AI says “done.”**
123
+ - **Goals are frozen before implementation.**
124
+ - **Verification records the real command and result.**
125
+ - **A Devil’s Advocate challenges the work before the Judge decides.**
126
+ - **Sensitive context is bounded and redacted.**
127
+ - **Publishing in assisted mode needs human approval.**
128
+ - **The browser never silently runs arbitrary shell commands.**
274
129
 
275
- ---
130
+ Choose the level of autonomy that feels right:
276
131
 
277
- ## Grok CLI Integration
132
+ | Mode | Best for |
133
+ |---|---|
134
+ | **Report only** | Explore a codebase without changing it |
135
+ | **Assisted** | Everyday work with human approval before delivery |
136
+ | **Unattended** | Trusted automation with stricter isolation and limits |
278
137
 
279
- 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`**.
138
+ Assisted mode is the default. Unattended mode stays off until you deliberately enable it.
280
139
 
281
- | Loop role | Grok `subagent_type` | Spawn rules |
282
- |---|---|---|
283
- | Orchestrator / Maker | parent session | Parent stays the orchestrator (Grok nesting depth is 1) |
284
- | Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `capability_mode: execute`, omit `resume_from` |
285
- | Judge | `judge` (fallback `general-purpose`) | Sibling of DA, never nested under DA |
140
+ ## For people who want the controls
286
141
 
287
- Do **not** use `caveman:cavecrew-reviewer` as Devil's Advocate or Judge — its output schema is not the Finding Ledger.
142
+ 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.
288
143
 
289
- Repo-local Grok files:
144
+ <details>
145
+ <summary><strong>Show common CLI commands</strong></summary>
290
146
 
291
- - `.grok/agents/devil-advocate.md` / `.grok/agents/judge.md`
292
- - `.grok/skills/ai-engineering-loop/SKILL.md`
293
- - `.grok/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
147
+ ```bash
148
+ # Project setup and health
149
+ npx ai-engineering-loop init
150
+ npx ai-engineering-loop status
151
+ npx ai-engineering-loop doctor
294
152
 
295
- 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.
153
+ # Start work
154
+ npx ai-engineering-loop run "describe the task"
155
+ npx ai-engineering-loop studio
296
156
 
297
- See [docs/grok-cli-feasibility.md](docs/grok-cli-feasibility.md).
157
+ # Explore workflows
158
+ npx ai-engineering-loop recipe list
159
+ npx ai-engineering-loop recipe simulate default --mode assisted
298
160
 
299
- ---
161
+ # Inspect the active Run
162
+ npx ai-engineering-loop state --json
163
+ npx ai-engineering-loop node status
300
164
 
301
- ## Claude Code Integration
165
+ # Emergency stop and resume
166
+ npx ai-engineering-loop budget pause
167
+ npx ai-engineering-loop budget resume
168
+ ```
302
169
 
303
- Claude Code is a first-class host. Use the **Task** (or **Agent**) tool with **only** `subagent_type`, `description`, and `prompt`.
170
+ See the [`core/`](core/) documentation for the full runtime, evidence, recipe, security, and adapter contracts.
304
171
 
305
- Do **not** pass Grok keys (`spawn_subagent`, `capability_mode`, `isolation`, `resume_from`). Extra keys are the usual cause of:
172
+ </details>
306
173
 
307
- ```
308
- API Error: 400 [kiro/claude-sonnet-5] REQUEST_BODY_INVALID
309
- ```
174
+ ## Works locally, delivers anywhere
310
175
 
311
- | Loop role | Claude Code `subagent_type` | Task keys |
312
- |---|---|---|
313
- | Orchestrator / Maker | parent session | n/a |
314
- | Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt`, wait (no background) |
315
- | Judge | `judge` (fallback `general-purpose`) | same, after DA returns |
316
-
317
- 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.
318
-
319
- Repo-local Claude Code files:
320
-
321
- - `.claude/agents/devil-advocate.md` / `.claude/agents/judge.md`
322
- - `.claude/skills/ai-engineering-loop/SKILL.md`
323
- - `.claude/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
324
-
325
- 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.
326
-
327
- See [docs/claude-code-feasibility.md](docs/claude-code-feasibility.md).
328
-
329
- ---
330
-
331
- ## Antigravity Agent Integration
332
-
333
- 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`.
334
-
335
- When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
336
-
337
- - **`/ai-engineering-loop init`**: Initialize project context only (non-destructive bootstrap).
338
- - **`/ai-engineering-loop status`**: Check repository context health & baseline freshness.
339
- - **`/ai-engineering-loop refresh`**: Reconcile drifted context files non-destructively.
340
- - **`/ai-engineering-loop [task description]`**: Execute the full 8-stage engineering lifecycle with pre-task drift gate and post-task impact assessment.
341
-
342
- 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.
343
-
344
- ---
345
-
346
- ## Repository Structure
347
-
348
- ```text
349
- ai-engineering-loop/
350
- │
351
- ├── README.md # Operating system overview & architecture
352
- ├── LICENSE # MIT Open Source License
353
- ├── package.json # CLI package manifest
354
- │
355
- ├── bin/ # CLI execution entrypoints
356
- │ └── ai-engineering-loop.js # npx executable CLI (init, status, refresh, run, sync-hosts)
357
- │
358
- ├── lib/ # Core orchestration & decision engine
359
- │ ├── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
360
- │ ├── recipe.js # Declarative graph validator and deterministic compiler
361
- │ └── workflow-runtime.js # Resumable scheduler and hash-chained event ledger
362
- │
363
- ├── recipes/ # Built-in workflow presets; target repos may add their own
364
- │ ├── default.json # Current production loop represented as a graph
365
- │ └── audit.json # Read-only report workflow
366
- │
367
- ├── tests/ # Deterministic test suites
368
- │ ├── capability-selection.test.js # Unit tests for capability lifecycle & truthful selection
369
- │ ├── orchestration.test.js # Tests for isolation, Finding schema, Judge matrix
370
- │ └── grok-runtime.test.js # Grok spawn_subagent mapping, aliases, forbidden types
371
- │
372
- ├── .agents/ # Antigravity host adapter
373
- │ ├── devil-advocate.md
374
- │ ├── judge.md
375
- │ └── workflows/ai-engineering-loop.md
376
- │
377
- ├── .grok/ # Grok CLI host adapter
378
- │ ├── agents/devil-advocate.md # Native DA subagent type
379
- │ ├── agents/judge.md # Native Judge subagent type
380
- │ ├── skills/ai-engineering-loop/ # Grok skill (spawn protocol)
381
- │ └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
382
- │
383
- ├── .claude/ # Claude Code host adapter (Kiro-safe)
384
- │ ├── agents/devil-advocate.md # Task subagent type
385
- │ ├── agents/judge.md # Task subagent type
386
- │ ├── skills/ai-engineering-loop/ # Claude skill (Task keys only)
387
- │ └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
388
- │
389
- ├── core/ # Generic engineering loop specifications
390
- │ ├── orchestration-model.md # 3-stage capability lifecycle & execution priority
391
- │ ├── project-initialization.md # Auto-discovery & initialization lifecycle
392
- │ ├── context-refresh-policy.md # Progressive drift hierarchy & living baseline
393
- │ ├── context-impact-assessment.md # Post-task impact assessment (NONE, TARGETED, MAJOR)
394
- │ ├── goal-contract.md # Task contract schema & acceptance criteria
395
- │ ├── grill-policy.md # Stage 1 human alignment (design tree)
396
- │ ├── root-cause-analysis.md # Stage 2 diagnosis gates
397
- │ ├── handoff-policy.md # Mid-loop session handoff artifact
398
- │ ├── verification-loop.md # Dual-layer verification & Evidence Contract
399
- │ ├── definition-of-done.md # 5 pillars of Done & rejection triggers
400
- │ ├── iteration-policy.md # Bounded autonomous loop (MAX_ITERATIONS = 3)
401
- │ ├── escalation-policy.md # Deterministic human escalation triggers
402
- │ ├── judge-policy.md # Evaluation rules, triage audit, & verdicts
403
- │ ├── configuration-precedence.md # 5-layer precedence & conflict resolution
404
- │ ├── controlled-workflow-runtime.md # Immutable plan, scheduler, events, and recovery
405
- │ ├── workflow-recipes.md # Recipe safety backbone and AI authoring protocol
406
- │ └── repo-config-schema.md # Schema for target repo .ai-engineering-loop/
407
- │
408
- ├── profiles/ # Project archetype profiles
409
- │ ├── README.md # Profile catalog & auto-detection rules
410
- │ ├── web-app.md # Frontend web applications
411
- │ ├── backend-api.md # Backend APIs & microservices
412
- │ ├── mobile-app.md # Native & cross-platform mobile apps
413
- │ ├── library.md # Reusable SDKs & shared packages
414
- │ └── monorepo.md # Multi-package monorepo workspaces
415
- │
416
- ├── agents/ # Triad agent role specifications
417
- │ ├── maker.md # Maker agent: surgical diffs & unit tests
418
- │ ├── devil-advocate.md # Adversarial reviewer: dual-axis finding ledger & diffs
419
- │ └── judge.md # Judge agent: impartial magistrate on Validity + Severity
420
- │
421
- ├── policies/ # Operational schemas & algorithms
422
- │ ├── discovery-safety-policy.md # Secret protection & non-destructive discovery rules
423
- │ ├── finding-policy.md # Dual-axis finding schema & severity matrix
424
- │ ├── tdd-policy.md # Red-green at named seams
425
- │ ├── evidence-policy.md # 5-level evidence hierarchy & Verification Evidence Contract
426
- │ └── no-progress-policy.md # Finding signature hashing & stagnation detection
427
- │
428
- ├── adapters/ # Pluggable Stage 8 delivery (not a second OS)
429
- │ ├── README.md # Catalog: standard, github, gitlab, dot
430
- │ ├── generate-adapter/SKILL.md # Grill Q1-Q5, then write adapter.md
431
- │ ├── generate-workflow/SKILL.md # Grill Q1-Q6, then write workflow.md + lessons.md
432
- │ ├── standard/ # Generic git delivery (any forge)
433
- │ ├── github/ # gh pr / GitHub Issues
434
- │ ├── gitlab/ # glab mr (not the DOT pipeline)
435
- │ └── dot/ # DOT-specific GitLab + multi-branch + chat
436
- │
437
- └── templates/ # Starter templates for target repositories
438
- └── repo-config/ # Ready-to-copy .ai-engineering-loop/ files
439
- ├── config.md # Project identity & profile binding
440
- ├── architecture.md # Layers & boundary invariants
441
- ├── glossary.md # Ubiquitous language
442
- ├── adr-readme.md # ADR folder template
443
- ├── conventions.md # Code standards & forbidden patterns
444
- ├── verification.md # CLI test/lint/build commands
445
- ├── adapter.md # Configured release pipeline
446
- ├── workflow.md # Optional loop overlay hooks
447
- └── lessons.md # Optional confirmed process lessons
448
- ```
176
+ Your living project context and Run evidence are stored under `.ai-engineering-loop/` and kept out of normal commits. Delivery adapters support:
177
+
178
+ - Standard Git
179
+ - GitHub
180
+ - GitLab
181
+ - Custom team workflows
182
+
183
+ The same engineering flow stays consistent even when teams use different delivery tools.
184
+
185
+ ## Why open source?
449
186
 
450
- ---
187
+ 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.
188
+
189
+ No hidden cloud control plane is required. No project source is uploaded by Workflow Studio.
190
+
191
+ ## Documentation
192
+
193
+ - [Workflow Studio](core/local-workflow-studio.md)
194
+ - [Workflow recipes](core/workflow-recipes.md)
195
+ - [Runtime safety](core/runtime-safety.md)
196
+ - [Verification](core/verification-loop.md)
197
+ - [Controlled workflow runtime](core/controlled-workflow-runtime.md)
198
+ - [Security](SECURITY.md)
199
+ - [Support](SUPPORT.md)
200
+
201
+ ## Contributing
202
+
203
+ 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.
204
+
205
+ ```bash
206
+ npm test
207
+ npm run doctor
208
+ ```
451
209
 
452
210
  ## License
453
211
 
454
- This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
212
+ MIT © [Ega Gofur](https://github.com/egagofur)
213
+
214
+ <div align="center">
215
+
216
+ **Let the agent handle the process. Keep your attention on the product.**
217
+
218
+ </div>
@@ -118,7 +118,7 @@ const {
118
118
  } = require('../lib/handoff.js');
119
119
  const { createStudioServer } = require('../lib/studio-server.js');
120
120
 
121
- const VERSION = '1.6.0';
121
+ const VERSION = require('../package.json').version;
122
122
  const CWD = process.cwd();
123
123
  const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
124
124
 
@@ -372,7 +372,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
372
372
 
373
373
  // 0. metadata.json (Baseline)
374
374
  const metadataJson = {
375
- contextVersion: '1.6.0',
375
+ contextVersion: VERSION,
376
376
  generatedAt: new Date().toISOString(),
377
377
  repositoryRevision: currentRevision,
378
378
  projectProfile: discovery.profile,