ai-engineering-loop 1.14.0 → 1.16.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 (112) hide show
  1. package/.agents/{workflows/ai-engineering-loop.md → skills/ai-engineering-loop/SKILL.md} +9 -7
  2. package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-deliver.md +1 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +48 -0
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +13 -0
  5. package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-review.md +2 -0
  6. package/.claude/skills/ai-engineering-loop/SKILL.md +10 -11
  7. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +1 -0
  8. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +48 -0
  9. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +6 -1
  10. package/.claude/skills/ai-engineering-loop/references/loop-review.md +2 -0
  11. package/CHANGELOG.md +83 -0
  12. package/README.md +54 -6
  13. package/adapters/README.md +22 -0
  14. package/adapters/dot/README.md +19 -9
  15. package/adapters/dot/gitlab.md +49 -0
  16. package/adapters/dot/mattermost.md +10 -0
  17. package/adapters/dot/skills/dot-dev-workflow/SKILL.md +27 -5
  18. package/adapters/dot/sonar.md +90 -0
  19. package/adapters/generate-adapter/SKILL.md +6 -5
  20. package/adapters/{dot → quality}/skills/task-impact-inquiry/SKILL.md +10 -7
  21. package/agents/instruction-only/AGENTS.md +24 -0
  22. package/bin/ai-engineering-loop.js +320 -34
  23. package/core/grill-policy.md +1 -1
  24. package/core/orchestration-model.md +11 -0
  25. package/core/runtime-safety.md +2 -1
  26. package/lib/adapter-check.js +102 -0
  27. package/lib/adapter-detect.js +125 -0
  28. package/lib/auto-update.js +3 -1
  29. package/lib/cli-args.js +11 -0
  30. package/lib/doctor.js +13 -17
  31. package/lib/gates.js +28 -1
  32. package/lib/generate-adapter.js +6 -30
  33. package/lib/host-skill-build.js +25 -15
  34. package/lib/hosts/agent-formats.js +135 -0
  35. package/lib/hosts/commands.js +126 -0
  36. package/lib/hosts/detect.js +56 -0
  37. package/lib/hosts/doctor.js +77 -0
  38. package/lib/hosts/redetect.js +60 -0
  39. package/lib/hosts/registry.js +298 -0
  40. package/lib/hosts/table.js +43 -0
  41. package/lib/orchestration.js +39 -6
  42. package/lib/run-abandon.js +116 -0
  43. package/lib/studio-server.js +1 -0
  44. package/lib/sync-hosts.js +156 -112
  45. package/package.json +2 -3
  46. package/schemas/report.schema.json +52 -5
  47. package/.agents/devil-advocate.md +0 -79
  48. package/.agents/judge.md +0 -58
  49. package/.claude/commands/ai-engineering-loop.md +0 -11
  50. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -61
  51. package/.gemini/skills/ai-engineering-loop/references/loop-maker.md +0 -8
  52. package/.gemini/skills/animate/RECIPES.md +0 -324
  53. package/.gemini/skills/animate/SKILL.md +0 -207
  54. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  55. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  56. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  57. package/.gemini/skills/apple-design/SKILL.md +0 -290
  58. package/.gemini/skills/ask-sonner/API.md +0 -64
  59. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  60. package/.gemini/skills/backend-development/SKILL.md +0 -272
  61. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  62. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  63. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  64. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  65. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  66. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  67. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  68. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  69. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  70. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  71. package/.gemini/skills/prototype/PICKER.md +0 -197
  72. package/.gemini/skills/prototype/SKILL.md +0 -98
  73. package/.gemini/skills/review-animations/SKILL.md +0 -120
  74. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  75. package/.gemini/skills/write-swift/SKILL.md +0 -396
  76. package/.grok/commands/ai-engineering-loop.md +0 -11
  77. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -62
  78. package/.grok/skills/ai-engineering-loop/references/loop-commands.md +0 -20
  79. package/.grok/skills/ai-engineering-loop/references/loop-deliver.md +0 -8
  80. package/.grok/skills/ai-engineering-loop/references/loop-goal.md +0 -10
  81. package/.grok/skills/ai-engineering-loop/references/loop-maker.md +0 -8
  82. package/.grok/skills/ai-engineering-loop/references/loop-review.md +0 -18
  83. package/.grok/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  84. package/.grok/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  85. package/.grok/skills/animate/RECIPES.md +0 -324
  86. package/.grok/skills/animate/SKILL.md +0 -207
  87. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  88. package/.grok/skills/animate-expo/SKILL.md +0 -263
  89. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  90. package/.grok/skills/apple-design/SKILL.md +0 -290
  91. package/.grok/skills/ask-sonner/API.md +0 -64
  92. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  93. package/.grok/skills/backend-development/SKILL.md +0 -272
  94. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  95. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  96. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  97. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  98. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  99. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  100. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  101. package/.grok/skills/improve-animations/SKILL.md +0 -109
  102. package/.grok/skills/mobile-native/SKILL.md +0 -311
  103. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  104. package/.grok/skills/prototype/PICKER.md +0 -197
  105. package/.grok/skills/prototype/SKILL.md +0 -98
  106. package/.grok/skills/review-animations/SKILL.md +0 -120
  107. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  108. package/.grok/skills/write-swift/SKILL.md +0 -396
  109. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-commands.md +0 -0
  110. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-goal.md +0 -0
  111. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-risky.md +0 -0
  112. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-verify.md +0 -0
