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 +152 -388
- package/bin/ai-engineering-loop.js +2 -2
- package/core/local-workflow-studio.md +39 -5
- package/docs/images/engineering-loop-overview.svg +114 -0
- package/docs/images/studio-hero.svg +124 -0
- package/lib/gates.js +3 -2
- package/lib/goal-runtime.js +130 -0
- package/lib/recipe-builder.js +28 -1
- package/lib/recipe-graph.js +92 -0
- package/lib/recipe.js +137 -7
- package/lib/run-history.js +193 -0
- package/lib/run-state.js +90 -5
- package/lib/runtime-files.js +1 -0
- package/lib/studio-layout.js +113 -0
- package/lib/studio-runtime.js +65 -0
- package/lib/studio-server.js +203 -3
- package/lib/workflow-runtime.js +79 -5
- package/package.json +3 -2
- package/schemas/edge-definition.schema.json +13 -0
- package/schemas/node-definition.schema.json +74 -1
- package/schemas/recipe.schema.json +5 -0
- package/studio/app.js +1420 -156
- package/studio/index.html +166 -14
- package/studio/styles.css +45 -74
package/README.md
CHANGED
|
@@ -1,454 +1,218 @@
|
|
|
1
1
|
<div align="center">
|
|
2
|
-
<h1>AI Engineering Loop</h1>
|
|
3
2
|
|
|
4
|
-
|
|
5
|
-
[](https://opensource.org/licenses/MIT)
|
|
6
|
-
[](https://github.com/egagofur/ai-engineering-loop/pulls)
|
|
7
|
-
[](https://github.com/egagofur/ai-engineering-loop)
|
|
8
|
-
[](https://github.com/egagofur/ai-engineering-loop/releases)
|
|
3
|
+
# AI Engineering Loop
|
|
9
4
|
|
|
10
|
-
|
|
5
|
+
### From idea to trusted code—without babysitting every command.
|
|
11
6
|
|
|
12
|
-
|
|
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
|
-
[
|
|
9
|
+
[](https://www.npmjs.com/package/ai-engineering-loop)
|
|
10
|
+
[](https://github.com/egagofur/ai-engineering-loop/releases)
|
|
11
|
+
[](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
|
+
[](docs/images/studio-hero.svg)
|
|
57
18
|
|
|
58
|
-
|
|
19
|
+
## Software delivery that feels simple
|
|
59
20
|
|
|
60
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
34
|
+
## Get started in a minute
|
|
79
35
|
|
|
80
|
-
|
|
36
|
+
Install it in any project:
|
|
81
37
|
|
|
82
|
-
|
|
38
|
+
```bash
|
|
39
|
+
npx ai-engineering-loop init
|
|
40
|
+
```
|
|
83
41
|
|
|
84
|
-
|
|
42
|
+
Then tell your coding agent:
|
|
85
43
|
|
|
86
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
56
|
+
## Meet Workflow Studio
|
|
155
57
|
|
|
156
|
-
|
|
58
|
+
Workflow Studio makes agent work feel like a product, not a terminal session.
|
|
157
59
|
|
|
158
|
-
|
|
60
|
+
### Build workflows visually
|
|
159
61
|
|
|
160
|
-
|
|
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
|
-
|
|
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
|
-
|
|
73
|
+
### Follow every Run
|
|
169
74
|
|
|
170
|
-
|
|
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
|
-
|
|
173
|
-
# Bootstrap .ai-engineering-loop/ context from repository discovery
|
|
174
|
-
npx ai-engineering-loop init
|
|
77
|
+
### Execute with confidence
|
|
175
78
|
|
|
176
|
-
|
|
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
|
-
|
|
180
|
-
npx ai-engineering-loop refresh
|
|
81
|
+
## One workspace from idea to delivery
|
|
181
82
|
|
|
182
|
-
|
|
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
|
-
|
|
188
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
109
|
+
- Product feature
|
|
110
|
+
- Bug fix
|
|
111
|
+
- Security review
|
|
112
|
+
- Repository audit
|
|
113
|
+
- Refactor
|
|
114
|
+
- Custom prompt-powered Agent workflow
|
|
266
115
|
|
|
267
|
-
|
|
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
|
-
|
|
118
|
+
## Safety without the scary dashboard
|
|
270
119
|
|
|
271
|
-
|
|
120
|
+
The Loop keeps a few promises:
|
|
272
121
|
|
|
273
|
-
|
|
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
|
-
|
|
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
|
-
|
|
138
|
+
Assisted mode is the default. Unattended mode stays off until you deliberately enable it.
|
|
280
139
|
|
|
281
|
-
|
|
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
|
-
|
|
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
|
-
|
|
144
|
+
<details>
|
|
145
|
+
<summary><strong>Show common CLI commands</strong></summary>
|
|
290
146
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
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
|
-
|
|
153
|
+
# Start work
|
|
154
|
+
npx ai-engineering-loop run "describe the task"
|
|
155
|
+
npx ai-engineering-loop studio
|
|
296
156
|
|
|
297
|
-
|
|
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
|
-
|
|
165
|
+
# Emergency stop and resume
|
|
166
|
+
npx ai-engineering-loop budget pause
|
|
167
|
+
npx ai-engineering-loop budget resume
|
|
168
|
+
```
|
|
302
169
|
|
|
303
|
-
|
|
170
|
+
See the [`core/`](core/) documentation for the full runtime, evidence, recipe, security, and adapter contracts.
|
|
304
171
|
|
|
305
|
-
|
|
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
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
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
|
-
|
|
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 = '
|
|
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:
|
|
375
|
+
contextVersion: VERSION,
|
|
376
376
|
generatedAt: new Date().toISOString(),
|
|
377
377
|
repositoryRevision: currentRevision,
|
|
378
378
|
projectProfile: discovery.profile,
|