ai-engineering-loop 2.14.0 → 2.15.0

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.
Files changed (48) hide show
  1. package/.agents/skills/ael/SKILL.md +4 -4
  2. package/.agents/skills/ael/references/loop-commands.md +6 -3
  3. package/.agents/skills/ael/references/loop-deliver.md +1 -0
  4. package/.agents/skills/ael/references/loop-goal.md +7 -4
  5. package/.agents/skills/ael/references/loop-hosts.md +1 -0
  6. package/.agents/skills/ael/references/loop-modes.md +1 -0
  7. package/CHANGELOG.md +31 -1
  8. package/README.md +1 -0
  9. package/adapters/project-onboarding/SKILL.md +2 -0
  10. package/agents/instruction-only/AGENTS.md +1 -1
  11. package/bin/ai-engineering-loop.js +447 -40
  12. package/core/coordinator.md +33 -0
  13. package/core/garden.md +18 -0
  14. package/core/goal-contract.md +23 -1
  15. package/core/overnight-contract.md +62 -0
  16. package/core/prototype-spike.md +28 -0
  17. package/core/root-cause-analysis.md +27 -0
  18. package/core/run-isolation.md +19 -0
  19. package/core/verification-loop.md +2 -0
  20. package/core/verification-one-pager.md +34 -0
  21. package/core/weekly-process-sampling.md +32 -0
  22. package/lib/agent-artifacts.js +6 -0
  23. package/lib/cli-args.js +5 -3
  24. package/lib/design-ref.js +15 -0
  25. package/lib/driver-scaffold.js +1 -1
  26. package/lib/feature-map.js +427 -1
  27. package/lib/features.js +20 -1
  28. package/lib/garden.js +171 -0
  29. package/lib/gates.js +18 -0
  30. package/lib/git-readiness.js +6 -1
  31. package/lib/goal-runtime.js +31 -1
  32. package/lib/harness-audit.js +1 -1
  33. package/lib/issue-repro.js +460 -0
  34. package/lib/learn.js +34 -0
  35. package/lib/overnight.js +179 -0
  36. package/lib/pr-babysit.js +277 -0
  37. package/lib/run-isolation.js +25 -4
  38. package/lib/spike.js +104 -0
  39. package/lib/ste.js +15 -0
  40. package/lib/verification-lanes.js +1 -2
  41. package/package.json +1 -1
  42. package/schemas/goal-contract.schema.json +13 -0
  43. package/README.npm.md +0 -104
  44. package/docs/images/ael-hero.svg +0 -19
  45. package/docs/images/engineering-loop-overview.svg +0 -114
  46. package/docs/images/social-preview.png +0 -0
  47. package/docs/images/studio-hero-orange.svg +0 -136
  48. package/docs/images/studio-hero.svg +0 -136
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ael
3
- description: Use when the user runs /ael, says "run the engineering loop" or "devil's advocate review", asks to init or refresh living project context, or wants the Maker / Devil's Advocate / Judge engineering loop.
3
+ description: Use for a feature or bugfix in a repo with AI Engineering Loop: "please add", "please fix", "fix this bug", "build this feature", "tambahin fitur", "Use AI Engineering Loop", /ael, "run the engineering loop", "devil's advocate review", or init/refresh living project context. A one-line typo or "just change this line" is a direct edit, not this loop.
4
4
  ---
5
5
  <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
6
6
 
@@ -22,7 +22,7 @@ Same skill on every host. Before the first DA or Judge spawn, read your host's s
22
22
 
23
23
  ## Loop
24
24
 
25
- Map (not a second OS) of the 8-stage loop: Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Parent = Maker + orchestrator; Devil's Advocate (DA) and Judge are fresh **siblings**, never nested or resumed. Gate failures override prose. Never edit `state.json`/`current.json`.
25
+ Map (not a second OS) of the 8-stage loop: Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Gate failures override prose. Never edit `state.json`/`current.json`.
26
26
 
