ai-engineering-loop 1.0.15 → 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 +5 -3
- package/.gemini/skills/ai-engineering-loop/SKILL.md +5 -3
- package/.grok/commands/ai-engineering-loop.md +1 -1
- package/.grok/skills/ai-engineering-loop/SKILL.md +4 -4
- package/README.md +23 -10
- package/adapters/README.md +29 -0
- package/adapters/generate-adapter/SKILL.md +123 -0
- package/adapters/generate-workflow/SKILL.md +128 -0
- package/adapters/github/README.md +28 -0
- package/adapters/github/pull-request.md +23 -0
- package/adapters/gitlab/README.md +28 -0
- package/adapters/gitlab/merge-request.md +26 -0
- package/adapters/standard/README.md +44 -0
- package/bin/ai-engineering-loop.js +63 -4
- package/core/context-impact-assessment.md +1 -0
- package/core/repo-config-schema.md +14 -1
- package/lib/generate-adapter.js +118 -0
- package/lib/generate-workflow.js +203 -0
- package/lib/sync-hosts.js +7 -1
- package/package.json +1 -1
- package/templates/repo-config/adapter.md +1 -1
- package/templates/repo-config/lessons.md +8 -0
- package/templates/repo-config/workflow.md +20 -0
- package/tests/generate-adapter.test.js +80 -0
- package/tests/generate-workflow.test.js +109 -0
- package/tests/living-context.test.js +15 -0
- package/tests/skill-host-compat.test.js +45 -0
- package/tests/sync-hosts.test.js +32 -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: `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.
|
|
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, or a task description.
|
|
11
|
+
Arguments: init, status, refresh, sync-hosts, generate-adapter, generate-workflow, or a task description.
|
|
@@ -24,14 +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`: 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
|
+
- `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.
|
|
28
30
|
- Any other argument: full loop for that task.
|
|
29
31
|
|
|
30
32
|
## Loop
|
|
31
33
|
|
|
32
34
|
Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as **siblings**, not nested.
|
|
33
35
|
|
|
34
|
-
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.
|
|
35
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.
|
|
36
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.
|
|
37
39
|
4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
|
|
@@ -43,7 +45,7 @@ Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as *
|
|
|
43
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.
|
|
44
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".
|
|
45
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).
|
|
46
|
-
9. Stage 8: delivery from `.ai-engineering-loop/adapter.md`.
|
|
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.
|
|
47
49
|
|
|
48
50
|
## Report header
|
|
49
51
|
|
|
@@ -19,12 +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`: 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
|
+
- `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.
|
|
23
25
|
- Any other argument: full loop for that task.
|
|
24
26
|
|
|
25
27
|
## Loop
|
|
26
28
|
|
|
27
|
-
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.
|
|
28
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.
|
|
29
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.
|
|
30
32
|
4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid.
|
|
@@ -36,7 +38,7 @@ Canonical mode ids: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_
|
|
|
36
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.
|
|
37
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".
|
|
38
40
|
8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate.
|
|
39
|
-
9. Stage 8: delivery from `.ai-engineering-loop/adapter.md`.
|
|
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.
|
|
40
42
|
|
|
41
43
|
## Report header
|
|
42
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` → 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`
|
|
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.
|
|
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
|
|
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
|
|
|
@@ -180,9 +180,19 @@ npx ai-engineering-loop run
|
|
|
180
180
|
|
|
181
181
|
# Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
182
182
|
npx ai-engineering-loop sync-hosts
|
|
183
|
+
|
|
184
|
+
# Grill (or --type) a Stage 8 delivery adapter for this repo
|
|
185
|
+
npx ai-engineering-loop generate-adapter
|
|
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
|
|
183
191
|
```
|
|
184
192
|
|
|
185
|
-
|
|
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.
|
|
194
|
+
|
|
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.
|
|
186
196
|
|
|
187
197
|
---
|
|
188
198
|
|
|
@@ -329,13 +339,14 @@ ai-engineering-loop/
|
|
|
329
339
|
│ ├── evidence-policy.md # 5-level evidence hierarchy & Verification Evidence Contract
|
|
330
340
|
│ └── no-progress-policy.md # Finding signature hashing & stagnation detection
|
|
331
341
|
│
|
|
332
|
-
├── adapters/ # Pluggable delivery
|
|
333
|
-
│
|
|
334
|
-
│
|
|
335
|
-
│
|
|
336
|
-
│
|
|
337
|
-
│
|
|
338
|
-
│
|
|
342
|
+
├── adapters/ # Pluggable Stage 8 delivery (not a second OS)
|
|
343
|
+
│ ├── README.md # Catalog: standard, github, gitlab, dot
|
|
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
|
|
346
|
+
│ ├── standard/ # Generic git delivery (any forge)
|
|
347
|
+
│ ├── github/ # gh pr / GitHub Issues
|
|
348
|
+
│ ├── gitlab/ # glab mr (not the DOT pipeline)
|
|
349
|
+
│ └── dot/ # DOT-specific GitLab + multi-branch + chat
|
|
339
350
|
│
|
|
340
351
|
└── templates/ # Starter templates for target repositories
|
|
341
352
|
└── repo-config/ # Ready-to-copy .ai-engineering-loop/ files
|
|
@@ -345,7 +356,9 @@ ai-engineering-loop/
|
|
|
345
356
|
├── adr-readme.md # ADR folder template
|
|
346
357
|
├── conventions.md # Code standards & forbidden patterns
|
|
347
358
|
├── verification.md # CLI test/lint/build commands
|
|
348
|
-
|
|
359
|
+
├── adapter.md # Configured release pipeline
|
|
360
|
+
├── workflow.md # Optional loop overlay hooks
|
|
361
|
+
└── lessons.md # Optional confirmed process lessons
|
|
349
362
|
```
|
|
350
363
|
|
|
351
364
|
---
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Delivery adapters
|
|
2
|
+
|
|
3
|
+
Stages 0–7 are the same on every host. **Stage 8 is the only place that knows your forge.**
|
|
4
|
+
|
|
5
|
+
An adapter is not a second engineering OS. It runs **after Judge `PASS`**. It must not start Maker, amend the Goal Contract, or skip Devil's Advocate.
|
|
6
|
+
|
|
7
|
+
## Shipped types
|
|
8
|
+
|
|
9
|
+
| Type | Use when | Spec |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| **`standard`** | Default. Any git repo. No company tools assumed. | [`standard/`](standard/) |
|
|
12
|
+
| **`github`** | `github.com` remote, `gh` CLI | [`github/`](github/) |
|
|
13
|
+
| **`gitlab`** | GitLab.com or self-hosted GitLab (not DOT) | [`gitlab/`](gitlab/) |
|
|
14
|
+
| **`dot`** | DOT delivery (GitLab + multi-branch + Coreview + Mattermost) | [`dot/`](dot/) |
|
|
15
|
+
|
|
16
|
+
Pick one with `npx ai-engineering-loop generate-adapter`. The agent **asks** (grill). Do not copy a neighbour's adapter.
|
|
17
|
+
|
|
18
|
+
Custom tools (Linear, Slack, Bitbucket): still start from `standard`, then name those tools in `.ai-engineering-loop/adapter.md`. Do not put secrets in the file.
|
|
19
|
+
|
|
20
|
+
## Generate
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npx ai-engineering-loop generate-adapter
|
|
24
|
+
npx ai-engineering-loop generate-adapter --type github
|
|
25
|
+
```
|
|
26
|
+
|
|
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,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: generate-adapter
|
|
3
|
+
description: Grill then write a Stage 8 delivery adapter for this repo. Use when the user says generate-adapter, buat adapter, or each team needs its own forge. Not a substitute for ai-engineering-loop.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Generate Adapter
|
|
7
|
+
|
|
8
|
+
Write **this repo's** Stage 8 delivery adapter. Every team has different tools. Do not copy DOT, and do not invent Slack/Jira/bots the user did not name.
|
|
9
|
+
|
|
10
|
+
This skill is not the engineering OS. After the adapter file exists, commit-bound work still runs `ai-engineering-loop`. Stage 8 reads the file 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/adapter.md` until:
|
|
17
|
+
|
|
18
|
+
1. Look-up is done (remote, CI, existing adapter).
|
|
19
|
+
2. Q1–Q5 are on screen with a recommended answer.
|
|
20
|
+
3. The user has answered or waived.
|
|
21
|
+
|
|
22
|
+
## When to use
|
|
23
|
+
|
|
24
|
+
- `generate-adapter`, `buat adapter`, `adapter sendiri`
|
|
25
|
+
- `.ai-engineering-loop/adapter.md` missing, `adapter_type` unknown, or Stage 8 would have to guess
|
|
26
|
+
- The user wants GitHub / GitLab / standard / custom delivery
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
## Host notes
|
|
31
|
+
|
|
32
|
+
Claude Code / Kiro: no mermaid, no LaTeX, no extra tool keys.
|
|
33
|
+
|
|
34
|
+
Grok: do not spawn children. Stay in the parent.
|
|
35
|
+
|
|
36
|
+
Look up facts. Grill only **decisions**.
|
|
37
|
+
|
|
38
|
+
## Steps
|
|
39
|
+
|
|
40
|
+
### 1. Look up
|
|
41
|
+
|
|
42
|
+
Read, in order. Skip if missing.
|
|
43
|
+
|
|
44
|
+
1. `git remote -v` and `.git/config`
|
|
45
|
+
2. `.github/workflows/`, `.gitlab-ci.yml`
|
|
46
|
+
3. `.ai-engineering-loop/adapter.md`
|
|
47
|
+
4. Shipped specs: `adapters/standard/`, `adapters/github/`, `adapters/gitlab/`, `adapters/dot/` (in the ai-engineering-loop package)
|
|
48
|
+
|
|
49
|
+
Or run `npx ai-engineering-loop generate-adapter` and use its detected block.
|
|
50
|
+
|
|
51
|
+
Cite the remote host. Do not ask what git already shows.
|
|
52
|
+
|
|
53
|
+
Recommended type:
|
|
54
|
+
|
|
55
|
+
- `github.com` → `github`
|
|
56
|
+
- GitLab host that is not a named company adapter → `gitlab`
|
|
57
|
+
- no remote / unknown → `standard`
|
|
58
|
+
- user said they need the DOT pipeline → `dot` (load `adapters/dot/`, do not invent extra tools)
|
|
59
|
+
|
|
60
|
+
### 2. Grill (wait)
|
|
61
|
+
|
|
62
|
+
Ask all five in one round. Number them. Give Recommended. Wait.
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Q1 - Forge: github | gitlab | standard (git only) | custom
|
|
66
|
+
Recommended: <from look-up>
|
|
67
|
+
|
|
68
|
+
Q2 - Open the change with: gh | glab | human copies the URL
|
|
69
|
+
Recommended: <binary that exists, else human>
|
|
70
|
+
|
|
71
|
+
Q3 - Extra environment branches after the default: none | list them
|
|
72
|
+
Recommended: none
|
|
73
|
+
|
|
74
|
+
Q4 - Notify after the PR/MR: none | name the tool you already use
|
|
75
|
+
Recommended: none
|
|
76
|
+
|
|
77
|
+
Q5 - Issue tracker: github | gitlab | none | name it
|
|
78
|
+
Recommended: same as forge, or none
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
If the user picks **custom**, they must name the tools. Do not fill Linear/Slack/Bitbucket unless they said so.
|
|
82
|
+
|
|
83
|
+
### 3. Write
|
|
84
|
+
|
|
85
|
+
Write `.ai-engineering-loop/adapter.md` (create `.ai-engineering-loop/` if needed).
|
|
86
|
+
|
|
87
|
+
- `adapter_type`: `standard` | `github` | `gitlab` | `dot` | `custom`
|
|
88
|
+
- `spec`: shipped folder (`adapters/github/`) or `.ai-engineering-loop/adapter/delivery.md` for custom
|
|
89
|
+
- remote, default branch, ci_provider from look-up
|
|
90
|
+
- extra branches and notify only if the user named them
|
|
91
|
+
- no tokens, no webhooks with secrets, no coworker handles, no internal ticket URLs
|
|
92
|
+
|
|
93
|
+
If `custom`, also write `.ai-engineering-loop/adapter/delivery.md` from their answers, following the same hard gate as `adapters/standard/` (Judge PASS first, no silent installs).
|
|
94
|
+
|
|
95
|
+
Headless alternative the user can run:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
npx ai-engineering-loop generate-adapter --type github
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`--type` skips this interview. Do not pass `--type` yourself unless they waived the grill.
|
|
102
|
+
|
|
103
|
+
### 4. Stop
|
|
104
|
+
|
|
105
|
+
Print the path written and the type. Do not start Maker. Do not open a PR.
|
|
106
|
+
|
|
107
|
+
## Output
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
Generate adapter
|
|
111
|
+
Detected: <remote> <ci>
|
|
112
|
+
Questions: Q1..Q5 with Recommended
|
|
113
|
+
Wrote: .ai-engineering-loop/adapter.md (type=<type>)
|
|
114
|
+
Next: /ai-engineering-loop for product work. Stage 8 uses this file.
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Forbidden
|
|
118
|
+
|
|
119
|
+
- Copying `adapters/dot/` onto a non-DOT repo
|
|
120
|
+
- Inventing company chat, review bots, or extra branches
|
|
121
|
+
- Mermaid or LaTeX
|
|
122
|
+
- Putting secrets or private ticket URLs in adapter.md
|
|
123
|
+
- Running the 8-stage product loop inside this skill
|
|
@@ -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
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# GitHub delivery adapter
|
|
2
|
+
|
|
3
|
+
Stage 8 after Judge `PASS` on GitHub-hosted repos.
|
|
4
|
+
|
|
5
|
+
This is not the engineering OS. Do not run Maker. Do not skip Devil's Advocate or Judge.
|
|
6
|
+
|
|
7
|
+
Requires `gh` authenticated to the current remote. If `gh` is missing, fall back to [`../standard/`](../standard/) and print the compare URL.
|
|
8
|
+
|
|
9
|
+
## Steps
|
|
10
|
+
|
|
11
|
+
1. Re-run `.ai-engineering-loop/verification.md` if the log is stale.
|
|
12
|
+
2. Commit the surgical diff. Push the topic branch. Never push the default branch.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
git push -u origin HEAD
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
3. Optional issue if none is linked (branch name, `Fixes #n`, or `gh issue list`):
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
gh issue create --title "<summary>" --body "<Goal Contract path and AC list>"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
4. Open the pull request. Follow [`pull-request.md`](pull-request.md).
|
|
25
|
+
|
|
26
|
+
5. Extra branches, review bots, and chat are **off** unless `.ai-engineering-loop/adapter.md` names them. Do not invent Actions secrets or Slack webhooks.
|
|
27
|
+
|
|
28
|
+
6. Stop. The human merges on GitHub.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# GitHub pull request
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
gh pr create \
|
|
5
|
+
--title "<type>(<scope>): <summary>" \
|
|
6
|
+
--body "$(cat <<'EOF'
|
|
7
|
+
## Goal Contract
|
|
8
|
+
`.ai-engineering-loop/tasks/goal-contract.md` (or the path this repo uses)
|
|
9
|
+
|
|
10
|
+
## What changed
|
|
11
|
+
- <root cause or behaviour>
|
|
12
|
+
- <edge cases>
|
|
13
|
+
- <tests added>
|
|
14
|
+
|
|
15
|
+
## Verification
|
|
16
|
+
Commands from `.ai-engineering-loop/verification.md` (exit 0).
|
|
17
|
+
EOF
|
|
18
|
+
)"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Link an issue with `Fixes #n` in the body when an issue exists.
|
|
22
|
+
|
|
23
|
+
Do not paste raw diffs, tokens, or local machine paths.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# GitLab delivery adapter
|
|
2
|
+
|
|
3
|
+
Stage 8 after Judge `PASS` on GitLab.com or self-hosted GitLab.
|
|
4
|
+
|
|
5
|
+
This is the **generic** GitLab adapter. It is not the DOT adapter. Do not load `adapters/dot/`. No extra environment cherry-picks unless `.ai-engineering-loop/adapter.md` lists those branches.
|
|
6
|
+
|
|
7
|
+
Requires `glab` authenticated to the current remote. If `glab` is missing, fall back to [`../standard/`](../standard/) and print the branch name.
|
|
8
|
+
|
|
9
|
+
## Steps
|
|
10
|
+
|
|
11
|
+
1. Re-run `.ai-engineering-loop/verification.md` if the log is stale.
|
|
12
|
+
2. Commit the surgical diff. Push the topic branch. Never push the default branch.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
git push -u origin HEAD
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
3. Optional issue if none is linked:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
glab issue create --title "<summary>" --description "<Goal Contract path and AC list>" --yes
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
4. Open the merge request. Follow [`merge-request.md`](merge-request.md).
|
|
25
|
+
|
|
26
|
+
5. Extra environments and chat notifications stay off unless `adapter.md` lists them.
|
|
27
|
+
|
|
28
|
+
6. Stop. The human merges on GitLab.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# GitLab merge request
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
glab mr create \
|
|
5
|
+
--source-branch <branch-name> \
|
|
6
|
+
--target-branch <default-branch> \
|
|
7
|
+
--title "<type>(<scope>): <summary>" \
|
|
8
|
+
--description "$(cat <<'EOF'
|
|
9
|
+
## Goal Contract
|
|
10
|
+
`.ai-engineering-loop/tasks/goal-contract.md` (or the path this repo uses)
|
|
11
|
+
|
|
12
|
+
## What changed
|
|
13
|
+
- <root cause or behaviour>
|
|
14
|
+
- <edge cases>
|
|
15
|
+
- <tests added>
|
|
16
|
+
|
|
17
|
+
## Verification
|
|
18
|
+
Commands from `.ai-engineering-loop/verification.md` (exit 0).
|
|
19
|
+
EOF
|
|
20
|
+
)" \
|
|
21
|
+
--yes
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Link the issue URL in the description when an issue exists.
|
|
25
|
+
|
|
26
|
+
Do not paste raw diffs, tokens, or local machine paths.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Standard delivery adapter
|
|
2
|
+
|
|
3
|
+
General Stage 8 for any git project. No GitHub, GitLab, Slack, or company bot is required.
|
|
4
|
+
|
|
5
|
+
Use this when the remote is unknown, the human merges by hand, or you have not generated a forge-specific adapter yet.
|
|
6
|
+
|
|
7
|
+
## Hard gate
|
|
8
|
+
|
|
9
|
+
Do not commit, push, or open a change request until Judge `PASS`.
|
|
10
|
+
|
|
11
|
+
If `.ai-engineering-loop/adapter.md` names a more specific type (`github`, `gitlab`, `dot`), follow that spec instead.
|
|
12
|
+
|
|
13
|
+
## Steps
|
|
14
|
+
|
|
15
|
+
1. Read `.ai-engineering-loop/verification.md`. Re-run those commands if the last log is stale. Keep exit codes.
|
|
16
|
+
2. Commit only the surgical diff for this Goal Contract.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
git status
|
|
20
|
+
git diff
|
|
21
|
+
git add <modified-files>
|
|
22
|
+
git commit -m "<type>(<scope>): <summary>"
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
3. Push the topic branch. Do not push to `main` / `master` / the default branch.
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
git push -u origin HEAD
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
4. Open a change request **with the tool that already exists**, or stop and give the human the compare URL:
|
|
32
|
+
- `gh pr create` if GitHub and `gh` works
|
|
33
|
+
- `glab mr create` if GitLab and `glab` works
|
|
34
|
+
- otherwise print `git remote -v` and the branch name; the human opens the PR/MR
|
|
35
|
+
5. Do not cherry-pick to extra environments unless `adapter.md` lists those branches.
|
|
36
|
+
6. Do not send chat notifications unless `adapter.md` names a channel and a tool. Never invent a webhook or token.
|
|
37
|
+
7. Stop. Merge is a human action unless the user already said to merge.
|
|
38
|
+
|
|
39
|
+
## Best practice
|
|
40
|
+
|
|
41
|
+
- One branch, one change request, default branch only.
|
|
42
|
+
- Link the Goal Contract path in the PR/MR body (not the whole chat).
|
|
43
|
+
- No secrets, no internal hostnames, no coworker handles in the description.
|
|
44
|
+
- If the forge CLI is missing, do not install it silently. Tell the user.
|