@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 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