ai-engineering-loop 1.0.16 → 1.0.17

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.
@@ -15,4 +15,4 @@ If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as si
15
15
 
16
16
  If no subagent tool exists, run the same budgets in this session as CONTEXT_ISOLATION_ONLY. Do not claim independent agent execution.
17
17
 
18
- Init/status/refresh/sync-hosts/generate-adapter: `npx ai-engineering-loop <command>`. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status`. If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session. Stage 8: load `adapters/<adapter_type>/`. If adapter.md is missing, run `generate-adapter` (grill). Do not invent a company pipeline.
18
+ Init/status/refresh/sync-hosts/generate-adapter/generate-workflow: `npx ai-engineering-loop <command>`. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status`. Read `.ai-engineering-loop/glossary.md`. Read `.ai-engineering-loop/lessons.md` and `.ai-engineering-loop/workflow.md` if they exist. Follow workflow.md hooks (`before_grill`, `after_freeze`, `after_pass`). Do not skip Goal Contract, verification, Devil's Advocate, or Judge even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session. After Judge PASS: run the `after_pass` hook if it is not `none`. Stage 8: load `adapters/<adapter_type>/`. If adapter.md is missing, run `generate-adapter` (grill). Do not invent a company pipeline. Confirmed process lessons go to `lessons.md`, not a chat dump.
@@ -8,4 +8,4 @@ Follow `.claude/skills/ai-engineering-loop/SKILL.md`.
8
8
 
9
9
  Use the Task tool for Devil's Advocate and Judge. Pass subagent_type, description, and prompt. If the schema includes run_in_background, set it false. Wait for each Task to finish. Write the git diff to a file and pass that path. DA: 8 tool calls. Judge: 4 tool calls, ledger and contract only. Do not let either roam the repo.
10
10
 
11
- Arguments: init, status, refresh, sync-hosts, generate-adapter, or a task description.
11
+ Arguments: init, status, refresh, sync-hosts, generate-adapter, generate-workflow, or a task description.
@@ -24,15 +24,16 @@ Claude Code talks to strict proxies (including Kiro). Follow this exactly:
24
24
 
25
25
  ## Commands
26
26
 
27
- - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter`: run `npx ai-engineering-loop <command>` in the repo. Do not commit unless asked.
27
+ - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter` / `generate-workflow`: run `npx ai-engineering-loop <command>` in the repo. Do not commit unless asked.
28
28
  - `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
29
+ - `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/workflow.md` and empty `lessons.md` if missing. Do not start Maker.
29
30
  - Any other argument: full loop for that task.
30
31
 
31
32
  ## Loop
32
33
 
33
34
  Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as **siblings**, not nested.
34
35
 
35
- 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init or refresh if missing or stale). Read `.ai-engineering-loop/glossary.md`. If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
36
+ 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init or refresh if missing or stale). Read `.ai-engineering-loop/glossary.md`. Read `.ai-engineering-loop/lessons.md` and `.ai-engineering-loop/workflow.md` if they exist. Follow workflow.md hooks (`before_grill`, `after_freeze`, `after_pass`). Do not skip Goal Contract, verification, Devil's Advocate, or Judge even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
36
37
  2. Stage 1: Goal Contract (`core/goal-contract.md`). If the user asks for ideas, list a short menu and wait; do not implement. If the task is ambiguous and the user can answer, grill first (`core/grill-policy.md`): design tree, recommended answers, do not ask look-up facts. Skip grill if the contract is already frozen or the user waived it. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Chat agreement is not freeze: every user-visible decision must be a numbered AC in the Goal Contract file. Freeze before any production edit. Name test seams. Use glossary terms. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only.
37
38
  3. Stages 2-4: Maker in the parent. Bugs: red repro first (`core/root-cause-analysis.md`). Features: TDD at named seams (`policies/tdd-policy.md`): one red test per AC row. Surgical diff.
38
39
  4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
@@ -44,7 +45,7 @@ Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as *
44
45
  6. Stage 6: Task `subagent_type: devil-advocate`. Use `general-purpose` only if that type is rejected. If the Task schema includes `run_in_background`, set it false. Then wait for Task to return. Do not start Judge or more Maker work until the Finding Ledger is back. Prompt: diff file path, name-only list, Goal Contract path, verification log path, conventions.md path, and "at most 8 tool calls; read the diff file; skip css and generated files". Report Spec and Standards axes separately.
45
46
  7. Stage 7: Task `subagent_type: judge` the same way (wait, no background). Use `general-purpose` only if `judge` is rejected. Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
46
47
  8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate (do not resume the previous child).
47
- 9. Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline.
48
+ 9. After Judge PASS: run the `after_pass` hook from workflow.md if it is not `none`. Then Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline. When the user confirms a process lesson, append one row to `lessons.md` (not a chat dump). Terms go to glossary.md.
48
49
 
49
50
  ## Report header
50
51
 
@@ -19,13 +19,14 @@ Canonical mode ids: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_
19
19
 
20
20
  ## Commands
21
21
 
22
- - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter`: run `npx ai-engineering-loop <command>` in the repo. Do not commit unless asked.
22
+ - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter` / `generate-workflow`: run `npx ai-engineering-loop <command>` in the repo. Do not commit unless asked.
23
23
  - `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
24
+ - `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/workflow.md` and empty `lessons.md` if missing. Do not start Maker.
24
25
  - Any other argument: full loop for that task.
25
26
 
26
27
  ## Loop
27
28
 
28
- 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init or refresh if missing or stale). Read `.ai-engineering-loop/glossary.md`. If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
29
+ 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init or refresh if missing or stale). Read `.ai-engineering-loop/glossary.md`. Read `.ai-engineering-loop/lessons.md` and `.ai-engineering-loop/workflow.md` if they exist. Follow workflow.md hooks (`before_grill`, `after_freeze`, `after_pass`). Do not skip Goal Contract, verification, Devil's Advocate, or Judge even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
29
30
  2. Stage 1: Goal Contract (`core/goal-contract.md`). If the user asks for ideas, list a short menu and wait; do not implement. If the task is ambiguous and the user can answer, grill first (`core/grill-policy.md`): design tree, recommended answers, do not ask look-up facts. Skip grill if the contract is already frozen or the user waived it. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Chat agreement is not freeze: every user-visible decision must be a numbered AC in the Goal Contract file. Freeze before any production edit. Name test seams. Use glossary terms. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only.
30
31
  3. Stages 2-4: Maker in the parent. Bugs: red repro first (`core/root-cause-analysis.md`). Features: TDD at named seams (`policies/tdd-policy.md`): one red test per AC row. Surgical diff.
