ai-engineering-loop 1.7.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 +149 -353
- package/bin/ai-engineering-loop.js +2 -2
- package/core/local-workflow-studio.md +28 -7
- 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 +27 -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/studio-runtime.js +65 -0
- package/lib/studio-server.js +154 -2
- package/lib/workflow-runtime.js +79 -5
- package/package.json +2 -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 +856 -59
- package/studio/index.html +95 -7
- package/studio/styles.css +20 -10
package/README.md
CHANGED
|
@@ -1,422 +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
|
-
|
|
17
|
+
[](docs/images/studio-hero.svg)
|
|
19
18
|
|
|
20
|
-
##
|
|
19
|
+
## Software delivery that feels simple
|
|
21
20
|
|
|
22
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
34
|
+
## Get started in a minute
|
|
29
35
|
|
|
30
|
-
|
|
36
|
+
Install it in any project:
|
|
31
37
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
|
|
42
|
+
Then tell your coding agent:
|
|
47
43
|
|
|
48
|
-
|
|
44
|
+
> Use AI Engineering Loop to build this feature: **your idea here**
|
|
49
45
|
|
|
50
|
-
|
|
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
|
-
|
|
48
|
+
Want the visual workspace?
|
|
53
49
|
|
|
54
|
-
```
|
|
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
|
-
|
|
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
|
+
## Meet Workflow Studio
|
|
116
57
|
|
|
117
|
-
|
|
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
|
+
Workflow Studio makes agent work feel like a product, not a terminal session.
|
|
121
59
|
|
|
122
|
-
|
|
60
|
+
### Build workflows visually
|
|
123
61
|
|
|
124
|
-
|
|
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
|
|
125
68
|
|
|
126
|
-
|
|
69
|
+
### Start with a Goal—not a vague prompt
|
|
127
70
|
|
|
128
|
-
|
|
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.
|
|
129
72
|
|
|
130
|
-
|
|
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
|
+
### Follow every Run
|
|
133
74
|
|
|
134
|
-
|
|
75
|
+
Runs have human-friendly names instead of cryptic hashes. Search previous work, inspect decisions, view evidence, and see exactly where a workflow stopped.
|
|
135
76
|
|
|
136
|
-
|
|
77
|
+
### Execute with confidence
|
|
137
78
|
|
|
138
|
-
The
|
|
79
|
+
The Execute button lives beside the workflow trigger. A Run starts only when the Goal, workflow, mode, and safety checks are ready.
|
|
139
80
|
|
|
140
|
-
|
|
141
|
-
# Bootstrap .ai-engineering-loop/ context from repository discovery
|
|
142
|
-
npx ai-engineering-loop init
|
|
81
|
+
## One workspace from idea to delivery
|
|
143
82
|
|
|
144
|
-
|
|
145
|
-
npx ai-engineering-loop status
|
|
83
|
+
The experience is organized into four simple moments:
|
|
146
84
|
|
|
147
|
-
|
|
148
|
-
|
|
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.
|
|
149
89
|
|
|
150
|
-
|
|
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"
|
|
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.
|
|
154
91
|
|
|
155
|
-
|
|
156
|
-
npx ai-engineering-loop state --json
|
|
92
|
+
`Specify (stages 0-1)` → `Make (stages 2-4)` → `Review (stages 5-7)` → `Deliver (stage 8)`
|
|
157
93
|
|
|
158
|
-
|
|
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
|
+
## Bring your own AI agent
|
|
164
95
|
|
|
165
|
-
|
|
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
|
+
AI Engineering Loop is designed to work with the tools developers already use:
|
|
191
97
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
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
|
+
- **Claude Code**
|
|
99
|
+
- **Grok CLI**
|
|
100
|
+
- **Gemini / Antigravity**
|
|
101
|
+
- Other agent hosts that can read project instructions and run local commands
|
|
211
102
|
|
|
212
|
-
|
|
213
|
-
npx ai-engineering-loop studio
|
|
214
|
-
npx ai-engineering-loop studio --port 4400 --no-open
|
|
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.
|
|
215
104
|
|
|
216
|
-
|
|
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
|
+
## Create workflows that fit your team
|
|
220
106
|
|
|
221
|
-
|
|
222
|
-
npx ai-engineering-loop sync-hosts
|
|
107
|
+
Start from a built-in workflow or make your own:
|
|
223
108
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
109
|
+
- Product feature
|
|
110
|
+
- Bug fix
|
|
111
|
+
- Security review
|
|
112
|
+
- Repository audit
|
|
113
|
+
- Refactor
|
|
114
|
+
- Custom prompt-powered Agent workflow
|
|
227
115
|
|
|
228
|
-
|
|
229
|
-
npx ai-engineering-loop generate-workflow
|
|
230
|
-
npx ai-engineering-loop generate-workflow --write
|
|
231
|
-
```
|
|
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.
|
|
232
117
|
|
|
233
|
-
|
|
118
|
+
## Safety without the scary dashboard
|
|
234
119
|
|
|
235
|
-
|
|
120
|
+
The Loop keeps a few promises:
|
|
236
121
|
|
|
237
|
-
|
|
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.**
|
|
238
129
|
|
|
239
|
-
|
|
130
|
+
Choose the level of autonomy that feels right:
|
|
240
131
|
|
|
241
|
-
|
|
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 |
|
|
242
137
|
|
|
243
|
-
|
|
138
|
+
Assisted mode is the default. Unattended mode stays off until you deliberately enable it.
|
|
244
139
|
|
|
245
|
-
##
|
|
140
|
+
## For people who want the controls
|
|
246
141
|
|
|
247
|
-
|
|
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.
|
|
248
143
|
|
|
249
|
-
|
|
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 |
|
|
144
|
+
<details>
|
|
145
|
+
<summary><strong>Show common CLI commands</strong></summary>
|
|
254
146
|
|
|
255
|
-
|
|
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
|
|
256
152
|
|
|
257
|
-
|
|
153
|
+
# Start work
|
|
154
|
+
npx ai-engineering-loop run "describe the task"
|
|
155
|
+
npx ai-engineering-loop studio
|
|
258
156
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
157
|
+
# Explore workflows
|
|
158
|
+
npx ai-engineering-loop recipe list
|
|
159
|
+
npx ai-engineering-loop recipe simulate default --mode assisted
|
|
160
|
+
|
|
161
|
+
# Inspect the active Run
|
|
162
|
+
npx ai-engineering-loop state --json
|
|
163
|
+
npx ai-engineering-loop node status
|
|
164
|
+
|
|
165
|
+
# Emergency stop and resume
|
|
166
|
+
npx ai-engineering-loop budget pause
|
|
167
|
+
npx ai-engineering-loop budget resume
|
|
168
|
+
```
|
|
262
169
|
|
|
263
|
-
|
|
170
|
+
See the [`core/`](core/) documentation for the full runtime, evidence, recipe, security, and adapter contracts.
|
|
264
171
|
|
|
265
|
-
|
|
172
|
+
</details>
|
|
266
173
|
|
|
267
|
-
|
|
174
|
+
## Works locally, delivers anywhere
|
|
268
175
|
|
|
269
|
-
|
|
176
|
+
Your living project context and Run evidence are stored under `.ai-engineering-loop/` and kept out of normal commits. Delivery adapters support:
|
|
270
177
|
|
|
271
|
-
|
|
178
|
+
- Standard Git
|
|
179
|
+
- GitHub
|
|
180
|
+
- GitLab
|
|
181
|
+
- Custom team workflows
|
|
272
182
|
|
|
273
|
-
|
|
183
|
+
The same engineering flow stays consistent even when teams use different delivery tools.
|
|
274
184
|
|
|
275
|
-
|
|
276
|
-
API Error: 400 [kiro/claude-sonnet-5] REQUEST_BODY_INVALID
|
|
277
|
-
```
|
|
185
|
+
## Why open source?
|
|
278
186
|
|
|
279
|
-
|
|
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
|
-
```
|
|
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.
|
|
417
188
|
|
|
418
|
-
|
|
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
|
+
```
|
|
419
209
|
|
|
420
210
|
## License
|
|
421
211
|
|
|
422
|
-
|
|
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,
|