@@ -3,14 +3,61 @@
3
3
  "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/report.schema.json",
4
4
  "title": "Report-only completion",
5
5
  "type": "object",
6
- "required": ["schemaVersion", "runId", "summary", "recommendations"],
6
+ "required": [
7
+ "schemaVersion",
8
+ "runId",
9
+ "summary",
10
+ "recommendations"
11
+ ],
7
12
  "properties": {
8
- "schemaVersion": { "const": 1 },
9
- "runId": { "type": "string", "minLength": 1 },
10
- "summary": { "type": "string", "minLength": 1 },
13
+ "schemaVersion": {
14
+ "const": 1
15
+ },
16
+ "runId": {
17
+ "type": "string",
18
+ "minLength": 1
19
+ },
20
+ "summary": {
21
+ "type": "string",
22
+ "minLength": 1
23
+ },
11
24
  "recommendations": {
12
25
  "type": "array",
13
- "items": { "type": "string", "minLength": 1 }
26
+ "items": {
27
+ "type": "string",
28
+ "minLength": 1
29
+ }
30
+ },
31
+ "review": {
32
+ "description": "Optional report review (#57). Independent modes need reviewer devil-advocate and its own childId; CONTEXT_ISOLATION_ONLY with nativeSubagent AVAILABLE needs reason.",
33
+ "type": "object",
34
+ "required": [
35
+ "executionMode"
36
+ ],
37
+ "properties": {
38
+ "executionMode": {
39
+ "type": "string",
40
+ "minLength": 1
41
+ },
42
+ "nativeSubagent": {
43
+ "enum": [
44
+ "AVAILABLE",
45
+ "UNAVAILABLE"
46
+ ]
47
+ },
48
+ "reviewer": {
49
+ "const": "devil-advocate"
50
+ },
51
+ "childId": {
52
+ "type": "string",
53
+ "minLength": 1
54
+ },
55
+ "reason": {
56
+ "type": "string",
57
+ "minLength": 1
58
+ }
59
+ },
60
+ "additionalProperties": true
14
61
  }
15
62
  },
16
63
  "additionalProperties": true
