ai-engineering-loop 1.0.5 → 1.0.6

package/.claude/agents/devil-advocate.md

@@ -0,0 +1,60 @@
+---
+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: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are the Devil's Advocate for the AI Engineering Loop. You are read-only. You never modify application source and never commit.
+
+## When to invoke
+
+- **After Maker verification.** Tests passed. Review the diff against the Goal Contract.
+- **Explicit review request.** The user or orchestrator asks for a devil's advocate pass.
+
+## Input barrier
+
+Use only the spawn prompt plus:
+
+- Goal Contract
+- `.ai-engineering-loop/` (`architecture.md`, `conventions.md`, `verification.md`)
+- The git diff (path in the prompt, or `git diff <base>...HEAD`)
+- Verification logs (exit code, stdout, test counts)
+
+Do not ask for Maker rationale. Do not treat parent narration as evidence.
+
+## Output
+
+Return a Finding Ledger as a fenced JSON block:
+
+```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": "What you read in the diff or source",
+      "concreteAlternativeDiff": "diff snippet"
+    }
+  ]
+}
+```
+
+Rules:
+
+- `validity` is VALID or INVALID.
+- `severity` is BLOCKER, HIGH, MEDIUM, or LOW.
+- `disposition` is STRONG, ACCEPTABLE, or WEAK.
+- Every VALID BLOCKER or HIGH finding must include `concreteAlternativeDiff`.
+- Empty `findings` is allowed when the diff is clean against the Goal Contract.
+
+Use Read, Grep, Glob, and read-only Bash (`git diff`, `git log`, `git show`). Do not write files.

package/.claude/agents/judge.md

@@ -0,0 +1,49 @@
+---
+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: Read, Grep, Glob, Bash
+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
+
+- **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.
+
+## 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.
+
+## 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.
+
+Use Read and read-only git. Do not edit source.

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

@@ -0,0 +1,10 @@
+---
+name: ai-engineering-loop
+description: Run the AI Engineering Loop (init, status, refresh, or full Maker then Devil's Advocate then Judge).
+---
+
+Follow `.claude/skills/ai-engineering-loop/SKILL.md`.
+
+Use the Task tool for Devil's Advocate and Judge. Pass only subagent_type, description, and prompt.
+
+Arguments: init, status, refresh, or a task description.

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "enabledMcpjsonServers": [
+    "browsermcp"
+  ],
+  "disabledMcpjsonServers": [
+    "Figma-20182",
+    "Figma-i5xgii"
+  ]
+}

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

