ai-engineering-loop 1.0.16 → 1.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.agents/judge.md CHANGED
@@ -16,7 +16,7 @@ Use only paths in the spawn prompt: Goal Contract, verification evidence, Findin
16
16
 
17
17
  AC source is the Goal Contract **file** only. Chat `setuju` and the parent transcript are not AC. Do not PASS because the parent agreed in chat. `CONTEXT_ISOLATION_ONLY` does not relax this.
18
18
 
19
- ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows.
19
+ ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows. ITERATE if claimed-vs-reality.md is missing or a Claimed row has empty Reality.
20
20
 
21
21
  ## Axes
22
22
 
@@ -5,14 +5,16 @@ description: Run the AI Engineering Loop on Antigravity (init, status, refresh,
5
5
 
6
6
  Follow `policies/review-budget.md`. Parent is Maker plus orchestrator. Do not use `browser_subagent`.
7
7
 
8
- Stage 1: if the user asks for ideas, list a short menu and wait; do not implement. Grill if the task is ambiguous (`core/grill-policy.md`), then freeze the Goal Contract file. Chat agreement is not freeze. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Use `.ai-engineering-loop/glossary.md`. Name test seams. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. Maker: TDD at those seams (`policies/tdd-policy.md`): one red test per AC row. Bugs: red repro first (`core/root-cause-analysis.md`). Mid-loop stop: `core/handoff-policy.md`.
8
+ Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge.
9
+
10
+ Stage 1: if the user asks for ideas, list a short menu and wait; do not implement. Grill if the task is ambiguous (`core/grill-policy.md`), then freeze the Goal Contract file. Chat agreement is not freeze. If the user prompt has no numbered AC, draft `.ai-engineering-loop/tasks/goal-contract.md` with a failure table, show it, wait for freeze. Do not start Maker. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Use `.ai-engineering-loop/glossary.md`. Name test seams. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. Stages 2-4: Read `maker_intern` from workflow.md (missing or none = parent is Maker). If a label is set, write `.ai-engineering-loop/tasks/maker-brief.md` and spawn intern only with tools that already exist. If spawn cannot select that intern, parent is Maker; say intern INVOCATION_UNAVAILABLE. Intern cannot skip verification, Devil's Advocate, or Judge. Maker: TDD at those seams (`policies/tdd-policy.md`): one red test per AC row. Bugs: red repro first (`core/root-cause-analysis.md`). Mid-loop stop: `core/handoff-policy.md`.
9
11
 
10
12
  If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as siblings. Wait for each child. Do not run them in the background. Use `general-purpose` only if the named type is rejected.
11
13
 
12
- 5. Before Devil's Advocate: write `git diff` to `.ai-engineering-loop/tasks/current.diff` and put `git diff --name-only` in the child prompt. Do not paste Maker rationale.
14
+ 5. Before Devil's Advocate: write `git diff` to `.ai-engineering-loop/tasks/current.diff` and put `git diff --name-only` in the child prompt. Do not paste Maker rationale. Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` (AC, Claimed, Reality from command log). Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
13
15
  6. Devil's Advocate 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.
14
16
  7. Judge 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".
15
17
 
16
18
  If no subagent tool exists, run the same budgets in this session as CONTEXT_ISOLATION_ONLY. Do not claim independent agent execution.
17
19
 
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.
20
+ Init/status/refresh/sync-hosts/generate-adapter/generate-workflow: `npx ai-engineering-loop <command>`. generate-workflow grills Q1-Q6. 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.
@@ -17,7 +17,7 @@ Use only paths in the spawn prompt: Goal Contract, verification evidence, Findin
17
17
 
18
18
  AC source is the Goal Contract **file** only. Chat `setuju` and the parent transcript are not AC. Do not PASS because the parent agreed in chat. `CONTEXT_ISOLATION_ONLY` does not relax this.
19
19
 
20
- ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows.
20
+ ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows. ITERATE if claimed-vs-reality.md is missing or a Claimed row has empty Reality.
21
21
 
22
22
  ## Axes
23
23
 
@@ -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,27 +24,31 @@ 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-Q6. 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
 
34
+ Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge.
35
+
33
36
  Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as **siblings**, not nested.
34
37
 
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
- 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
- 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
- 4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
38
+ 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.
39
+ 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. If the user prompt has no numbered AC, draft `.ai-engineering-loop/tasks/goal-contract.md` with a failure table, show it, wait for freeze. Do not start Maker.
40
+ 3. Stages 2-4: Read `maker_intern` from workflow.md (missing or none = parent is Maker). If a label is set, write `.ai-engineering-loop/tasks/maker-brief.md` (Goal Contract path, seams, files in scope) and spawn that intern only with Task/Agent using the same allowed keys as Devil's Advocate. Do not add a model key or HTTP client. If the host cannot select that intern, the parent is Maker; say intern INVOCATION_UNAVAILABLE. Intern cannot skip verification, Devil's Advocate, or Judge. After intern returns, parent runs Stage 5. 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.
41
+ 4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid. Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` (AC, Claimed, Reality from command log). Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
39
42
  5. Write artifacts, then spawn. Before Devil's Advocate:
40
43
  - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
41
44
  - Write changed paths (`git diff --name-only`) into the Task prompt as a short list.
42
45
  - Put those paths in the child prompt. Do not paste Maker rationale.
46
+ - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
43
47
  - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
44
48
  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
49
  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
50
  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.
51
+ 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
52
 
49
53
  ## Report header
50
54
 
@@ -19,25 +19,29 @@ 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-Q6. 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
- 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
- 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
- 4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
29
+ Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge.
30
+
31
+ 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.
32
+ 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. If the user prompt has no numbered AC, draft `.ai-engineering-loop/tasks/goal-contract.md` with a failure table, show it, wait for freeze. Do not start Maker.
33
+ 3. Stages 2-4: Read `maker_intern` from workflow.md (missing or none = parent is Maker). If a label is set, write `.ai-engineering-loop/tasks/maker-brief.md` (Goal Contract path, seams, files in scope) and spawn that intern only with tools that already exist. Do not add HTTP clients or API keys. If the host cannot select that intern, the parent is Maker; say intern INVOCATION_UNAVAILABLE. Intern cannot skip verification, Devil's Advocate, or Judge. After intern returns, parent runs Stage 5. 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.
34
+ 4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid. Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` (AC, Claimed, Reality from command log). Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
32
35
  5. Write artifacts, then spawn. Before Devil's Advocate:
33
36
  - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
34
37
  - Write changed paths (`git diff --name-only`) into the child prompt as a short list.
35
38
  - Put those paths in the child prompt. Do not paste Maker rationale.
39
+ - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
36
40
  - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
37
41
  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
42
  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
43
  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.
44
+ 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
45
 
42
46
  ## Report header
43
47
 
@@ -18,7 +18,7 @@ Use only paths in the spawn prompt: Goal Contract, verification evidence, Findin
18
18
 
19
19
  AC source is the Goal Contract **file** only. Chat `setuju` and the parent transcript are not AC. Do not PASS because the parent agreed in chat. `CONTEXT_ISOLATION_ONLY` does not relax this.
20
20
 
21
- ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows.
21
+ ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows. ITERATE if claimed-vs-reality.md is missing or a Claimed row has empty Reality.
22
22
 
23
23
  ## Axes
24
24
 
@@ -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,25 +38,28 @@ 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-Q6. 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.
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
- 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
- 4. Stage 5: run verification from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
47
+ Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge.
48
+
49
+ 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.
50
+ 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. If the user prompt has no numbered AC, draft `.ai-engineering-loop/tasks/goal-contract.md` with a failure table, show it, wait for freeze. Do not start Maker.
51
+ 3. Stages 2–4: Read `maker_intern` from workflow.md (missing or none = parent is Maker). If a label is set, write `.ai-engineering-loop/tasks/maker-brief.md` and spawn that intern as a sibling (`background: false`, wait). Pass a model key only if that key exists on the spawn schema. Do not invent keys, HTTP clients, or API keys. Intern must not spawn DA or Judge (depth 1). After intern returns, parent runs Stage 5 then DA/Judge. If intern spawn is unavailable, parent is Maker; say intern INVOCATION_UNAVAILABLE. Intern cannot skip verification, Devil's Advocate, or Judge. 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.
52
+ 4. Stage 5: run verification from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid. Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` (AC, Claimed, Reality from command log). Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
51
53
  5. Write artifacts to disk so children do not need parent chat:
52
54
  - Goal Contract path
53
55
  - `git diff` written to `.ai-engineering-loop/tasks/current.diff`
54
56
  - verification log (file)
57
+ - `.ai-engineering-loop/tasks/claimed-vs-reality.md` (do not spawn DA without it)
55
58
  - If stopping mid-loop, `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`)
56
59
  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
60
  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
61
  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.
62
+ 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
63
 
61
64
  After a proven Grok DA spawn, the report header must be:
62
65
 
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.18-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
 
@@ -64,12 +64,15 @@ The 8-stage loop stays one OS. These techniques sit **inside** existing stages (
64
64
 
65
65
  | Stage | Technique | Spec |
66
66
  |---|---|---|
67
- | 1 | Grill until the design-tree frontier is empty, then freeze the Goal Contract. Idea requests: menu, wait, then grill the pick. Chat `setuju` is not freeze; user-visible decisions must be numbered AC in the contract file. AC is a **failure table** (happy, empty/omit, boundary, sibling, error), not sunny path only. Business-logic change: **blast radius** (lifecycle sketch, four pillars, ASCII picture) via `task-impact-inquiry` inside grill — not a second loop. Passing unit tests are not isolation proof. | `core/grill-policy.md` |
67
+ | 1 | Grill until the design-tree frontier is empty, then freeze the Goal Contract. Idea requests: menu, wait, then grill the pick. Chat `setuju` is not freeze; user-visible decisions must be numbered AC in the contract file. AC is a **failure table** (happy, empty/omit, boundary, sibling, error), not sunny path only. **Sloppy prompt** (no numbered AC): draft the Goal Contract file, show it, wait for freeze — do not Maker. Business-logic change: **blast radius** (lifecycle sketch, four pillars, ASCII picture) via `task-impact-inquiry` inside grill — not a second loop. Passing unit tests are not isolation proof. | `core/grill-policy.md` |
68
68
  | 1 | Ubiquitous language in `.ai-engineering-loop/glossary.md`; load-bearing choices in `.ai-engineering-loop/adrs/` | `core/repo-config-schema.md` |
69
69
  | 2 | Bugs: red repro → minimise → hypothesise → instrument → fix | `core/root-cause-analysis.md` |
70
+ | 4 | Optional **Maker intern**: one overlay field `maker_intern`. Default `none` = parent is Maker. Any host-native label (`gemini-flash`, `haiku`, `grok-mini`, `qwen`, …). Not locked to one vendor. No intern API keys. If the host cannot spawn that intern, parent is Maker (`INVOCATION_UNAVAILABLE`). Devil's Advocate and Judge stay on the parent. | `.ai-engineering-loop/workflow.md` |
70
71
  | 4–5 | Red-green at named **seams**; failure table (not happy path only); coverage is a map; no grep/tautology | `policies/tdd-policy.md` |
72
+ | 5 | **Claimed vs Reality** table before DA. Missing file or empty Reality blocks Devil's Advocate. "Seems green" is not Reality. | `core/verification-loop.md` |
71
73
  | 6–7 | Spec vs Standards reported separately. Standards BLOCKER/HIGH iterate only when `hardConvention` is true | `policies/finding-policy.md` |
72
74
  | any | Mid-loop stop writes `.ai-engineering-loop/tasks/handoff.md` | `core/handoff-policy.md` |
75
+ | any | **Compact map** (host guidance, not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge. | host skills |
73
76
 
74
77
  `init` now requires `glossary.md` and `adrs/README.md`. Repair fills missing files only; a filled glossary is never overwritten.
75
78
 
@@ -184,11 +187,15 @@ npx ai-engineering-loop sync-hosts
184
187
  # Grill (or --type) a Stage 8 delivery adapter for this repo
185
188
  npx ai-engineering-loop generate-adapter
186
189
  npx ai-engineering-loop generate-adapter --type github
190
+
191
+ # Grill (or --write) a loop overlay + empty lessons.md for this repo
192
+ npx ai-engineering-loop generate-workflow
193
+ npx ai-engineering-loop generate-workflow --write
187
194
  ```
188
195
 
189
196
  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
197
 
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.
198
+ `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
199
 
193
200
  ---
194
201
 
@@ -338,6 +345,7 @@ ai-engineering-loop/
338
345
  ├── adapters/ # Pluggable Stage 8 delivery (not a second OS)
339
346
  │ ├── README.md # Catalog: standard, github, gitlab, dot
340
347
  │ ├── generate-adapter/SKILL.md # Grill Q1-Q5, then write adapter.md
348
+ │ ├── generate-workflow/SKILL.md # Grill Q1-Q6, then write workflow.md + lessons.md
341
349
  │ ├── standard/ # Generic git delivery (any forge)
342
350
  │ ├── github/ # gh pr / GitHub Issues
343
351
  │ ├── gitlab/ # glab mr (not the DOT pipeline)
@@ -351,7 +359,9 @@ ai-engineering-loop/
351
359
  ├── adr-readme.md # ADR folder template
352
360
  ├── conventions.md # Code standards & forbidden patterns
353
361
  ├── verification.md # CLI test/lint/build commands
354
- └── adapter.md # Configured release pipeline
362
+ ├── adapter.md # Configured release pipeline
363
+ ├── workflow.md # Optional loop overlay hooks
364
+ └── lessons.md # Optional confirmed process lessons
355
365
  ```
356
366
 
357
367
  ---
@@ -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,134 @@
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–Q6 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 six 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
+ Q6 - Maker intern: none | any host-native label (gemini-flash, grok-mini, haiku, qwen, ...)
75
+ Recommended: none
76
+ ```
77
+
78
+ If they name a tool or step, write that name into the matching hook. Do not invent Figma/Jira/Slack unless they said so.
79
+
80
+ Q6 is a host-native label only (`maker_intern` in workflow.md). Not locked to one vendor. Do not paste API keys or URLs. Default none = parent is Maker.
81
+
82
+ ### 3. Write
83
+
84
+ Write `.ai-engineering-loop/workflow.md` (create `.ai-engineering-loop/` if needed).
85
+
86
+ - Required stages listed and not skippable
87
+ - Hooks from Q1–Q3 (`none` if they picked none)
88
+ - **maker_intern** from Q6 (`none` if they picked none)
89
+ - Optional skips only `blast_radius` and/or `generate_adapter`
90
+ - No tokens, no coworker handles, no internal ticket URLs
91
+
92
+ Write `.ai-engineering-loop/lessons.md` only if it is missing. If it already has rows, leave it.
93
+
94
+ Headless alternative the user can run:
95
+
96
+ ```bash
97
+ npx ai-engineering-loop generate-workflow --write
98
+ ```
99
+
100
+ `--write` skips this interview and writes default hooks (`none`) and `maker_intern: none`. Do not pass `--write` yourself unless they waived the grill.
101
+
102
+ ### 4. Lessons during later product work
103
+
104
+ When the user confirms "this is wrong / this is right" and it is not a domain term, a code ban, or an ADR:
105
+
106
+ - Append one row to `lessons.md`
107
+ - Date, lesson, do-not
108
+ - Do not paste the chat
109
+
110
+ Route: term → `glossary.md`. Code ban → `conventions.md`. Load-bearing design → `adrs/`. Process / taste / "user always rejects X" → `lessons.md`.
111
+
112
+ ### 5. Stop
113
+
114
+ Print the paths written. Do not start Maker. Do not open a PR.
115
+
116
+ ## Output
117
+
118
+ ```text
119
+ Generate workflow overlay
120
+ Existing: <workflow yes/no> <lessons yes/no>
121
+ Questions: Q1..Q6 with Recommended
122
+ Wrote: .ai-engineering-loop/workflow.md
123
+ Lessons: .ai-engineering-loop/lessons.md (created or left)
124
+ Next: /ai-engineering-loop for product work. Stage 0 reads these files.
125
+ ```
126
+
127
+ ## Forbidden
128
+
129
+ - Replacing the 8-stage OS
130
+ - Skipping Goal Contract, verification, Devil's Advocate, or Judge
131
+ - Using a second evaluation filename. The file is `lessons.md`
132
+ - Dumping chat into lessons
133
+ - Mermaid or LaTeX
134
+ - Running the 8-stage product loop inside this skill
package/agents/maker.md CHANGED
@@ -42,6 +42,7 @@ flowchart LR
42
42
  2. **CANNOT Alter Acceptance Criteria**: The Maker Agent must never modify the Goal Contract's acceptance criteria to bypass failing tests.
43
43
  3. **CANNOT Suppress Verification Failures**: The Maker Agent is strictly prohibited from adding `@ts-ignore`, `eslint-disable`, mock overrides that mask bugs, or skipping broken tests to achieve green results.
44
44
  4. **CANNOT Make Unsolicited Renovations**: Even if surrounding legacy code is poorly written, the Maker must not refactor untouched modules unless explicitly included in the Goal Contract.
45
+ 5. **CANNOT Skip Review**: A Maker intern (optional `maker_intern` overlay label) cannot skip verification, Devil's Advocate, or Judge. Intern is a cheaper Stage 4 builder only. Default `none` means the parent is Maker. The label is host-native and not locked to one vendor. AEL does not store intern API keys.
45
46
 
46
47
  ---
47
48
 
@@ -10,7 +10,7 @@ Use only paths in the spawn prompt: Goal Contract, verification evidence, Findin
10
10
 
11
11
  AC source is the Goal Contract **file** only. Chat `setuju` and the parent transcript are not AC. Do not PASS because the parent agreed in chat. `CONTEXT_ISOLATION_ONLY` does not relax this.
12
12
 
13
- ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows.
13
+ ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows. ITERATE if claimed-vs-reality.md is missing or a Claimed row has empty Reality.
14
14
 
15
15
  ## Axes
16
16
 
@@ -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.18';
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.18',
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 + intern + 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
 
@@ -112,3 +112,4 @@ Every single item listed under `Acceptance Criteria` must map to at least one co
112
112
  - **The Chat Contract**: Treating "setuju" in the parent transcript as AC. The file is the contract.
113
113
  - **The Wrong Artifact**: Tests pass on a `/tmp` build while the sample the user opens omits the feature.
114
114
  - **The Happy-Path Contract**: Only the sunny case is an AC. Coverage % is not a substitute for a failure table.
115
+ - **The Sloppy Ship**: Implementing from a vague prompt without a drafted failure table in the Goal Contract file.
@@ -45,6 +45,17 @@ Before Maker starts:
45
45
 
46
46
  If a decision was agreed in chat and is missing from the file, the contract is not frozen. Do not start Maker.
47
47
 
48
+ ## Sloppy / underspecified prompts
49
+
50
+ A prompt with no numbered AC (for example "fix login", "bikin aja bagus") is not permission to Maker.
51
+
52
+ 1. Look up facts. Draft `.ai-engineering-loop/tasks/goal-contract.md` with a **failure table** (happy, empty/omit, boundary, sibling, error).
53
+ 2. Show the AC list. Recommended answers already filled.
54
+ 3. Wait for an explicit freeze of that file. Chat `setuju` is **not** a freeze.
55
+ 4. Do not start Maker. Do not treat the draft as frozen.
56
+
57
+ If the prompt already has numbered AC, or a Goal Contract for this task is already frozen on disk, Do not invent a second draft.
58
+
48
59
  ## Business blast radius
49
60
 
50
61
  Green unit tests are not proof that sibling rows, approvals, or downstream jobs survived.
@@ -24,6 +24,7 @@ Overwrite the previous handoff for the active task. Do not commit unless the use
24
24
 
25
25
  ## Verification
26
26
  - last command, exit code, log path (or NOT RUN)
27
+ - claimed-vs-reality.md path (or NOT RUN)
27
28
 
28
29
  ## Review
29
30
  - DA ledger path (or NOT RUN)
@@ -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
@@ -77,7 +79,19 @@ Maintains lightweight state for instant drift detection:
77
79
  - Durable why for load-bearing choices settled in grill. `refresh` does not overwrite existing ADRs.
78
80
 
79
81
  ### 9. `tasks/` — Run artifacts (optional)
80
- - `current.diff`, verification logs, `handoff.md`. Not required for `init` validity.
82
+ - `current.diff`, verification logs, `handoff.md`, `claimed-vs-reality.md`, `maker-brief.md`. Not required for `init` validity.
83
+
84
+ ### 10. `workflow.md` — Loop overlay (optional)
85
+ - Hooks around the 8-stage OS: `before_grill`, `after_freeze`, `after_pass`.
86
+ - Optional `maker_intern` (default `none`). Any host-native label. Not locked to one vendor. Not a key or URL.
87
+ - Cannot skip Goal Contract, verification, Devil's Advocate, or Judge.
88
+ - Missing file means default 8-stage loop (no extra hooks, parent is Maker).
89
+ - Generate with `npx ai-engineering-loop generate-workflow` (grill Q1–Q6) or `--write`.
90
+
91
+ ### 11. `lessons.md` — Confirmed process lessons (optional)
92
+ - One human-confirmed row per lesson. Not a chat transcript. Not `eval.md`.
93
+ - Terms still go to `glossary.md`. Code bans to `conventions.md`. Design why to `adrs/`.
94
+ - `refresh` / `--write` must not overwrite filled lessons.
81
95
 
82
96
  ---
83
97