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.
Files changed (39) hide show
  1. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +1 -0
  2. package/CHANGELOG.md +25 -0
  3. package/README.md +1 -0
  4. package/THIRD_PARTY_NOTICES.md +11 -0
  5. package/adapters/spec/LICENSE +202 -0
  6. package/adapters/spec/NOTICE-AEL.md +26 -0
  7. package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
  8. package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
  9. package/adapters/spec/agents/ael-spec-design.md +65 -0
  10. package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
  11. package/adapters/spec/agents/ael-spec-structural.md +67 -0
  12. package/adapters/spec/agents/ael-spec-style.md +68 -0
  13. package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
  14. package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
  15. package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
  16. package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
  17. package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
  18. package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
  19. package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
  20. package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
  21. package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
  22. package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
  23. package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
  24. package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
  25. package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
  26. package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
  27. package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
  28. package/bin/ai-engineering-loop.js +42 -2
  29. package/core/spec-pack.md +47 -0
  30. package/lib/design-ref.js +178 -0
  31. package/lib/gates.js +1 -0
  32. package/lib/goal-runtime.js +5 -0
  33. package/lib/hosts/doctor.js +16 -2
  34. package/lib/impact-map.js +29 -1
  35. package/lib/receipt.js +12 -1
  36. package/lib/smart-context.js +10 -1
  37. package/lib/sync-hosts.js +25 -2
  38. package/package.json +1 -1
  39. package/schemas/goal-contract.schema.json +87 -11
