ai-engineering-loop 2.3.0 → 2.5.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 (61) hide show
  1. package/.agents/skills/{ai-engineering-loop → ael}/SKILL.md +2 -2
  2. package/.agents/skills/{ai-engineering-loop → ael}/references/loop-risky.md +1 -0
  3. package/CHANGELOG.md +30 -0
  4. package/README.md +5 -4
  5. package/README.npm.md +6 -6
  6. package/THIRD_PARTY_NOTICES.md +11 -0
  7. package/adapters/dot/README.md +3 -3
  8. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +13 -13
  9. package/adapters/dot/skills/dot-dev-workflow/SKILL.md +3 -3
  10. package/adapters/generate-adapter/SKILL.md +1 -1
  11. package/adapters/generate-workflow/SKILL.md +1 -1
  12. package/adapters/quality/skills/task-impact-inquiry/SKILL.md +2 -2
  13. package/adapters/spec/LICENSE +202 -0
  14. package/adapters/spec/NOTICE-AEL.md +26 -0
  15. package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
  16. package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
  17. package/adapters/spec/agents/ael-spec-design.md +65 -0
  18. package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
  19. package/adapters/spec/agents/ael-spec-structural.md +67 -0
  20. package/adapters/spec/agents/ael-spec-style.md +68 -0
  21. package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
  22. package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
  23. package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
  24. package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
  25. package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
  26. package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
  27. package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
  28. package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
  29. package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
  30. package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
  31. package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
  32. package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
  33. package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
  34. package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
  35. package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
  36. package/agents/instruction-only/AGENTS.md +1 -1
  37. package/bin/ai-engineering-loop.js +47 -7
  38. package/core/grill-policy.md +1 -1
  39. package/core/project-initialization.md +2 -2
  40. package/core/spec-pack.md +47 -0
  41. package/lib/bench.js +12 -12
  42. package/lib/design-ref.js +178 -0
  43. package/lib/docs.js +1 -1
  44. package/lib/doctor.js +2 -2
  45. package/lib/gates.js +1 -0
  46. package/lib/goal-runtime.js +5 -0
  47. package/lib/host-skill-build.js +1 -1
  48. package/lib/hosts/doctor.js +21 -3
  49. package/lib/impact-map.js +29 -1
  50. package/lib/receipt.js +12 -1
  51. package/lib/smart-context.js +10 -1
  52. package/lib/sync-hosts.js +28 -5
  53. package/package.json +3 -2
  54. package/schemas/goal-contract.schema.json +87 -11
  55. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-commands.md +0 -0
  56. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-deliver.md +0 -0
  57. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-goal.md +0 -0
  58. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-hosts.md +0 -0
  59. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-maker.md +0 -0
  60. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-review.md +0 -0
  61. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-verify.md +0 -0
@@ -1,6 +1,6 @@
1
1
  ---
2
- name: ai-engineering-loop
3
- description: Use when the user runs /ai-engineering-loop, says "run the engineering loop" or "devil's advocate review", asks to init or refresh living project context, or wants the Maker / Devil's Advocate / Judge engineering loop.
2
+ name: ael
3
+ description: Use when the user runs /ael, says "run the engineering loop" or "devil's advocate review", asks to init or refresh living project context, or wants the Maker / Devil's Advocate / Judge engineering loop.
4
4
  ---
5
5
  <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
6
6
 
@@ -7,3 +7,4 @@ Applies to HIGH_RISK_PATH changes (auth, payments, migrations, secrets, infra),
7
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
8
  - UNATTENDED: sandbox worktree only, and `budget pause` is the kill switch (`docs runtime-safety`).
9
9
  - The tier never falls back once raised.
