ai-engineering-loop 2.2.0 → 2.4.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 (133) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
  6. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +1 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  8. package/.claude/agents/judge.md +5 -2
  9. package/.grok/agents/judge.md +5 -2
  10. package/CHANGELOG.md +60 -0
  11. package/README.md +1 -0
  12. package/THIRD_PARTY_NOTICES.md +11 -0
  13. package/adapters/spec/LICENSE +202 -0
  14. package/adapters/spec/NOTICE-AEL.md +26 -0
  15. package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
  16. package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
  17. package/adapters/spec/agents/ael-spec-design.md +65 -0
  18. package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
  19. package/adapters/spec/agents/ael-spec-structural.md +67 -0
  20. package/adapters/spec/agents/ael-spec-style.md +68 -0
  21. package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
  22. package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
  23. package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
  24. package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
  25. package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
  26. package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
  27. package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
  28. package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
  29. package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
  30. package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
  31. package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
  32. package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
  33. package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
  34. package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
  35. package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
  36. package/agents/maker.md +1 -1
  37. package/agents/shared/judge.body.md +5 -2
  38. package/bin/ai-engineering-loop.js +344 -78
  39. package/core/definition-of-done.md +2 -2
  40. package/core/escalation-policy.md +1 -1
  41. package/core/goal-contract.md +1 -1
  42. package/core/iteration-policy.md +2 -1
  43. package/core/judge-policy.md +10 -4
  44. package/core/orchestration-model.md +8 -7
  45. package/core/repo-config-schema.md +2 -2
  46. package/core/runtime-safety.md +3 -3
  47. package/core/spec-pack.md +47 -0
  48. package/lib/auto-update.js +8 -14
  49. package/lib/claimed-vs-reality.js +2 -2
  50. package/lib/cli-args.js +3 -1
  51. package/lib/design-ref.js +178 -0
  52. package/lib/docs.js +1 -1
  53. package/lib/doctor.js +0 -6
  54. package/lib/escalation.js +1 -1
  55. package/lib/fsutil.js +88 -0
  56. package/lib/gates.js +70 -27
  57. package/lib/generate-workflow.js +0 -29
  58. package/lib/goal-runtime.js +8 -2
  59. package/lib/guard-hooks.js +26 -7
  60. package/lib/guard.js +100 -10
  61. package/lib/hosts/doctor.js +17 -7
  62. package/lib/impact-map.js +31 -8
  63. package/lib/jsonl-ledger.js +104 -0
  64. package/lib/learn.js +4 -9
  65. package/lib/loop-groups.js +0 -25
  66. package/lib/migrations.js +1 -5
  67. package/lib/no-progress.js +119 -0
  68. package/lib/node-evidence.js +1 -5
  69. package/lib/orchestration.js +5 -361
  70. package/lib/personal-workflow.js +1 -1
  71. package/lib/quick.js +152 -0
  72. package/lib/receipt.js +13 -6
  73. package/lib/recipe-builder.js +3 -35
  74. package/lib/recipe-graph.js +2 -63
  75. package/lib/recipe.js +2 -4
  76. package/lib/review-ingest.js +116 -0
  77. package/lib/run-abandon.js +2 -1
  78. package/lib/run-compaction.js +4 -12
  79. package/lib/run-interactions.js +16 -71
  80. package/lib/run-lifecycle.js +25 -77
  81. package/lib/run-state.js +68 -17
  82. package/lib/run-watcher.js +11 -14
  83. package/lib/runtime-files.js +45 -1
  84. package/lib/safe-context.js +17 -6
  85. package/lib/sandbox.js +2 -1
  86. package/lib/smart-context.js +13 -14
  87. package/lib/spawn-command.js +94 -0
  88. package/lib/studio-layout.js +2 -8
  89. package/lib/studio-runtime.js +2 -1
  90. package/lib/studio-server.js +25 -5
  91. package/lib/sync-hosts.js +25 -2
  92. package/lib/tier.js +36 -10
  93. package/lib/user-state.js +2 -17
  94. package/lib/verification-lanes.js +115 -0
  95. package/lib/verification-recorder.js +110 -22
  96. package/lib/workflow-runtime.js +7 -4
  97. package/package.json +1 -2
  98. package/policies/review-budget.md +1 -1
  99. package/schemas/goal-contract.schema.json +87 -11
  100. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  101. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  102. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  103. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  104. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  105. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  106. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  107. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  108. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  109. package/.claude/skills/animate/RECIPES.md +0 -324
  110. package/.claude/skills/animate/SKILL.md +0 -207
  111. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  112. package/.claude/skills/animate-expo/SKILL.md +0 -263
  113. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  114. package/.claude/skills/apple-design/SKILL.md +0 -290
  115. package/.claude/skills/ask-sonner/API.md +0 -64
  116. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  117. package/.claude/skills/backend-development/SKILL.md +0 -272
  118. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  119. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  120. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  121. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  122. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  123. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  124. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  125. package/.claude/skills/improve-animations/SKILL.md +0 -109
  126. package/.claude/skills/mobile-native/SKILL.md +0 -311
  127. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  128. package/.claude/skills/prototype/PICKER.md +0 -197
  129. package/.claude/skills/prototype/SKILL.md +0 -98
  130. package/.claude/skills/review-animations/SKILL.md +0 -120
  131. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  132. package/.claude/skills/write-swift/SKILL.md +0 -396
  133. package/lib/intern-catalog.js +0 -53
