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.
- package/.agents/workflows/ai-engineering-loop.md +47 -11
- package/.claude/commands/ai-engineering-loop.md +1 -1
- package/.claude/skills/ai-engineering-loop/SKILL.md +26 -44
- package/.claude/skills/ai-engineering-loop/references/loop-commands.md +20 -0
- package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
- package/.claude/skills/ai-engineering-loop/references/loop-goal.md +10 -0
- package/.claude/skills/ai-engineering-loop/references/loop-maker.md +8 -0
- package/.claude/skills/ai-engineering-loop/references/loop-review.md +18 -0
- package/.claude/skills/ai-engineering-loop/references/loop-risky.md +9 -0
- package/.claude/skills/ai-engineering-loop/references/loop-verify.md +20 -0
- package/.gemini/skills/ai-engineering-loop/SKILL.md +24 -37
- package/.gemini/skills/ai-engineering-loop/references/loop-commands.md +20 -0
- package/.gemini/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
- package/.gemini/skills/ai-engineering-loop/references/loop-goal.md +10 -0
- package/.gemini/skills/ai-engineering-loop/references/loop-maker.md +8 -0
- package/.gemini/skills/ai-engineering-loop/references/loop-review.md +18 -0
- package/.gemini/skills/ai-engineering-loop/references/loop-risky.md +9 -0
- package/.gemini/skills/ai-engineering-loop/references/loop-verify.md +20 -0
- package/.grok/skills/ai-engineering-loop/SKILL.md +29 -61
- package/.grok/skills/ai-engineering-loop/references/loop-commands.md +20 -0
- package/.grok/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
- package/.grok/skills/ai-engineering-loop/references/loop-goal.md +10 -0
- package/.grok/skills/ai-engineering-loop/references/loop-maker.md +8 -0
- package/.grok/skills/ai-engineering-loop/references/loop-review.md +18 -0
- package/.grok/skills/ai-engineering-loop/references/loop-risky.md +9 -0
- package/.grok/skills/ai-engineering-loop/references/loop-verify.md +20 -0
- package/CHANGELOG.md +69 -0
- package/README.md +40 -1
- package/README.npm.md +6 -2
- package/THIRD_PARTY_NOTICES.md +29 -0
- package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +24 -16
- package/adapters/project-onboarding/SKILL.md +27 -0
- package/adapters/project-onboarding/references/output.md +29 -0
- package/adapters/quality/skills/ael-code-simplifier/SKILL.md +43 -0
- package/adapters/quality/skills/ael-receiving-code-review/SKILL.md +37 -0
- package/bin/ai-engineering-loop.js +979 -69
- package/core/root-cause-analysis.md +6 -0
- package/core/runtime-safety.md +30 -3
- package/evals/cases/21-tier-t0-docs.json +34 -0
- package/evals/cases/22-tier-t1-small-pass.json +30 -0
- package/evals/cases/23-tier-t1-blocker.json +26 -0
- package/evals/cases/24-tier-t1-auth-escalates.json +30 -0
- package/lib/auto-update.js +486 -0
- package/lib/budget.js +31 -1
- package/lib/cli-args.js +84 -0
- package/lib/docs.js +91 -0
- package/lib/doctor.js +7 -1
- package/lib/gates.js +114 -1
- package/lib/host-skill-build.js +121 -0
- package/lib/migrations.js +84 -0
- package/lib/project-registry.js +148 -0
- package/lib/run-state.js +6 -3
- package/lib/sync-hosts.js +325 -42
- package/lib/tier.js +134 -0
- package/lib/update-manager.js +17 -1
- package/lib/update-notice.js +192 -0
- package/lib/user-state.js +80 -0
- package/lib/verification-recorder.js +44 -0
- package/migrations/README.md +21 -0
- package/package.json +7 -2
|
@@ -1,77 +1,49 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ai-engineering-loop
|
|
3
|
-
description:
|
|
4
|
-
Autonomous AI Engineering Operating System. On Grok CLI, run the 8-stage loop
|
|
5
|
-
with native spawn_subagent for Devil's Advocate and Judge (TRUE_INDEPENDENT_AGENT).
|
|
6
|
-
Also handles init/status/refresh of .ai-engineering-loop/ living context.
|
|
7
|
-
Triggers: /ai-engineering-loop, "run the engineering loop", "devil's advocate review".
|
|
3
|
+
description: Use when the user runs /ai-engineering-loop, says "run the engineering loop" or "devil's advocate review", or asks to init or refresh living project context on Grok CLI (native spawn_subagent review).
|
|
8
4
|
user-invocable: true
|
|
9
5
|
---
|
|
6
|
+
<!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
|
|
10
7
|
|
|
11
|
-
# AI Engineering Loop
|
|
8
|
+
# AI Engineering Loop (Grok CLI)
|
|
12
9
|
|
|
13
|
-
|
|
14
|
-
This skill is the Grok host adapter. Do not paraphrase the specs; read them.
|
|
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.
|
|
15
11
|
|
|
16
|
-
## Host
|
|
12
|
+
## Host rules
|
|
17
13
|
|
|
18
|
-
1.
|
|
19
|
-
2.
|
|
20
|
-
3.
|
|
21
|
-
|
|
22
|
-
Canonical mode ids: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_PROCESS_AGENT`, `CONTEXT_ISOLATION_ONLY`, `UNAVAILABLE`.
|
|
23
|
-
Skill aliases: `NATIVE_SUBAGENT` → `TRUE_INDEPENDENT_AGENT`; `ARTIFACT_ISOLATED_REVIEW` → `CONTEXT_ISOLATION_ONLY`.
|
|
24
|
-
|
|
25
|
-
## Grok process topology
|
|
26
|
-
|
|
27
|
-
Parent session is the orchestrator (and usually the Maker). Spawn **siblings**, never nested children (Grok depth limit is 1).
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
Parent (Maker + orchestrator)
|
|
31
|
-
├─ spawn devil-advocate capability_mode=execute isolation=none resume_from=omit
|
|
32
|
-
└─ spawn judge capability_mode=execute isolation=none resume_from=omit
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
Forbidden `subagent_type` values for DA/Judge: `caveman:cavecrew-reviewer`, `caveman:cavecrew-builder`, `caveman:cavecrew-investigator`, `explore`, `plan`. Cavecrew-reviewer uses a different finding schema and cannot feed the Judge.
|
|
36
|
-
|
|
37
|
-
Optional fallback if `devil-advocate` / `judge` types are not registered: `subagent_type: "general-purpose"` with the matching agent spec prepended to the prompt and `description` still prefixed `[devil-advocate]` or `[judge]`.
|
|
14
|
+
1. `spawn_subagent` present and `GROK_SUBAGENTS` not `0`: review is **INVOCATION_AVAILABLE**; **PROVEN** only after a child returns its own `subagent_id`. Otherwise use `CONTEXT_ISOLATION_ONLY`, disclosed; never call it a subagent review.
|
|
15
|
+
2. Siblings only (depth limit 1): `capability_mode: "execute"`, `background: false`, `isolation: none`, no `resume_from`. Forbidden `subagent_type` for DA/Judge: `caveman:cavecrew-reviewer`, `caveman:cavecrew-builder`, `caveman:cavecrew-investigator`, `explore`, `plan`. Unregistered: `general-purpose`, agent spec prepended, `description` prefixed `[devil-advocate]`/`[judge]`.
|
|
16
|
+
3. Models: `grok models` (drop grok-imagine-* and video); never type a model name. Headless `grok -p` is `FRESH_PROCESS_AGENT` only once it prints a model response.
|
|
17
|
+
4. Alias: `NATIVE_SUBAGENT` → `TRUE_INDEPENDENT_AGENT`.
|
|
38
18
|
|
|
39
19
|
## Commands
|
|
40
20
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
Run `npx ai-engineering-loop <command>` in the target repo. Do not commit unless the user asks. `sync-hosts` copies this package's skills/agents/commands into `~/.claude`, `~/.grok`, `~/.gemini`, and `~/.agents` for hosts that already exist. `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/adapter.md`. Do not start Maker. `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q6. Q6 Maker intern: run `grok models` (or `/models` if that slash command exists here), drop grok-imagine-* and video, show numbered options plus none. Do not type a model name. Then write `.ai-engineering-loop/workflow.md` and empty `lessons.md` if missing. Do not start Maker.
|
|
44
|
-
|
|
45
|
-
### `/ai-engineering-loop [task]`
|
|
21
|
+
`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.
|
|
46
22
|
|
|
47
|
-
|
|
23
|
+
## Loop
|
|
48
24
|
|
|
49
|
-
|
|
25
|
+
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`.
|
|
50
26
|
|
|
51
|
-
|
|
27
|
+
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.
|
|
28
|
+
- **T0** trivial (docs, typo, lint): `gate goal`, Maker, `verify`, claimed-vs-reality, `gate review`, `gate judge` (deterministic); no subagents.
|
|
29
|
+
- **T1** normal: frozen Goal, red test, `verify`, lean DA, `gate review --json`; spawn Judge only on `judgeRequired`.
|
|
30
|
+
- **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>`.
|
|
52
31
|
|
|
53
|
-
|
|
32
|
+
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.
|
|
33
|
+
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`.
|
|
54
34
|
|
|
55
|
-
|
|
35
|
+
Invariants (every tier):
|
|
36
|
+
- AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
|
|
37
|
+
- One red test per AC row (bugs: red repro) before the fix.
|
|
38
|
+
- 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.
|
|
39
|
+
- ITERATE at most to iteration 3, each with a **new** DA.
|
|
40
|
+
- Never infer human approval.
|
|
41
|
+
- After each child `budget record` real usage or `--unavailable`; never invent counts.
|
|
42
|
+
- No secrets or hidden reasoning in activity messages.
|
|
56
43
|
|
|
57
|
-
|
|
44
|
+
## Report header
|
|
58
45
|
|
|
59
|
-
|
|
60
|
-
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.
|
|
61
|
-
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 `grok models`; unknown means parent Maker. Intern cannot skip gates or spawn DA/Judge. 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 do not refresh after every test cycle. Then run `npx ai-engineering-loop gate maker`.
|
|
62
|
-
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.
|
|
63
|
-
5. Write artifacts to disk so children do not need parent chat:
|
|
64
|
-
- Goal Contract path
|
|
65
|
-
- `git diff` written to `.ai-engineering-loop/tasks/current.diff`
|
|
66
|
-
- verification log (file)
|
|
67
|
-
- `.ai-engineering-loop/tasks/claimed-vs-reality.md` (do not spawn DA without it)
|
|
68
|
-
- If stopping mid-loop, `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`)
|
|
69
|
-
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 Devil's Advocate with the pack path, `background: false`, `capability_mode: "execute"`, and no `resume_from`; 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`.
|
|
70
|
-
7. Stage 7: Run `npx ai-engineering-loop escalation --json`; resolve `STRONG_MODEL` through `grok models`, or escalate to the user if unavailable. 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 a fresh sibling Judge and wait, then `budget record` actual usage. Normalize `RUN_DIR/verdict.json` with modelTier, then run `npx ai-engineering-loop gate judge`.
|
|
71
|
-
8. If Judge says `ITERATE` and iteration < 3, Maker fixes in the parent, re-verify, spawn a **fresh** DA (new spawn, no resume).
|
|
72
|
-
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.
|
|
73
|
-
|
|
74
|
-
After a proven Grok DA spawn, the report header must be:
|
|
46
|
+
After a proven Grok DA spawn:
|
|
75
47
|
|
|
76
48
|
```
|
|
77
49
|
Execution Mode: TRUE_INDEPENDENT_AGENT
|
|
@@ -80,7 +52,7 @@ Native Subagent Invocation: AVAILABLE
|
|
|
80
52
|
Review Method: True Independent Agent
|
|
81
53
|
```
|
|
82
54
|
|
|
83
|
-
When
|
|
55
|
+
When no subagent ran:
|
|
84
56
|
|
|
85
57
|
```
|
|
86
58
|
Execution Mode: CONTEXT_ISOLATION_ONLY
|
|
@@ -88,7 +60,3 @@ Independent LLM Execution: NOT PROVEN
|
|
|
88
60
|
Native Subagent Invocation: UNAVAILABLE
|
|
89
61
|
Review Method: Clean-Slate Artifact Isolation Barrier
|
|
90
62
|
```
|
|
91
|
-
|
|
92
|
-
## Headless fallback
|
|
93
|
-
|
|
94
|
-
If this session cannot spawn but `grok -p` is authenticated, that is `FRESH_PROCESS_AGENT` only after the child process prints a model response. Prefer `spawn_subagent` when both exist.
|
|
@@ -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.
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. Versions follow [Semantic Versioning](https://semver.org/). Entries under **Unreleased** ship with the next version bump.
|
|
4
|
+
|
|
5
|
+
## Unreleased
|
|
6
|
+
|
|
7
|
+
_No changes yet._
|
|
8
|
+
|
|
9
|
+
## 1.14.0 - 2026-10-10
|
|
10
|
+
|
|
11
|
+
### Auto-update and project registry (#37)
|
|
12
|
+
|
|
13
|
+
- **Added:** `~/.ai-engineering-loop/projects.json`, filled by `init`/`run`/`status`/`refresh`, plus `projects list|add|remove|scan --root <dir> [--depth 4]`. Missing folders are pruned, and the scan skips `node_modules`, `.git`, and symlinks.
|
|
14
|
+
- **Added:** a background version check (detached, at most every 24 h, 3 s timeout, cached in `update-check.json`) that never blocks a command, even offline.
|
|
15
|
+
- **Added:** `update policy off|notify|patch|minor|all` with `--channel` and `--pin`. Majors are always notice-only. Opt out with `AEL_NO_AUTO_UPDATE=1` or `CI=true`.
|
|
16
|
+
- **Added:** `update auto` for global installs. It takes a lock, verifies the release repository and integrity, then runs `npm i -g`, `sync-hosts`, and `refresh --non-destructive` for every registered project. Projects with an active run stay pending, and updates wait while any UNATTENDED run is active. `update rollback --yes` undoes the update.
|
|
17
|
+
- **Added:** `refresh --non-destructive`. Files you edited are kept and new templates are written as `*.ael-new`. Generated hashes are tracked in `.ai-engineering-loop/.ael-generated.json`.
|
|
18
|
+
- **Added:** a useful update notice: current -> latest, 2-4 highlights from the target's CHANGELOG (fetched in the background and cached), one update command for the detected package manager (npm/pnpm/yarn/bun), and how to silence it (`AEL_NO_UPDATE_NOTICE=1`). At most once per 24 h per project, interactive stderr only, never in CI or `--json`. `CHANGELOG.md` now ships in the package.
|
|
19
|
+
- **Added:** legacy projects (no `.ael-generated.json`) get AEL-managed context files overwritten and obsolete ones deleted on their first update, with a snapshot in `.ai-engineering-loop/.ael-backup/<timestamp>/` that `update rollback` restores. Hash-tracked projects also drop obsolete unedited AEL files. `sync-hosts` removes host files it installed that the package no longer ships (for example the old `code-simplifier` and `receiving-code-review` folders), keeping edited ones.
|
|
20
|
+
- **Added:** `migrate --from <version>` and `migrations/<major>.js` (idempotent, recorded in `~/.ai-engineering-loop/migrations.json`). `update apply` runs it after any install that crosses a major. No migration ships in 1.x.
|
|
21
|
+
- **Release:** `publish.yml` publishes with `npm publish --access public --provenance` through OIDC (`id-token: write`), no long-lived token.
|
|
22
|
+
- **Conservative defaults (open decisions):** project-scope installs are notify-only and `package.json` is never changed. With no policy set and no interactive answer, the policy is `notify`; the first-run TTY prompt suggests `minor`. Agents never initiate updates (`core/runtime-safety.md`).
|
|
23
|
+
|
|
24
|
+
### Slim skill adoption (#36)
|
|
25
|
+
|
|
26
|
+
- **Added:** `project-onboarding` (core pack) fills `.ai-engineering-loop/architecture.md` and `conventions.md` from the code, citing evidence. Output is in Indonesian or English, it reads the last 100 commits (or `--since`), and it covers a wider file-type list. It never triggers automatically (`/ai-engineering-loop onboard`).
|
|
27
|
+
- **Added:** opt-in `quality` pack (`sync-hosts --pack quality`). `ael-code-simplifier` tidies a finished diff with no behavior change, on request only, before `verify`. `ael-receiving-code-review` verifies each finding before acting on it and declines with evidence.
|
|
28
|
+
- **Merged, no new skill:** "no claim without fresh evidence" and a claim-to-evidence table in `loop-verify`. Trace-backward, three-strikes, and test-pollution bisection in `core/root-cause-analysis.md`. Stage-boundary compaction notes in `loop-goal` and `loop-verify`. A default verification order in the `verification.md` that `init` generates.
|
|
29
|
+
- **Not adopted:** `using-dot-skills` (an always-invoke rule that conflicts with "pick the smallest relevant skill"), plus planners, TDD guides, reviewer agents, and hooks that duplicate AEL stages.
|
|
30
|
+
- All adopted text was written fresh for AEL; credits are in `THIRD_PARTY_NOTICES.md`.
|
|
31
|
+
- Both quality skills carry an `ael-` prefix (`ael-code-simplifier`, `ael-receiving-code-review`) so they cannot clash with dot-plugin's `code-simplifier` and `receiving-code-review`.
|
|
32
|
+
|
|
33
|
+
### P3 — one skill source, slim SKILL.md, on-demand references, metrics (#35)
|
|
34
|
+
|
|
35
|
+
- **Changed:** the four `ai-engineering-loop` host skills (Claude, Grok, Gemini/Antigravity skill, Antigravity workflow) are generated from `skill-src/ai-engineering-loop/` (one template plus a per-host overlay) by `npm run build:skills`. `npm run check:skills` and a test fail when a generated file is edited by hand.
|
|
36
|
+
- **Changed:** each SKILL.md is now at most 4,000 characters (it was 8-12k): host rules, tier table, stage map, and the quality invariants. Stage details moved to `references/loop-{goal,maker,verify,review,deliver,risky,commands}.md`, read only on entering a stage.
|
|
37
|
+
- **Added:** `sync-hosts` installs `references/` beside each host SKILL.md. The references are also available as `ai-engineering-loop docs loop-<stage>` (the Antigravity workflow uses this).
|
|
38
|
+
- **Added:** `gate maker --from-git` writes the working-tree diff (tracked and new files, excluding `.ai-engineering-loop/`) to `RUN_DIR/diff.patch` and gates it in one call. It is refused in UNATTENDED, where `sandbox capture` is used instead.
|
|
39
|
+
- **Changed:** Stage 0 no longer calls `status` separately, because `run --json` reports host-skill freshness. T0 skips the `tdd-policy` read.
|
|
40
|
+
- **Added:** `npm run measure` drives T0 docs, T1 feature, and T2 auth fixtures through the real CLI and reports context, calls, and subagents per tier.
|
|
41
|
+
|
|
42
|
+
### P2 — combined stage commands to cut agent round-trips (#34)
|
|
43
|
+
|
|
44
|
+
- **Added:** `verify [--cmd "<command>"]... [--shell] [--serial]` records the commands in parallel by default (`--serial` to opt out), and only if all pass runs `gate verification`, compacts the run, and scaffolds `claimed-vs-reality.md`. With no `--cmd` it uses `test_unit` from `.ai-engineering-loop/verification.md`. Failing commands are recorded and never gated.
|
|
45
|
+
- **Added:** `review-pack --json` builds the fast-path assessment, diff-hunk pack, and escalation floor in one call and returns the pack path, tier, and whether a Devil's Advocate is needed.
|
|
46
|
+
- **Added:** `deliver --destination <where> --summary <text> --approve --by <name>` approves READY approval nodes, writes `delivery.json`, and passes the delivery gate. In ASSISTED it refuses (exit 2, nothing written) without `--approve`.
|
|
47
|
+
- **Added:** `goal freeze --latest --by <name>`: the CLI resolves the newest draft revision and hash.
|
|
48
|
+
- **Changed:** `run --json` also returns the budget summary and host-skill freshness. Stage commands publish Studio heartbeats automatically, so skills no longer ask for a manual heartbeat before every stage or for a separate `tasks/current.diff`.
|
|
49
|
+
- The long command forms still work, and the tests show both paths produce identical gate history, artifacts, and workflow node states.
|
|
50
|
+
|
|
51
|
+
### P1 — automatic task tiers with a deterministic review gate (#33)
|
|
52
|
+
|
|
53
|
+
- **Added:** `run` classifies each new run as **T0** (trivial: docs/typo/lint/bump, small), **T1** (default), or **T2** (risky task text, `HIGH_RISK_PATH`, more than 10 files) and stores `tier` with reasons in `state.json`. `run --json` prints `tier`, `tierReasons`, and the expected subagent count. `--tier T0|T1|T2 --tier-reason <text>` overrides and is recorded.
|
|
54
|
+
- **Added:** `gate maker` re-assesses the tier from the gated diff and only raises it (for example T1 → T2 when the diff touches `src/auth/`).
|
|
55
|
+
- **Added:** T0 has no Devil's Advocate. `gate review` writes an explicit empty, diff-bound ledger only after `claimed-vs-reality.md` is complete. T0 and T1 `gate judge` write a deterministic verdict (`decidedBy: deterministic-gate`) when there are no BLOCKER/HIGH findings, escalation is `CHEAP_MODEL`, and the iteration is under the cap. Otherwise the Judge subagent is required. `gate review --json` reports `judgeRequired` with reasons.
|
|
56
|
+
- **Changed:** A T2 Judge `PASS` requires `modelTier` `STRONG_MODEL` or `HUMAN`. Runs without a tier (created before this change or directly through the library) keep the previous full-Judge behavior.
|
|
57
|
+
- **Changed:** The DOT blast-radius grill applies to business-logic changes, not to every DOT task.
|
|
58
|
+
- **Added:** Four evaluation cases (21–24) for the tier paths. The catalog is now 24 cases.
|
|
59
|
+
|
|
60
|
+
### P0 — slim context and round-trips without weakening gates (#26)
|
|
61
|
+
|
|
62
|
+
- **Fixed (#25):** `--help` / `-h` on any command prints that command's usage and exits without side effects. `sync-hosts --help` no longer runs a real sync. Writer commands (`init`, `refresh`, `sync-hosts`, `update`, `generate-adapter`, `generate-workflow`) reject unknown flags with exit code 2 before writing anything.
|
|
63
|
+
- **Fixed (#25):** `sync-hosts` records what it wrote in `~/.ai-engineering-loop/host-manifest.json`. A host file that was edited by hand (or that predates the manifest) is copied to `<file>.ael-backup` before it is overwritten.
|
|
64
|
+
- **Changed (#27):** Host skills no longer tell agents to read all of `core/`, `agents/`, and `policies/` (files that do not exist in target repositories). New read-only `ai-engineering-loop docs <name> [--section <heading>]` prints one packaged spec, and skills cite specs only at the stage that needs them.
|
|
65
|
+
- **Changed (#28):** Devil's Advocate / Judge budgets live in the agent bodies. Parent skills keep only the one-line spawn prompt (needed when a host falls back to a `general-purpose` child); the Claude command no longer repeats them.
|
|
66
|
+
- **Changed (#29):** When the host exposes no provider usage, `budget record --unavailable` notes the gap once. `ASSISTED` continues and discloses it at delivery instead of asking the human; `UNATTENDED` fails closed with `USAGE_UNAVAILABLE_UNATTENDED`. `budget status` runs once per iteration instead of before every child.
|
|
67
|
+
- **Changed (#30):** `run` no longer syncs host skills, and Stage 0 no longer calls `sync-hosts`. `status` / new `status --json` report `hostSkills` freshness (`installedVersion`, `packageVersion`, `stale`, `staleFiles`) without writing.
|
|
68
|
+
- **Changed (#31):** `sync-hosts` installs only the `core` pack by default. `--pack backend,design` opts in (saved in `~/.ai-engineering-loop/config.json`); `--prune` removes unmodified files of unselected packs. Existing installs keep any optional pack already on disk.
|
|
69
|
+
- **Fixed (#32):** `dot-dev-skill-router` names only skills that exist in AEL or dot-plugin (`verification-before-completion`, `design-openapi-contract`, `generate-api-test`, ...) or are explicitly marked *optional, if installed*. Plan-execution and brainstorming routes now go through the AEL loop instead of around it.
|
package/README.md
CHANGED
|
@@ -65,6 +65,30 @@ npx ai-engineering-loop verification record --run <run-id> -- npm test
|
|
|
65
65
|
|
|
66
66
|
The command captures bounded, redacted output without invoking a shell implicitly, records failures honestly, and generates a compact test summary. For other stage artifacts, use `scaffold delivery --run <run-id>` (or `verification` / `findings`) to create a private, deliberately incomplete template. Copy or rename it to the gate's real artifact filename, fill it with observed evidence, and remove `_templateOnly`; then `validate <repository-relative-file>` reports schema and Run-binding issues without advancing a gate. Templates are never accepted as evidence. `context claimed-vs-reality --run <run-id>` creates the Goal checklist while leaving claim and evidence cells blank.
|
|
67
67
|
|
|
68
|
+
Common stage sequences also have one-call forms that gate exactly like the long forms:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
npx ai-engineering-loop verify --run <run-id> --cmd "npm test" # record (parallel), gate, compact, claimed-vs-reality
|
|
72
|
+
npx ai-engineering-loop review-pack --run <run-id> --json # fast-path + diff-hunk pack + escalation floor
|
|
73
|
+
npx ai-engineering-loop deliver --run <run-id> --destination pr --summary "..." --approve --by <name>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`deliver` refuses without `--approve` in ASSISTED mode; pass it only after a human approved delivery.
|
|
77
|
+
|
|
78
|
+
Contributors: the host `ai-engineering-loop` skills are generated. Edit `skill-src/ai-engineering-loop/`, then run `npm run build:skills` (CI checks for drift with `npm run check:skills`). `npm run measure` reports per-tier context and tool calls.
|
|
79
|
+
|
|
80
|
+
### Staying up to date
|
|
81
|
+
|
|
82
|
+
`run`, `status`, `init`, and `refresh` check npm in the background at most once a day; the command never waits. What happens next depends on your policy:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npx ai-engineering-loop update policy minor # off | notify | patch | minor | all (majors are always notice-only)
|
|
86
|
+
npx ai-engineering-loop projects list # projects refreshed after an update (scan: projects scan --root ~/Development)
|
|
87
|
+
npx ai-engineering-loop update rollback --yes
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Global installs apply patch and minor releases automatically. They then re-sync host skills and refresh every registered project, keeping your edits (new templates arrive as `*.ael-new`). Project installs only show a short notice (current -> latest, a few changelog highlights, the exact `npm`/`pnpm`/`yarn`/`bun` command, how to silence it), at most once a day per project, because AEL never edits your `package.json`. Projects from versions before hash tracking are overwritten on their first update, with the old files kept in `.ai-engineering-loop/.ael-backup/` and restored by `update rollback`. Major updates run `migrate --from <old>` after install. Opt out with `AEL_NO_AUTO_UPDATE=1`; CI is always off. There is no daemon, so other machines pick up an update the next time the CLI runs there.
|
|
91
|
+
|
|
68
92
|
When context packs exceed their budget, the CLI now reports the limit and a per-file size/token estimate so an agent can choose smaller files without trial and error. For a delivery gate blocked by a recipe approval node, inspect `node status --run <run-id>` and explicitly approve the READY prerequisite; the gate error points to the actionable command.
|
|
69
93
|
|
|
70
94
|
## Meet Workflow Studio
|
|
@@ -138,7 +162,22 @@ AI Engineering Loop is designed to work with the tools developers already use:
|
|
|
138
162
|
- **Gemini / Antigravity**
|
|
139
163
|
- Other agent hosts that can read project instructions and run local commands
|
|
140
164
|
|
|
141
|
-
The project includes ready-to-use skills and reviewer roles for supported hosts. Each host follows the same Goal, verification, review, and approval rules.
|
|
165
|
+
The project includes ready-to-use skills and reviewer roles for supported hosts. Each host follows the same Goal, verification, review, and approval rules.
|
|
166
|
+
|
|
167
|
+
`sync-hosts` installs the **core** pack by default: the `ai-engineering-loop` skill, Devil's Advocate and Judge agents, commands, and the small helper skills the loop itself uses. Optional packs stay out of every session's skill index until you ask for them:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
npx ai-engineering-loop sync-hosts --pack backend # framework-agnostic backend best practices
|
|
171
|
+
npx ai-engineering-loop sync-hosts --pack backend,design # plus Emil Kowalski's MIT-licensed design/animation skills
|
|
172
|
+
npx ai-engineering-loop sync-hosts --pack quality # ael-code-simplifier + ael-receiving-code-review (opt-in)
|
|
173
|
+
npx ai-engineering-loop sync-hosts --pack core --prune # drop unmodified optional-pack files again
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The choice is saved in `~/.ai-engineering-loop/config.json` and reused by later syncs. Existing installs keep any optional pack that is already on disk. Host files you edited by hand are backed up to `<file>.ael-backup` before they are overwritten, and `--help` or an unknown flag never writes anything.
|
|
177
|
+
|
|
178
|
+
Runs do not touch your home directory: `run` no longer syncs hosts. `status` (and `status --json`) reports when host skills are behind the package so you can sync and start a new session.
|
|
179
|
+
|
|
180
|
+
Specs such as the grill, TDD, and runtime-safety policies ship inside the package. Agents read only the one they need with `npx ai-engineering-loop docs <name> [--section <heading>]`.
|
|
142
181
|
|
|
143
182
|
## Create workflows that fit your team
|
|
144
183
|
|
package/README.npm.md
CHANGED
|
@@ -47,9 +47,13 @@ npx ai-engineering-loop studio
|
|
|
47
47
|
npx ai-engineering-loop handoff create --audience developer
|
|
48
48
|
|
|
49
49
|
# 5. Copy package host skills into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
50
|
-
#
|
|
51
|
-
#
|
|
50
|
+
# Default: core pack (ai-engineering-loop skill, DA/Judge agents, commands).
|
|
51
|
+
# Optional: --pack backend,design (saved for later syncs); --prune removes them again.
|
|
52
52
|
npx ai-engineering-loop sync-hosts
|
|
53
|
+
npx ai-engineering-loop sync-hosts --pack backend,design
|
|
54
|
+
|
|
55
|
+
# Read one packaged spec instead of the whole package source
|
|
56
|
+
npx ai-engineering-loop docs grill-policy --section "When to grill"
|
|
53
57
|
```
|
|
54
58
|
|
|
55
59
|
---
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -8,3 +8,32 @@ AEL vendors design and animation skills from `emilkowalski/skills` so `ai-engine
|
|
|
8
8
|
- License: MIT
|
|
9
9
|
|
|
10
10
|
The vendored skill text remains authored by the original project. See the upstream repository for updates and full project context.
|
|
11
|
+
|
|
12
|
+
## Adopted skill ideas (issue #36)
|
|
13
|
+
|
|
14
|
+
The following AEL files were written fresh for AEL. No upstream text was copied. They adapt ideas from the projects below, which are credited here.
|
|
15
|
+
|
|
16
|
+
### obra/superpowers
|
|
17
|
+
|
|
18
|
+
- Source: https://github.com/obra/superpowers
|
|
19
|
+
- License: MIT
|
|
20
|
+
- Ideas adapted: receiving-code-review (verify feedback before acting, decline with evidence), verification-before-completion (no completion claim without fresh evidence), and systematic-debugging (trace backward, question the design after three failed fixes, bisect test pollution).
|
|
21
|
+
- AEL files: `adapters/quality/skills/ael-receiving-code-review/SKILL.md` (prefixed `ael-` to avoid clashing with the dot-plugin skill of the same idea), the "No claim without fresh evidence" section of `references/loop-verify.md`, and "When fixes keep failing" in `core/root-cause-analysis.md`.
|
|
22
|
+
|
|
23
|
+
### worldflowai/everything-claude-code
|
|
24
|
+
|
|
25
|
+
- Source: https://github.com/worldflowai/everything-claude-code
|
|
26
|
+
- License: MIT (as stated in the project README)
|
|
27
|
+
- Ideas adapted: strategic-compact (compact at stage boundaries) and verification-loop (build, typecheck, lint, test, security order).
|
|
28
|
+
- AEL files: the compaction notes in `references/loop-goal.md` / `loop-verify.md` and the default order in the generated `.ai-engineering-loop/verification.md`.
|
|
29
|
+
|
|
30
|
+
### Cynthia-cym/project-onboarding
|
|
31
|
+
|
|
32
|
+
- Source: https://github.com/Cynthia-cym/project-onboarding
|
|
33
|
+
- License: MIT, Copyright (c) 2026 Cynthia-cym
|
|
34
|
+
- Ideas adapted: evidence-first repository onboarding from structure, history, and code patterns.
|
|
35
|
+
- AEL files: `adapters/project-onboarding/` (writes `.ai-engineering-loop/architecture.md` and `conventions.md`).
|
|
36
|
+
|
|
37
|
+
### ael-code-simplifier
|
|
38
|
+
|
|
39
|
+
`adapters/quality/skills/ael-code-simplifier/SKILL.md` is an original AEL text for a common "simplify the diff without changing behavior" practice.
|
|
@@ -12,10 +12,17 @@ Pick the smallest relevant skill. Do not load every skill. **AI Engineering Loop
|
|
|
12
12
|
1. Read repository instructions and inspect the affected code before choosing a workflow.
|
|
13
13
|
2. For DOT work that will be committed or opened as an MR, load `ai-engineering-loop`. Stage 1 grill includes `task-impact-inquiry` (four pillars). Stages 6-7 are AEL Devil's Advocate and Judge. Do not run the old 9-phase `dot-dev-workflow` as a second loop. Do not run `task-impact-inquiry` as a second interview after grill.
|
|
14
14
|
3. After Judge `PASS`, load `dot-dev-workflow` for Stage 8 delivery only.
|
|
15
|
-
4. Use `ponytail` when the smallest correct solution matters.
|
|
16
|
-
5. Use `dot-verification` before claiming a change is fixed, complete, passing, or ready.
|
|
17
|
-
6. Commits, push, GitLab issue/MR, Mattermost, deploys, database mutation, and deletion are explicit user-requested side effects. `auto-mr-issue` is never automatic.
|
|
15
|
+
4. Use `ponytail` (optional, if installed) when the smallest correct solution matters.
|
|
16
|
+
5. Use `verification-before-completion` (dot-plugin; older installs call it `dot-verification`) before claiming a change is fixed, complete, passing, or ready.
|
|
17
|
+
6. Commits, push, GitLab issue/MR, Mattermost, deploys, database mutation, and deletion are explicit user-requested side effects. `auto-mr-issue` (optional, if installed) is never automatic.
|
|
18
18
|
7. Do not invent APIs, test results, design tokens, or behavior. Report blockers as blockers.
|
|
19
|
+
8. If a named skill is not installed, say so and continue with `ai-engineering-loop`; never guess a substitute name.
|
|
20
|
+
|
|
21
|
+
## Skill sources
|
|
22
|
+
|
|
23
|
+
- **AEL (this package):** `ai-engineering-loop`, `task-impact-inquiry`, `dot-dev-workflow`, `backend-development`.
|
|
24
|
+
- **dot-plugin:** `verification-before-completion`, `design-openapi-contract`, `design-dbml-database`, `generate-api-test`, `generate-ui-e2e-test`, `generate-module-fsd`, `merge-request`, `gitlab-mr-feedback`, `receiving-code-review`, `fetch-gitlab-issue`, `sonarqube-issues`, `sentry-issues`.
|
|
25
|
+
- **Optional, if installed:** `ponytail`, `auto-mr-issue`, `product-contract-analysis`, `fig-to-tailwind-extractor`, `figma-token-extractor`, `frontend-design`, `design-taste-frontend`, `ui-ux-pro-max`, `web-design-guidelines`, `webapp-testing`, `backend-safety-guardrails`, `creative-ideation`.
|
|
19
26
|
|
|
20
27
|
## Route by task
|
|
21
28
|
|
|
@@ -23,22 +30,23 @@ Pick the smallest relevant skill. Do not load every skill. **AI Engineering Loop
|
|
|
23
30
|
|---|---|
|
|
24
31
|
| DOT bugfix / feature / refactor that will be committed or opened as MR | `ai-engineering-loop` (grill includes `task-impact-inquiry`; DA + Judge before commit) → `dot-dev-workflow` Stage 8 after Judge PASS |
|
|
25
32
|
| Impact / blast-radius question only (no implementation) | `task-impact-inquiry` |
|
|
26
|
-
| New feature, product/UI behavior unclear | `
|
|
33
|
+
| New feature, product/UI behavior unclear | `ai-engineering-loop` Stage 1 grill and Goal Contract; add `product-contract-analysis` (optional, if installed) for product questions. Do not run a separate brainstorming loop |
|
|
27
34
|
| Legacy FE + BE module documentation | `generate-module-fsd` |
|
|
28
|
-
| Raw `.fig` file to standalone HTML + Tailwind | `fig-to-tailwind-extractor`; add `figma-token-extractor` for token/visual-contract audit |
|
|
29
|
-
| New landing page or visual redesign | `frontend-design` + `design-taste-frontend`; add `ui-ux-pro-max` only for a targeted UI decision |
|
|
30
|
-
| UI/accessibility/design review | `web-design-guidelines`; add `ui-ux-pro-max` for focused UX, stack, typography, or interaction guidance |
|
|
31
|
-
| DOT API contract or OpenAPI change | `ai-engineering-loop` → `
|
|
32
|
-
| DOT
|
|
33
|
-
|
|
|
34
|
-
| Backend
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
35
|
+
| Raw `.fig` file to standalone HTML + Tailwind | `fig-to-tailwind-extractor`; add `figma-token-extractor` for token/visual-contract audit (both optional, if installed) |
|
|
36
|
+
| New landing page or visual redesign | `frontend-design` + `design-taste-frontend`; add `ui-ux-pro-max` only for a targeted UI decision (optional, if installed) |
|
|
37
|
+
| UI/accessibility/design review | `web-design-guidelines`; add `ui-ux-pro-max` for focused UX, stack, typography, or interaction guidance (optional, if installed) |
|
|
38
|
+
| DOT API contract or OpenAPI change | `ai-engineering-loop` → `design-openapi-contract` → `verification-before-completion` |
|
|
39
|
+
| DOT database schema (DBML) change | `ai-engineering-loop` → `design-dbml-database` → `verification-before-completion` |
|
|
40
|
+
| DOT backend behavior/API regression coverage | `ai-engineering-loop` → `generate-api-test` → `verification-before-completion` |
|
|
41
|
+
| Backend architecture, clean code, naming, or query optimization | `ai-engineering-loop` → `backend-development` (during Maker) → `verification-before-completion` |
|
|
42
|
+
| Backend action, queue, worker, or entity status recalculation | `ai-engineering-loop` → `backend-development` + `backend-safety-guardrails` (optional, if installed) during Maker → `verification-before-completion` |
|
|
43
|
+
| Local web app repro, browser smoke, or UI regression | `webapp-testing` (optional, if installed) → `verification-before-completion` |
|
|
44
|
+
| Executing an existing written plan | `ai-engineering-loop` (paste the plan as the Goal Contract draft). Do not load `executing-plans` as a second loop |
|
|
45
|
+
| Pre-merge review after AEL already ran | AEL Judge verdict is the gate. Do not re-run a separate devil's-advocate skill unless Judge was skipped |
|
|
38
46
|
| Code review feedback reception | `receiving-code-review` |
|
|
39
47
|
| GitLab MR discussions / feedback resolution | `gitlab-mr-feedback` → `receiving-code-review` |
|
|
40
|
-
| Broad creative/product ideation | `creative-ideation
|
|
41
|
-
| Explicit post-commit GitLab issue/MR request | `auto-mr-issue` after the user explicitly asks for it |
|
|
48
|
+
| Broad creative/product ideation | AEL idea menu (list a short menu and wait); `creative-ideation` (optional, if installed) for open-ended exploration |
|
|
49
|
+
| Explicit post-commit GitLab issue/MR request | `auto-mr-issue` (optional, if installed) after the user explicitly asks for it |
|
|
42
50
|
|
|
43
51
|
## Workflow gates
|
|
44
52
|
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: project-onboarding
|
|
3
|
+
description: Use when the user asks to onboard onto a repository or to fill or refresh .ai-engineering-loop/architecture.md and conventions.md from the actual code. Does NOT run the engineering loop, edit source code, or trigger automatically on every session.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Onboarding
|
|
7
|
+
|
|
8
|
+
Turn an unfamiliar repository into evidence-backed living context for the AI Engineering Loop. Output goes into `.ai-engineering-loop/architecture.md` and `.ai-engineering-loop/conventions.md`, in the language the user writes in (Indonesian or English).
|
|
9
|
+
|
|
10
|
+
Run `npx ai-engineering-loop init` first if `.ai-engineering-loop/` is missing. Never edit source code here.
|
|
11
|
+
|
|
12
|
+
## Procedure
|
|
13
|
+
|
|
14
|
+
1. **Shape.** List the top two directory levels and the manifests (package.json, go.mod, pyproject.toml, pom.xml, Gemfile, composer.json, Cargo.toml, Dockerfile, CI files). Record languages, frameworks, entry points, and how to run, test, and build.
|
|
15
|
+
2. **History.** `git log --oneline -n 100` (or `--since=<date>` for a large repo) and `git shortlog -sn -n 100`. Note hot directories, recent large changes, and reverts. Reverts and repeated fixes in one area are gotcha candidates.
|
|
16
|
+
3. **Data path.** Follow one real request or job from ingress to persistence and side effects. Name the modules and seams.
|
|
17
|
+
4. **Conventions.** Grep for the patterns the code actually uses: error handling, logging, validation, config, test layout, naming. Check `*.{js,ts,tsx,jsx,py,go,rb,java,kt,php,rs,cs,swift,sql}`. Prefer what most files do over what one file does.
|
|
18
|
+
5. **Gotchas.** Only record ones you can prove: cite a file:line, commit, test, or command output for each. No speculation.
|
|
19
|
+
6. **Write.** Update the two files with the template in `references/output.md`. Keep existing human-written sections; add or replace only the sections this skill owns.
|
|
20
|
+
7. **Report** what you added, the evidence count, and any open question for the human.
|
|
21
|
+
|
|
22
|
+
## Rules
|
|
23
|
+
|
|
24
|
+
- Evidence over adjectives: every claim names its source.
|
|
25
|
+
- Do not paste secrets, tokens, customer data, or `.env` values; name the variable instead.
|
|
26
|
+
- Keep each file short (aim for under 150 lines). Link to code instead of copying it.
|
|
27
|
+
- Commands you ran go into `.ai-engineering-loop/verification.md` only if they actually passed.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Onboarding output template
|
|
2
|
+
|
|
3
|
+
## architecture.md (sections owned by project-onboarding)
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
## Overview (onboarding)
|
|
7
|
+
<2-4 lines: what the system does, main runtime, deployment shape>
|
|
8
|
+
|
|
9
|
+
## Modules and seams
|
|
10
|
+
| Area | Path | Responsibility | Evidence |
|
|
11
|
+
|---|---|---|---|
|
|
12
|
+
|
|
13
|
+
## Request / job path
|
|
14
|
+
<ingress> -> <handler> -> <domain> -> <store> -> <side effects> (file:line for each hop)
|
|
15
|
+
|
|
16
|
+
## Hot spots (last 100 commits)
|
|
17
|
+
- <path>: <n> commits; <why it churns, with commit refs>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## conventions.md (sections owned by project-onboarding)
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
## Observed conventions (onboarding)
|
|
24
|
+
| Topic | Rule the code follows | Example (file:line) |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
|
|
27
|
+
## Gotchas (proven)
|
|
28
|
+
- <gotcha> — evidence: <file:line | commit | test | command + exit code>
|
|
29
|
+
```
|