ai-engineering-loop 2.3.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/references/loop-risky.md +1 -0
- package/CHANGELOG.md +25 -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/bin/ai-engineering-loop.js +42 -2
- package/core/spec-pack.md +47 -0
- package/lib/design-ref.js +178 -0
- package/lib/gates.js +1 -0
- package/lib/goal-runtime.js +5 -0
- package/lib/hosts/doctor.js +16 -2
- package/lib/impact-map.js +29 -1
- package/lib/receipt.js +12 -1
- package/lib/smart-context.js +10 -1
- package/lib/sync-hosts.js +25 -2
- package/package.json +1 -1
- package/schemas/goal-contract.schema.json +87 -11
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ael-spec-review-loop
|
|
3
|
+
license: Apache-2.0
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
description: >-
|
|
6
|
+
Executes the Antagonistic-Review process from the Elephant-Goldfish
|
|
7
|
+
Model (EGM) via an automated multi-agent review loop to audit documents
|
|
8
|
+
against qualitative standards and structural templates, and automatically
|
|
9
|
+
apply approved fixes. Use when reviewing design docs, READMEs, feature
|
|
10
|
+
specifications, implementation plans, or verifying document completeness
|
|
11
|
+
and tone.
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
<!-- 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. -->
|
|
15
|
+
|
|
16
|
+
# Goldfish Review: Loop (Orchestration Driver)
|
|
17
|
+
|
|
18
|
+
Host rules: spawn each Goldfish reviewer as a fresh sibling subagent with your host's subagent tool, as described in `npx ai-engineering-loop docs loop-hosts` (read only your host's section). Personas and standards named below resolve with `npx ai-engineering-loop docs <name>`.
|
|
19
|
+
|
|
20
|
+
## Overview
|
|
21
|
+
|
|
22
|
+
This skill acts as the central orchestration engine driving the multi-agent
|
|
23
|
+
review loop. It coordinates two distinct agent memory models:
|
|
24
|
+
|
|
25
|
+
* **The Goldfish (Adversarial Auditors)**: Subagents spawned in isolated,
|
|
26
|
+
fresh context windows to catch unstated assumptions without historical bias.
|
|
27
|
+
* **The Elephant (Persistent Resolver)**: The primary agent context holding
|
|
28
|
+
institutional knowledge to evaluate findings and apply approved repairs.
|
|
29
|
+
|
|
30
|
+
The driver manages argument intake, resolves paths for reviewers and standards,
|
|
31
|
+
unconditionally re-parses target line ranges before every iteration, spawns
|
|
32
|
+
concurrent specialized Goldfish auditors based on configuration, and coordinates
|
|
33
|
+
with the Elephant context to resolve findings.
|
|
34
|
+
|
|
35
|
+
## Delegation
|
|
36
|
+
|
|
37
|
+
A Goldfish runs in a fresh context with no conversation history. Spawn each
|
|
38
|
+
subagent with your harness's subagent tool (per host in `npx ai-engineering-loop docs loop-hosts`; for example Grok CLI `spawn_subagent`, Claude Code `Task` or `Agent`, Codex `spawn_agent`, Antigravity `invoke_subagent`). Each subagent is a persona doc (`npx ai-engineering-loop docs <name>`), and its
|
|
39
|
+
frontmatter `name` (for example `ael-spec-zoom-out`) is the subagent type to request
|
|
40
|
+
where your harness registers named subagents. Otherwise spawn a general-purpose
|
|
41
|
+
subagent and tell it to read that persona file first. Pass the prompt verbatim
|
|
42
|
+
and wait for the report. If your harness cannot nest subagents,
|
|
43
|
+
use direct dispatch instead of the synthesizer. See `npx ai-engineering-loop docs loop-hosts`.
|
|
44
|
+
If your host has no subagent tool, do not stop: run each reviewer one at a time in this session, reading only its persona, the standard, and the document (not the earlier conversation), label every report `Review Method: CONTEXT_ISOLATION_ONLY (not an independent Goldfish review)`, and tell the user.
|
|
45
|
+
|
|
46
|
+
## Inputs
|
|
47
|
+
|
|
48
|
+
The caller or user provides exactly these parameters:
|
|
49
|
+
|
|
50
|
+
* **`TargetFile`**: Absolute or relative path to target document.
|
|
51
|
+
* **`SemanticTarget`**: Descriptive targeting string (e.g., *"Target the H4
|
|
52
|
+
block with SS-ID 'S1.12'"*), or `full file`.
|
|
53
|
+
* **`Reviewers`**: List of reviewer names (shortnames or paths).
|
|
54
|
+
* **`Standards`**: Mapping of reviewer names to standard names (shortnames or
|
|
55
|
+
paths).
|
|
56
|
+
* **`GoldfishContext`**: A reading list (source files, directories, or
|
|
57
|
+
documentation URLs) fed to reviewers to establish their baseline.
|
|
58
|
+
|
|
59
|
+
## Path & Standard Resolution Logic
|
|
60
|
+
|
|
61
|
+
When resolving names in `Reviewers` and `Standards`:
|
|
62
|
+
|
|
63
|
+
* **Reviewer Shortnames**: Map reviewer shortname (e.g., `design_critic`,
|
|
64
|
+
`structural`, `style`, `implementation_readiness`,
|
|
65
|
+
`codebase_details`, `comprehension`, `zoom_out`) to `npx ai-engineering-loop docs ael-spec-<persona>`, where `<persona>` is the shortname with `_` written as `-` (`design_critic` is `ael-spec-design`), or an `ael-spec-*` name as is.
|
|
66
|
+
The persona file defines the reviewer's core mandates, audit vectors, and
|
|
67
|
+
output format.
|
|
68
|
+
* **Standard Shortnames**: Map standard shortname (e.g., `feature-spec-standard`,
|
|
69
|
+
`implementation-readiness-standard`, `zoom-out-standard`, `heilmeier-standard`,
|
|
70
|
+
`re-implementation-standard`) to `npx ai-engineering-loop docs ael-spec-{name}`.
|
|
71
|
+
* **Custom Paths**: If the name contains a slash (`/`), treat it as an
|
|
72
|
+
absolute or workspace-relative path and read it directly.
|
|
73
|
+
|
|
74
|
+
## Execution Workflow
|
|
75
|
+
|
|
76
|
+
### Step 1: Intake & Configuration UX
|
|
77
|
+
|
|
78
|
+
Evaluate the provided inputs (`TargetFile`, `SemanticTarget`, `Reviewers`,
|
|
79
|
+
`Standards`, `GoldfishContext`).
|
|
80
|
+
|
|
81
|
+
1. **Identify Missing Inputs**: Determine which of the required parameters are
|
|
82
|
+
missing.
|
|
83
|
+
2. **Interactive Onboarding**:
|
|
84
|
+
* If **all** inputs are present, proceed to Step 2.
|
|
85
|
+
* If **some or all** inputs are missing, interactively prompt the user
|
|
86
|
+
**only for the missing inputs**, one at a time via chat messages.
|
|
87
|
+
3. **Reviewer Recommendations**:
|
|
88
|
+
* *Feature Specs*: Recommend `design_critic` (mapped to
|
|
89
|
+
`npx ai-engineering-loop docs ael-spec-feature-spec-standard`) and
|
|
90
|
+
`structural` (mapped to `npx ai-engineering-loop docs ael-spec-feature-spec-standard`).
|
|
91
|
+
* *Implementation Plans*: Recommend `implementation_readiness`
|
|
92
|
+
(mapped to `npx ai-engineering-loop docs ael-spec-implementation-readiness-standard`)
|
|
93
|
+
and `codebase_details`.
|
|
94
|
+
4. **Confirm Configuration**: Display the consolidated plan (Target, Reviewers,
|
|
95
|
+
and mapped Standards) and ask the user to confirm before proceeding.
|
|
96
|
+
|
|
97
|
+
### Step 2: The Sharpening Loop (Iterative Cycle)
|
|
98
|
+
|
|
99
|
+
Execute the following sequence in a continuous loop:
|
|
100
|
+
|
|
101
|
+
#### 2.1 Unconditional Target Resolution
|
|
102
|
+
|
|
103
|
+
Before every iteration, unconditionally re-scan `TargetFile` by reading it
|
|
104
|
+
and using the stable `SemanticTarget` string (e.g., locating the target header) to
|
|
105
|
+
dynamically determine the updated absolute start and end line numbers. This
|
|
106
|
+
ensures absolute accuracy even if the file was edited in prior rounds. (If `full
|
|
107
|
+
file` mode is specified, confirm full-file line bounds).
|
|
108
|
+
|
|
109
|
+
#### 2.2 Review Swarm Execution
|
|
110
|
+
|
|
111
|
+
1. **Launch Subagent Swarm**:
|
|
112
|
+
Spawn subagents to execute the review:
|
|
113
|
+
* **Hierarchical Dispatch (Synthesizer)**: Spawn the intermediate
|
|
114
|
+
synthesizer subagent (`npx ai-engineering-loop docs ael-spec-synthesizer` / `ael-spec-synthesizer`).
|
|
115
|
+
The synthesizer spawns the Goldfish review swarm in
|
|
116
|
+
parallel, deduplicates findings, writes the report artifact, and
|
|
117
|
+
returns a single summary message to avoid context pollution in the root
|
|
118
|
+
conversation. Pass it the Failed Reviewers rule below. Its summary must
|
|
119
|
+
give a status, `completed` or `not run`, for each requested reviewer.
|
|
120
|
+
* **Direct Dispatch (Flat Swarm)**: Alternatively, spawn each requested
|
|
121
|
+
reviewer subagent in `Reviewers` directly.
|
|
122
|
+
Instruct each subagent to first read its persona definition in
|
|
123
|
+
`npx ai-engineering-loop docs ael-spec-<persona>`, where `<persona>` is the shortname with `_` written as `-` (`design_critic` is `ael-spec-design`), or an `ael-spec-*` name as is, then audit `TargetFile` at the resolved line range
|
|
124
|
+
against its designated standard in the `ael-spec-*-standard` docs,
|
|
125
|
+
supplying `GoldfishContext`.
|
|
126
|
+
* Each reviewer produces findings with severity (🔴 Blocker, 🟡 Major, 🟢
|
|
127
|
+
Nit), line numbers, discrepancy descriptions, and rationales.
|
|
128
|
+
2. **Consolidate Findings**: Collect all findings across reviewers into a single
|
|
129
|
+
flat `FindingsList`. Give each finding a stable id
|
|
130
|
+
(`<reviewer>-<round>-<n>`) and record its reviewer, severity, and affected
|
|
131
|
+
scope.
|
|
132
|
+
3. **Failed Reviewers**: A reviewer that times out, fails, or returns no report
|
|
133
|
+
did not review. Retry it once. If it fails again, record it as **not run**
|
|
134
|
+
in the report. Never count it as a reviewer with zero findings. If the
|
|
135
|
+
synthesizer summary has no status for a requested reviewer, record that
|
|
136
|
+
reviewer as not run.
|
|
137
|
+
|
|
138
|
+
#### 2.3 Aggregated Resolution Hand-off
|
|
139
|
+
|
|
140
|
+
1. Pass `TargetFile`, the active line range, and the aggregated `FindingsList`
|
|
141
|
+
to the **`ael-spec-resolve`** workflow.
|
|
142
|
+
2. Execute the resolution workflow in the primary Elephant context:
|
|
143
|
+
* Categorize findings into `CONTEST` vs. `PROPOSE FIX`.
|
|
144
|
+
* Save `goldfish_review_report.md` with your file-writing tool.
|
|
145
|
+
* Present the interactive decision gate (Auto accept, Continue, Interactive
|
|
146
|
+
breakdown).
|
|
147
|
+
* Apply approved text repairs to `TargetFile` using your file-editing tool.
|
|
148
|
+
|
|
149
|
+
#### 2.4 Iteration Check & Turn Boundary
|
|
150
|
+
|
|
151
|
+
Fresh reviewers sample differently each round, so a round with zero findings
|
|
152
|
+
is rare even when the document improves. Use these rules instead:
|
|
153
|
+
|
|
154
|
+
* **Settled findings**: A finding is settled when it is contested or
|
|
155
|
+
recorded without a fix (accepted risk). Keep the settled list across
|
|
156
|
+
rounds. If a new reviewer raises a settled finding again (same affected
|
|
157
|
+
scope, same issue), do not re-open it.
|
|
158
|
+
* **Fixed findings**: An applied fix does not settle a finding. If a later
|
|
159
|
+
reviewer raises the same issue at the same scope, the fix failed or a
|
|
160
|
+
later edit reintroduced the issue. Re-open the finding.
|
|
161
|
+
* **Clean round**: A round is clean when no reviewer raises a Blocker or
|
|
162
|
+
Major finding that is not settled. Nits do not block. A reviewer recorded
|
|
163
|
+
as not run makes the round not clean. Decide this from the review results,
|
|
164
|
+
before you apply the fixes of that round.
|
|
165
|
+
* **Converged**: Two consecutive clean rounds. One clean round is not enough,
|
|
166
|
+
because the next fresh reviewer can find a different gap in the same text.
|
|
167
|
+
* **Cap**: 5 rounds.
|
|
168
|
+
* **Churn**: A new finding is at the scope of an applied fix, and reverting
|
|
169
|
+
that fix would resolve it.
|
|
170
|
+
|
|
171
|
+
On converged, go to Step 3. On cap or churn, write a short list of the open
|
|
172
|
+
findings by severity, then ask the user one question: accept and proceed,
|
|
173
|
+
continue past the cap, or return the document to drafting.
|
|
174
|
+
|
|
175
|
+
**Crucial Turn-Taking Requirement**: After the resolution phase finishes for a
|
|
176
|
+
given round, the loop driver **MUST respect the turn-taking checkpoint in
|
|
177
|
+
`ael-spec-resolve`**. The driver must remain idle across human turns,
|
|
178
|
+
only looping back to Step 2.1 when the user explicitly confirms they wish to run
|
|
179
|
+
another round of review.
|
|
180
|
+
|
|
181
|
+
### Step 3: Output Boundary & Final Checkpoint
|
|
182
|
+
|
|
183
|
+
Upon completion (converged, cap or churn accepted by the user, or manual
|
|
184
|
+
halt):
|
|
185
|
+
|
|
186
|
+
* **Programmatic Callers**: If running as a subflow of `ael-spec-review`, exit
|
|
187
|
+
cleanly to hand execution back to the parent workflow.
|
|
188
|
+
* **Manual Invocations**: Output a summary of completion in chat: *"The review
|
|
189
|
+
loop has completed after [N] rounds ([converged | accepted at cap | halted]).
|
|
190
|
+
Open findings are in the report. Would you like to proceed to
|
|
191
|
+
the next stage, or do you have any final questions?"*
|
|
@@ -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
|
+
## Execution Instructions
|
|
4
|
+
|
|
5
|
+
* **Design-Only Scope**: You are strictly forbidden from
|
|
6
|
+
writing, modifying, or building any production implementation files (e.g.,
|
|
7
|
+
`.h`, `.cc`, `.py`, `.go`) in the source tree. You may only write code
|
|
8
|
+
inside a markdown draft block or in a temporary scratchpad file.
|
|
9
|
+
* **Scratchpad Location (CRITICAL)**: You MUST write any temporary
|
|
10
|
+
scratchpad code files ONLY outside the project source tree (e.g.,
|
|
11
|
+
under `/tmp/` or your conversation's active scratch directory). You
|
|
12
|
+
are STRICTLY FORBIDDEN from creating `.h`, `.cc`, `.py`, `.go`, or any
|
|
13
|
+
other code files anywhere inside the project source tree.
|
|
14
|
+
* **HOW TO RESPOND**: If the user asks for production implementation while
|
|
15
|
+
this design workflow is active, explain that it produces design documents
|
|
16
|
+
and illustrative code only. Label any markdown or scratchpad example
|
|
17
|
+
clearly. Do not imply that production files were changed. Ask whether to
|
|
18
|
+
continue the design or leave the workflow for implementation.
|
|
19
|
+
* **Explicit Consensus Gates**: You must confirm with the user and achieve
|
|
20
|
+
explicit agreement at each step transition. Do not save the document or move
|
|
21
|
+
to the next step without the user's explicit "go-ahead". Do not move on
|
|
22
|
+
easily. Challenge the user at every step.
|
|
23
|
+
* **ONE QUESTION AT A TIME (CRITICAL)**: You are strictly forbidden from
|
|
24
|
+
asking more than one question in a single response. You must present exactly
|
|
25
|
+
one question or request for clarification, wait for the user's response, and
|
|
26
|
+
only then proceed. Do not bundle questions or present a list of questions
|
|
27
|
+
for the user to answer at once.
|
|
28
|
+
* **NO SUMMARIES (CRITICAL)**: You MUST NOT include a "Summary of work",
|
|
29
|
+
"Status", "Adherence", or "Rule checklist" in your final response. Respond
|
|
30
|
+
only with the technical content and next steps.
|
|
31
|
+
* **Contradiction Auditing (MUST ENFORCE - CRITICAL)**: If you detect a
|
|
32
|
+
contradiction between the user's new requests and earlier
|
|
33
|
+
goals/architecture, **you MUST NOT modify any files**. You must only respond
|
|
34
|
+
to the user in plain text, point out the contradiction, and ask for
|
|
35
|
+
resolution. You are strictly forbidden from planning or executing any
|
|
36
|
+
file-writing/editing tool in the same turn as you discover a contradiction.
|
|
@@ -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).
|
|
@@ -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) {
|
|
@@ -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
|
|
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
|
|
@@ -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`.
|