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.
- package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
- package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
- package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
- package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
- package/.agents/skills/ai-engineering-loop/references/loop-risky.md +1 -0
- package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
- package/.claude/agents/judge.md +5 -2
- package/.grok/agents/judge.md +5 -2
- package/CHANGELOG.md +60 -0
- package/README.md +1 -0
- package/THIRD_PARTY_NOTICES.md +11 -0
- package/adapters/spec/LICENSE +202 -0
- package/adapters/spec/NOTICE-AEL.md +26 -0
- package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
- package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
- package/adapters/spec/agents/ael-spec-design.md +65 -0
- package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
- package/adapters/spec/agents/ael-spec-structural.md +67 -0
- package/adapters/spec/agents/ael-spec-style.md +68 -0
- package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
- package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
- package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
- package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
- package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
- package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
- package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
- package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
- package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
- package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
- package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
- package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
- package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
- package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
- package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
- package/agents/maker.md +1 -1
- package/agents/shared/judge.body.md +5 -2
- package/bin/ai-engineering-loop.js +344 -78
- package/core/definition-of-done.md +2 -2
- package/core/escalation-policy.md +1 -1
- package/core/goal-contract.md +1 -1
- package/core/iteration-policy.md +2 -1
- package/core/judge-policy.md +10 -4
- package/core/orchestration-model.md +8 -7
- package/core/repo-config-schema.md +2 -2
- package/core/runtime-safety.md +3 -3
- package/core/spec-pack.md +47 -0
- package/lib/auto-update.js +8 -14
- package/lib/claimed-vs-reality.js +2 -2
- package/lib/cli-args.js +3 -1
- package/lib/design-ref.js +178 -0
- package/lib/docs.js +1 -1
- package/lib/doctor.js +0 -6
- package/lib/escalation.js +1 -1
- package/lib/fsutil.js +88 -0
- package/lib/gates.js +70 -27
- package/lib/generate-workflow.js +0 -29
- package/lib/goal-runtime.js +8 -2
- package/lib/guard-hooks.js +26 -7
- package/lib/guard.js +100 -10
- package/lib/hosts/doctor.js +17 -7
- package/lib/impact-map.js +31 -8
- package/lib/jsonl-ledger.js +104 -0
- package/lib/learn.js +4 -9
- package/lib/loop-groups.js +0 -25
- package/lib/migrations.js +1 -5
- package/lib/no-progress.js +119 -0
- package/lib/node-evidence.js +1 -5
- package/lib/orchestration.js +5 -361
- package/lib/personal-workflow.js +1 -1
- package/lib/quick.js +152 -0
- package/lib/receipt.js +13 -6
- package/lib/recipe-builder.js +3 -35
- package/lib/recipe-graph.js +2 -63
- package/lib/recipe.js +2 -4
- package/lib/review-ingest.js +116 -0
- package/lib/run-abandon.js +2 -1
- package/lib/run-compaction.js +4 -12
- package/lib/run-interactions.js +16 -71
- package/lib/run-lifecycle.js +25 -77
- package/lib/run-state.js +68 -17
- package/lib/run-watcher.js +11 -14
- package/lib/runtime-files.js +45 -1
- package/lib/safe-context.js +17 -6
- package/lib/sandbox.js +2 -1
- package/lib/smart-context.js +13 -14
- package/lib/spawn-command.js +94 -0
- package/lib/studio-layout.js +2 -8
- package/lib/studio-runtime.js +2 -1
- package/lib/studio-server.js +25 -5
- package/lib/sync-hosts.js +25 -2
- package/lib/tier.js +36 -10
- package/lib/user-state.js +2 -17
- package/lib/verification-lanes.js +115 -0
- package/lib/verification-recorder.js +110 -22
- package/lib/workflow-runtime.js +7 -4
- package/package.json +1 -2
- package/policies/review-budget.md +1 -1
- package/schemas/goal-contract.schema.json +87 -11
- package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
- package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
- package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
- package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
- package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
- package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
- package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
- package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
- package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
- package/.claude/skills/animate/RECIPES.md +0 -324
- package/.claude/skills/animate/SKILL.md +0 -207
- package/.claude/skills/animate-expo/RECIPES.md +0 -385
- package/.claude/skills/animate-expo/SKILL.md +0 -263
- package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
- package/.claude/skills/apple-design/SKILL.md +0 -290
- package/.claude/skills/ask-sonner/API.md +0 -64
- package/.claude/skills/ask-sonner/SKILL.md +0 -88
- package/.claude/skills/backend-development/SKILL.md +0 -272
- package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
- package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
- package/.claude/skills/backend-development/references/security-checklist.md +0 -60
- package/.claude/skills/emil-design-eng/SKILL.md +0 -674
- package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
- package/.claude/skills/improve-animations/AUDIT.md +0 -115
- package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
- package/.claude/skills/improve-animations/SKILL.md +0 -109
- package/.claude/skills/mobile-native/SKILL.md +0 -311
- package/.claude/skills/pick-ui-library/SKILL.md +0 -85
- package/.claude/skills/prototype/PICKER.md +0 -197
- package/.claude/skills/prototype/SKILL.md +0 -98
- package/.claude/skills/review-animations/SKILL.md +0 -120
- package/.claude/skills/review-animations/STANDARDS.md +0 -187
- package/.claude/skills/write-swift/SKILL.md +0 -396
- 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
|
|
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
|
|