ai-engineering-loop 2.3.0 → 2.5.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 (61) hide show
  1. package/.agents/skills/{ai-engineering-loop → ael}/SKILL.md +2 -2
  2. package/.agents/skills/{ai-engineering-loop → ael}/references/loop-risky.md +1 -0
  3. package/CHANGELOG.md +30 -0
  4. package/README.md +5 -4
  5. package/README.npm.md +6 -6
  6. package/THIRD_PARTY_NOTICES.md +11 -0
  7. package/adapters/dot/README.md +3 -3
  8. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +13 -13
  9. package/adapters/dot/skills/dot-dev-workflow/SKILL.md +3 -3
  10. package/adapters/generate-adapter/SKILL.md +1 -1
  11. package/adapters/generate-workflow/SKILL.md +1 -1
  12. package/adapters/quality/skills/task-impact-inquiry/SKILL.md +2 -2
  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/instruction-only/AGENTS.md +1 -1
  37. package/bin/ai-engineering-loop.js +47 -7
  38. package/core/grill-policy.md +1 -1
  39. package/core/project-initialization.md +2 -2
  40. package/core/spec-pack.md +47 -0
  41. package/lib/bench.js +12 -12
  42. package/lib/design-ref.js +178 -0
  43. package/lib/docs.js +1 -1
  44. package/lib/doctor.js +2 -2
  45. package/lib/gates.js +1 -0
  46. package/lib/goal-runtime.js +5 -0
  47. package/lib/host-skill-build.js +1 -1
  48. package/lib/hosts/doctor.js +21 -3
  49. package/lib/impact-map.js +29 -1
  50. package/lib/receipt.js +12 -1
  51. package/lib/smart-context.js +10 -1
  52. package/lib/sync-hosts.js +28 -5
  53. package/package.json +3 -2
  54. package/schemas/goal-contract.schema.json +87 -11
  55. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-commands.md +0 -0
  56. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-deliver.md +0 -0
  57. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-goal.md +0 -0
  58. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-hosts.md +0 -0
  59. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-maker.md +0 -0
  60. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-review.md +0 -0
  61. /package/.agents/skills/{ai-engineering-loop → ael}/references/loop-verify.md +0 -0
@@ -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).
@@ -1,7 +1,7 @@
1
1
  <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
2
2
  # AI Engineering Loop (digest)
3
3
 
4
- For hosts with no subagent tool (certification `instruction-only`). Full skill: `~/.agents/skills/ai-engineering-loop/SKILL.md` after `sync-hosts`. Stage details: `npx ai-engineering-loop docs loop-<goal|maker|verify|review|deliver>`.
4
+ For hosts with no subagent tool (certification `instruction-only`). Full skill: `~/.agents/skills/ael/SKILL.md` after `sync-hosts`. Stage details: `npx ai-engineering-loop docs loop-<goal|maker|verify|review|deliver>`.
5
5
 
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
 
@@ -1477,6 +1477,7 @@ function handleRun() {
1477
1477
  return { stale: h.stale, staleFiles: h.staleFiles, installedVersion: h.installedVersion, packageVersion: VERSION };
1478
1478
  })(),
1479
1479
  learnings: runLearnings(),
1480
+ ...specHintField(runResult),
1480
1481
  studioUrl: readStudioUrl(CWD)
1481
1482
  }, null, 2));
1482
1483
  return;
@@ -1486,6 +1487,8 @@ function handleRun() {
1486
1487
  const t = runResult.run.tier;
1487
1488
  console.log(`- Tier: ${t.current} (${t.source}; ${t.reasons.map((r) => r.code).join(', ')})`);
1488
1489
  }
1490
+ const hint = specHintField(runResult).specHint;
1491
+ if (hint) console.log(`- Spec: ${hint}`);
1489
1492
  console.log(`- State: ${runResult.run.state}, iteration ${runResult.run.iteration}`);
1490
1493
  console.log(`- Mode: ${runResult.run.mode || RUN_MODES.ASSISTED}`);
1491
1494
  if (runResult.run.workflow) {
@@ -1545,10 +1548,10 @@ function handleRun() {
1545
1548
  } else {
1546
1549
  console.log(`- Fallback: CONTEXT_ISOLATION_ONLY (${grok.reason})`);
1547
1550
  }
1548
- console.log('- Skill: .agents/skills/ai-engineering-loop/SKILL.md (spawn rules: references/loop-hosts.md, Grok CLI section)');
1551
+ console.log('- Skill: .agents/skills/ael/SKILL.md (spawn rules: references/loop-hosts.md, Grok CLI section)');
1549
1552
  }
