@faviovazquez/deliberate 0.1.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/BRAINSTORM.md +300 -0
- package/CHANGELOG.md +26 -0
- package/LICENSE +21 -0
- package/README.md +229 -0
- package/SKILL.md +365 -0
- package/agents/adversarial-strategist.md +96 -0
- package/agents/assumption-breaker.md +93 -0
- package/agents/bias-detector.md +95 -0
- package/agents/classifier.md +92 -0
- package/agents/emergence-reader.md +95 -0
- package/agents/first-principles.md +95 -0
- package/agents/formal-verifier.md +95 -0
- package/agents/incentive-mapper.md +95 -0
- package/agents/inverter.md +95 -0
- package/agents/pragmatic-builder.md +95 -0
- package/agents/reframer.md +95 -0
- package/agents/resilience-anchor.md +95 -0
- package/agents/risk-analyst.md +95 -0
- package/agents/specialists/design-lens.md +96 -0
- package/agents/specialists/ml-intuition.md +96 -0
- package/agents/specialists/safety-frontier.md +96 -0
- package/agents/systems-thinker.md +95 -0
- package/bin/cli.js +69 -0
- package/configs/defaults.yaml +54 -0
- package/configs/provider-model-slots.example.yaml +88 -0
- package/install.sh +210 -0
- package/package.json +54 -0
- package/scripts/detect-platform.sh +70 -0
- package/scripts/frame-template.html +517 -0
- package/scripts/helper.js +339 -0
- package/scripts/release.sh +131 -0
- package/scripts/start-server.sh +274 -0
- package/scripts/stop-server.sh +42 -0
- package/templates/brainstorm-output.md +60 -0
- package/templates/deliberation-output.md +64 -0
package/BRAINSTORM.md
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deliberate-brainstorm
|
|
3
|
+
description: "Multi-agent brainstorming with visual companion. Generates diverse ideas through independent agent perspectives, cross-pollinates, and converges on actionable designs. Use when exploring new features, redesigns, or creative solutions. Invoke with /deliberate --brainstorm."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# deliberate --brainstorm -- Multi-Agent Brainstorming Protocol
|
|
7
|
+
|
|
8
|
+
Brainstorm mode is not a stripped-down deliberation. It's a separate process optimized for creative exploration, where multiple agents independently generate, challenge, and refine ideas before converging on actionable designs.
|
|
9
|
+
|
|
10
|
+
## Invocation
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
/deliberate --brainstorm "how should we redesign the onboarding flow?"
|
|
14
|
+
/deliberate --brainstorm --members assumption-breaker,reframer,pragmatic-builder "new pricing model"
|
|
15
|
+
/deliberate --brainstorm --triad product "what features should v2 include?"
|
|
16
|
+
/deliberate --brainstorm --visual "landing page redesign"
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## HARD GATE
|
|
20
|
+
|
|
21
|
+
**No implementation until the user approves the design.**
|
|
22
|
+
|
|
23
|
+
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until the brainstorm has produced a design and the user has explicitly approved it. This gate is non-negotiable. The brainstorm exists to prevent premature implementation.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Process Flow
|
|
28
|
+
|
|
29
|
+
### Phase 1: Context Exploration
|
|
30
|
+
|
|
31
|
+
Read the relevant context before asking any questions:
|
|
32
|
+
- Project files (AGENTS.md, .planning/, relevant source code)
|
|
33
|
+
- Domain context mentioned by the user
|
|
34
|
+
- Previous deliberation records in `deliberations/` if they exist
|
|
35
|
+
|
|
36
|
+
Produce a brief context summary (3-5 sentences) so the user can confirm you understand the space.
|
|
37
|
+
|
|
38
|
+
### Phase 2: Visual Companion Offer
|
|
39
|
+
|
|
40
|
+
If this brainstorm is likely to involve visual content (UI, architecture diagrams, mockups, design comparisons), offer the visual companion:
|
|
41
|
+
|
|
42
|
+
> "Some of what we're working on might be easier to show than describe. I can put together mockups, diagrams, comparisons, and other visuals in a browser as we go. Want to try it? (Requires opening a local URL)"
|
|
43
|
+
|
|
44
|
+
**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. Wait for the user's response before continuing.
|
|
45
|
+
|
|
46
|
+
If they accept, launch the visual companion:
|
|
47
|
+
```bash
|
|
48
|
+
scripts/start-server.sh --project-dir {project_root}
|
|
49
|
+
```
|
|
50
|
+
Save `screen_dir` and `state_dir`. Tell user to open the URL.
|
|
51
|
+
|
|
52
|
+
If they decline, proceed with text-only brainstorming.
|
|
53
|
+
|
|
54
|
+
### Phase 3: Clarifying Questions
|
|
55
|
+
|
|
56
|
+
Ask 3-5 targeted questions to understand scope, constraints, and desired outcome:
|
|
57
|
+
|
|
58
|
+
- **One question at a time.** Do not overwhelm with multiple questions.
|
|
59
|
+
- **Multiple choice preferred.** Easier to answer than open-ended when possible.
|
|
60
|
+
- **YAGNI ruthlessly.** Remove unnecessary scope from all designs.
|
|
61
|
+
- **Be flexible.** Go back and clarify when something doesn't make sense.
|
|
62
|
+
|
|
63
|
+
Each question should narrow the design space. Stop asking when you have enough to propose approaches.
|
|
64
|
+
|
|
65
|
+
### Phase 4: Agent Selection
|
|
66
|
+
|
|
67
|
+
Based on the domain and clarified scope, select 3-5 agents:
|
|
68
|
+
|
|
69
|
+
- **Auto-selection**: Match domain keywords from the user's question against agent `duo_keywords` in frontmatter. Select the best-matching triad plus 1-2 agents from polarity pairs for productive tension.
|
|
70
|
+
- **Manual override**: User can specify `--members` to pick any agents.
|
|
71
|
+
- **Always include at least one polarity pair** in the selection to guarantee disagreement.
|
|
72
|
+
|
|
73
|
+
Announce the selected agents and their functions to the user:
|
|
74
|
+
```
|
|
75
|
+
For this brainstorm, I'm bringing in:
|
|
76
|
+
- pragmatic-builder (will ground ideas in shipping reality)
|
|
77
|
+
- reframer (will challenge whether we're solving the right problem)
|
|
78
|
+
- incentive-mapper (will assess how users actually behave)
|
|
79
|
+
- design-lens (will evaluate from the user's perspective)
|
|
80
|
+
|
|
81
|
+
These agents will generate ideas independently, then challenge and build on each other's work.
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Phase 5: Divergent Phase
|
|
85
|
+
|
|
86
|
+
Each selected agent independently generates 2-3 ideas or approaches. The prompt for each agent:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
## Your Role
|
|
90
|
+
You are {agent_name}. Read your full agent definition at agents/{agent_name}.md.
|
|
91
|
+
|
|
92
|
+
## Brainstorm Topic
|
|
93
|
+
{User's question + clarified scope from Phase 3}
|
|
94
|
+
|
|
95
|
+
## Instructions
|
|
96
|
+
Generate 2-3 distinct ideas or approaches for this topic.
|
|
97
|
+
Each idea should:
|
|
98
|
+
- Have a clear one-line title
|
|
99
|
+
- Have a 2-3 sentence description of how it works
|
|
100
|
+
- Include one "why this might be the right approach" statement
|
|
101
|
+
- Include one "what could go wrong" statement
|
|
102
|
+
|
|
103
|
+
Apply your specific analytical method. Your ideas should reflect your unique function.
|
|
104
|
+
200 words maximum per idea.
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
**Visual companion**: If active, push an idea map to the browser showing each agent's ideas as colored nodes in a force-directed layout. Each node shows the idea title; clicking reveals the full description.
|
|
108
|
+
|
|
109
|
+
### Phase 6: Cross-Pollination
|
|
110
|
+
|
|
111
|
+
Each agent reviews ALL other agents' ideas and responds:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
## Your Role
|
|
115
|
+
You are {agent_name}.
|
|
116
|
+
|
|
117
|
+
## All Ideas Generated
|
|
118
|
+
{All ideas from Phase 5, attributed to their source agent}
|
|
119
|
+
|
|
120
|
+
## Instructions
|
|
121
|
+
For each other agent's ideas:
|
|
122
|
+
1. Pick the ONE idea from another agent that you find most promising. Explain what makes it strong from your perspective.
|
|
123
|
+
2. Pick the ONE idea from another agent that concerns you most. Explain the risk from your perspective.
|
|
124
|
+
3. Propose ONE hybrid: combine elements from 2+ agents' ideas into something none of them proposed alone.
|
|
125
|
+
|
|
126
|
+
150 words maximum per response.
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**Visual companion**: Update the idea map with connections between nodes. Green edges for "builds on," red edges for "challenges," blue edges for hybrid connections.
|
|
130
|
+
|
|
131
|
+
### Phase 7: Convergence
|
|
132
|
+
|
|
133
|
+
The coordinator synthesizes cross-pollination results and identifies the top 2-3 directions:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
## Convergence Summary
|
|
137
|
+
|
|
138
|
+
### Direction A: {title}
|
|
139
|
+
Supported by: {agent names}
|
|
140
|
+
Core idea: {description}
|
|
141
|
+
Key concern: {the main risk raised during cross-pollination}
|
|
142
|
+
|
|
143
|
+
### Direction B: {title}
|
|
144
|
+
Supported by: {agent names}
|
|
145
|
+
Core idea: {description}
|
|
146
|
+
Key concern: {the main risk raised during cross-pollination}
|
|
147
|
+
|
|
148
|
+
### Direction C: {title} (if applicable)
|
|
149
|
+
...
|
|
150
|
+
|
|
151
|
+
Which direction should we develop into a full design?
|
|
152
|
+
Or should we combine elements from multiple directions?
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
**Visual companion**: Push a convergence view showing the top directions as large nodes with supporting agents clustered around them. Clickable to see full reasoning.
|
|
156
|
+
|
|
157
|
+
Present this to the user and wait for their choice.
|
|
158
|
+
|
|
159
|
+
### Phase 8: Design Presentation
|
|
160
|
+
|
|
161
|
+
Once the user selects a direction, develop it into a full design. Present the design in sections, waiting for approval on each before moving to the next:
|
|
162
|
+
|
|
163
|
+
1. **Overview**: What we're building and why (2-3 sentences)
|
|
164
|
+
2. **Architecture/Structure**: How the pieces fit together
|
|
165
|
+
3. **Key Decisions**: The important choices in this design and why we made them
|
|
166
|
+
4. **What We're NOT Building**: Explicit scope boundaries (YAGNI)
|
|
167
|
+
5. **Risks and Mitigations**: What could go wrong and how we handle it
|
|
168
|
+
6. **Agent Attribution**: Which agent contributed which design decision
|
|
169
|
+
|
|
170
|
+
Present each section separately. Get user feedback before moving to the next. If the user wants changes, revise before proceeding.
|
|
171
|
+
|
|
172
|
+
**Visual companion**: For visual designs (UI, architecture), push mockups/diagrams to the browser using the visual companion CSS classes (options, cards, split views, mockups).
|
|
173
|
+
|
|
174
|
+
### Phase 9: Design Document
|
|
175
|
+
|
|
176
|
+
Once all sections are approved, compile the full design into a single document:
|
|
177
|
+
|
|
178
|
+
```markdown
|
|
179
|
+
## Brainstorm Design: {title}
|
|
180
|
+
|
|
181
|
+
### Overview
|
|
182
|
+
{Approved overview}
|
|
183
|
+
|
|
184
|
+
### Architecture
|
|
185
|
+
{Approved architecture}
|
|
186
|
+
|
|
187
|
+
### Key Decisions
|
|
188
|
+
{Approved decisions with rationale}
|
|
189
|
+
|
|
190
|
+
### Scope Boundaries
|
|
191
|
+
{What we're NOT building}
|
|
192
|
+
|
|
193
|
+
### Risks
|
|
194
|
+
{Identified risks and mitigations}
|
|
195
|
+
|
|
196
|
+
### Agent Attribution
|
|
197
|
+
{Which agents contributed which ideas}
|
|
198
|
+
|
|
199
|
+
### Brainstorm Metadata
|
|
200
|
+
- Date: {YYYY-MM-DD}
|
|
201
|
+
- Agents: {list}
|
|
202
|
+
- Phases completed: {list}
|
|
203
|
+
- Visual companion: {yes/no}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Save to `deliberations/brainstorm-YYYY-MM-DD-HH-MM-{slug}.md`.
|
|
207
|
+
|
|
208
|
+
### Phase 10: Self-Review
|
|
209
|
+
|
|
210
|
+
Before presenting the final design to the user, run a quick self-review:
|
|
211
|
+
|
|
212
|
+
- Does the design address the original question?
|
|
213
|
+
- Does it respect the scope boundaries established in Phase 3?
|
|
214
|
+
- Are there any internal contradictions?
|
|
215
|
+
- Would `pragmatic-builder` say this is over-engineered?
|
|
216
|
+
- Would `assumption-breaker` find hidden premises?
|
|
217
|
+
|
|
218
|
+
If any issues surface, revise and note the revision.
|
|
219
|
+
|
|
220
|
+
### Phase 11: User Approval (HARD GATE)
|
|
221
|
+
|
|
222
|
+
Present the complete design document to the user.
|
|
223
|
+
|
|
224
|
+
```
|
|
225
|
+
Here's the complete design from this brainstorm session.
|
|
226
|
+
[Design document]
|
|
227
|
+
|
|
228
|
+
Does this look right? I won't write any code until you approve.
|
|
229
|
+
If you want changes, tell me what to adjust.
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
**Only proceed to implementation after explicit user approval.**
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Visual Companion in Brainstorm Mode
|
|
237
|
+
|
|
238
|
+
### Per-question decision rule
|
|
239
|
+
|
|
240
|
+
Even after the user accepts the visual companion, decide FOR EACH STEP whether to use browser or terminal:
|
|
241
|
+
|
|
242
|
+
**Use the browser when the content IS visual:**
|
|
243
|
+
- Idea maps showing agent positions and connections
|
|
244
|
+
- Architecture diagrams for proposed designs
|
|
245
|
+
- UI mockups and wireframes
|
|
246
|
+
- Side-by-side design comparisons
|
|
247
|
+
- Convergence visualizations
|
|
248
|
+
|
|
249
|
+
**Use the terminal when the content is text:**
|
|
250
|
+
- Clarifying questions (Phase 3)
|
|
251
|
+
- Scope decisions
|
|
252
|
+
- Conceptual A/B/C choices described in words
|
|
253
|
+
- Risk discussions
|
|
254
|
+
- Tradeoff lists
|
|
255
|
+
|
|
256
|
+
A question about a visual topic is not automatically a visual question. "What kind of dashboard do you want?" is conceptual (terminal). "Which of these dashboard layouts works better?" is visual (browser).
|
|
257
|
+
|
|
258
|
+
### Brainstorm-specific views
|
|
259
|
+
|
|
260
|
+
These views supplement the standard visual companion CSS classes:
|
|
261
|
+
|
|
262
|
+
1. **Idea Map** (Phase 5): Force-directed graph. Agents as colored circles. Ideas as smaller nodes connected to their source agent. Node size proportional to support from other agents.
|
|
263
|
+
|
|
264
|
+
2. **Cross-Pollination Map** (Phase 6): Same layout as idea map, with edges added:
|
|
265
|
+
- Green edges: "builds on" connections
|
|
266
|
+
- Red edges: "challenges" connections
|
|
267
|
+
- Blue dashed edges: hybrid proposals
|
|
268
|
+
|
|
269
|
+
3. **Convergence View** (Phase 7): Top directions as large nodes. Supporting agents clustered. Concerns shown as red annotations.
|
|
270
|
+
|
|
271
|
+
4. **Design Sections** (Phase 8): Standard mockup/wireframe views using the visual companion CSS classes (options, cards, split views, mockups, pros/cons).
|
|
272
|
+
|
|
273
|
+
### Writing visual content
|
|
274
|
+
|
|
275
|
+
Write HTML fragments to `screen_dir/`. The server wraps them in the frame template automatically.
|
|
276
|
+
|
|
277
|
+
```html
|
|
278
|
+
<h2>Brainstorm: Idea Map</h2>
|
|
279
|
+
<p class="subtitle">4 agents generated 11 ideas. Click any idea to see details.</p>
|
|
280
|
+
<canvas id="idea-map" width="800" height="600"></canvas>
|
|
281
|
+
<script>
|
|
282
|
+
// Force-directed graph rendering
|
|
283
|
+
// Agent colors, idea nodes, connection edges
|
|
284
|
+
</script>
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
For Canvas 2D visualizations (idea maps, agreement matrices), include the rendering script inline in the HTML fragment. The frame template provides the CSS theme; the visualization logic is self-contained.
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## Key Principles
|
|
292
|
+
|
|
293
|
+
- **One question at a time**: Don't overwhelm with multiple questions
|
|
294
|
+
- **Multiple choice preferred**: Easier to answer than open-ended
|
|
295
|
+
- **YAGNI ruthlessly**: Remove unnecessary features from all designs
|
|
296
|
+
- **Explore alternatives**: Always propose 2-3 approaches before settling
|
|
297
|
+
- **Incremental validation**: Present design, get approval before moving on
|
|
298
|
+
- **Be flexible**: Go back and clarify when something doesn't make sense
|
|
299
|
+
- **Agent diversity**: Always include at least one polarity pair for productive tension
|
|
300
|
+
- **Design before code**: The HARD GATE is non-negotiable
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.1.0] - 2025-04-03
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- 14 core agents with functional names: assumption-breaker, first-principles, classifier, formal-verifier, bias-detector, systems-thinker, resilience-anchor, adversarial-strategist, emergence-reader, incentive-mapper, pragmatic-builder, reframer, risk-analyst, inverter
|
|
12
|
+
- 3 optional specialist agents: ml-intuition, safety-frontier, design-lens
|
|
13
|
+
- SKILL.md coordinator protocol with 4 modes: Full (3 rounds), Quick (2 rounds), Duo (dialectic), Brainstorm
|
|
14
|
+
- BRAINSTORM.md sub-skill with 11-phase creative exploration flow
|
|
15
|
+
- 18 pre-defined triads for domain-optimized deliberation
|
|
16
|
+
- 4 profiles: full, lean, exploration, execution
|
|
17
|
+
- Polarity pairs for structural disagreement
|
|
18
|
+
- Enforcement rules: hemlock rule, 3-level depth limit, 2-message cutoff, dissent quota, novelty gate, groupthink flag
|
|
19
|
+
- Visual companion: HTML+JS+Canvas 2D browser interface with force-directed graphs, agent position maps, agreement matrices
|
|
20
|
+
- File-watcher server (Node.js) with auto-refresh, JSONL event capture, 30-min auto-shutdown
|
|
21
|
+
- Frame template with dark theme CSS: options, cards, split views, mockups, pros/cons, agent badges, verdict styling
|
|
22
|
+
- Platform support: Claude Code (parallel subagents), Windsurf (sequential), Cursor (sequential)
|
|
23
|
+
- Platform-aware installer with auto-detection, global/workspace scope
|
|
24
|
+
- `npx @faviovazquez/deliberate` universal installer
|
|
25
|
+
- Model tier configs for Anthropic (claude-sonnet-4.6), OpenAI (gpt-5.4), Google (gemini-2.5-pro/flash), Ollama (qwen3-coder)
|
|
26
|
+
- Output templates for deliberation and brainstorm records saved to deliberations/
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Favio Vazquez
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# deliberate
|
|
2
|
+
|
|
3
|
+
**Agreement is a bug.**
|
|
4
|
+
|
|
5
|
+
A multi-agent deliberation and brainstorming skill for AI coding assistants. Forces multiple agents to disagree before they agree, surfacing blind spots that single-perspective answers hide.
|
|
6
|
+
|
|
7
|
+
## The Problem
|
|
8
|
+
|
|
9
|
+
AI chatbots are sycophantic. They validate your claims, confirm your hypotheses, and produce polished answers that sound balanced but come from a single reasoning tradition. Research shows this leads to "delusional spiraling" where even rational users develop dangerously confident beliefs after prolonged conversations ([Chandra et al., 2025](https://arxiv.org/abs/2602.19141)).
|
|
10
|
+
|
|
11
|
+
A single LLM produces one coherent viewpoint per generation. It simulates balance. It does not achieve genuine adversarial deliberation.
|
|
12
|
+
|
|
13
|
+
## The Solution
|
|
14
|
+
|
|
15
|
+
`deliberate` externalizes the disagreement layer. Instead of asking one agent for a balanced answer, it spawns multiple agents with distinct analytical methods, explicit blind spots, and structural counterweights. They analyze independently, cross-examine each other, and produce a verdict that shows you where they agree, where they disagree, and why.
|
|
16
|
+
|
|
17
|
+
The disagreements are the point. A single model averages opposing views into one confident recommendation. `deliberate` keeps them separate so you can decide.
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npx @faviovazquez/deliberate
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
This auto-detects your platform (Claude Code, Windsurf, Cursor) and installs the skill to the current workspace. Then open your AI assistant and try:
|
|
26
|
+
|
|
27
|
+
**Claude Code:**
|
|
28
|
+
```
|
|
29
|
+
/deliberate "should we migrate from REST to GraphQL?"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**Windsurf / Cursor:**
|
|
33
|
+
```
|
|
34
|
+
@deliberate should we migrate from REST to GraphQL?
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Windsurf also auto-invokes the skill when your question matches the skill description.
|
|
38
|
+
|
|
39
|
+
### Manual Installation
|
|
40
|
+
|
|
41
|
+
**Claude Code (workspace):**
|
|
42
|
+
```bash
|
|
43
|
+
git clone https://github.com/FavioVazquez/deliberate.git
|
|
44
|
+
cd deliberate
|
|
45
|
+
./install.sh --platform claude-code
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Claude Code (global -- all projects):**
|
|
49
|
+
```bash
|
|
50
|
+
./install.sh --platform claude-code --global
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**Windsurf (workspace -- into .windsurf/skills/):**
|
|
54
|
+
```bash
|
|
55
|
+
git clone https://github.com/FavioVazquez/deliberate.git
|
|
56
|
+
cd deliberate
|
|
57
|
+
./install.sh --platform windsurf
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**Windsurf (global -- into ~/.codeium/windsurf/skills/):**
|
|
61
|
+
```bash
|
|
62
|
+
./install.sh --platform windsurf --global
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Modes
|
|
66
|
+
|
|
67
|
+
### Full Deliberation (3 rounds)
|
|
68
|
+
```
|
|
69
|
+
/deliberate --full "is this acquisition worth pursuing at 8x revenue?"
|
|
70
|
+
```
|
|
71
|
+
All 14 agents. Round 1: independent analysis. Round 2: cross-examination (must disagree). Round 3: crystallization. Produces a structured verdict with minority report.
|
|
72
|
+
|
|
73
|
+
### Quick Deliberation (2 rounds)
|
|
74
|
+
```
|
|
75
|
+
/deliberate --quick "monorepo or polyrepo?"
|
|
76
|
+
```
|
|
77
|
+
Auto-selected triad. Rounds 1 + 3 only (skip cross-examination). Faster, cheaper.
|
|
78
|
+
|
|
79
|
+
### Triad (domain-optimized)
|
|
80
|
+
```
|
|
81
|
+
/deliberate --triad architecture "should we split the monolith?"
|
|
82
|
+
/deliberate --triad decision "build vs buy for notifications"
|
|
83
|
+
/deliberate --triad risk "should we launch before the audit?"
|
|
84
|
+
```
|
|
85
|
+
3 agents selected for the domain. 18 pre-defined triads available.
|
|
86
|
+
|
|
87
|
+
### Duo / Dialectic
|
|
88
|
+
```
|
|
89
|
+
/deliberate --duo assumption-breaker,pragmatic-builder "rewrite the auth layer?"
|
|
90
|
+
```
|
|
91
|
+
Two agents, two rounds of exchange, then synthesis. Best for binary decisions.
|
|
92
|
+
|
|
93
|
+
### Brainstorm
|
|
94
|
+
```
|
|
95
|
+
/deliberate --brainstorm "how should we redesign onboarding?"
|
|
96
|
+
/deliberate --brainstorm --visual "landing page redesign"
|
|
97
|
+
```
|
|
98
|
+
Creative exploration with multiple agents. Divergent ideas, cross-pollination, convergence into actionable designs. Optional visual companion with interactive idea maps.
|
|
99
|
+
|
|
100
|
+
### Auto-Detect (no flag)
|
|
101
|
+
```
|
|
102
|
+
/deliberate "should we migrate from REST to GraphQL?"
|
|
103
|
+
```
|
|
104
|
+
Parses your question, selects the best-matching triad, runs 3-round protocol.
|
|
105
|
+
|
|
106
|
+
## The 14 Core Agents
|
|
107
|
+
|
|
108
|
+
| Agent | Function |
|
|
109
|
+
|-------|----------|
|
|
110
|
+
| `assumption-breaker` | Destroys hidden premises, tests by contradiction |
|
|
111
|
+
| `first-principles` | Bottom-up derivation, refuses unexplained complexity |
|
|
112
|
+
| `classifier` | Taxonomic structure, category errors, four-cause analysis |
|
|
113
|
+
| `formal-verifier` | Computational skeleton, mechanization boundaries |
|
|
114
|
+
| `bias-detector` | Cognitive bias detection, pre-mortem, de-biasing |
|
|
115
|
+
| `systems-thinker` | Feedback loops, leverage points, unintended consequences |
|
|
116
|
+
| `resilience-anchor` | Control vs acceptance, moral clarity, anti-panic |
|
|
117
|
+
| `adversarial-strategist` | Terrain reading, competitive dynamics, strategic timing |
|
|
118
|
+
| `emergence-reader` | Non-action, subtraction, minimum intervention |
|
|
119
|
+
| `incentive-mapper` | Power dynamics, actor incentives, how people actually behave |
|
|
120
|
+
| `pragmatic-builder` | Ship it, maintenance cost, over-engineering detection |
|
|
121
|
+
| `reframer` | Dissolves false problems, frame audit, perspective shift |
|
|
122
|
+
| `risk-analyst` | Antifragility, tail risk, fragility profile |
|
|
123
|
+
| `inverter` | Multi-model reasoning, inversion ("what guarantees failure?") |
|
|
124
|
+
|
|
125
|
+
Plus 3 **optional specialists** activated for domain-specific triads: `ml-intuition` (AI/ML), `safety-frontier` (AI safety), `design-lens` (UX/design).
|
|
126
|
+
|
|
127
|
+
Agents are named by their function, not by historical figures. Each agent declares its analytical method, what it sees that others miss, and what it tends to miss. These declared blind spots are why the polarity pairs matter.
|
|
128
|
+
|
|
129
|
+
## 18 Pre-defined Triads
|
|
130
|
+
|
|
131
|
+
| Domain | Agents |
|
|
132
|
+
|--------|--------|
|
|
133
|
+
| architecture | classifier + formal-verifier + first-principles |
|
|
134
|
+
| strategy | adversarial-strategist + incentive-mapper + resilience-anchor |
|
|
135
|
+
| ethics | resilience-anchor + assumption-breaker + emergence-reader |
|
|
136
|
+
| debugging | first-principles + assumption-breaker + formal-verifier |
|
|
137
|
+
| innovation | formal-verifier + emergence-reader + classifier |
|
|
138
|
+
| conflict | assumption-breaker + incentive-mapper + resilience-anchor |
|
|
139
|
+
| complexity | emergence-reader + classifier + formal-verifier |
|
|
140
|
+
| risk | adversarial-strategist + resilience-anchor + first-principles |
|
|
141
|
+
| shipping | pragmatic-builder + adversarial-strategist + first-principles |
|
|
142
|
+
| product | pragmatic-builder + incentive-mapper + reframer |
|
|
143
|
+
| decision | inverter + bias-detector + risk-analyst |
|
|
144
|
+
| systems | systems-thinker + emergence-reader + classifier |
|
|
145
|
+
| economics | adversarial-strategist + inverter + incentive-mapper |
|
|
146
|
+
| uncertainty | risk-analyst + adversarial-strategist + assumption-breaker |
|
|
147
|
+
| bias | bias-detector + reframer + assumption-breaker |
|
|
148
|
+
| ai | formal-verifier + ml-intuition + safety-frontier |
|
|
149
|
+
| ai-product | pragmatic-builder + ml-intuition + design-lens |
|
|
150
|
+
| design | design-lens + reframer + pragmatic-builder |
|
|
151
|
+
|
|
152
|
+
## Visual Companion
|
|
153
|
+
|
|
154
|
+
The visual companion is a browser-based interface that shows deliberation progress in real time. Launch it with `--visual`:
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
/deliberate --visual --full "major architecture decision"
|
|
158
|
+
/deliberate --brainstorm --visual "redesign the dashboard"
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
It provides:
|
|
162
|
+
- **Agent Position Map**: Force-directed graph showing agents as colored nodes positioned by agreement/disagreement
|
|
163
|
+
- **Agreement Matrix**: Heatmap of which agents agree/disagree on which points
|
|
164
|
+
- **Idea Evolution Timeline** (brainstorm): How ideas appeared, forked, merged across phases
|
|
165
|
+
- **Verdict Formation** (deliberation): Step-by-step visualization of how the verdict emerged
|
|
166
|
+
- **Minority Report Panel**: Highlighted dissenting positions
|
|
167
|
+
|
|
168
|
+
Built with plain HTML + JS + Canvas 2D. No framework, no build step. Served locally via a lightweight Node.js file-watcher server.
|
|
169
|
+
|
|
170
|
+
## Platforms
|
|
171
|
+
|
|
172
|
+
| Platform | Execution Model | Default Profile | Invocation | Install Paths |
|
|
173
|
+
|----------|----------------|-----------------|------------|---------------|
|
|
174
|
+
| Claude Code | Parallel subagents (`context: fork`) | full (14 agents) | `/deliberate` | `~/.claude/skills/` (global), `.claude/skills/` (workspace) |
|
|
175
|
+
| Windsurf | Sequential role-prompting | lean (5 agents) | `@deliberate` or auto | `~/.codeium/windsurf/skills/` (global), `.windsurf/skills/` (workspace) |
|
|
176
|
+
| Cursor | Sequential role-prompting | lean (5 agents) | `@deliberate` or auto | `.cursor/skills/` (workspace) |
|
|
177
|
+
|
|
178
|
+
### How it works on each platform
|
|
179
|
+
|
|
180
|
+
**Claude Code**: Each agent runs as a parallel subagent with its own isolated context window. The coordinator dispatches all agents simultaneously in Round 1 and Round 3, and sequentially in Round 2 (cross-examination). Agents are installed as separate `.md` files in `~/.claude/agents/` and referenced by the skill.
|
|
181
|
+
|
|
182
|
+
**Windsurf / Cursor**: No subagent support. The coordinator adopts each agent's persona sequentially within a single context window. Agent definitions are bundled inside the skill directory and read on demand. The default "lean" profile (5 agents) keeps context usage manageable while still providing genuine multi-perspective deliberation.
|
|
183
|
+
|
|
184
|
+
**Cross-platform compatibility**: Windsurf discovers skills in `.claude/skills/` if Claude Code config reading is enabled. The agent `.md` files use a superset YAML frontmatter that both platforms handle gracefully (unknown fields are ignored).
|
|
185
|
+
|
|
186
|
+
## Configuration
|
|
187
|
+
|
|
188
|
+
### Model tiers
|
|
189
|
+
All agents use sonnet-equivalent models by default. To enable higher-tier models:
|
|
190
|
+
|
|
191
|
+
```yaml
|
|
192
|
+
# In your project's config.yaml:
|
|
193
|
+
model_tier: high
|
|
194
|
+
# WARNING: high-tier models consume significantly more tokens/credits
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### Custom model routing
|
|
198
|
+
Copy `configs/provider-model-slots.example.yaml` to `configs/provider-model-slots.yaml` and customize per-agent model assignments.
|
|
199
|
+
|
|
200
|
+
### Output
|
|
201
|
+
All deliberation and brainstorm records are saved to `deliberations/` in your project root.
|
|
202
|
+
|
|
203
|
+
## When to Use
|
|
204
|
+
|
|
205
|
+
**Use `/deliberate` for** complex decisions where trade-offs are real: architecture choices, strategic pivots, build-vs-buy, pricing models, any situation where you suspect a single confident answer hides real trade-offs.
|
|
206
|
+
|
|
207
|
+
**Don't use `/deliberate` for** questions with clear correct answers. Don't convene 14 agents to debate tabs vs spaces.
|
|
208
|
+
|
|
209
|
+
**The sweet spot:** Decisions where you already have an opinion but suspect you're missing something.
|
|
210
|
+
|
|
211
|
+
## Enforcement
|
|
212
|
+
|
|
213
|
+
The protocol includes safeguards against common failure modes:
|
|
214
|
+
- **Hemlock rule**: Prevents infinite questioning spirals
|
|
215
|
+
- **3-level depth limit**: Forces position commitment after 3 rounds of questioning
|
|
216
|
+
- **2-message cutoff**: Prevents any pair from dominating the discussion
|
|
217
|
+
- **Dissent quota**: At least 30% of agents must disagree in Round 2
|
|
218
|
+
- **Novelty gate**: Round 2 must introduce new ideas
|
|
219
|
+
- **Groupthink flag**: Unanimous agreement triggers explicit warning
|
|
220
|
+
|
|
221
|
+
## References
|
|
222
|
+
|
|
223
|
+
- **Chandra, Y., Mishra, C., & Flynn, B.** (2025). *Can AIeli-bots turn us all delusional? How AI sycophancy, AI psychosis, and human self-correction interact.* arXiv:2602.19141. [Paper](https://arxiv.org/abs/2602.19141) — The formal model of sycophancy-induced delusional spiraling that motivated this project. Shows how even rational users develop dangerously confident beliefs after prolonged conversations with agreeable AI.
|
|
224
|
+
- **Council of High Intelligence** — [github.com/0xNyk/council-of-high-intelligence](https://github.com/0xNyk/council-of-high-intelligence) — The original multi-agent deliberation system for Claude Code. 18 agents modeled on historical thinkers with polarity pairs, triads, and a 3-round protocol. `deliberate` redesigns the agent roster around analytical functions rather than personas, adds enforcement rules, and extends to multiple platforms.
|
|
225
|
+
- **Superpowers Brainstorming Skill** — [github.com/obra/superpowers](https://github.com/obra/superpowers) — The brainstorming skill and browser-based visual companion architecture. `deliberate` adapts the file-watcher server pattern and CSS frame template approach for deliberation-specific visualizations (agent position maps, agreement matrices, idea evolution).
|
|
226
|
+
|
|
227
|
+
## License
|
|
228
|
+
|
|
229
|
+
MIT
|