31
32
  4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
@@ -37,7 +38,7 @@ Canonical mode ids: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_
37
38
  6. Stage 6: spawn `devil-advocate`. Wait. Prompt: diff file path, name-only list, Goal Contract path, verification log path, conventions.md path, and "at most 8 tool calls; read the diff file; skip css and generated files". Report Spec and Standards axes separately.
38
39
  7. Stage 7: spawn `judge` the same way (wait, no background). Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
39
40
  8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate.
40
- 9. Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline.
41
+ 9. After Judge PASS: run the `after_pass` hook from workflow.md if it is not `none`. Then Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline. When the user confirms a process lesson, append one row to `lessons.md` (not a chat dump). Terms go to glossary.md.
41
42
 
42
43
  ## Report header
43
44
 
@@ -7,5 +7,5 @@ Follow `.grok/skills/ai-engineering-loop/SKILL.md`.
7
7
 
8
8
  Arguments:
9
9
 
10
- - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter` → run `npx ai-engineering-loop <arg>`
10
+ - `init` / `status` / `refresh` / `sync-hosts` / `generate-adapter` / `generate-workflow` → run `npx ai-engineering-loop <arg>`
11
11
  - anything else → full 8-stage loop for that task, spawning `devil-advocate` then `judge` via `spawn_subagent`
@@ -38,13 +38,13 @@ Optional fallback if `devil-advocate` / `judge` types are not registered: `subag
38
38
 
39
39
  ## Commands
40
40
 
41
- ### `/ai-engineering-loop init|status|refresh|sync-hosts|generate-adapter`
41
+ ### `/ai-engineering-loop init|status|refresh|sync-hosts|generate-adapter|generate-workflow`
42
42
 
43
- Run `npx ai-engineering-loop <command>` in the target repo. Do not commit unless the user asks. `sync-hosts` copies this package's skills/agents/commands into `~/.claude`, `~/.grok`, `~/.gemini`, and `~/.agents` for hosts that already exist. `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
43
+ Run `npx ai-engineering-loop <command>` in the target repo. Do not commit unless the user asks. `sync-hosts` copies this package's skills/agents/commands into `~/.claude`, `~/.grok`, `~/.gemini`, and `~/.agents` for hosts that already exist. `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/adapter.md`. Do not start Maker. `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q5. Then write `.ai-engineering-loop/workflow.md` and empty `lessons.md` if missing. Do not start Maker.
44
44
 
45
45
  ### `/ai-engineering-loop [task]`
46
46
 
47
- 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init/refresh if missing or stale). Read `.ai-engineering-loop/glossary.md`. If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
47
+ 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init/refresh if missing or stale). Read `.ai-engineering-loop/glossary.md`. Read `.ai-engineering-loop/lessons.md` and `.ai-engineering-loop/workflow.md` if they exist. Follow workflow.md hooks (`before_grill`, `after_freeze`, `after_pass`). Do not skip Goal Contract, verification, Devil's Advocate, or Judge even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
48
48
  2. Stage 1: Goal Contract (`core/goal-contract.md`). If the user asks for ideas, list a short menu and wait; do not implement. If the task is ambiguous and the user can answer, grill first (`core/grill-policy.md`): design tree, recommended answers, do not ask look-up facts. Skip grill if the contract is already frozen or the user waived it. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Chat agreement is not freeze: every user-visible decision must be a numbered AC in the Goal Contract file. Freeze before any production edit. Name test seams. Use glossary terms. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only.
49
49
  3. Stages 2–4: Maker work in the **parent**. Bugs: red repro first (`core/root-cause-analysis.md`). Features: TDD at named seams (`policies/tdd-policy.md`): one red test per AC row. Surgical diff. Parent may be the Maker; do not spawn Maker as a child if you still need to spawn DA/Judge afterward from the same parent.
50
50
  4. Stage 5: run verification from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
@@ -56,7 +56,7 @@ Run `npx ai-engineering-loop <command>` in the target repo. Do not commit unless
56
56
  6. Stage 6: `spawn_subagent` Devil's Advocate. `background: false`. `capability_mode: "execute"`. Do **not** pass `resume_from`. Wait for the child. Prompt: diff file path, name-only file list, Goal Contract path, verification log path, conventions.md path, plus "at most 8 tool calls; read the diff file; skip css and generated files". Report Spec and Standards axes separately.
57
57
  7. Stage 7: `spawn_subagent` Judge the same way (`background: false`, wait). Use `general-purpose` only if `judge` is rejected. Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
58
58
  8. If Judge says `ITERATE` and iteration < 3, Maker fixes in the parent, re-verify, spawn a **fresh** DA (new spawn, no resume).
59
- 9. Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline.
59
+ 9. After Judge PASS: run the `after_pass` hook from workflow.md if it is not `none`. Then Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline. When the user confirms a process lesson, append one row to `lessons.md` (not a chat dump). Terms go to glossary.md.
60
60
 
61
61
  After a proven Grok DA spawn, the report header must be:
