ai-engineering-loop 1.0.9 → 1.0.10

package/.agents/devil-advocate.md

@@ -0,0 +1,52 @@
+---
+name: devil-advocate
+description: Use this agent after deterministic tests pass, to adversarially review a git diff against a Goal Contract. Returns a Finding Ledger. Typical triggers include a completed Maker pass and an explicit devil's advocate request.
+tools: view_file, grep_search, list_dir, run_command
+---
+
+You are the Devil's Advocate for the AI Engineering Loop. You are read-only. You never modify application source and never commit.
+
+## Budget (hard stop)
+
+Finish in at most 8 tool calls, then emit the Finding Ledger. Do not explore the rest of the repo. Do not spawn children. Do not run git log. Do not use browser_subagent.
+
+## Input barrier
+
+Use only:
+
+1. The diff file path in the spawn prompt. Read that file first. Do not run git diff if a diff path was given.
+2. Goal Contract path (if given).
+3. Verification log path (if given).
+4. At most 8 source files that appear as paths in the diff.
+
+Skip: `*.css`, files named like `*-css.ts` or `report-css.ts`, generated/vendor dirs, and any file where the diff hunk already contains enough evidence. Prefer quoting the hunk over opening the whole file.
+
+Do not ask for Maker rationale.
+
+## Output
+
+Return a Finding Ledger as a fenced JSON block and stop:
+
+```json
+{
+  "iteration": 1,
+  "executionMode": "TRUE_INDEPENDENT_AGENT",
+  "findings": [
+    {
+      "id": "DA-01",
+      "topic": "correctness",
+      "validity": "VALID",
+      "severity": "BLOCKER",
+      "disposition": "STRONG",
+      "location": "path/to/file.ext#L12-L20",
+      "acceptanceCriteria": "AC-1",
+      "failureScenario": "Concrete failing case",
+      "reproduction": "Steps to reproduce",
+      "evidence": "Hunk or line you read",
+      "concreteAlternativeDiff": "diff snippet"
+    }
+  ]
+}
+```
+
+Rules: validity VALID or INVALID; severity BLOCKER, HIGH, MEDIUM, or LOW; disposition STRONG, ACCEPTABLE, or WEAK. VALID BLOCKER or HIGH must include concreteAlternativeDiff. Empty findings is allowed.

package/.agents/judge.md

@@ -0,0 +1,40 @@
+---
+name: judge
+description: Use this agent after Devil's Advocate returns a Finding Ledger. Issues PASS, ITERATE, or ESCALATE from Validity plus Severity. Typical triggers include a completed adversarial review and an explicit judge request.
+tools: view_file, grep_search, list_dir, run_command
+---
+
+You are the Judge for the AI Engineering Loop. You do not write application code. You issue one verdict: PASS, ITERATE, or ESCALATE.
+
+## Budget (hard stop)
+
+Finish in at most 4 tool calls, then emit the verdict. Read the Finding Ledger and Goal Contract first. Open source only to fact-check a location the ledger already cited. Do not re-review the whole diff. Do not run git log. Do not spawn children. Do not use browser_subagent. Skip `*.css`, `*report-css*`, and generated/vendor files.
+
+## Inputs
+
+Use only paths in the spawn prompt: Goal Contract, verification evidence, Finding Ledger. Ignore Maker optimism and reviewer tone. Disposition never overrides Validity plus Severity.
+
+## Decision matrix
+
+- Verification missing, vague, or non-zero exit: ITERATE
+- Any VALID BLOCKER or HIGH still open: ITERATE (ESCALATE if iteration is 3 or more)
+- INVALID findings: DISMISS, cannot block delivery
+- VALID MEDIUM or LOW: ACCEPT as tradeoff; may still PASS
+- All acceptance criteria proven, verification green, zero open blockers: PASS
+
+## Output
+
+Return a fenced JSON block:
+
+```json
+{
+  "verdict": "PASS",
+  "reason": "All acceptance criteria verified; 0 open blocking findings",
+  "action": "Proceed to context impact assessment and delivery adapter",
+  "blockingFindings": [],
+  "acceptableTradeoffs": [],
+  "dismissedFindings": []
+}
+```
+
+`verdict` must be exactly PASS, ITERATE, or ESCALATE. Do not edit source.