@@ -0,0 +1,59 @@
+---
+name: ai-engineering-loop
+description: Use when the user runs /ai-engineering-loop, asks to init or refresh living project context, or wants the Maker / Devil's Advocate / Judge engineering loop on Claude Code.
+---
+
+# AI Engineering Loop (Claude Code)
+
+Canonical specs: `core/`, `agents/`, `policies/`. Read those files. Do not invent extra tool parameters.
+
+## Host rule (prevents 400 REQUEST_BODY_INVALID)
+
+Claude Code talks to strict proxies (including Kiro). Follow this exactly:
+
+1. Use only tools that exist in this session.
+2. For subagents, call the host tool named **Task** (or **Agent** if that is the only subagent tool). Pass **only** these keys:
+   - `subagent_type`
+   - `description`
+   - `prompt`
+3. Do **not** add any other keys. Extra keys make Kiro return HTTP 400 `REQUEST_BODY_INVALID`.
+4. If no Task/Agent tool exists, review in this session and label it `CONTEXT_ISOLATION_ONLY`. Do not invent a tool name.
+
+## Commands
+
+- `init` / `status` / `refresh`: run `npx ai-engineering-loop <command>` in the repo. Do not commit unless asked.
+- Any other argument: full loop for that task.
+
+## Loop
+
+Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as **siblings**, not nested.
+
+1. Stage 0: `npx ai-engineering-loop status` (init or refresh if missing or stale).
+2. Stage 1: write a Goal Contract. Schema: `core/goal-contract.md`.
+3. Stages 2-4: Maker work in the parent. Surgical diff plus tests.
+4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
+5. Write artifact paths (Goal Contract, diff, verification log). Put those paths in child prompts. Do not paste Maker rationale.
+6. Stage 6: Task `subagent_type: devil-advocate` (fallback `general-purpose`). Prompt: artifact paths plus Finding Ledger contract from `agents/devil-advocate.md`.
+7. Stage 7: Task `subagent_type: judge` (fallback `general-purpose`). Prompt: Goal Contract, verification evidence, Finding Ledger. Verdict is PASS, ITERATE, or ESCALATE.
+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`.
+
+## Report header
+
+When Task/Agent actually returned a child result:
+
+```
+Execution Mode: TRUE_INDEPENDENT_AGENT
+Independent LLM Execution: PROVEN
+Native Subagent Invocation: AVAILABLE
+Review Method: True Independent Agent
+```
+
+When no subagent tool exists:
+
+```
+Execution Mode: CONTEXT_ISOLATION_ONLY
+Independent LLM Execution: NOT PROVEN
+Native Subagent Invocation: UNAVAILABLE
+Review Method: Clean-Slate Artifact Isolation Barrier
+```

package/README.md

@@ -6,13 +6,13 @@
 [![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.5-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
+[![Release](https://img.shields.io/badge/release-v1.0.6-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
 
 **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
 
 *Featuring living project context, strict verification evidence contracts, 3-stage capability lifecycle registry, and dual-axis Judge evaluation.*
 
-[Overview](#overview--philosophy) • [Runtime Capability Registry](#runtime-capability-registry--execution-modes) • [Verification Evidence](#verification-evidence-contract) • [CLI Commands](#cli-interface--commands) • [Grok CLI](#grok-cli-integration) • [Antigravity](#antigravity-agent-integration) • [Lifecycle](#lifecycle-stages) • [Architecture](#architecture--5-layer-configuration) • [Project Profiles](#project-profiles) • [Repository Structure](#repository-structure) • [Reference Examples](#reference-examples) • [Contributing](#contributing)
+[Overview](#overview--philosophy) • [Runtime Capability Registry](#runtime-capability-registry--execution-modes) • [Verification Evidence](#verification-evidence-contract) • [CLI Commands](#cli-interface--commands) • [Grok CLI](#grok-cli-integration) • [Claude Code](#claude-code-integration) • [Antigravity](#antigravity-agent-integration) • [Lifecycle](#lifecycle-stages) • [Architecture](#architecture--5-layer-configuration) • [Project Profiles](#project-profiles) • [Repository Structure](#repository-structure) • [Reference Examples](#reference-examples) • [Contributing](#contributing)
 
 </div>
 
@@ -188,6 +188,32 @@ See [docs/grok-cli-feasibility.md](docs/grok-cli-feasibility.md).
 
 ---
 
+## Claude Code Integration
+
+Claude Code is a first-class host. Use the **Task** (or **Agent**) tool with **only** `subagent_type`, `description`, and `prompt`.
+
+Do **not** pass Grok keys (`spawn_subagent`, `capability_mode`, `isolation`, `resume_from`). Extra keys are the usual cause of:
+
+```
+API Error: 400 [kiro/claude-sonnet-5] REQUEST_BODY_INVALID
+```
+
+| Loop role | Claude Code `subagent_type` | Task keys |
+|---|---|---|
+| Orchestrator / Maker | parent session | n/a |
+| Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+| Judge | `judge` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+
+Repo-local Claude Code files:
+
+- `.claude/agents/devil-advocate.md` / `.claude/agents/judge.md`
+- `.claude/skills/ai-engineering-loop/SKILL.md`
+- `.claude/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
+
+See [docs/claude-code-feasibility.md](docs/claude-code-feasibility.md).
+
+---
+
 ## Antigravity Agent Integration
 
 When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
@@ -227,6 +253,12 @@ ai-engineering-loop/
 │   ├── skills/ai-engineering-loop/     # Grok skill (spawn protocol)
 │   └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
 │
+├── .claude/                            # Claude Code host adapter (Kiro-safe)
+│   ├── agents/devil-advocate.md        # Task subagent type
+│   ├── agents/judge.md                 # Task subagent type
+│   ├── skills/ai-engineering-loop/     # Claude skill (Task keys only)
+│   └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
+│
 ├── core/                               # Generic engineering loop specifications
 │   ├── orchestration-model.md          # 3-stage capability lifecycle & execution priority
 │   ├── project-initialization.md       # Auto-discovery & initialization lifecycle