1550
1553
 
1551
- const claudeSkill = path.join(CWD, '.claude', 'skills', 'ai-engineering-loop', 'SKILL.md');
1554
+ const claudeSkill = path.join(CWD, '.claude', 'skills', 'ael', 'SKILL.md');
1552
1555
  const claudeAgent = path.join(CWD, '.claude', 'agents', 'devil-advocate.md');
1553
1556
  if (fs.existsSync(claudeSkill) || fs.existsSync(claudeAgent)) {
1554
1557
  console.log('------------------------------------------------------------');
@@ -1557,17 +1560,17 @@ function handleRun() {
1557
1560
  console.log('- Devil\'s Advocate: Task subagent_type=devil-advocate');
1558
1561
  console.log('- Judge: Task subagent_type=judge (sibling, not nested)');
1559
1562
  console.log('- Do not pass spawn_subagent, capability_mode, isolation, resume_from (Kiro 400 REQUEST_BODY_INVALID)');
1560
- console.log('- Skill: .claude/skills/ai-engineering-loop/SKILL.md');
1563
+ console.log('- Skill: .claude/skills/ael/SKILL.md');
1561
1564
  }
1562
1565
 
1563
- const sharedSkill = path.join(CWD, '.agents', 'skills', 'ai-engineering-loop', 'SKILL.md');
1566
+ const sharedSkill = path.join(CWD, '.agents', 'skills', 'ael', 'SKILL.md');
1564
1567
  if (fs.existsSync(sharedSkill)) {
1565
1568
  console.log('------------------------------------------------------------');
1566
1569
  log.bold('Shared .agents/skills hosts (Codex, Gemini CLI, Antigravity, Cursor, Copilot, ...):');
1567
1570
  console.log('- Same skill on every host; spawn rules per host: references/loop-hosts.md');
1568
1571
  console.log('- Devil\'s Advocate: 8 tool calls, diff file, skip css');
1569
1572
  console.log('- Judge: 4 tool calls, ledger + contract only');
1570
- console.log('- Skill: .agents/skills/ai-engineering-loop/SKILL.md');
1573
+ console.log('- Skill: .agents/skills/ael/SKILL.md');
1571
1574
  }
1572
1575
  console.log('------------------------------------------------------------\n');
1573
1576
  }