package/.agents/workflows/ai-engineering-loop.md

@@ -0,0 +1,18 @@
+---
+name: ai-engineering-loop
+description: Run the AI Engineering Loop on Antigravity (init, status, refresh, or full Maker then Devil's Advocate then Judge).
+---
+
+Follow `policies/review-budget.md`.
+
+Parent is Maker plus orchestrator. Write `git diff` to `.ai-engineering-loop/tasks/current.diff` before review.
+
+If `invoke_subagent` (or an equivalent Task tool) exists, spawn `devil-advocate` then `judge` as siblings. Wait for each child. Do not run them in the background. Do not use `browser_subagent`.
+
+Devil's Advocate prompt: diff file path, name-only list, Goal Contract path, verification log path, and "at most 8 tool calls; skip css and generated files".
+
+Judge prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css".
+
+If no subagent tool exists, run the same budgets in this session as CONTEXT_ISOLATION_ONLY. Do not claim independent agent execution.
+
+Init/status/refresh: `npx ai-engineering-loop <command>`.

package/.claude/agents/judge.md

@@ -7,19 +7,13 @@ model: inherit
 
 You are the Judge for the AI Engineering Loop. You do not write application code. You issue one verdict: PASS, ITERATE, or ESCALATE.
 
-## When to invoke
+## Budget (hard stop)
 
-- **After Devil's Advocate.** A Finding Ledger exists. Evaluate it against the Goal Contract and verification evidence.
-- **Explicit judge request.** The orchestrator asks for a verdict.
+Finish in at most 4 tool calls, then emit the verdict. Read the Finding Ledger and Goal Contract first. Open source only to fact-check a location the ledger already cited. Do not re-review the whole diff. Do not run git log. Do not spawn children. Skip `*.css`, `*report-css*`, and generated/vendor files.
 
 ## Inputs
 
-- Goal Contract
-- Verification evidence (command, exit code 0, stdout, test counts)
-- Devil's Advocate Finding Ledger
-- Git diff only to fact-check a finding
-
-Ignore Maker optimism and reviewer tone. Disposition never overrides Validity plus Severity.
+Use only paths in the spawn prompt: Goal Contract, verification evidence, Finding Ledger. Ignore Maker optimism and reviewer tone. Disposition never overrides Validity plus Severity.
 
 ## Decision matrix
 
@@ -44,6 +38,4 @@ Return a fenced JSON block:
 }
 ```
 
-`verdict` must be exactly PASS, ITERATE, or ESCALATE.
-
-Budget: at most 4 tool calls. Read the ledger and Goal Contract first. Open source only to fact-check a cited location. Do not run git log. Do not edit source.
+`verdict` must be exactly PASS, ITERATE, or ESCALATE. Do not edit source.

package/.claude/commands/ai-engineering-loop.md

@@ -6,6 +6,6 @@ allowed-tools: "Read, Grep, Glob, Edit, Write, Task, Bash(npm run *), Bash(npm t
 
 Follow `.claude/skills/ai-engineering-loop/SKILL.md`.
 
-Use the Task tool for Devil's Advocate and Judge. Pass subagent_type, description, and prompt. If the schema includes run_in_background, set it false. Wait for each Task to finish. Write the git diff to a file and pass that path; do not let the reviewer roam the repo.
+Use the Task tool for Devil's Advocate and Judge. Pass subagent_type, description, and prompt. If the schema includes run_in_background, set it false. Wait for each Task to finish. Write the git diff to a file and pass that path. DA: 8 tool calls. Judge: 4 tool calls, ledger and contract only. Do not let either roam the repo.
 
 Arguments: init, status, refresh, or a task description.

package/.claude/skills/ai-engineering-loop/SKILL.md

@@ -40,7 +40,7 @@ Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as *
    - Write changed paths (`git diff --name-only`) into the Task prompt as a short list.
    - Put those paths in the child prompt. Do not paste Maker rationale.
 6. Stage 6: Task `subagent_type: devil-advocate`. Use `general-purpose` only if that type is rejected. If the Task schema includes `run_in_background`, set it false. Then wait for Task to return. Do not start Judge or more Maker work until the Finding Ledger is back. Prompt: diff file path, name-only list, Goal Contract path, verification log path, and "at most 8 tool calls; read the diff file; skip css and generated files".
-7. Stage 7: Task `subagent_type: judge` the same way (wait, no background). Prompt: Goal Contract, verification evidence, Finding Ledger.
+7. Stage 7: Task `subagent_type: judge` the same way (wait, no background). Use `general-purpose` only if `judge` is rejected. Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
 8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate (do not resume the previous child).
 9. Stage 8: delivery from `.ai-engineering-loop/adapter.md`.
 

package/.grok/agents/judge.md

@@ -1,39 +1,32 @@
 ---
 name: judge
-description: >
-  Impartial magistrate for the AI Engineering Loop. Spawn after Devil's Advocate
-  returns a Finding Ledger. Issues PASS, ITERATE, or ESCALATE from Validity +
-  Severity. Does not edit application source.
+description: Impartial magistrate for the AI Engineering Loop. Spawn after Devil's Advocate returns a Finding Ledger. Issues PASS, ITERATE, or ESCALATE from Validity plus Severity. Does not edit application source.
 prompt_mode: full
 permission_mode: plan
 agents_md: true
 ---
 
-You are the Judge for the AI Engineering Loop. You do not write application code.
-You evaluate evidence and issue one verdict: PASS, ITERATE, or ESCALATE.
+You are the Judge for the AI Engineering Loop. You do not write application code. You issue one verdict: PASS, ITERATE, or ESCALATE.
 
-## Inputs
+## Budget (hard stop)
 
-Use only:
+Finish in at most 4 tool calls, then emit the verdict. Read the Finding Ledger and Goal Contract first. Open source only to fact-check a location the ledger already cited. Do not re-review the whole diff. Do not run git log. Do not spawn children. Skip `*.css`, `*report-css*`, and generated/vendor files.
 
-- Goal Contract (acceptance criteria, constraints, out of scope)
-- Deterministic verification evidence (command, exit code 0, stdout, test counts)
-- Devil's Advocate Finding Ledger
-- The git diff if you need to fact-check a finding
+## Inputs
 
-Ignore Maker optimism and reviewer tone. Disposition never overrides Validity + Severity.
+Use only paths in the spawn prompt: Goal Contract, verification evidence, Finding Ledger. Ignore Maker optimism and reviewer tone. Disposition never overrides Validity plus Severity.
 
 ## Decision matrix
 
-- Verification evidence missing, vague, or non-zero exit → ITERATE
-- Any VALID BLOCKER or HIGH still open → ITERATE (ESCALATE if iteration >= MAX_ITERATIONS, default 3)
-- INVALID findings → DISMISS, cannot block delivery
-- VALID MEDIUM or LOW → ACCEPT as tradeoff; may still PASS
-- All ACs proven, verification green, zero open blockers → PASS
+- Verification missing, vague, or non-zero exit: ITERATE
+- Any VALID BLOCKER or HIGH still open: ITERATE (ESCALATE if iteration is 3 or more)
+- INVALID findings: DISMISS, cannot block delivery
+- VALID MEDIUM or LOW: ACCEPT as tradeoff; may still PASS
+- All acceptance criteria proven, verification green, zero open blockers: PASS
 
 ## Output contract
 
-Return a Judge verdict as a fenced JSON block:
+Return a fenced JSON block:
 
 ```json
 {
@@ -46,8 +39,4 @@ Return a Judge verdict as a fenced JSON block:
 }
 ```
 
-`verdict` must be exactly PASS, ITERATE, or ESCALATE.
-
-## Tools
-
-Read artifacts and run read-only git. Do not edit source. Do not spawn subagents.
+`verdict` must be exactly PASS, ITERATE, or ESCALATE. Do not edit source.

package/.grok/skills/ai-engineering-loop/SKILL.md

@@ -52,7 +52,7 @@ Run `npx ai-engineering-loop <command>` in the target repo. Do not commit unless
    - `git diff <base>...HEAD` (file)
    - verification log (file)
 6. Stage 6: `spawn_subagent` Devil's Advocate. `background: false`. `capability_mode: "execute"`. Do **not** pass `resume_from`. Wait for the child. Prompt: diff file path, name-only file list, Goal Contract path, verification log path, plus "at most 8 tool calls; skip css and generated files".
-7. Stage 7: `spawn_subagent` Judge the same way (`background: false`, wait). Prompt follows `agents/judge.md`.
+7. Stage 7: `spawn_subagent` Judge the same way (`background: false`, wait). Use `general-purpose` only if `judge` is rejected. Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
 8. If Judge says `ITERATE` and iteration < 3, Maker fixes in the parent, re-verify, spawn a **fresh** DA (new spawn, no resume).
 9. Stage 8: delivery adapter from `.ai-engineering-loop/adapter.md`.
 

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
 [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
-[![Release](https://img.shields.io/badge/release-v1.0.9-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
+[![Release](https://img.shields.io/badge/release-v1.0.10-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
 
 **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
 
@@ -220,6 +220,8 @@ See [docs/claude-code-feasibility.md](docs/claude-code-feasibility.md).
 
 ## Antigravity Agent Integration
 
+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`.
+
 When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
 
 - **`/ai-engineering-loop init`**: Initialize project context only (non-destructive bootstrap).
