ai-engineering-loop 1.13.0 → 1.14.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.
Files changed (60) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +47 -11
  2. package/.claude/commands/ai-engineering-loop.md +1 -1
  3. package/.claude/skills/ai-engineering-loop/SKILL.md +26 -44
  4. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  5. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  6. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  7. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  8. package/.claude/skills/ai-engineering-loop/references/loop-review.md +18 -0
  9. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  10. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  11. package/.gemini/skills/ai-engineering-loop/SKILL.md +24 -37
  12. package/.gemini/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  13. package/.gemini/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  14. package/.gemini/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  15. package/.gemini/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  16. package/.gemini/skills/ai-engineering-loop/references/loop-review.md +18 -0
  17. package/.gemini/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  18. package/.gemini/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  19. package/.grok/skills/ai-engineering-loop/SKILL.md +29 -61
  20. package/.grok/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  21. package/.grok/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  22. package/.grok/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  23. package/.grok/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  24. package/.grok/skills/ai-engineering-loop/references/loop-review.md +18 -0
  25. package/.grok/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  26. package/.grok/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  27. package/CHANGELOG.md +69 -0
  28. package/README.md +40 -1
  29. package/README.npm.md +6 -2
  30. package/THIRD_PARTY_NOTICES.md +29 -0
  31. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +24 -16
  32. package/adapters/project-onboarding/SKILL.md +27 -0
  33. package/adapters/project-onboarding/references/output.md +29 -0
  34. package/adapters/quality/skills/ael-code-simplifier/SKILL.md +43 -0
  35. package/adapters/quality/skills/ael-receiving-code-review/SKILL.md +37 -0
  36. package/bin/ai-engineering-loop.js +979 -69
  37. package/core/root-cause-analysis.md +6 -0
  38. package/core/runtime-safety.md +30 -3
  39. package/evals/cases/21-tier-t0-docs.json +34 -0
  40. package/evals/cases/22-tier-t1-small-pass.json +30 -0
  41. package/evals/cases/23-tier-t1-blocker.json +26 -0
  42. package/evals/cases/24-tier-t1-auth-escalates.json +30 -0
  43. package/lib/auto-update.js +486 -0
  44. package/lib/budget.js +31 -1
  45. package/lib/cli-args.js +84 -0
  46. package/lib/docs.js +91 -0
  47. package/lib/doctor.js +7 -1
  48. package/lib/gates.js +114 -1
  49. package/lib/host-skill-build.js +121 -0
  50. package/lib/migrations.js +84 -0
  51. package/lib/project-registry.js +148 -0
  52. package/lib/run-state.js +6 -3
  53. package/lib/sync-hosts.js +325 -42
  54. package/lib/tier.js +134 -0
  55. package/lib/update-manager.js +17 -1
  56. package/lib/update-notice.js +192 -0
  57. package/lib/user-state.js +80 -0
  58. package/lib/verification-recorder.js +44 -0
  59. package/migrations/README.md +21 -0
  60. package/package.json +7 -2
@@ -2,23 +2,59 @@
2
2
  name: ai-engineering-loop
