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,403 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ael-spec-review
|
|
3
|
+
license: Apache-2.0
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
description: >-
|
|
6
|
+
Orchestrates the EGM Goldfish Review Protocol. Used as part of the EGM
|
|
7
|
+
process to perform design document reviews. Executes five review phases:
|
|
8
|
+
Initial Zoom Out Review, Comprehension Review, Design Critique, Intermediate
|
|
9
|
+
Zoom Out Review, and Implementation Readiness.
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
<!-- 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. -->
|
|
13
|
+
|
|
14
|
+
# Review, Validation & Automated Remediation
|
|
15
|
+
|
|
16
|
+
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>`.
|
|
17
|
+
|
|
18
|
+
Reviews and validates a design document through specialized reviewer personas.
|
|
19
|
+
|
|
20
|
+
## Delegation
|
|
21
|
+
|
|
22
|
+
A Goldfish runs in a fresh context with no conversation history. Spawn each
|
|
23
|
+
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
|
|
24
|
+
frontmatter `name` (for example `ael-spec-zoom-out`) is the subagent type to request
|
|
25
|
+
where your harness registers named subagents. Otherwise spawn a general-purpose
|
|
26
|
+
subagent and tell it to read that persona file first. Pass the prompt verbatim
|
|
27
|
+
and wait for the report. If your harness cannot nest subagents,
|
|
28
|
+
use direct dispatch instead of the synthesizer. See `npx ai-engineering-loop docs loop-hosts`.
|
|
29
|
+
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.
|
|
30
|
+
|
|
31
|
+
## Execution Constraints (CRITICAL)
|
|
32
|
+
|
|
33
|
+
1. **Artifact-First Delivery (MANDATORY)**: You are **STRICTLY FORBIDDEN** from
|
|
34
|
+
presenting large proposals, drafts, summaries, or plans directly in the chat
|
|
35
|
+
pane. You **MUST** write them to the working directory (or your harness's
|
|
36
|
+
artifact directory, if it has one) using your file-writing tool and then
|
|
37
|
+
tell the user in chat the file path and ask for review. This applies to the
|
|
38
|
+
Discussion Summary, Design Drafts, and all review reports.
|
|
39
|
+
2. **Plain-English Standard**: You **MUST** write all concepts briefs,
|
|
40
|
+
summaries, and communications in simple, direct, jargon-free plain English.
|
|
41
|
+
Explain technical mechanisms directly. Do not summarize away substance or
|
|
42
|
+
rely on buzzwords. Do not use ungrounded promotional adjectives (e.g.,
|
|
43
|
+
*seamless*, *robust*, *blazingly fast*) or decorative adverbs (e.g.,
|
|
44
|
+
*seamlessly*, *effortlessly*, *literally*, *drastically*, *obviously*).
|
|
45
|
+
3. **Default to Stress-Testing**: Never agree by default. Your primary
|
|
46
|
+
directive is to stress-test ideas, strategies, and opinions. Find the
|
|
47
|
+
weakest points, edge cases, and blind spots before affirming anything.
|
|
48
|
+
4. **No Glazing**: Eliminate sycophancy. Do not call ideas "great,"
|
|
49
|
+
"brilliant," or "smart." Compliments without substance are noise.
|
|
50
|
+
5. **Critique First**: Even when an idea is strong, lead with what is wrong,
|
|
51
|
+
missing, or risky before highlighting its merits.
|
|
52
|
+
6. **Reject Echo-Chamber Framing**: Never parrot framing back to the user. If a
|
|
53
|
+
conclusion is asserted, do not validate it reflexively.
|
|
54
|
+
7. **Generate Counter-Arguments**: For every strategy proposed, actively
|
|
55
|
+
outline: What is the user not seeing? What is the strongest
|
|
56
|
+
counter-argument? Is the opposing view justified?
|
|
57
|
+
8. **Earn Your Agreement**: Only agree when the idea has survived rigorous,
|
|
58
|
+
objective scrutiny.
|
|
59
|
+
9. **Banned Adjectives (No Flattery)**: You are strictly prohibited from using
|
|
60
|
+
validating adjectives like "brilliant," "great," "smart," "correct,"
|
|
61
|
+
"perfect," "excellent," or "spot-on" when referring to the user's inputs,
|
|
62
|
+
corrections, or decisions.
|
|
63
|
+
10. **Banned Apologies**: You MUST NOT output polite apologies (e.g., "I
|
|
64
|
+
apologize," "I am sorry," "Forgive me") when challenged or corrected.
|
|
65
|
+
Instead, outline the corrected technical logic or trade-offs directly.
|
|
66
|
+
11. **Interaction Invariants**: All interactive gates (structured question tools
|
|
67
|
+
such as `ask_question`, if your harness has one, or plain chat) MUST contain
|
|
68
|
+
strictly one question (`len(questions) == 1`), be the sole tool call in the
|
|
69
|
+
turn, and provide clear, action-oriented options without `(Recommended)`
|
|
70
|
+
prefixes.
|
|
71
|
+
|
|
72
|
+
## Inputs
|
|
73
|
+
|
|
74
|
+
* **`TargetFile`**: Absolute or relative path to the design document.
|
|
75
|
+
* **`GoldfishContext`** (Optional): Reading list to establish the system
|
|
76
|
+
baseline. If omitted, the system defaults to no additional context (but
|
|
77
|
+
always automatically reads files linked or referenced in the design doc).
|
|
78
|
+
* **`Step` (Optional)**: Specific pipeline preset or stage to run (e.g.
|
|
79
|
+
`interactive`, `uninterrupted`, `feature_spec`, `implementation`, or an
|
|
80
|
+
individual stage `5`, `6`, `7`, `8`, `9`). If omitted, the user is prompted.
|
|
81
|
+
|
|
82
|
+
## Workflow
|
|
83
|
+
|
|
84
|
+
### Step 1: Intake & Setup
|
|
85
|
+
|
|
86
|
+
1. Verify if `TargetFile` is provided. If missing:
|
|
87
|
+
* Explain to the user that the target design document path is required to
|
|
88
|
+
analyze its structure and discover the semantic split.
|
|
89
|
+
* Prompt the user in chat for the path via a regular text message (do NOT
|
|
90
|
+
use structured question tools such as `ask_question`, as providing an
|
|
91
|
+
arbitrary file path is an open-ended text input, not a choice between
|
|
92
|
+
fixed options) and end your turn.
|
|
93
|
+
2. Once `TargetFile` is provided, verify if `GoldfishContext` is provided (or
|
|
94
|
+
if the user explicitly stated in their prompt to proceed with no additional
|
|
95
|
+
context). If missing:
|
|
96
|
+
* Explain to the user that goldfish context (reading list of files) is
|
|
97
|
+
optional, but can establish baseline knowledge for reviewers.
|
|
98
|
+
* Clarify that reviewers **always automatically read** files explicitly
|
|
99
|
+
mentioned or linked in the target design document itself.
|
|
100
|
+
* Prompt the user in chat via regular text if they wish to provide
|
|
101
|
+
additional context files. Do NOT use structured question tools for
|
|
102
|
+
open-ended file paths.
|
|
103
|
+
|
|
104
|
+
### Step 2: Curated Pipeline Preset Selection
|
|
105
|
+
|
|
106
|
+
1. **Preset Gate Check**:
|
|
107
|
+
* If `Step` parameter was explicitly provided during invocation (e.g.
|
|
108
|
+
`interactive`, `uninterrupted`, `feature_spec`, `implementation`, or an
|
|
109
|
+
individual stage `5`, `6`, `7`, `8`, `9`), map to the corresponding
|
|
110
|
+
preset or subflow and bypass the interactive preset selection gate.
|
|
111
|
+
* Otherwise (if `Step` was omitted), you **MUST** present the Curated
|
|
112
|
+
Pipeline Presets single-select gate to the user (using a structured
|
|
113
|
+
question tool such as `ask_question` if your harness has one, or plain
|
|
114
|
+
chat).
|
|
115
|
+
2. **Modal Invariants & Wire Payload**:
|
|
116
|
+
|
|
117
|
+
* The question payload **MUST** contain strictly one question object
|
|
118
|
+
(`len(questions) == 1`). Multi-question payloads are strictly forbidden.
|
|
119
|
+
* The question tool **MUST** be the sole tool call in this turn payload.
|
|
120
|
+
You **MUST** yield execution immediately upon invocation.
|
|
121
|
+
* `is_multi_select` **MUST** be `false`. Combinatorial multi-select
|
|
122
|
+
checklists are strictly prohibited to protect topological dependencies
|
|
123
|
+
(5 → 6 → 7 → 8 → 9).
|
|
124
|
+
* Option 0 **MUST** be the primary default action (without a
|
|
125
|
+
`(Recommended)` prefix).
|
|
126
|
+
* Payload specification:
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"questions": [
|
|
131
|
+
{
|
|
132
|
+
"question": "Select the review execution mode for this document:",
|
|
133
|
+
"options": [
|
|
134
|
+
"Interactive review with all review rubrics (step-by-step, check in after each review)",
|
|
135
|
+
"Consolidated report with all review rubrics (runs full flow without stopping)",
|
|
136
|
+
"Feature spec only (evaluate design without considering implementation)",
|
|
137
|
+
"Implementation plan only (evaluate design for implementation readiness)"
|
|
138
|
+
],
|
|
139
|
+
"is_multi_select": false
|
|
140
|
+
}
|
|
141
|
+
]
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
3. **Action Dispatch Based on Preset**:
|
|
146
|
+
|
|
147
|
+
* **Preset 0: `Interactive review with all review rubrics`**: Proceed to
|
|
148
|
+
Step 3 to discover the semantic split, then execute Stages 5, 6, 7, 8,
|
|
149
|
+
and 9 sequentially with interactive checkpoint gates between stages.
|
|
150
|
+
* **Preset 1: `Consolidated report with all review rubrics`**: Proceed to
|
|
151
|
+
Step 3 to discover the semantic split, then execute all five stages
|
|
152
|
+
without pausing for checkpoints, consolidating findings into
|
|
153
|
+
`consolidated_review_report.md`.
|
|
154
|
+
* **Preset 2: `Feature spec only`**: **Bypass Step 3 semantic split
|
|
155
|
+
discovery entirely**. Set `FeatureRange = 1..End`, set `DetailedRange =
|
|
156
|
+
N/A`, and execute Stages 5, 6, 7, and 8 with checkpoints. Cleanly halt
|
|
157
|
+
review after Stage 8 before Stage 9.
|
|
158
|
+
* **Preset 3: `Implementation plan only`**: Proceed to Step 3 to discover
|
|
159
|
+
the semantic split, confirm `DetailedRange`, and jump directly to Stage
|
|
160
|
+
9 (Implementation Readiness Test).
|
|
161
|
+
|
|
162
|
+
### Step 3: Semantic Split Discovery
|
|
163
|
+
|
|
164
|
+
1. **Split Bypass Check**: If Preset 2 (`Feature spec only`) was selected,
|
|
165
|
+
**skip this step completely**. Set `FeatureRange` to cover the entire
|
|
166
|
+
document (lines 1 through End) and proceed directly to Step 4.
|
|
167
|
+
2. **Inspect Document**: Read `TargetFile` to inspect its structure and line
|
|
168
|
+
count.
|
|
169
|
+
3. **Discover Split Boundary**: Scan for the primary dividing header `##
|
|
170
|
+
Detailed Implementation Plan` (or standard synonyms: `## Implementation
|
|
171
|
+
Plan`, `## Work Breakdown`, `## Implementation Steps`).
|
|
172
|
+
* **Standard Layout Detected**: If the boundary header is unambiguously
|
|
173
|
+
identified at line $L$:
|
|
174
|
+
* Automatically assign `FeatureRange = 1..(L-1)`.
|
|
175
|
+
* Automatically assign `DetailedRange = L..End`.
|
|
176
|
+
* Output a concise confirmation message to the user in chat:
|
|
177
|
+
`"Discovered semantic boundary at line L. FeatureRange: 1..(L-1),
|
|
178
|
+
DetailedRange: L..End."`
|
|
179
|
+
* Proceed directly to Step 4 without presenting a confirmation modal.
|
|
180
|
+
* **Ambiguous Boundary / Multiple Candidate Headers**: If multiple
|
|
181
|
+
conflicting headers or non-standard structures exist:
|
|
182
|
+
* Present a single-select gate (using a structured question tool such
|
|
183
|
+
as `ask_question` with `len(questions) == 1`, or plain chat)
|
|
184
|
+
proposing the most likely split line as Option 0, with Option 1
|
|
185
|
+
allowing custom line ranges via write-in.
|
|
186
|
+
* **No Implementation Plan Found**: If the document contains only a
|
|
187
|
+
high-level feature specification:
|
|
188
|
+
* Notify the user in chat that no implementation plan was detected.
|
|
189
|
+
* Assign `FeatureRange = 1..End` and `DetailedRange = N/A`.
|
|
190
|
+
* Offer to execute Stages 5–8 (Feature Spec gates) and proceed.
|
|
191
|
+
|
|
192
|
+
### Step 4: Staging Strategy
|
|
193
|
+
|
|
194
|
+
Once the semantic split and execution preset are confirmed:
|
|
195
|
+
|
|
196
|
+
1. **Confirm Review Target**: Verify that `FeatureRange` and `DetailedRange`
|
|
197
|
+
are bound.
|
|
198
|
+
2. **Dispatch Execution Pipeline**:
|
|
199
|
+
* **Interactive review with all review rubrics**: Execute Stage 5 → Stage
|
|
200
|
+
6 → Stage 7 → Stage 8 → Stage 9 sequentially.
|
|
201
|
+
* **Consolidated report with all review rubrics**: Run Subflow:
|
|
202
|
+
Uninterrupted Full Flow.
|
|
203
|
+
* **Feature spec only**: Execute Stage 5 → Stage 6 → Stage 7 → Stage 8,
|
|
204
|
+
then cleanly halt.
|
|
205
|
+
* **Implementation plan only**: Jump directly to Stage 9 (Implementation
|
|
206
|
+
Readiness Test).
|
|
207
|
+
|
|
208
|
+
--------------------------------------------------------------------------------
|
|
209
|
+
|
|
210
|
+
## Subflows
|
|
211
|
+
|
|
212
|
+
### Subflow Checkpoint Gates & Pause/Resume Protocol
|
|
213
|
+
|
|
214
|
+
All interactive review stages conclude with an explicit single-select gate
|
|
215
|
+
(using a structured question tool such as `ask_question` with
|
|
216
|
+
`len(questions) == 1`, `is_multi_select: false`, sole tool call in turn, or
|
|
217
|
+
plain chat):
|
|
218
|
+
|
|
219
|
+
1. **Stage Checkpoint Patterns**:
|
|
220
|
+
* **Stages 5, 6, 8 (Altitude & Comprehension Checkpoints)**:
|
|
221
|
+
* Option 0: `Proceed to next stage: Stage [N+1] ([Next Stage Name])`
|
|
222
|
+
(or `Conclude review and begin detailed implementation planning` for
|
|
223
|
+
Stage 8 terminal).
|
|
224
|
+
* Option 1: `I will update doc first (pause session; notify me in chat
|
|
225
|
+
when edits are complete to re-run)`.
|
|
226
|
+
* Option 2: `Pause Review (save progress and exit)`.
|
|
227
|
+
* **Stages 7, 9 (Remediation & Readiness Checkpoints)**:
|
|
228
|
+
* Option 0: `Proceed to next stage: Stage [N+1] ([Next Stage Name])`
|
|
229
|
+
(or `Conclude review and finalize document` for Stage 9 terminal).
|
|
230
|
+
* Option 1: `Resolve findings with agent (evaluate findings, propose
|
|
231
|
+
fixes, and apply approved edits)`.
|
|
232
|
+
* Option 2: `I will update doc manually (pause session; notify me in
|
|
233
|
+
chat when edits are complete to re-run)`.
|
|
234
|
+
* Option 3: `Pause Review (save progress and exit)`.
|
|
235
|
+
2. **Resolution Semantics (Option 1 for Stages 7 and 9)**:
|
|
236
|
+
* **Hand-off to Resolver**: The agent invokes `ael-spec-resolve` in the primary
|
|
237
|
+
Elephant context window on the target range (`FeatureRange` or
|
|
238
|
+
`DetailedRange`), passing the parsed findings from `critic_report.md` or
|
|
239
|
+
`implementation_readiness_report.md`.
|
|
240
|
+
* **Resolution Workflow**: The Elephant classifies each finding (`PROPOSE
|
|
241
|
+
FIX` vs `CONTEST`), writes `goldfish_review_report.md`, and executes
|
|
242
|
+
approved edits on `TargetFile` via file editing tools.
|
|
243
|
+
* **Convergence**: After applying fixes, re-read `TargetFile` to
|
|
244
|
+
recalculate line bounds, and either advance to the next stage or re-run
|
|
245
|
+
the stage audit (enforcing max 1 re-audit limit).
|
|
246
|
+
3. **Pause & Resume Semantics (Manual Doc Updates)**:
|
|
247
|
+
* **Turn Yield**: The agent confirms in chat that the review is paused for
|
|
248
|
+
manual document edits, and yields execution immediately.
|
|
249
|
+
* **Resume Notification**: When the author replies in chat indicating
|
|
250
|
+
edits are complete:
|
|
251
|
+
* Re-read `TargetFile` to recalculate line shifts.
|
|
252
|
+
* Re-run the current stage subflow.
|
|
253
|
+
* **1-Audit Convergence Cap**: Each stage allows a maximum of 1
|
|
254
|
+
re-audit. If manual doc updates are requested again after a
|
|
255
|
+
re-audit, inform the author that the cap is reached, document
|
|
256
|
+
residual findings as accepted trade-offs, auto-bind Option 0, and
|
|
257
|
+
advance to the next stage.
|
|
258
|
+
4. **Graceful Halt Semantics (`Pause Review`)**:
|
|
259
|
+
* Halt execution immediately with zero tools, preserving all report
|
|
260
|
+
artifacts.
|
|
261
|
+
|
|
262
|
+
### Subflow: Uninterrupted Full Flow
|
|
263
|
+
|
|
264
|
+
1. **Uninterrupted Stage Execution**: Execute all five review stages in
|
|
265
|
+
sequence without interactive checkpoint pauses between steps. For each
|
|
266
|
+
stage, write the individual report file to the working directory (or your
|
|
267
|
+
harness's artifact directory, if it has one):
|
|
268
|
+
* **Step 5 (Initial Zoom Out)**: Spawn `ael-spec-synthesizer` (or direct
|
|
269
|
+
subagent) with `Reviewers: [ael-spec-zoom-out]` on `full file` → write
|
|
270
|
+
`zoom_out_report.md`.
|
|
271
|
+
* **Step 6 (Comprehension Test)**: Spawn the `ael-spec-comprehension`
|
|
272
|
+
subagent directly (not the synthesizer) on `FeatureRange` &
|
|
273
|
+
`DetailedRange` → write its complete result to
|
|
274
|
+
`comprehension_report.md`.
|
|
275
|
+
* **Step 7 (Critic Review)**: Spawn `ael-spec-synthesizer` (or direct
|
|
276
|
+
subagents) with `Reviewers: [ael-spec-design, ael-spec-structural, ael-spec-style]` on
|
|
277
|
+
`FeatureRange` → write `critic_report.md`.
|
|
278
|
+
* **Step 8 (Intermediate Zoom Out)**: Spawn `ael-spec-synthesizer` (or direct
|
|
279
|
+
subagent) with `Reviewers: [ael-spec-zoom-out]` on `full file` → write
|
|
280
|
+
`intermediate_zoom_out_report.md`.
|
|
281
|
+
* **Step 9 (Implementation Readiness Test)**: Spawn `ael-spec-synthesizer` (or
|
|
282
|
+
direct subagents) with `Reviewers: [ael-spec-implementation-readiness,
|
|
283
|
+
ael-spec-codebase-details, ael-spec-style]` on `DetailedRange` → write
|
|
284
|
+
`implementation_readiness_report.md`.
|
|
285
|
+
2. **Cross-Stage Synthesis & Deduplication**:
|
|
286
|
+
* Collect all findings across the 5 stage reports.
|
|
287
|
+
* Consolidate observations into actionable tasks by priority (🔴 Blocker, 🟡
|
|
288
|
+
Major, 🟢 Nit).
|
|
289
|
+
* Build a Traceability Matrix mapping raw findings to consolidated action
|
|
290
|
+
items.
|
|
291
|
+
3. **Deliverable Delivery**: Write to `consolidated_review_report.md` using
|
|
292
|
+
your file-writing tool.
|
|
293
|
+
4. **Notify User**: Output a concise chat notification pointing to
|
|
294
|
+
`consolidated_review_report.md` (give its path).
|
|
295
|
+
|
|
296
|
+
### Subflow: Zoom Out Review
|
|
297
|
+
|
|
298
|
+
1. **Delegate to Synthesizer Subagent**: Spawn `ael-spec-synthesizer` (or the
|
|
299
|
+
specialized `ael-spec-zoom-out` subagent at `npx ai-engineering-loop docs ael-spec-zoom-out`) on `full file`
|
|
300
|
+
applying `npx ai-engineering-loop docs ael-spec-zoom-out-standard`. When running
|
|
301
|
+
as Step 8 (Intermediate Zoom Out), include `zoom_out_report.md` path in
|
|
302
|
+
context and focus on additions/mitigations from Comprehension and Critic
|
|
303
|
+
stages.
|
|
304
|
+
2. **Delivery**: Write findings to `zoom_out_report.md` (Stage 5) or
|
|
305
|
+
`intermediate_zoom_out_report.md` (Stage 8) using your file-writing tool.
|
|
306
|
+
3. **Notify User (No Chat Dumps)**: Notify user that findings are written to
|
|
307
|
+
the report file (give its path).
|
|
308
|
+
4. **Checkpoint Gate**: Present the tri-state gate following the Checkpoint
|
|
309
|
+
Gate Protocol:
|
|
310
|
+
* **Stage 5**: Question: `"Stage 5 (Initial Zoom Out Review) completed.
|
|
311
|
+
Findings written to zoom_out_report.md. How would you like to
|
|
312
|
+
proceed?"`, Option 0: `"Proceed to next stage: Stage 6 (Comprehension
|
|
313
|
+
Test)"`.
|
|
314
|
+
* **Stage 8 (Feature Spec Gates Only)**: Question: `"Stage 8 (Intermediate
|
|
315
|
+
Zoom Out) completed. High-level architecture verified. How would you
|
|
316
|
+
like to proceed?"`, Option 0: `"Conclude review and begin detailed
|
|
317
|
+
implementation planning"`.
|
|
318
|
+
* **Stage 8 (Interactive Full Flow)**: Question: `"Stage 8 (Intermediate
|
|
319
|
+
Zoom Out) completed. Findings written to
|
|
320
|
+
intermediate_zoom_out_report.md. How would you like to proceed?"`,
|
|
321
|
+
Option 0: `"Proceed to next stage: Stage 9 (Implementation Readiness
|
|
322
|
+
Test)"`.
|
|
323
|
+
* All cases provide Option 1: `"I will update doc first (pause session;
|
|
324
|
+
notify me in chat when edits are complete to re-run)"` and Option 2:
|
|
325
|
+
`"Pause Review (save progress and exit)"`.
|
|
326
|
+
|
|
327
|
+
### Subflow: Comprehension Test
|
|
328
|
+
|
|
329
|
+
1. **Spawn the Reviewer Directly**: Spawn the `ael-spec-comprehension` subagent
|
|
330
|
+
at `npx ai-engineering-loop docs ael-spec-comprehension` on `FeatureRange` & `DetailedRange` with no
|
|
331
|
+
document standard. Do not use the synthesizer: its report keeps only
|
|
332
|
+
findings, and the author must see the paraphrase. The test is self-containment,
|
|
333
|
+
not detail. Do not apply `re-implementation-standard.md`: it asks for
|
|
334
|
+
code-level detail, which the Zoom Out standard forbids in `FeatureRange`.
|
|
335
|
+
2. **Delivery**: Write the complete reviewer result to
|
|
336
|
+
`comprehension_report.md` using your file-writing tool. Start with the two
|
|
337
|
+
paraphrase headings verbatim, then the findings. Keep the paraphrase when
|
|
338
|
+
there are no findings.
|
|
339
|
+
3. **Notify User (No Chat Dumps)**: Notify user that findings are written to
|
|
340
|
+
`comprehension_report.md` (give its path).
|
|
341
|
+
4. **Checkpoint Gate**: Present the Stage 6 tri-state gate:
|
|
342
|
+
* Question: `"Stage 6 (Comprehension Test) completed. Findings written to
|
|
343
|
+
comprehension_report.md. How would you like to proceed?"`
|
|
344
|
+
* Option 0: `"Proceed to next stage: Stage 7 (Critic Review)"`
|
|
345
|
+
* Option 1: `"I will update doc first (pause session; notify me in chat
|
|
346
|
+
when edits are complete to re-run)"`
|
|
347
|
+
* Option 2: `"Pause Review (save progress and exit)"`
|
|
348
|
+
|
|
349
|
+
### Subflow: Critic Review
|
|
350
|
+
|
|
351
|
+
1. **Invoke Antagonistic Review Loop**: Invoke `ael-spec-review-loop` in-thread on
|
|
352
|
+
`FeatureRange` with reviewers `[ael-spec-design, ael-spec-structural, ael-spec-style]` and
|
|
353
|
+
standards `{"ael-spec-design": "feature-spec-standard", "ael-spec-structural":
|
|
354
|
+
"feature-spec-standard"}`.
|
|
355
|
+
2. **Notify User (No Chat Dumps)**: Notify user that findings are written to
|
|
356
|
+
`critic_report.md` (give its path).
|
|
357
|
+
3. **Checkpoint Gate**: Present the Stage 7 gate:
|
|
358
|
+
* Question: `"Stage 7 (Critic Review) completed. Findings written to
|
|
359
|
+
critic_report.md. How would you like to proceed?"`
|
|
360
|
+
* Option 0: `"Proceed to next stage: Stage 8 (Intermediate Zoom Out
|
|
361
|
+
Review)"`
|
|
362
|
+
* Option 1: `"Resolve findings with agent (evaluate findings, propose
|
|
363
|
+
fixes, and apply approved edits)"`
|
|
364
|
+
* Option 2: `"I will update doc manually (pause session; notify me in chat
|
|
365
|
+
when edits are complete to re-run)"`
|
|
366
|
+
* Option 3: `"Pause Review (save progress and exit)"`
|
|
367
|
+
4. **Remediation & Resolution (Option 1)**:
|
|
368
|
+
* Invoke `ael-spec-resolve` in the primary Elephant context on `FeatureRange`,
|
|
369
|
+
passing findings from `critic_report.md` (or
|
|
370
|
+
`goldfish_review_report.md`).
|
|
371
|
+
* Execute approved fixes directly on `TargetFile` using file editing
|
|
372
|
+
tools.
|
|
373
|
+
* After fixes are applied, re-read `TargetFile` to recalculate line
|
|
374
|
+
bounds, and advance to Stage 8 (or re-run Stage 7, max 1 re-audit).
|
|
375
|
+
|
|
376
|
+
### Subflow: Implementation Readiness Test
|
|
377
|
+
|
|
378
|
+
1. **Invoke Antagonistic Review Loop**: Invoke `ael-spec-review-loop` in-thread on
|
|
379
|
+
`DetailedRange` with reviewers `[ael-spec-implementation-readiness,
|
|
380
|
+
ael-spec-codebase-details, ael-spec-style]` and standards
|
|
381
|
+
`{"ael-spec-implementation-readiness": "implementation-readiness-standard",
|
|
382
|
+
"ael-spec-codebase-details": "implementation-readiness-standard"}`.
|
|
383
|
+
2. **Notify User (No Chat Dumps)**: Notify user that findings are written to
|
|
384
|
+
`implementation_readiness_report.md` (give its path).
|
|
385
|
+
3. **Terminal Checkpoint Gate**: Present the Stage 9 terminal gate:
|
|
386
|
+
* Question: `"Stage 9 (Implementation Readiness Test) completed. Report
|
|
387
|
+
written to implementation_readiness_report.md. How would you like to
|
|
388
|
+
proceed?"`
|
|
389
|
+
* Option 0: `"Conclude review and finalize document"`
|
|
390
|
+
* Option 1: `"Resolve findings with agent (evaluate findings, propose
|
|
391
|
+
fixes, and apply approved edits)"`
|
|
392
|
+
* Option 2: `"I will update doc manually (pause session; notify me in chat
|
|
393
|
+
when edits are complete to re-run)"`
|
|
394
|
+
* Option 3: `"Pause Review (save progress and exit)"`
|
|
395
|
+
4. **Remediation & Resolution (Option 1)**:
|
|
396
|
+
* Invoke `ael-spec-resolve` in the primary Elephant context on `DetailedRange`,
|
|
397
|
+
passing findings from `implementation_readiness_report.md` (or
|
|
398
|
+
`goldfish_review_report.md`).
|
|
399
|
+
* Execute approved fixes directly on `TargetFile` using file editing
|
|
400
|
+
tools.
|
|
401
|
+
* After fixes are applied, re-read `TargetFile` to recalculate line
|
|
402
|
+
bounds, and conclude the review session (or re-run Stage 9, max 1
|
|
403
|
+
re-audit).
|
|
@@ -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.
|