package/README.npm.md

@@ -44,6 +44,10 @@ npx ai-engineering-loop run
 
 Inside a Grok TUI session, `/ai-engineering-loop` uses repo-local `.grok/agents/` types. Devil's Advocate and Judge spawn as sibling children (`capability_mode: execute`, no `resume_from`). Do not use `caveman:cavecrew-reviewer` as the loop reviewer.
 
+## Claude Code
+
+Inside Claude Code, `/ai-engineering-loop` uses `.claude/agents/` types via the **Task** tool. Pass only `subagent_type`, `description`, and `prompt`. Do not pass Grok keys (`spawn_subagent`, `capability_mode`, `resume_from`) — extra keys cause Kiro `REQUEST_BODY_INVALID`.
+
 ---
 
 ## Antigravity IDE Integration

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.5';
+const VERSION = '1.0.6';
 const CWD = process.cwd();
 const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
 
@@ -601,6 +601,18 @@ function handleRun() {
     }
     console.log('- Skill: .grok/skills/ai-engineering-loop/SKILL.md');
   }
+
+  const claudeSkill = path.join(CWD, '.claude', 'skills', 'ai-engineering-loop', 'SKILL.md');
+  const claudeAgent = path.join(CWD, '.claude', 'agents', 'devil-advocate.md');
+  if (fs.existsSync(claudeSkill) || fs.existsSync(claudeAgent)) {
+    console.log('------------------------------------------------------------');
+    log.bold('Claude Code host:');
+    console.log('- Subagent tool: Task (or Agent). Keys allowed: subagent_type, description, prompt');
+    console.log('- Devil\'s Advocate: Task subagent_type=devil-advocate');
+    console.log('- Judge: Task subagent_type=judge (sibling, not nested)');
+    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');
+  }
   console.log('------------------------------------------------------------\n');
 }
 

package/docs/claude-code-feasibility.md

@@ -0,0 +1,45 @@
+# Claude Code Feasibility and Kiro Request Safety
+
+## 1. Problem
+
+Claude Code users (including Kiro-backed models such as `kiro/claude-sonnet-5`) hit:
+
+```
+API Error: 400 [kiro/claude-sonnet-5] [400]:
+{"message":"Improperly formed request.","reason":"REQUEST_BODY_INVALID"}
+```
+
+Kiro's `generateAssistantResponse` rejects request bodies that Claude Code will happily send. Two skill-side causes were confirmed:
+
+1. **Extra tool keys.** The shared skill told the model to call `spawn_subagent` with `capability_mode`, `isolation`, and `resume_from`. Claude Code's Task/Agent schema does not have those fields. Proxies that validate additionalProperties fail with `REQUEST_BODY_INVALID`.
+2. **Hostile markup in the injected skill.** Mermaid (`<br>`, nested `{braces}`), LaTeX (`$\rightarrow$`), and folded YAML descriptions inflate and corrupt the system/skill payload Kiro receives.
+
+This is separate from 9router bugs that reject any Anthropic `system` field. Those need a router fix. The skill must still not add extra invalid keys or markup.
+
+## 2. Claude Code mapping
+
+| Loop role | Claude Code type | Task keys allowed |
+|---|---|---|
+| Orchestrator / Maker | parent session | n/a |
+| Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+| Judge | `judge` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+
+Do not pass Grok keys (`spawn_subagent`, `capability_mode`, `resume_from`, `isolation`, `background`) on Claude Code.
+
+Repo files:
+
+- `.claude/skills/ai-engineering-loop/SKILL.md`
+- `.claude/agents/devil-advocate.md`
+- `.claude/agents/judge.md`
+- `.claude/commands/ai-engineering-loop.md`
+
+## 3. Mode selection
+
+| Condition | Mode |
+|---|---|
+| Task/Agent tool present, child result returned | `TRUE_INDEPENDENT_AGENT` |
+| No subagent tool | `CONTEXT_ISOLATION_ONLY` |
+
+## 4. What stays in Grok-only files
+
+Grok spawn details live in `.grok/skills/ai-engineering-loop/SKILL.md`. Claude Code must not load that file as its skill. Claude Code discovers `.claude/` first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-loop",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "A reusable, framework-agnostic AI Engineering Operating System for autonomous coding agents.",
   "main": "bin/ai-engineering-loop.js",
   "bin": {
@@ -20,6 +20,7 @@
     "tests/",
     "scripts/",
     ".grok/",
+    ".claude/",
     "LICENSE",
     "README.md",
     "README.npm.md"
@@ -41,6 +42,7 @@
     "autonomous-agents",
     "antigravity",
     "grok",
+    "claude-code",
     "subagents"
   ],
   "author": "Ega Gofur",

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