10
+ - New feature or architecture: suggest a reviewed design first (`docs spec-pack`), then `goal draft --from-design <doc>`.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,36 @@ All notable changes to this project are documented here. Versions follow [Semant
6
6
 
7
7
  _No changes yet._
8
8
 
9
+ ## 2.5.0 - 2026-11-02
10
+
11
+ - **Changed:** the core host skill is now `ael` (#107), so the slash command is `/ael` on every host (`~/.claude/skills/ael`, `~/.agents/skills/ael`, and each host's own folder). `sync-hosts` and `update` remove the old `ai-engineering-loop` skill files AEL wrote, so the command no longer appears twice; files you edited or added there are kept, and `hosts doctor` reports the leftover folder. Skill sources moved to `skill-src/ael/`.
12
+ - **Added:** `ael` CLI alias next to `ai-engineering-loop` (`ael --version`). The npm package name and the project folder `.ai-engineering-loop/` are unchanged.
13
+
14
+ ## 2.4.0 - 2026-11-02
15
+
16
+ ### Spec pack: design before code (EGM fork)
17
+
18
+ - **Added:** opt-in `spec` host pack (`sync-hosts --pack spec`, #96): six host-neutral skills, `ael-spec-brainstorm`, `ael-spec-draft`, `ael-spec-review`, `ael-spec-review-loop`, `ael-spec-resolve` and `ael-spec-drift`, derived from Google's Elephant-Goldfish Model through the fork [egagofur/elephant-goldfish-model](https://github.com/egagofur/elephant-goldfish-model) (Apache-2.0). Reviewer personas and document standards are `ael-spec-*` docs (`docs ael-spec-zoom-out`). On a host without a subagent tool the reviews run one at a time in-session, labelled `CONTEXT_ISOLATION_ONLY`, instead of stopping. Core and T0/T1 runs are unchanged.
19
+ - **Internal:** `vendor/egm/` holds the pinned fork files (not shipped); `scripts/sync-spec-pack.js` regenerates `adapters/spec/`, `--check` fails on stale output, and `--pull [ref]` refreshes the vendor copy.
20
+
21
+ ### Design documents as Goal input
22
+
23
+ - **Added:** `goal draft --from-design <doc.md>` (#97) prefills a Goal draft from a design document: objective from the title and first goal, one acceptance row per Test Plan item (or per goal), `outOfScope` from Non-Goals, and `designRef { path, sha256, targetFiles }` from the Target Scope file paths. With `--file`, the given contract keeps its rows and only gains `designRef`. Missing, outside-the-repo, symlinked, non-Markdown or >256 KB documents are refused.
24
+ - **Added:** `goal freeze` refuses rows that still contain `<fill: …>` placeholders (`GOAL_PLACEHOLDERS`); `goal show` reports `design.designChanged` when the document changed after drafting. Goals without `designRef` behave as before.
25
+
26
+ ### Design drift
27
+
28
+ - **Added:** when the frozen Goal has `designRef` (#98), `impact drift` (run with `verify`) also records `design { path, docChanged, planned, unplanned[], untouched[] }` in `impact-drift.json`: changed files outside the design's plan and planned files nobody touched. The review pack shows it as two short lines for the Devil's Advocate and `receipt.json` carries the counts under `impact.design`. It is informational: no ledger finding, no gate failure. Runs without `designRef` are unchanged.
29
+
30
+ ### Spec pack hint and doctor status
31
+
32
+ - **Added:** a new T2 Run prints one `specHint` (`run --json`) suggesting `ael-spec-brainstorm -> ael-spec-draft -> ael-spec-review` and `goal draft --from-design` (#99), plus the install command when the `spec` pack is missing. T0/T1 and resumed Runs print nothing new.
33
+ - **Added:** `hosts doctor` rows carry `spec { installed, reviewMode }` (`FRESH_SUBAGENT`, or `CONTEXT_ISOLATION_ONLY` on instruction-only hosts) and the text report names the install command when no host has the pack. It never changes `ok`.
34
+
35
+ ### Spec pack guide
36
+
37
+ - **Docs:** `npx ai-engineering-loop docs spec-pack` (#100): when to use the `spec` pack and when not, the flow from `ael-spec-brainstorm` to `goal draft --from-design` and `ael-spec-drift`, the host fallback, and how to pull upstream EGM updates. README and the T2 reference (`loop-risky`) point at it; `THIRD_PARTY_NOTICES.md` lists every shipped EGM-derived file.
38
+
9
39
  ## 2.3.0 - 2026-10-21
10
40
 
11
41
  ### Security
package/README.md CHANGED
@@ -75,7 +75,7 @@ npx ai-engineering-loop deliver --run <run-id> --destination pr --summary "..."
75
75
 
76
76
  `deliver` refuses without `--approve` in ASSISTED mode; pass it only after a human approved delivery.
77
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.
78
+ Contributors: the host `ael` skills are generated. Edit `skill-src/ael/`, 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
79
 
80
80
  ### Staying up to date
81
81
 
@@ -183,12 +183,12 @@ Guardrails: **enforced** = `npx ai-engineering-loop hooks install` adds native p
183
183
  Not supported (no native skills): Aider, Continue.
184
184
  <!-- hosts-table:end -->
185
185
 
186
- 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.
186
+ Every host gets the **same** `ael` skill, invoked as `/ael` (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`. Earlier releases named the skill `ai-engineering-loop`; `sync-hosts` removes that old folder when AEL wrote it and `hosts doctor` flags any copy it had to keep. Each host follows the same Goal, verification, review, and approval rules.
187
187
 
188
188
  Install once, then let AEL find your agents:
189
189
 
190
190
  ```bash
191
- npm i -g ai-engineering-loop
191
+ npm i -g ai-engineering-loop # installs the `ai-engineering-loop` and short `ael` commands
192
192
  ai-engineering-loop setup # detects agents (config folder or binary on PATH, never executed), asks, installs
193
193
  ai-engineering-loop hosts list # what is detected / enabled, and where each host reads skills
194
194
  ai-engineering-loop hosts doctor # per host: copies of the skill it sees, identical or not, files to sync
@@ -200,12 +200,13 @@ There is no `postinstall` hook: npm 7+ hides its output, pnpm 10 and Bun block i
200
200
 
201
201
  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`.
202
202
 
203
- `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:
203
+ `sync-hosts` installs the **core** pack by default: the `ael` 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:
204
204
 
205
205
  ```bash
206
206
  npx ai-engineering-loop sync-hosts --pack backend # framework-agnostic backend best practices
207
207
  npx ai-engineering-loop sync-hosts --pack backend,design # plus Emil Kowalski's MIT-licensed design/animation skills
208
208
  npx ai-engineering-loop sync-hosts --pack quality # ael-code-simplifier + ael-receiving-code-review (opt-in)
209
+ npx ai-engineering-loop sync-hosts --pack spec # ael-spec-* design-doc skills from the EGM fork (docs spec-pack)
209
210
  npx ai-engineering-loop sync-hosts --pack core --prune # drop unmodified optional-pack files again
210
211
  ```
211
212
 
package/README.npm.md CHANGED
@@ -72,11 +72,11 @@ npx ai-engineering-loop docs grill-policy --section "When to grill"
72
72
 
73
73
  ## Grok CLI
74
74
 
75
- Inside a Grok TUI session, `/ai-engineering-loop` uses repo-local `.grok/agents/` types. Devil's Advocate and Judge spawn as sibling children (`capability_mode: execute`, no `resume_from`). Do not use `caveman:cavecrew-reviewer` as the loop reviewer.
75
+ Inside a Grok TUI session, `/ael` uses repo-local `.grok/agents/` types. Devil's Advocate and Judge spawn as sibling children (`capability_mode: execute`, no `resume_from`). Do not use `caveman:cavecrew-reviewer` as the loop reviewer.
76
76
 
77
77
  ## Claude Code
78
78
 
79
- Inside Claude Code, `/ai-engineering-loop` uses `.claude/agents/` types via the **Task** tool. Pass only `subagent_type`, `description`, and `prompt`. Do not pass Grok keys (`spawn_subagent`, `capability_mode`, `resume_from`) — extra keys cause Kiro `REQUEST_BODY_INVALID`.
79
+ Inside Claude Code, `/ael` uses `.claude/agents/` types via the **Task** tool. Pass only `subagent_type`, `description`, and `prompt`. Do not pass Grok keys (`spawn_subagent`, `capability_mode`, `resume_from`) — extra keys cause Kiro `REQUEST_BODY_INVALID`.
80
80
 
81
81
  ---
82
82
 
@@ -84,10 +84,10 @@ Inside Claude Code, `/ai-engineering-loop` uses `.claude/agents/` types via the
84
84
 
85
85
  In Antigravity IDE or compatible agentic platforms, invoke the loop directly in chat:
86
86
 
87
- - `/ai-engineering-loop init` — Bootstrap project context only.
88
- - `/ai-engineering-loop status` — Check context health and living freshness.
89
- - `/ai-engineering-loop refresh` — Reconcile drifted context files.
90
- - `/ai-engineering-loop <task>` — Execute the full 8-stage engineering lifecycle.
87
+ - `/ael init` — Bootstrap project context only.
88
+ - `/ael status` — Check context health and living freshness.
89
+ - `/ael refresh` — Reconcile drifted context files.
90
+ - `/ael <task>` — Execute the full 8-stage engineering lifecycle.
91
91
 
92
92
  ---
93
93
 
@@ -9,6 +9,17 @@ AEL vendors design and animation skills from `emilkowalski/skills` so `ai-engine
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
11
 
12
+ ## google/elephant-goldfish-model (Elephant-Goldfish Model, EGM)
13
+
14
+ AEL ships a modified derivative of EGM as the opt-in `spec` host pack (`sync-hosts --pack spec`, issue #96).
15
+
16
+ - Upstream: https://github.com/google/elephant-goldfish-model (Copyright Google LLC; not an officially supported Google product)
17
+ - Fork vendored: https://github.com/egagofur/elephant-goldfish-model at the commit in `vendor/egm/UPSTREAM.json`
18
+ - License: Apache License 2.0, shipped as `adapters/spec/LICENSE`; modifications listed in `adapters/spec/NOTICE-AEL.md`
19
+ - Modifications: skills and personas renamed `egm-*` to `ael-spec-*` (`egm-drift-report` to `ael-spec-drift`), plugin-root and harness-specific references replaced with `ai-engineering-loop docs` lookups and AEL host rules, and a disclosed same-session fallback (`CONTEXT_ISOLATION_ONLY`) where a host has no subagent tool. `egm-bootstrap`, plugin manifests, tests and icons are not shipped.
20
+ - AEL files shipped: `adapters/spec/skills/ael-spec-{brainstorm,draft,review,review-loop,resolve,drift}/SKILL.md`, `adapters/spec/skills/ael-spec-draft/references/design_doc.md`, `adapters/spec/agents/ael-spec-*.md` (8 reviewer personas), `adapters/spec/standards/ael-spec-*.md` (5 document standards and the execution instructions), `adapters/spec/LICENSE` and `adapters/spec/NOTICE-AEL.md`. They are generated by `scripts/sync-spec-pack.js`; every file names the source commit and the skills keep `license: Apache-2.0`.
21
+ - Original AEL text (not derived from EGM): `core/spec-pack.md`, `lib/design-ref.js` (`goal draft --from-design`), design drift in `lib/impact-map.js`, and the spec status in `hosts doctor`.
22
+
12
23
  ## Adopted skill ideas (issue #36)
13
24
 
14
25
  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.
@@ -63,13 +63,13 @@ The DOT adapter is organized into five specification modules:
63
63
 
64
64
  This adapter composes the DOT skill suite. `task-impact-inquiry` is adapter-neutral and ships in `adapters/quality/skills/task-impact-inquiry/`; `sync-hosts` upserts it to every enabled host. On DOT repos it is mandatory in Stage 1. Other DOT skills (router, workflow) still update-if-exists only.
65
65
 
66
- On a DOT repo (`adapter_type: dot`), **run `ai-engineering-loop`**, not the old 9-phase `dot-dev-workflow`, as the engineering OS. Stage 1 grill **includes** `task-impact-inquiry`. Do not run a second interview. After Judge `PASS`, Stage 8 is `dot-dev-workflow` delivery (GitLab, cherry-pick, Coreview, Mattermost). Canonical DOT copies: `adapters/dot/skills/` (`task-impact-inquiry`: `adapters/quality/skills/`). See `core/grill-policy.md`.
66
+ On a DOT repo (`adapter_type: dot`), **run `ael`**, not the old 9-phase `dot-dev-workflow`, as the engineering OS. Stage 1 grill **includes** `task-impact-inquiry`. Do not run a second interview. After Judge `PASS`, Stage 8 is `dot-dev-workflow` delivery (GitLab, cherry-pick, Coreview, Mattermost). Canonical DOT copies: `adapters/dot/skills/` (`task-impact-inquiry`: `adapters/quality/skills/`). See `core/grill-policy.md`.
67
67
 
68
68
  | Skill | Primary Role & Governance |
69
69
  | :--- | :--- |
70
- | **`ai-engineering-loop`** | Engineering OS (Stages 0-7). Use this for DOT bugfix/feature/refactor. |
70
+ | **`ael`** | Engineering OS (Stages 0-7). Use this for DOT bugfix/feature/refactor. |
71
71
  | **`dot-dev-workflow`** | Stage 8 delivery only after Judge PASS. Not a parallel engineering loop. |
72
- | **`dot-dev-skill-router`** | Routes commit-bound DOT work to `ai-engineering-loop`, then Stage 8. |
72
+ | **`dot-dev-skill-router`** | Routes commit-bound DOT work to `ael`, then Stage 8. |
73
73
  | **`task-impact-inquiry`** | Business blast radius (lifecycle sketch, four pillars, ASCII picture). Canonical: `adapters/quality/skills/task-impact-inquiry/` (adapter-neutral, EN + ID triggers). 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. |
74
74
  | **`backend-development`** | Framework-agnostic backend guidelines (clean naming, database queries, security, error handling). |
75
75
  | **`backend-safety-guardrails`** | 6 architectural backend safety invariants (queue bypass, BigInt, status recalculation loops). |
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: dot-dev-skill-router
3
- description: Route DOT tasks. Commit-bound bugfix, feature, or refactor uses ai-engineering-loop for Stages 0-7, then dot-dev-workflow for Stage 8 delivery. Do not use dot-dev-workflow as a parallel engineering OS.
3
+ description: Route DOT tasks. Commit-bound bugfix, feature, or refactor uses ael for Stages 0-7, then dot-dev-workflow for Stage 8 delivery. Do not use dot-dev-workflow as a parallel engineering OS.
4
4
  ---
5
5
 
6
6
  # DOT Development Skill Router
@@ -10,17 +10,17 @@ Pick the smallest relevant skill. Do not load every skill. **AI Engineering Loop
10
10
  ## Core rules
11
11
 
12
12
  1. Read repository instructions and inspect the affected code before choosing a workflow.
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.
13
+ 2. For DOT work that will be committed or opened as an MR, load `ael`. 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
15
  4. Use `ponytail` (optional, if installed) when the smallest correct solution matters.
16
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
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.
19
+ 8. If a named skill is not installed, say so and continue with `ael`; never guess a substitute name.
20
20
 
21
21
  ## Skill sources
22
22
 
23
- - **AEL (this package):** `ai-engineering-loop`, `task-impact-inquiry`, `dot-dev-workflow`, `backend-development`.
23
+ - **AEL (this package):** `ael`, `task-impact-inquiry`, `dot-dev-workflow`, `backend-development`.
24
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
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`.
26
26
 
@@ -28,20 +28,20 @@ Pick the smallest relevant skill. Do not load every skill. **AI Engineering Loop
28
28
 
29
29
  | Task | Load in order |
30
30
  |---|---|
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 |
31
+ | DOT bugfix / feature / refactor that will be committed or opened as MR | `ael` (grill includes `task-impact-inquiry`; DA + Judge before commit) → `dot-dev-workflow` Stage 8 after Judge PASS |
32
32
  | Impact / blast-radius question only (no implementation) | `task-impact-inquiry` |
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 |
33
+ | New feature, product/UI behavior unclear | `ael` Stage 1 grill and Goal Contract; add `product-contract-analysis` (optional, if installed) for product questions. Do not run a separate brainstorming loop |
34
34
  | Legacy FE + BE module documentation | `generate-module-fsd` |
35
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
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
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` |
38
+ | DOT API contract or OpenAPI change | `ael` → `design-openapi-contract` → `verification-before-completion` |
39
+ | DOT database schema (DBML) change | `ael` → `design-dbml-database` → `verification-before-completion` |
40
+ | DOT backend behavior/API regression coverage | `ael` → `generate-api-test` → `verification-before-completion` |
41
+ | Backend architecture, clean code, naming, or query optimization | `ael` → `backend-development` (during Maker) → `verification-before-completion` |
42
+ | Backend action, queue, worker, or entity status recalculation | `ael` → `backend-development` + `backend-safety-guardrails` (optional, if installed) during Maker → `verification-before-completion` |
43
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 |
44
+ | Executing an existing written plan | `ael` (paste the plan as the Goal Contract draft). Do not load `executing-plans` as a second loop |
45
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 |
46
46
  | Code review feedback reception | `receiving-code-review` |
47
47
  | GitLab MR discussions / feedback resolution | `gitlab-mr-feedback` → `receiving-code-review` |
@@ -57,7 +57,7 @@ Pick the smallest relevant skill. Do not load every skill. **AI Engineering Loop
57
57
 
58
58
  ## Avoid
59
59
 
60
- - Do not run `dot-dev-workflow` Phases 1-6 when `ai-engineering-loop` is available.
60
+ - Do not run `dot-dev-workflow` Phases 1-6 when `ael` is available.
61
61
  - Do not chain `task-impact-inquiry` then a full second engineering loop.
62
62
  - Do not invoke `auto-mr-issue` merely because code was committed.
63
63
  - Do not use the full delivery pipeline for a tiny local question unless the user asked to ship.
@@ -1,18 +1,18 @@
1
1
  ---
2
2
  name: dot-dev-workflow
3
- description: DOT Stage 8 delivery after AI Engineering Loop Judge PASS. GitLab issue/MR, one topic-branch MR (extra env cherry-pick only if named this turn), pipeline + Sonar gate, Coreview triage, card to Ready to review, Mattermost. Not a substitute for ai-engineering-loop.
3
+ description: DOT Stage 8 delivery after AI Engineering Loop Judge PASS. GitLab issue/MR, one topic-branch MR (extra env cherry-pick only if named this turn), pipeline + Sonar gate, Coreview triage, card to Ready to review, Mattermost. Not a substitute for ael.
4
4
  ---
5
5
 
6
6
  # DOT Delivery Workflow (Stage 8)
7
7
 
8
8
  This is **not** the engineering OS. On DOT repositories:
9
9
 
10
- 1. Run **`ai-engineering-loop`** for Stages 0-7 (grill, RCA, Maker, verification, Devil's Advocate, Judge).
10
+ 1. Run **`ael`** for Stages 0-7 (grill, RCA, Maker, verification, Devil's Advocate, Judge).
11
11
  2. Run **this skill only after Judge `PASS`** (or the user explicitly asked to ship).
12
12
  3. Stage 1 grill already includes `task-impact-inquiry`. Do not interview again.
13
13
  4. Stages 6-7 are AEL DA + Judge. Do not re-run skill `devils-advocate` as a second pre-commit OS.
14
14
 
15
- If `ai-engineering-loop` is missing on this host, say so and stop. Do not silently run the old 9-phase loop.
15
+ If `ael` is missing on this host, say so and stop. Do not silently run the old 9-phase loop.
16
16
 
17
17
  ## Mapping (old phases → AEL)
18
18
 
@@ -112,7 +112,7 @@ Generate adapter
112
112
  Detected: <remote> <ci>
113
113
  Questions: Q1..Q5 with Recommended
114
114
  Wrote: .ai-engineering-loop/adapter.md (type=<type>)
115
- Next: /ai-engineering-loop for product work. Stage 8 uses this file.
115
+ Next: /ael for product work. Stage 8 uses this file.
116
116
  ```
117
117
 
118
118
  ## Forbidden
@@ -126,7 +126,7 @@ Existing: <workflow yes/no> <lessons yes/no>
126
126
  Questions: Q1..Q6 with Recommended
127
127
  Wrote: .ai-engineering-loop/workflow.md
128
128
  Lessons: .ai-engineering-loop/lessons.md (created or left)
129
- Next: /ai-engineering-loop for product work. Stage 0 reads these files.
129
+ Next: /ael for product work. Stage 0 reads these files.
130
130
  ```
131
131
 
132
132
  ## Forbidden
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: task-impact-inquiry
3
- description: Map business blast radius before code. Use for impact, side effects, sibling data, approval, queues, or when a new developer must learn the current flow. Triggers (EN/ID): check the impact, impact analysis, blast radius, side effects, cek impactnya, analisa pengaruh. Not a substitute for ai-engineering-loop.
3
+ description: Map business blast radius before code. Use for impact, side effects, sibling data, approval, queues, or when a new developer must learn the current flow. Triggers (EN/ID): check the impact, impact analysis, blast radius, side effects, cek impactnya, analisa pengaruh. Not a substitute for ael.
4
4
  ---
5
5
 
6
6
  # Task Impact Inquiry
@@ -9,7 +9,7 @@ Map the **current business flow** and the **blast radius** of a change before an
9
9
 
10
10
  This skill fills AI Engineering Loop Stage 1 grill. It is not a parallel engineering OS.
11
11
 
12
- If Stage 1 grill already produced this matrix and the user confirmed it, stop. Do not interview again. On commit-bound work, continue in `ai-engineering-loop` (freeze the Goal Contract, then Maker). Do not start a second engineering loop from your team's own workflow skill.
12
+ If Stage 1 grill already produced this matrix and the user confirmed it, stop. Do not interview again. On commit-bound work, continue in `ael` (freeze the Goal Contract, then Maker). Do not start a second engineering loop from your team's own workflow skill.
13
13
 
14
14
  Works on any adapter. On `adapter_type: dot` it is mandatory in Stage 1; the DOT-only rules live in `adapters/dot/README.md`.
15
15
 
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
@@ -0,0 +1,26 @@
1
+ # Notice of modifications (egagofur fork)
2
+
3
+ This repository is a fork of [google/elephant-goldfish-model](https://github.com/google/elephant-goldfish-model)
4
+ (EGM), Copyright Google LLC, licensed under the Apache License 2.0 (see `LICENSE`).
5
+ EGM is not an officially supported Google product, and this fork is not endorsed by Google.
6
+
7
+ `main` tracks upstream unchanged except for this file. Pull upstream updates with
8
+ `gh repo sync egagofur/elephant-goldfish-model`.
9
+
10
+ ## Derivative shipped by ai-engineering-loop
11
+
12
+ [ai-engineering-loop](https://github.com/egagofur/ai-engineering-loop) (AEL) vendors a pinned
13
+ commit of this fork under `vendor/egm/` and generates a modified derivative, the optional
14
+ `spec` host pack, with `scripts/sync-spec-pack.js`. The changes made to that derivative:
15
+
16
+ - Skills and reviewer personas are renamed from `egm-*` to `ael-spec-*`
17
+ (`egm-drift-report` becomes `ael-spec-drift`) so they cannot collide with an installed EGM plugin.
18
+ - Plugin-root and harness-specific references (`${CLAUDE_PLUGIN_ROOT}`, `docs/claude.md`,
19
+ `docs/codex.md`, `docs/harnesses.md`, `agents/*.md`, `resources/**`) are replaced with
20
+ `npx ai-engineering-loop docs <name>` lookups and AEL's per-host subagent rules, so the
21
+ pack works on every AEL host (Grok CLI, Cursor, Claude Code, Codex, Antigravity, and others).
22
+ - Where a host has no fresh-context subagent tool, the reviews run sequentially in the same
23
+ session and are labelled `CONTEXT_ISOLATION_ONLY` instead of stopping.
24
+ - `egm-bootstrap`, plugin manifests, the website, tests, and icons are not shipped.
25
+
26
+ Every generated file keeps its `license: Apache-2.0` line and names the source commit.
@@ -0,0 +1,71 @@
1
+ ---
2
+ name: ael-spec-codebase-details
3
+ description: Pedantic Technical Quality Auditor verifying that documentation accurately and exhaustively matches actual codebase implementation and existing library reuse opportunities.
4
+ license: Apache-2.0
5
+ ---
6
+
7
+ <!-- Generated by scripts/sync-spec-pack.js from egagofur/elephant-goldfish-model@228457d1e0b6. Derived from the Elephant-Goldfish Model, Copyright Google LLC, Apache-2.0; modified: renamed to ael-spec-*, host-neutral references. Do not edit; run the script. -->
8
+
9
+ # Core Mandates (Universal Goldfish Context)
10
+
11
+ You are a specialized Goldfish subagent operating within the Elephant-Goldfish Model. You have been delegated a specific task by the root agent (the Elephant).
12
+
13
+ 1. **Strict Read-Only Protocol**: You are a strictly read-only agent. You have NO tools to modify the workspace, write files, or compile code. Do not attempt to fix or refactor any code.
14
+ 2. **Stateless Mindset (Goldfish Isolation)**: You evaluate plans with zero conversational history or external assumptions. You must read the document as a naive team member or fresh reader who has just joined the project.
15
+ 3. **No Chitchat**: Avoid conversational filler. Focus exclusively on technical rationale and findings. Do not narrate your tool usage.
16
+
17
+ ---
18
+
19
+ # Role
20
+
21
+ You are **Codebase Details Goldfish**.
22
+ You are a pedantic, detail-oriented Technical Quality Auditor. You behave as a strict compliance officer who does not accept hand-waving explanations, unstated assumptions, or missing details. Your goal is to ensure the documentation perfectly and exhaustively matches the actual codebase implementation.
23
+
24
+ ---
25
+
26
+ # Instructions
27
+
28
+ Inspect the `Mode` parameter specified by the caller:
29
+
30
+ ### IF Mode: BRAINSTORM (Upstream Concept Ideation)
31
+ Evaluate the raw feature concept for observability, telemetry, and operational debuggability:
32
+ 1. **Telemetry & Tracing**: Are key operations traceable in distributed tracing? Are telemetry metrics actionable?
33
+ 2. **Operational Debuggability**: How will oncall engineers triage a production incident at 3 AM?
34
+ 3. Report observability requirements and telemetry gaps back to the orchestrator.
35
+
36
+ ### IF Mode: REVIEW (Document Audit)
37
+ Audit the target document file and line range specified by the caller:
38
+
39
+ 1. **Map the Scope**: Parse the active target scope to identify which source files (from the provided codebase context) it describes.
40
+ 2. **Verify Code vs. Doc**: For each mapped source file, read the code and verify that all key implementation details (including public APIs, core algorithms, configuration flags, and critical logic paths) are documented in the target scope.
41
+ 3. **Audit against the Standard**: Compare the depth and accuracy of the descriptions in the target scope against the requirements defined in the Target Standard. Flag any areas that fall short of the standard's criteria.
42
+ 4. **Filter Test Files**: Ignore simple unit test files, but strictly audit test infrastructure (mocks, helpers, base classes).
43
+
44
+ ### Audit Vectors:
45
+ * **Missing Logic Detail**: Functions, validation rules, or algorithms present in the code that are omitted from the target scope.
46
+ * **Unstated Assumptions**: Hardcoded constants, environment variables, or system dependencies in the code that are not documented.
47
+ * **Undocumented Edge Cases**: Catch blocks, null checks, retry limits, or failure modes in the code that are missing in the target scope.
48
+ * **Test Infrastructure Neglect**: Ensuring that shared mocks and test helpers are documented with the same level of detail as production code.
49
+ * **Contradicts the Code**: The document describes current behavior that the source does not have. Report as 🔴 Blocker: every later reader inherits the false statement.
50
+ * **Non-Existent References**: Files, functions, endpoints, or tables that the document cites as current state but that do not exist. Check every one.
51
+
52
+ **Proposed files are not findings.** An implementation plan lists files it will create. Their absence is not a defect. Apply Non-Existent References only to items the document says exist now. If the plan lists files without marking each `Create`, `Modify`, or `Delete`, report that once as 🟡 Major, and do not flag each path.
53
+
54
+ ---
55
+
56
+ # Output Format
57
+
58
+ Report your findings back to the orchestrator in plain, natural language.
59
+
60
+ #### IF Mode: REVIEW
61
+ For each finding, include:
62
+ 1. **Severity**: [Blocker | Major | Nit]
63
+ 2. **Affected Scope**: Referenced filepath, API, or line numbers.
64
+ 3. **Discrepancy Description & Rationale**: Explanation of the codebase drift or existing library reuse opportunity discovered via code search.
65
+
66
+ #### IF Mode: BRAINSTORM
67
+ For each telemetry or debuggability gap, include:
68
+ 1. **Severity**: [Blocker | Major | Nit]
69
+ 2. **Dimension**: Observability & Operational SRE Debuggability
70
+ 3. **Operational Risk**: Missing trace context, unmonitored metric, or triage friction.
71
+ 4. **Mitigation Requirement**: Mandatory telemetry requirement for the Concepts Brief/PRD.