@@ -1,79 +0,0 @@
1
- ---
2
- name: devil-advocate
3
- description: Use this agent after deterministic tests pass, to adversarially review a git diff against a Goal Contract. Returns a Finding Ledger. Typical triggers include a completed Maker pass and an explicit devil's advocate request.
4
- tools: view_file, grep_search, list_dir, run_command
5
- ---
6
-
7
- You are the Devil's Advocate for the AI Engineering Loop. You are read-only. You never modify application source and never commit.
8
-
9
- ## Budget (hard stop)
10
-
11
- Finish in at most 8 tool calls, then emit the Finding Ledger. Do not explore the rest of the repo. Do not spawn children. Do not run git log.
12
-
13
- Default to a lean review: spend detail where it protects correctness, not on prose. Treat the context pack as scarce. Prefer one precise quote over a long explanation.
14
-
15
- ## Input barrier
16
-
17
- Use only:
18
-
19
- 1. The diff or smart diff-hunk pack path in the spawn prompt. Read that file first. Do not run git diff if a diff path was given.
20
- 2. Goal Contract path (if given).
21
- 3. Verification log path (if given).
22
- 4. conventions.md path (if given). At most one extra read.
23
- 5. At most 8 source files that appear as paths in the diff.
24
-
25
- Skip: `*.css`, files named like `*-css.ts` or `report-css.ts`, generated/vendor dirs, and any file where the diff hunk already contains enough evidence. Prefer quoting the hunk over opening the whole file.
26
-
27
- Do not ask for Maker rationale.
28
-
29
- On iteration 2 or later, review only the changed hunks since the previous Finding Ledger plus previously unresolved findings. A smart diff-hunk pack already contains that shape; use it instead of opening full files when possible. Do not re-litigate accepted or dismissed findings unless the new diff changes their evidence.
30
-
31
- ## Two axes (do not merge)
32
-
33
- Report Spec and Standards as separate findings. Do not rerank one axis with the other. A change can pass Spec and fail Standards, or the reverse. Do not spawn children to split axes.
34
-
35
- **Spec** (`axis: "spec"`): Goal Contract acceptance criteria, correctness, error handling, security, concurrency, tests that fail to prove an AC, happy-path-only suite vs written failure table. BLOCKER or HIGH only for a real AC breach or runtime defect.
36
-
37
- **Standards** (`axis: "standards"`): `.ai-engineering-loop/conventions.md` plus the smell baseline below. Judgement calls: severity MEDIUM or LOW. Set `hardConvention: true` only when conventions.md states a hard rule that this hunk violates. A smell that hides an AC defect is Spec, not Standards.
38
-
39
- Skip style nits unless they hide a defect.
40
-
41
- Smell baseline (judgement only; skip if tooling already enforces; repo conventions override): Mysterious Name; Duplicated Code; Feature Envy; Data Clumps; Primitive Obsession; Repeated Switches; Shotgun Surgery; Divergent Change; Speculative Generality; Message Chains; Middle Man; Refused Bequest.
42
-
43
- ## Output
44
-
45
- Return a Finding Ledger as a fenced JSON block and stop:
46
-
47
- ```json
48
- {
49
- "iteration": 1,
50
- "executionMode": "TRUE_INDEPENDENT_AGENT",
51
- "findings": [
52
- {
53
- "id": "DA-01",
54
- "axis": "spec",
55
- "hardConvention": false,
56
- "topic": "correctness",
57
- "validity": "VALID",
58
- "severity": "BLOCKER",
59
- "disposition": "STRONG",
60
- "location": "path/to/file.ext#L12-L20",
61
- "acceptanceCriteria": "AC-1",
62
- "failureScenario": "Concrete failing case",
63
- "reproduction": "Steps to reproduce",
64
- "evidence": "Hunk or line you read",
65
- "concreteAlternativeDiff": "diff snippet"
66
- }
67
- ]
68
- }
69
- ```
70
-
71
- Rules: axis is spec or standards (default spec). hardConvention is boolean, default false. validity VALID or INVALID; severity BLOCKER, HIGH, MEDIUM, or LOW; disposition STRONG, ACCEPTABLE, or WEAK. VALID BLOCKER or HIGH must include concreteAlternativeDiff. Empty findings is allowed.
72
-
73
- Lean output caps:
74
-
75
- - Emit at most 5 findings unless a sixth or later finding is BLOCKER.
76
- - Keep `failureScenario`, `reproduction`, and `evidence` under 500 characters each.
77
- - Keep `concreteAlternativeDiff` under 12 lines; describe the rest in words.
78
- - For MEDIUM/LOW findings, omit `concreteAlternativeDiff` unless the fix is a one-line replacement.
79
- - Do not include broad summaries, praise, or restated policy text when findings are non-empty.
package/.agents/judge.md DELETED
@@ -1,58 +0,0 @@
1
- ---
2
- name: judge
3
- description: Use this agent after Devil's Advocate returns a Finding Ledger. Issues PASS, ITERATE, or ESCALATE from Validity plus Severity. Typical triggers include a completed adversarial review and an explicit judge request.
4
- tools: view_file, grep_search, list_dir, run_command
5
- ---
6
-
7
- You are the Judge for the AI Engineering Loop. You do not write application code. You issue one verdict: PASS, ITERATE, or ESCALATE.
8
-
9
- ## Budget (hard stop)
10
-
11
- Finish in at most 4 tool calls, then emit the verdict. Read the Finding Ledger and Goal Contract first. Open source only to fact-check a location the ledger already cited. Do not re-review the whole diff. Do not run git log. Do not spawn children. Skip `*.css`, `*report-css*`, and generated/vendor files.
12
-
13
- Use a lean decision style. The Judge decides; it does not write an audit report. Prefer compact verdict evidence over narrative summaries.
14
-
15
- ## Inputs
16
-
17
- Use only paths in the spawn prompt: Goal Contract, verification evidence, Finding Ledger. Ignore Maker optimism and reviewer tone. Disposition never overrides Validity plus Severity.
18
-
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
-
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
-
23
- ## Axes
24
-
25
- Do not merge Spec and Standards into one ranking.
26
-
27
- - Spec VALID BLOCKER or HIGH (or missing axis, treated as spec): ITERATE (ESCALATE if iteration is 3 or more)
28
- - Standards VALID BLOCKER or HIGH: ITERATE only when hardConvention is true
29
- - Other Standards findings: ACCEPT as tradeoff; may still PASS
30
- - INVALID findings: DISMISS, cannot block delivery
31
- - VALID MEDIUM or LOW: ACCEPT as tradeoff; may still PASS
32
- - Verification missing, vague, or non-zero exit: ITERATE
33
- - All acceptance criteria proven, verification green, zero open blockers: PASS
34
-
35
- ## Output
36
-
37
- Return a fenced JSON block:
38
-
39
- ```json
40
- {
41
- "verdict": "PASS",
42
- "reason": "All acceptance criteria verified; 0 open blocking findings",
43
- "action": "Proceed to context impact assessment and delivery adapter",
44
- "blockingFindings": [],
45
- "acceptableTradeoffs": [],
46
- "dismissedFindings": []
47
- }
48
- ```
49
-
50
- `verdict` must be exactly PASS, ITERATE, or ESCALATE. Do not edit source.
51
-
52
- Lean output caps:
53
-
54
- - Keep `reason` under 900 characters.
55
- - Keep `action` under 700 characters.
56
- - Put only blocking IDs in `blockingFindings`; do not restate every accepted LOW/MEDIUM note.
57
- - Summarize accepted tradeoffs as IDs plus one short phrase each.
58
- - Do not quote the Goal Contract or Finding Ledger unless needed to resolve a disputed blocker.
@@ -1,11 +0,0 @@
1
- ---
2
- name: ai-engineering-loop
3
- description: Run the AI Engineering Loop (init, status, refresh, or full Maker then Devil's Advocate then Judge).
4
- allowed-tools: "Read, Grep, Glob, Edit, Write, Task, Bash(npm run *), Bash(npm test *), Bash(npx *), Bash(git *)"
5
- ---
6
-
7
- Follow `.claude/skills/ai-engineering-loop/SKILL.md`.
8
-
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. Reviewer budgets live in the agent files; do not let either roam the repo.
10
-
11
- Arguments: init, status, refresh, sync-hosts, generate-adapter, generate-workflow, or a task description.
@@ -1,61 +0,0 @@
1
- ---
2
- name: ai-engineering-loop
3
- description: Use when the user runs /ai-engineering-loop, asks to init or refresh living project context, or wants the Maker / Devil's Advocate / Judge engineering loop on Antigravity.
4
- ---
5
- <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
6
-
7
- # AI Engineering Loop (Antigravity)
8
-
9
- Stage details: `references/loop-*.md` beside this file, read only on entering that stage. Specs and references: `npx ai-engineering-loop docs <name> [--section <h>]`; never read whole spec directories.
10
-
11
- ## Host rules
12
-
13
- 1. If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as siblings, wait for each, never in the background; `general-purpose` only if the named type is rejected. Do not use `browser_subagent`.
14
- 2. No subagent tool: run the same budgets in this session as `CONTEXT_ISOLATION_ONLY`; do not claim independent agent execution.
15
- 3. Models: the host catalog (`/models` when it exists); never type a model name.
16
- 4. Modes: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_PROCESS_AGENT`, `CONTEXT_ISOLATION_ONLY`, `UNAVAILABLE`.
17
-
18
- ## Commands
19
-
20
- `init|status|refresh|sync-hosts|generate-adapter|generate-workflow`: run `npx ai-engineering-loop <command>` (`loop-commands`); do not commit unless asked. Otherwise: the loop.
21
-
22
- ## Loop
23
-
24
- Compact 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 is Maker plus orchestrator; Devil's Advocate (DA) and Judge are fresh **siblings**, never nested or resumed. A gate failure overrides prose. Never edit `state.json`/`current.json`.
25
-
26
- 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.
27
- - **T0** trivial (docs, typo, lint): `gate goal`, Maker, `verify`, claimed-vs-reality, `gate review`, `gate judge` (deterministic); no subagents.
28
- - **T1** normal: frozen Goal, red test, `verify`, lean DA, `gate review --json`; spawn Judge only on `judgeRequired`.
29
- - **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>`.
30
-
31
- 0. `run --json [--mode report-only|assisted|unattended]` (runId, tier, budget, hostSkills; `RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user to. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present.
32
- 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
-
34
- Invariants (every tier):
35
- - AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
36
- - One red test per AC row (bugs: red repro) before the fix.
37
- - 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.
38
- - ITERATE at most to iteration 3, each with a **new** DA.
39
- - Never infer human approval.
40
- - After each child `budget record` real usage or `--unavailable`; never invent counts.
41
- - No secrets or hidden reasoning in activity messages.
42
-
43
- ## Report header
44
-
45
- When a child actually returned a result:
46
-
47
- ```
48
- Execution Mode: TRUE_INDEPENDENT_AGENT
49
- Independent LLM Execution: PROVEN
50
- Native Subagent Invocation: AVAILABLE
51
- Review Method: True Independent Agent
52
- ```
53
-
54
- When no subagent ran:
55
-
56
- ```
57
- Execution Mode: CONTEXT_ISOLATION_ONLY
58
- Independent LLM Execution: NOT PROVEN
59
- Native Subagent Invocation: UNAVAILABLE
60
- Review Method: Clean-Slate Artifact Isolation Barrier
61
- ```
@@ -1,8 +0,0 @@
1
- # Stages 2-4: Maker
2
-
3
- - T1/T2: read `docs tdd-policy` before Maker. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files.
4
- - Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, 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>`.
5
- - 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.
6
- - Bugs: red repro first. Features: one red test per AC row, then green.
7
- - After package and manifest edits are stable, run `npx ai-engineering-loop refresh` once (drift during red-green is expected; do not refresh per test cycle).
8
- - ASSISTED: `npx ai-engineering-loop gate maker --from-git` writes the exact working-tree diff (tracked and new files, excluding `.ai-engineering-loop/`) to `RUN_DIR/diff.patch` and gates it; or write that file yourself and run `gate maker`. UNATTENDED: `sandbox capture` writes it, then `gate maker`. The gate can raise the tier from the diff.
@@ -1,324 +0,0 @@
1
- # Animation Recipes
2
-
3
- Ready-to-build implementations for the cases that come up most. Start from the recipe, then adapt — don't rebuild from scratch.
4
-
5
- Curves are the `--ease-out`, `--ease-in-out`, and `--ease-drawer` tokens defined in SKILL.md.
6
-
7
- ---
8
-
9
- ## Button press
10
-
11
- Any pressable element. Instant feedback that the interface heard the user.
12
-
13
- ```css
14
- .button {
15
- transition: transform 160ms var(--ease-out);
16
- }
17
-
18
- .button:active {
19
- transform: scale(0.97);
20
- }
21
- ```
22
-
23
- `scale()` scales children too — the label and icons come along, which is what makes it read as a physical press.
24
-
25
- No hover gating needed here: `:active` is a real press on touch. Gate any `:hover` styling separately.
26
-
27
- ---
28
-
29
- ## Dropdown, popover, menu, select
30
-
31
- Scales out of its trigger, not out of thin air.
32
-
33
- ```css
34
- .popover {
35
- transform-origin: var(--transform-origin); /* Base UI supplies this */
36
- transition:
37
- opacity 200ms var(--ease-out),
38
- transform 200ms var(--ease-out);
39
- }
40
-
41
- .popover[data-starting-style],
42
- .popover[data-ending-style] {
43
- opacity: 0;
44
- transform: scale(0.95);
45
- }
46
- ```
47
-
48
- The `transform-origin` is the whole point — the panel should look like it came out of the thing you clicked.
49
-
50
- ---
51
-
52
- ## Tooltip
53
-
54
- Same shape as a popover, faster, plus the detail most implementations miss.
55
-
56
- ```css
57
- .tooltip {
58
- transform-origin: var(--transform-origin);
59
- transition:
60
- transform 125ms var(--ease-out),
61
- opacity 125ms var(--ease-out);
62
- }
63
-
64
- .tooltip[data-starting-style],
65
- .tooltip[data-ending-style] {
66
- opacity: 0;
67
- transform: scale(0.97);
68
- }
69
-
70
- /* Once one tooltip is open, neighbours open instantly */
71
- .tooltip[data-instant] {
72
- transition-duration: 0ms;
73
- }
74
- ```
75
-
76
- The initial delay prevents accidental activation. After that, skipping both the delay and the animation makes the whole toolbar feel faster.
77
-
78
- ---
79
-
80
- ## Modal
81
-
82
- The one popover that stays centered.
83
-
84
- ```css
85
- .modal {
86
- transform-origin: center; /* exempt — not anchored to a trigger */
87
- transition:
88
- opacity 250ms var(--ease-out),
89
- transform 250ms var(--ease-out);
90
- }
91
-
92
- .modal[data-starting-style],
93
- .modal[data-ending-style] {
94
- opacity: 0;
95
- transform: scale(0.96);
96
- }
97
-
98
- .backdrop {
99
- transition: opacity 250ms var(--ease-out);
100
- }
101
- ```
102
-
103
- Animate the backdrop's opacity alongside it so they read as one surface.
104
-
105
- ---
106
-
107
- ## Drawer / sheet
108
-
109
- ```css
110
- .drawer {
111
- transform: translateY(0);
112
- transition: transform 500ms var(--ease-drawer);
113
- }
114
-
115
- .drawer[data-closed] {
116
- transform: translateY(100%);
117
- }
118
- ```
119
-
120
- This is how Vaul hides a drawer before animating it in.
121
-
122
- Add drag and it becomes a gesture problem — see **Drag to dismiss** below.
123
-
124
- ---
125
-
126
- ## Toast
127
-
128
- ```css
129
- .toast {
130
- opacity: 1;
131
- transform: translateY(0);
132
- transition:
133
- opacity 400ms ease,
134
- transform 400ms ease;
135
-
136
- @starting-style {
137
- opacity: 0;
138
- transform: translateY(100%);
139
- }
140
- }
141
- ```
142
-
143
- - `ease` rather than `ease-out`, slightly slower than typical UI: Sonner reads as elegant partly because its motion is tuned to the component's personality rather than to the generic UI budget.
144
- - If `@starting-style` isn't available, fall back to the mount flag:
145
-
146
- ```jsx
147
- useEffect(() => { setMounted(true); }, []);
148
- // <div data-mounted={mounted}>
149
- ```
150
-
151
- When toasts stack and the list reflows, the opacity change has to work against the height change. There's no formula for that pair — adjust until it feels right, then check it again the next day.
152
-
153
- ---
154
-
155
- ## Accordion / collapse
156
-
157
- ```css
158
- .content {
159
- overflow: hidden;
160
- transition:
161
- height 200ms var(--ease-out),
162
- opacity 200ms var(--ease-out);
163
- }
164
- ```
165
-
166
- Keep it short — this is one of the few animations that costs layout on every frame, so a long duration is expensive as well as sluggish. Measure the content height in JS (or use a headless primitive that supplies it) rather than animating to `auto`.
167
-
168
- ---
169
-
170
- ## Stagger a group entrance
171
-
172
- For a list or grid the user sees occasionally — not for a list they scroll past all day.
173
-
174
- ```css
175
- .item {
176
- opacity: 0;
177
- transform: translateY(8px);
178
- animation: fadeIn 300ms var(--ease-out) forwards;
179
- }
180
-
181
- .item:nth-child(2) { animation-delay: 50ms; }
182
- .item:nth-child(3) { animation-delay: 100ms; }
183
- .item:nth-child(4) { animation-delay: 150ms; }
184
-
185
- @keyframes fadeIn {
186
- to {
187
- opacity: 1;
188
- transform: translateY(0);
189
- }
190
- }
191
- ```
192
-
193
- Stagger is decorative — it must never block interaction while it plays.
194
-
195
- ---
196
-
197
- ## Hold to confirm
198
-
199
- For destructive actions where a plain click is too easy to fire by accident.
200
-
201
- ```css
202
- .overlay {
203
- clip-path: inset(0 100% 0 0);
204
- transition: clip-path 200ms var(--ease-out); /* release: snappy */
205
- }
206
-
207
- .button:active .overlay {
208
- clip-path: inset(0 0 0 0);
209
- transition: clip-path 2s linear; /* press: slow and deliberate */
210
- }
211
-
212
- .button:active {
213
- transform: scale(0.97);
214
- }
215
- ```
216
-
217
- `linear` is correct here — the fill is a progress indicator, and progress shouldn't ease.
218
-
219
- ---
220
-
221
- ## Tab indicator with a color transition
222
-
223
- Timing individual color transitions across a tab list never quite lands. Clip instead.
224
-
225
- Duplicate the tab list. Style the copy as the active state — different background, different text color. Clip the copy so only the active tab shows, and animate the clip on change:
226
-
227
- ```css
228
- .tabs-active-copy {
229
- clip-path: inset(0 60% 0 20%); /* driven by the active tab's position */
230
- transition: clip-path 250ms var(--ease-in-out);
231
- }
232
- ```
233
-
234
- The text and background change together, in perfect sync, because they're one element being revealed rather than two colors being interpolated.
235
-
236
- ---
237
-
238
- ## Scroll reveal
239
-
240
- Marketing surfaces only. Don't do this to functional UI a user visits daily.
241
-
242
- ```css
243
- .reveal {
244
- clip-path: inset(0 0 100% 0);
245
- transition: clip-path 600ms var(--ease-in-out);
246
- }
247
-
248
- .reveal[data-visible] {
249
- clip-path: inset(0 0 0 0);
250
- }
251
- ```
252
-
253
- Trigger with `IntersectionObserver`, or Motion's `useInView` with `{ once: true, margin: "-100px" }`. Fire it once — re-animating on every scroll-by is an interface fighting its reader.
254
-
255
- ---
256
-
257
- ## Drag to dismiss
258
-
259
- The gesture recipe. Springs, not durations, because the user can reverse mid-motion.
260
-
261
- ```js
262
- // Dismiss on a flick, not just on distance
263
- const timeTaken = Date.now() - dragStartTime.current;
264
- const velocity = Math.abs(swipeAmount) / timeTaken;
265
-
266
- if (Math.abs(swipeAmount) >= SWIPE_THRESHOLD || velocity > 0.11) {
267
- dismiss();
268
- }
269
- ```
270
-
271
- ```js
272
- // Set transform on the dragged element directly.
273
- // Driving it through a CSS variable on the parent recalcs styles for every child.
274
- element.style.transform = `translateY(${distance}px)`;
275
- ```
276
-
277
- Four details that separate a good drag from a bad one:
278
-
279
- - **Pointer capture** once the drag starts, so it continues when the pointer leaves the element's bounds.
280
- - **Multi-touch protection** — `if (isDragging) return` on new touch points, or switching fingers mid-drag makes the element jump.
281
- - **Damping past boundaries** — dragging beyond a natural edge moves the element less the further it goes. Real things slow before they stop.
282
- - **Friction, not a wall** — allow the over-drag with rising resistance rather than refusing it.
283
-
284
- Settle with a spring so an interrupted drag keeps its velocity:
285
-
286
- ```js
287
- { type: "spring", duration: 0.5, bounce: 0.2 }
288
- ```
289
-
290
- ---
291
-
292
- ## Masking a crossfade that won't settle
293
-
294
- When two states overlap visibly during a transition and no amount of easing or duration tuning fixes it, blur the seam:
295
-
296
- ```css
297
- .content {
298
- transition:
299
- filter 200ms ease,
300
- opacity 200ms ease;
301
- }
302
-
303
- .content.transitioning {
304
- filter: blur(2px);
305
- opacity: 0.7;
306
- }
307
- ```
308
-
309
- Without blur the eye reads two distinct objects swapping. Blur blends them into one perceived transformation. Keep it under 20px — heavy blur is expensive, especially in Safari.
310
-
311
- ---
312
-
313
- ## Programmatic, without a library
314
-
315
- When the motion needs JS control but not a dependency, WAAPI gives you CSS-grade performance:
316
-
317
- ```js
318
- element.animate(
319
- [{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
320
- { duration: 1000, fill: 'forwards', easing: 'cubic-bezier(0.77, 0, 0.175, 1)' }
321
- );
322
- ```
323
-
324
- Hardware-accelerated, interruptible, no bundle cost.