ai-engineering-loop 1.13.0 → 1.15.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 (117) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +62 -0
  2. package/.agents/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  4. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  6. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-review.md +18 -0
  8. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  9. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  10. package/.claude/skills/ai-engineering-loop/SKILL.md +28 -47
  11. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  12. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  13. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  14. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  15. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  16. package/.claude/skills/ai-engineering-loop/references/loop-review.md +18 -0
  17. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  18. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  19. package/CHANGELOG.md +116 -0
  20. package/README.md +90 -5
  21. package/README.npm.md +6 -2
  22. package/THIRD_PARTY_NOTICES.md +29 -0
  23. package/adapters/dot/README.md +1 -1
  24. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +24 -16
  25. package/adapters/project-onboarding/SKILL.md +27 -0
  26. package/adapters/project-onboarding/references/output.md +29 -0
  27. package/adapters/quality/skills/ael-code-simplifier/SKILL.md +43 -0
  28. package/adapters/quality/skills/ael-receiving-code-review/SKILL.md +37 -0
  29. package/bin/ai-engineering-loop.js +1270 -75
  30. package/core/grill-policy.md +1 -1
  31. package/core/root-cause-analysis.md +6 -0
  32. package/core/runtime-safety.md +31 -3
  33. package/evals/cases/21-tier-t0-docs.json +34 -0
  34. package/evals/cases/22-tier-t1-small-pass.json +30 -0
  35. package/evals/cases/23-tier-t1-blocker.json +26 -0
  36. package/evals/cases/24-tier-t1-auth-escalates.json +30 -0
  37. package/lib/auto-update.js +488 -0
  38. package/lib/budget.js +31 -1
  39. package/lib/cli-args.js +95 -0
  40. package/lib/docs.js +91 -0
  41. package/lib/doctor.js +9 -14
  42. package/lib/gates.js +114 -1
  43. package/lib/host-skill-build.js +121 -0
  44. package/lib/hosts/agent-formats.js +135 -0
  45. package/lib/hosts/commands.js +126 -0
  46. package/lib/hosts/detect.js +56 -0
  47. package/lib/hosts/doctor.js +76 -0
  48. package/lib/hosts/redetect.js +60 -0
  49. package/lib/hosts/registry.js +271 -0
  50. package/lib/hosts/table.js +35 -0
  51. package/lib/migrations.js +84 -0
  52. package/lib/project-registry.js +148 -0
  53. package/lib/run-abandon.js +116 -0
  54. package/lib/run-state.js +6 -3
  55. package/lib/sync-hosts.js +456 -130
  56. package/lib/tier.js +134 -0
  57. package/lib/update-manager.js +17 -1
  58. package/lib/update-notice.js +192 -0
  59. package/lib/user-state.js +80 -0
  60. package/lib/verification-recorder.js +44 -0
  61. package/migrations/README.md +21 -0
  62. package/package.json +8 -4
  63. package/.agents/devil-advocate.md +0 -79
  64. package/.agents/judge.md +0 -58
  65. package/.agents/workflows/ai-engineering-loop.md +0 -24
  66. package/.claude/commands/ai-engineering-loop.md +0 -11
  67. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -74
  68. package/.gemini/skills/animate/RECIPES.md +0 -324
  69. package/.gemini/skills/animate/SKILL.md +0 -207
  70. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  71. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  72. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  73. package/.gemini/skills/apple-design/SKILL.md +0 -290
  74. package/.gemini/skills/ask-sonner/API.md +0 -64
  75. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  76. package/.gemini/skills/backend-development/SKILL.md +0 -272
  77. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  78. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  79. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  80. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  81. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  82. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  83. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  84. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  85. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  86. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  87. package/.gemini/skills/prototype/PICKER.md +0 -197
  88. package/.gemini/skills/prototype/SKILL.md +0 -98
  89. package/.gemini/skills/review-animations/SKILL.md +0 -120
  90. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  91. package/.gemini/skills/write-swift/SKILL.md +0 -396
  92. package/.grok/commands/ai-engineering-loop.md +0 -11
  93. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -94
  94. package/.grok/skills/animate/RECIPES.md +0 -324
  95. package/.grok/skills/animate/SKILL.md +0 -207
  96. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  97. package/.grok/skills/animate-expo/SKILL.md +0 -263
  98. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  99. package/.grok/skills/apple-design/SKILL.md +0 -290
  100. package/.grok/skills/ask-sonner/API.md +0 -64
  101. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  102. package/.grok/skills/backend-development/SKILL.md +0 -272
  103. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  104. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  105. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  106. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  107. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  108. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  109. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  110. package/.grok/skills/improve-animations/SKILL.md +0 -109
  111. package/.grok/skills/mobile-native/SKILL.md +0 -311
  112. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  113. package/.grok/skills/prototype/PICKER.md +0 -197
  114. package/.grok/skills/prototype/SKILL.md +0 -98
  115. package/.grok/skills/review-animations/SKILL.md +0 -120
  116. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  117. package/.grok/skills/write-swift/SKILL.md +0 -396
