ai-engineering-loop 1.7.0 → 1.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +151 -353
- package/bin/ai-engineering-loop.js +73 -3
- 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/loop-groups.js +144 -0
- package/lib/node-registry.js +8 -0
- package/lib/recipe-builder.js +27 -1
- package/lib/recipe-graph.js +111 -0
- package/lib/recipe.js +142 -8
- package/lib/run-checkout.js +175 -0
- package/lib/run-history.js +193 -0
- package/lib/run-interactions.js +184 -0
- package/lib/run-state.js +113 -13
- package/lib/studio-runtime.js +73 -0
- package/lib/studio-server.js +251 -3
- package/lib/workflow-runtime.js +392 -8
- package/package.json +2 -2
- package/schemas/compiled-plan.schema.json +5 -0
- package/schemas/edge-definition.schema.json +13 -0
- package/schemas/loop-group.schema.json +41 -0
- package/schemas/node-definition.schema.json +75 -1
- package/schemas/recipe.schema.json +10 -0
- package/schemas/workflow-event.schema.json +10 -1
- package/schemas/workflow-state.schema.json +16 -0
- package/studio/app.js +1177 -59
- package/studio/index.html +126 -8
- package/studio/styles.css +26 -13
package/README.md
CHANGED
|
@@ -1,422 +1,220 @@
|
|
|
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
|
+
On first setup, `.ai-engineering-loop/` is added to your project’s `.gitignore` so plans and Run evidence stay private by default. Want to share that context with your team? Simply remove that line from `.gitignore`.
|
|
116
57
|
|
|
117
|
-
|
|
118
|
-
- **`VALID + BLOCKER / HIGH`** $\rightarrow$ **`ITERATE`** (Maker must apply concrete fix diff and add regression tests).
|
|
119
|
-
- **`VALID + MEDIUM / LOW`** $\rightarrow$ **`ACCEPT / TRADEOFF`** (Merged; documented as acceptable tradeoff in MR notes).
|
|
120
|
-
- **`INVALID`** $\rightarrow$ **`DISMISS`** (Reviewer hallucination disproven by code; cannot block delivery; signature recorded).
|
|
58
|
+
## Meet Workflow Studio
|
|
121
59
|
|
|
122
|
-
|
|
60
|
+
Workflow Studio makes agent work feel like a product, not a terminal session.
|
|
123
61
|
|
|
124
|
-
|
|
62
|
+
### Build workflows visually
|
|
125
63
|
|
|
126
|
-
|
|
64
|
+
- Connect steps on an open canvas
|
|
65
|
+
- Add the next step directly from any node
|
|
66
|
+
- Rename nodes in place without breaking their identity
|
|
67
|
+
- Select, move, duplicate, or delete groups of nodes
|
|
68
|
+
- Import and export workflow JSON safely
|
|
69
|
+
- Create your own prompt-powered Agent nodes
|
|
127
70
|
|
|
128
|
-
|
|
71
|
+
### Start with a Goal—not a vague prompt
|
|
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
|
+
Write the task in plain language, add the outcomes that matter, and **Freeze** the Goal when it is ready. The agent cannot quietly move the finish line after work begins.
|
|
133
74
|
|
|
134
|
-
|
|
75
|
+
### Follow every Run
|
|
135
76
|
|
|
136
|
-
|
|
77
|
+
Runs have human-friendly names instead of cryptic hashes. Search previous work, inspect decisions, view evidence, and see exactly where a workflow stopped.
|
|
137
78
|
|
|
138
|
-
|
|
79
|
+
### Execute with confidence
|
|
139
80
|
|
|
140
|
-
|
|
141
|
-
# Bootstrap .ai-engineering-loop/ context from repository discovery
|
|
142
|
-
npx ai-engineering-loop init
|
|
81
|
+
The Execute button lives beside the workflow trigger. A Run starts only when the Goal, workflow, mode, and safety checks are ready.
|
|
143
82
|
|
|
144
|
-
|
|
145
|
-
npx ai-engineering-loop status
|
|
83
|
+
## One workspace from idea to delivery
|
|
146
84
|
|
|
147
|
-
|
|
148
|
-
npx ai-engineering-loop refresh
|
|
85
|
+
The experience is organized into four simple moments:
|
|
149
86
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
87
|
+
1. **Specify** — agree on what success and failure look like.
|
|
88
|
+
2. **Make** — let the agent investigate, plan, and build.
|
|
89
|
+
3. **Review** — verify the result and challenge unsupported claims.
|
|
90
|
+
4. **Deliver** — ask for human approval before publishing.
|
|
154
91
|
|
|
155
|
-
|
|
156
|
-
npx ai-engineering-loop state --json
|
|
92
|
+
Under the hood, these moments use eight evidence-backed stages. The rigor is there when you need it, but it does not have to dominate the experience.
|
|
157
93
|
|
|
158
|
-
|
|
159
|
-
npx ai-engineering-loop policy show
|
|
160
|
-
npx ai-engineering-loop policy set --allow-unattended true
|
|
161
|
-
npx ai-engineering-loop budget status
|
|
162
|
-
npx ai-engineering-loop budget pause
|
|
163
|
-
npx ai-engineering-loop budget resume
|
|
94
|
+
`Specify (stages 0-1)` → `Make (stages 2-4)` → `Review (stages 5-7)` → `Deliver (stage 8)`
|
|
164
95
|
|
|
165
|
-
|
|
166
|
-
npx ai-engineering-loop budget record --input 1200 --output 300 --model provider/model-id
|
|
167
|
-
npx ai-engineering-loop budget status --node root-cause --estimate 4000
|
|
168
|
-
npx ai-engineering-loop budget record --node root-cause --input 3000 --output 700 --model provider/model-id
|
|
169
|
-
|
|
170
|
-
# Isolate unattended Maker, then capture only its diff
|
|
171
|
-
npx ai-engineering-loop sandbox create
|
|
172
|
-
npx ai-engineering-loop sandbox capture
|
|
173
|
-
|
|
174
|
-
# Validate artifacts and advance stages
|
|
175
|
-
npx ai-engineering-loop gate goal
|
|
176
|
-
npx ai-engineering-loop gate report
|
|
177
|
-
npx ai-engineering-loop gate maker
|
|
178
|
-
npx ai-engineering-loop gate verification
|
|
179
|
-
npx ai-engineering-loop gate review
|
|
180
|
-
npx ai-engineering-loop escalation --json
|
|
181
|
-
npx ai-engineering-loop gate judge
|
|
182
|
-
npx ai-engineering-loop gate delivery
|
|
183
|
-
|
|
184
|
-
# Build bounded model-visible context
|
|
185
|
-
npx ai-engineering-loop context devil-advocate <files...>
|
|
186
|
-
npx ai-engineering-loop context judge <files...>
|
|
187
|
-
|
|
188
|
-
# Validate installation and the production evaluation catalog
|
|
189
|
-
npx ai-engineering-loop doctor
|
|
190
|
-
npx ai-engineering-loop eval
|
|
96
|
+
## Bring your own AI agent
|
|
191
97
|
|
|
192
|
-
|
|
193
|
-
npx ai-engineering-loop recipe list
|
|
194
|
-
npx ai-engineering-loop recipe validate default --mode assisted
|
|
195
|
-
npx ai-engineering-loop recipe explain default --mode assisted
|
|
196
|
-
npx ai-engineering-loop recipe graph default --mode assisted
|
|
197
|
-
npx ai-engineering-loop recipe simulate default --mode assisted
|
|
198
|
-
npx ai-engineering-loop recipe catalog --json
|
|
199
|
-
npx ai-engineering-loop recipe create api-bugfix --from bugfix
|
|
200
|
-
npx ai-engineering-loop recipe inspect api-bugfix --json
|
|
201
|
-
npx ai-engineering-loop recipe diff bugfix api-bugfix
|
|
202
|
-
npx ai-engineering-loop recipe install candidate.json
|
|
203
|
-
npx ai-engineering-loop recipe install candidate-v2.json --replace
|
|
204
|
-
|
|
205
|
-
# Operate a custom node in an immutable recipe-bound run
|
|
206
|
-
npx ai-engineering-loop node status
|
|
207
|
-
npx ai-engineering-loop node start root-cause
|
|
208
|
-
npx ai-engineering-loop node activity root-cause --message "Comparing failing evidence"
|
|
209
|
-
npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
|
|
210
|
-
npx ai-engineering-loop node approve delivery-approval --yes
|
|
98
|
+
AI Engineering Loop is designed to work with the tools developers already use:
|
|
211
99
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
100
|
+
- **Claude Code**
|
|
101
|
+
- **Grok CLI**
|
|
102
|
+
- **Gemini / Antigravity**
|
|
103
|
+
- Other agent hosts that can read project instructions and run local commands
|
|
215
104
|
|
|
216
|
-
|
|
217
|
-
npx ai-engineering-loop handoff create --audience developer
|
|
218
|
-
npx ai-engineering-loop handoff inspect <run-id>.ael-handoff.json
|
|
219
|
-
npx ai-engineering-loop handoff brief <run-id>.ael-handoff.json
|
|
105
|
+
The project includes ready-to-use skills and reviewer roles for supported hosts. Each host follows the same Goal, verification, review, and approval rules.
|
|
220
106
|
|
|
221
|
-
|
|
222
|
-
npx ai-engineering-loop sync-hosts
|
|
107
|
+
## Create workflows that fit your team
|
|
223
108
|
|
|
224
|
-
|
|
225
|
-
npx ai-engineering-loop generate-adapter
|
|
226
|
-
npx ai-engineering-loop generate-adapter --type github
|
|
109
|
+
Start from a built-in workflow or make your own:
|
|
227
110
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
111
|
+
- Product feature
|
|
112
|
+
- Bug fix
|
|
113
|
+
- Security review
|
|
114
|
+
- Repository audit
|
|
115
|
+
- Refactor
|
|
116
|
+
- Custom prompt-powered Agent workflow
|
|
117
|
+
|
|
118
|
+
Custom Agents can reference approved capabilities, MCP connections, input artifacts, and output formats. They do not receive hidden shell, filesystem, network, or secret access.
|
|
119
|
+
|
|
120
|
+
## Safety without the scary dashboard
|
|
121
|
+
|
|
122
|
+
The Loop keeps a few promises:
|
|
123
|
+
|
|
124
|
+
- **Nothing ships only because an AI says “done.”**
|
|
125
|
+
- **Goals are frozen before implementation.**
|
|
126
|
+
- **Verification records the real command and result.**
|
|
127
|
+
- **A Devil’s Advocate challenges the work before the Judge decides.**
|
|
128
|
+
- **Sensitive context is bounded and redacted.**
|
|
129
|
+
- **Publishing in assisted mode needs human approval.**
|
|
130
|
+
- **The browser never silently runs arbitrary shell commands.**
|
|
131
|
+
|
|
132
|
+
Choose the level of autonomy that feels right:
|
|
232
133
|
|
|
233
|
-
|
|
134
|
+
| Mode | Best for |
|
|
135
|
+
|---|---|
|
|
136
|
+
| **Report only** | Explore a codebase without changing it |
|
|
137
|
+
| **Assisted** | Everyday work with human approval before delivery |
|
|
138
|
+
| **Unattended** | Trusted automation with stricter isolation and limits |
|
|
234
139
|
|
|
235
|
-
|
|
140
|
+
Assisted mode is the default. Unattended mode stays off until you deliberately enable it.
|
|
236
141
|
|
|
237
|
-
|
|
142
|
+
## For people who want the controls
|
|
238
143
|
|
|
239
|
-
|
|
144
|
+
The friendly workflow sits on top of a complete local CLI. You can inspect recipes, budgets, evidence, nodes, gates, policies, and handoffs whenever you need to.
|
|
240
145
|
|
|
241
|
-
|
|
146
|
+
<details>
|
|
147
|
+
<summary><strong>Show common CLI commands</strong></summary>
|
|
242
148
|
|
|
243
|
-
|
|
149
|
+
```bash
|
|
150
|
+
# Project setup and health
|
|
151
|
+
npx ai-engineering-loop init
|
|
152
|
+
npx ai-engineering-loop status
|
|
153
|
+
npx ai-engineering-loop doctor
|
|
244
154
|
|
|
245
|
-
|
|
155
|
+
# Start work
|
|
156
|
+
npx ai-engineering-loop run "describe the task"
|
|
157
|
+
npx ai-engineering-loop studio
|
|
246
158
|
|
|
247
|
-
|
|
159
|
+
# Explore workflows
|
|
160
|
+
npx ai-engineering-loop recipe list
|
|
161
|
+
npx ai-engineering-loop recipe simulate default --mode assisted
|
|
248
162
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
| Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `capability_mode: execute`, omit `resume_from` |
|
|
253
|
-
| Judge | `judge` (fallback `general-purpose`) | Sibling of DA, never nested under DA |
|
|
163
|
+
# Inspect the active Run
|
|
164
|
+
npx ai-engineering-loop state --json
|
|
165
|
+
npx ai-engineering-loop node status
|
|
254
166
|
|
|
255
|
-
|
|
167
|
+
# Emergency stop and resume
|
|
168
|
+
npx ai-engineering-loop budget pause
|
|
169
|
+
npx ai-engineering-loop budget resume
|
|
170
|
+
```
|
|
256
171
|
|
|
257
|
-
|
|
172
|
+
See the [`core/`](core/) documentation for the full runtime, evidence, recipe, security, and adapter contracts.
|
|
258
173
|
|
|
259
|
-
|
|
260
|
-
- `.grok/skills/ai-engineering-loop/SKILL.md`
|
|
261
|
-
- `.grok/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
|
|
174
|
+
</details>
|
|
262
175
|
|
|
263
|
-
|
|
176
|
+
## Works locally, delivers anywhere
|
|
264
177
|
|
|
265
|
-
|
|
178
|
+
Your living project context and Run evidence are stored under `.ai-engineering-loop/` and kept out of normal commits by default. You can remove its `.gitignore` entry whenever you want to share that context. Delivery adapters support:
|
|
266
179
|
|
|
267
|
-
|
|
180
|
+
- Standard Git
|
|
181
|
+
- GitHub
|
|
182
|
+
- GitLab
|
|
183
|
+
- Custom team workflows
|
|
268
184
|
|
|
269
|
-
|
|
185
|
+
The same engineering flow stays consistent even when teams use different delivery tools.
|
|
270
186
|
|
|
271
|
-
|
|
187
|
+
## Why open source?
|
|
272
188
|
|
|
273
|
-
|
|
189
|
+
The rules that decide whether AI-generated work is trustworthy should be inspectable. AI Engineering Loop keeps its schemas, safety policies, verification logic, recipes, and agent prompts in the repository.
|
|
274
190
|
|
|
275
|
-
|
|
276
|
-
API Error: 400 [kiro/claude-sonnet-5] REQUEST_BODY_INVALID
|
|
277
|
-
```
|
|
191
|
+
No hidden cloud control plane is required. No project source is uploaded by Workflow Studio.
|
|
278
192
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
- `.claude/agents/devil-advocate.md` / `.claude/agents/judge.md`
|
|
290
|
-
- `.claude/skills/ai-engineering-loop/SKILL.md`
|
|
291
|
-
- `.claude/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
|
|
292
|
-
|
|
293
|
-
On Kiro auto mode, pre-allow verification Bash or the safety classifier 400s the session. Copy `templates/repo-config/claude-permissions.json` into the target repo `.claude/settings.local.json` `permissions.allow` list. If Bash returns "cannot determine the safety", do not retry; switch permission mode to default and start a new session.
|
|
294
|
-
|
|
295
|
-
See [docs/claude-code-feasibility.md](docs/claude-code-feasibility.md).
|
|
296
|
-
|
|
297
|
-
---
|
|
298
|
-
|
|
299
|
-
## Antigravity Agent Integration
|
|
300
|
-
|
|
301
|
-
Antigravity uses `.agents/devil-advocate.md`, `.agents/judge.md`, and `.agents/workflows/ai-engineering-loop.md`. Same review budget as Claude Code and Grok: DA 8 tool calls, Judge 4, wait (no background), skip css/generated, never `browser_subagent`. If `invoke_subagent` is missing, disclose `CONTEXT_ISOLATION_ONLY`.
|
|
302
|
-
|
|
303
|
-
When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
|
|
304
|
-
|
|
305
|
-
- **`/ai-engineering-loop init`**: Initialize project context only (non-destructive bootstrap).
|
|
306
|
-
- **`/ai-engineering-loop status`**: Check repository context health & baseline freshness.
|
|
307
|
-
- **`/ai-engineering-loop refresh`**: Reconcile drifted context files non-destructively.
|
|
308
|
-
- **`/ai-engineering-loop [task description]`**: Execute the full 8-stage engineering lifecycle with pre-task drift gate and post-task impact assessment.
|
|
309
|
-
|
|
310
|
-
On Grok CLI the same slash command is provided by `.grok/commands/ai-engineering-loop.md` and runs Devil's Advocate / Judge as native subagents.
|
|
311
|
-
|
|
312
|
-
---
|
|
313
|
-
|
|
314
|
-
## Repository Structure
|
|
315
|
-
|
|
316
|
-
```text
|
|
317
|
-
ai-engineering-loop/
|
|
318
|
-
│
|
|
319
|
-
├── README.md # Operating system overview & architecture
|
|
320
|
-
├── LICENSE # MIT Open Source License
|
|
321
|
-
├── package.json # CLI package manifest
|
|
322
|
-
│
|
|
323
|
-
├── bin/ # CLI execution entrypoints
|
|
324
|
-
│ └── ai-engineering-loop.js # npx executable CLI (init, status, refresh, run, sync-hosts)
|
|
325
|
-
│
|
|
326
|
-
├── lib/ # Core orchestration & decision engine
|
|
327
|
-
│ ├── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
|
|
328
|
-
│ ├── recipe.js # Declarative graph validator and deterministic compiler
|
|
329
|
-
│ └── workflow-runtime.js # Resumable scheduler and hash-chained event ledger
|
|
330
|
-
│
|
|
331
|
-
├── recipes/ # Built-in workflow presets; target repos may add their own
|
|
332
|
-
│ ├── default.json # Current production loop represented as a graph
|
|
333
|
-
│ └── audit.json # Read-only report workflow
|
|
334
|
-
│
|
|
335
|
-
├── tests/ # Deterministic test suites
|
|
336
|
-
│ ├── capability-selection.test.js # Unit tests for capability lifecycle & truthful selection
|
|
337
|
-
│ ├── orchestration.test.js # Tests for isolation, Finding schema, Judge matrix
|
|
338
|
-
│ └── grok-runtime.test.js # Grok spawn_subagent mapping, aliases, forbidden types
|
|
339
|
-
│
|
|
340
|
-
├── .agents/ # Antigravity host adapter
|
|
341
|
-
│ ├── devil-advocate.md
|
|
342
|
-
│ ├── judge.md
|
|
343
|
-
│ └── workflows/ai-engineering-loop.md
|
|
344
|
-
│
|
|
345
|
-
├── .grok/ # Grok CLI host adapter
|
|
346
|
-
│ ├── agents/devil-advocate.md # Native DA subagent type
|
|
347
|
-
│ ├── agents/judge.md # Native Judge subagent type
|
|
348
|
-
│ ├── skills/ai-engineering-loop/ # Grok skill (spawn protocol)
|
|
349
|
-
│ └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
|
|
350
|
-
│
|
|
351
|
-
├── .claude/ # Claude Code host adapter (Kiro-safe)
|
|
352
|
-
│ ├── agents/devil-advocate.md # Task subagent type
|
|
353
|
-
│ ├── agents/judge.md # Task subagent type
|
|
354
|
-
│ ├── skills/ai-engineering-loop/ # Claude skill (Task keys only)
|
|
355
|
-
│ └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
|
|
356
|
-
│
|
|
357
|
-
├── core/ # Generic engineering loop specifications
|
|
358
|
-
│ ├── orchestration-model.md # 3-stage capability lifecycle & execution priority
|
|
359
|
-
│ ├── project-initialization.md # Auto-discovery & initialization lifecycle
|
|
360
|
-
│ ├── context-refresh-policy.md # Progressive drift hierarchy & living baseline
|
|
361
|
-
│ ├── context-impact-assessment.md # Post-task impact assessment (NONE, TARGETED, MAJOR)
|
|
362
|
-
│ ├── goal-contract.md # Task contract schema & acceptance criteria
|
|
363
|
-
│ ├── grill-policy.md # Stage 1 human alignment (design tree)
|
|
364
|
-
│ ├── root-cause-analysis.md # Stage 2 diagnosis gates
|
|
365
|
-
│ ├── handoff-policy.md # Mid-loop session handoff artifact
|
|
366
|
-
│ ├── verification-loop.md # Dual-layer verification & Evidence Contract
|
|
367
|
-
│ ├── definition-of-done.md # 5 pillars of Done & rejection triggers
|
|
368
|
-
│ ├── iteration-policy.md # Bounded autonomous loop (MAX_ITERATIONS = 3)
|
|
369
|
-
│ ├── escalation-policy.md # Deterministic human escalation triggers
|
|
370
|
-
│ ├── judge-policy.md # Evaluation rules, triage audit, & verdicts
|
|
371
|
-
│ ├── configuration-precedence.md # 5-layer precedence & conflict resolution
|
|
372
|
-
│ ├── controlled-workflow-runtime.md # Immutable plan, scheduler, events, and recovery
|
|
373
|
-
│ ├── workflow-recipes.md # Recipe safety backbone and AI authoring protocol
|
|
374
|
-
│ └── repo-config-schema.md # Schema for target repo .ai-engineering-loop/
|
|
375
|
-
│
|
|
376
|
-
├── profiles/ # Project archetype profiles
|
|
377
|
-
│ ├── README.md # Profile catalog & auto-detection rules
|
|
378
|
-
│ ├── web-app.md # Frontend web applications
|
|
379
|
-
│ ├── backend-api.md # Backend APIs & microservices
|
|
380
|
-
│ ├── mobile-app.md # Native & cross-platform mobile apps
|
|
381
|
-
│ ├── library.md # Reusable SDKs & shared packages
|
|
382
|
-
│ └── monorepo.md # Multi-package monorepo workspaces
|
|
383
|
-
│
|
|
384
|
-
├── agents/ # Triad agent role specifications
|
|
385
|
-
│ ├── maker.md # Maker agent: surgical diffs & unit tests
|
|
386
|
-
│ ├── devil-advocate.md # Adversarial reviewer: dual-axis finding ledger & diffs
|
|
387
|
-
│ └── judge.md # Judge agent: impartial magistrate on Validity + Severity
|
|
388
|
-
│
|
|
389
|
-
├── policies/ # Operational schemas & algorithms
|
|
390
|
-
│ ├── discovery-safety-policy.md # Secret protection & non-destructive discovery rules
|
|
391
|
-
│ ├── finding-policy.md # Dual-axis finding schema & severity matrix
|
|
392
|
-
│ ├── tdd-policy.md # Red-green at named seams
|
|
393
|
-
│ ├── evidence-policy.md # 5-level evidence hierarchy & Verification Evidence Contract
|
|
394
|
-
│ └── no-progress-policy.md # Finding signature hashing & stagnation detection
|
|
395
|
-
│
|
|
396
|
-
├── adapters/ # Pluggable Stage 8 delivery (not a second OS)
|
|
397
|
-
│ ├── README.md # Catalog: standard, github, gitlab, dot
|
|
398
|
-
│ ├── generate-adapter/SKILL.md # Grill Q1-Q5, then write adapter.md
|
|
399
|
-
│ ├── generate-workflow/SKILL.md # Grill Q1-Q6, then write workflow.md + lessons.md
|
|
400
|
-
│ ├── standard/ # Generic git delivery (any forge)
|
|
401
|
-
│ ├── github/ # gh pr / GitHub Issues
|
|
402
|
-
│ ├── gitlab/ # glab mr (not the DOT pipeline)
|
|
403
|
-
│ └── dot/ # DOT-specific GitLab + multi-branch + chat
|
|
404
|
-
│
|
|
405
|
-
└── templates/ # Starter templates for target repositories
|
|
406
|
-
└── repo-config/ # Ready-to-copy .ai-engineering-loop/ files
|
|
407
|
-
├── config.md # Project identity & profile binding
|
|
408
|
-
├── architecture.md # Layers & boundary invariants
|
|
409
|
-
├── glossary.md # Ubiquitous language
|
|
410
|
-
├── adr-readme.md # ADR folder template
|
|
411
|
-
├── conventions.md # Code standards & forbidden patterns
|
|
412
|
-
├── verification.md # CLI test/lint/build commands
|
|
413
|
-
├── adapter.md # Configured release pipeline
|
|
414
|
-
├── workflow.md # Optional loop overlay hooks
|
|
415
|
-
└── lessons.md # Optional confirmed process lessons
|
|
416
|
-
```
|
|
193
|
+
## Documentation
|
|
194
|
+
|
|
195
|
+
- [Workflow Studio](core/local-workflow-studio.md)
|
|
196
|
+
- [Workflow recipes](core/workflow-recipes.md)
|
|
197
|
+
- [Runtime safety](core/runtime-safety.md)
|
|
198
|
+
- [Verification](core/verification-loop.md)
|
|
199
|
+
- [Controlled workflow runtime](core/controlled-workflow-runtime.md)
|
|
200
|
+
- [Security](SECURITY.md)
|
|
201
|
+
- [Support](SUPPORT.md)
|
|
417
202
|
|
|
418
|
-
|
|
203
|
+
## Contributing
|
|
204
|
+
|
|
205
|
+
Ideas, workflow recipes, bug reports, and pull requests are welcome. Start with an issue or open a focused PR with a clear explanation of the user outcome.
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
npm test
|
|
209
|
+
npm run doctor
|
|
210
|
+
```
|
|
419
211
|
|
|
420
212
|
## License
|
|
421
213
|
|
|
422
|
-
|
|
214
|
+
MIT © [Ega Gofur](https://github.com/egagofur)
|
|
215
|
+
|
|
216
|
+
<div align="center">
|
|
217
|
+
|
|
218
|
+
**Let the agent handle the process. Keep your attention on the product.**
|
|
219
|
+
|
|
220
|
+
</div>
|