@@ -251,6 +253,11 @@ ai-engineering-loop/
 │   ├── orchestration.test.js           # Tests for isolation, Finding schema, Judge matrix
 │   └── grok-runtime.test.js            # Grok spawn_subagent mapping, aliases, forbidden types
 │
+├── .agents/                            # Antigravity host adapter
+│   ├── devil-advocate.md
+│   ├── judge.md
+│   └── workflows/ai-engineering-loop.md
+│
 ├── .grok/                              # Grok CLI host adapter
 │   ├── agents/devil-advocate.md        # Native DA subagent type
 │   ├── agents/judge.md                 # Native Judge subagent type

package/agents/devil-advocate.md

@@ -16,8 +16,10 @@ The Devil's Advocate executes under one of 4 runtime modes depending on platform
 
 Canonical ids are listed first; skill aliases are in parentheses.
 
-1. **`TRUE_INDEPENDENT_AGENT`** (`NATIVE_SUBAGENT`): Genuine independent child session.
-   - **Grok CLI**: `spawn_subagent` with `subagent_type: "devil-advocate"` (fallback `"general-purpose"`), `capability_mode: "execute"`, `isolation: "none"`, **omit** `resume_from`. Agent definition: `.grok/agents/devil-advocate.md`.
+1. **`TRUE_INDEPENDENT_AGENT`** (`NATIVE_SUBAGENT`): Genuine independent child session. Budget: at most 8 tool calls; diff file first; skip css/generated; no git log; wait, no background. Policy: `policies/review-budget.md`.
+   - **Claude Code**: Task `subagent_type: "devil-advocate"`. Agent: `.claude/agents/devil-advocate.md`.
+   - **Grok CLI**: `spawn_subagent` `subagent_type: "devil-advocate"`, `capability_mode: "execute"`, omit `resume_from`, `background: false`. Agent: `.grok/agents/devil-advocate.md`.
+   - **Antigravity**: `invoke_subagent` (or Task) named `devil-advocate`. Do not use `browser_subagent`. Agent: `.agents/devil-advocate.md`.
    - Do **not** use `caveman:cavecrew-reviewer` (compressed review schema, not a Finding Ledger).
 2. **`ISOLATED_AGENT_INSTANCE`** (`SDK_AGENT`): Programmatic SDK agent instance with isolated memory.
 3. **`FRESH_PROCESS_AGENT`** (`HEADLESS_SUBPROCESS`): Fresh OS process such as `grok -p` after a model response is captured.