3
3
  description: Run the AI Engineering Loop on Antigravity (init, status, refresh, or full Maker then Devil's Advocate then Judge).
4
4
  ---
5
+ <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
5
6
 
6
- Follow `policies/review-budget.md`. Parent is Maker plus orchestrator. Do not use `browser_subagent`.
7
+ # AI Engineering Loop (Antigravity workflow)
7
8
 
8
- Compact map (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.
9
+ Stage details: the `loop-*` references via `npx ai-engineering-loop docs <name>`, read only on entering that stage. Specs and references: `npx ai-engineering-loop docs <name> [--section <h>]`; never read whole spec directories.
9
10
 
10
- Deterministic gates are mandatory. Read `core/runtime-safety.md`. Stage 0 runs sync-hosts, status, then `npx ai-engineering-loop run [--mode report-only|assisted|unattended]`; `state --json` gives runId, immutable mode, and `.ai-engineering-loop/runs/<runId>/` (`RUN_DIR`). Never edit state.json. Run `budget status --run <runId>` before every model/subagent call and `budget record --input <actual> --output <actual> --model <id> --run <runId>` immediately after provider usage is returned. Never invent counts. Missing accounting stops UNATTENDED and requires human direction in ASSISTED. `budget pause` is the kill switch. Keep Workflow Studio alive without exposing chain-of-thought: before each stage or long operation emit `npx ai-engineering-loop activity heartbeat --run <runId> --phase <phase> --message <short factual summary>`. Existing node and gate commands publish their lifecycle automatically. Persist human questions with `interaction question` so they appear once in Studio.
11
+ ## Host rules
11
12
 
12
- Inherited invariants: read `core/grill-policy.md`, `policies/tdd-policy.md`, and `.ai-engineering-loop/glossary.md`. On `adapter_type: dot`, grill includes blast radius: lifecycle sketch and load `task-impact-inquiry`. If the user prompt has no numbered AC, draft the contract, list a short menu and wait. Chat agreement is not freeze. AC is a failure table. One red test per AC row. Do not freeze sunny-path-only. Write claimed-vs-reality.md. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality. Report Spec and Standards separately. Use `context query <term>` and `context related <file>` before opening broad source files. Use `reviewProfile` from runtime policy (default `lean`) for context packs; use iteration-delta review in iteration 2+. DA prompt: "at most 8 tool calls; read the diff file; skip css and generated files". Judge prompt: "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff". Never use `browser_subagent` as reviewer. `generate-workflow` reads workflow.md and lessons.md; missing maker_intern means INVOCATION_UNAVAILABLE. Do not type a model name.
13
+ 1. If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as siblings and wait for each; `general-purpose` only if rejected. Do not use `browser_subagent`.
14
+ 2. No subagent tool: same budgets in this session as `CONTEXT_ISOLATION_ONLY`; never claim independent execution.
15
+ 3. Models: the host catalog; never type a model name.
13
16
 
14
- Stage 1: if the user asks for ideas, list a short menu and wait; do not implement. Grill if the task is ambiguous (`core/grill-policy.md`). Chat agreement is not freeze. Publish the complete failure-table JSON through `npx ai-engineering-loop goal draft --run <runId> --file <repository-local-json> --revision <currentRevision>` so Studio shows the exact draft, then wait. After explicit human freeze, run `goal freeze --run <runId> --revision <reviewedRevision> --hash <reviewedHash> --by human`; `gate goal` remains legacy compatibility only. Do not start Maker before freeze. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Use `.ai-engineering-loop/glossary.md`. Name test seams. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. Stages 2-4 branch on mode: REPORT_ONLY never edits repository files, writes RUN_DIR/report.json, runs `gate report`, and stops. ASSISTED uses normal Maker. UNATTENDED runs `sandbox create --run <runId>`, Maker only in the returned worktreePath, never edits the parent checkout, and runs `sandbox capture --run <runId>`. Read `maker_intern` from workflow.md (missing or none = parent is Maker). Do not type a model name. If intern is set, confirm it came from this host's list (`/models` if that command exists). If the list command is missing or the id is not on it, parent is Maker; say intern INVOCATION_UNAVAILABLE. Intern cannot skip verification, Devil's Advocate, or Judge. Maker: TDD at those seams (`policies/tdd-policy.md`): one red test per AC row. ASSISTED writes RUN_DIR/diff.patch; UNATTENDED capture writes it. After package/manifest edits stabilize, run `npx ai-engineering-loop refresh` once; drift during red-green is expected, so do not refresh after each test cycle. Then run `npx ai-engineering-loop gate maker`. Stage 5 may use `npx ai-engineering-loop verification record --run <runId> -- <executable> [args...]` to capture bounded, redacted output and generate verification.json plus its summary without a shell. Use `--shell -- "command"` only when necessary. Failed commands stay recorded and fail the verification gate. `npx ai-engineering-loop scaffold verification --run <runId>` (or `findings` / `delivery`) creates a deliberately incomplete template; edit it into real evidence, remove `_templateOnly`, and run `npx ai-engineering-loop validate <repository-relative-file>` for diagnostics. Templates never pass a gate. Generate AC rows with `npx ai-engineering-loop context claimed-vs-reality --run <runId>` and fill Claim/Reality from actual changes and command output. Run `npx ai-engineering-loop context compact --run <runId>`, pass compact summaries to reviewers instead of raw logs, then `gate verification`. Bugs: red repro first (`core/root-cause-analysis.md`). Mid-loop stop: `core/handoff-policy.md`.
17
+ ## Commands
15
18
 
16
- If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as siblings. Wait for each child. Do not run them in the background. Use `general-purpose` only if the named type is rejected.
19
+ `init|status|refresh|sync-hosts|generate-adapter|generate-workflow`: run `npx ai-engineering-loop <command>` (`loop-commands`); do not commit unless asked. Otherwise: the loop.
17
20
 
18
- 5. Before Devil's Advocate: write `git diff` to `.ai-engineering-loop/tasks/current.diff` and put `git diff --name-only` in the child prompt. Do not paste Maker rationale. Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` (AC, Claimed, Reality from command log). Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
19
- 6. Run `context fast-path --json`; keep the default lean path when eligible. Build `context diff-hunks --run <runId>` first, add `context devil-advocate` only for hunks that need full file context, check `budget status`, spawn DA with the pack path, wait, `budget record` actual usage, normalize RUN_DIR/findings.json with runId and diffHash, then `gate review`.
20
- 7. Run `escalation --json`, resolve the required tier from the host catalog, build Judge context from only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; Judge must not read the full diff unless those summaries contradict each other. Check `budget status`, spawn Judge, wait, `budget record` actual usage, write verdict.json with modelTier, then `gate judge`.
21
+ ## Loop
21
22
 
22
- If no subagent tool exists, run the same budgets in this session as CONTEXT_ISOLATION_ONLY. Do not claim independent agent execution.
23
+ Compact map (not a second OS) of the 8-stage loop: Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Parent is Maker plus orchestrator; Devil's Advocate (DA) and Judge are fresh **siblings**, never nested or resumed. A gate failure overrides prose. Never edit `state.json`/`current.json`.
23
24
 
24
- Init/status/refresh/sync-hosts/generate-adapter/generate-workflow: `npx ai-engineering-loop <command>`. generate-workflow grills Q1-Q6. Q6 Maker intern: pick from the host catalog; do not type a model name. After Judge PASS, PR/MR body includes `Steps to Reproduce & Testing (QA)` and bugfix placeholders must not stay empty. Preview Stage 8 remote payloads and never include context packs, usage ledgers, raw logs, or credentials. In ASSISTED, wait for explicit human approval and write `humanApproved: true` in RUN_DIR/delivery.json; never infer it. Before `gate delivery`, inspect `npx ai-engineering-loop node status --run <runId>` and explicitly approve any READY approval prerequisite with `npx ai-engineering-loop node approve delivery-approval --yes --by <name> --run <runId>`. A blocked gate should explain the READY prerequisite and next command; never bypass approval. Only `gate delivery` completes the run. Confirmed process lessons go to lessons.md, not a chat dump.
25
+ Tier (from `run --json`; it only rises). Do not skip Goal Contract, verification, Devil's Advocate, or Judge gates; the tier only decides who fills them.
26
+ - **T0** trivial (docs, typo, lint): `gate goal`, Maker, `verify`, claimed-vs-reality, `gate review`, `gate judge` (deterministic); no subagents.
27
+ - **T1** normal: frozen Goal, red test, `verify`, lean DA, `gate review --json`; spawn Judge only on `judgeRequired`.
28
+ - **T2** risky (HIGH_RISK_PATH, DOT business logic, >10 files): add `loop-risky` (blast radius, Judge on STRONG_MODEL). Unseen risk: `run --new --tier T2 --tier-reason <why>`.
29
+
30
+ 0. `run --json [--mode report-only|assisted|unattended]` (runId, tier, budget, hostSkills; `RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user to. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present.
31
+ 1. Goal Contract: `loop-goal`. 2-4. Maker: `loop-maker`, then `gate maker`. 5. Verify: `loop-verify`. 6-7. DA and Judge: `loop-review`. 8. Deliver: `loop-deliver`.
32
+
33
+ Invariants (every tier):
34
+ - AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
35
+ - One red test per AC row (bugs: red repro) before the fix.
36
+ - Write claimed-vs-reality.md after `gate verification` passes. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
37
+ - ITERATE at most to iteration 3, each with a **new** DA.
38
+ - Never infer human approval.
39
+ - After each child `budget record` real usage or `--unavailable`; never invent counts.
40
+ - No secrets or hidden reasoning in activity messages.
41
+
42
+ ## Report header
43
+
44
+ When a child actually returned a result:
45
+
46
+ ```
47
+ Execution Mode: TRUE_INDEPENDENT_AGENT
48
+ Independent LLM Execution: PROVEN
49
+ Native Subagent Invocation: AVAILABLE
50
+ Review Method: True Independent Agent
51
+ ```
52
+
53
+ When no subagent ran:
54
+
55
+ ```
56
+ Execution Mode: CONTEXT_ISOLATION_ONLY
57
+ Independent LLM Execution: NOT PROVEN
58
+ Native Subagent Invocation: UNAVAILABLE
59
+ Review Method: Clean-Slate Artifact Isolation Barrier
60
+ ```
@@ -6,6 +6,6 @@ allowed-tools: "Read, Grep, Glob, Edit, Write, Task, Bash(npm run *), Bash(npm t
6
6
 
7
7
  Follow `.claude/skills/ai-engineering-loop/SKILL.md`.
8
8
 
9
- 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.
9
+ 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. Reviewer budgets live in the agent files; do not let either roam the repo.
10
10
 
11
11
  Arguments: init, status, refresh, sync-hosts, generate-adapter, generate-workflow, or a task description.
@@ -3,66 +3,48 @@ name: ai-engineering-loop
3
3
  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.
4
4
  allowed-tools: "Read, Grep, Glob, Edit, Write, Task, Bash(npm run *), Bash(npm test *), Bash(npx *), Bash(git *)"
5
5
  ---
6
+ <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
6
7
 
7
8
  # AI Engineering Loop (Claude Code)
8
9
 
9
- Canonical specs: `core/`, `agents/`, `policies/`. Read those files. Do not invent extra tool parameters.
10
+ Stage details: `references/loop-*.md` beside this file, read only on entering that stage. Specs and references: `npx ai-engineering-loop docs <name> [--section <h>]`; never read whole spec directories.
10
11
 
11
- ## Host rule (prevents 400 REQUEST_BODY_INVALID)
12
+ ## Host rules
12
13
 
13
- Claude Code talks to strict proxies (including Kiro). Follow this exactly:
14
-
15
- 1. Use only tools that exist in this session.
16
- 2. For subagents, call the host tool named **Task** (or **Agent** if that is the only subagent tool). Pass **only** these keys:
17
- - `subagent_type`
18
- - `description`
19
- - `prompt`
20
- - `run_in_background: false` only if that key exists on the Task schema. Never invent other keys.
21
- 3. Do **not** add any other keys. Extra keys make Kiro return HTTP 400 `REQUEST_BODY_INVALID`.
22
- 4. If no Task/Agent tool exists, review in this session and label it `CONTEXT_ISOLATION_ONLY`. Do not invent a tool name.
23
- 5. If Bash or Write returns "cannot determine the safety" or HTTP 400 REQUEST_BODY_INVALID: stop that tool. Do not retry it. Continue with Read, Grep, and Glob. Tell the user to switch off auto permission mode (use default) or add a permissions.allow rule for the verification command, then start a new session.
14
+ Strict proxies (including Kiro) return HTTP 400 `REQUEST_BODY_INVALID` on unknown keys:
15
+ 1. Use only tools that exist in this session. Spawn subagents with **Task** (or **Agent** if that is the only one), passing only `subagent_type`, `description`, `prompt`, and `run_in_background: false` only if the schema has it. Never invent other keys.
16
+ 2. `subagent_type: devil-advocate` / `judge`; `general-purpose` only if rejected. No Task/Agent tool: review in this session as `CONTEXT_ISOLATION_ONLY`.
17
+ 3. Bash or Write says "cannot determine the safety" or 400: stop that tool, do not retry, use Read/Grep/Glob, and tell the user to leave auto permission mode or add a permissions.allow rule, then start a new session.
18
+ 4. Models: `/models` when it exists; never type a model name.
24
19
 
25
20
  ## Commands
26
21
 
27
- - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter` / `generate-workflow`: run `npx ai-engineering-loop <command>` in the repo. Do not commit unless asked.
28
- - `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
29
- - `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q6. Q6 Maker intern: if `/models` exists in this session, use it and show numbered options; else only `none`. Do not type a model name. Then write `.ai-engineering-loop/workflow.md` and empty `lessons.md` if missing. Do not start Maker.
30
- - Any other argument: full loop for that task.
22
+ `init|status|refresh|sync-hosts|generate-adapter|generate-workflow`: run `npx ai-engineering-loop <command>` (`loop-commands`); do not commit unless asked. Otherwise: the loop.
31
23
 
32
24
  ## Loop
33
25
 
34
- Compact map (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.
35
-
36
- Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as **siblings**, not nested.
37
-
38
- ## Deterministic artifact gates (mandatory)
39
-
40
- Keep Workflow Studio alive without exposing chain-of-thought: before each stage or long operation emit `npx ai-engineering-loop activity heartbeat --run <runId> --phase <phase> --message <short factual summary>`. Existing `node start|activity|complete` and `gate` commands publish node lifecycle automatically. Before asking the human, persist the question with `npx ai-engineering-loop interaction question --run <runId> --id <id> --message <text>` so it appears once in Studio. Never put secrets, hidden reasoning, or raw model context in activity messages.
41
-
42
- Run `npx ai-engineering-loop state --json` to get the current `runId` and use `.ai-engineering-loop/runs/<runId>/` as `RUN_DIR`. Never edit `state.json` or `current.json`.
26
+ Compact map (not a second OS) of the 8-stage loop: Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Parent is Maker plus orchestrator; Devil's Advocate (DA) and Judge are fresh **siblings**, never nested or resumed. A gate failure overrides prose. Never edit `state.json`/`current.json`.
43
27
 
44
- Read `core/runtime-safety.md`. The ledger mode is immutable. Before every model or Task call, run `npx ai-engineering-loop budget status --run <runId>`; after it returns, record actual provider-reported usage with `budget record --input <n> --output <n> --model <id> --run <runId>`. Never invent actual token counts. If usage metadata is unavailable, UNATTENDED stops and escalates; ASSISTED discloses the gap and asks the human whether to continue. `budget pause` is an emergency kill switch.
28
+ Tier (from `run --json`; it only rises). Do not skip Goal Contract, verification, Devil's Advocate, or Judge gates; the tier only decides who fills them.
29
+ - **T0** trivial (docs, typo, lint): `gate goal`, Maker, `verify`, claimed-vs-reality, `gate review`, `gate judge` (deterministic); no subagents.
30
+ - **T1** normal: frozen Goal, red test, `verify`, lean DA, `gate review --json`; spawn Judge only on `judgeRequired`.
31
+ - **T2** risky (HIGH_RISK_PATH, DOT business logic, >10 files): add `loop-risky` (blast radius, Judge on STRONG_MODEL). Unseen risk: `run --new --tier T2 --tier-reason <why>`.
45
32
 
46
- Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/tdd-policy.md`, and `.ai-engineering-loop/glossary.md`. On `adapter_type: dot`, grill includes blast radius: lifecycle sketch and load `task-impact-inquiry`. If the user prompt has no numbered AC, draft the contract, list a short menu and wait. Chat agreement is not freeze. AC is a failure table. One red test per AC row. Do not freeze sunny-path-only. Write claimed-vs-reality.md. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality. Report Spec and Standards separately. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files. Use the runtime policy `reviewProfile` (default `lean`) for context packs; do not upgrade to `standard` or `thorough` unless the human asks or the budget gate requires escalation. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files". Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
33
+ 0. `run --json [--mode report-only|assisted|unattended]` (runId, tier, budget, hostSkills; `RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user to. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present.
34
+ 1. Goal Contract: `loop-goal`. 2-4. Maker: `loop-maker`, then `gate maker`. 5. Verify: `loop-verify`. 6-7. DA and Judge: `loop-review`. 8. Deliver: `loop-deliver`.
47
35
 
48
- 1. Stage 0: `npx ai-engineering-loop sync-hosts`, `status`, then `run [--mode report-only|assisted|unattended]` to create or resume the ledger. Run `state --json` and `budget status`. Read `.ai-engineering-loop/glossary.md`. Read `.ai-engineering-loop/lessons.md` and `.ai-engineering-loop/workflow.md` if they exist. Follow workflow.md hooks (`before_grill`, `after_freeze`, `after_pass`). Do not skip required gates even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop. If sync-hosts copied files, tell the user a new session is needed; keep going with this session.
49
- 2. Stage 1: Goal Contract (`core/goal-contract.md`). If the user asks for ideas, list a short menu and wait; do not implement. If the task is ambiguous and the user can answer, grill first (`core/grill-policy.md`): design tree, recommended answers, do not ask look-up facts. On business-logic change, and always on `adapter_type: dot`, include blast radius. Chat agreement is not freeze. Emit `npx ai-engineering-loop activity goal-drafting --run <runId> --message <summary>` before drafting. Write the contract JSON to a repository-local temporary file, then publish it with `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` so Workflow Studio sees the exact draft and its ready state. Wait. After the user explicitly freezes, use `npx ai-engineering-loop goal freeze --run <runId> --revision <reviewedRevision> --hash <reviewedHash> --by human`; do not edit production code unless it passes. `gate goal` remains the legacy compatibility command, not the preferred revision-bound path.
50
- 3. After Goal freeze, branch on mode. REPORT_ONLY: do not edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then run `gate report` and stop. ASSISTED: run the normal Maker and later require human approval. UNATTENDED: run `sandbox create --run <runId>`, set Maker's working directory to the returned worktreePath, never edit the parent checkout, then run `sandbox capture --run <runId>`. For Maker, read `maker_intern` from workflow.md (missing or none = parent is Maker). Do not type a model name. Confirm it through `/models` when available; otherwise parent is Maker and report INVOCATION_UNAVAILABLE. Intern cannot skip later gates. Bugs: red repro first. Features: one red test per AC row. In ASSISTED write the exact review diff to `RUN_DIR/diff.patch`; UNATTENDED capture writes it. After all package/manifest edits are stable, run `npx ai-engineering-loop refresh` once; manifest drift during red-green is expected, so do not refresh after each test cycle. Then run `npx ai-engineering-loop gate maker`.
51
- 4. Stage 5: run each command from `.ai-engineering-loop/verification.md` through `npx ai-engineering-loop verification record --run <runId> -- <executable> [args...]`. It captures bounded, redacted output, binds evidence to the gated diff, writes `RUN_DIR/verification.json`, and refreshes `verification-summary.json`; commands run without a shell by default. Use `--shell -- "command"` only when shell syntax is required. Run `npx ai-engineering-loop context compact --run <runId>` and pass run-summary.md and verification-summary.json to reviewers instead of raw logs whenever possible. A failed command is still recorded and returns a non-zero CLI exit; it cannot pass `gate verification`. Vague "seems green" is invalid. Run `npx ai-engineering-loop context claimed-vs-reality --run <runId>` to scaffold AC rows from the frozen Goal; fill Claimed and Reality from actual changes and command output. For hand-authored artifacts, `npx ai-engineering-loop scaffold verification --run <runId>` (or `findings` / `delivery`) writes a deliberately incomplete `.template.json`; edit it into the real artifact, remove `_templateOnly`, then use `npx ai-engineering-loop validate <repository-relative-file>` for diagnostics. Templates are never evidence. Run `npx ai-engineering-loop gate verification`; do not spawn Devil's Advocate unless it passes.
52
- 5. Write artifacts, then spawn. Before Devil's Advocate:
53
- - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
54
- - Write changed paths (`git diff --name-only`) into the Task prompt as a short list.
55
- - Put those paths in the child prompt. Do not paste Maker rationale.
56
- - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
57
- - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
58
- 6. Stage 6: Run `npx ai-engineering-loop context fast-path --json`; keep the default lean path when eligible. Build `npx ai-engineering-loop context diff-hunks --run <runId>` plus `npx ai-engineering-loop context devil-advocate <files...>` only for files whose hunks are insufficient. In iteration 2+, prefer the diff-hunk pack's unresolved findings and new hunks instead of replaying the whole diff. Recheck `budget status`, then Task `subagent_type: devil-advocate`. Use `general-purpose` only if rejected. Wait and immediately `budget record` its actual usage. Normalize its ledger into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
59
- 7. Stage 7: Run `npx ai-engineering-loop escalation --json` before selecting Judge. Resolve the required tier through `/models`; if unavailable, escalate to the user. Build Judge context from only run-summary.md, verification-summary.json (or verification.json if the summary is missing), open-findings.json/findings.json, and the Goal hash; Judge must not read the full diff unless those summaries contradict each other. Recheck `budget status`, spawn Judge as a sibling and wait, then immediately `budget record` actual usage. Normalize its output into `RUN_DIR/verdict.json`, include `modelTier`, then run `npx ai-engineering-loop gate judge`. A gate failure overrides optimistic prose.
60
- 8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate (do not resume the previous child).
61
- 9. After Judge PASS: run the `after_pass` hook, then Stage 8 from `.ai-engineering-loop/adapter.md`. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads; do not expose context packs, usage ledgers, raw logs, or credentials. In ASSISTED, wait for explicit human approval and write `humanApproved: true`; never infer approval. For recipe-bound Runs, inspect `npx ai-engineering-loop node status --run <runId>` and explicitly approve any READY `approval` node (for example `node approve delivery-approval --yes --by <name> --run <runId>`). Then write `RUN_DIR/delivery.json` with destination and summary, validate it if useful, and run `npx ai-engineering-loop gate delivery`. If the gate says the node is not READY, follow its prerequisite status and command hint; do not bypass approval. Only this gate completes the run.
36
+ Invariants (every tier):
37
+ - AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
38
+ - One red test per AC row (bugs: red repro) before the fix.
39
+ - Write claimed-vs-reality.md after `gate verification` passes. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
40
+ - ITERATE at most to iteration 3, each with a **new** DA.
41
+ - Never infer human approval.
42
+ - After each child `budget record` real usage or `--unavailable`; never invent counts.
43
+ - No secrets or hidden reasoning in activity messages.
62
44
 
63
45
  ## Report header
64
46
 
65
- When Task/Agent actually returned a child result:
47
+ When Task/Agent returned a child result:
66
48
 
67
49
  ```
68
50
  Execution Mode: TRUE_INDEPENDENT_AGENT
@@ -71,7 +53,7 @@ Native Subagent Invocation: AVAILABLE
71
53
  Review Method: True Independent Agent
72
54
  ```
73
55
 
74
- When no subagent tool exists:
56
+ When no subagent ran:
75
57
 
76
58
  ```
77
59
  Execution Mode: CONTEXT_ISOLATION_ONLY
@@ -0,0 +1,20 @@
1
+ # Loop commands and Studio
2
+
3
+ - `init` / `status` / `refresh` / `sync-hosts`: run `npx ai-engineering-loop <command>` in the repo. `sync-hosts` installs the core pack into hosts that already exist; `--pack backend|design` opts in, and user-edited files are backed up first. Do not commit unless asked.
4
+ - `onboard`: load skill `project-onboarding` to fill `.ai-engineering-loop/architecture.md` and `conventions.md` from the code with evidence. Never automatic.
5
+ - `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5, then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
6
+ - `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q6. Q6 Maker intern: list numbered options from the host model catalog (see Host rules) plus `none`; if there is no catalog, offer only `none`. Do not type a model name. Write `.ai-engineering-loop/workflow.md` and an empty `lessons.md` if missing. Do not start Maker. Missing `maker_intern` means INVOCATION_UNAVAILABLE.
7
+
8
+ - Never run `update apply|auto|rollback|policy` unless the user asks; the CLI applies updates itself under the user's policy (`docs runtime-safety`).
9
+
10
+ ## Studio
11
+
12
+ Stage commands (`run`, `goal`, `gate`, `verify`, `review-pack`, `deliver`, `node start|activity|complete`) publish Studio lifecycle and heartbeats automatically. Emit `npx ai-engineering-loop activity heartbeat --run <runId> --phase <phase> --message <short factual summary>` only during long manual work, never before every stage. Before asking the human, persist the question with `npx ai-engineering-loop interaction question --run <runId> --id <id> --message <text>` so it appears once in Studio.
13
+
14
+ ## Budget
15
+
16
+ `run --json` already reports the budget; run `budget status --run <runId>` only before each new iteration. After each child, `budget record --input <n> --output <n> --model <id> --run <runId>` from provider usage. No usage shown: `budget record --unavailable --run <runId>` once; ASSISTED continues and discloses it at delivery (do not ask the human); UNATTENDED fails that command, so stop and escalate. `budget pause` is the kill switch. The ledger mode is immutable. UNATTENDED or budget errors: `docs runtime-safety`.
17
+
18
+ ## Resuming
19
+
20
+ `state --json` gives the current runId only when resuming a run. If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`docs handoff-policy`).
@@ -0,0 +1,8 @@
1
+ # Stage 8: Delivery
2
+
3
+ - After Judge PASS, run the `after_pass` hook, then the Stage 8 adapter from `.ai-engineering-loop/adapter.md`.
4
+ - The PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Disclose any `budget record --unavailable`.
5
+ - Preview remote payloads; never include context packs, usage ledgers, raw logs, or credentials.
6
+ - ASSISTED: wait for explicit human approval and never infer it. Then one call: `npx ai-engineering-loop deliver --run <runId> --destination <where> --summary <text> --approve --by <name>` (approves READY approval nodes, writes `RUN_DIR/delivery.json` with `humanApproved: true`, runs `gate delivery`). Without `--approve` it refuses in ASSISTED.
7
+ - Long form: `node status --run <runId>`, `node approve delivery-approval --yes --by <name> --run <runId>` for each READY approval node, write `RUN_DIR/delivery.json`, then `gate delivery`. If the gate says a node is not READY, follow its prerequisite hint; never bypass approval.
8
+ - Only the delivery gate completes the run.
@@ -0,0 +1,10 @@
1
+ # Stage 1: Goal Contract
2
+
3
+ - If the user asks for ideas, list a short menu and wait; do not implement.
4
+ - Ambiguous task the user can answer: grill first (`docs grill-policy`): design tree, recommended answers, never ask look-up facts. T2 adds `loop-risky`.
5
+ - If the user prompt has no numbered AC, draft the contract (`docs goal-contract` if needed), list it, and wait. Chat agreement is not freeze.
6
+ - AC is a failure table: each row has a statement, required evidence, and failure cases. Do not freeze sunny-path-only. T0 may use 1-3 rows that still list failure cases.
7
+ - Emit `npx ai-engineering-loop activity goal-drafting --run <runId> --message <summary>`, write the contract JSON to a repository-local temporary file, then `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` so Studio shows the exact draft.
8
+ - Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --latest --run <runId> --by human` (or `--revision <r> --hash <h>`). T0 may write `RUN_DIR/goal-contract.json` and run `gate goal` directly.
9
+ - Do not edit production code until the Goal gate passes.
10
+ - After the freeze, work from the frozen contract (`goal show --run <runId>`), not the drafting chat; compact the conversation there if the host supports it.
@@ -0,0 +1,8 @@
1
+ # Stages 2-4: Maker
2
+
3
+ - T1/T2: read `docs tdd-policy` before Maker. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files.
4
+ - Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
5
+ - Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
6
+ - Bugs: red repro first. Features: one red test per AC row, then green.
7
+ - After package and manifest edits are stable, run `npx ai-engineering-loop refresh` once (drift during red-green is expected; do not refresh per test cycle).
8
+ - ASSISTED: `npx ai-engineering-loop gate maker --from-git` writes the exact working-tree diff (tracked and new files, excluding `.ai-engineering-loop/`) to `RUN_DIR/diff.patch` and gates it; or write that file yourself and run `gate maker`. UNATTENDED: `sandbox capture` writes it, then `gate maker`. The gate can raise the tier from the diff.
@@ -0,0 +1,18 @@
1
+ # Stages 6-7: Devil's Advocate and Judge
2
+
3
+ ## Devil's Advocate (T1, T2)
4
+
5
+ - `npx ai-engineering-loop review-pack --run <runId> --json` returns the DA pack path, fast-path, escalation floor, and tier. Keep the lean path when eligible; add `context devil-advocate <files...>` only for files whose hunks are insufficient. The DA reads that pack or `RUN_DIR/diff.patch` (do not also write `tasks/current.diff`).
6
+ - Use the runtime policy `reviewProfile` (default `lean`); upgrade to `standard` or `thorough` only when the human asks or the budget gate requires it.
7
+ - Spawn a new DA as a sibling (Host rules) with the pack path, the changed paths as a short list, and claimed-vs-reality.md. Do not paste Maker rationale. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files".
8
+ - Iteration 2+: give unresolved findings and new hunks, not the whole diff again.
9
+ - Wait, `budget record` its usage (or `--unavailable`), normalize its ledger into `RUN_DIR/findings.json` with runId and diffHash, then `npx ai-engineering-loop gate review --json`. Report Spec and Standards separately.
10
+
11
+ ## Judge
12
+
13
+ - T0, or T1 when `gate review --json` reports `judgeRequired: false`: run `gate judge`; the CLI writes the deterministic verdict.
14
+ - Otherwise run `npx ai-engineering-loop escalation --json` and resolve the required tier through the host model catalog; if unavailable, escalate to the user. T2 needs STRONG_MODEL.
15
+ - Judge context: only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; it reads the full diff only if those contradict each other. Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
16
+ - Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier`, then `gate judge`. A gate failure overrides optimistic prose.
17
+ - Acting on findings (ITERATE or human MR comments): verify each one before changing code; fix valid ones test-first, decline invalid ones with evidence (skill `ael-receiving-code-review` if installed).
18
+ - ITERATE while iteration < 3: fix in the parent, re-verify, spawn a **new** DA (never resume the previous child). At the iteration ceiling (3) ESCALATE to the human instead.
@@ -0,0 +1,9 @@
1
+ # T2 risky tier
2
+
3
+ Applies to HIGH_RISK_PATH changes (auth, payments, migrations, secrets, infra), DOT business logic, more than 10 files, or a manual `--tier T2`.
4
+
5
+ - Grill before the Goal (`docs grill-policy`): design tree, recommended answers, no look-up questions.
6
+ - Business-logic changes need a blast radius: lifecycle sketch of what reads and writes the changed state; on `adapter_type: dot` load `task-impact-inquiry`. Skip it for docs, config, or UI-copy changes.
7
+ - Full DA (not the T1 lean shortcut) and Judge on STRONG_MODEL resolved through the host model catalog; if unavailable, escalate to the user. Never run the deterministic Judge for T2.
8
+ - UNATTENDED: sandbox worktree only, and `budget pause` is the kill switch (`docs runtime-safety`).
9
+ - The tier never falls back once raised.
@@ -0,0 +1,20 @@
1
+ # Stage 5: Verification
2
+
3
+ - One call: `npx ai-engineering-loop verify --run <runId> [--cmd "<command>"]...` (defaults to `test_unit` from `.ai-engineering-loop/verification.md`). It records each command in parallel (`--serial` for dependent commands), binds bounded, redacted evidence to the gated diff, and only when all pass runs `gate verification`, `context compact`, and scaffolds claimed-vs-reality. Shell syntax needs `--shell`.
4
+ - Long form (same gate): `verification record --run <runId> -- <executable> [args...]` per command, `gate verification`, `context compact --run <runId>`, `context claimed-vs-reality --run <runId>`.
5
+ - A failed command is recorded honestly and returns non-zero; it cannot pass the gate. Vague "seems green" is invalid.
6
+ - Fill `.ai-engineering-loop/tasks/claimed-vs-reality.md`: Claimed from the actual change, Reality from command output. Do not spawn DA while the file is missing or any Claimed row lacks Reality.
7
+ - Hand-authored artifacts: `scaffold verification|findings|delivery --run <runId>` writes an incomplete `.template.json`; edit it into the real artifact, remove `_templateOnly`, and `validate <repository-relative-file>`. Templates are never evidence.
8
+ - Pass run-summary.md and verification-summary.json to reviewers instead of raw logs.
9
+
10
+ ## No claim without fresh evidence
11
+
12
+ Before saying "done", "fixed", "passing", or "ready", run the proving command in this iteration and cite its output; earlier runs and "should work" are not evidence.
13
+
14
+ | Claim | Required evidence |
15
+ |---|---|
16
+ | Tests pass | the test command's output this iteration, exit 0 |
17
+ | Bug fixed | the red repro now passes, with the command shown |
18
+ | AC met | its claimed-vs-reality row cites that output |
19
+
20
+ After `verify`, continue from run-summary.md and verification-summary.json, not earlier logs or chat.
@@ -2,56 +2,43 @@
2
2
  name: ai-engineering-loop
3
3
  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 Antigravity.
4
4
  ---
5
+ <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
5
6
 
6
7
  # AI Engineering Loop (Antigravity)
7
8
 
8
- Canonical specs: if this workspace has `core/`, `agents/`, `policies/`, read those files. Otherwise run `npx ai-engineering-loop` and follow the published specs.
9
+ Stage details: `references/loop-*.md` beside this file, read only on entering that stage. Specs and references: `npx ai-engineering-loop docs <name> [--section <h>]`; never read whole spec directories.
9
10
 
10
- Follow `policies/review-budget.md` when that file exists. Parent is Maker plus orchestrator. Do not use `browser_subagent`.
11
+ ## Host rules
11
12
 
12
- ## Host rule
13
-
14
- If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as siblings. Wait for each child. Do not run them in the background. Use `general-purpose` only if the named type is rejected.
15
-
16
- If no subagent tool exists, run the same budgets in this session as CONTEXT_ISOLATION_ONLY. Do not claim independent agent execution.
17
-
18
- Canonical mode ids: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_PROCESS_AGENT`, `CONTEXT_ISOLATION_ONLY`, `UNAVAILABLE`.
13
+ 1. If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as siblings, wait for each, never in the background; `general-purpose` only if the named type is rejected. Do not use `browser_subagent`.
14
+ 2. No subagent tool: run the same budgets in this session as `CONTEXT_ISOLATION_ONLY`; do not claim independent agent execution.
15
+ 3. Models: the host catalog (`/models` when it exists); never type a model name.
16
+ 4. Modes: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_PROCESS_AGENT`, `CONTEXT_ISOLATION_ONLY`, `UNAVAILABLE`.
19
17
 
20
18
  ## Commands
21
19
 
22
- - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter` / `generate-workflow`: run `npx ai-engineering-loop <command>` in the repo. Do not commit unless asked.
23
- - `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
24
- - `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q6. Q6 Maker intern: if `/models` exists in this session, use it and show numbered options; else only `none`. Do not type a model name. Then write `.ai-engineering-loop/workflow.md` and empty `lessons.md` if missing. Do not start Maker.
25
- - Any other argument: full loop for that task.
20
+ `init|status|refresh|sync-hosts|generate-adapter|generate-workflow`: run `npx ai-engineering-loop <command>` (`loop-commands`); do not commit unless asked. Otherwise: the loop.
26
21
 
27
22
  ## Loop
28
23
 
29
- Compact map (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.
30
-
31
- ## Deterministic artifact gates (mandatory)
32
-
33
- Keep Workflow Studio alive without exposing chain-of-thought: before each stage or long operation emit `npx ai-engineering-loop activity heartbeat --run <runId> --phase <phase> --message <short factual summary>`. Existing `node start|activity|complete` and `gate` commands publish node lifecycle automatically. Before asking the human, persist the question with `npx ai-engineering-loop interaction question --run <runId> --id <id> --message <text>` so it appears once in Studio. Never put secrets, hidden reasoning, or raw model context in activity messages.
34
-
35
- Run `npx ai-engineering-loop state --json` to get the current runId and use `.ai-engineering-loop/runs/<runId>/` as `RUN_DIR`. Never edit state.json or current.json.
24
+ Compact map (not a second OS) of the 8-stage loop: Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Parent is Maker plus orchestrator; Devil's Advocate (DA) and Judge are fresh **siblings**, never nested or resumed. A gate failure overrides prose. Never edit `state.json`/`current.json`.
36
25
 
37
- Read `core/runtime-safety.md`. Before every model or subagent call, run `budget status --run <runId>` and afterward run `budget record --input <actual> --output <actual> --model <id> --run <runId>` using provider-reported usage. Never invent usage. Missing usage stops UNATTENDED and requires human direction in ASSISTED. `budget pause` is the kill switch.
26
+ Tier (from `run --json`; it only rises). Do not skip Goal Contract, verification, Devil's Advocate, or Judge gates; the tier only decides who fills them.
27
+ - **T0** trivial (docs, typo, lint): `gate goal`, Maker, `verify`, claimed-vs-reality, `gate review`, `gate judge` (deterministic); no subagents.
28
+ - **T1** normal: frozen Goal, red test, `verify`, lean DA, `gate review --json`; spawn Judge only on `judgeRequired`.
29
+ - **T2** risky (HIGH_RISK_PATH, DOT business logic, >10 files): add `loop-risky` (blast radius, Judge on STRONG_MODEL). Unseen risk: `run --new --tier T2 --tier-reason <why>`.
38
30
 
39
- Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/tdd-policy.md`, and `.ai-engineering-loop/glossary.md`. On `adapter_type: dot`, grill includes blast radius: lifecycle sketch and load `task-impact-inquiry`. If the user prompt has no numbered AC, draft the contract, list a short menu and wait. Chat agreement is not freeze. AC is a failure table. One red test per AC row. Do not freeze sunny-path-only. Write claimed-vs-reality.md. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality. Report Spec and Standards separately. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files. Use the runtime policy `reviewProfile` (default `lean`) for context packs; do not upgrade to `standard` or `thorough` unless the human asks or the budget gate requires escalation. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files". Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff". `generate-workflow` still reads workflow.md and lessons.md; missing maker_intern means INVOCATION_UNAVAILABLE. Do not type a model name.
31
+ 0. `run --json [--mode report-only|assisted|unattended]` (runId, tier, budget, hostSkills; `RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user to. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present.
32
+ 1. Goal Contract: `loop-goal`. 2-4. Maker: `loop-maker`, then `gate maker`. 5. Verify: `loop-verify`. 6-7. DA and Judge: `loop-review`. 8. Deliver: `loop-deliver`.
40
33
 
41
- 1. Stage 0: sync hosts, check status, then run `npx ai-engineering-loop run [--mode report-only|assisted|unattended]` to create or resume the ledger. Run `state --json` and `budget status`. Read glossary, lessons, and workflow overlays. Required gates cannot be skipped.
42
- 2. Stage 1: grill ambiguous decisions and business blast radius first. Emit `npx ai-engineering-loop activity goal-drafting --run <runId> --message <summary>`. Write the Goal Contract JSON to a repository-local temporary file, then publish it with `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` so Workflow Studio sees it and its ready state. Wait. Chat agreement is not freeze. After explicit human freeze, use `npx ai-engineering-loop goal freeze --run <runId> --revision <reviewedRevision> --hash <reviewedHash> --by human`; do not edit production code unless it passes. `gate goal` remains the legacy compatibility command, not the preferred revision-bound path.
43
- 3. After Goal freeze, branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json`, run `gate report`, and stop. ASSISTED: use the normal Maker. UNATTENDED: run `sandbox create --run <runId>`, run Maker only in the returned worktreePath, never edit the parent checkout, then run `sandbox capture --run <runId>`. Resolve maker_intern only through the host catalog; otherwise parent is Maker. Intern cannot skip gates. Use red repro or TDD. ASSISTED writes `RUN_DIR/diff.patch`; UNATTENDED capture writes it. After package/manifest edits are stable, run `npx ai-engineering-loop refresh` once; drift during red-green is expected, so avoid refreshing after each test cycle. Then run `npx ai-engineering-loop gate maker`.
44
- 4. Stage 5: record each verification command with `npx ai-engineering-loop verification record --run <runId> -- <executable> [args...]`. It runs without a shell by default, captures bounded/redacted output, binds evidence to the gated diff, writes `RUN_DIR/verification.json`, and updates the summary. Use `--shell -- "command"` only when shell syntax is required. Failed commands are recorded and return non-zero; they cannot pass the gate. Run `npx ai-engineering-loop context compact --run <runId>` and pass run-summary.md and verification-summary.json to reviewers instead of raw logs whenever possible. Use `npx ai-engineering-loop context claimed-vs-reality --run <runId>` to scaffold AC rows from the frozen Goal, then fill both columns from real changes and command output. For hand-authored artifacts, `npx ai-engineering-loop scaffold verification --run <runId>` (or `findings` / `delivery`) creates an incomplete `.template.json`; edit it into the real artifact, remove `_templateOnly`, then use `npx ai-engineering-loop validate <repository-relative-file>` for diagnostics. Templates are never evidence. Run `npx ai-engineering-loop gate verification`; do not spawn DA unless it passes.
45
- 5. Write artifacts, then spawn. Before Devil's Advocate:
46
- - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
47
- - Write changed paths (`git diff --name-only`) into the child prompt as a short list.
48
- - Put those paths in the child prompt. Do not paste Maker rationale.
49
- - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
50
- - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
51
- 6. Stage 6: Run `npx ai-engineering-loop context fast-path --json`; keep the default lean path when eligible. Build `npx ai-engineering-loop context diff-hunks --run <runId>`, then `context devil-advocate <files...>` only when hunks are insufficient. Use unresolved findings and new hunks instead of replaying accepted old findings. Check `budget status`, spawn DA with the pack path, wait, and `budget record` actual usage. Normalize its output into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
52
- 7. Stage 7: Run `npx ai-engineering-loop escalation --json`, resolve the required tier through the host catalog, or escalate to the user. Build Judge context from only run-summary.md, verification-summary.json (or verification.json if the summary is missing), open-findings.json/findings.json, and the Goal hash; Judge must not read the full diff unless those summaries contradict each other. Check `budget status`, spawn Judge, wait, and `budget record` actual usage. Write `RUN_DIR/verdict.json` with modelTier, then run `npx ai-engineering-loop gate judge`.
53
- 8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate.
54
- 9. After Judge PASS: run after_pass, then the configured Stage 8 adapter. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads and never include context packs, usage ledgers, raw logs, or credentials. In ASSISTED, wait for explicit human approval and put `humanApproved: true` in `RUN_DIR/delivery.json`; never infer it. For recipe-bound Runs, check `node status --run <runId>` and explicitly approve every READY approval prerequisite (for example `node approve delivery-approval --yes --by <name> --run <runId>`). Then run `npx ai-engineering-loop gate delivery`; follow actionable prerequisite hints if the gate says the delivery node is not READY.
34
+ Invariants (every tier):
35
+ - AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
36
+ - One red test per AC row (bugs: red repro) before the fix.
37
+ - Write claimed-vs-reality.md after `gate verification` passes. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
38
+ - ITERATE at most to iteration 3, each with a **new** DA.
39
+ - Never infer human approval.
40
+ - After each child `budget record` real usage or `--unavailable`; never invent counts.
41
+ - No secrets or hidden reasoning in activity messages.
55
42
 
56
43
  ## Report header
57
44
 
@@ -64,7 +51,7 @@ Native Subagent Invocation: AVAILABLE
64
51
  Review Method: True Independent Agent
65
52
  ```
66
53
 
67
- When no subagent tool exists:
54
+ When no subagent ran:
68
55
 
69
56
  ```
70
57
  Execution Mode: CONTEXT_ISOLATION_ONLY
@@ -0,0 +1,20 @@
1
+ # Loop commands and Studio
2
+
3
+ - `init` / `status` / `refresh` / `sync-hosts`: run `npx ai-engineering-loop <command>` in the repo. `sync-hosts` installs the core pack into hosts that already exist; `--pack backend|design` opts in, and user-edited files are backed up first. Do not commit unless asked.
4
+ - `onboard`: load skill `project-onboarding` to fill `.ai-engineering-loop/architecture.md` and `conventions.md` from the code with evidence. Never automatic.
5
+ - `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5, then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
6
+ - `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q6. Q6 Maker intern: list numbered options from the host model catalog (see Host rules) plus `none`; if there is no catalog, offer only `none`. Do not type a model name. Write `.ai-engineering-loop/workflow.md` and an empty `lessons.md` if missing. Do not start Maker. Missing `maker_intern` means INVOCATION_UNAVAILABLE.
7
+
8
+ - Never run `update apply|auto|rollback|policy` unless the user asks; the CLI applies updates itself under the user's policy (`docs runtime-safety`).
9
+
10
+ ## Studio
11
+
12
+ Stage commands (`run`, `goal`, `gate`, `verify`, `review-pack`, `deliver`, `node start|activity|complete`) publish Studio lifecycle and heartbeats automatically. Emit `npx ai-engineering-loop activity heartbeat --run <runId> --phase <phase> --message <short factual summary>` only during long manual work, never before every stage. Before asking the human, persist the question with `npx ai-engineering-loop interaction question --run <runId> --id <id> --message <text>` so it appears once in Studio.
13
+
14
+ ## Budget
15
+
16
+ `run --json` already reports the budget; run `budget status --run <runId>` only before each new iteration. After each child, `budget record --input <n> --output <n> --model <id> --run <runId>` from provider usage. No usage shown: `budget record --unavailable --run <runId>` once; ASSISTED continues and discloses it at delivery (do not ask the human); UNATTENDED fails that command, so stop and escalate. `budget pause` is the kill switch. The ledger mode is immutable. UNATTENDED or budget errors: `docs runtime-safety`.
17
+
18
+ ## Resuming
19
+
20
+ `state --json` gives the current runId only when resuming a run. If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`docs handoff-policy`).
@@ -0,0 +1,8 @@
1
+ # Stage 8: Delivery
2
+
3
+ - After Judge PASS, run the `after_pass` hook, then the Stage 8 adapter from `.ai-engineering-loop/adapter.md`.
4
+ - The PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Disclose any `budget record --unavailable`.
5
+ - Preview remote payloads; never include context packs, usage ledgers, raw logs, or credentials.
6
+ - ASSISTED: wait for explicit human approval and never infer it. Then one call: `npx ai-engineering-loop deliver --run <runId> --destination <where> --summary <text> --approve --by <name>` (approves READY approval nodes, writes `RUN_DIR/delivery.json` with `humanApproved: true`, runs `gate delivery`). Without `--approve` it refuses in ASSISTED.
7
+ - Long form: `node status --run <runId>`, `node approve delivery-approval --yes --by <name> --run <runId>` for each READY approval node, write `RUN_DIR/delivery.json`, then `gate delivery`. If the gate says a node is not READY, follow its prerequisite hint; never bypass approval.
8
+ - Only the delivery gate completes the run.
@@ -0,0 +1,10 @@
1
+ # Stage 1: Goal Contract
2
+
3
+ - If the user asks for ideas, list a short menu and wait; do not implement.
4
+ - Ambiguous task the user can answer: grill first (`docs grill-policy`): design tree, recommended answers, never ask look-up facts. T2 adds `loop-risky`.
5
+ - If the user prompt has no numbered AC, draft the contract (`docs goal-contract` if needed), list it, and wait. Chat agreement is not freeze.
6
+ - AC is a failure table: each row has a statement, required evidence, and failure cases. Do not freeze sunny-path-only. T0 may use 1-3 rows that still list failure cases.
7
+ - Emit `npx ai-engineering-loop activity goal-drafting --run <runId> --message <summary>`, write the contract JSON to a repository-local temporary file, then `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` so Studio shows the exact draft.
8
+ - Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --latest --run <runId> --by human` (or `--revision <r> --hash <h>`). T0 may write `RUN_DIR/goal-contract.json` and run `gate goal` directly.
9
+ - Do not edit production code until the Goal gate passes.
10
+ - After the freeze, work from the frozen contract (`goal show --run <runId>`), not the drafting chat; compact the conversation there if the host supports it.
@@ -0,0 +1,8 @@
1
+ # Stages 2-4: Maker
2
+
3
+ - T1/T2: read `docs tdd-policy` before Maker. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files.
4
+ - Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
5
+ - Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
6
+ - Bugs: red repro first. Features: one red test per AC row, then green.
7
+ - After package and manifest edits are stable, run `npx ai-engineering-loop refresh` once (drift during red-green is expected; do not refresh per test cycle).
8
+ - ASSISTED: `npx ai-engineering-loop gate maker --from-git` writes the exact working-tree diff (tracked and new files, excluding `.ai-engineering-loop/`) to `RUN_DIR/diff.patch` and gates it; or write that file yourself and run `gate maker`. UNATTENDED: `sandbox capture` writes it, then `gate maker`. The gate can raise the tier from the diff.
@@ -0,0 +1,18 @@
1
+ # Stages 6-7: Devil's Advocate and Judge
2
+
3
+ ## Devil's Advocate (T1, T2)
4
+
5
+ - `npx ai-engineering-loop review-pack --run <runId> --json` returns the DA pack path, fast-path, escalation floor, and tier. Keep the lean path when eligible; add `context devil-advocate <files...>` only for files whose hunks are insufficient. The DA reads that pack or `RUN_DIR/diff.patch` (do not also write `tasks/current.diff`).
6
+ - Use the runtime policy `reviewProfile` (default `lean`); upgrade to `standard` or `thorough` only when the human asks or the budget gate requires it.
7
+ - Spawn a new DA as a sibling (Host rules) with the pack path, the changed paths as a short list, and claimed-vs-reality.md. Do not paste Maker rationale. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files".
8
+ - Iteration 2+: give unresolved findings and new hunks, not the whole diff again.
9
+ - Wait, `budget record` its usage (or `--unavailable`), normalize its ledger into `RUN_DIR/findings.json` with runId and diffHash, then `npx ai-engineering-loop gate review --json`. Report Spec and Standards separately.
10
+
11
+ ## Judge
12
+
13
+ - T0, or T1 when `gate review --json` reports `judgeRequired: false`: run `gate judge`; the CLI writes the deterministic verdict.
14
+ - Otherwise run `npx ai-engineering-loop escalation --json` and resolve the required tier through the host model catalog; if unavailable, escalate to the user. T2 needs STRONG_MODEL.
15
+ - Judge context: only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; it reads the full diff only if those contradict each other. Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
16
+ - Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier`, then `gate judge`. A gate failure overrides optimistic prose.
17
+ - Acting on findings (ITERATE or human MR comments): verify each one before changing code; fix valid ones test-first, decline invalid ones with evidence (skill `ael-receiving-code-review` if installed).
18
+ - ITERATE while iteration < 3: fix in the parent, re-verify, spawn a **new** DA (never resume the previous child). At the iteration ceiling (3) ESCALATE to the human instead.
@@ -0,0 +1,9 @@
1
+ # T2 risky tier
2
+
3
+ Applies to HIGH_RISK_PATH changes (auth, payments, migrations, secrets, infra), DOT business logic, more than 10 files, or a manual `--tier T2`.
4
+
5
+ - Grill before the Goal (`docs grill-policy`): design tree, recommended answers, no look-up questions.
6
+ - Business-logic changes need a blast radius: lifecycle sketch of what reads and writes the changed state; on `adapter_type: dot` load `task-impact-inquiry`. Skip it for docs, config, or UI-copy changes.
7
+ - Full DA (not the T1 lean shortcut) and Judge on STRONG_MODEL resolved through the host model catalog; if unavailable, escalate to the user. Never run the deterministic Judge for T2.
8
+ - UNATTENDED: sandbox worktree only, and `budget pause` is the kill switch (`docs runtime-safety`).
9
+ - The tier never falls back once raised.
@@ -0,0 +1,20 @@
1
+ # Stage 5: Verification
2
+
3
+ - One call: `npx ai-engineering-loop verify --run <runId> [--cmd "<command>"]...` (defaults to `test_unit` from `.ai-engineering-loop/verification.md`). It records each command in parallel (`--serial` for dependent commands), binds bounded, redacted evidence to the gated diff, and only when all pass runs `gate verification`, `context compact`, and scaffolds claimed-vs-reality. Shell syntax needs `--shell`.
4
+ - Long form (same gate): `verification record --run <runId> -- <executable> [args...]` per command, `gate verification`, `context compact --run <runId>`, `context claimed-vs-reality --run <runId>`.
5
+ - A failed command is recorded honestly and returns non-zero; it cannot pass the gate. Vague "seems green" is invalid.
6
+ - Fill `.ai-engineering-loop/tasks/claimed-vs-reality.md`: Claimed from the actual change, Reality from command output. Do not spawn DA while the file is missing or any Claimed row lacks Reality.
7
+ - Hand-authored artifacts: `scaffold verification|findings|delivery --run <runId>` writes an incomplete `.template.json`; edit it into the real artifact, remove `_templateOnly`, and `validate <repository-relative-file>`. Templates are never evidence.
8
+ - Pass run-summary.md and verification-summary.json to reviewers instead of raw logs.
9
+
10
+ ## No claim without fresh evidence
11
+
12
+ Before saying "done", "fixed", "passing", or "ready", run the proving command in this iteration and cite its output; earlier runs and "should work" are not evidence.
13
+
14
+ | Claim | Required evidence |
15
+ |---|---|
16
+ | Tests pass | the test command's output this iteration, exit 0 |
17
+ | Bug fixed | the red repro now passes, with the command shown |
18
+ | AC met | its claimed-vs-reality row cites that output |
19
+
20
+ After `verify`, continue from run-summary.md and verification-summary.json, not earlier logs or chat.