27
27
  Tier (from `run --json`; it only rises). Do not skip Goal Contract, verification, Devil's Advocate, or Judge gates; the tier only decides who fills them.
28
28
  - **T0** trivial (docs/typo/lint): `quick start "<task>"` (run + `gate goal`), edit, `quick finish`; no subagents.
@@ -30,14 +30,14 @@ Tier (from `run --json`; it only rises). Do not skip Goal Contract, verification
30
30
  - **T2** risky (HIGH_RISK_PATH, DOT business logic, >10 files): add `loop-risky` (blast radius, Judge on STRONG_MODEL). Unseen risk: `run --new --tier T2 --tier-reason <why>`.
31
31
 
32
32
  0. `run --json [--mode report-only|assisted|unattended]` (`RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present; heed `learnings`.
33
- 1. Goal Contract: `loop-goal`. 2-4. Maker: `loop-maker`, then `gate maker`. 5. Verify: `loop-verify`. 6-7. DA and Judge: `loop-review`. 8. Deliver: `loop-deliver`.
33
+ 1. Goal Contract: `loop-goal` (confirm the git toplevel is the project the human named). 2-4. Maker: `loop-maker`, then `gate maker`. 5. Verify: `loop-verify`. 6-7. DA and Judge: `loop-review`. 8. Deliver: `loop-deliver`.
34
34
 
35
35
  Invariants (every tier):
36
36
  - AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
37
37
  - One red test per AC row (bugs: red repro) before the fix.
38
38
  - Write claimed-vs-reality.md after `gate verification` passes. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
39
39
  - ITERATE to iteration 3 (or the recipe cap), each with a **new** DA.
40
- - Never infer human approval; ask with host buttons (`loop-hosts`).
40
+ - Never infer human approval; ask with host buttons (`loop-hosts`). A cancelled or unanswered question: stop and wait; never freeze yourself.
41
41
  - After each child `budget record` real usage or `--unavailable`; never invent counts.
42
42
  - No secrets or hidden reasoning in activity messages.
43
43
 
@@ -13,15 +13,18 @@ Run these when the user asks how the loop is doing, before planning work, or whe
13
13
  - `stats [--last <n>] [--json]`: failure causes by harness layer (`task_spec`, `context`, `environment`, `verification`, `state`, `model`), false-victory rate per tier, iterations to PASS, revert rate of delivered Runs (from git) and the verification share of tokens. Fix the bottleneck layer first.
14
14
  - `learn --transcripts [--since 30d]`: corrections you repeated across agent chats become candidate lessons (local, redacted; `docs verification-loop` 12).
15
15
  - `learn promote ... --prove <commit>`: the check must fail on the commit that introduced the mistake. `measurement record --ac <id> --runs <n> --spread <pct> --effect <pct> --limiter <text>` for `measure: true` ACs (`docs verification-loop` 3e).
16
- - `run --worktree "<task>"` starts a task in its own git worktree when another Run is unfinished; `worktree prune [--audit] [--include-scratch] [--yes]` removes finished, clean worktrees and merged branches; `pr status --run <id>` reads the PR once and records `merge.json` when merged (`docs run-isolation`).
16
+ - `run --worktree "<task>"` starts a task in its own git worktree when another Run is unfinished; `run --worktree --base <branch> "<task>"` stacks that worktree on a local commit. There is no coordinator process (`docs coordinator`). `worktree prune [--audit] [--include-scratch] [--yes]` removes finished, clean worktrees and merged branches; `pr status --run <id>` reads the PR once and records `merge.json` when merged; `pr babysit --run <id>` polls that PR, starts a T0 or T1 fix on the same branch when checks fail, and leaves the merge to the human (`docs run-isolation`).
17
17
  - `recap [--days N] [--for me|lead|client] [--projects <p,...>|all]`: one HTML page of what shipped, with evidence (`docs recap`). Client recaps take one project.
18
18
  - `outcome record --run <id> --source mr-comment|revert|bug|incident --location <file[:line]> --summary <text> --by <name>`: a problem people found after delivery. Only record what the human reported; never invent one. Then `calibrate` lists DA misses and wrong dismissals per reviewer prompt version.
19
+ - `run --from-issue <url|#n>` reads one GitHub (`gh issue view`) or GitLab (`glab issue view`) issue and drafts a red-repro Goal, then the normal loop. `outcome repro --file <path>` does the same from a pasted report. Both are read-only: never comment or edit the issue (`docs root-cause-analysis`).
19
20
  - `debt [--file <path>]` lists trade-offs the Judge accepted and L3 waivers; `debt close <id> --by <name>` only on the human's word.
20
- - `next`: the next unblocked feature in `.ai-engineering-loop/features.json` and VCR (verified/activated). Finish the active feature before starting another.
21
+ - `next`: the next unblocked feature from `.ai-engineering-loop/features.json`, or from `feature-map.md` when that is the only list, plus VCR (verified/activated). Finish the active feature before starting another. No list: `feature-map scaffold`.
21
22
  - `learn` lists lessons seen in 3+ Runs; a human promotes one with `learn promote <id> --check "<cmd>" --fix "<instruction>" --by <name>`. Default `verify` then runs it as an L1 rule. On a codebase that already has old violations use `--scope diff`: the check reads only added lines from `$AEL_ADDED_LINES_FILE`, so new ones fail and the old ones become a backlog (`doctor --harness`). Common cases need no script: `--forbid-import "src/renderer/** -> src/main/**"` or `--forbid-api "\buseEffect\(" --except "src/framework/**"`.
22
- - `.ai-engineering-loop/feature-map.md` (Feature | Where | Paths | How to reach | Driver): `review-pack` adds the features a diff touches; use those names and drivers for L3 evidence. `driver scaffold [--feature <id>]` writes a reusable driver (launch, drive, observe) per row and fills the Driver column; fill in its `EXPECT` and steps once, then reuse it every Run.
23
+ - `.ai-engineering-loop/feature-map.md` (Feature | Where | Paths | How to reach | Driver): `review-pack` adds the features a diff touches; use those names and drivers for L3 evidence. `feature-map scaffold` drafts the table from routes, OpenAPI, pages, or the README (a stub if none) and never overwrites an edited map (`.ael-new`). `driver scaffold [--feature <id>]` writes a reusable driver (launch, drive, observe) per row and fills the Driver column; fill in its `EXPECT` and steps once, then reuse it every Run.
23
24
  - Dig before asking (`docs dig-first`): `.ai-engineering-loop/sources.md` lists readable sources (read-only); `sources hint` suggests queries, `sources record` caches one line each (budget T0 0, T1 4, T2 8). Goal `statements` label fact/decision/assumption; a fact needs `path:line`, a commit or a recorded `S-n`. Assumptions are shown, never blocking.
24
25
  - `doctor --harness`: harness debt (entry-file size and structure, stale learnings, rule provenance, skill budget). Report findings; do not mass-delete.
26
+ - `refresh --garden` reports stale learnings, dead feature-map rows, and old Runs. It writes nothing until `--yes`. `--yes` never deletes Runs (`docs garden`).
27
+ - Before freeze, one throwaway spike is allowed (`docs prototype-spike`, no arena). The verification map is `docs verification-one-pager`.
25
28
  - `bench --without <integrity|l3|l1|smoke|rules>` measures whether a gate component still earns its cost (`docs bench`). Never use it on a real task.
26
29
 
27
30
  ## Personal workflow
@@ -9,6 +9,7 @@
9
9
  - Commit before `deliver` (its receipt binds `HEAD`; videos/screenshots: `--evidence AC-N=<https-url>`, required for `crossComponent` and rubric ACs). Paste `RUN_DIR/receipt.md` into the PR/MR Receipt section unchanged; ❌ stays ❌ (`docs pr-receipt`).
10
10
  - Only the delivery gate completes the run. It also mines lessons for the next Run.
11
11
  - Worktree Run: after `deliver`, continue in `cleanup.mainCheckout` (Stage 9).
12
+ - After the PR is open, `npx ai-engineering-loop pr babysit --run <runId>` polls with backoff. Failing checks start a T0 or T1 fix on that same branch and push it. Ready to merge, or changes requested, stops for a human. Merge stays with the human (`docs run-isolation`).
12
13
 
13
14
  ## Report header (execution mode)
14
15
 
@@ -1,16 +1,19 @@
1
1
  # Stage 1: Goal Contract
2
2
 
3
+ - Before drafting: `pwd` and `git rev-parse --show-toplevel` must be the project the human named. `goal draft` prints `repoRoot`. If it differs, stop. Do not search parent or sibling repos. If unsure, ask and wait.
3
4
  - `run` said `RUN_CONFLICT`: the human picks an `option`.
4
5
  - If the user asks for ideas, list a short menu and wait; do not implement.
5
6
  - Ambiguous task the user can answer: grill first (`docs grill-policy`): design tree, recommended answers, never ask look-up facts. T2 adds `loop-risky`.
6
7
  - If the user prompt has no numbered AC, draft the contract (`docs goal-contract` if needed), list it, and wait. Chat agreement is not freeze.
8
+ - Before acceptance criteria, restate the problem in your own words (`docs goal-contract`, Restate): Problem, Done-when, Fail-if, Unknowns. Leave the human's method out. `goal draft` refuses a missing restatement.
9
+ - A bug report already drafted by `run --from-issue` or `outcome repro` has one red-repro AC. Show it and wait for freeze (`docs root-cause-analysis`).
7
10
  - AC is a failure table: each row has a statement, required evidence, and failure cases. Do not freeze sunny-path-only. T0 may use 1-3 rows that still list failure cases.
8
11
  - Boundary-crossing AC (UI-API, service-DB, queue, IPC): `crossComponent: true`; needs L3.
9
- - Optional per AC: `verify.command` (Judge PASS needs it green), `rubric` for subjective ACs; Goal `featureId` links `features.json`; Goal `flow` (from/event/to) for UI work: show its table with the draft (`docs goal-contract`).
10
- - Write the contract JSON to `.ai-engineering-loop/drafts/goal.json`, then `npx ai-engineering-loop goal draft --json --run <runId> --file <file> --revision <currentRevision>` (publishes the draft and the freeze question to Studio). Show the human `goal show --run <runId> --human` (plain Markdown) and the `impactPreview` in one message.
11
- - Write `objective`, AC `statement` and `failureCases` in STE style (`docs goal-contract`, STE): one fact or action per sentence, active voice, at most 20-25 words, words a test can check. Fix `readability` warnings from `goal draft` before asking for the freeze.
12
+ - Optional per AC: `verify.command`, `rubric`, `featureId`, `flow` (from/event/to). Show the flow table (`docs goal-contract`).
13
+ - Write `.ai-engineering-loop/drafts/goal.json`, then `npx ai-engineering-loop goal draft --json --run <runId> --file <file> --revision <currentRevision>`. Show `goal show --run <runId> --human` and `impactPreview`.
14
+ - Write `objective`, AC `statement` and `failureCases` in STE style (`docs goal-contract`): short, active, testable. Fix `readability` warnings before asking for the freeze.
12
15
  - If `goal draft` returns `diagramOptions`, offer the recommended view or freeze; render only the pick (`goal diagram --view <v>`), then ask: freeze, another view, or add AC for `?`/side effects.
13
- - Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --json --latest --run <runId> --by <name>` (or `--revision <r> --hash <h>`). Add `--confirm-impact` when that answer also accepts the blast radius. T0: `quick start`.
16
+ - Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --json --latest --run <runId> --by <their name>` (or `--revision <r> --hash <h>`). `--by` is that person, never `agent`, `ael-agent`, a model id, or empty. A cancelled or unanswered question: stop and wait. Never freeze yourself. Add `--confirm-impact` when that answer also accepts the blast radius. T0: `quick start`.
14
17
  - Otherwise the freeze writes a DRAFT blast-radius map: `impact show --run <runId>`. ASSISTED: the human confirms or edits it (`impact confirm --by <name> [--allow <glob>] [--remove <path>]`); copy/CSS/comment-only goals: `impact skip --by <name> --reason <text>` (`docs blast-radius-map`).
15
18
  - Do not edit production code until the Goal gate passes.
16
19
  - After the freeze, work from the frozen contract (`goal show --run <runId>`), not the drafting chat; compact the conversation there if the host supports it.
@@ -56,3 +56,4 @@ Every decision that is the human's (freeze the Goal, a diagram view, RUN_CONFLIC
56
56
  - CLI JSON that already lists choices (`conflict.options`, `diagramOptions`) maps one option per entry; keep the command each option runs.
57
57
  - No such tool: a numbered list with the exact words to reply, recommendation first.
58
58
  - Only the human's own answer counts. No answer, a timeout or a changed subject is not approval.
59
+ - Cancelled, unanswered, timed out, or a non-interactive "continue without an answer": stop. Ask in the user-visible message and wait for the next turn. Do not freeze and do not edit.
@@ -3,4 +3,5 @@
3
3
  Read when the Run is REPORT_ONLY or UNATTENDED, or `workflow.md` names a `maker_intern`.
4
4
 
5
5
  - Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then the report review (`loop-report`), run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
6
+ - Overnight (UNATTENDED, human has left): follow `docs overnight-contract`. Do not freeze, deliver, merge, or guess. When you stop, `overnight check --run <runId>` must pass.
6
7
  - Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
package/CHANGELOG.md CHANGED
@@ -4,7 +4,37 @@ All notable changes to this project are documented here. Versions follow [Semant
4
4
 
5
5
  ## Unreleased
6
6
 
7
- _No changes yet._
7
+ ## 2.15.0 - 2026-11-22
8
+
9
+ Feature map, PR babysit, issue red-repro, and a restatement before the Goal; agent-safety fixes from the e2e test; overnight contract, prototype spike, garden, and stacked-run docs.
10
+
11
+ - **Added:** a verification one-pager (`docs verification-one-pager`): the gates in order, what `verify` records, and how the Judge uses that evidence.
12
+ - **Added:** how to coordinate agents and stack pull requests without a coordinator process (`docs coordinator`). `run --worktree --base <branch>` starts the worktree from that local commit. `--base` alone is refused, so the current checkout is not switched.
13
+ - **Added:** a weekly process-sampling playbook (`docs/playbooks/weekly-process-sampling.md`, also `docs weekly-process-sampling`). Read three recent Runs and check the loop was followed. No command.
14
+ - **Added:** `refresh --garden` reports stale learnings, feature-map rows whose paths match nothing, and old Runs (`docs garden`). It writes nothing unless `--yes`. `--yes` prunes those learnings and moves fully dead feature-map rows under `## Stale (garden)` after saving `feature-map.md.ael-backup`. Runs are never deleted.
15
+ - **Added:** a throwaway prototype spike before the Goal freeze (`docs prototype-spike`). `spike record --discarded --question "..." --learned "..."` writes `runs/<id>/spike.json`. It refuses a spike that was not discarded, and it refuses once the Goal is frozen. No arena and no second model.
16
+ - **Added:** an overnight contract for unattended runs (`docs overnight-contract`). `overnight check [--run <id>]` recomputes the morning packet from Run files: what the agent may do, when it must stop, and which files a person reviews in the morning. Exit 1 when the run was delivered without a person, or a stopped run is missing that packet.
17
+ - **Fixed:** `goal freeze` refuses an empty `--by` and agent-like names (`agent`, `ael-agent`, a model id such as `deepseek-flash`). The skill says a cancelled or unanswered question is not approval: stop and wait, and never freeze yourself (#162).
18
+ - **Fixed:** The skill confirms `git rev-parse --show-toplevel` is the project the human named before drafting. `goal draft` prints that path as `repoRoot` (#164).
19
+ - **Changed:** The `ael` skill description also matches an ordinary feature or bugfix in a repository that already has AI Engineering Loop (`please add`, `please fix`, `fix this bug`, `build this feature`, `tambahin fitur`, `Use AI Engineering Loop`). A one-line typo or "just change this line" stays a direct edit (#160).
20
+ - **Fixed:** `review-pack` keeps `context/diff-hunks.json` valid JSON. Debt, feature, and assumption notes are stored with `JSON.stringify` and an atomic write instead of being appended as Markdown (#163).
21
+ - **Fixed:** `verify` prints a bounded stdout and stderr tail, the exit code, and the evidence path when a command fails. `--json` includes `stdoutTail` and `stderrTail` (#153).
22
+ - **Changed:** `setup` without a TTY exits 2 and names `setup --yes` instead of looking successful. `setup --yes` exits 1 when no coding agent is installed. Get started tells agents and scripts to pass `--yes` (#148).
23
+ - **Fixed:** `run` rejects unknown `--*` flags with `INVALID_USAGE` and a suggestion. A typo no longer becomes the task or replaces the active Run (#150).
24
+ - **Fixed:** `feature-map scaffold` reads bullets under Features and Usage, `package.json` `bin` and scripts, and `src/<feature>/` directories. An empty result names the next step (#152).
25
+ - **Fixed:** `next` uses `feature-map.md` when `features.json` is absent. Its FIX example is valid JSON (#151).
26
+ - **Added:** `feature-map scaffold` drafts `.ai-engineering-loop/feature-map.md` (Feature | Where | Paths | How to reach | Driver) from routes, an OpenAPI or Swagger document, page files, or README headings. No signal writes a stub table with no rows. An edited map is never overwritten; the new draft is `feature-map.md.ael-new`. `init` and project onboarding offer the command and do not run it unless you say yes. `driver scaffold` names this command when the map is missing.
27
+ - **Added:** `pr babysit --run <id>` polls PR status with backoff. Failing checks start a T0 or T1 fix Run on the same branch and push it. Ready to merge, or changes requested, stops for a human. Merge stays with the human. `GH_UNAVAILABLE` matches `pr status` (`docs run-isolation`).
28
+ - **Added:** `run --from-issue <url|#n>` reads one GitHub issue (`gh issue view`) or GitLab issue (`glab issue view`) and drafts a red-repro Goal: one failing behavior plus the verify command that fails today. `outcome repro --file <path>` does the same from a pasted report. The issue connector is read-only (no comment, create, or edit). The Run then follows the normal loop (freeze, Maker, verification, Devil's Advocate, Judge, human-approved delivery). See `docs root-cause-analysis`.
29
+ - **Added:** a Restate block before acceptance criteria. The agent writes the problem in its own words (`problem`, `doneWhen`, `failIf`, `unknowns`) and leaves the human's method out. `goal draft` refuses a missing or blank restatement (`RESTATEMENT_MISSING`). `goal.md` prints the block first (`docs goal-contract`, Restate).
30
+
31
+ ## 2.14.1 - 2026-11-21
32
+
33
+ Repo cleanup.
34
+
35
+ - **Changed:** repo cleanup (`docs/audit/repo-cleanup-2026-11-21.md`). Finished cards, board history, old designs, the issue #110 cut and QA pack, and old feasibility docs moved to `docs/archive/`; unused images, `README.npm.md`, `templates/repo-config/` and `examples/` removed; `social-preview.png` moved out of the package to `docs/brand/`. The package is 87 KB smaller.
36
+ - **Changed:** `scripts/init.sh` is deprecated: it now runs `npx ai-engineering-loop init` and will be removed in the next release.
37
+ - **Changed:** CI runs the release checks (`doctor --package`, `check:skills`, `audit:package`, `measure`); `ael help` lists every command again, including `gate`, `context`, `review` and `outcome`.
8
38
 
9
39
  ## 2.14.0 - 2026-11-21
10
40
 
package/README.md CHANGED
@@ -34,6 +34,7 @@ In any project:
34
34
  ```bash
35
35
  npm i -g ai-engineering-loop # Node 18+ and git required
36
36
  ael setup # installs the ael skill into your coding agents
37
+ # agents and scripts: ael setup --yes (no prompt)
37
38
  ael init # writes .ai-engineering-loop/ for this project
38
39
  ```
39
40
 
@@ -18,6 +18,7 @@ Run `npx ai-engineering-loop init` first if `.ai-engineering-loop/` is missing.
18
18
  5. **Gotchas.** Only record ones you can prove: cite a file:line, commit, test, or command output for each. No speculation.
19
19
  6. **Write.** Update the two files with the template in `references/output.md`. Keep existing human-written sections; add or replace only the sections this skill owns.
20
20
  7. **Report** what you added, the evidence count, and any open question for the human.
21
+ 8. **Feature map (optional).** When `.ai-engineering-loop/feature-map.md` is missing, offer `npx ai-engineering-loop feature-map scaffold` as a next step. It drafts rows (feature, what it does, how a user reaches it) from routes, OpenAPI, pages, or the README, and writes `feature-map.md.ael-new` instead of overwriting an edited map. Run it only after the user says yes.
21
22
 
22
23
  ## Rules
23
24
 
@@ -25,3 +26,4 @@ Run `npx ai-engineering-loop init` first if `.ai-engineering-loop/` is missing.
25
26
  - Do not paste secrets, tokens, customer data, or `.env` values; name the variable instead.
26
27
  - Keep each file short (aim for under 150 lines). Link to code instead of copying it.
27
28
  - Commands you ran go into `.ai-engineering-loop/verification.md` only if they actually passed.
29
+ - Do not run `feature-map scaffold` unless the user asks. Offering it is enough.
@@ -6,7 +6,7 @@ For hosts with no subagent tool (certification `instruction-only`). Full skill:
6
6
  Loop: Specify (0-1), Make (2-4), Review (5-7), Deliver (8). You are Maker. Devil's Advocate (DA) and Judge run in this session as `CONTEXT_ISOLATION_ONLY`, with the same budgets; never claim independent review.
7
7
 
8
8
  1. `npx ai-engineering-loop run --json` gives runId, tier, budget. Read `.ai-engineering-loop/glossary.md`.
9
- 2. Goal Contract: AC is a failure table (happy, empty, boundary, error). Only after the human freezes: `goal freeze --json --latest --run <runId> --by human`. Chat agreement is not freeze.
9
+ 2. Goal Contract: AC is a failure table (happy, empty, boundary, error). Confirm `git rev-parse --show-toplevel` is the project the human named. Only after the human freezes: `goal freeze --json --latest --run <runId> --by <their name>`. Never `--by agent` or `ael-agent`. A cancelled question: stop and wait. Chat agreement is not freeze.
10
10
  3. Maker: one red test per AC row before the fix, then `gate maker`.
11
11
  4. `verify --cmd <test command>`, then write claimed-vs-reality.md.
12
12
  5. DA: re-read only the diff, Goal, and evidence; log findings; `gate review`. Judge: write the verdict from the evidence, then `gate judge`. ITERATE at most 3 times.