@@ -0,0 +1,38 @@
1
+ <!-- Generated by scripts/sync-spec-pack.js from egagofur/elephant-goldfish-model@228457d1e0b6. Derived from the Elephant-Goldfish Model, Copyright Google LLC, Apache-2.0; modified: renamed to ael-spec-*, host-neutral references. Do not edit; run the script. -->
2
+
3
+ # Feature Specification Standard
4
+
5
+ This standard defines the quality bar for high-level feature specifications
6
+ before implementation begins.
7
+
8
+ ## Core Principle
9
+
10
+ A feature specification passes if a competent engineer (or fresh AI session) who
11
+ is unfamiliar with the codebase can understand the proposed feature, the
12
+ business motivation, and the design trade-offs, and confirm that all major risks
13
+ and alternatives have been addressed.
14
+
15
+ ## The Alternatives Rule
16
+
17
+ The specification must include a **mandatory evaluation of alternatives**. It
18
+ fails this standard if it proposes a single path without proving that other
19
+ viable designs were considered and rejected for specific, documented reasons
20
+ (including, but not limited to, complexity, cost, performance, or scalability).
21
+
22
+ ## Risks & Limits
23
+
24
+ The specification must explicitly call out its own constraints. It must identify
25
+ potential failure modes, security implications, scalability limits, and how they
26
+ will be mitigated.
27
+
28
+ ## Requirements (Non-Exhaustive Examples)
29
+
30
+ The specification must detail these areas if applicable to the changes:
31
+
32
+ * **Problem Statement**: The business or user problem being solved.
33
+ * **Goals & Non-Goals**: What the feature will and will not deliver.
34
+ * **Proposed Architecture**: Component layout, data flows, and ecosystem
35
+ integration.
36
+ * **Alternatives Considered**: Rejected options and rationale for rejection.
37
+ * **Risks & Mitigations**: Identified security, scalability, or complexity
38
+ risks.
@@ -0,0 +1,32 @@
1
+ <!-- Generated by scripts/sync-spec-pack.js from egagofur/elephant-goldfish-model@228457d1e0b6. Derived from the Elephant-Goldfish Model, Copyright Google LLC, Apache-2.0; modified: renamed to ael-spec-*, host-neutral references. Do not edit; run the script. -->
2
+
3
+ # Heilmeier Catechism Standard
4
+
5
+ This standard defines the quality bar for project proposals based on the
6
+ Heilmeier Catechism.
7
+
8
+ ## Core Principle
9
+
10
+ A proposal passes if a competent engineer (or fresh AI session) who is
11
+ unfamiliar with the project can understand the goals, risks, and value of the
12
+ proposed work, and confirm that all catechism questions are answered without
13
+ ambiguity.
14
+
15
+ ## Requirements (The Catechism Questions)
16
+
17
+ To satisfy this standard, the proposal must explicitly and clearly answer the
18
+ following questions:
19
+
20
+ * **Objectives**: What is being attempted? (Must be written with absolutely no
21
+ jargon).
22
+ * **State of the Art**: How is it done today, and what are the limits of
23
+ current practice?
24
+ * **New Approach**: What is new in the approach, and why is it expected to be
25
+ successful?
26
+ * **Impact**: Who cares? If successful, what difference will it make?
27
+ * **Risks**: What are the risks and the payoffs?
28
+ * **Cost**: How much will it cost in terms of resources, compute, or
29
+ headcount?
30
+ * **Timeline**: How long will it take?
31
+ * **Metrics & Exams**: What are the mid-term and final "exams" to check for
32
+ success?
@@ -0,0 +1,36 @@
1
+ <!-- Generated by scripts/sync-spec-pack.js from egagofur/elephant-goldfish-model@228457d1e0b6. Derived from the Elephant-Goldfish Model, Copyright Google LLC, Apache-2.0; modified: renamed to ael-spec-*, host-neutral references. Do not edit; run the script. -->
2
+
3
+ # Implementation Readiness Standard
4
+
5
+ This standard defines the quality bar for implementation plans and task lists.
6
+
7
+ ## Core Principle
8
+
9
+ A plan passes if a competent engineer (or fresh AI session) who is unfamiliar
10
+ with the codebase can execute the plan and produce the correct changes on the
11
+ first attempt, without guessing, asking clarifying questions, or making
12
+ independent design choices.
13
+
14
+ ## The Zero-Decision Rule
15
+
16
+ The plan must leave **zero design or architectural choices to the implementer**.
17
+ If the implementer must make design choices (including, but not limited to,
18
+ choosing a database schema, designing an API path, selecting a dependency, or
19
+ deciding how to handle a new edge case), the plan **fails** this standard. All
20
+ such decisions must be pre-determined and documented in the plan.
21
+
22
+ ## Phasing & Checkpoints
23
+
24
+ The plan must partition the work into logical, incremental phases. Each phase
25
+ must leave the codebase in a stable, buildable, and testable state.
26
+
27
+ ## Requirements (Non-Exhaustive Examples)
28
+
29
+ The plan must detail these areas if applicable to the proposed changes:
30
+
31
+ * **Target Scope**: Explicit list of files to be created, modified, or
32
+ deleted.
33
+ * **Actionable Steps**: Precise logic changes, data transformations, and API
34
+ updates for each file.
35
+ * **Test Plan**: Specific test cases (happy path and edge cases) that must be
36
+ implemented.
@@ -0,0 +1,39 @@
1
+ <!-- Generated by scripts/sync-spec-pack.js from egagofur/elephant-goldfish-model@228457d1e0b6. Derived from the Elephant-Goldfish Model, Copyright Google LLC, Apache-2.0; modified: renamed to ael-spec-*, host-neutral references. Do not edit; run the script. -->
2
+
3
+ # Re-Implementation Standard
4
+
5
+ This standard defines the quality bar for documenting codebase state.
6
+
7
+ ## Core Principle
8
+
9
+ A document passes if a competent engineer (or fresh AI session) who is
10
+ unfamiliar with the codebase can write functionally identical code on the first
11
+ attempt using *only* the document, without guessing or making independent design
12
+ choices.
13
+
14
+ ## The Zero-Assumption Rule
15
+
16
+ The document fails if the reader must guess parameter defaults, assume error
17
+ handling, choose design patterns, or infer output schemas. Every behaviorally
18
+ significant contract must be explicit.
19
+
20
+ ## Scope of Detail
21
+
22
+ * **Include**: External contracts (APIs, formats, side-effects), behavioral
23
+ rules (logic, state, errors), and performance constraints.
24
+ * **Exclude**: Syntax (loops, variable names), internal code organization
25
+ (private helpers), and non-observable structures (internal collections).
26
+
27
+ ## Requirements (Non-Exhaustive Examples)
28
+
29
+ Document these areas if applicable to the codebase scope:
30
+
31
+ * **APIs**: Signatures, types, and expected behavior.
32
+ * **Logic**: Control flow, algorithms, and validation.
33
+ * **Data**: Schemas, serialization, and state transitions.
34
+ * **Side Effects**: Database writes, network calls, logging, and metrics.
35
+ * **Dependencies**: System integrations and libraries.
36
+ * **Configuration**: Flags, parameters, and hooks.
37
+ * **Constraints**: Hardcoded limits and assumptions.
38
+ * **Errors**: Edge cases, empty states, and retries.
39
+ * **Tests**: Test helpers and mocks (if documenting tests).
@@ -0,0 +1,62 @@
1
+ <!-- Generated by scripts/sync-spec-pack.js from egagofur/elephant-goldfish-model@228457d1e0b6. Derived from the Elephant-Goldfish Model, Copyright Google LLC, Apache-2.0; modified: renamed to ael-spec-*, host-neutral references. Do not edit; run the script. -->
2
+
3
+ # Zoom Out Standard
4
+
5
+ This standard defines the quality bar for evaluating high-level designs,
6
+ architectures, and implementation plans from a high-altitude perspective.
7
+
8
+ ## Core Principle
9
+
10
+ A design passes if it solves the root problem in the simplest possible way,
11
+ leverages existing infrastructure and codebase conventions, avoids premature
12
+ optimization or speculative features (YAGNI), and maintains appropriate
13
+ abstraction boundaries without getting bogged down in low-level code
14
+ implementation details.
15
+
16
+ ## 0. Context Sufficiency (Prerequisite Check)
17
+
18
+ * **Understanding the Objective**: The document must contain enough
19
+ information to define the overall objective. If the reviewer cannot
20
+ determine *what* we are trying to achieve and *why*, the review must fail
21
+ immediately with a request for context.
22
+
23
+ ## 1. Root Problem Focus
24
+
25
+ * **Symptom vs. Root Cause**: The design must solve the underlying problem,
26
+ not just apply a local band-aid to symptoms.
27
+ * **Project Alignment**: The design must align with the high-level goals and
28
+ architectural philosophy defined in the project's root documentation
29
+ (`README.md` or `context.md`).
30
+
31
+ ## 2. Simplicity & Extensibility
32
+
33
+ * **YAGNI (You Aren't Gonna Need It)**: Reject abstractions, code paths, or
34
+ features built solely for speculative future requirements.
35
+ * **Premature Optimization**: Avoid introducing complexity (caching, sharding,
36
+ async queues) before performance bottlenecks are proven.
37
+ * **Minimalist Data Flow**: Ensure data passes through the minimal number of
38
+ components.
39
+ * **No Architectural Dead-Ends**: Use clean interfaces and boundaries to allow
40
+ future expansion without blocking it, without implementing speculative
41
+ features now.
42
+
43
+ ## 3. Anti-Weeds (Altitude Control)
44
+
45
+ * **Premature Detail**: High-level sections must focus on architecture,
46
+ interfaces, and data flows, not code-level implementation details (e.g.,
47
+ helper functions or loop variables).
48
+ * **Workarounds vs. Structural Fixes**: Avoid complex local workarounds;
49
+ propose changes to the root component if that is cleaner.
50
+ * **Right Placement (Architectural Fit)**: Ensure new logic is placed in the
51
+ correct layer/component according to separation of concerns.
52
+
53
+ ## 4. Leverage Existing
54
+
55
+ * **Codebase Reuse**: Search the codebase and reuse existing utilities,
56
+ classes, or modules instead of reinventing them. Ensure the candidate for
57
+ reuse is stable, maintained, and does not violate dependency boundaries.
58
+ * **Pattern Consistency**: Follow established design patterns in the codebase.
59
+ * **Platform Standards**: Use established ecosystem frameworks and standard libraries
60
+ instead of bespoke or ad-hoc custom solutions.
61
+ * **Identify Anti-Patterns**: Actively flag known anti-patterns
62
+ (e.g., bypassing standard authentication, hardcoding deployment configurations).
package/agents/maker.md CHANGED
@@ -62,7 +62,7 @@ flowchart LR
62
62
  ### Step 3: Run Deterministic Verification
63
63
  - Run test commands: `npx jest`, `pytest`, `cargo test`, `go test`, etc.
64
64
  - Run typecheck: `npx tsc --noEmit`, `mypy`, etc.
65
- - Run linter: `npx eslint --fix`, `ruff`, etc.
65
+ - Run linter: `npx eslint --fix`, `ruff`, etc. Auto-fixes change the diff, so run them **before** `gate maker`; after the gate, run linters in check mode only (a changed diff fails the verification gate).
66
66
  - Run build if applicable.
67
67
 
68
68
  ### Step 4: Submit to Adversarial Gate
@@ -14,11 +14,13 @@ AC source is the Goal Contract **file** only. Chat `setuju` and the parent trans
14
14
 
15
15
  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.
16
16
 
17
+ The gate recomputes the verdict from the ledger. To block on a problem the ledger lacks (wrong-artifact or happy-path-only evidence, an AC the tests do not prove), add it to `judgeFindings` in the Finding Ledger shape: VALID, BLOCKER or HIGH, with `location`, `failureScenario`, `evidence`, and `concreteAlternativeDiff`. A verdict that blocks without such a finding is rejected. You cannot PASS what the ledger blocks.
18
+
17
19
  ## Axes
18
20
 
19
21
  Do not merge Spec and Standards into one ranking.
20
22
 
21
- - Spec VALID BLOCKER or HIGH (or missing axis, treated as spec): ITERATE (ESCALATE if iteration is 3 or more)
23
+ - Spec VALID BLOCKER or HIGH (or missing axis, treated as spec): ITERATE (ESCALATE at the recipe's iteration cap, default 3)
22
24
  - Standards VALID BLOCKER or HIGH: ITERATE only when hardConvention is true
23
25
  - Other Standards findings: ACCEPT as tradeoff; may still PASS
24
26
  - INVALID findings: DISMISS, cannot block delivery
@@ -37,7 +39,8 @@ Return a fenced JSON block:
37
39
  "action": "Proceed to context impact assessment and delivery adapter",
38
40
  "blockingFindings": [],
39
41
  "acceptableTradeoffs": [],
40
- "dismissedFindings": []
42
+ "dismissedFindings": [],
43
+ "judgeFindings": []
41
44
  }
42
45
  ```
43
46