package/CHANGELOG.md ADDED
@@ -0,0 +1,116 @@
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.15.0 - 2026-10-11
10
+
11
+ ### Multi-agent hosts: `setup` suggests `auto` detection mode (#54 decision 4)
12
+
13
+ - **Changed:** interactive `setup` now asks "Sync agents you install later automatically? [Y/n] (recommended: Y = auto)"; pressing Enter picks `auto`. `setup --yes`, a missing TTY, CI, and scripts keep `manual` unless `--mode` is passed. Gemini CLI detection, Kiro/Junie read-only reviewers, and the deferred Cline reviewer are unchanged.
14
+
15
+ ### Multi-agent hosts, phase 4: new agents, `hosts doctor`, generated host table (#52)
16
+
17
+ - **Added:** agents installed after `setup` are detected again (stat only). With `hosts.mode: auto`, the background `update auto` of a global install enables and syncs them; a host you disabled stays disabled. With `manual` (default), `status` prints one short notice per new agent, at most once a day. Nothing is written or shown in CI, in `--json` output, or with `AEL_NO_AUTO_UPDATE=1`. `update auto --json` reports `hosts.added`.
18
+ - **Added:** `hosts doctor [--json]`: per enabled host, how many copies of the core skill it sees across the folders it scans, whether they are identical, and which AEL files still need a sync. Read-only; exits 1 when something needs attention.
19
+ - **Changed:** the README host table is generated from `lib/hosts/registry.js` (`npm run build:hosts-table`); `npm test` fails when it drifts.
20
+
21
+ ### Multi-agent hosts, phase 3: own-folder hosts (#51)
22
+
23
+ - **Added:** Cline (`~/.cline/skills`), Kiro (`~/.kiro/skills`), and Qwen Code (`~/.qwen/skills`) get their own byte-identical copy of the skill, because they do not read `~/.agents/skills/`.
24
+ - **Added:** Roo Code and JetBrains Junie, which the current docs show also read `~/.agents/skills/`, so they use the shared copy (the research report had marked this as inferred "no").
25
+ - **Added:** reviewer subagents for Kiro (`~/.kiro/agents/*.md`, `tools: [read]`), Qwen (`~/.qwen/agents/*.md`, `approvalMode: plan`), and Junie (`~/.junie/agents/*.md`, `tools: [Read, Grep]`). Cline and Roo get none (no documented file format), so the loop runs `CONTEXT_ISOLATION_ONLY` there.
26
+
27
+ ### Multi-agent hosts, phase 2: shared-folder hosts (#50)
28
+
29
+ - **Added:** OpenCode, Windsurf/Devin Desktop, Amp, Factory Droid, Augment (Auggie), Zed, and Goose to the host registry. All of them read the shared `~/.agents/skills/` folder, so they use the same single copy of the skill and never get a second one in their own folders.
30
+ - **Added:** reviewer subagents where the host supports file-based ones: OpenCode `~/.config/opencode/agents/*.md` (`mode: subagent`, edits denied), Factory `~/.factory/droids/*.md` (`tools: read-only`), and Augment `~/.augment/agents/*.md`. Amp (TypeScript plugins), Zed, Goose, and Windsurf have no file-based reviewer agent, so the loop runs DA and Judge as `CONTEXT_ISOLATION_ONLY` there.
31
+
32
+ ### Multi-agent hosts, phase 1: host registry, setup, and `hosts` (#49)
33
+
34
+ - **Added:** a data-driven host registry (`lib/hosts/registry.js`). Each entry holds detection signals, the skill folder (the shared `~/.agents/skills` or the host's own), the folders the host scans, the reviewer subagent format, official doc links, and a verification date. Tier 1 hosts: Claude Code, Codex CLI, Gemini CLI, Antigravity (IDE/2.0 and the `agy` CLI), Grok CLI, Cursor, and GitHub Copilot.
35
+ - **Added:** detection by config folder or by an executable on `PATH`. The binary is checked with `stat` only and never executed.
36
+ - **Added:** reviewer subagents in each host's own format, all from the same `agents/shared/*.body.md`: Codex `~/.codex/agents/*.toml` (read-only sandbox), Gemini CLI `~/.gemini/agents/*.md`, Cursor `~/.cursor/agents/*.md` (`readonly`), and Copilot `~/.copilot/agents/*.agent.md`.
37
+ - **Added:** `setup [--yes] [--hosts a,b] [--mode auto|manual] [--json]`, which runs once and asks before writing. Without a TTY it prints the plan and writes nothing unless `--yes` is passed. Also added: `hosts list [--json]`, `hosts enable <id...>`, and `hosts disable <id...>`. Disabling removes only manifest-tracked files that AEL wrote and you did not edit. The shared folder stays while any enabled host still reads it.
38
+ - **Added:** a first-run hint that replaces a `postinstall` hook. It appears on interactive stderr at most once a day until hosts are chosen, never in CI or `--json`, and can be silenced with `AEL_NO_SETUP_HINT=1`. The package still defines no install script.
39
+ - Until `setup` runs, `sync-hosts` and `update auto` write only to hosts whose config folder already exists, or that an earlier sync already installed. Hosts found only on `PATH` wait for `setup`.
40
+
41
+ ### Multi-agent hosts, phase 0: close the host gaps (#48)
42
+
43
+ - **Fixed:** the `ai-engineering-loop` skill now lands in the shared `~/.agents/skills/` folder, so Codex, Gemini CLI, and the other hosts that read it see the loop. Grok, Gemini CLI, and Codex installs trigger it.
44
+ - **Fixed:** Gemini CLI no longer gets Antigravity's `~/.gemini/config/skills/` path. Antigravity keeps `~/.gemini/config/skills/`, and its Devil's Advocate and Judge now install as `~/.gemini/config/agents/<name>.md` subagents (`subagent: true`) instead of `~/.agents/*.md`.
45
+ - **Changed:** one host-neutral `SKILL.md` (standard `name`/`description` frontmatter only) is generated for every host, byte-identical everywhere. Per-host spawn rules moved to `references/loop-hosts.md`. Grok no longer gets its own skill copies (it reads `~/.claude/skills` and `~/.agents/skills`), and the `user-invocable` overlay is gone (Grok's default is already `true`).
46
+ - **Removed:** `~/.agents/workflows/ai-engineering-loop.md`, `~/.agents/{devil-advocate,judge}.md`, and the `~/.claude/commands` and `~/.grok/commands` copies. The skill already provides `/ai-engineering-loop`. `sync-hosts` deletes these files where AEL wrote them, and keeps them if you edited them.
47
+ - **Note:** the Claude skill no longer pre-approves tools through `allowed-tools`, because other hosts (for example Copilot) treat that field as a permission grant. Claude Code may ask for permission a little more often.
48
+
49
+ ### `run --abandon` for stale runs (#46)
50
+
51
+ - **Added:** `run --abandon [--run <id>] --reason <text> --by <name> [--yes] [--json]`. It moves a run that will never finish to `CANCELLED`, records reason, actor, and time in the run's history ledger (recipe-bound runs also get a `RUN_CANCELLED` event), and releases `current.json` so `refresh --non-destructive` and `update auto` process the project again. Run data is kept. With `--run <id>` for a non-current run, the current pointer is left alone.
52
+ - ASSISTED runs ask for confirmation (or `--yes`). UNATTENDED runs are refused (exit 2) unless a human passes `--yes`. Finished runs and "no current run" exit 2. `--help` writes nothing, and unknown flags are rejected before any write.
53
+ - `status` (text and `--json` `activeRun`), `state`, and `projects list` point at `run --abandon` when the active run has not moved for 7 days or more. The "skipping refresh" message and the pending-projects update summary suggest it too.
54
+ - A pointer renamed by hand to `runs/current.stale-*.json` is simply ignored.
55
+
56
+ ## 1.14.0 - 2026-10-10
57
+
58
+ ### Auto-update and project registry (#37)
59
+
60
+ - **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.
61
+ - **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.
62
+ - **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`.
63
+ - **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.
64
+ - **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`.
65
+ - **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.
66
+ - **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.
67
+ - **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.
68
+ - **Release:** `publish.yml` publishes with `npm publish --access public --provenance` through OIDC (`id-token: write`), no long-lived token.
69
+ - **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`).
70
+
71
+ ### Slim skill adoption (#36)
72
+
73
+ - **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`).
74
+ - **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.
75
+ - **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.
76
+ - **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.
77
+ - All adopted text was written fresh for AEL; credits are in `THIRD_PARTY_NOTICES.md`.
78
+ - 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`.
79
+
80
+ ### P3 — one skill source, slim SKILL.md, on-demand references, metrics (#35)
81
+
82
+ - **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.
83
+ - **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.
84
+ - **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).
85
+ - **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.
86
+ - **Changed:** Stage 0 no longer calls `status` separately, because `run --json` reports host-skill freshness. T0 skips the `tdd-policy` read.
87
+ - **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.
88
+
89
+ ### P2 — combined stage commands to cut agent round-trips (#34)
90
+
91
+ - **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.
92
+ - **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.
93
+ - **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`.
94
+ - **Added:** `goal freeze --latest --by <name>`: the CLI resolves the newest draft revision and hash.
95
+ - **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`.
96
+ - The long command forms still work, and the tests show both paths produce identical gate history, artifacts, and workflow node states.
97
+
98
+ ### P1 — automatic task tiers with a deterministic review gate (#33)
99
+
100
+ - **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.
101
+ - **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/`).
102
+ - **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.
103
+ - **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.
104
+ - **Changed:** The DOT blast-radius grill applies to business-logic changes, not to every DOT task.
105
+ - **Added:** Four evaluation cases (21–24) for the tier paths. The catalog is now 24 cases.
106
+
107
+ ### P0 — slim context and round-trips without weakening gates (#26)
108
+
109
+ - **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.
110
+ - **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.
111
+ - **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.
112
+ - **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.
113
+ - **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.
114
+ - **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.
115
+ - **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.
116
+ - **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,39 @@ 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
+
92
+ Projects with an unfinished run are skipped until that run ends. If a run was simply left behind, close it (the run is kept, marked `CANCELLED`, and `current.json` is released):
93
+
94
+ ```bash
95
+ npx ai-engineering-loop run --abandon --reason "left behind after delivery" --by ega # asks to confirm; add --yes to skip
96
+ npx ai-engineering-loop run --abandon --run <run-id> --reason "superseded" --by ega --yes # a non-current run
97
+ ```
98
+
99
+ `status`, `state`, and `projects list` show this hint when an active run has not moved for 7 days. UNATTENDED runs need `--yes` from a human.
100
+
68
101
  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