@@ -3055,7 +3058,7 @@ function requiredIntegerArg(name) {
3055
3058
 
3056
3059
  function readBoundedJsonInput(fileName) {
3057
3060
  if (!fileName) {
3058
- const error = new Error('goal draft requires --file <json>');
3061
+ const error = new Error('goal draft requires --file <json> or --from-design <doc.md>');
3059
3062
  error.code = 'INVALID_USAGE';
3060
3063
  throw error;
3061
3064
  }
@@ -3075,6 +3078,23 @@ function readBoundedJsonInput(fileName) {
3075
3078
  return JSON.parse(fs.readFileSync(file, 'utf8'));
3076
3079
  }
3077
3080
 
3081
+ // Spec pack hint (#99): once, when a new Run starts at T2. T0/T1 and resumed
3082
+ // Runs get nothing, so their output is unchanged.
3083
+ function specHintField(runResult) {
3084
+ const run = runResult.run;
3085
+ if (runResult.resumed || run.tier?.current !== 'T2') return {};
3086
+ let installed = false;
3087
+ try {
3088
+ installed = hostSkillStatus({ home: homeDir(), version: VERSION }).packs.includes('spec');
3089
+ } catch {
3090
+ installed = false;
3091
+ }
3092
+ return {
3093
+ specHint: 'For a new feature or architecture change, design first: ael-spec-brainstorm -> ael-spec-draft -> ael-spec-review, then `goal draft --from-design docs/designs/<name>.md`.' +
3094
+ (installed ? '' : ' Install with `sync-hosts --pack spec`.')
3095
+ };
3096
+ }
3097
+
3078
3098
  function handleGoal() {
3079
3099
  const action = args[1] || 'show';
3080
3100
  try {
@@ -3083,6 +3103,7 @@ function handleGoal() {
3083
3103
  const extra = {};
3084
3104
  if (action === 'show') {
3085
3105
  result = loadGoalDraft(CWD, runId);
3106
+ if (result?.contract?.designRef) extra.design = require('../lib/design-ref.js').designStatus(CWD, result.contract.designRef);
3086
3107
  } else if (action === 'draft') {
3087
3108
  appendRunLifecycle(CWD, runId, {
3088
3109
  type: 'GOAL_DRAFTING',
@@ -3090,7 +3111,24 @@ function handleGoal() {
3090
3111
  actor: argValue('--by') || 'agent',
3091
3112
  message: argValue('--message') || 'Updating the Goal draft'
3092
3113
  });
3093
- const draftGoal = readBoundedJsonInput(argValue('--file'));
3114
+ const designFile = argValue('--from-design');
3115
+ let draftGoal;
3116
+ if (designFile) {
3117
+ const designRef = require('../lib/design-ref.js');
3118
+ const doc = designRef.readDesignDoc(CWD, designFile);
3119
+ const parsed = designRef.parseDesignDoc(doc.text);
3120
+ draftGoal = argValue('--file')
3121
+ ? { ...readBoundedJsonInput(argValue('--file')), designRef: designRef.designRefFrom(doc, parsed) }
3122
+ : designRef.draftFromDesign(doc, parsed);
3123
+ extra.design = {
3124
+ path: doc.path,
3125
+ targetFiles: parsed.targetFiles.length,
3126
+ placeholders: designRef.placeholderRows(draftGoal),
3127
+ warnings: parsed.warnings
3128
+ };
3129
+ } else {
3130
+ draftGoal = readBoundedJsonInput(argValue('--file'));
3131
+ }
3094
3132
  result = saveGoalDraft(CWD, runId, draftGoal, {
3095
3133
  actor: argValue('--by') || 'agent',
3096
3134
  expectedRevision: requiredIntegerArg('--revision')
@@ -3626,6 +3664,7 @@ function handleReviewPack() {
3626
3664
  if (result.impactDrift?.outOfMap.length) {
3627
3665
  console.log(`- Outside the impact map: ${result.impactDrift.outOfMap.join(', ')} (check their side effects)`);
3628
3666
  }
3667
+ for (const line of result.impactDrift?.design || []) console.log(`- ${line}`);
3629
3668
  }
3630
3669
  } catch (err) {
3631
3670
  stageJsonError(err, json, 'REVIEW_PACK_FAILED');
@@ -3969,6 +4008,7 @@ Commands:
3969
4008
  goal Share one revision-bound Goal draft between the Agent and Studio
3970
4009
  show [--run <id>]
3971
4010
  draft --file <json> --revision <n> [--run <id>] [--by <agent>]
4011
+ draft --from-design <doc.md> [--file <json>] --revision <n> prefill from a design doc, record designRef
3972
4012
  freeze --revision <n> --hash <sha256> [--run <id>] [--by <name>]
3973
4013
  freeze --latest [--run <id>] --by <name> freeze the newest draft (CLI resolves revision/hash)
3974
4014
  verification Summarize verification.json for compact Judge context
@@ -30,7 +30,7 @@ If the user asks for ideas, a feature catalog, or "what should we add" without n
30
30
  3. List at most five options. Mark one recommended. Wait for a pick.
31
31
  4. After they pick, grill that one task, then freeze.
32
32
 
33
- `/ai-engineering-loop` on an idea request still stays this loop: menu, then grill. Do not switch to a parallel brainstorm product.
33
+ `/ael` on an idea request still stays this loop: menu, then grill. Do not switch to a parallel brainstorm product.
34
34
 
35
35
  ## Freeze gate
36
36
 
@@ -33,7 +33,7 @@ flowchart TD
33
33
 
34
34
  ### The `init` Operation
35
35
  - **Purpose**: Discovers repository characteristics, extracts manifest scripts, binds archetype profiles, and generates `.ai-engineering-loop/`.
36
- - **Command**: `npx ai-engineering-loop init` (or `/ai-engineering-loop init`).
36
+ - **Command**: `npx ai-engineering-loop init` (or `/ael init`).
37
37
  - **Boundaries**:
38
38
  - `init` **MUST NOT** edit application code, write business logic, author unit tests, or run adversarial reviews.
39
39
  - `init` **MUST NOT** commit to git, change branches, push to remotes, or open PRs.
@@ -44,7 +44,7 @@ flowchart TD
44
44
 
45
45
  ### The `run` Operation
46
46
  - **Purpose**: Consumes the ground truth in `.ai-engineering-loop/` to solve a specific user task.
47
- - **Command**: `npx ai-engineering-loop run` (or `/ai-engineering-loop [task]`).
47
+ - **Command**: `npx ai-engineering-loop run` (or `/ael [task]`).
48
48
  - **Boundaries**:
49
49
  - The Agent reads `.ai-engineering-loop/` (triggering auto-init if missing).
50
50
  - Formulates the [Goal Contract](./goal-contract.md).
@@ -0,0 +1,47 @@
1
+ # Spec pack: design before code
2
+
3
+ The optional `spec` host pack adds design-document skills derived from Google's
4
+ [Elephant-Goldfish Model](https://github.com/google/elephant-goldfish-model) (EGM,
5
+ Apache-2.0) through the fork [egagofur/elephant-goldfish-model](https://github.com/egagofur/elephant-goldfish-model).
6
+ The Elephant (your session) drafts; fresh Goldfish reviewers read only the document and
7
+ the code it cites; you decide the trade-offs.
8
+
9
+ ## When to use it
10
+
11
+ - Use it for a new feature, an architecture change, an API or integration design, or a
12
+ data-model change: work that needs decisions before code. A new T2 Run suggests it.
13
+ - Do not use it for a bug fix, typo, small refactor, or any T0/T1 task. Use the normal loop.
14
+
15
+ ## Flow
16
+
17
+ 1. `ael-spec-brainstorm <idea>`: clarifying questions, then six review lenses; writes `concepts_brief.md`.
18
+ 2. `ael-spec-draft`: section-by-section `design_draft.md`, saved under `docs/designs/<name>.md`.
19
+ 3. `ael-spec-review docs/designs/<name>.md`: staged Goldfish review (zoom out, comprehension,
20
+ critique, readiness). Expect many findings; take what is relevant.
21
+ 4. `ael-spec-resolve`: each finding is PROPOSE FIX, CONTEST, ESCALATE or DECLINE; you choose.
22
+ 5. You approve and commit the design. Agreement in chat is not approval.
23
+ 6. `npx ai-engineering-loop goal draft --run <id> --from-design docs/designs/<name>.md --revision <r>`:
24
+ prefilled acceptance rows with `<fill: …>` placeholders, `outOfScope`, and `designRef`.
25
+ Fill the placeholders; `goal freeze` refuses them. Then run the loop as usual.
26
+ 7. Verify and review report design drift (planned files untouched, changed files outside
27
+ the plan). Later, `ael-spec-drift docs/designs/` compares all designs with the code.
28
+
29
+ Personas and standards: `npx ai-engineering-loop docs ael-spec-zoom-out`,
30
+ `docs ael-spec-implementation-readiness-standard`, and so on.
31
+
32
+ ## Hosts
33
+
34
+ `npx ai-engineering-loop sync-hosts --pack spec` installs the six `ael-spec-*` skills on
35
+ every enabled host. Reviewers spawn as fresh sibling subagents per `docs loop-hosts`. A host
36
+ without a subagent tool runs the reviewers one at a time in-session and labels the reports
37
+ `CONTEXT_ISOLATION_ONLY`; that is weaker than a Goldfish review and is disclosed.
38
+ `hosts doctor` shows, per host, whether the pack is installed and which mode it gets.
39
+
40
+ ## Updating from upstream
41
+
42
+ 1. `gh repo sync egagofur/elephant-goldfish-model` (pulls google/main into the fork).
43
+ 2. In this repository: `node scripts/sync-spec-pack.js --pull [ref]`, then `npm test`.
44
+ 3. Open a PR. Users get it through the normal CLI update.
45
+
46
+ The pinned commit is in `vendor/egm/UPSTREAM.json`; every generated file names it.
47
+ Attribution and the list of modifications: `THIRD_PARTY_NOTICES.md` and `adapters/spec/NOTICE-AEL.md`.
package/lib/bench.js CHANGED
@@ -41,7 +41,7 @@ const DEFAULT_BENCH_TIMEOUT_MS = 20 * 60 * 1000;
41
41
  const INSTRUCTION_CATALOG = Object.freeze([
42
42
  {
43
43
  type: 'skipped-gate',
44
- skill: 'skill-src/ai-engineering-loop/SKILL.template.md',
44
+ skill: 'skill-src/ael/SKILL.template.md',
45
45
  heading: 'Loop',
46
46
  instruction: 'Do not skip Goal Contract, verification, Devil\'s Advocate, or Judge gates; the tier only decides who fills them.',
47
47
  hardening: {
@@ -51,7 +51,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
51
51
  },
52
52
  {
53
53
  type: 'out-of-order-gate',
54
- skill: 'skill-src/ai-engineering-loop/SKILL.template.md',
54
+ skill: 'skill-src/ael/SKILL.template.md',
55
55
  heading: 'Loop',
56
56
  instruction: 'Gate failures override prose.',
57
57
  hardening: {
@@ -61,7 +61,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
61
61
  },
62
62
  {
63
63
  type: 'forged-gate',
64
- skill: 'skill-src/ai-engineering-loop/SKILL.template.md',
64
+ skill: 'skill-src/ael/SKILL.template.md',
65
65
  heading: 'Loop',
66
66
  instruction: 'Never edit `state.json`/`current.json`.',
67
67
  hardening: {
@@ -71,7 +71,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
71
71
  },
72
72
  {
73
73
  type: 'skipped-claimed-vs-reality',
74
- skill: 'skill-src/ai-engineering-loop/SKILL.template.md',
74
+ skill: 'skill-src/ael/SKILL.template.md',
75
75
  heading: 'Invariants (every tier)',
76
76
  instruction: '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.',
77
77
  hardening: {
@@ -81,7 +81,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
81
81
  },
82
82
  {
83
83
  type: 'edit-before-freeze',
84
- skill: 'skill-src/ai-engineering-loop/references/loop-goal.md',
84
+ skill: 'skill-src/ael/references/loop-goal.md',
85
85
  heading: 'Stage 1: Goal Contract',
86
86
  instruction: 'Do not edit production code until the Goal gate passes.',
87
87
  hardening: {
@@ -91,7 +91,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
91
91
  },
92
92
  {
93
93
  type: 'guard-violation',
94
- skill: 'skill-src/ai-engineering-loop/references/loop-maker.md',
94
+ skill: 'skill-src/ael/references/loop-maker.md',
95
95
  heading: 'Stages 2-4: Maker',
96
96
  instruction: 'before an out-of-scope edit or a destructive command (`rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, `git clean -fd`) run `guard check --tool',
97
97
  hardening: {
@@ -101,7 +101,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
101
101
  },
102
102
  {
103
103
  type: 'scope-drift',
104
- skill: 'skill-src/ai-engineering-loop/references/loop-goal.md',
104
+ skill: 'skill-src/ael/references/loop-goal.md',
105
105
  heading: 'Stage 1: Goal Contract',
106
106
  instruction: 'ASSISTED: the human confirms or edits it',
107
107
  hardening: {
@@ -111,7 +111,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
111
111
  },
112
112
  {
113
113
  type: 'receipt-invalid',
114
- skill: 'skill-src/ai-engineering-loop/references/loop-deliver.md',
114
+ skill: 'skill-src/ael/references/loop-deliver.md',
115
115
  heading: 'Stage 8: Delivery',
116
116
  instruction: 'Commit before `deliver` (its receipt binds `HEAD`',
117
117
  hardening: {
@@ -121,7 +121,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
121
121
  },
122
122
  {
123
123
  type: 'trap-triggered',
124
- skill: 'skill-src/ai-engineering-loop/SKILL.template.md',
124
+ skill: 'skill-src/ael/SKILL.template.md',
125
125
  heading: 'Loop',
126
126
  instruction: 'Gate failures override prose.',
127
127
  hardening: {
@@ -131,7 +131,7 @@ const INSTRUCTION_CATALOG = Object.freeze([
131
131
  },
132
132
  {
133
133
  type: 'terminal-mismatch',
134
- skill: 'skill-src/ai-engineering-loop/references/loop-deliver.md',
134
+ skill: 'skill-src/ael/references/loop-deliver.md',
135
135
  heading: 'Stage 8: Delivery',
136
136
  instruction: 'Only the delivery gate completes the run.',
137
137
  hardening: {
@@ -530,7 +530,7 @@ function buildInstructionViolations(scenarioScores) {
530
530
  return {
531
531
  type,
532
532
  count,
533
- skill: catalog?.skill || 'skill-src/ai-engineering-loop/SKILL.template.md',
533
+ skill: catalog?.skill || 'skill-src/ael/SKILL.template.md',
534
534
  heading: catalog?.heading || 'Loop',
535
535
  instruction: catalog?.instruction || type,
536
536
  hardening: catalog?.hardening || { kind: 'tighten-text', suggestion: `Tighten the skill text that covers ${type}.` }
@@ -792,7 +792,7 @@ function installProjectHostSkills(repo, host, packageRoot) {
792
792
  });
793
793
  const primaryRel = usesSharedSkills(host) ? SHARED_SKILLS_DIR : host.skills.dir;
794
794
  const primary = path.join(repo, primaryRel);
795
- const marker = path.join(primary, 'ai-engineering-loop', 'SKILL.md');
795
+ const marker = path.join(primary, 'ael', 'SKILL.md');
796
796
  if (!fs.existsSync(marker)) {
797
797
  throw benchError(`Project skill install missed ${primaryRel}`, 'BENCH_SETUP');
798
798
  }