@@ -0,0 +1,188 @@
1
+ ---
2
+ name: ael-spec-resolve
3
+ license: Apache-2.0
4
+ disable-model-invocation: true
5
+ description: >-
6
+ The Elephant resolution skill. Ingests flat deficiency reports from
7
+ concurrent Goldfish reviewers, applies automated fixes for PROPOSE FIX
8
+ items via UI multiple-choice gates, and presents interactive
9
+ negotiation/re-sync checkpoints.
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
+ # Goldfish Review: Resolve
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
+ ## Overview
19
+
20
+ This skill instructs the agent on how to operate within the primary Elephant
21
+ context window to parse flat deficiency reports from concurrent Goldfish
22
+ reviewers. It defends accurate design choices, applies automated textual
23
+ repairs, and manages interactive negotiation checkpoints.
24
+
25
+ ## Prerequisites & Context Strategy
26
+
27
+ * **Context Recommendation (Elephant Memory)**: This skill should be run in
28
+ the persistent conversation session that generated the target document (the
29
+ Elephant) to recall earlier reasoning and craft higher-quality fixes.
30
+
31
+ ## Inputs
32
+
33
+ The caller or orchestration driver provides exactly these parameters:
34
+
35
+ * **`TargetFile`**: Absolute or relative path to target document.
36
+ * **`LineRange`**: Exact line numbers (or `full file`).
37
+ * **`FindingsList`**: Aggregated flat list of findings from Goldfish
38
+ reviewers.
39
+
40
+ ## Execution Workflow
41
+
42
+ ### Step 1: Intake Validation & Gather Context
43
+
44
+ 1. **Hybrid Execution UX**: Detect if execution arguments are present:
45
+
46
+ * *Automated Mode*: If all parameters are provided, execute silently as a
47
+ subprocess.
48
+ * *Standalone Human Mode*: If parameters are omitted, trigger a friendly
49
+ onboarding flow. Prompt for one piece of input at a time, waiting for
50
+ the user's response after each turn. Once all inputs are specified,
51
+ display the final setup and verify the user is ready to continue.
52
+
53
+ 2. Read `TargetFile` at `LineRange` by reading it and parse the `FindingsList`.
54
+
55
+ ### Step 2: Evaluate & Categorize
56
+
57
+ Give each finding exactly one category:
58
+
59
+ * **CONTEST**: The critique is inaccurate or relies on a misunderstanding of
60
+ the codebase. Cite evidence that the reviewer could read: a file and
61
+ symbol, or a decision recorded in the document.
62
+ * **ESCALATE**: The critique is inaccurate, but the evidence is outside every
63
+ file the reviewer could read (for example, a team convention or a verbal
64
+ decision). State that fact. Do not fix the finding. Give it to the user.
65
+ * **PROPOSE FIX**: The critique is valid. Define precise textual replacements
66
+ or structural formatting adjustments to resolve the gap.
67
+ * **DECLINE**: The finding is a Nit. Record it. Do not fix it. You can use
68
+ PROPOSE FIX for a Nit if the fix is worth it.
69
+
70
+ Apply these rules:
71
+
72
+ * **A contest must be checkable.** "This was intentional" is not evidence.
73
+ If you cannot cite evidence the reviewer could read, use ESCALATE or
74
+ PROPOSE FIX.
75
+ * **Do not add context only to satisfy a reviewer.** Add context when a human
76
+ reader of the document needs it. If only a zero-context subagent needs it,
77
+ use ESCALATE.
78
+ * **Do not contest a comprehension gap.** If a fresh reader could not follow
79
+ the document, the document is missing context.
80
+ * **Do not change a severity.** If you think a Blocker is a Nit, CONTEST it
81
+ and state the reason.
82
+ * You wrote the document under review. A wish to contest is not evidence
83
+ that the reviewer is wrong.
84
+
85
+ ### Step 3: Report Fixes
86
+
87
+ Construct the final report and save it named
88
+ `goldfish_review_report.md` in the working directory (or your harness's artifact directory, if it has one)
89
+ using your file-writing tool. Use this layout:
90
+
91
+ ```markdown
92
+ # Goldfish Annotated Review Report
93
+
94
+ **Target:** `[TargetFile]` (`[LineRange]`)
95
+
96
+ ## Prioritized Findings & AI Suggestions
97
+
98
+ {{range findings, ordered by Severity}}
99
+ ### [Issue 1] [`[ReviewerPersona]`] - Severity: [High | Medium | Low]
100
+ * **Affected Scope:** [Lines Start-End]([RelativePath]#L[Start]-L[End]) ([Sub-header])
101
+ * **Discrepancy Description:** [copied from FindingsList]
102
+ * **Rationale:** [copied from FindingsList]
103
+ * ***AI Suggestion:*** [CONTEST | ESCALATE | PROPOSE FIX | DECLINE]
104
+ * ***Justification:*** [Detailed reason]
105
+ * ***Proposed Edit:***
106
+ * Location: [Line/Header]
107
+ * Change: [Precise replacement string or deletion note]
108
+ {{end}}
109
+ ```
110
+
111
+ ### Step 4: Interactive Resolution Gate
112
+
113
+ If any finding is `ESCALATE`, list those findings first in the chat message.
114
+ They need the user's knowledge, not only approval.
115
+
116
+ Before proceeding, output a visible chat message to the user: *"I have compiled
117
+ the audit findings into `goldfish_review_report.md`. Please review the findings there and choose how you would like to
118
+ proceed:
119
+
120
+ - **Comment directly on the file**: Review `goldfish_review_report.md` in
121
+ chat or the file and leave comments/edits to approve, reject, or contest
122
+ specific items.
123
+ - **Auto accept**: Reply "auto accept" to batch-apply all proposed fixes
124
+ (skipping contested items).
125
+ - **Continue to next phase**: Reply "continue" or "no changes" to proceed
126
+ without applying fixes.
127
+ - **Interactive breakdown**: Reply "interactive breakdown" for a guided,
128
+ item-by-item walkthrough in chat with detailed explanations for each
129
+ proposed edit or contested finding before making decisions.
130
+ - **Custom instruction / Wildcard request**: Reply with any custom
131
+ instruction, question, or out-of-band request."*
132
+
133
+ You **MUST** immediately yield active execution by calling **zero tools** in
134
+ this turn payload. You must stop execution and go idle, waiting for the human
135
+ developer to comment on/edit the artifact or reply in the chat.
136
+
137
+ Interpret the user's action/response as follows:
138
+
139
+ - **"Auto accept" / "Accept all suggestions" / User clicks "Proceed" without
140
+ contesting**: Apply all fixes where the AI suggestion was `PROPOSE FIX`
141
+ directly to `TargetFile` at `LineRange` in a single batch using
142
+ your file-editing tool. Any items categorized as `CONTEST`, `ESCALATE`, or
143
+ `DECLINE` are explicitly bypassed. Then proceed to Step 5.
144
+ - **"Continue to next phase" / "No changes"**: Do not apply any automated
145
+ fixes. Then proceed to Step 5.
146
+ - **"Interactive breakdown"**: Enter a sequential breakdown loop over ALL
147
+ finding items (all categories except `DECLINE`):
148
+
149
+ 1. For each item `i`, output a visible chat message formatting the full
150
+ finding details and explanation in rich markdown:
151
+
152
+ ```markdown
153
+ ### Breakdown Item [i]: [Issue Title] [`[ReviewerPersona]`]
154
+ * **Scope:** [Lines Start-End]([RelativePath]#L[Start]-L[End]) ([Sub-header])
155
+ * **Description:** [Description]
156
+ * **AI Suggestion:** [CONTEST | ESCALATE | PROPOSE FIX]
157
+ * **Explanation & Justification:** [Detailed reason and background explaining why the fix is proposed or why the finding is contested]
158
+ * **Proposed Edit:** [Precise replacement text or deletion note]
159
+ ```
160
+
161
+ Then prompt the user in chat for their decision on this item (calling
162
+ **zero tools** and going idle):
163
+
164
+ * If `PROPOSE FIX`: Ask the user to reply with **Accept proposed
165
+ fix**, **Skip / ignore**, or **Discuss**.
166
+ * If `CONTEST`: Ask the user to reply with **Skip / agree with
167
+ contest**, **Overrule contest (propose fix)**, or **Discuss**.
168
+ * If `ESCALATE`: Ask the user to reply with **Confirm (no change)**,
169
+ **Add the fact to the document**, or **Discuss**.
170
+
171
+ 2. Record the user's decisions in an internal memory checklist (e.g., *Item
172
+ 1: Accepted*, *Item 2: Ignored*, *Item 3: Overruled*). **Do NOT call any
173
+ file editing tools during this sequential loop.**
174
+
175
+ 3. Once all items have been decided, summarize the accepted edits, execute
176
+ them using your file-editing tool, and proceed to Step 5.
177
+
178
+ - **Custom instruction / Out-of-band edit**: If the user provides targeted
179
+ instructions, apply them and proceed.
180
+
181
+ ### Step 5: Post-Resolution Synchronization & Exit
182
+
183
+ 1. **Re-verify Lines**: If changes were made to `TargetFile`, verify that the
184
+ file remains structurally coherent and valid markdown.
185
+ 2. Mark the report as resolved (add a `Status: resolved` line at the top).
186
+ 3. **Handoff**: Exit cleanly back to the caller (such as `ael-spec-review-loop`)
187
+ with the count of accepted fixes, contested items, escalated items,
188
+ declined items, and remaining unaddressed issues.
@@ -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).