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,315 @@
1
+ ---
2
+ name: ael-spec-draft
3
+ license: Apache-2.0
4
+ disable-model-invocation: true
5
+ description: >-
6
+ Drafts a design document section-by-section using the concepts brief from
7
+ ael-spec-brainstorm (or user notes). This is the second step in the Elephant-Goldfish (EGM)
8
+ feature flow. Use when you are ready to write a design doc after aligning on
9
+ requirements + solution.
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
+ # Design Drafting (Document Construction)
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
+ This skill guides the user through drafting a technical design document based on
19
+ the aligned problem and requirements from the brainstorm phase.
20
+
21
+ ## Execution Constraints (CRITICAL)
22
+
23
+ 1. You **MUST** read and apply the
24
+ execution instructions in `npx ai-engineering-loop docs ael-spec-execution-instructions`.
25
+ 2. **Artifact-First Delivery (MANDATORY)**: You are **STRICTLY FORBIDDEN** from
26
+ presenting large proposals, drafts, summaries, or plans directly in the chat
27
+ pane. You **MUST** write them directly to the working directory (or your
28
+ harness's artifact directory, if it has one) (`design_draft.md` or
29
+ `./design_draft.md`) using your file-writing tool and tell the user in chat
30
+ the file path and ask for review. This applies to the Discussion Summary,
31
+ Design Drafts, and all review reports.
32
+ 3. **Plain-English Standard**: You **MUST** write all concepts briefs,
33
+ summaries, and communications in simple, direct, jargon-free plain English.
34
+ Explain technical mechanisms directly. Do not summarize away substance or
35
+ rely on buzzwords. Do not use ungrounded promotional adjectives (e.g.,
36
+ *seamless*, *robust*, *blazingly fast*) or decorative adverbs (e.g.,
37
+ *seamlessly*, *effortlessly*, *literally*, *drastically*, *obviously*).
38
+ 4. **Default to Stress-Testing**: Never agree by default. Your primary
39
+ directive is to stress-test ideas, strategies, and opinions. Find the
40
+ weakest points, edge cases, and blind spots before affirming anything.
41
+ 5. **No Glazing**: Eliminate sycophancy. Do not call ideas "great,"
42
+ "brilliant," or "smart." Compliments without substance are noise.
43
+ 6. **Critique First**: Even when an idea is strong, lead with what is wrong,
44
+ missing, or risky before highlighting its merits.
45
+ 7. **Reject Echo-Chamber Framing**: Never parrot framing back to the user. If a
46
+ conclusion is asserted, do not validate it reflexively.
47
+ 8. **Generate Counter-Arguments**: For every strategy proposed, actively
48
+ outline: What is the user not seeing? What is the strongest
49
+ counter-argument? Is the opposing view justified?
50
+ 9. **Earn Your Agreement**: Only agree when the idea has survived rigorous,
51
+ objective scrutiny.
52
+ 10. **Banned Adjectives (No Flattery)**: You are strictly prohibited from using
53
+ validating adjectives like "brilliant," "great," "smart," "correct,"
54
+ "perfect," "excellent," or "spot-on" when referring to the user's inputs,
55
+ corrections, or decisions.
56
+ 11. **Banned Apologies**: You MUST NOT output polite apologies (e.g., "I
57
+ apologize," "I am sorry," "Forgive me") when challenged or corrected.
58
+ Instead, outline the corrected technical logic or trade-offs directly.
59
+ 12. **Interaction Invariants**: All interactive gates (structured question tools
60
+ such as `ask_question`, if your harness has one, or plain chat) MUST contain
61
+ strictly one question (`len(questions) == 1`), be the sole tool call in the
62
+ turn, and provide clear, action-oriented options without `(Recommended)`
63
+ prefixes.
64
+ 13. **Owner Decides Architecture**: When a design decision has more than one
65
+ defensible answer (e.g., data model, component boundaries, storage,
66
+ protocols), present up to three options, each with its mechanism,
67
+ trade-offs, and the conditions under which it fails, and ask the owner to
68
+ choose through a single-select gate. Do not rank the options, mark a
69
+ default, or pick one. If the owner asks you to choose ("just pick one"),
70
+ restate the trade-offs and present the same gate again. Decide mechanical
71
+ choices with one defensible answer (e.g., file naming, formatting)
72
+ yourself.
73
+
74
+ ## Inputs
75
+
76
+ * **`Context File`** (Optional): File path to a predecessor document (e.g.,
77
+ `docs/designs/<feature_name>.md`, `concepts_brief.md`, or
78
+ `discussion_summary.md`). If omitted, the skill defaults to consuming
79
+ predecessor context (e.g., `concepts_brief.md` or `discussion_summary.md`).
80
+
81
+ ## Execution Workflow
82
+
83
+ Follow these steps sequentially. Execute steps in order but allow the user to
84
+ revisit old phases in case they forgot something. Do not skip ahead without
85
+ explicit consensus from the user to confirm we can proceed between steps. Write
86
+ the document iteratively as the conversation progresses between sections.
87
+
88
+ ### Section Approval Gate (Steps 2–5)
89
+
90
+ After writing or updating each section in `design_draft.md` using your
91
+ file-writing tool, you must present the approval gate in the same turn following
92
+ this strict generation order:
93
+
94
+ 1. **Visible Chat Summary & Link (FIRST)**: You **MUST** output conversational
95
+ markdown text before the question gate. State which section was drafted or
96
+ updated, highlight 2–3 key decisions or additions, and provide a link or
97
+ path to `design_draft.md` (e.g., `[design draft](/absolute/project/design_draft.md)` in Codex).
98
+ 2. **Approval Gate (SECOND)**: In the same turn, present the single-select
99
+ approval choice (using a structured question tool such as `ask_question`
100
+ with `len(questions) == 1` and `is_multi_select: false` if your harness has
101
+ one, or plain chat):
102
+
103
+ > [!CAUTION] **Negative Constraint (No Empty Chat Bubbles)**: NEVER emit a
104
+ > structured question tool call with empty response text. Always generate the
105
+ > visible chat explanation and file link before invoking the question gate.
106
+
107
+ ```json
108
+ {
109
+ "questions": [
110
+ {
111
+ "question": "Drafted [Section Name] in design_draft.md. Please review. How would you like to proceed?",
112
+ "options": [
113
+ "Approve [Section Name] and proceed to next section",
114
+ "Request revisions to [Section Name] (via inline comments or write-in)"
115
+ ],
116
+ "is_multi_select": false
117
+ }
118
+ ]
119
+ }
120
+ ```
121
+
122
+ * **Option 0 (`Approve [Section Name] and proceed to next section`)**:
123
+ * If inline comments on `design_draft.md` are also present in the turn
124
+ context, apply those inline updates to `design_draft.md` first before
125
+ advancing to the next section.
126
+ * Otherwise, advance immediately to drafting the next section.
127
+ * **Option 1 (`Request revisions to [Section Name] (via inline comments or
128
+ write-in)`) or Modal Skip with Inline Comments**:
129
+ * **With Inline Comments and/or Write-in Instructions**: Inspect both the
130
+ write-in response and any inline comments left on `design_draft.md`
131
+ (honoring positive callouts to retain highlighted sections and negative
132
+ callouts to revise or remove content). Apply all revisions to
133
+ `design_draft.md` using your file-writing tool, notify the user, and
134
+ re-present the approval gate.
135
+ * **Empty Write-in Guard (CRITICAL)**: If selected without write-in text
136
+ **and** without any inline comments in the turn context, **DO NOT** loop
137
+ or fail. Prompt in chat: `"Please specify the adjustments or additions
138
+ needed for [Section Name] (either via inline comments on design_draft.md
139
+ or here in chat) so I can revise the draft."` and yield active execution
140
+ to wait for user clarification in chat.
141
+
142
+ ### Step 1: Ingest Predecessor Context (Concepts Brief or Notes)
143
+
144
+ 1. **Context File**: If `Context File` is specified, read and parse it directly.
145
+ 2. **Polymorphic Intake**: If omitted, discover context by checking sources in
146
+ strict priority order:
147
+ * **Priority 1: Modern Ideation Brief (`concepts_brief.md`)**: Check for
148
+ `concepts_brief.md` in `./concepts_brief.md`, the conversation artifact
149
+ directory, or `scratch/concepts_brief.md`. If found, ingest and parse
150
+ the brief.
151
+ * **Priority 2: Discussion Summary (`discussion_summary.md`)**: If
152
+ `concepts_brief.md` is not found, check for `discussion_summary.md` in
153
+ `./discussion_summary.md`, the conversation artifact directory, or
154
+ `scratch/discussion_summary.md`. If found, ingest and parse the summary.
155
+ **Do NOT** prompt the user to start `/ael-spec-brainstorm` or warn of
156
+ deprecation.
157
+ * **Priority 3: Interactive Chat Prompt**: If neither file exists, prompt
158
+ the user in chat for the feature's problem statement, goals, and
159
+ technical context, or offer to launch `/ael-spec-brainstorm`.
160
+ 3. **Verify State**: Parse the document. Present a quick confirmation to the
161
+ user to ensure we are starting with the correct context.
162
+ 4. **Consensus**: Get explicit approval to start drafting the document.
163
+
164
+ ### Step 2: Draft Overview, Goals & Problem Statement
165
+
166
+ 1. **Review Context**: Use the ingested information to frame the business
167
+ problem and user pain points.
168
+ 2. **Draft Content**: Write "The Problem", "Overview", "Goals", and "Non-Goals"
169
+ in clear, plain English Markdown following the design document template
170
+ (`references/design_doc.md`).
171
+ 3. **Focus**: Emphasize the *why* (the user need and business value) rather
172
+ than the *how* (technical implementation).
173
+ 4. **Write Draft Artifact (MANDATORY)**: Save this initial draft to
174
+ `design_draft.md` in the working directory (or your harness's artifact
175
+ directory, if it has one) using your file-writing tool.
176
+ 5. **Notify & Verify (No Chat Dumps)**: You are **STRICTLY FORBIDDEN** from
177
+ printing the draft in the chat. Instead, notify the user in conversational
178
+ chat text that Overview & Problem Statement has been drafted, provide a
179
+ clickable link or path to `design_draft.md`, and present the Section
180
+ Approval Gate for `Overview & Goals`.
181
+
182
+ ### Step 3: Draft Technical Plan
183
+
184
+ 1. **Synthesize Architecture**: Review the proposed high-level architecture and
185
+ solution from the ingested context.
186
+ 2. **Draft Plan**: Describe the proposed changes in clear prose. Identify new
187
+ components, modified files, and API changes. Include text-based block
188
+ diagrams (e.g., ASCII or Mermaid) to illustrate data flow.
189
+ 3. **Update Draft Artifact (MANDATORY)**: Update `design_draft.md` to
190
+ append/insert the "Technical Plan" section using your file-writing tool.
191
+ 4. **Notify & Verify (No Chat Dumps)**: You are **STRICTLY FORBIDDEN** from
192
+ printing the technical plan in the chat. Notify the user in conversational
193
+ chat text that the Technical Plan has been added, provide a clickable link
194
+ or path to `design_draft.md`, and present the Section Approval Gate for
195
+ `Technical Plan`.
196
+
197
+ ### Step 4: Draft Alternatives
198
+
199
+ 1. **Review Alternatives**: Read the alternatives rejected during brainstorming
200
+ from the `Alternatives Weighed` section of the ingested context. Do not
201
+ rely on memory: drafting often runs in a new session. If the section is
202
+ absent, ask the user which alternatives were rejected and why.
203
+ 2. **Draft Content**: Write the "Alternatives Considered" section in plain
204
+ English in Markdown format.
205
+ 3. **Detail Reasons**: For each alternative, explicitly state *why* it was
206
+ rejected (e.g., higher latency, scaling limitations, team unfamiliarity).
207
+ 4. **Update Draft Artifact (MANDATORY)**: Update `design_draft.md` to
208
+ append/insert the "Alternatives Considered" section using your file-writing
209
+ tool.
210
+ 5. **Notify & Verify (No Chat Dumps)**: You are **STRICTLY FORBIDDEN** from
211
+ printing the alternatives in the chat. Notify the user in conversational
212
+ chat text that the Alternatives section has been added, provide a clickable
213
+ link or path to `design_draft.md`, and present the Section Approval Gate for
214
+ `Alternatives Considered`.
215
+
216
+ ### Step 5: Draft Implementation
217
+
218
+ Draft a detailed implementation plan that focuses on how to implement the
219
+ feature. This plan must be detailed. You should ask questions and add enough
220
+ detail so that with the plan alone you can implement it without having to make
221
+ any impactful decisions. Follow these guidelines:
222
+
223
+ 1. **Single Implementation List**: List everything that needs to happen in one
224
+ unified section.
225
+ 2. **Enumerate Files**: List EVERY file that will be changed, created, or
226
+ deleted. Include any documentation, schema, config, proto, or testing files
227
+ that should be updated. You MUST include a reference to every file touched
228
+ by the plan.
229
+ 3. **Rationale**: Every file must be accompanied with a rationale explaining
230
+ *what* will change and *why* the change is necessary.
231
+ 4. **Format Links**: Provide full paths to files if known, or clear basenames,
232
+ using relative paths (e.g., `./sub/README.md` or `../sibling/README.md`) for
233
+ intra-package and sibling documentation links.
234
+ 5. **NO CODE**: Do not generate actual implementation code in this design
235
+ draft. Pseudocode, APIs, or schemas are allowed.
236
+ 6. **Update Draft Artifact (MANDATORY)**: Update `design_draft.md` to
237
+ append/insert this "Detailed Implementation" section using your file-writing
238
+ tool.
239
+ 7. **Notify & Verify (No Chat Dumps)**: You are **STRICTLY FORBIDDEN** from
240
+ printing the implementation plan in the chat. Notify the user in
241
+ conversational chat text that the Detailed Implementation Plan has been
242
+ added, provide a clickable link or path to `design_draft.md`, and present
243
+ the Section Approval Gate for `Detailed Implementation`.
244
+
245
+ ### Step 6: Write Design Document Finalization
246
+
247
+ When you are asked to write or save the design document, follow these rules
248
+ strictly:
249
+
250
+ 1. **Reconcile against the Predecessor Context**: Do not grade the draft
251
+ against the Zoom Out standard here. The session that wrote the draft agrees
252
+ with it; `/ael-spec-review` Stage 5 runs that check from a fresh context.
253
+ Instead, re-read the context ingested at Step 1 and compare it with the
254
+ draft. No Goldfish can do this check, because no Goldfish reads the brief.
255
+ * **Contradiction**: the brief decided a question and the draft decides it
256
+ differently. Report every one.
257
+ * **Addition**: the draft decides a question the brief did not raise.
258
+ Report it only if it changes the architecture, an external interface, or
259
+ a dependency.
260
+
261
+ List contradictions first, one line each, quoting the brief and the draft.
262
+ Ask the user to decide each one. Do not change the draft to match the brief
263
+ on your own: the draft can be right, because drafting reads code that the
264
+ brainstorm did not. If nothing diverges, say so in one line. If Step 1
265
+ found no predecessor file, skip this step.
266
+
267
+ If a contradiction is open, stop and wait for the user. Apply each
268
+ decision to `design_draft.md` before Step 6.2.
269
+
270
+ 2. **Target Directory**: If the user specified a target directory or file, use
271
+ it. Otherwise, probe the workspace for existing design directories (from
272
+ `Context File` directory, `docs/designs/`, or `<project>/docs/designs/`),
273
+ bind `[DiscoveredPath]` (defaulting to `docs/designs/`), and present a
274
+ single-select gate (using a structured question tool such as `ask_question`
275
+ with `len(questions) == 1` and `is_multi_select: false` if your harness has
276
+ one, or plain chat):
277
+
278
+ ```json
279
+ {
280
+ "questions": [
281
+ {
282
+ "question": "Where should the design be saved?",
283
+ "options": [
284
+ "Save to detected directory: [DiscoveredPath]",
285
+ "Specify custom target directory"
286
+ ],
287
+ "is_multi_select": false
288
+ }
289
+ ]
290
+ }
291
+ ```
292
+
293
+ * **Option 0**: Set `<DESIGN_DIR>` to `[DiscoveredPath]`.
294
+ * **Option 1**: If custom path is provided in write-in text, set
295
+ `<DESIGN_DIR>` to supplied path. If empty write-in, prompt in chat:
296
+ `"Please specify the custom target directory path where you would like
297
+ to save the design document."` and yield active execution.
298
+
299
+ 3. **Update Sitemap**: If `<DESIGN_DIR>/SITEMAP.md` exists, register the new
300
+ design in it (Link, Date, Author, Components, Description).
301
+
302
+ 4. **Write doc**: Once finalized, write the contents of `design_draft.md` to
303
+ the designated destination file at `<DESIGN_DIR>/<FEATURE>.md` using your
304
+ file-writing tool. Follow the [template](references/design_doc.md) for final
305
+ structure if any adjustments are needed.
306
+
307
+ 5. **Clean Formatting**: Ensure clean standard Markdown formatting, valid table
308
+ syntax, and proper code block fences.
309
+
310
+ 6. **Handoff**: Provide a clickable link to the finalized design and recommend
311
+ that the user review the document with:
312
+
313
+ ```markdown
314
+ `ael-spec-review` <DESIGN_PATH>
315
+ ```
@@ -0,0 +1,179 @@
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/Project Name]
4
+
5
+ * **Author:** [Author Name or GitHub Handle]
6
+ * **Status:** [Draft | Proposed | In Review | Approved]
7
+ * **Date:** [YYYY-MM-DD]
8
+
9
+ --------------------------------------------------------------------------------
10
+
11
+ ## Overview
12
+
13
+ <!-- Provide a high-level summary of the feature, the business or technical
14
+ problem it solves, and its context within the system. Keep it concise so both
15
+ humans and agents can quickly parse the main objective.
16
+ -->
17
+
18
+ ## The Problem
19
+
20
+ [Summarize the problem and the proposed solution here.]
21
+
22
+ ## Goals
23
+
24
+ <!--
25
+ What will this feature achieve? Be specific, measurable, and clear.
26
+ These goals represent the absolute criteria for success.
27
+ -->
28
+
29
+ * Goal 1
30
+ * Goal 2
31
+
32
+ ## Non-Goals
33
+
34
+ <!--
35
+ Explicitly state what is out of scope. This is crucial to prevent feature creep
36
+ and to define strict boundaries for the implementation agent.
37
+ -->
38
+
39
+ * Non-Goal 1
40
+ * Non-Goal 2
41
+
42
+ ## Open Questions
43
+
44
+ <!--
45
+ List unresolved design questions, technical unknowns, or dependencies requiring
46
+ investigation. Unanswered questions are retained here across drafting sessions
47
+ to preserve conversational memory and prevent future sessions from re-asking
48
+ questions that were already discussed. Remove answered questions as they are
49
+ resolved.
50
+ -->
51
+
52
+ * **Question 1**: [Description of technical unknown or open question]
53
+ * **Question 2**: [Description of technical unknown or open question]
54
+
55
+ ## Critical User Journeys (CUJs)
56
+
57
+ <!--
58
+ Define the end-to-end user journeys this design enables. Each CUJ must contain:
59
+
60
+ 1. Given: Preconditions, starting state, and environment configurations.
61
+ 2. When: The trigger, user action, or system event.
62
+ 3. Then: The expected outcome, verification criteria, and postconditions.
63
+ -->
64
+
65
+ ### CUJ 1: [Journey Title]
66
+
67
+ * **Given**: [Preconditions]
68
+ * **When**: [Actions]
69
+ * **Then**: [Expected Outcomes]
70
+
71
+ ### CUJ 2: [Journey Title]
72
+
73
+ * **Given**: [Preconditions]
74
+ * **When**: [Actions]
75
+ * **Then**: [Expected Outcomes]
76
+
77
+ ## Technical Plan (Architecture)
78
+
79
+ <!-- Detail the high-level design, architectural choices, system data flows, and
80
+ component interactions. Include ASCII or Mermaid diagrams to clearly model the
81
+ relationships.
82
+ -->
83
+
84
+ [Explain your architectural choices, data structures, and system component
85
+ mapping here.]
86
+
87
+ ```text
88
+ [Optional ASCII Architecture Diagram]
89
+ ```
90
+
91
+ ## Alternatives Considered
92
+
93
+ <!-- Document other architectural approaches or designs that were evaluated and
94
+ rejected. Explain the pros, cons, and the technical reasoning for why the chosen
95
+ plan is superior.
96
+ -->
97
+
98
+ ### Alternative A: [Alternative Title]
99
+
100
+ * **Pros**: [List benefits]
101
+ * **Cons**: [List drawbacks]
102
+ * **Reason for Rejection**: [Why this option was not selected]
103
+
104
+ --------------------------------------------------------------------------------
105
+
106
+ ## Non-Functional Requirements
107
+
108
+ <!-- Analyze non-functional concerns only if they represent critical risks for
109
+ this design:
110
+
111
+ - Security & Privacy: (Data sensitivity, auth/auth, secrets management).
112
+ - Performance & Latency: (Execution runtime, storage footprint, LLM token
113
+ overhead).
114
+ - Rollout & Rollback: (Feature flags, backward compatibility, rollback
115
+ commands).
116
+ -->
117
+
118
+ [Detail any critical non-functional requirements here. If none are critical,
119
+ this section can be omitted or stated as "None".]
120
+
121
+ --------------------------------------------------------------------------------
122
+
123
+ ### Additional Resources
124
+
125
+ <!-- Specify the external resources and context that were used during the design
126
+ discussion. Optional. If none were provided omit this section.-->
127
+
128
+ * Important project docs referenced
129
+ * Important docs/ referenced
130
+ * Related work
131
+
132
+ ### Future Improvements
133
+
134
+ <!-- Specify areas that have room for future improvement here. If none were
135
+ provided omit this section.-->
136
+
137
+ * **The idea**: What could be improved?
138
+
139
+ --------------------------------------------------------------------------------
140
+
141
+ ## Detailed Implementation Plan
142
+
143
+ <!-- Specify exactly which files must be created or modified. Do not use vague
144
+ language or TBDs.
145
+ -->
146
+
147
+ ### Target Files to Create/Modify
148
+
149
+ #### 1. `[File Path 1]` ([Create | Modify])
150
+
151
+ * **Type / Scope**: [e.g., Python Service, C++ Library, TypeScript Module, Build
152
+ Configuration]
153
+ * **Proposed Changes**: [Describe the new APIs, class/function signatures, or
154
+ behavioral logic here. Focus on the minimal required details for
155
+ implementation.]
156
+
157
+ #### 2. `[File Path 2]` ([Create | Modify])
158
+
159
+ * **Type / Scope**: [e.g., Unit Test, E2E Test Driver]
160
+ * **Proposed Changes**: [Describe the test coverage, expected test cases, or
161
+ mock assertions.]
162
+
163
+ ### Verification Plan
164
+
165
+ <!-- Specify what unit, integration, or manual tests must pass to validate the
166
+ implementation. What metrics should be measured to verify success?
167
+ -->
168
+
169
+ * **Compilation/Build**: [e.g., `npm run build`, `cargo build`, `make`]
170
+ * **Unit Tests**: [e.g., `pytest`, `npm test`, `cargo test`]
171
+ * **Static Analysis & Linting**: [e.g., `eslint`, `ruff check`, `golangci-lint`]
172
+ * **Test Coverage Requirement**: [e.g., 85%+ branch coverage]
173
+ * **E2E/Integration**: [e.g., Integration test command or automated eval runner]
174
+
175
+ --------------------------------------------------------------------------------
176
+
177
+ <!-- Provenance: Indicates initial structural drafting via EGM. -->
178
+
179
+ *Drafted with EGM*
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: ael-spec-drift
3
+ license: Apache-2.0
4
+ disable-model-invocation: true
5
+ description: >-
6
+ Runs drift detection on all design documents to check for document and
7
+ code consistency. Produces an actionable report with differences. Use when the
8
+ user asks to detect drift or check for consistency across all design documents
9
+ or READMEs in a directory.
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
+ # Detect Drift In Designs and Code
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
+ When the user asks to detect drift across all designs or a set of READMEs, the
19
+ goal is to identify all instances where the codebase has diverged or failed to
20
+ implement the specifications described by those designs or READMEs.
21
+
22
+ 1. **Check Input**: Verify a directory containing design documents or READMEs
23
+ is provided. If not provided, ask the user to specify the target directory.
24
+ 2. **List Documents**: List all files in the design directory.
25
+ 3. **Analyze**: For EACH design document:
26
+
27
+ * **Contextualize**: Read the design document. Identify the intent,
28
+ proposed changes, and specific filenames/symbols mentioned.
29
+ * **Locate Source**: Find the corresponding source code files in the
30
+ source tree. If paths aren't explicit, use code search or grep to
31
+ locate the relevant classes, functions, or API endpoints mentioned in
32
+ the doc. Prompt the user to add missing links to the document to make
33
+ future detection cheaper.
34
+ * **Verify**: Read the current state of those source files.
35
+ * **Detect Drift**: Compare the design vs. reality. Look specifically for:
36
+ * Missing Features: Logic described in the doc but absent in the code.
37
+ * Incomplete Models: Dataclasses/Classes/Structs/Protos missing fields
38
+ specified in the design.
39
+ * Logic Shortcuts: Hardcoded values where dynamic logic was planned.
40
+ * Architectural Divergence: Implementation using different
41
+ patterns/libraries than proposed.
42
+ * **Filter**: Report ONLY the differences. Do not describe what is working
43
+ or what matches. If the code matches the design perfectly, output "No
44
+ drift detected."
45
+
46
+ 4. **Report**: Produce a single report listing all discrepancies found.
47
+
48
+ * Append the analysis for each file to `{YYYY-MM-DD}_DRIFT_REPORT.md`
49
+ using your file-writing tool.
50
+ * Strict Format:
51
+
52
+ ```markdown
53
+ ## <DESIGN_DOC_NAME>
54
+
55
+ <Bulleted list of specific divergences found>
56
+ <Or "No drift detected">
57
+ ```
58
+
59
+ 5. **Guidance**
60
+
61
+ - Be rigorous. If a design doc mentions a specific object, field or file
62
+ name and the code doesn't have it, that is a reportable drift. Double
63
+ check for coverage. If there is some part of the logic that is not
64
+ referenced in a design or README, this is a reportable drift.
65
+ - Read files liberally to ensure you are looking at the current state
66
+ of the code, not relying on memory.
67
+ - Process the files sequentially to ensure the tool output buffer doesn't
68
+ overflow.