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.
- package/.agents/workflows/ai-engineering-loop.md +1 -1
- package/.claude/commands/ai-engineering-loop.md +1 -1
- package/.claude/skills/ai-engineering-loop/SKILL.md +4 -3
- package/.gemini/skills/ai-engineering-loop/SKILL.md +4 -3
- package/.grok/commands/ai-engineering-loop.md +1 -1
- package/.grok/skills/ai-engineering-loop/SKILL.md +4 -4
- package/README.md +10 -3
- package/adapters/README.md +2 -0
- package/adapters/generate-workflow/SKILL.md +128 -0
- package/bin/ai-engineering-loop.js +34 -3
- package/core/context-impact-assessment.md +1 -0
- package/core/repo-config-schema.md +13 -0
- package/lib/generate-workflow.js +203 -0
- package/lib/sync-hosts.js +4 -1
- package/package.json +1 -1
- package/templates/repo-config/lessons.md +8 -0
- package/templates/repo-config/workflow.md +20 -0
- package/tests/generate-workflow.test.js +109 -0
- package/tests/living-context.test.js +15 -0
- package/tests/skill-host-compat.test.js +24 -0
- package/tests/sync-hosts.test.js +18 -1
|
@@ -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
|
[](https://opensource.org/licenses/MIT)
|
|
7
7
|
[](https://github.com/egagofur/ai-engineering-loop/pulls)
|
|
8
8
|
[](https://github.com/egagofur/ai-engineering-loop)
|
|
9
|
-
[](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-
|
|
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
|
-
|
|
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
|
---
|
package/adapters/README.md
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
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
|
@@ -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');
|
package/tests/sync-hosts.test.js
CHANGED
|
@@ -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,
|
|
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
|
+
});
|