@vpxa/aikit 0.1.186 → 0.1.188
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/package.json +1 -1
- package/packages/blocks-core/dist/index.js +112 -31
- package/packages/embeddings/dist/index.d.ts +5 -0
- package/packages/embeddings/dist/index.js +1 -1
- package/packages/present/dist/index.html +135 -54
- package/packages/server/dist/index.js +1 -1
- package/packages/server/dist/{server-BCnhTdUy.js → server-BvVBHkFD.js} +121 -121
- package/packages/server/viewers/canvas.html +164 -67
- package/scaffold/dist/definitions/skills/adr-skill.mjs +73 -155
- package/scaffold/dist/definitions/skills/aikit.mjs +291 -318
- package/scaffold/dist/definitions/skills/brainstorming.mjs +107 -242
- package/scaffold/dist/definitions/skills/browser-use.mjs +213 -1
- package/scaffold/dist/definitions/skills/c4-architecture.mjs +213 -2257
- package/scaffold/dist/definitions/skills/docs.mjs +395 -755
- package/scaffold/dist/definitions/skills/lesson-learned.mjs +61 -21
- package/scaffold/dist/definitions/skills/present.mjs +1 -1
- package/scaffold/dist/definitions/skills/react.mjs +104 -137
- package/scaffold/dist/definitions/skills/requirements-clarity.mjs +55 -2
- package/scaffold/dist/definitions/skills/session-handoff.mjs +127 -177
- package/scaffold/dist/definitions/skills/typescript.mjs +16 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
var e=[{file:`SKILL.md`,content:`---
|
|
2
2
|
name: brainstorming
|
|
3
|
-
description: "Design exploration for planning-phase agents (Orchestrator, Planner, Researchers). Explores user intent, requirements and design BEFORE handing off to implementation agents. NOT for code agents
|
|
3
|
+
description: "Design exploration for planning-phase agents (Orchestrator, Planner, Researchers). Explores user intent, requirements and design BEFORE handing off to implementation agents. Use when there are multiple valid approaches to a problem, when architecture decisions need exploration, when the user says 'how should I...', 'what's the best way to...', 'explore options for...', or when a task has genuine design forks. NOT for code agents - they implement designs, not create them. NOT for single-path decisions - if only one approach makes sense, skip this."
|
|
4
4
|
metadata:
|
|
5
5
|
category: planning
|
|
6
6
|
domain: general
|
|
@@ -16,35 +16,40 @@ argument-hint: "Feature, component, or behavior to design"
|
|
|
16
16
|
|
|
17
17
|
## Quick Reference
|
|
18
18
|
|
|
19
|
-
**Purpose:** Explore
|
|
19
|
+
**Purpose:** Explore requirements and design space before implementation starts.
|
|
20
20
|
|
|
21
|
-
**
|
|
21
|
+
**Use this skill when:** there are multiple viable approaches, architecture trade-offs matter, or the user is asking for guidance rather than code.
|
|
22
22
|
|
|
23
|
-
**
|
|
24
|
-
- **Simple Mode** - <=3 files, single concern, no new boundaries -> brief context + 3-5 targeted questions + short design summary
|
|
25
|
-
- **Full Mode** - multi-file, new services, cross-cutting concerns -> deep context gathering + structured design document + explicit approval
|
|
23
|
+
**Skip this skill when:** the work is already decided, the change is mechanical, or only one reasonable path exists.
|
|
26
24
|
|
|
27
|
-
**
|
|
25
|
+
**HARD GATE:** Do NOT write code, scaffold files, or hand off to implementation until a design is presented and approved.
|
|
28
26
|
|
|
29
|
-
**
|
|
30
|
-
|
|
31
|
-
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
|
|
32
|
-
|
|
33
|
-
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
|
|
27
|
+
**Expected output:** a short design or spec with constraints, alternatives, recommendation, risks, and acceptance criteria.
|
|
34
28
|
|
|
35
29
|
<HARD-GATE>
|
|
36
30
|
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
|
|
37
31
|
</HARD-GATE>
|
|
38
32
|
|
|
39
|
-
##
|
|
33
|
+
## When Brainstorming Is Appropriate
|
|
34
|
+
|
|
35
|
+
Use brainstorming when at least one of these is true:
|
|
40
36
|
|
|
41
|
-
|
|
37
|
+
- Multiple valid approaches exist and the choice changes cost, risk, or UX
|
|
38
|
+
- The work introduces or changes boundaries: service, module, API, workflow, ownership
|
|
39
|
+
- The user is asking for options, strategy, trade-offs, or "best way" guidance
|
|
40
|
+
- Constraints are real but incomplete: performance, timeline, migration cost, reversibility, team familiarity
|
|
41
|
+
|
|
42
|
+
Do not use brainstorming when the path is already obvious:
|
|
43
|
+
|
|
44
|
+
- Fixing a typo, renaming a variable, or updating a pinned dependency
|
|
45
|
+
- Implementing an already-approved spec or ADR
|
|
46
|
+
- Mechanical migrations where the desired end state is predetermined
|
|
42
47
|
|
|
43
48
|
---
|
|
44
49
|
|
|
45
50
|
## Mode Selection
|
|
46
51
|
|
|
47
|
-
This skill operates in two modes.
|
|
52
|
+
This skill operates in two modes. You choose the mode from the problem shape; do not ask the user which mode they want.
|
|
48
53
|
|
|
49
54
|
### Simple Mode
|
|
50
55
|
|
|
@@ -57,7 +62,7 @@ Use when **all** of these are true:
|
|
|
57
62
|
|
|
58
63
|
Examples: config change, utility function, bug fix with design ambiguity, small feature in existing component.
|
|
59
64
|
|
|
60
|
-
###
|
|
65
|
+
### Full Mode
|
|
61
66
|
|
|
62
67
|
Use when **any** of these are true:
|
|
63
68
|
- Affects >3 files or crosses service boundaries
|
|
@@ -71,269 +76,129 @@ Examples: new notification channel, new API service, platform redesign, multi-se
|
|
|
71
76
|
|
|
72
77
|
---
|
|
73
78
|
|
|
74
|
-
##
|
|
75
|
-
|
|
76
|
-
### Checklist
|
|
77
|
-
|
|
78
|
-
1. **Explore project context** — check files, docs, recent commits
|
|
79
|
-
2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
|
|
80
|
-
3. **Propose 2-3 approaches** — with trade-offs and your recommendation
|
|
81
|
-
4. **Present design** — in sections scaled to their complexity, get user approval after each section
|
|
82
|
-
5. **Write design doc** — save to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` and commit
|
|
83
|
-
6. **Transition to implementation** — invoke writing-plans skill to create implementation plan
|
|
84
|
-
|
|
85
|
-
### Process Flow
|
|
86
|
-
|
|
87
|
-
\`\`\`dot
|
|
88
|
-
digraph brainstorming_simple {
|
|
89
|
-
"Explore project context" [shape=box];
|
|
90
|
-
"Ask clarifying questions" [shape=box];
|
|
91
|
-
"Propose 2-3 approaches" [shape=box];
|
|
92
|
-
"Present design sections" [shape=box];
|
|
93
|
-
"User approves design?" [shape=diamond];
|
|
94
|
-
"Write design doc" [shape=box];
|
|
95
|
-
"Invoke writing-plans skill" [shape=doublecircle];
|
|
96
|
-
|
|
97
|
-
"Explore project context" -> "Ask clarifying questions";
|
|
98
|
-
"Ask clarifying questions" -> "Propose 2-3 approaches";
|
|
99
|
-
"Propose 2-3 approaches" -> "Present design sections";
|
|
100
|
-
"Present design sections" -> "User approves design?";
|
|
101
|
-
"User approves design?" -> "Present design sections" [label="no, revise"];
|
|
102
|
-
"User approves design?" -> "Write design doc" [label="yes"];
|
|
103
|
-
"Write design doc" -> "Invoke writing-plans skill";
|
|
104
|
-
}
|
|
105
|
-
\`\`\`
|
|
106
|
-
|
|
107
|
-
---
|
|
108
|
-
|
|
109
|
-
## Advanced Mode Process
|
|
110
|
-
|
|
111
|
-
### Checklist
|
|
112
|
-
|
|
113
|
-
1. **Explore project context** — check files, docs, recent commits
|
|
114
|
-
2. **Assess scope** — if multiple independent subsystems, decompose before detailing (see below)
|
|
115
|
-
3. **Offer visual presentation support** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. Use \`present({ schemaVersion: 1, title: "Brainstorming", blocks: [...] })\` to display brainstorming results. Use \`list\` for idea sets, \`table\` for evaluation matrices, \`kv\` for the selected approach, and \`metrics\` for requirement scores. NEVER \`code\` blocks for structured data.
|
|
116
|
-
4. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
|
|
117
|
-
5. **Propose 2-3 approaches via Decision Protocol** — run the full 3-phase multi-model decision protocol: Phase 1 (4 Researchers in parallel), Phase 2 (peer review with anonymized outputs), Phase 3 (structured verdict). Present the verdict visually using \`present({ schemaVersion: 1, title: "Approach Verdict", blocks: [...] })\` with \`table\` for approach comparisons, \`list\` for recommendations, and \`kv\` for verdict metadata. NEVER \`code\` blocks for structured data. *(See "Decision Protocol Integration" below.)*
|
|
118
|
-
6. **Present design** — in sections scaled to their complexity, get user approval after each section
|
|
119
|
-
7. **Write design doc** — save to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` and commit
|
|
120
|
-
8. **Spec review loop** — review the spec for completeness, consistency, clarity, scope, and YAGNI. Fix issues. Max 3 iterations, then surface to user.
|
|
121
|
-
9. **User reviews written spec** — ask user to review the spec file before proceeding
|
|
122
|
-
10. **Transition to implementation** — invoke writing-plans skill to create implementation plan
|
|
123
|
-
|
|
124
|
-
### Decision Protocol Integration (Advanced Mode Only)
|
|
125
|
-
|
|
126
|
-
When Advanced Mode reaches step 5 ("Propose approaches"), invoke the **full 3-phase multi-model decision protocol**:
|
|
127
|
-
|
|
128
|
-
**Phase 1 — Independent Research:**
|
|
129
|
-
1. Frame the design question with full context gathered from steps 1-4
|
|
130
|
-
2. Launch ALL 4 Researcher variants **in parallel** with identical framing — each applies its thinking style:
|
|
131
|
-
- **Alpha (Contrarian)**: Actively seeks flaws and fatal assumptions
|
|
132
|
-
- **Beta (First Principles)**: Strips assumptions, rebuilds from ground truth
|
|
133
|
-
- **Gamma (Expansionist)**: Finds undervalued opportunities, cross-domain patterns
|
|
134
|
-
- **Delta (Executor)**: Focuses on fastest path, implementation cost, feasibility
|
|
135
|
-
|
|
136
|
-
**Phase 2 — Peer Review:**
|
|
137
|
-
3. **Anonymize** Phase 1 outputs as Perspective A / B / C / D (strip agent names)
|
|
138
|
-
4. Launch a **second parallel batch** of 4 reviewers, each evaluating ALL perspectives:
|
|
139
|
-
- Strongest argument — which perspective and why?
|
|
140
|
-
- Critical blind spot — what did the strongest miss?
|
|
141
|
-
- Consensus gap — what did ALL overlook?
|
|
142
|
-
- Verdict — which approach to adopt?
|
|
143
|
-
|
|
144
|
-
**Phase 3 — Structured Verdict:**
|
|
145
|
-
5. Synthesize BOTH layers into the structured verdict format:
|
|
146
|
-
- **Where Agrees** / **Where Clashes** / **Blind Spots Caught** / **Recommendation** (with confidence) / **First Step**
|
|
147
|
-
6. Present verdict visually using \`present({ schemaVersion: 1, title: "Approach Verdict", blocks: [...] })\` with \`table\` for approach comparisons, \`list\` for recommendations, and \`kv\` for verdict metadata. NEVER \`code\` blocks for structured data.
|
|
148
|
-
7. If a decision produces an ADR, write it to \`docs/decisions/\`
|
|
149
|
-
|
|
150
|
-
**Floor-tier shortcut**: Skip Phase 2 (peer review), synthesize directly from Phase 1.
|
|
151
|
-
|
|
152
|
-
This replaces the single-agent "propose approaches" step with 8 independent evaluations (4 research + 4 review), producing significantly higher-quality decisions.
|
|
153
|
-
|
|
154
|
-
### Process Flow
|
|
155
|
-
|
|
156
|
-
\`\`\`dot
|
|
157
|
-
digraph brainstorming_advanced {
|
|
158
|
-
"Explore project context" [shape=box];
|
|
159
|
-
"Assess scope" [shape=diamond];
|
|
160
|
-
"Decompose into sub-projects" [shape=box];
|
|
161
|
-
"Visual questions ahead?" [shape=diamond];
|
|
162
|
-
"Offer Visual Presentation\\n(own message)" [shape=box];
|
|
163
|
-
"Ask clarifying questions" [shape=box];
|
|
164
|
-
"Phase 1: 4 Researchers\\nin parallel" [shape=box, style=bold];
|
|
165
|
-
"Phase 2: Peer Review\\n(anonymized, 4 reviewers)" [shape=box, style=bold];
|
|
166
|
-
"Phase 3: Structured Verdict" [shape=box];
|
|
167
|
-
"Present design sections" [shape=box];
|
|
168
|
-
"User approves design?" [shape=diamond];
|
|
169
|
-
"Write design doc" [shape=box];
|
|
170
|
-
"Spec review loop" [shape=box];
|
|
171
|
-
"Spec review passed?" [shape=diamond];
|
|
172
|
-
"User reviews spec?" [shape=diamond];
|
|
173
|
-
"Invoke writing-plans skill" [shape=doublecircle];
|
|
174
|
-
|
|
175
|
-
"Explore project context" -> "Assess scope";
|
|
176
|
-
"Assess scope" -> "Decompose into sub-projects" [label="too large"];
|
|
177
|
-
"Assess scope" -> "Visual questions ahead?" [label="right-sized"];
|
|
178
|
-
"Decompose into sub-projects" -> "Visual questions ahead?" [label="first sub-project"];
|
|
179
|
-
"Visual questions ahead?" -> "Offer Visual Presentation\\n(own message)" [label="yes"];
|
|
180
|
-
"Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
|
|
181
|
-
"Offer Visual Presentation\\n(own message)" -> "Ask clarifying questions";
|
|
182
|
-
"Ask clarifying questions" -> "Phase 1: 4 Researchers\\nin parallel";
|
|
183
|
-
"Phase 1: 4 Researchers\\nin parallel" -> "Phase 2: Peer Review\\n(anonymized, 4 reviewers)";
|
|
184
|
-
"Phase 2: Peer Review\\n(anonymized, 4 reviewers)" -> "Phase 3: Structured Verdict";
|
|
185
|
-
"Phase 3: Structured Verdict" -> "Present design sections";
|
|
186
|
-
"Present design sections" -> "User approves design?";
|
|
187
|
-
"User approves design?" -> "Present design sections" [label="no, revise"];
|
|
188
|
-
"User approves design?" -> "Write design doc" [label="yes"];
|
|
189
|
-
"Write design doc" -> "Spec review loop";
|
|
190
|
-
"Spec review loop" -> "Spec review passed?";
|
|
191
|
-
"Spec review passed?" -> "Spec review loop" [label="issues found, fix"];
|
|
192
|
-
"Spec review passed?" -> "User reviews spec?" [label="approved"];
|
|
193
|
-
"User reviews spec?" -> "Write design doc" [label="changes requested"];
|
|
194
|
-
"User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
|
|
195
|
-
}
|
|
196
|
-
\`\`\`
|
|
197
|
-
|
|
198
|
-
### Large Project Decomposition
|
|
199
|
-
|
|
200
|
-
Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
|
|
201
|
-
|
|
202
|
-
If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
|
|
203
|
-
|
|
204
|
-
### Spec Review Loop
|
|
205
|
-
|
|
206
|
-
After writing the spec document, review it yourself for:
|
|
207
|
-
|
|
208
|
-
| Category | What to Look For |
|
|
209
|
-
|----------|------------------|
|
|
210
|
-
| Completeness | TODOs, placeholders, "TBD", incomplete sections |
|
|
211
|
-
| Consistency | Internal contradictions, conflicting requirements |
|
|
212
|
-
| Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
|
|
213
|
-
| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
|
|
214
|
-
| YAGNI | Unrequested features, over-engineering |
|
|
79
|
+
## NEVER
|
|
215
80
|
|
|
216
|
-
**
|
|
81
|
+
- **NEVER skip divergent thinking to jump to solutions** - premature convergence is the most common brainstorming failure. Force at least 3 alternatives before evaluating.
|
|
82
|
+
- **NEVER present options without trade-off analysis** - listing A/B/C without pros, cons, and context is noise. Each option needs: strength, weakness, best-when.
|
|
83
|
+
- **NEVER conflate requirements with design** - "the user wants to log in" is a requirement; "use OAuth2 + JWT" is a design. Clarify the problem before exploring the solution space.
|
|
84
|
+
- **NEVER evaluate during the divergent phase** - "that won't work" too early kills useful exploration. Generate first, judge second.
|
|
85
|
+
- **NEVER propose more than 5 options** - too many options create analysis paralysis. 3-5 well-differentiated choices is enough.
|
|
86
|
+
- **NEVER present the obvious choice as the only real option with strawman alternatives** - if one option clearly dominates before analysis, say brainstorming is unnecessary and recommend directly.
|
|
87
|
+
- **NEVER use brainstorming for single-path decisions** - if there is only one credible path, execute or hand off; do not manufacture fake alternatives.
|
|
88
|
+
- **NEVER hide the deciding constraint** - if compliance, migration cost, latency, or org ownership is driving the decision, state it explicitly.
|
|
217
89
|
|
|
218
|
-
|
|
90
|
+
## Core Workflow
|
|
219
91
|
|
|
220
|
-
|
|
92
|
+
| Stage | What you do | What good output looks like |
|
|
93
|
+
|-------|-------------|-----------------------------|
|
|
94
|
+
| Frame | State the problem, constraints, and success criteria | Clear decision question and explicit boundaries |
|
|
95
|
+
| Clarify | Ask one question at a time until ambiguity drops | Requirements are separate from solutions |
|
|
96
|
+
| Diverge | Generate 3 alternatives that differ in shape, not just labels | Options have meaningfully different trade-offs |
|
|
97
|
+
| Evaluate | Compare options against criteria, constraints, reversibility, and delivery cost | Rejection reasons are explicit |
|
|
98
|
+
| Recommend | Pick one option and explain why the others lost | Recommendation matches the stated constraints |
|
|
99
|
+
| Confirm | Present the design, get approval, then hand off | Implementation can proceed without reopening core design questions |
|
|
221
100
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
> "Spec written and committed to \`<path>\`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
|
|
225
|
-
|
|
226
|
-
Wait for the user's response. If they request changes, make them and re-run the spec review. Only proceed once the user approves.
|
|
101
|
+
Simple Mode compresses the workflow into a short design note. Full Mode produces a fuller spec and spends more time on constraints, interfaces, migration, and rollout.
|
|
227
102
|
|
|
228
103
|
---
|
|
229
104
|
|
|
230
|
-
##
|
|
231
|
-
|
|
232
|
-
**Understanding the idea:**
|
|
233
|
-
- Check out the current project state first (files, docs, recent commits)
|
|
234
|
-
- Ask questions one at a time to refine the idea
|
|
235
|
-
- Prefer multiple choice questions when possible, but open-ended is fine too
|
|
236
|
-
- Only one question per message — if a topic needs more exploration, break it into multiple questions
|
|
237
|
-
- Focus on understanding: purpose, constraints, success criteria
|
|
105
|
+
## Decision Protocol
|
|
238
106
|
|
|
239
|
-
|
|
240
|
-
- Propose 2-3 different approaches with trade-offs
|
|
241
|
-
- Present options conversationally with your recommendation and reasoning
|
|
242
|
-
- Lead with your recommended option and explain why
|
|
107
|
+
Use the heaviest process the problem actually needs. The protocol scales with decision complexity; it does not assume a giant agent swarm.
|
|
243
108
|
|
|
244
|
-
|
|
245
|
-
- Once you believe you understand what you're building, present the design
|
|
246
|
-
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
|
|
247
|
-
- Ask after each section whether it looks right so far
|
|
248
|
-
- Cover: architecture, components, data flow, error handling, testing
|
|
249
|
-
- Be ready to go back and clarify if something doesn't make sense
|
|
109
|
+
### Multi-Researcher Mode
|
|
250
110
|
|
|
251
|
-
|
|
252
|
-
- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
|
|
253
|
-
- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
|
|
254
|
-
- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
|
|
111
|
+
Use this when the decision is high-impact and the Orchestrator can actually dispatch multiple research passes.
|
|
255
112
|
|
|
256
|
-
**
|
|
257
|
-
-
|
|
258
|
-
|
|
259
|
-
- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
|
|
113
|
+
1. **Independent passes** - gather 2-4 perspectives if available. More is optional, not mandatory.
|
|
114
|
+
2. **Cross-check blind spots** - compare where the perspectives agree, clash, and what each missed.
|
|
115
|
+
3. **Structured verdict** - produce one recommendation with confidence, deciding constraints, rejected alternatives, and first implementation step.
|
|
260
116
|
|
|
261
|
-
|
|
117
|
+
Do not block waiting for an 8-agent protocol. If capacity is limited, reduce the number of perspectives and keep the structure.
|
|
262
118
|
|
|
263
|
-
|
|
264
|
-
- Write the validated design to \`docs/plans/YYYY-MM-DD-<topic>-design.md\`
|
|
265
|
-
- (User preferences for spec location override this default)
|
|
266
|
-
- Use elements-of-style:writing-clearly-and-concisely skill if available
|
|
267
|
-
- Commit the design document to git
|
|
119
|
+
### Single-Agent Fallback
|
|
268
120
|
|
|
269
|
-
|
|
270
|
-
- Invoke the writing-plans skill to create a detailed implementation plan
|
|
271
|
-
- Do NOT invoke any other skill. writing-plans is the next step.
|
|
121
|
+
When running as a single agent (no Orchestrator dispatching multi-model research), use this structured approach:
|
|
272
122
|
|
|
273
|
-
**
|
|
123
|
+
1. **Frame the decision space** - state the question, list constraints, define success criteria
|
|
124
|
+
2. **Generate 3 alternatives** - force diversity by thinking from different lenses:
|
|
125
|
+
- Lens A: Simplest approach (minimum viable, least risk)
|
|
126
|
+
- Lens B: Best long-term approach (might be more work now, pays off later)
|
|
127
|
+
- Lens C: Unconventional approach (different framing, different trade-off)
|
|
128
|
+
3. **Evaluate against criteria** - for each alternative, score against the stated success criteria
|
|
129
|
+
4. **Recommend with rationale** - pick one, explain WHY, acknowledge what you're trading away
|
|
274
130
|
|
|
275
|
-
|
|
131
|
+
This replaces the full Multi-Model Decision Protocol when running solo.
|
|
276
132
|
|
|
277
|
-
|
|
278
|
-
- **Multiple choice preferred** — Easier to answer than open-ended when possible
|
|
279
|
-
- **YAGNI ruthlessly** — Remove unnecessary features from all designs
|
|
280
|
-
- **Explore alternatives** — Always propose 2-3 approaches before settling
|
|
281
|
-
- **Incremental validation** — Present design, get approval before moving on
|
|
282
|
-
- **Be flexible** — Go back and clarify when something doesn't make sense
|
|
133
|
+
### Verdict Format
|
|
283
134
|
|
|
284
|
-
|
|
135
|
+
Express the result in structured text, not diagrams:
|
|
285
136
|
|
|
286
|
-
|
|
137
|
+
| Section | Required content |
|
|
138
|
+
|---------|------------------|
|
|
139
|
+
| Decision | What question is being answered |
|
|
140
|
+
| Constraints | What limited the design space |
|
|
141
|
+
| Options | 3 alternatives with strength, weakness, best-when |
|
|
142
|
+
| Recommendation | Chosen option and why |
|
|
143
|
+
| Rejections | Why the other options lost |
|
|
144
|
+
| Risks | What could fail and how reversible it is |
|
|
145
|
+
| First Step | Smallest useful next move after approval |
|
|
287
146
|
|
|
288
|
-
###
|
|
289
|
-
|
|
290
|
-
Before presenting any design, \`search\` curated knowledge for existing glossary, domain models, and naming conventions. The design must use **canonical terms** from the codebase — not synonyms, not approximations.
|
|
147
|
+
### Large Project Decomposition
|
|
291
148
|
|
|
292
|
-
|
|
293
|
-
- If fuzzy language exists ("handle the thing", "process the data"), sharpen it to precise domain terms
|
|
294
|
-
- Cross-reference proposed interfaces against existing code: do the names, shapes, and flows match what's already there?
|
|
149
|
+
Before asking detailed questions, assess scope. If the request includes multiple independent subsystems, decompose first. Do not brainstorm the whole platform as one blob.
|
|
295
150
|
|
|
296
|
-
|
|
151
|
+
If the project is too large for a single spec, break it into sub-projects, define the order, then brainstorm the first sub-project only.
|
|
297
152
|
|
|
298
|
-
|
|
153
|
+
## Design Quality Signals
|
|
299
154
|
|
|
300
|
-
-
|
|
301
|
-
-
|
|
302
|
-
-
|
|
155
|
+
- **Options are genuinely different** - if they only differ in naming, you have not explored the space.
|
|
156
|
+
- **Trade-offs are real** - if one option dominates on all dimensions, the others are strawmen.
|
|
157
|
+
- **Constraints are explicit** - "we chose X because of Y constraint" is good; "X is better" is lazy.
|
|
158
|
+
- **Reversibility is assessed** - one-way doors need more analysis than two-way doors.
|
|
159
|
+
- **You can explain why NOT the other options** - if you cannot articulate the rejection reason, the analysis is shallow.
|
|
303
160
|
|
|
304
|
-
|
|
161
|
+
## Design Review Checklist
|
|
305
162
|
|
|
306
|
-
|
|
163
|
+
Before presenting the design, verify these quality bars:
|
|
307
164
|
|
|
308
|
-
|
|
165
|
+
- **Completeness** - no TODOs, placeholders, or missing constraints that block planning.
|
|
166
|
+
- **Consistency** - sections do not contradict each other.
|
|
167
|
+
- **Precision** - two competent developers would implement compatible solutions from this spec.
|
|
168
|
+
- **Scope control** - the design solves the asked problem and avoids unrequested extras.
|
|
169
|
+
- **Canonical language** - names and domain terms match the codebase or are explicitly introduced.
|
|
309
170
|
|
|
310
|
-
|
|
171
|
+
Fix serious issues before handoff. Minor wording changes are advisory, not blockers.
|
|
311
172
|
|
|
312
|
-
|
|
313
|
-
- Concrete examples (input → output)
|
|
314
|
-
- Boundary conditions (what happens at 0, 1, MAX?)
|
|
315
|
-
- Error cases (what fails, what's the recovery?)
|
|
173
|
+
## Working Method
|
|
316
174
|
|
|
317
|
-
|
|
175
|
+
- Check current project context before proposing changes.
|
|
176
|
+
- Ask one question per message when clarification is needed.
|
|
177
|
+
- Prefer multiple-choice questions when they reduce ambiguity faster.
|
|
178
|
+
- Separate divergent generation from evaluation.
|
|
179
|
+
- Lead with your recommendation once the option space is explored.
|
|
180
|
+
- Stay concrete: boundaries, interfaces, data flow, failure modes, rollout.
|
|
318
181
|
|
|
319
|
-
|
|
320
|
-
- Note which existing docs/comments are now outdated
|
|
321
|
-
- Include documentation updates as part of the design output (not a separate "docs task")
|
|
322
|
-
- The design doc itself becomes the canonical reference — don't create knowledge that lives only in chat
|
|
182
|
+
## Output Contract
|
|
323
183
|
|
|
324
|
-
|
|
184
|
+
For Simple Mode, produce a concise design note with:
|
|
325
185
|
|
|
326
|
-
|
|
186
|
+
- Goal
|
|
187
|
+
- Constraints
|
|
188
|
+
- 3 options
|
|
189
|
+
- Recommendation
|
|
190
|
+
- Risks and acceptance criteria
|
|
327
191
|
|
|
328
|
-
|
|
329
|
-
> "Some of what we're working on might be easier to explain visually. I can use \`present({ schemaVersion: 1, title: \\"Working Session Visuals\\", blocks: [...] })\` to show mockups, diagrams, comparisons, and other visuals as we go, using \`list\`, \`table\`, \`kv\`, and \`metrics\` blocks as appropriate. I never use \`code\` blocks for structured data. Want me to use that when helpful?"
|
|
192
|
+
For Full Mode, produce a spec that also covers:
|
|
330
193
|
|
|
331
|
-
|
|
194
|
+
- Boundaries and component responsibilities
|
|
195
|
+
- Interfaces and data flow
|
|
196
|
+
- Migration or rollout strategy
|
|
197
|
+
- Error handling and operational risks
|
|
198
|
+
- Test and acceptance strategy
|
|
332
199
|
|
|
333
|
-
|
|
200
|
+
When useful, save the approved design to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` before handing off to implementation planning.
|
|
334
201
|
|
|
335
|
-
- **Use \`present({ schemaVersion: 1, title: "Visual Option", blocks: [...] })\`** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs. Use \`list\` for idea options, \`table\` for side-by-side evaluations, \`kv\` for selected approach metadata, and \`metrics\` for numeric scoring. NEVER \`code\` blocks for structured data.
|
|
336
|
-
- **Use regular chat** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
|
|
337
202
|
`},{file:`spec-document-reviewer-prompt.md`,content:`# Spec Document Reviewer Prompt Template
|
|
338
203
|
|
|
339
204
|
Use this template when dispatching a spec document reviewer subagent.
|