102
 
70
103
  ## Meet Workflow Studio
@@ -133,12 +166,64 @@ Under the hood, these moments use eight evidence-backed stages. The rigor is the
133
166
 
134
167
  AI Engineering Loop is designed to work with the tools developers already use:
135
168
 
136
- - **Claude Code**
137
- - **Grok CLI**
138
- - **Gemini / Antigravity**
139
- - Other agent hosts that can read project instructions and run local commands
169
+ <!-- hosts-table:start (generated from lib/hosts/registry.js; run npm run build:hosts-table) -->
170
+ | Host | id | Skill folder | Reviewer agents | Detected by |
171
+ |---|---|---|---|---|
172
+ | Claude Code | `claude` | `~/.claude/skills` | `~/.claude/agents` | `~/.claude`, `claude` |
173
+ | Codex CLI | `codex` | `~/.agents/skills` (shared) | `~/.codex/agents` | `~/.codex`, `codex` |
174
+ | Gemini CLI | `gemini` | `~/.agents/skills` (shared) | `~/.gemini/agents` | `~/.gemini`, `gemini` |
175
+ | Antigravity (IDE / 2.0) | `antigravity` | `~/.gemini/config/skills` | `~/.gemini/config/agents` | `~/.gemini/antigravity`, `antigravity` |
176
+ | Antigravity CLI (agy) | `antigravity-cli` | `~/.gemini/antigravity-cli/skills` | `~/.gemini/config/agents` | `~/.gemini/antigravity-cli`, `agy` |
177
+ | Grok CLI | `grok` | `~/.agents/skills` (shared) | `~/.grok/agents` | `~/.grok`, `grok` |
178
+ | Cursor (editor + CLI) | `cursor` | `~/.agents/skills` (shared) | `~/.cursor/agents` | `~/.cursor`, `cursor-agent`, `cursor` |
179
+ | GitHub Copilot (CLI / VS Code) | `copilot` | `~/.agents/skills` (shared) | `~/.copilot/agents` | `~/.copilot`, `copilot` |
180
+ | OpenCode | `opencode` | `~/.agents/skills` (shared) | `~/.config/opencode/agents` | `~/.config/opencode`, `opencode` |
181
+ | Windsurf / Devin Desktop | `windsurf` | `~/.agents/skills` (shared) | none (in-session review) | `~/.codeium/windsurf`, `~/.config/devin` |
182
+ | Amp | `amp` | `~/.agents/skills` (shared) | none (in-session review) | `~/.config/amp`, `amp` |
183
+ | Factory Droid | `factory` | `~/.agents/skills` (shared) | `~/.factory/droids` | `~/.factory`, `droid` |
184
+ | Augment (Auggie) | `augment` | `~/.agents/skills` (shared) | `~/.augment/agents` | `~/.augment`, `auggie` |
185
+ | Zed | `zed` | `~/.agents/skills` (shared) | none (in-session review) | `~/.config/zed`, `~/Library/Application Support/Zed`, `zed` |
186
+ | Goose | `goose` | `~/.agents/skills` (shared) | none (in-session review) | `~/.config/goose`, `goose` |
187
+ | Cline | `cline` | `~/.cline/skills` | none (in-session review) | `~/.cline`, `cline` |
188
+ | Roo Code | `roo` | `~/.agents/skills` (shared) | none (in-session review) | `~/.roo` |
189
+ | Kiro (IDE + CLI) | `kiro` | `~/.kiro/skills` | `~/.kiro/agents` | `~/.kiro`, `kiro-cli`, `kiro` |
190
+ | Qwen Code | `qwen` | `~/.qwen/skills` | `~/.qwen/agents` | `~/.qwen`, `qwen` |
191
+ | JetBrains Junie | `junie` | `~/.agents/skills` (shared) | `~/.junie/agents` | `~/.junie`, `junie` |
192
+
193
+ Not supported (no native skills): Aider, Continue.
194
+ <!-- hosts-table:end -->
195
+
196
+ Every host gets the **same** `ai-engineering-loop` skill (byte-identical, so an agent that scans several skill folders never sees two different versions). The few host-specific spawn rules live in its `references/loop-hosts.md`. Each host follows the same Goal, verification, review, and approval rules.
197
+
198
+ Install once, then let AEL find your agents:
199
+
200
+ ```bash
201
+ npm i -g ai-engineering-loop
202
+ ai-engineering-loop setup # detects agents (config folder or binary on PATH, never executed), asks, installs
203
+ ai-engineering-loop hosts list # what is detected / enabled, and where each host reads skills
204
+ ai-engineering-loop hosts doctor # per host: copies of the skill it sees, identical or not, files to sync
205
+ ai-engineering-loop hosts enable cursor copilot
206
+ ai-engineering-loop hosts disable codex # removes the files AEL wrote there (edited files are kept)
207
+ ```
208
+
209
+ There is no `postinstall` hook: npm 7+ hides its output, pnpm 10 and Bun block it, and `--ignore-scripts` skips it. Instead the first interactive command suggests `setup` (at most once a day; silence with `AEL_NO_SETUP_HINT=1`). `setup` without a terminal only prints the plan unless you pass `--yes`. Until you run `setup`, `sync-hosts` keeps the old behaviour: it writes only to hosts whose config folder already exists.
210
+
211
+ Agents you install later are noticed by `status` and the background `update auto` (stat only, cheap). With `auto` (the answer `setup` suggests when it asks; just press Enter), a global install enables and syncs them on its own; with `manual` (the default for `setup --yes` and any non-interactive run) you get one short notice per new agent, at most once a day. Nothing is written or shown in CI, in `--json` output, or with `AEL_NO_AUTO_UPDATE=1`.
212
+
213
+ `sync-hosts` installs the **core** pack by default: the `ai-engineering-loop` skill, Devil's Advocate and Judge agents, and the small helper skills the loop itself uses. Optional packs stay out of every session's skill index until you ask for them:
214
+
215
+ ```bash
216
+ npx ai-engineering-loop sync-hosts --pack backend # framework-agnostic backend best practices
217
+ npx ai-engineering-loop sync-hosts --pack backend,design # plus Emil Kowalski's MIT-licensed design/animation skills
218
+ npx ai-engineering-loop sync-hosts --pack quality # ael-code-simplifier + ael-receiving-code-review (opt-in)
219
+ npx ai-engineering-loop sync-hosts --pack core --prune # drop unmodified optional-pack files again
220
+ ```
221
+
222
+ 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.
223
+
224
+ 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.
140
225
 
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. `sync-hosts` also installs the `backend-development` skill for Claude, Grok, Gemini, and Codex-compatible `.agents/skills` hosts: a framework-agnostic backend best-practice pack with deeper references for API design, query/database work, and security reviews. It also vendors Emil Kowalski’s MIT-licensed design and animation skills so local agents can review motion, interaction taste, Apple-style interface principles, UI library choices, Swift, and React Native/Expo animation work without requiring a separate skills install.
226
+ 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
227
 
