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 +1 -1
- package/.agents/workflows/ai-engineering-loop.md +5 -3
- package/.claude/agents/judge.md +1 -1
- package/.claude/commands/ai-engineering-loop.md +1 -1
- package/.claude/skills/ai-engineering-loop/SKILL.md +10 -6
- package/.gemini/skills/ai-engineering-loop/SKILL.md +10 -6
- package/.grok/agents/judge.md +1 -1
- package/.grok/commands/ai-engineering-loop.md +1 -1
- package/.grok/skills/ai-engineering-loop/SKILL.md +10 -7
- package/README.md +14 -4
- package/adapters/README.md +2 -0
- package/adapters/generate-workflow/SKILL.md +134 -0
- package/agents/maker.md +1 -0
- package/agents/shared/judge.body.md +1 -1
- package/bin/ai-engineering-loop.js +34 -3
- package/core/context-impact-assessment.md +1 -0
- package/core/goal-contract.md +1 -0
- package/core/grill-policy.md +11 -0
- package/core/handoff-policy.md +1 -0
- package/core/repo-config-schema.md +15 -1
- package/core/verification-loop.md +23 -0
- package/lib/claimed-vs-reality.js +37 -0
- package/lib/generate-workflow.js +233 -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 +25 -0
- package/tests/claimed-vs-reality.test.js +27 -0
- package/tests/generate-workflow.test.js +179 -0
- package/tests/living-context.test.js +15 -0
- package/tests/skill-host-compat.test.js +78 -0
- package/tests/sync-hosts.test.js +18 -1
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
|
-
|
|
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.
|
package/.claude/agents/judge.md
CHANGED
|
@@ -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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
|
package/.grok/agents/judge.md
CHANGED
|
@@ -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
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
[](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
|
|
|
@@ -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-
|
|
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
|
-
|
|
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
|
---
|
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,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
|
-
|
|
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.
|
|
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
|
|
package/core/goal-contract.md
CHANGED
|
@@ -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.
|
package/core/grill-policy.md
CHANGED
|
@@ -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.
|
package/core/handoff-policy.md
CHANGED
|
@@ -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
|
|