@@ -0,0 +1,68 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+function readRepo(rel) {
+  return fs.readFileSync(path.join(ROOT, rel), 'utf8');
+}
+
+function parseFrontmatter(content, label) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+  assert.ok(match, `${label} is missing YAML frontmatter`);
+  const fm = match[1];
+  assert.match(fm, /^name:\s*[a-z0-9-]+$/m, `${label} name must be kebab-case`);
+  assert.match(fm, /^description:\s+\S/m, `${label} description must be a single-line value`);
+  assert.doesNotMatch(fm, /^description:\s*>-?/m, `${label} must not use folded YAML description`);
+  const desc = fm.split('\n').find((line) => line.startsWith('description:'));
+  assert.ok(desc.length <= 500, `${label} description exceeds 500 chars (${desc.length})`);
+  return { fm, body: content.slice(match[0].length) };
+}
+
+test('Claude Code skill is Kiro-safe: no mermaid, latex, HTML breaks, or Grok tool keys', () => {
+  const content = readRepo('.claude/skills/ai-engineering-loop/SKILL.md');
+  parseFrontmatter(content, 'claude skill');
+
+  assert.doesNotMatch(content, /```mermaid/);
+  assert.doesNotMatch(content, /\$\\/);
+  assert.doesNotMatch(content, /<br\s*\/?>/i);
+  assert.doesNotMatch(content, /spawn_subagent/);
+  assert.doesNotMatch(content, /capability_mode/);
+  assert.doesNotMatch(content, /resume_from/);
+  assert.match(content, /\bTask\b/);
+  assert.match(content, /subagent_type/);
+  assert.match(content, /devil-advocate/);
+  assert.match(content, /\bjudge\b/);
+});
+
+test('Claude Code agents exist with Claude tool names and Finding Ledger / verdict contracts', () => {
+  const da = readRepo('.claude/agents/devil-advocate.md');
+  const judge = readRepo('.claude/agents/judge.md');
+  parseFrontmatter(da, 'devil-advocate agent');
+  parseFrontmatter(judge, 'judge agent');
+
+  assert.match(da, /^tools:\s*Read, Grep, Glob, Bash$/m);
+  assert.match(judge, /^tools:\s*Read, Grep, Glob, Bash$/m);
+  assert.doesNotMatch(da, /spawn_subagent|capability_mode|resume_from/);
+  assert.doesNotMatch(judge, /spawn_subagent|capability_mode|resume_from/);
+  assert.match(da, /Finding Ledger/);
+  assert.match(judge, /PASS/);
+  assert.match(judge, /ITERATE/);
+  assert.match(judge, /ESCALATE/);
+});
+
+test('Claude Code slash command does not embed Grok spawn keys', () => {
+  const cmd = readRepo('.claude/commands/ai-engineering-loop.md');
+  parseFrontmatter(cmd, 'claude command');
+  assert.doesNotMatch(cmd, /spawn_subagent|capability_mode|resume_from/);
+  assert.match(cmd, /ai-engineering-loop/);
+});
+
+test('Grok skill may use spawn_subagent; Claude skill must not', () => {
+  const grok = readRepo('.grok/skills/ai-engineering-loop/SKILL.md');
+  const claude = readRepo('.claude/skills/ai-engineering-loop/SKILL.md');
+  assert.match(grok, /spawn_subagent/);
+  assert.doesNotMatch(claude, /spawn_subagent/);
+});