package/agents/judge.md

@@ -4,7 +4,11 @@
 
 The **Judge Agent** is the final decision-maker of the AI Engineering Loop. It serves as an impartial magistrate that evaluates the complete evidence pipeline (Contract, Diff, Deterministic Verification Logs, and Devil's Advocate findings) to determine whether the iteration should **PASS**, **ITERATE**, or **ESCALATE**.
 
-On **Grok CLI**, the parent orchestrator spawns the Judge with `spawn_subagent` (`subagent_type: "judge"`, fallback `"general-purpose"`), `capability_mode: "execute"`, and **no** `resume_from`. Agent definition: `.grok/agents/judge.md`. The Judge is a sibling of the Devil's Advocate, never its child (Grok nesting depth is 1).
+Host spawn (Judge is a sibling of Devil's Advocate, never nested). Wait for the child. Do not run Judge in the background. Budget: at most 4 tool calls; read the Finding Ledger and Goal Contract first; fact-check cited locations only; skip css/generated; no git log. Policy: `policies/review-budget.md`.
+
+- **Claude Code**: Task `subagent_type: "judge"` (fallback `"general-purpose"`). Agent: `.claude/agents/judge.md`.
+- **Grok CLI**: `spawn_subagent` `subagent_type: "judge"`, `capability_mode: "execute"`, omit `resume_from`, `background: false`. Agent: `.grok/agents/judge.md`.
+- **Antigravity**: `invoke_subagent` (or Task) named `judge`. Do not use `browser_subagent`. Agent: `.agents/judge.md`. If no subagent tool exists, run the same budget as CONTEXT_ISOLATION_ONLY.
 
 ```mermaid
 flowchart LR

package/bin/ai-engineering-loop.js

@@ -15,7 +15,7 @@ const path = require('path');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
 
-const VERSION = '1.0.9';
+const VERSION = '1.0.10';
 const CWD = process.cwd();
 const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
 
@@ -613,6 +613,16 @@ function handleRun() {
     console.log('- Do not pass spawn_subagent, capability_mode, isolation, resume_from (Kiro 400 REQUEST_BODY_INVALID)');
     console.log('- Skill: .claude/skills/ai-engineering-loop/SKILL.md');
   }
+
+  const agAgent = path.join(CWD, '.agents', 'judge.md');
+  if (fs.existsSync(agAgent)) {
+    console.log('------------------------------------------------------------');
+    log.bold('Antigravity host:');
+    console.log('- Subagent: invoke_subagent or Task; wait; never browser_subagent');
+    console.log('- Devil\'s Advocate: 8 tool calls, diff file, skip css');
+    console.log('- Judge: 4 tool calls, ledger + contract only');
+    console.log('- Workflow: .agents/workflows/ai-engineering-loop.md');
+  }
   console.log('------------------------------------------------------------\n');
 }
 

package/docs/antigravity-feasibility.md

@@ -64,9 +64,11 @@ flowchart TD
 - **Analysis**:
   - Full codebase context in every prompt leads to context bloat and degraded attention.
   - **Optimization Strategy**:
-    - Pass only the `Goal Contract` + `git diff <base>...HEAD` to the Devil's Advocate, not the entire conversation history.
-    - Retain finding signatures and summaries rather than full raw chat transcripts.
-    - Run deterministic checks with summarized test output (failing tests in detail, passing suites as totals).
+    - Write `git diff` to `.ai-engineering-loop/tasks/current.diff` and pass that path.
+    - Devil's Advocate: at most 8 tool calls; skip css/generated; no git log; wait (no background).
+    - Judge: at most 4 tool calls; ledger + Goal Contract only; fact-check cited locations; wait.
+    - Do not use `browser_subagent` as a reviewer.
+    - If `invoke_subagent` is missing, use CONTEXT_ISOLATION_ONLY with the same budgets. See `policies/review-budget.md` and `.agents/`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-loop",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "A reusable, framework-agnostic AI Engineering Operating System for autonomous coding agents.",
   "main": "bin/ai-engineering-loop.js",
   "bin": {
@@ -19,6 +19,7 @@
     "docs/",
     "tests/",
     "scripts/",
+    ".agents/",
     ".grok/",
     ".claude/agents/",
     ".claude/commands/",

package/policies/review-budget.md

@@ -0,0 +1,24 @@
+# Review Budget (all hosts)
+
+Applies to Devil's Advocate and Judge on Claude Code, Grok CLI, and Antigravity. Parent always waits; children never run in the background.
+
+## Shared spawn rules
+
+- Write `git diff` to `.ai-engineering-loop/tasks/current.diff` before review.
+- Pass artifact **paths**, not Maker chat.
+- Spawn DA and Judge as siblings. Do not nest.
+- Prefer named types `devil-advocate` and `judge`. Use `general-purpose` only if the named type is rejected.
+- Skip `*.css`, `*report-css*`, generated/vendor. Do not run `git log`.
+
+## Devil's Advocate
+
+- At most **8** tool calls, then emit the Finding Ledger.
+- Read the diff file first. Do not run `git diff` if that path was given.
+- Open at most **8** files that appear in the diff. Prefer quoting a hunk over opening the whole file.
+
+## Judge
+
+- At most **4** tool calls, then emit PASS, ITERATE, or ESCALATE.
+- Read the Finding Ledger and Goal Contract first.
+- Open source only to fact-check a `location` the ledger already cited.
+- Do not re-review the whole diff. Do not roam the repo.

package/tests/skill-host-compat.test.js

@@ -78,3 +78,35 @@ test('Grok skill may use spawn_subagent; Claude skill must not', () => {
   assert.match(grok, /spawn_subagent/);
   assert.doesNotMatch(claude, /spawn_subagent/);
 });
+
+test('Judge budget is the same on Claude Code, Grok, and Antigravity', () => {
+  const hosts = [
+    '.claude/agents/judge.md',
+    '.grok/agents/judge.md',
+    '.agents/judge.md'
+  ];
+  for (const rel of hosts) {
+    const body = readRepo(rel);
+    assert.match(body, /Budget \(hard stop\)/);
+    assert.match(body, /4 tool calls/);
+    assert.match(body, /Do not run git log/);
+    assert.match(body, /Do not re-review the whole diff/);
+    assert.match(body, /\*report-css\*/);
+  }
+});
+
+test('Antigravity workflow waits and never uses browser_subagent as reviewer', () => {
+  const wf = readRepo('.agents/workflows/ai-engineering-loop.md');
+  parseFrontmatter(wf, 'antigravity workflow');
+  assert.match(wf, /8 tool calls/);
+  assert.match(wf, /4 tool calls/);
+  assert.match(wf, /browser_subagent/);
+  assert.match(wf, /CONTEXT_ISOLATION_ONLY/);
+});
+
+test('Claude and Grok parent skills pass Judge a 4-call ledger-only prompt', () => {
+  const claude = readRepo('.claude/skills/ai-engineering-loop/SKILL.md');
+  const grok = readRepo('.grok/skills/ai-engineering-loop/SKILL.md');
+  assert.match(claude, /4 tool calls/);
+  assert.match(grok, /4 tool calls/);
+});