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,265 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ael-spec-brainstorm
|
|
3
|
+
license: Apache-2.0
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
description: >-
|
|
6
|
+
Interactive ideation and brainstorming skill for the Elephant &
|
|
7
|
+
Goldfish Model (EGM). Helps turn half-baked concepts into structured
|
|
8
|
+
hypotheses via clarifying questions, review, and iterative refinement.
|
|
9
|
+
Produces an RFC summary for human review or more detailed design with
|
|
10
|
+
/ael-spec-draft.
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
<!-- 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. -->
|
|
14
|
+
|
|
15
|
+
# EGM Brainstorm: Interactive Multi-Lens Ideation & Refinement
|
|
16
|
+
|
|
17
|
+
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>`.
|
|
18
|
+
|
|
19
|
+
## Overview
|
|
20
|
+
|
|
21
|
+
This skill acts as the upstream conversational brainstorming engine for the
|
|
22
|
+
Elephant-Goldfish Model (EGM). It turns "half-baked" or raw concepts into
|
|
23
|
+
hypotheses by combining **interactive clarifying questions** with an automated
|
|
24
|
+
**Goldfish review**. The outcome is an iteratively refined RFC summary
|
|
25
|
+
(`concepts_brief.md`) that leads directly into `/ael-spec-draft` or review with
|
|
26
|
+
peers.
|
|
27
|
+
|
|
28
|
+
## Delegation
|
|
29
|
+
|
|
30
|
+
A Goldfish runs in a fresh context with no conversation history. Spawn each
|
|
31
|
+
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
|
|
32
|
+
frontmatter `name` (for example `ael-spec-zoom-out`) is the subagent type to request
|
|
33
|
+
where your harness registers named subagents. Otherwise spawn a general-purpose
|
|
34
|
+
subagent and tell it to read that persona file first. Pass the prompt verbatim
|
|
35
|
+
and wait for the report. If your harness cannot nest subagents,
|
|
36
|
+
use direct dispatch instead of the synthesizer. See `npx ai-engineering-loop docs loop-hosts`.
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
## Execution Constraints (CRITICAL)
|
|
40
|
+
|
|
41
|
+
1. **Artifact-First Delivery (MANDATORY)**: You are **STRICTLY FORBIDDEN** from
|
|
42
|
+
presenting large proposals, drafts, brainstorm summaries, or briefs directly
|
|
43
|
+
in the chat pane. You **MUST** write/update them directly to a file (e.g.,
|
|
44
|
+
`./concepts_brief.md` in the working directory or your harness's artifact
|
|
45
|
+
directory, if it has one) using your file-writing tool and notify the user
|
|
46
|
+
in the chat with a clean link to the file.
|
|
47
|
+
2. **Multi-Turn Open-Ended Clarification & Readiness Gate**: You **MUST** drill
|
|
48
|
+
down into the concept through open-ended plain-text questions across
|
|
49
|
+
multiple chat turns until the problem statement and boundaries are
|
|
50
|
+
thoroughly clear. You **MUST NOT** spawn subagents until the user explicitly
|
|
51
|
+
confirms readiness after reviewing the anchored working hypothesis. You are
|
|
52
|
+
**STRICTLY FORBIDDEN** from using structured question tools (`ask_question`)
|
|
53
|
+
or supplying pre-canned multiple-choice candidate answers during open-ended
|
|
54
|
+
questioning.
|
|
55
|
+
3. **Parallel Goldfish Reviews**: You **MUST** evaluate the feature concept
|
|
56
|
+
across specialized Goldfish lenses simultaneously to prevent sequential bias
|
|
57
|
+
and maximize critique breadth.
|
|
58
|
+
4. **Plain-English Standard**: You **MUST** write all concepts briefs, RFC
|
|
59
|
+
summaries, and communications in simple, direct, jargon-free plain English.
|
|
60
|
+
Explain technical mechanisms directly. Do not summarize away substance or
|
|
61
|
+
rely on buzzwords. Do not use ungrounded promotional adjectives (e.g.,
|
|
62
|
+
*seamless*, *robust*, *blazingly fast*) or decorative adverbs (e.g.,
|
|
63
|
+
*seamlessly*, *effortlessly*, *literally*, *drastically*, *obviously*).
|
|
64
|
+
5. **Default to Stress-Testing**: Never agree by default. Your primary
|
|
65
|
+
directive is to stress-test ideas, strategies, and opinions. Find the
|
|
66
|
+
weakest points, edge cases, and blind spots before affirming anything.
|
|
67
|
+
6. **No Glazing**: Eliminate sycophancy. Do not call ideas "great,"
|
|
68
|
+
"brilliant," or "smart." Compliments without substance are noise.
|
|
69
|
+
7. **Critique First**: Even when an idea is strong, lead with what is wrong,
|
|
70
|
+
missing, or risky before highlighting its merits.
|
|
71
|
+
8. **Reject Echo-Chamber Framing**: Never parrot framing back to the user. If a
|
|
72
|
+
conclusion is asserted, do not validate it reflexively.
|
|
73
|
+
9. **Generate Counter-Arguments**: For every strategy proposed, actively
|
|
74
|
+
outline: What is the user not seeing? What is the strongest
|
|
75
|
+
counter-argument? Is the opposing view justified?
|
|
76
|
+
10. **Earn Your Agreement**: Only agree when the idea has survived rigorous,
|
|
77
|
+
objective scrutiny.
|
|
78
|
+
11. **Banned Adjectives (No Flattery)**: You are strictly prohibited from using
|
|
79
|
+
validating adjectives like "brilliant," "great," "smart," "correct,"
|
|
80
|
+
"perfect," "excellent," or "spot-on" when referring to the user's inputs,
|
|
81
|
+
corrections, or decisions.
|
|
82
|
+
12. **Banned Apologies**: You MUST NOT output polite apologies (e.g., "I
|
|
83
|
+
apologize," "I am sorry," "Forgive me") when challenged or corrected.
|
|
84
|
+
Instead, outline the corrected technical logic or trade-offs directly.
|
|
85
|
+
13. **Interaction Invariants**: All interactive gates (structured question tools
|
|
86
|
+
such as `ask_question`, if your harness has one, or plain chat) MUST contain
|
|
87
|
+
strictly one question (`len(questions) == 1`), be the sole tool call in the
|
|
88
|
+
turn, and provide clear, action-oriented options without `(Recommended)`
|
|
89
|
+
prefixes.
|
|
90
|
+
|
|
91
|
+
## The Goldfish Brainstorming Lenses
|
|
92
|
+
|
|
93
|
+
| Lens / Persona | Core Objective | Key Questions Challenged |
|
|
94
|
+
| :---------------------- | :---------------------- | :----------------------- |
|
|
95
|
+
| **Contrarian / YAGNI** | Code & complexity minimization | *Why does this feature need to exist? Can an existing library, open-source dependency, API, or service solve 90% of this problem without writing new code?* |
|
|
96
|
+
| **Cost, Quota & Token Economics** | Infrastructure & budget scaling | *What is the peak QPS, memory footprint, database query load, or LLM token budget? Will this hit quota ceilings at scale?* |
|
|
97
|
+
| **UX & Developer Ergonomics** | Usability & cognitive overhead | *Is the API/CLI intuitive? Does it match ecosystem conventions? Are error messages actionable, or does it add developer friction?* |
|
|
98
|
+
| **Migration & Backward Compatibility** | Rollout safety & version skew | *How do existing clients/data migrate? Does this break serialized schemas, protos, or persistent storage? How is rollback handled mid-migration?* |
|
|
99
|
+
| **Observability & SRE Debuggability** | Telemetry & operational visibility | *Are key operations traceable via distributed tracing? Are telemetry metrics actionable? How will oncall engineers triage a production incident at 3 AM?* |
|
|
100
|
+
| **Long-Term Tech Debt & Maintenance** | Future maintainability | *Does this introduce tightly coupled dependencies or brittle state machines that will be painful to maintain in 2 years?* |
|
|
101
|
+
|
|
102
|
+
## Execution Workflow
|
|
103
|
+
|
|
104
|
+
### Step 1: Deep Clarification & Problem Statement Drilling
|
|
105
|
+
|
|
106
|
+
1. **Check for Concept Foundation**: Verify if the user provided an initial
|
|
107
|
+
feature idea or concept prompt. If missing, prompt the user to describe what
|
|
108
|
+
they want to brainstorm.
|
|
109
|
+
2. **Iterative Problem Drilling (Multi-Turn Chat)**: Do **NOT** rush into
|
|
110
|
+
launching subagents after a single response. Continue asking targeted,
|
|
111
|
+
open-ended clarifying questions across multiple chat turns as needed until
|
|
112
|
+
the problem statement, constraints, and target behavior are thoroughly
|
|
113
|
+
defined. Do NOT use structured question tools (`ask_question`) and do NOT
|
|
114
|
+
provide candidate multiple-choice options during problem exploration. Ask
|
|
115
|
+
open-ended questions directly in chat:
|
|
116
|
+
|
|
117
|
+
* *What specific problem, bottleneck, or pain point does this solve?*
|
|
118
|
+
* *Who or what system will consume this feature, and under what
|
|
119
|
+
SLAs/invariants?*
|
|
120
|
+
* *What are the hard non-negotiable constraints (e.g., zero false
|
|
121
|
+
positives, offline operation, specific platform/dialect)?*
|
|
122
|
+
* *What are the edge cases or out-of-scope boundaries?*
|
|
123
|
+
* *How is this issue dealt with today? Why doesn't that work?*
|
|
124
|
+
* *How is success going to be measured?*
|
|
125
|
+
|
|
126
|
+
3. **Readiness Checkpoint Gate (Single-Select)**: Once a clear foundation is
|
|
127
|
+
established, summarize the anchored working hypothesis in 2-3 sentences.
|
|
128
|
+
Present an explicit single-select confirmation gate (using a structured
|
|
129
|
+
question tool such as `ask_question` if your harness has one, or plain
|
|
130
|
+
chat):
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"questions": [
|
|
135
|
+
{
|
|
136
|
+
"question": "Anchored feature hypothesis: [2-3 sentence summary]. How would you like to proceed?",
|
|
137
|
+
"options": [
|
|
138
|
+
"Review with Goldfishes",
|
|
139
|
+
"Clarify additional constraints or assumptions in chat"
|
|
140
|
+
],
|
|
141
|
+
"is_multi_select": false
|
|
142
|
+
}
|
|
143
|
+
]
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
* **Option 0: `Review with Goldfishes`**: The user confirms readiness.
|
|
148
|
+
Proceed immediately to Step 2 (Goldfish Review & Synthesis) to invoke
|
|
149
|
+
`ael-spec-synthesizer`.
|
|
150
|
+
* **Option 1: `Clarify additional constraints or assumptions in chat`**:
|
|
151
|
+
The user wishes to refine the problem statement or provides write-in
|
|
152
|
+
notes. Stay in Step 1, yield the turn in chat for details, incorporate
|
|
153
|
+
feedback into the hypothesis, and re-present the readiness gate when
|
|
154
|
+
ready.
|
|
155
|
+
|
|
156
|
+
4. **Proceed to Step 2 ONLY** after Option 0 is confirmed. Do NOT spawn
|
|
157
|
+
subagents before this gate confirms readiness.
|
|
158
|
+
|
|
159
|
+
### Step 2: Goldfish Review & Synthesis
|
|
160
|
+
|
|
161
|
+
1. **Delegate to Synthesizer Subagent**: Spawn the intermediate
|
|
162
|
+
**`ael-spec-synthesizer`** agent (or parallel Goldfish subagents across the 6
|
|
163
|
+
specialized lenses if your harness cannot nest subagents):
|
|
164
|
+
* Subagent: `ael-spec-synthesizer` (`npx ai-engineering-loop docs ael-spec-synthesizer`)
|
|
165
|
+
* `Prompt`: >- Conduct multi-lens brainstorm for feature concept:
|
|
166
|
+
`[AnchoredFeatureHypothesis]`. Mode: `BRAINSTORM`. Reviewers:
|
|
167
|
+
`[ael-spec-design, ael-spec-codebase-details, ael-spec-zoom-out, ael-spec-comprehension,
|
|
168
|
+
ael-spec-implementation-readiness, ael-spec-structural]`.
|
|
169
|
+
2. **Synthesizer Execution**: The `ael-spec-synthesizer` subagent launches the
|
|
170
|
+
parallel Goldfish reviewers across the specialized lenses (`ael-spec-design`,
|
|
171
|
+
`ael-spec-codebase-details`, `ael-spec-zoom-out`, `ael-spec-comprehension`,
|
|
172
|
+
`ael-spec-implementation-readiness`, `ael-spec-structural`) with `Mode: BRAINSTORM`.
|
|
173
|
+
3. **Deduplication**: Collect the raw findings from the Goldfish reviewers,
|
|
174
|
+
deduplicate overlapping points, and format them into a cohesive analysis.
|
|
175
|
+
4. **Write/Update Artifact**: Format and write the synthesized brief to
|
|
176
|
+
`concepts_brief.md` in the working directory (or your harness's artifact
|
|
177
|
+
directory, if it has one) using your file-writing tool.
|
|
178
|
+
|
|
179
|
+
The `concepts_brief.md` artifact follows this structure:
|
|
180
|
+
|
|
181
|
+
```markdown
|
|
182
|
+
# [Feature Name]
|
|
183
|
+
|
|
184
|
+
* **Author:** [Author Name or GitHub Handle]
|
|
185
|
+
* **Date:** [YYYY-MM-DD]
|
|
186
|
+
|
|
187
|
+
## Overview
|
|
188
|
+
|
|
189
|
+
[High-level summary of the feature, target user, and core value proposition written in plain English.]
|
|
190
|
+
|
|
191
|
+
## Analysis
|
|
192
|
+
|
|
193
|
+
[Cohesive analysis found by review lenses written in plain English.]
|
|
194
|
+
|
|
195
|
+
## Goals vs. Non-Goals
|
|
196
|
+
|
|
197
|
+
* **In-Scope Goals:** [Explicitly defined scope items]
|
|
198
|
+
* **Out-of-Scope Non-Goals:** [Features intentionally excluded]
|
|
199
|
+
|
|
200
|
+
## Alternatives Weighed
|
|
201
|
+
|
|
202
|
+
[Each option rejected during ideation, with the reason. `/ael-spec-draft` copies
|
|
203
|
+
these into Alternatives Considered and has no other source for them.]
|
|
204
|
+
|
|
205
|
+
## Key Decisions & Staging for Next Steps
|
|
206
|
+
|
|
207
|
+
[Key decisions resolved during ideation to be carried forward into `/ael-spec-draft`.]
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Step 3: Interactive Iteration & Refinement Loop
|
|
211
|
+
|
|
212
|
+
1. **Notify & Highlight (No Chat Dumps)**: Notify the user in chat that
|
|
213
|
+
`concepts_brief.md` has been updated (give its path). Highlight 2-3 key
|
|
214
|
+
objections or open risks raised by the Goldfish reviewers.
|
|
215
|
+
2. **Iterate**: Ask the user how they wish to address the Goldfish objections
|
|
216
|
+
(e.g., pivoting the approach, narrowing scope, or adding constraints).
|
|
217
|
+
3. **Loop Back**: Repeat Steps 1 and 2 to re-run or update the Goldfish
|
|
218
|
+
analysis until the concept has survived scrutiny and the user is satisfied.
|
|
219
|
+
|
|
220
|
+
### Step 4: Finalize & Handoff
|
|
221
|
+
|
|
222
|
+
1. **Artifact Alignment**: Ask the user to review the final `concepts_brief.md`
|
|
223
|
+
artifact and confirm their alignment.
|
|
224
|
+
2. **Step 4 Handoff Gate Modal (Single-Select)**: Once approved, present the
|
|
225
|
+
standardized handoff choices (using a structured question tool such as
|
|
226
|
+
`ask_question` if your harness has one, or plain chat):
|
|
227
|
+
|
|
228
|
+
```json
|
|
229
|
+
{
|
|
230
|
+
"questions": [
|
|
231
|
+
{
|
|
232
|
+
"question": "Brainstorming complete. concepts_brief.md is finalized. Select next step:",
|
|
233
|
+
"options": [
|
|
234
|
+
"Publish concepts_brief.md as RFC for team feedback",
|
|
235
|
+
"Proceed to /ael-spec-draft (Initialize formal design document)",
|
|
236
|
+
"Continue refining concepts_brief.md in ideation mode",
|
|
237
|
+
"Conclude brainstorming and keep brief for later"
|
|
238
|
+
],
|
|
239
|
+
"is_multi_select": false
|
|
240
|
+
}
|
|
241
|
+
]
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
* **Option 0: `Publish concepts_brief.md as RFC for team feedback`**:
|
|
246
|
+
* Write `concepts_brief.md` to `docs/designs/<feature_name>.md` using
|
|
247
|
+
your file-writing tool.
|
|
248
|
+
* Register the RFC in `docs/designs/SITEMAP.md` if it exists.
|
|
249
|
+
* Notify the user in chat that the RFC has been published and can be
|
|
250
|
+
shared with the team for feedback before formal drafting. Remind the
|
|
251
|
+
user that once feedback is gathered, a detailed design can be
|
|
252
|
+
initiated by running `/ael-spec-draft docs/designs/<feature_name>.md`.
|
|
253
|
+
* **Option 1: `Proceed to /ael-spec-draft (Initialize formal design
|
|
254
|
+
document)`**:
|
|
255
|
+
* Confirm that `concepts_brief.md` is saved in the working directory
|
|
256
|
+
or artifact directory.
|
|
257
|
+
* Instruct the user to run `/ael-spec-draft` (or activate the `ael-spec-draft`
|
|
258
|
+
skill), noting that `/ael-spec-draft` automatically ingests
|
|
259
|
+
`concepts_brief.md` as its Priority 1 intake source.
|
|
260
|
+
* **Option 2: `Continue refining concepts_brief.md in ideation mode`**:
|
|
261
|
+
* Return to Step 3 iteration loop to drill into further edge cases or
|
|
262
|
+
update the brief based on user chat input.
|
|
263
|
+
* **Option 3: `Conclude brainstorming and keep brief for later`**:
|
|
264
|
+
* Conclude the session gracefully. Remind the user that
|
|
265
|
+
`concepts_brief.md` remains saved for future reference.
|
|
@@ -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
|
+
```
|