143
228
  ## Create workflows that fit your team
144
229
 
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
- # Includes ai-engineering-loop, backend-development, and vendored design/animation skills
51
- # for Claude, Grok, Gemini, and Codex-compatible .agents skills.
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
  ---
@@ -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.
@@ -60,7 +60,7 @@ On a DOT repo (`adapter_type: dot`), **run `ai-engineering-loop`**, not the old
60
60
  | **`ai-engineering-loop`** | Engineering OS (Stages 0-7). Use this for DOT bugfix/feature/refactor. |
61
61
  | **`dot-dev-workflow`** | Stage 8 delivery only after Judge PASS. Not a parallel engineering loop. |
62
62
  | **`dot-dev-skill-router`** | Routes commit-bound DOT work to `ai-engineering-loop`, then Stage 8. |
63
- | **`task-impact-inquiry`** | Business blast radius (lifecycle sketch, four pillars, ASCII picture). Canonical: `adapters/dot/skills/task-impact-inquiry/`. Host copies: `~/.claude/skills/`, `~/.grok/skills/`, `~/.gemini/config/skills/`. Fills Stage 1 grill; impact-only stops after the matrix. Not a parallel OS. |
63
+ | **`task-impact-inquiry`** | Business blast radius (lifecycle sketch, four pillars, ASCII picture). Canonical: `adapters/dot/skills/task-impact-inquiry/`. Host copies: `~/.claude/skills/`, `~/.agents/skills/` (Codex, Gemini CLI, Grok, and other shared-folder hosts), `~/.gemini/config/skills/` (Antigravity). Fills Stage 1 grill; impact-only stops after the matrix. Not a parallel OS. |
64
64
  | **`backend-development`** | Framework-agnostic backend guidelines (clean naming, database queries, security, error handling). |