62
62
 
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
7
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
8
8
  [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
9
- [![Release](https://img.shields.io/badge/release-v1.0.16-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
9
+ [![Release](https://img.shields.io/badge/release-v1.0.17-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
10
10
 
11
11
  **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
12
12
 
@@ -184,11 +184,15 @@ npx ai-engineering-loop sync-hosts
184
184
  # Grill (or --type) a Stage 8 delivery adapter for this repo
185
185
  npx ai-engineering-loop generate-adapter
186
186
  npx ai-engineering-loop generate-adapter --type github
187
+
188
+ # Grill (or --write) a loop overlay + empty lessons.md for this repo
189
+ npx ai-engineering-loop generate-workflow
190
+ npx ai-engineering-loop generate-workflow --write
187
191
  ```
188
192
 
189
193
  Shipped adapters (Stage 8 only, after Judge PASS): `standard`, `github`, `gitlab`, `dot`. Catalog: `adapters/README.md`. Each team generates its own; do not copy a neighbour's pipeline.
190
194
 
191
- `sync-hosts` updates only hosts that already exist on the machine. DOT skills (`dot-dev-skill-router`, `dot-dev-workflow`) are updated only if they are already installed. `task-impact-inquiry` and `generate-adapter` are upserted onto Claude, Grok, and Gemini. After a copy, start a new session so the host reloads skill text. `/ai-engineering-loop` Stage 0 and `run` call `sync-hosts` so a published package bump reaches global host files without a manual copy.
195
+ `sync-hosts` updates only hosts that already exist on the machine. DOT skills (`dot-dev-skill-router`, `dot-dev-workflow`) are updated only if they are already installed. `task-impact-inquiry`, `generate-adapter`, and `generate-workflow` are upserted onto Claude, Grok, and Gemini. After a copy, start a new session so the host reloads skill text. `/ai-engineering-loop` Stage 0 and `run` call `sync-hosts` so a published package bump reaches global host files without a manual copy.
192
196
 
193
197
  ---
194
198
 
@@ -338,6 +342,7 @@ ai-engineering-loop/
338
342
  ├── adapters/ # Pluggable Stage 8 delivery (not a second OS)
339
343
  │ ├── README.md # Catalog: standard, github, gitlab, dot
340
344
  │ ├── generate-adapter/SKILL.md # Grill Q1-Q5, then write adapter.md
345
+ │ ├── generate-workflow/SKILL.md # Grill Q1-Q5, then write workflow.md + lessons.md
341
346
  │ ├── standard/ # Generic git delivery (any forge)
342
347
  │ ├── github/ # gh pr / GitHub Issues
343
348
  │ ├── gitlab/ # glab mr (not the DOT pipeline)
@@ -351,7 +356,9 @@ ai-engineering-loop/
351
356
  ├── adr-readme.md # ADR folder template
352
357
  ├── conventions.md # Code standards & forbidden patterns
353
358
  ├── verification.md # CLI test/lint/build commands
354
- └── adapter.md # Configured release pipeline
359
+ ├── adapter.md # Configured release pipeline
360
+ ├── workflow.md # Optional loop overlay hooks
361
+ └── lessons.md # Optional confirmed process lessons
355
362
  ```
356
363
 
357
364
  ---
@@ -25,3 +25,5 @@ npx ai-engineering-loop generate-adapter --type github
25
25
  ```
26
26
 
27
27
  Interactive path: load skill `generate-adapter`, answer Q1–Q5, then the agent writes `.ai-engineering-loop/adapter.md`.
28
+
29
+ Loop overlay (not a forge type): skill `generate-workflow` writes `.ai-engineering-loop/workflow.md` and `lessons.md`. It does not replace Stages 0–7.
@@ -0,0 +1,128 @@
1
+ ---
2
+ name: generate-workflow
3
+ description: Grill then write a loop overlay and empty lessons.md for this repo. Use when the user says generate-workflow, buat workflow, or their team needs extra steps around AEL. Not a substitute for ai-engineering-loop.
4
+ ---
5
+
6
+ # Generate Workflow Overlay
7
+
8
+ Write **this repo's** loop overlay. Teams add hooks around the 8-stage OS. They do not replace it.
9
+
10
+ This skill is not the engineering OS. After the files exist, commit-bound work still runs `ai-engineering-loop`. Stage 0 reads the files this skill writes.
11
+
12
+ ## Hard gate
13
+
14
+ Do not edit production code. Do not create a feature branch for the product.
15
+
16
+ Do not write `.ai-engineering-loop/workflow.md` until:
17
+
18
+ 1. Look-up is done (existing overlay, lessons, adapter).
19
+ 2. Q1–Q5 are on screen with a recommended answer.
20
+ 3. The user has answered or waived.
21
+
22
+ Never skip Goal Contract, verification, Devil's Advocate, or Judge. If the user asks to skip those, refuse and keep them required.
23
+
24
+ ## When to use
25
+
26
+ - `generate-workflow`, `buat workflow`, `overlay loop`, `lessons.md`
27
+ - `.ai-engineering-loop/workflow.md` missing and the team wants extra steps
28
+ - The user wants confirmed process lessons to survive sessions
29
+
30
+ If Stage 1 grill for a **product task** is already running, do not start this skill as a second interview. Finish that Goal Contract first.
31
+
32
+ ## Host notes
33
+
34
+ Claude Code / Kiro: no mermaid, no LaTeX, no extra tool keys.
35
+
36
+ Grok: do not spawn children. Stay in the parent.
37
+
38
+ Look up facts. Grill only **decisions**.
39
+
40
+ ## Steps
41
+
42
+ ### 1. Look up
43
+
44
+ Read, in order. Skip if missing.
45
+
46
+ 1. `.ai-engineering-loop/workflow.md`
47
+ 2. `.ai-engineering-loop/lessons.md`
48
+ 3. `.ai-engineering-loop/adapter.md`
49
+
50
+ Or run `npx ai-engineering-loop generate-workflow` and use its protocol block.
51
+
52
+ Cite what already exists. Do not ask whether those files are present.
53
+
54
+ ### 2. Grill (wait)
55
+
56
+ Ask all five in one round. Number them. Give Recommended. Wait.
57
+
58
+ ```text
59
+ Q1 - Extra step before grill: none | name it
60
+ Recommended: none
61
+
62
+ Q2 - Extra step after Goal Contract freeze: none | name it
63
+ Recommended: none
64
+
65
+ Q3 - Extra step after Judge PASS (before Stage 8): none | name it
66
+ Recommended: none
67
+
68
+ Q4 - Blast radius when the change is not business logic: keep AEL default (skip) | always run
69
+ Recommended: keep AEL default
70
+
71
+ Q5 - Skip generate-adapter when adapter.md already exists: yes | no
72
+ Recommended: yes
73
+ ```
74
+
75
+ If they name a tool or step, write that name into the matching hook. Do not invent Figma/Jira/Slack unless they said so.
76
+
77
+ ### 3. Write
78
+
79
+ Write `.ai-engineering-loop/workflow.md` (create `.ai-engineering-loop/` if needed).
80
+
81
+ - Required stages listed and not skippable
82
+ - Hooks from Q1–Q3 (`none` if they picked none)
83
+ - Optional skips only `blast_radius` and/or `generate_adapter`
84
+ - No tokens, no coworker handles, no internal ticket URLs
85
+
86
+ Write `.ai-engineering-loop/lessons.md` only if it is missing. If it already has rows, leave it.
87
+
88
+ Headless alternative the user can run:
89
+
90
+ ```bash
91
+ npx ai-engineering-loop generate-workflow --write
92
+ ```
93
+
94
+ `--write` skips this interview and writes default hooks (`none`). Do not pass `--write` yourself unless they waived the grill.
95
+
96
+ ### 4. Lessons during later product work
97
+
98
+ When the user confirms "this is wrong / this is right" and it is not a domain term, a code ban, or an ADR:
99
+
100
+ - Append one row to `lessons.md`
101
+ - Date, lesson, do-not
102
+ - Do not paste the chat
103
+
104
+ Route: term → `glossary.md`. Code ban → `conventions.md`. Load-bearing design → `adrs/`. Process / taste / "user always rejects X" → `lessons.md`.
105
+
106
+ ### 5. Stop
107
+
108
+ Print the paths written. Do not start Maker. Do not open a PR.
109
+
110
+ ## Output
111
+
112
+ ```text
113
+ Generate workflow overlay
114
+ Existing: <workflow yes/no> <lessons yes/no>
115
+ Questions: Q1..Q5 with Recommended
116
+ Wrote: .ai-engineering-loop/workflow.md
117
+ Lessons: .ai-engineering-loop/lessons.md (created or left)
118
+ Next: /ai-engineering-loop for product work. Stage 0 reads these files.
119
+ ```
120
+
121
+ ## Forbidden
122
+
123
+ - Replacing the 8-stage OS
124
+ - Skipping Goal Contract, verification, Devil's Advocate, or Judge
125
+ - Using a second evaluation filename. The file is `lessons.md`
126
+ - Dumping chat into lessons
127
+ - Mermaid or LaTeX
128
+ - Running the 8-stage product loop inside this skill
@@ -26,8 +26,15 @@ const {
26
26
  formatGenerateAdapterReport,
27
27
  parseTypeArg
28
28
  } = require('../lib/generate-adapter.js');
29
-
30
- const VERSION = '1.0.16';
29
+ const {
30
+ writeWorkflowOverlay,
31
+ formatGenerateWorkflowReport,
32
+ parseWriteArg,
33
+ workflowMarkdown,
34
+ lessonsMarkdown
35
+ } = require('../lib/generate-workflow.js');
36
+
37
+ const VERSION = '1.0.17';
31
38
  const CWD = process.cwd();
32
39
  const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
33
40
 
@@ -281,7 +288,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
281
288
 
282
289
  // 0. metadata.json (Baseline)
283
290
  const metadataJson = {
284
- contextVersion: '1.0.16',
291
+ contextVersion: '1.0.17',
285
292
  generatedAt: new Date().toISOString(),
286
293
  repositoryRevision: currentRevision,
287
294
  projectProfile: discovery.profile,
@@ -418,6 +425,9 @@ What becomes easier, harder, or forbidden.
418
425
  \`\`\`
419
426
  `;
420
427
  writeContextFile(path.join(targetDir, 'adrs', 'README.md'), adrReadme, { overwrite: false });
428
+
429
+ writeContextFile(path.join(targetDir, 'workflow.md'), workflowMarkdown(), { overwrite: false });
430
+ writeContextFile(path.join(targetDir, 'lessons.md'), lessonsMarkdown(), { overwrite: false });
421
431
  }
422
432
 
423
433
  /**
@@ -677,6 +687,22 @@ function handleGenerateAdapter() {
677
687
  }
678
688
  }
679
689
 
690
+ function handleGenerateWorkflow() {
691
+ log.info('AI Engineering Loop — Generate loop overlay (generate-workflow)');
692
+ const shouldWrite = parseWriteArg(process.argv);
693
+ if (!shouldWrite) {
694
+ console.log(formatGenerateWorkflowReport({ version: VERSION }));
695
+ return;
696
+ }
697
+ try {
698
+ const wrote = writeWorkflowOverlay(CWD, {});
699
+ console.log(formatGenerateWorkflowReport({ version: VERSION, wrote }));
700
+ } catch (err) {
701
+ log.error(err.message);
702
+ process.exit(1);
703
+ }
704
+ }
705
+
680
706
  function detectGrokHost() {
681
707
  try {
682
708
  const { detectGrokRuntime } = require('../lib/orchestration.js');
@@ -771,6 +797,8 @@ Commands:
771
797
  --dry-run print the plan without writing
772
798
  generate-adapter Print detected forge and grill protocol for Stage 8
773
799
  --type standard|github|gitlab|dot write .ai-engineering-loop/adapter.md (skip grill)
800
+ generate-workflow Print grill protocol for a loop overlay (hooks + lessons.md)
801
+ --write write .ai-engineering-loop/workflow.md and empty lessons.md (skip grill)
774
802
 
775
803
  Options:
776
804
  -h, --help Show this help menu
@@ -804,6 +832,9 @@ switch (command) {
804
832
  case 'generate-adapter':
805
833
  handleGenerateAdapter();
806
834
  break;
835
+ case 'generate-workflow':
836
+ handleGenerateWorkflow();
837
+ break;
807
838
  case '-v':
808
839
  case '--version':
809
840
  console.log(`ai-engineering-loop v${VERSION}`);
@@ -70,6 +70,7 @@ flowchart TD
70
70
  | New folder in `src/modules/` or `apps/` | `architecture.md` | Add module summary and boundary notes |
71
71
  | New global error class or lint rule added | `conventions.md` | Document new pattern or forbidden rule |
72
72
  | New or corrected domain term | `glossary.md` | Add or fix one glossary row |
73
+ | Confirmed process / taste lesson (not a term) | `lessons.md` | Append one row; do not dump chat |
73
74
  | Load-bearing design choice settled | `adrs/NNN-*.md` | Write an ADR; do not bury it in chat |
74
75
  | `.gitlab-ci.yml` / `.github/workflows` edited | `adapter.md` | Update CI/CD workflow references |
75
76
 
@@ -14,6 +14,8 @@ The `.ai-engineering-loop/` directory serves as the **Living Project Context** f
14
14
  ├── verification.md # Exact CLI verification commands
15
15
  ├── adapter.md # Configured delivery pipeline & CI/CD tools
16
16
  ├── glossary.md # Ubiquitous language (one term per concept)
17
+ ├── workflow.md # Optional loop overlay (hooks around the 8-stage OS)
18
+ ├── lessons.md # Optional confirmed process lessons (not a chat log)
17
19
  ├── adrs/ # Architecture Decision Records from Stage 1 grill
18
20
  │ └── README.md
19
21
  └── tasks/ # Ephemeral: current.diff, handoff.md, verification logs
@@ -79,6 +81,17 @@ Maintains lightweight state for instant drift detection:
79
81
  ### 9. `tasks/` — Run artifacts (optional)
80
82
  - `current.diff`, verification logs, `handoff.md`. Not required for `init` validity.
81
83
 
84
+ ### 10. `workflow.md` — Loop overlay (optional)
85
+ - Hooks around the 8-stage OS: `before_grill`, `after_freeze`, `after_pass`.
86
+ - Cannot skip Goal Contract, verification, Devil's Advocate, or Judge.
87
+ - Missing file means default 8-stage loop (no extra hooks).
88
+ - Generate with `npx ai-engineering-loop generate-workflow` (grill) or `--write`.
89
+
90
+ ### 11. `lessons.md` — Confirmed process lessons (optional)
91
+ - One human-confirmed row per lesson. Not a chat transcript. Not `eval.md`.
92
+ - Terms still go to `glossary.md`. Code bans to `conventions.md`. Design why to `adrs/`.
93
+ - `refresh` / `--write` must not overwrite filled lessons.
94
+
82
95
  ---
83
96
 
84
97
  ## 3. Version Control Recommendation
@@ -0,0 +1,203 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ const REQUIRED_STAGES = ['goal_contract', 'verification', 'devil_advocate', 'judge'];
7
+ const ALLOWED_OPTIONAL_SKIPS = ['blast_radius', 'generate_adapter'];
8
+ const DEFAULT_HOOKS = {
9
+ before_grill: 'none',
10
+ after_freeze: 'none',
11
+ after_pass: 'none'
12
+ };
13
+
14
+ const REQUIRED_ALIASES = {
15
+ goal_contract: 'goal_contract',
16
+ 'goal contract': 'goal_contract',
17
+ verification: 'verification',
18
+ devil_advocate: 'devil_advocate',
19
+ "devil's advocate": 'devil_advocate',
20
+ 'devils advocate': 'devil_advocate',
21
+ judge: 'judge'
22
+ };
23
+
24
+ function normalizeSkip(name) {
25
+ return String(name || '')
26
+ .trim()
27
+ .toLowerCase()
28
+ .replace(/['"]/g, '')
29
+ .replace(/\s+/g, '_');
30
+ }
31
+
32
+ function assertNoRequiredSkip(skips) {
33
+ for (const raw of skips || []) {
34
+ const id = REQUIRED_ALIASES[normalizeSkip(raw)] || normalizeSkip(raw);
35
+ if (REQUIRED_STAGES.includes(id)) {
36
+ const err = new Error(`cannot skip required stage: ${id}`);
37
+ err.code = 'REQUIRED_SKIP';
38
+ throw err;
39
+ }
40
+ }
41
+ }
42
+
43
+ function routeDurableNote(kind) {
44
+ const map = {
45
+ term: 'glossary.md',
46
+ process: 'lessons.md',
47
+ lesson: 'lessons.md',
48
+ convention: 'conventions.md',
49
+ adr: 'adrs/'
50
+ };
51
+ return map[kind] || 'lessons.md';
52
+ }
53
+
54
+ function workflowMarkdown({ hooks = DEFAULT_HOOKS, optionalSkips = [] } = {}) {
55
+ const skipLine = optionalSkips.length ? optionalSkips.join(', ') : 'none';
56
+ return `# Loop Overlay
57
+
58
+ This file adds hooks around the AI Engineering Loop. It does not replace the 8-stage OS.
59
+
60
+ ## Required (cannot skip)
61
+ - Goal Contract
62
+ - verification
63
+ - Devil's Advocate
64
+ - Judge
65
+
66
+ ## Hooks
67
+ - **before_grill**: ${hooks.before_grill || 'none'}
68
+ - **after_freeze**: ${hooks.after_freeze || 'none'}
69
+ - **after_pass**: ${hooks.after_pass || 'none'}
70
+
71
+ ## Optional skips
72
+ ${skipLine}
73
+
74
+ Allowed optional skips: \`blast_radius\` (when the change is not business logic), \`generate_adapter\` (when adapter.md already exists).
75
+ Do not list Goal Contract, verification, Devil's Advocate, or Judge here.
76
+ `;
77
+ }
78
+
79
+ function lessonsMarkdown() {
80
+ return `# Lessons
81
+
82
+ Confirmed by a human. One row per lesson. Not a chat transcript. Not a glossary.
83
+
84
+ Route elsewhere when it fits: term → glossary.md, code ban → conventions.md, load-bearing design → adrs/.
85
+
86
+ | Date | Lesson | Do not |
87
+ |---|---|---|
88
+ `;
89
+ }
90
+
91
+ function parseHookLine(text, key) {
92
+ const re = new RegExp(`\\*\\*${key}\\*\\*:\\s*(.+)`, 'i');
93
+ const match = text.match(re);
94
+ if (!match) return 'none';
95
+ return match[1].trim() || 'none';
96
+ }
97
+
98
+ function parseOptionalSkips(text) {
99
+ const block = text.split(/## Optional skips/i)[1];
100
+ if (!block) return [];
101
+ const line = block.split('\n').find((row) => row.trim() && !row.startsWith('#'));
102
+ if (!line) return [];
103
+ const raw = line.replace(/^-\s*/, '').trim();
104
+ if (!raw || /^none$/i.test(raw)) return [];
105
+ return raw.split(/,|\|/).map((item) => normalizeSkip(item)).filter(Boolean);
106
+ }
107
+
108
+ function parseWorkflowMarkdown(text) {
109
+ return {
110
+ missing: false,
111
+ required: REQUIRED_STAGES.slice(),
112
+ hooks: {
113
+ before_grill: parseHookLine(text, 'before_grill'),
114
+ after_freeze: parseHookLine(text, 'after_freeze'),
115
+ after_pass: parseHookLine(text, 'after_pass')
116
+ },
117
+ optionalSkips: parseOptionalSkips(text)
118
+ };
119
+ }
120
+
121
+ function parseWorkflowFile(rootDir) {
122
+ const dest = path.join(rootDir, '.ai-engineering-loop', 'workflow.md');
123
+ try {
124
+ const text = fs.readFileSync(dest, 'utf8');
125
+ return parseWorkflowMarkdown(text);
126
+ } catch {
127
+ return {
128
+ missing: true,
129
+ required: REQUIRED_STAGES.slice(),
130
+ hooks: { ...DEFAULT_HOOKS },
131
+ optionalSkips: []
132
+ };
133
+ }
134
+ }
135
+
136
+ function lessonsAreFilled(text) {
137
+ if (!text || !text.trim()) return false;
138
+ return /\| 20\d{2}-/.test(text);
139
+ }
140
+
141
+ function writeWorkflowOverlay(rootDir, { hooks, optionalSkips } = {}) {
142
+ const skips = optionalSkips || [];
143
+ assertNoRequiredSkip(skips);
144
+ for (const skip of skips) {
145
+ const id = normalizeSkip(skip);
146
+ if (!ALLOWED_OPTIONAL_SKIPS.includes(id)) {
147
+ const err = new Error(`Unknown optional skip: ${skip}. Use ${ALLOWED_OPTIONAL_SKIPS.join('|')}`);
148
+ err.code = 'UNKNOWN_SKIP';
149
+ throw err;
150
+ }
151
+ }
152
+ const dir = path.join(rootDir, '.ai-engineering-loop');
153
+ fs.mkdirSync(dir, { recursive: true });
154
+ const workflowPath = path.join(dir, 'workflow.md');
155
+ const lessonsPath = path.join(dir, 'lessons.md');
156
+ fs.writeFileSync(
157
+ workflowPath,
158
+ workflowMarkdown({
159
+ hooks: { ...DEFAULT_HOOKS, ...(hooks || {}) },
160
+ optionalSkips: skips
161
+ })
162
+ );
163
+ if (!fs.existsSync(lessonsPath) || !lessonsAreFilled(fs.readFileSync(lessonsPath, 'utf8'))) {
164
+ if (!fs.existsSync(lessonsPath)) {
165
+ fs.writeFileSync(lessonsPath, lessonsMarkdown());
166
+ }
167
+ }
168
+ return { workflow: workflowPath, lessons: lessonsPath };
169
+ }
170
+
171
+ function formatGenerateWorkflowReport({ version, wrote } = {}) {
172
+ const lines = [
173
+ `Workflow overlay generate (v${version || 'unknown'})`,
174
+ 'This is not a second OS. Required: Goal Contract, verification, Devil\'s Advocate, Judge.',
175
+ 'Files: .ai-engineering-loop/workflow.md and lessons.md',
176
+ 'Next: load skill generate-workflow. Ask Q1-Q5. Wait.',
177
+ 'Headless: npx ai-engineering-loop generate-workflow --write'
178
+ ];
179
+ if (wrote) {
180
+ lines.push(`Wrote: ${wrote.workflow}`);
181
+ lines.push(`Lessons: ${wrote.lessons}`);
182
+ }
183
+ return lines.join('\n');
184
+ }
185
+
186
+ function parseWriteArg(argv) {
187
+ return argv.includes('--write');
188
+ }
189
+
190
+ module.exports = {
191
+ REQUIRED_STAGES,
192
+ ALLOWED_OPTIONAL_SKIPS,
193
+ DEFAULT_HOOKS,
194
+ assertNoRequiredSkip,
195
+ routeDurableNote,
196
+ workflowMarkdown,
197
+ lessonsMarkdown,
198
+ parseWorkflowMarkdown,
199
+ parseWorkflowFile,
200
+ writeWorkflowOverlay,
201
+ formatGenerateWorkflowReport,
202
+ parseWriteArg
203
+ };
package/lib/sync-hosts.js CHANGED
@@ -35,6 +35,7 @@ function hostFileMap(home) {
35
35
  { src: '.claude/skills/ai-engineering-loop/SKILL.md', dest: path.join(claude, 'skills/ai-engineering-loop/SKILL.md'), mode: 'upsert' },
36
36
  { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(claude, 'skills/task-impact-inquiry/SKILL.md'), mode: 'upsert' },
37
37
  { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(claude, 'skills/generate-adapter/SKILL.md'), mode: 'upsert' },
38
+ { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(claude, 'skills/generate-workflow/SKILL.md'), mode: 'upsert' },
38
39
  { src: '.claude/agents/devil-advocate.md', dest: path.join(claude, 'agents/devil-advocate.md'), mode: 'upsert' },
39
40
  { src: '.claude/agents/judge.md', dest: path.join(claude, 'agents/judge.md'), mode: 'upsert' },
40
41
  { src: '.claude/commands/ai-engineering-loop.md', dest: path.join(claude, 'commands/ai-engineering-loop.md'), mode: 'upsert' }
@@ -47,6 +48,7 @@ function hostFileMap(home) {
47
48
  { src: '.grok/skills/ai-engineering-loop/SKILL.md', dest: path.join(grok, 'skills/ai-engineering-loop/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
48
49
  { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(grok, 'skills/task-impact-inquiry/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
49
50
  { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(grok, 'skills/generate-adapter/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
51
+ { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(grok, 'skills/generate-workflow/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
50
52
  { src: '.grok/agents/devil-advocate.md', dest: path.join(grok, 'agents/devil-advocate.md'), mode: 'upsert' },
51
53
  { src: '.grok/agents/judge.md', dest: path.join(grok, 'agents/judge.md'), mode: 'upsert' },
52
54
  { src: '.grok/commands/ai-engineering-loop.md', dest: path.join(grok, 'commands/ai-engineering-loop.md'), mode: 'upsert' }
@@ -58,7 +60,8 @@ function hostFileMap(home) {
58
60
  files: [
59
61
  { src: '.gemini/skills/ai-engineering-loop/SKILL.md', dest: path.join(gemini, 'config/skills/ai-engineering-loop/SKILL.md'), mode: 'upsert' },
60
62
  { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(gemini, 'config/skills/task-impact-inquiry/SKILL.md'), mode: 'upsert' },
61
- { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(gemini, 'config/skills/generate-adapter/SKILL.md'), mode: 'upsert' }
63
+ { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(gemini, 'config/skills/generate-adapter/SKILL.md'), mode: 'upsert' },
64
+ { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(gemini, 'config/skills/generate-workflow/SKILL.md'), mode: 'upsert' }
62
65
  ]
63
66
  },
64
67
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.0.16",
3
+ "version": "1.0.17",
4
4
  "description": "A reusable, framework-agnostic AI Engineering Operating System for autonomous coding agents.",
5
5
  "main": "bin/ai-engineering-loop.js",
6
6
  "bin": {
@@ -0,0 +1,8 @@
1
+ # Lessons
2
+
3
+ Confirmed by a human. One row per lesson. Not a chat transcript. Not a glossary.
4
+
5
+ Route elsewhere when it fits: term → glossary.md, code ban → conventions.md, load-bearing design → adrs/.
6
+
7
+ | Date | Lesson | Do not |
8
+ |---|---|---|
@@ -0,0 +1,20 @@
1
+ # Loop Overlay
2
+
3
+ This file adds hooks around the AI Engineering Loop. It does not replace the 8-stage OS.
4
+
5
+ ## Required (cannot skip)
6
+ - Goal Contract
7
+ - verification
8
+ - Devil's Advocate
9
+ - Judge
10
+
11
+ ## Hooks
12
+ - **before_grill**: none
13
+ - **after_freeze**: none
14
+ - **after_pass**: none
15
+
16
+ ## Optional skips
17
+ none
18
+
19
+ Allowed optional skips: `blast_radius` (when the change is not business logic), `generate_adapter` (when adapter.md already exists).
20
+ Do not list Goal Contract, verification, Devil's Advocate, or Judge here.
@@ -0,0 +1,109 @@
1
+ 'use strict';
2
+
3
+ const test = require('node:test');
4
+ const assert = require('node:assert');
5
+ const fs = require('fs');
6
+ const os = require('os');
7
+ const path = require('path');
8
+ const { execFileSync } = require('child_process');
9
+
10
+ const {
11
+ parseWorkflowFile,
12
+ writeWorkflowOverlay,
13
+ assertNoRequiredSkip,
14
+ routeDurableNote,
15
+ parseWriteArg
16
+ } = require('../lib/generate-workflow.js');
17
+
18
+ const CLI = path.join(__dirname, '..', 'bin', 'ai-engineering-loop.js');
19
+
20
+ function tmpRepo() {
21
+ return fs.mkdtempSync(path.join(os.tmpdir(), 'ael-workflow-'));
22
+ }
23
+
24
+ test('AC-1 writeWorkflowOverlay writes workflow.md and empty lessons.md', () => {
25
+ const dir = tmpRepo();
26
+ const wrote = writeWorkflowOverlay(dir, {});
27
+ const workflow = fs.readFileSync(wrote.workflow, 'utf8');
28
+ const lessons = fs.readFileSync(wrote.lessons, 'utf8');
29
+ assert.match(workflow, /Goal Contract/);
30
+ assert.match(workflow, /Devil's Advocate/);
31
+ assert.match(workflow, /Judge/);
32
+ assert.match(workflow, /verification/);
33
+ assert.match(workflow, /before_grill/);
34
+ assert.doesNotMatch(workflow, /skip Devil's Advocate/i);
35
+ assert.match(lessons, /# Lessons/);
36
+ assert.doesNotMatch(lessons, /\| 20\d{2}-/);
37
+ });
38
+
39
+ test('AC-2 missing workflow.md returns default overlay', () => {
40
+ const dir = tmpRepo();
41
+ const parsed = parseWorkflowFile(dir);
42
+ assert.strictEqual(parsed.missing, true);
43
+ assert.strictEqual(parsed.hooks.before_grill, 'none');
44
+ assert.strictEqual(parsed.hooks.after_freeze, 'none');
45
+ assert.strictEqual(parsed.hooks.after_pass, 'none');
46
+ assert.deepStrictEqual(parsed.optionalSkips, []);
47
+ assert.deepStrictEqual(parsed.required, [
48
+ 'goal_contract',
49
+ 'verification',
50
+ 'devil_advocate',
51
+ 'judge'
52
+ ]);
53
+ });
54
+
55
+ test('AC-3 skip devil_advocate is rejected and does not write', () => {
56
+ const dir = tmpRepo();
57
+ assert.throws(
58
+ () => writeWorkflowOverlay(dir, { optionalSkips: ['devil_advocate'] }),
59
+ /cannot skip/
60
+ );
61
+ assert.ok(!fs.existsSync(path.join(dir, '.ai-engineering-loop', 'workflow.md')));
62
+ assert.throws(() => assertNoRequiredSkip(['judge']), /cannot skip/);
63
+ assert.throws(() => assertNoRequiredSkip(['goal_contract']), /cannot skip/);
64
+ assert.throws(() => assertNoRequiredSkip(['verification']), /cannot skip/);
65
+ assert.doesNotThrow(() => assertNoRequiredSkip(['blast_radius']));
66
+ });
67
+
68
+ test('AC-4 routeDurableNote sends term to glossary and process to lessons', () => {
69
+ assert.strictEqual(routeDurableNote('term'), 'glossary.md');
70
+ assert.strictEqual(routeDurableNote('process'), 'lessons.md');
71
+ assert.strictEqual(routeDurableNote('convention'), 'conventions.md');
72
+ assert.strictEqual(routeDurableNote('adr'), 'adrs/');
73
+ });
74
+
75
+ test('AC-5 --write does not overwrite filled lessons.md', () => {
76
+ const dir = tmpRepo();
77
+ const ctx = path.join(dir, '.ai-engineering-loop');
78
+ fs.mkdirSync(ctx, { recursive: true });
79
+ const lessonsPath = path.join(ctx, 'lessons.md');
80
+ fs.writeFileSync(lessonsPath, '# Lessons\n\n| Date | Lesson | Do not |\n|---|---|---|\n| 2026-08-30 | Keep the Figma step | skip Figma |\n');
81
+ writeWorkflowOverlay(dir, {});
82
+ const after = fs.readFileSync(lessonsPath, 'utf8');
83
+ assert.match(after, /Keep the Figma step/);
84
+ assert.ok(fs.existsSync(path.join(ctx, 'workflow.md')));
85
+ });
86
+
87
+ test('parseWriteArg reads --write', () => {
88
+ assert.strictEqual(parseWriteArg(['generate-workflow', '--write']), true);
89
+ assert.strictEqual(parseWriteArg(['generate-workflow']), false);
90
+ });
91
+
92
+ test('CLI generate-workflow without --write prints grill protocol', () => {
93
+ const dir = tmpRepo();
94
+ const out = execFileSync('node', [CLI, 'generate-workflow'], { cwd: dir, encoding: 'utf8' });
95
+ assert.match(out, /generate-workflow/);
96
+ assert.match(out, /Q1-Q5/);
97
+ assert.ok(!fs.existsSync(path.join(dir, '.ai-engineering-loop', 'workflow.md')));
98
+ });
99
+
100
+ test('CLI generate-workflow --write writes overlay files', () => {
101
+ const dir = tmpRepo();
102
+ const out = execFileSync('node', [CLI, 'generate-workflow', '--write'], {
103
+ cwd: dir,
104
+ encoding: 'utf8'
105
+ });
106
+ assert.match(out, /Wrote:/);
107
+ assert.ok(fs.existsSync(path.join(dir, '.ai-engineering-loop', 'workflow.md')));
108
+ assert.ok(fs.existsSync(path.join(dir, '.ai-engineering-loop', 'lessons.md')));
109
+ });
@@ -21,10 +21,16 @@ test('init writes glossary.md and adrs/README.md', () => {
21
21
  execFileSync('node', [CLI, 'init'], { cwd: dir, encoding: 'utf8' });
22
22
  const glossary = path.join(dir, '.ai-engineering-loop', 'glossary.md');
23
23
  const adr = path.join(dir, '.ai-engineering-loop', 'adrs', 'README.md');
24
+ const workflow = path.join(dir, '.ai-engineering-loop', 'workflow.md');
25
+ const lessons = path.join(dir, '.ai-engineering-loop', 'lessons.md');
24
26
  assert.ok(fs.existsSync(glossary));
25
27
  assert.ok(fs.existsSync(adr));
28
+ assert.ok(fs.existsSync(workflow));
29
+ assert.ok(fs.existsSync(lessons));
26
30
  assert.match(fs.readFileSync(glossary, 'utf8'), /Ubiquitous Language/);
27
31
  assert.match(fs.readFileSync(adr, 'utf8'), /Architecture Decision Records/);
32
+ assert.match(fs.readFileSync(workflow, 'utf8'), /before_grill/);
33
+ assert.match(fs.readFileSync(lessons, 'utf8'), /# Lessons/);
28
34
  });
29
35
 
30
36
  test('repair fills missing glossary without overwriting a filled glossary or architecture', () => {
@@ -44,3 +50,12 @@ test('repair fills missing glossary without overwriting a filled glossary or arc
44
50
  assert.match(fs.readFileSync(glossary, 'utf8'), /Foo: bar/);
45
51
  assert.ok(fs.existsSync(architecture));
46
52
  });
53
+
54
+ test('init does not overwrite filled lessons.md', () => {
55
+ const dir = tmpRepo();
56
+ execFileSync('node', [CLI, 'init'], { cwd: dir, encoding: 'utf8' });
57
+ const lessons = path.join(dir, '.ai-engineering-loop', 'lessons.md');
58
+ fs.writeFileSync(lessons, '# Lessons\n\n| Date | Lesson | Do not |\n|---|---|---|\n| 2026-08-30 | Keep Figma | skip Figma |\n');
59
+ execFileSync('node', [CLI, 'init'], { cwd: dir, encoding: 'utf8' });
60
+ assert.match(fs.readFileSync(lessons, 'utf8'), /Keep Figma/);
61
+ });
@@ -210,6 +210,30 @@ test('DOT router sends commit-bound work to ai-engineering-loop; workflow is Sta
210
210
  assert.doesNotMatch(readme, /Pre-commit multi-round adversarial review gate \(Phase 6\)/);
211
211
  });
212
212
 
213
+ test('generate-workflow skill is Claude-safe and host skills read the overlay', () => {
214
+ const skill = readRepo('adapters/generate-workflow/SKILL.md');
215
+ const { fm } = parseFrontmatter(skill, 'generate-workflow');
216
+ assert.doesNotMatch(fm, /^description:\s*>-?/m);
217
+ assert.doesNotMatch(skill, /```mermaid/);
218
+ assert.doesNotMatch(skill, /\$\\/);
219
+ assert.doesNotMatch(skill, /spawn_subagent/);
220
+ assert.match(skill, /Q1/);
221
+ assert.match(skill, /Do not start Maker/);
222
+ assert.match(skill, /lessons\.md/);
223
+ for (const rel of [
224
+ '.claude/skills/ai-engineering-loop/SKILL.md',
225
+ '.grok/skills/ai-engineering-loop/SKILL.md',
226
+ '.gemini/skills/ai-engineering-loop/SKILL.md',
227
+ '.agents/workflows/ai-engineering-loop.md'
228
+ ]) {
229
+ const text = readRepo(rel);
230
+ assert.match(text, /lessons\.md/, rel);
231
+ assert.match(text, /workflow\.md/, rel);
232
+ assert.match(text, /Do not skip Goal Contract, verification, Devil's Advocate, or Judge/, rel);
233
+ assert.match(text, /generate-workflow/, rel);
234
+ }
235
+ });
236
+
213
237
  test('generate-adapter skill is Claude-safe and shipped adapters stay generic', () => {
214
238
  const skill = readRepo('adapters/generate-adapter/SKILL.md');
215
239
  const { fm } = parseFrontmatter(skill, 'generate-adapter');
@@ -102,7 +102,7 @@ test('dry-run does not write; second apply is current', () => {
102
102
  assert.ok(!fs.existsSync(path.join(home, '.gemini/config/skills/ai-engineering-loop/SKILL.md')));
103
103
  applyHostSync({ packageRoot: ROOT, home });
104
104
  const again = applyHostSync({ packageRoot: ROOT, home });
105
- assert.strictEqual(summarizeHostSync(again.filter((item) => item.id === 'gemini')).current, 3);
105
+ assert.strictEqual(summarizeHostSync(again.filter((item) => item.id === 'gemini')).current, 4);
106
106
  assert.strictEqual(summarizeHostSync(again.filter((item) => item.id === 'gemini')).copy, 0);
107
107
  });
108
108
 
@@ -135,6 +135,7 @@ test('CLI help lists sync-hosts', () => {
135
135
  const out = execFileSync('node', [CLI, '--help'], { encoding: 'utf8' });
136
136
  assert.match(out, /sync-hosts/);
137
137
  assert.match(out, /generate-adapter/);
138
+ assert.match(out, /generate-workflow/);
138
139
  });
139
140
 
140
141
  test('sync upserts generate-adapter onto Claude, Grok, and Gemini', () => {
@@ -149,3 +150,19 @@ test('sync upserts generate-adapter onto Claude, Grok, and Gemini', () => {
149
150
  assert.doesNotMatch(claude, /```mermaid/);
150
151
  assert.match(grok, /^user-invocable: true$/m);
151
152
  });
153
+
154
+ test('sync upserts generate-workflow onto Claude, Grok, and Gemini', () => {
155
+ const home = tmpHome();
156
+ fs.mkdirSync(path.join(home, '.claude'));
157
+ fs.mkdirSync(path.join(home, '.grok'));
158
+ fs.mkdirSync(path.join(home, '.gemini'));
159
+ applyHostSync({ packageRoot: ROOT, home });
160
+ const claude = fs.readFileSync(path.join(home, '.claude/skills/generate-workflow/SKILL.md'), 'utf8');
161
+ const grok = fs.readFileSync(path.join(home, '.grok/skills/generate-workflow/SKILL.md'), 'utf8');
162
+ const gemini = fs.readFileSync(path.join(home, '.gemini/config/skills/generate-workflow/SKILL.md'), 'utf8');
163
+ assert.match(claude, /name: generate-workflow/);
164
+ assert.doesNotMatch(claude, /```mermaid/);
165
+ assert.match(claude, /lessons\.md/);
166
+ assert.match(grok, /^user-invocable: true$/m);
167
+ assert.match(gemini, /Do not start Maker/);
168
+ });