65
65
  | **`backend-safety-guardrails`** | 6 architectural backend safety invariants (queue bypass, BigInt, status recalculation loops). |
66
66
  | **`devils-advocate`** | Legacy DOT pre-commit skill. On AEL, Stages 6-7 are package Devil's Advocate + Judge. Do not re-run this skill after Judge PASS. |
@@ -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 | `brainstorming` → `product-contract-analysis` → then `ai-engineering-loop` if it will be built |
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` → `dot-openapi-contract` → `dot-verification` |
32
- | DOT backend behavior/API regression coverage | `ai-engineering-loop` → `dot-api-test` → `dot-verification` |
33
- | Backend architecture, clean code, naming, or query optimization | `ai-engineering-loop` → `backend-development` (during Maker) → `dot-verification` |
34
- | Backend action, queue, worker, or entity status recalculation | `ai-engineering-loop` → `backend-development` + `backend-safety-guardrails` (during Maker) → `dot-verification` |
35
- | Local web app repro, browser smoke, or UI regression | `webapp-testing` → `dot-verification` |
36
- | Plan execution with review checkpoints | `executing-plans` → `ai-engineering-loop` |
37
- | Pre-merge review after AEL already ran | AEL Judge verdict is the gate. Do not re-run skill `devils-advocate` unless Judge was skipped |
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`; use `brainstorming` when the next outcome must be an approved plan |
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
+ ```
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: ael-code-simplifier
3
+ description: Use when the user explicitly asks to simplify, tidy, or de-slop a finished diff without changing behavior. Does NOT review for defects (use the Devil's Advocate), refactor architecture, rename public APIs, or run automatically after edits.
4
+ ---
5
+
6
+ # AEL Code Simplifier
7
+
8
+ Rewrite *how* changed code reads; never *what* it does. Behavior, contracts, status codes, queries, and public names stay identical.
9
+
10
+ Optional in the AI Engineering Loop: only at T1/T2, only on request, after Maker and **before** `verify`, so verification and the Devil's Advocate see the final diff.
11
+
12
+ ## Scope
13
+
14
+ 1. Only files in `git diff` (staged and unstaged) or paths the user named. Do not open neighbors "while you are there".
15
+ 2. Follow the target repository's own conventions (`.ai-engineering-loop/conventions.md`, `AGENTS.md`, `CLAUDE.md`), not personal taste.
16
+ 3. Keep architectural layers separate. Never merge or skip a layer.
17
+
18
+ ## Allowed changes
19
+
20
+ - Remove dead code, unused imports, unreachable branches, and debug output added by this diff.
21
+ - Flatten needless nesting with early returns; replace clever one-liners with plain code.
22
+ - Collapse duplicated logic introduced by this diff into one local helper.
23
+ - Rename local variables whose names hide intent.
24
+ - Delete comments that restate the code; keep comments that explain *why*.
25
+ - Replace hand-rolled code with an existing helper the repo already uses.
26
+
27
+ ## Not allowed
28
+
29
+ - Behavior or output changes, including error messages that callers or tests match.
30
+ - File moves, public API renames, new dependencies, new abstractions or frameworks.
31
+ - Changing or deleting tests to make them pass; new tests are Maker work.
32
+ - Formatting churn outside changed hunks.
33
+
34
+ If the code cannot get simpler without changing behavior, stop and say so; that is a separate task.
35
+
36
+ ## Procedure
37
+
38
+ 1. List the changed files and the hunks you will touch.
39
+ 2. Apply the smallest edits that make each hunk easier to read.
40
+ 3. Run the repository's fast checks (unit tests, typecheck, lint) and show the output. Any new failure means revert that edit.
41
+ 4. Report: files touched, what was simplified, and confirmation that behavior is unchanged with command evidence.
42
+
43
+ Inside a loop run, the simplified diff still goes through `verify`, claimed-vs-reality, and review; this skill never replaces a gate.
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: ael-receiving-code-review
3
+ description: Use when acting on review feedback (Devil's Advocate findings during ITERATE, or human MR/PR comments) before changing code. Does NOT perform a review (use the Devil's Advocate) or decide PASS/ITERATE (use the Judge).
4
+ ---
5
+
6
+ # AEL Receiving Code Review
7
+
8
+ Feedback is a claim to check, not an order to obey. Verify each item against the code before you change anything.
9
+
10
+ ## For every finding or comment
11
+
12
+ 1. **Restate** it in one line with the exact file and line it refers to. If you cannot locate it, ask for the location; do not guess.
13
+ 2. **Verify** it against the current code, the frozen Goal Contract, and the command evidence:
14
+ - reproduce it (a failing test, a command, or a concrete input), or
15
+ - show why it does not apply (the code path, a passing test, or the AC row that excludes it).
16
+ 3. **Classify** it as one of:
17
+ - `valid`: fix it test-first (red test, then fix).
18
+ - `invalid`: decline with evidence.
19
+ - `out-of-scope`: valid but outside the frozen Goal; record it in the handoff or as a follow-up, and do not widen the diff.
20
+ - `unclear`: ask one precise question.
21
+ 4. **Respond** with that classification and evidence. No performative agreement ("Great catch!") and no silent fixes.
22
+
23
+ ## Rules
24
+
25
+ - Do not apply a suggestion you have not verified, even from a senior reviewer or a stronger model.
26
+ - Do not argue from preference. Disagreement needs evidence: code, tests, specs, or measurements.
27
+ - Fix one finding at a time and re-run the relevant check after each, so a regression is attributable.
28
+ - A finding that contradicts the frozen Goal Contract goes back to the human; never edit the contract yourself.
29
+ - In the AI Engineering Loop, every fixed finding is re-verified with `verify` and reviewed again by a **new** Devil's Advocate. Iteration 3 is the ceiling.
30
+
31
+ ## Reply template (MR/PR)
32
+
33
+ ```
34
+ F-<id> <valid|invalid|out-of-scope|unclear>: <one-line reason>
35
+ Evidence: <test name / command + exit code / file:line>
36
+ Change: <commit or "none">
37
+ ```