@faviovazquez/deliberate 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +466 -94
  3. package/bin/cli.js +358 -45
  4. package/package.json +1 -1
  5. package/scripts/release.sh +0 -131
package/CHANGELOG.md CHANGED
@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.2.1] - 2025-04-03
9
+
10
+ ### Added
11
+ - 7 Gemini-generated images for the README (banner, sycophancy diagram, modes overview, agents wheel, triad map, enforcement rules, verdict output)
12
+ - Expanded "The Problem" section with deep sycophancy analysis: confirmation bias amplification, delusional spiraling, simulated balance, hidden trade-offs, context collapse
13
+ - "What deliberate brings to the table" section explaining structural disagreement, forced dissent, minority report, cross-examination, transparent verdicts
14
+ - Images embedded throughout README at relevant sections
15
+
16
+ ## [0.2.0] - 2025-04-03
17
+
18
+ ### Changed
19
+ - Rewrote installer as pure Node.js (no bash dependency required)
20
+ - Blue ASCII "DELIBERATE" banner with professional CLI styling
21
+ - Interactive prompts: platform selection with auto-detection, global/local scope choice
22
+ - Clean ✓ checkmark output with colored status lines
23
+ - Platform flags: --claude, --windsurf, --cursor, --all
24
+ - Scope flags: --global/-g, --local/-l
25
+ - Added --dry-run preview, --uninstall support
26
+ - Moved release.sh to repo root (dev-only, excluded from npm package)
27
+
8
28
  ## [0.1.0] - 2025-04-03
9
29
 
10
30
  ### Added
package/README.md CHANGED
@@ -1,163 +1,408 @@
1
+ <p align="center">
2
+ <img src="assets/banner.png" alt="deliberate — Agreement is a bug" width="100%" />
3
+ </p>
4
+
1
5
  # deliberate
2
6
 
3
7
  **Agreement is a bug.**
4
8
 
5
9
  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
10
 
7
- ## The Problem
11
+ ## The Problem: AI Sycophancy
12
+
13
+ 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.
14
+
15
+ This is not a minor UX inconvenience. It is a structural failure mode:
8
16
 
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)).
17
+ - **Confirmation bias amplification**: LLMs agree with the user's framing by default. If you ask "should we use microservices?", the model builds a case for microservices. If you ask "should we stay monolithic?", the same model builds an equally confident case for monoliths. The answer follows the framing, not the evidence.
18
+ - **Delusional spiraling**: [Chandra et al. (2025)](https://arxiv.org/abs/2602.19141) formalized how prolonged conversations with agreeable AI lead to "sycophancy-induced delusional spiraling" — users develop dangerously confident beliefs because the AI never pushes back. Their model shows that even initially rational users converge toward overconfidence when the AI consistently validates.
19
+ - **Simulated balance**: A single LLM generates one coherent viewpoint per response. When asked for "both sides," it produces a paragraph for each — but both paragraphs come from the same reasoning tradition, the same training distribution, the same latent biases. It simulates balance without achieving genuine adversarial analysis.
20
+ - **Hidden trade-offs**: Complex decisions involve real trade-offs where the correct answer depends on which values you weight. A single model flattens these into one recommendation, hiding the tensions that should be visible to the decision-maker.
21
+ - **Context collapse**: In long conversations, the AI anchors on earlier positions. By session 5, you're in an echo chamber of your own assumptions, reinforced by an eager assistant.
10
22
 
11
- A single LLM produces one coherent viewpoint per generation. It simulates balance. It does not achieve genuine adversarial deliberation.
23
+ The research is clear: a single AI perspective is structurally insufficient for complex decisions.
24
+
25
+ <p align="center">
26
+ <img src="assets/sycophancy.png" alt="The Sycophancy Problem — Single AI vs Multi-Agent Deliberation" width="100%" />
27
+ </p>
12
28
 
13
29
  ## The Solution
14
30
 
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.
31
+ `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
32
 
17
33
  The disagreements are the point. A single model averages opposing views into one confident recommendation. `deliberate` keeps them separate so you can decide.
18
34
 
35
+ **What deliberate brings to the table:**
36
+
37
+ - **Structural disagreement, not simulated balance**: Each agent has a declared analytical method and declared blind spots. The polarity pairs (e.g., `pragmatic-builder` vs `reframer`: "ship it" vs "does it even need to exist?") guarantee genuine tension.
38
+ - **Forced dissent**: The protocol requires at least 30% of agents to disagree in Round 2. Unanimous agreement triggers an explicit groupthink warning. The system is designed to make agreement hard.
39
+ - **Minority report**: Dissenting positions are preserved in full, not averaged away. Sometimes the minority is right — you should see their reasoning.
40
+ - **Multi-round cross-examination**: Agents don't just state opinions in parallel. In Round 2, each agent must name which other agent they most disagree with, and why. This forces genuine engagement with opposing views.
41
+ - **Transparent verdict**: The output shows you agreement, disagreement, the specific tensions, and unresolved questions. No confident recommendation hiding real trade-offs.
42
+
43
+ ---
44
+
19
45
  ## Quick Start
20
46
 
47
+ ### Install
48
+
21
49
  ```bash
22
50
  npx @faviovazquez/deliberate
23
51
  ```
24
52
 
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:
53
+ The interactive installer auto-detects your platform and lets you choose global or workspace installation. You can also pass flags directly:
26
54
 
27
- **Claude Code:**
55
+ ```bash
56
+ # Claude Code — global (recommended)
57
+ npx @faviovazquez/deliberate --claude --global
58
+
59
+ # Windsurf — global
60
+ npx @faviovazquez/deliberate --windsurf --global
61
+
62
+ # Cursor — workspace only
63
+ npx @faviovazquez/deliberate --cursor
64
+
65
+ # All detected platforms — global
66
+ npx @faviovazquez/deliberate --all --global
67
+
68
+ # Preview without installing
69
+ npx @faviovazquez/deliberate --claude --global --dry-run
70
+
71
+ # Uninstall
72
+ npx @faviovazquez/deliberate --claude --global --uninstall
73
+ ```
74
+
75
+ ### Your First Deliberation
76
+
77
+ **Claude Code** — invoke with `/deliberate`:
28
78
  ```
29
79
  /deliberate "should we migrate from REST to GraphQL?"
30
80
  ```
31
81
 
32
- **Windsurf / Cursor:**
82
+ **Windsurf** — invoke with `@deliberate` or just ask a complex question (Windsurf auto-invokes when the question matches the skill description):
33
83
  ```
34
84
  @deliberate should we migrate from REST to GraphQL?
35
85
  ```
36
86
 
37
- Windsurf also auto-invokes the skill when your question matches the skill description.
87
+ **Cursor** — invoke with `@deliberate`:
88
+ ```
89
+ @deliberate should we migrate from REST to GraphQL?
90
+ ```
38
91
 
39
- ### Manual Installation
92
+ ### Manual Installation (git clone)
40
93
 
41
- **Claude Code (workspace):**
42
94
  ```bash
43
95
  git clone https://github.com/FavioVazquez/deliberate.git
44
96
  cd deliberate
45
- ./install.sh --platform claude-code
46
97
  ```
47
98
 
48
- **Claude Code (global -- all projects):**
49
99
  ```bash
100
+ # Claude Code
50
101
  ./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
102
 
60
- **Windsurf (global -- into ~/.codeium/windsurf/skills/):**
61
- ```bash
103
+ # Windsurf
62
104
  ./install.sh --platform windsurf --global
105
+
106
+ # Both
107
+ ./install.sh --platform all --global
63
108
  ```
64
109
 
110
+ ---
111
+
65
112
  ## Modes
66
113
 
114
+ `deliberate` has 6 modes. Each mode works on every platform — only the invocation syntax differs.
115
+
116
+ <p align="center">
117
+ <img src="assets/modes_overview.png" alt="Six Deliberation Modes" width="100%" />
118
+ </p>
119
+
67
120
  ### Full Deliberation (3 rounds)
121
+
122
+ All 14 core agents. Round 1: independent analysis. Round 2: cross-examination (agents must disagree). Round 3: crystallization. Produces a structured verdict with minority report.
123
+
124
+ **Claude Code:**
68
125
  ```
69
126
  /deliberate --full "is this acquisition worth pursuing at 8x revenue?"
127
+ /deliberate --full "should we open-source our core library?"
128
+ ```
129
+
130
+ **Windsurf / Cursor:**
131
+ ```
132
+ @deliberate full deliberation: is this acquisition worth pursuing at 8x revenue?
133
+ @deliberate run all 14 agents on: should we open-source our core library?
70
134
  ```
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
135
 
73
136
  ### Quick Deliberation (2 rounds)
137
+
138
+ Auto-selected triad. Rounds 1 + 3 only (skips cross-examination). Faster, cheaper, still multi-perspective.
139
+
140
+ **Claude Code:**
74
141
  ```
75
142
  /deliberate --quick "monorepo or polyrepo?"
143
+ /deliberate --quick "should we add Redis caching?"
144
+ ```
145
+
146
+ **Windsurf / Cursor:**
147
+ ```
148
+ @deliberate quick: monorepo or polyrepo?
149
+ @deliberate quick deliberation on whether to add Redis caching
76
150
  ```
77
- Auto-selected triad. Rounds 1 + 3 only (skip cross-examination). Faster, cheaper.
78
151
 
79
152
  ### Triad (domain-optimized)
153
+
154
+ 3 agents selected for a specific domain. 18 pre-defined triads available (see table below). Use when you know the domain of your question.
155
+
156
+ **Claude Code:**
80
157
  ```
81
158
  /deliberate --triad architecture "should we split the monolith?"
82
159
  /deliberate --triad decision "build vs buy for notifications"
83
- /deliberate --triad risk "should we launch before the audit?"
160
+ /deliberate --triad risk "should we launch before the security audit?"
161
+ /deliberate --triad ai "should we fine-tune or use RAG?"
162
+ /deliberate --triad shipping "can we ship v2 by Friday?"
163
+ ```
164
+
165
+ **Windsurf / Cursor:**
166
+ ```
167
+ @deliberate architecture triad: should we split the monolith?
168
+ @deliberate use the decision triad for: build vs buy for notifications
169
+ @deliberate risk triad: should we launch before the security audit?
170
+ @deliberate ai triad: should we fine-tune or use RAG?
171
+ @deliberate shipping triad: can we ship v2 by Friday?
84
172
  ```
85
- 3 agents selected for the domain. 18 pre-defined triads available.
86
173
 
87
174
  ### Duo / Dialectic
175
+
176
+ Two agents, two rounds of exchange, then synthesis. Best for binary decisions ("should we X or not?"). Pair agents from the polarity pairs table for maximum disagreement.
177
+
178
+ **Claude Code:**
88
179
  ```
89
180
  /deliberate --duo assumption-breaker,pragmatic-builder "rewrite the auth layer?"
181
+ /deliberate --duo risk-analyst,pragmatic-builder "ship with known tech debt?"
182
+ /deliberate --duo classifier,emergence-reader "impose strict types or keep it flexible?"
183
+ ```
184
+
185
+ **Windsurf / Cursor:**
186
+ ```
187
+ @deliberate duo with assumption-breaker and pragmatic-builder: should we rewrite the auth layer?
188
+ @deliberate dialectic between risk-analyst and pragmatic-builder on shipping with known tech debt
189
+ @deliberate duo: classifier vs emergence-reader on imposing strict types vs keeping it flexible
90
190
  ```
91
- Two agents, two rounds of exchange, then synthesis. Best for binary decisions.
92
191
 
93
192
  ### Brainstorm
193
+
194
+ Creative exploration with multiple agents. Divergent ideas → cross-pollination → convergence into actionable designs. Optionally add `--visual` for an interactive browser companion.
195
+
196
+ **Claude Code:**
94
197
  ```
95
198
  /deliberate --brainstorm "how should we redesign onboarding?"
96
199
  /deliberate --brainstorm --visual "landing page redesign"
200
+ /deliberate --brainstorm "new pricing model for our API"
201
+ ```
202
+
203
+ **Windsurf / Cursor:**
204
+ ```
205
+ @deliberate brainstorm: how should we redesign onboarding?
206
+ @deliberate brainstorm with visual companion: landing page redesign
207
+ @deliberate brainstorm: new pricing model for our API
97
208
  ```
98
- Creative exploration with multiple agents. Divergent ideas, cross-pollination, convergence into actionable designs. Optional visual companion with interactive idea maps.
99
209
 
100
210
  ### Auto-Detect (no flag)
211
+
212
+ Just ask your question. The coordinator parses domain keywords, selects the best-matching triad, and runs the 3-round protocol automatically.
213
+
214
+ **Claude Code:**
101
215
  ```
102
216
  /deliberate "should we migrate from REST to GraphQL?"
217
+ /deliberate "is our microservices architecture causing more problems than it solves?"
218
+ /deliberate "should we hire senior engineers or train juniors?"
219
+ ```
220
+
221
+ **Windsurf / Cursor:**
222
+ ```
223
+ @deliberate should we migrate from REST to GraphQL?
224
+ @deliberate is our microservices architecture causing more problems than it solves?
225
+ @deliberate should we hire senior engineers or train juniors?
226
+ ```
227
+
228
+ ### Custom Agent Selection
229
+
230
+ Pick specific agents by name for full control over who deliberates.
231
+
232
+ **Claude Code:**
233
+ ```
234
+ /deliberate --members assumption-breaker,first-principles,bias-detector "why does our cache keep failing?"
235
+ /deliberate --members pragmatic-builder,risk-analyst,systems-thinker,inverter "refactor the payment system?"
236
+ ```
237
+
238
+ **Windsurf / Cursor:**
239
+ ```
240
+ @deliberate use agents assumption-breaker, first-principles, and bias-detector: why does our cache keep failing?
241
+ @deliberate members pragmatic-builder, risk-analyst, systems-thinker, inverter: should we refactor the payment system?
242
+ ```
243
+
244
+ ### Profiles
245
+
246
+ Pre-defined agent groups for common scenarios. Use when you don't want to pick individual agents.
247
+
248
+ | Profile | Agents | When to Use |
249
+ |---------|--------|-------------|
250
+ | `full` | All 14 core agents | Complex decisions with real trade-offs. **Claude Code default.** |
251
+ | `lean` | assumption-breaker, first-principles, bias-detector, pragmatic-builder, inverter | Fast decisions, limited context. **Windsurf/Cursor default.** |
252
+ | `exploration` | assumption-breaker, classifier, emergence-reader, reframer, systems-thinker, inverter, risk-analyst | Discovery, open-ended investigation |
253
+ | `execution` | pragmatic-builder, first-principles, adversarial-strategist, bias-detector, formal-verifier | Shipping decisions, technical trade-offs |
254
+
255
+ **Claude Code:**
256
+ ```
257
+ /deliberate --profile exploration "what's the right approach to AI safety for our product?"
258
+ /deliberate --profile execution "can we ship this feature by next sprint?"
259
+ /deliberate --profile lean "quick take: should we use Postgres or MongoDB?"
260
+ ```
261
+
262
+ **Windsurf / Cursor:**
263
+ ```
264
+ @deliberate exploration profile: what's the right approach to AI safety for our product?
265
+ @deliberate execution profile: can we ship this feature by next sprint?
266
+ @deliberate lean profile: should we use Postgres or MongoDB?
103
267
  ```
104
- Parses your question, selects the best-matching triad, runs 3-round protocol.
268
+
269
+ ---
270
+
271
+ ## Flags Reference
272
+
273
+ | Flag | Effect | Example (Claude Code) |
274
+ |------|--------|----------------------|
275
+ | *(no flag)* | Auto-detect domain, select matching triad | `/deliberate "your question"` |
276
+ | `--full` | All 14 core agents, 3-round protocol | `/deliberate --full "question"` |
277
+ | `--quick` | Auto-detect triad, 2-round protocol (skip cross-examination) | `/deliberate --quick "question"` |
278
+ | `--duo a,b` | Dialectic mode: 2 agents, 2 exchange rounds, then synthesis | `/deliberate --duo risk-analyst,pragmatic-builder "question"` |
279
+ | `--triad {domain}` | Pre-defined triad for domain, 3-round protocol | `/deliberate --triad architecture "question"` |
280
+ | `--members a,b,c` | Custom agent selection (2-14 agents), 3-round protocol | `/deliberate --members a,b,c "question"` |
281
+ | `--brainstorm` | Creative exploration with divergent-convergent flow | `/deliberate --brainstorm "question"` |
282
+ | `--profile {name}` | Use named profile (full, lean, exploration, execution) | `/deliberate --profile exploration "question"` |
283
+ | `--visual` | Launch browser-based visual companion | `/deliberate --visual --full "question"` |
284
+ | `--save {slug}` | Override auto-generated filename slug for output | `/deliberate --save my-decision "question"` |
285
+
286
+ > **Windsurf/Cursor note:** Flags are expressed as natural language after `@deliberate`. The skill parses intent from your message. Examples: `@deliberate full deliberation: ...`, `@deliberate quick: ...`, `@deliberate architecture triad: ...`, `@deliberate brainstorm: ...`.
287
+
288
+ ---
105
289
 
106
290
  ## The 14 Core Agents
107
291
 
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.
292
+ Each agent is named by its analytical function — not by historical figures. Every agent declares its method, what it sees that others miss, and what it tends to miss. These declared blind spots are why the polarity pairs matter.
293
+
294
+ <p align="center">
295
+ <img src="assets/agents_wheel.png" alt="The 14 Core Agents" width="100%" />
296
+ </p>
297
+
298
+ | # | Agent | Function | Tier |
299
+ |---|-------|----------|------|
300
+ | 1 | `assumption-breaker` | Destroys hidden premises, tests by contradiction, dialectical questioning | high |
301
+ | 2 | `first-principles` | Bottom-up derivation, refuses unexplained complexity | mid |
302
+ | 3 | `classifier` | Taxonomic structure, category errors, four-cause analysis | mid |
303
+ | 4 | `formal-verifier` | Computational skeleton, mechanization boundaries, abstraction | mid |
304
+ | 5 | `bias-detector` | Cognitive bias detection, pre-mortem, de-biasing interventions | high |
305
+ | 6 | `systems-thinker` | Feedback loops, leverage points, unintended consequences | mid |
306
+ | 7 | `resilience-anchor` | Control vs acceptance, moral clarity, anti-panic grounding | mid |
307
+ | 8 | `adversarial-strategist` | Terrain reading, competitive dynamics, strategic timing | mid |
308
+ | 9 | `emergence-reader` | Non-action, subtraction, intervention audit, minimum intervention | high |
309
+ | 10 | `incentive-mapper` | Power dynamics, actor incentives, principal-agent problems | mid |
310
+ | 11 | `pragmatic-builder` | Ship it, maintenance cost, over-engineering detection | mid |
311
+ | 12 | `reframer` | Dissolves false problems, frame audit, false dichotomies | high |
312
+ | 13 | `risk-analyst` | Antifragility, tail risk, fragility profile, barbell strategy | high |
313
+ | 14 | `inverter` | Multi-model reasoning, inversion ("what guarantees failure?"), opportunity cost | mid |
314
+
315
+ ### Optional Specialists
316
+
317
+ Activated only when their domain-specific triad is selected:
318
+
319
+ | Agent | Function | Triads |
320
+ |-------|----------|--------|
321
+ | `ml-intuition` | Neural net intuition, training dynamics, jagged frontier | ai, ai-product |
322
+ | `safety-frontier` | Scaling dynamics, capability-safety frontier, phase transitions | ai |
323
+ | `design-lens` | User-centered design, honesty audit, "less but better" | design, ai-product |
324
+
325
+ ### Polarity Pairs
326
+
327
+ These agents are structural counterweights. When both are present, genuine disagreement is almost guaranteed. Use these pairings for `--duo` mode:
328
+
329
+ | Pair | Tension |
330
+ |------|---------|
331
+ | `assumption-breaker` vs `first-principles` | Top-down destruction vs bottom-up construction |
332
+ | `classifier` vs `emergence-reader` | Impose structure vs let it emerge |
333
+ | `adversarial-strategist` vs `resilience-anchor` | Win externally vs govern internally |
334
+ | `formal-verifier` vs `incentive-mapper` | Abstract purity vs messy human reality |
335
+ | `pragmatic-builder` vs `reframer` | Ship it vs does it need to exist? |
336
+ | `pragmatic-builder` vs `systems-thinker` | Fix the bug vs redesign the system |
337
+ | `risk-analyst` vs `ml-intuition` | Tail paranoia vs empirical iteration |
338
+
339
+ ---
128
340
 
129
341
  ## 18 Pre-defined Triads
130
342
 
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 |
343
+ Each triad is a team of 3 agents optimized for a domain. The reasoning chain shows the deliberation flow.
344
+
345
+ <p align="center">
346
+ <img src="assets/triad_map.png" alt="18 Pre-defined Triads" width="100%" />
347
+ </p>
348
+
349
+ | Domain | Agents | Reasoning Chain |
350
+ |--------|--------|-----------------|
351
+ | `architecture` | classifier + formal-verifier + first-principles | categorize → formalize → simplicity-test |
352
+ | `strategy` | adversarial-strategist + incentive-mapper + resilience-anchor | terrain → incentives → moral grounding |
353
+ | `ethics` | resilience-anchor + assumption-breaker + emergence-reader | duty → questioning → natural order |
354
+ | `debugging` | first-principles + assumption-breaker + formal-verifier | bottom-up → assumptions → formal verify |
355
+ | `innovation` | formal-verifier + emergence-reader + classifier | abstraction → emergence → classification |
356
+ | `conflict` | assumption-breaker + incentive-mapper + resilience-anchor | expose → predict → ground |
357
+ | `complexity` | emergence-reader + classifier + formal-verifier | emergence → categories → formalism |
358
+ | `risk` | adversarial-strategist + resilience-anchor + first-principles | threats → resilience → empirical verify |
359
+ | `shipping` | pragmatic-builder + adversarial-strategist + first-principles | pragmatism → timing → first-principles |
360
+ | `product` | pragmatic-builder + incentive-mapper + reframer | ship it → incentives → reframing |
361
+ | `decision` | inverter + bias-detector + risk-analyst | inversion → biases → tail risk |
362
+ | `systems` | systems-thinker + emergence-reader + classifier | feedback → emergence → structure |
363
+ | `economics` | adversarial-strategist + inverter + incentive-mapper | terrain → models → power |
364
+ | `uncertainty` | risk-analyst + adversarial-strategist + assumption-breaker | tails → threats → premises |
365
+ | `bias` | bias-detector + reframer + assumption-breaker | biases → frame → premises |
366
+ | `ai` | formal-verifier + ml-intuition + safety-frontier | formalism → empirical ML → safety |
367
+ | `ai-product` | pragmatic-builder + ml-intuition + design-lens | ship → ML reality → user |
368
+ | `design` | design-lens + reframer + pragmatic-builder | user → frame → ship |
369
+
370
+ **Which triad should I use?**
371
+
372
+ | If your question is about... | Use triad |
373
+ |------------------------------|-----------|
374
+ | Code structure, API design, monolith vs micro | `architecture` |
375
+ | Build vs buy, go/no-go, pricing | `decision` |
376
+ | Should we launch/ship? | `shipping` |
377
+ | Competitive moves, market entry | `strategy` |
378
+ | Something feels risky | `risk` or `uncertainty` |
379
+ | Root cause analysis, why is X broken | `debugging` |
380
+ | Feature design, user experience | `product` or `design` |
381
+ | AI/ML architecture, model selection | `ai` |
382
+ | AI product decisions | `ai-product` |
383
+ | Team dynamics, organizational change | `conflict` |
384
+ | System reliability, scaling | `systems` or `complexity` |
385
+ | Ethical implications | `ethics` |
386
+ | Cognitive biases in your decision | `bias` |
387
+
388
+ ---
151
389
 
152
390
  ## Visual Companion
153
391
 
154
- The visual companion is a browser-based interface that shows deliberation progress in real time. Launch it with `--visual`:
392
+ A browser-based interface that shows deliberation progress in real time. Available on all platforms.
155
393
 
394
+ **Claude Code:**
156
395
  ```
157
396
  /deliberate --visual --full "major architecture decision"
158
397
  /deliberate --brainstorm --visual "redesign the dashboard"
159
398
  ```
160
399
 
400
+ **Windsurf / Cursor:**
401
+ ```
402
+ @deliberate full deliberation with visual companion: major architecture decision
403
+ @deliberate brainstorm with visual: redesign the dashboard
404
+ ```
405
+
161
406
  It provides:
162
407
  - **Agent Position Map**: Force-directed graph showing agents as colored nodes positioned by agreement/disagreement
163
408
  - **Agreement Matrix**: Heatmap of which agents agree/disagree on which points
@@ -167,62 +412,189 @@ It provides:
167
412
 
168
413
  Built with plain HTML + JS + Canvas 2D. No framework, no build step. Served locally via a lightweight Node.js file-watcher server.
169
414
 
415
+ ---
416
+
170
417
  ## Platforms
171
418
 
172
419
  | Platform | Execution Model | Default Profile | Invocation | Install Paths |
173
420
  |----------|----------------|-----------------|------------|---------------|
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) |
421
+ | Claude Code | Parallel subagents (`context: fork`) | full (14 agents) | `/deliberate` + flags | `~/.claude/skills/` + `~/.claude/agents/` |
422
+ | Windsurf | Sequential role-prompting | lean (5 agents) | `@deliberate` or auto-invoke | `~/.codeium/windsurf/skills/deliberate/` |
423
+ | Cursor | Sequential role-prompting | lean (5 agents) | `@deliberate` | `.cursor/skills/deliberate/` |
177
424
 
178
425
  ### How it works on each platform
179
426
 
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.
427
+ **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 requires seeing prior outputs). Agents are installed as separate `.md` files in `~/.claude/agents/` and referenced by the skill protocol in `~/.claude/skills/deliberate/`.
428
+
429
+ **Windsurf**: No subagent support. The coordinator adopts each agent's persona sequentially within a single context window. Agent definitions are bundled inside the skill directory (`~/.codeium/windsurf/skills/deliberate/agents/`) and read on demand. The default "lean" profile (5 agents) keeps context usage manageable. Windsurf also auto-invokes the skill when your question matches the skill description — you don't always need to type `@deliberate`.
181
430
 
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.
431
+ **Cursor**: Same sequential execution as Windsurf. Agents bundled inside `.cursor/skills/deliberate/agents/`. Workspace-local installation only.
183
432
 
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).
433
+ ---
185
434
 
186
435
  ## Configuration
187
436
 
188
- ### Model tiers
189
- All agents use sonnet-equivalent models by default. To enable higher-tier models:
437
+ ### Model Tiers
190
438
 
439
+ All agents use sonnet-equivalent models by default. The tier determines model quality:
440
+
441
+ | Tier | Model | Agents at this tier |
442
+ |------|-------|--------------------|
443
+ | `high` | claude-sonnet-4 / equivalent | assumption-breaker, bias-detector, emergence-reader, reframer, risk-analyst |
444
+ | `mid` | claude-sonnet-4 / equivalent | All other agents |
445
+
446
+ To override all agents to a higher tier:
191
447
  ```yaml
192
448
  # In your project's config.yaml:
193
449
  model_tier: high
194
450
  # WARNING: high-tier models consume significantly more tokens/credits
195
451
  ```
196
452
 
197
- ### Custom model routing
198
- Copy `configs/provider-model-slots.example.yaml` to `configs/provider-model-slots.yaml` and customize per-agent model assignments.
453
+ ### Custom Model Routing
199
454
 
200
- ### Output
201
- All deliberation and brainstorm records are saved to `deliberations/` in your project root.
455
+ For per-agent model control, copy the example config:
456
+
457
+ ```bash
458
+ cp configs/provider-model-slots.example.yaml configs/provider-model-slots.yaml
459
+ ```
460
+
461
+ Then edit to assign specific models per agent:
462
+ ```yaml
463
+ # configs/provider-model-slots.yaml
464
+ assumption-breaker:
465
+ provider: anthropic
466
+ model: claude-sonnet-4-20250514
467
+ first-principles:
468
+ provider: anthropic
469
+ model: claude-sonnet-4-20250514
470
+ # ... customize per agent
471
+ ```
472
+
473
+ ### Output Location
474
+
475
+ All deliberation and brainstorm records are saved to `deliberations/` in your project root:
476
+ ```
477
+ deliberations/
478
+ 2025-04-03-14-30-triad-architecture-monolith.md
479
+ 2025-04-03-15-00-full-acquisition.md
480
+ 2025-04-03-16-00-brainstorm-onboarding.md
481
+ ```
482
+
483
+ ### Platform Defaults
484
+
485
+ The `configs/defaults.yaml` file controls per-platform behavior:
486
+
487
+ ```yaml
488
+ platforms:
489
+ claude-code:
490
+ execution: parallel # Agents run as parallel subagents
491
+ default_profile: full # All 14 agents
492
+ windsurf:
493
+ execution: sequential # Single context, role-prompting
494
+ default_profile: lean # 5 agents (saves context)
495
+ cursor:
496
+ execution: sequential
497
+ default_profile: lean
498
+ ```
499
+
500
+ You can override the default profile per invocation with `--profile`.
501
+
502
+ ---
202
503
 
203
504
  ## When to Use
204
505
 
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.
506
+ **Use `deliberate` for:**
507
+ - Complex decisions where trade-offs are real: architecture choices, strategic pivots, build-vs-buy
508
+ - Pricing models, go/no-go decisions, risk assessment
509
+ - Any situation where you suspect a single confident answer hides real trade-offs
510
+ - Decisions where you already have an opinion but suspect you're missing something
206
511
 
207
- **Don't use `/deliberate` for** questions with clear correct answers. Don't convene 14 agents to debate tabs vs spaces.
512
+ **Don't use `deliberate` for:**
513
+ - Questions with clear correct answers
514
+ - Don't convene 14 agents to debate tabs vs spaces
515
+ - Don't use `--full` when a triad covers the domain (14 agents consume significant context and API cost)
208
516
 
209
- **The sweet spot:** Decisions where you already have an opinion but suspect you're missing something.
517
+ **The sweet spot:** Decisions where a single confident answer hides real trade-offs. `deliberate` surfaces what you're not seeing — structured, with the disagreements visible.
518
+
519
+ ---
210
520
 
211
521
  ## Enforcement
212
522
 
213
523
  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
524
+
525
+ <p align="center">
526
+ <img src="assets/enforcement.png" alt="Protocol Enforcement" width="100%" />
527
+ </p>
528
+
529
+ | Rule | What it prevents |
530
+ |------|-----------------|
531
+ | **Hemlock rule** | Infinite questioning spirals — forces 50-word position statement |
532
+ | **3-level depth limit** | Endless depth — forces position commitment after 3 rounds of questioning |
533
+ | **2-message cutoff** | Any pair dominating the discussion |
534
+ | **Dissent quota (30%)** | Groupthink — at least 30% of agents must disagree in Round 2 |
535
+ | **Novelty gate** | Stale deliberation — Round 2 must introduce new ideas not in Round 1 |
536
+ | **Groupthink flag** | Unanimous agreement triggers explicit warning to the user |
537
+
538
+ ---
539
+
540
+ ## Verdict Output
541
+
542
+ Every deliberation produces a structured verdict saved to `deliberations/`:
543
+
544
+ <p align="center">
545
+ <img src="assets/verdict.png" alt="Structured Verdict Output" width="100%" />
546
+ </p>
547
+
548
+ ```markdown
549
+ ## Deliberation Verdict
550
+
551
+ ### Problem
552
+ {Original question}
553
+
554
+ ### Agents Present
555
+ {List of agents with functions}
556
+
557
+ ### Mode
558
+ {Full / Quick / Duo / Triad: {domain}}
559
+
560
+ ### Consensus Position
561
+ {Position held by 2/3+ agents, if one exists}
562
+
563
+ ### Key Insights by Agent
564
+ {2-3 sentence summary per agent}
565
+
566
+ ### Points of Agreement
567
+ {Where agents converged}
568
+
569
+ ### Points of Disagreement
570
+ {Where agents diverged, with the specific tension}
571
+
572
+ ### Minority Report
573
+ {Dissenting positions with full reasoning — sometimes the minority is right}
574
+
575
+ ### Verdict Type
576
+ {consensus | majority | split | dilemma}
577
+
578
+ ### Recommended Next Steps
579
+ {1-3 concrete actions}
580
+
581
+ ### Unresolved Questions
582
+ {Questions raised but not resolved}
583
+ ```
584
+
585
+ **Verdict types:**
586
+ - **consensus**: 2/3+ agree, minority report recorded
587
+ - **majority**: Simple majority, significant dissent recorded
588
+ - **split**: No majority, all positions presented equally
589
+ - **dilemma**: Genuine dilemma with no clear resolution — the agents surfaced the tension, you decide
590
+
591
+ ---
220
592
 
221
593
  ## References
222
594
 
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).
595
+ - **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.
596
+ - **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. `deliberate` redesigns the agent roster around analytical functions rather than personas, adds enforcement rules, and extends to multiple platforms.
597
+ - **Superpowers Brainstorming Skill** — [github.com/obra/superpowers](https://github.com/obra/superpowers) — The brainstorming skill and browser-based visual companion architecture.
226
598
 
227
599
  ## License
228
600
 
package/bin/cli.js CHANGED
@@ -2,68 +2,381 @@
2
2
 
3
3
  'use strict';
4
4
 
5
- const { execSync, spawn } = require('child_process');
6
- const path = require('path');
7
5
  const fs = require('fs');
6
+ const path = require('path');
7
+ const os = require('os');
8
+ const readline = require('readline');
8
9
 
9
10
  const ROOT = path.resolve(__dirname, '..');
10
- const INSTALL_SCRIPT = path.join(ROOT, 'install.sh');
11
+ const pkg = require(path.join(ROOT, 'package.json'));
11
12
 
13
+ // ─── Colors ────────────────────────────────────────────────────────────────
14
+ const blue = '\x1b[38;5;33m';
15
+ const cyan = '\x1b[36m';
16
+ const green = '\x1b[32m';
17
+ const yellow = '\x1b[33m';
18
+ const dim = '\x1b[2m';
19
+ const bold = '\x1b[1m';
20
+ const reset = '\x1b[0m';
21
+
22
+ // ─── Argument parsing ──────────────────────────────────────────────────────
12
23
  const args = process.argv.slice(2);
24
+ const hasClaude = args.includes('--claude') || args.includes('--claude-code');
25
+ const hasWindsurf = args.includes('--windsurf');
26
+ const hasCursor = args.includes('--cursor');
27
+ const hasAll = args.includes('--all');
28
+ const hasGlobal = args.includes('--global') || args.includes('-g');
29
+ const hasLocal = args.includes('--local') || args.includes('-l');
30
+ const hasDryRun = args.includes('--dry-run');
31
+ const hasHelp = args.includes('--help') || args.includes('-h');
32
+ const hasUninstall = args.includes('--uninstall') || args.includes('-u');
33
+
34
+ let selectedPlatforms = [];
35
+ if (hasAll) selectedPlatforms = ['claude-code', 'windsurf'];
36
+ if (hasClaude) selectedPlatforms.push('claude-code');
37
+ if (hasWindsurf) selectedPlatforms.push('windsurf');
38
+ if (hasCursor) selectedPlatforms.push('cursor');
39
+
40
+ // ─── Banner ────────────────────────────────────────────────────────────────
41
+ const banner = `
42
+ ${blue} ██████╗ ███████╗██╗ ██╗██████╗ ███████╗██████╗ █████╗ ████████╗███████╗
43
+ ██╔══██╗██╔════╝██║ ██║██╔══██╗██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝
44
+ ██║ ██║█████╗ ██║ ██║██████╔╝█████╗ ██████╔╝███████║ ██║ █████╗
45
+ ██║ ██║██╔══╝ ██║ ██║██╔══██╗██╔══╝ ██╔══██╗██╔══██║ ██║ ██╔══╝
46
+ ██████╔╝███████╗███████╗██║██████╔╝███████╗██║ ██║██║ ██║ ██║ ███████╗
47
+ ╚═════╝ ╚══════╝╚══════╝╚═╝╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚══════╝${reset}
48
+
49
+ ${dim}Agreement is a bug.${reset}
50
+ ${dim}v${pkg.version} · Multi-agent deliberation for AI coding assistants${reset}
51
+ `;
52
+
53
+ // ─── Help text ─────────────────────────────────────────────────────────────
54
+ const helpText = `
55
+ ${yellow}Usage:${reset} npx @faviovazquez/deliberate [platform] [scope] [options]
56
+
57
+ ${yellow}Platforms:${reset}
58
+ ${cyan}--claude${reset} Claude Code (~/.claude/)
59
+ ${cyan}--windsurf${reset} Windsurf (~/.codeium/windsurf/)
60
+ ${cyan}--cursor${reset} Cursor (.cursor/skills/)
61
+ ${cyan}--all${reset} All detected platforms
13
62
 
14
- function usage() {
15
- console.log(`
16
- deliberate -- Multi-agent deliberation for AI coding assistants
17
- Agreement is a bug.
63
+ ${yellow}Scope:${reset}
64
+ ${cyan}-g, --global${reset} Install to global config directory (recommended)
65
+ ${cyan}-l, --local${reset} Install to current project directory
18
66
 
19
- Usage:
20
- npx @faviovazquez/deliberate Auto-detect platform and install
21
- npx @faviovazquez/deliberate --platform X Install for specific platform
22
- npx @faviovazquez/deliberate --dry-run Preview installation
23
- npx @faviovazquez/deliberate --help Show this help
67
+ ${yellow}Options:${reset}
68
+ ${cyan}--dry-run${reset} Preview without installing
69
+ ${cyan}-u, --uninstall${reset} Remove deliberate files
70
+ ${cyan}-h, --help${reset} Show this help
24
71
 
25
- Platforms: claude-code, windsurf, cursor, all
72
+ ${yellow}Examples:${reset}
73
+ ${dim}# Interactive install (prompts for platform and scope)${reset}
74
+ npx @faviovazquez/deliberate
26
75
 
27
- After installation, open your AI coding assistant and try:
28
- /deliberate "should we migrate from REST to GraphQL?"
76
+ ${dim}# Install for Claude Code globally${reset}
77
+ npx @faviovazquez/deliberate --claude --global
29
78
 
30
- Learn more: https://github.com/FavioVazquez/deliberate
31
- `);
79
+ ${dim}# Install for all platforms globally${reset}
80
+ npx @faviovazquez/deliberate --all --global
81
+
82
+ ${dim}# Preview installation${reset}
83
+ npx @faviovazquez/deliberate --claude --global --dry-run
84
+ `;
85
+
86
+ // ─── Path helpers ──────────────────────────────────────────────────────────
87
+ function getGlobalDir(platform) {
88
+ switch (platform) {
89
+ case 'claude-code': return path.join(os.homedir(), '.claude');
90
+ case 'windsurf': return path.join(os.homedir(), '.codeium', 'windsurf');
91
+ case 'cursor': return path.join(process.cwd(), '.cursor');
92
+ default: return path.join(os.homedir(), '.claude');
93
+ }
32
94
  }
33
95
 
34
- if (args.includes('--help') || args.includes('-h')) {
35
- usage();
36
- process.exit(0);
96
+ function getLocalDir(platform) {
97
+ switch (platform) {
98
+ case 'claude-code': return path.join(process.cwd(), '.claude');
99
+ case 'windsurf': return path.join(process.cwd(), '.windsurf');
100
+ case 'cursor': return path.join(process.cwd(), '.cursor');
101
+ default: return path.join(process.cwd(), '.claude');
102
+ }
37
103
  }
38
104
 
39
- // Forward all arguments to install.sh
40
- console.log('');
41
- console.log(' deliberate installer');
42
- console.log(' Agreement is a bug.');
43
- console.log('');
44
-
45
- // Check for bash
46
- try {
47
- execSync('which bash', { stdio: 'pipe' });
48
- } catch (e) {
49
- console.error('Error: bash is required. Please install bash and try again.');
50
- process.exit(1);
105
+ function getPlatformLabel(platform) {
106
+ const labels = { 'claude-code': 'Claude Code', 'windsurf': 'Windsurf', 'cursor': 'Cursor' };
107
+ return labels[platform] || platform;
51
108
  }
52
109
 
53
- // Make install.sh executable
54
- try {
55
- fs.chmodSync(INSTALL_SCRIPT, '755');
56
- } catch (e) {
57
- // May already be executable
110
+ function tildePath(p) {
111
+ return p.replace(os.homedir(), '~');
58
112
  }
59
113
 
60
- // Run install.sh with forwarded arguments
61
- const installArgs = args.length > 0 ? args : [];
62
- const child = spawn('bash', [INSTALL_SCRIPT, ...installArgs], {
63
- stdio: 'inherit',
64
- cwd: ROOT
65
- });
114
+ // ─── File copy ─────────────────────────────────────────────────────────────
115
+ let fileCount = 0;
116
+
117
+ function copyFile(src, dest) {
118
+ if (hasDryRun) {
119
+ console.log(` ${dim}(dry-run)${reset} ${tildePath(dest)}`);
120
+ return;
121
+ }
122
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
123
+ fs.copyFileSync(src, dest);
124
+ fileCount++;
125
+ }
126
+
127
+ function copyDir(srcDir, destDir) {
128
+ if (!fs.existsSync(srcDir)) return;
129
+ for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
130
+ const src = path.join(srcDir, entry.name);
131
+ const dest = path.join(destDir, entry.name);
132
+ if (entry.isDirectory()) {
133
+ copyDir(src, dest);
134
+ } else {
135
+ copyFile(src, dest);
136
+ }
137
+ }
138
+ }
139
+
140
+ function makeExecutable(filePath) {
141
+ if (hasDryRun || !fs.existsSync(filePath)) return;
142
+ try { fs.chmodSync(filePath, '755'); } catch { /* ignore */ }
143
+ }
144
+
145
+ // ─── Install functions ─────────────────────────────────────────────────────
146
+ function installClaudeCode(isGlobal) {
147
+ const baseDir = isGlobal ? getGlobalDir('claude-code') : getLocalDir('claude-code');
148
+ const agentsDir = path.join(baseDir, 'agents');
149
+ const skillDir = path.join(baseDir, 'skills', 'deliberate');
150
+ const locationLabel = tildePath(baseDir);
151
+
152
+ console.log(`\n Installing for ${cyan}Claude Code${reset} → ${cyan}${locationLabel}${reset}\n`);
153
+
154
+ // Core agents
155
+ const agentsSrc = path.join(ROOT, 'agents');
156
+ for (const f of fs.readdirSync(agentsSrc)) {
157
+ if (!f.endsWith('.md')) continue;
158
+ copyFile(path.join(agentsSrc, f), path.join(agentsDir, `deliberate-${f}`));
159
+ }
160
+ // Specialist agents
161
+ const specSrc = path.join(agentsSrc, 'specialists');
162
+ if (fs.existsSync(specSrc)) {
163
+ for (const f of fs.readdirSync(specSrc)) {
164
+ if (!f.endsWith('.md')) continue;
165
+ copyFile(path.join(specSrc, f), path.join(agentsDir, `deliberate-${f}`));
166
+ }
167
+ }
168
+ console.log(` ${green}✓${reset} Installed 17 agents to ${tildePath(agentsDir)}/`);
169
+
170
+ // Skill protocol
171
+ copyFile(path.join(ROOT, 'SKILL.md'), path.join(skillDir, 'SKILL.md'));
172
+ copyFile(path.join(ROOT, 'BRAINSTORM.md'), path.join(skillDir, 'BRAINSTORM.md'));
173
+ console.log(` ${green}✓${reset} Installed skill protocol to ${tildePath(skillDir)}/`);
174
+
175
+ // Configs
176
+ copyDir(path.join(ROOT, 'configs'), path.join(skillDir, 'configs'));
177
+ console.log(` ${green}✓${reset} Installed configs`);
178
+
179
+ // Scripts
180
+ copyDir(path.join(ROOT, 'scripts'), path.join(skillDir, 'scripts'));
181
+ makeExecutable(path.join(skillDir, 'scripts', 'start-server.sh'));
182
+ makeExecutable(path.join(skillDir, 'scripts', 'stop-server.sh'));
183
+ makeExecutable(path.join(skillDir, 'scripts', 'detect-platform.sh'));
184
+ console.log(` ${green}✓${reset} Installed visual companion scripts`);
185
+
186
+ // Templates
187
+ copyDir(path.join(ROOT, 'templates'), path.join(skillDir, 'templates'));
188
+ console.log(` ${green}✓${reset} Installed output templates`);
189
+
190
+ console.log(`\n ${green}Done!${reset} Open Claude Code and try: ${cyan}/deliberate "your question here"${reset}`);
191
+ }
192
+
193
+ function installWindsurf(isGlobal) {
194
+ const baseDir = isGlobal ? getGlobalDir('windsurf') : getLocalDir('windsurf');
195
+ const skillDir = path.join(baseDir, 'skills', 'deliberate');
196
+ const locationLabel = tildePath(skillDir);
197
+
198
+ console.log(`\n Installing for ${cyan}Windsurf${reset} → ${cyan}${locationLabel}${reset}\n`);
199
+
200
+ // Skill protocol
201
+ copyFile(path.join(ROOT, 'SKILL.md'), path.join(skillDir, 'SKILL.md'));
202
+ copyFile(path.join(ROOT, 'BRAINSTORM.md'), path.join(skillDir, 'BRAINSTORM.md'));
203
+ console.log(` ${green}✓${reset} Installed skill protocol`);
204
+
205
+ // Agents (bundled with skill)
206
+ copyDir(path.join(ROOT, 'agents'), path.join(skillDir, 'agents'));
207
+ console.log(` ${green}✓${reset} Installed 17 agents`);
208
+
209
+ // Configs, Scripts, Templates
210
+ copyDir(path.join(ROOT, 'configs'), path.join(skillDir, 'configs'));
211
+ copyDir(path.join(ROOT, 'scripts'), path.join(skillDir, 'scripts'));
212
+ copyDir(path.join(ROOT, 'templates'), path.join(skillDir, 'templates'));
213
+ makeExecutable(path.join(skillDir, 'scripts', 'start-server.sh'));
214
+ makeExecutable(path.join(skillDir, 'scripts', 'stop-server.sh'));
215
+ makeExecutable(path.join(skillDir, 'scripts', 'detect-platform.sh'));
216
+ console.log(` ${green}✓${reset} Installed configs, scripts, templates`);
66
217
 
67
- child.on('close', (code) => {
68
- process.exit(code || 0);
218
+ console.log(`\n ${green}Done!${reset} Open Windsurf and try: ${cyan}@deliberate${reset} or just ask a complex decision question.`);
219
+ }
220
+
221
+ function installCursor(isGlobal) {
222
+ // Cursor is always workspace-local
223
+ const skillDir = path.join(process.cwd(), '.cursor', 'skills', 'deliberate');
224
+ const locationLabel = tildePath(skillDir);
225
+
226
+ console.log(`\n Installing for ${cyan}Cursor${reset} → ${cyan}${locationLabel}${reset}\n`);
227
+
228
+ copyFile(path.join(ROOT, 'SKILL.md'), path.join(skillDir, 'SKILL.md'));
229
+ copyFile(path.join(ROOT, 'BRAINSTORM.md'), path.join(skillDir, 'BRAINSTORM.md'));
230
+ copyDir(path.join(ROOT, 'agents'), path.join(skillDir, 'agents'));
231
+ copyDir(path.join(ROOT, 'configs'), path.join(skillDir, 'configs'));
232
+ copyDir(path.join(ROOT, 'scripts'), path.join(skillDir, 'scripts'));
233
+ copyDir(path.join(ROOT, 'templates'), path.join(skillDir, 'templates'));
234
+ makeExecutable(path.join(skillDir, 'scripts', 'start-server.sh'));
235
+ makeExecutable(path.join(skillDir, 'scripts', 'stop-server.sh'));
236
+ makeExecutable(path.join(skillDir, 'scripts', 'detect-platform.sh'));
237
+ console.log(` ${green}✓${reset} Installed skill, agents, configs, scripts, templates`);
238
+
239
+ console.log(`\n ${green}Done!${reset} Open Cursor and try: ${cyan}@deliberate${reset} or just ask a complex decision question.`);
240
+ }
241
+
242
+ // ─── Uninstall ─────────────────────────────────────────────────────────────
243
+ function uninstall(platform, isGlobal) {
244
+ const label = getPlatformLabel(platform);
245
+ let removed = 0;
246
+
247
+ if (platform === 'claude-code') {
248
+ const baseDir = isGlobal ? getGlobalDir('claude-code') : getLocalDir('claude-code');
249
+ console.log(`\n Uninstalling from ${cyan}${label}${reset} at ${cyan}${tildePath(baseDir)}${reset}\n`);
250
+
251
+ // Remove agents
252
+ const agentsDir = path.join(baseDir, 'agents');
253
+ if (fs.existsSync(agentsDir)) {
254
+ for (const f of fs.readdirSync(agentsDir)) {
255
+ if (f.startsWith('deliberate-') && f.endsWith('.md')) {
256
+ fs.unlinkSync(path.join(agentsDir, f)); removed++;
257
+ }
258
+ }
259
+ if (removed > 0) console.log(` ${green}✓${reset} Removed ${removed} agent files`);
260
+ }
261
+
262
+ // Remove skill dir
263
+ const skillDir = path.join(baseDir, 'skills', 'deliberate');
264
+ if (fs.existsSync(skillDir)) {
265
+ fs.rmSync(skillDir, { recursive: true });
266
+ console.log(` ${green}✓${reset} Removed skills/deliberate/`);
267
+ removed++;
268
+ }
269
+ } else {
270
+ const baseDir = platform === 'windsurf'
271
+ ? (isGlobal ? getGlobalDir('windsurf') : getLocalDir('windsurf'))
272
+ : path.join(process.cwd(), '.cursor');
273
+ const skillDir = path.join(baseDir, 'skills', 'deliberate');
274
+ console.log(`\n Uninstalling from ${cyan}${label}${reset} at ${cyan}${tildePath(skillDir)}${reset}\n`);
275
+
276
+ if (fs.existsSync(skillDir)) {
277
+ fs.rmSync(skillDir, { recursive: true });
278
+ console.log(` ${green}✓${reset} Removed skills/deliberate/`);
279
+ removed++;
280
+ }
281
+ }
282
+
283
+ if (removed === 0) console.log(` ${yellow}⚠${reset} No deliberate files found.`);
284
+ else console.log(`\n ${green}Done!${reset} deliberate uninstalled from ${label}.`);
285
+ }
286
+
287
+ // ─── Detect platforms ──────────────────────────────────────────────────────
288
+ function detectPlatforms() {
289
+ const detected = [];
290
+ if (fs.existsSync(path.join(os.homedir(), '.claude'))) detected.push('claude-code');
291
+ if (fs.existsSync(path.join(os.homedir(), '.codeium', 'windsurf'))) detected.push('windsurf');
292
+ if (fs.existsSync(path.join(process.cwd(), '.windsurf'))) {
293
+ if (!detected.includes('windsurf')) detected.push('windsurf');
294
+ }
295
+ if (fs.existsSync(path.join(process.cwd(), '.cursor'))) detected.push('cursor');
296
+ return detected;
297
+ }
298
+
299
+ // ─── Interactive prompt ────────────────────────────────────────────────────
300
+ async function promptUser() {
301
+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
302
+ const ask = (q) => new Promise(resolve => rl.question(q, resolve));
303
+
304
+ const detected = detectPlatforms();
305
+
306
+ console.log(` ${yellow}Select platform:${reset}`);
307
+ console.log(` 1) Claude Code ${dim}(${detected.includes('claude-code') ? green + 'detected' + reset : dim + 'not detected' + reset}${dim})${reset}`);
308
+ console.log(` 2) Windsurf ${dim}(${detected.includes('windsurf') ? green + 'detected' + reset : dim + 'not detected' + reset}${dim})${reset}`);
309
+ console.log(` 3) Cursor ${dim}(workspace only)${reset}`);
310
+ console.log(` 4) All detected ${dim}(${detected.length > 0 ? detected.map(getPlatformLabel).join(', ') : 'none detected'})${reset}`);
311
+
312
+ const platformChoice = await ask(`\n ${bold}Platform [1-4]:${reset} `);
313
+ const platformMap = {
314
+ '1': ['claude-code'],
315
+ '2': ['windsurf'],
316
+ '3': ['cursor'],
317
+ '4': detected.length > 0 ? detected : ['claude-code'],
318
+ };
319
+ const platforms = platformMap[platformChoice.trim()] || ['claude-code'];
320
+
321
+ // Only ask scope if not cursor-only
322
+ let isGlobal = true;
323
+ const hasCursorOnly = platforms.length === 1 && platforms[0] === 'cursor';
324
+ if (!hasCursorOnly) {
325
+ console.log(`\n ${yellow}Install scope:${reset}`);
326
+ console.log(` 1) ${green}Global${reset} ${dim}(recommended)${reset} — available in all projects`);
327
+ console.log(` 2) Local — current project only`);
328
+ const scopeChoice = await ask(`\n ${bold}Scope [1-2]:${reset} `);
329
+ isGlobal = scopeChoice.trim() !== '2';
330
+ } else {
331
+ isGlobal = false; // Cursor is always workspace-local
332
+ }
333
+
334
+ rl.close();
335
+ return { platforms, isGlobal };
336
+ }
337
+
338
+ // ─── Entry point ───────────────────────────────────────────────────────────
339
+ async function main() {
340
+ console.log(banner);
341
+
342
+ if (hasHelp) { console.log(helpText); process.exit(0); }
343
+
344
+ let platforms = selectedPlatforms;
345
+ let isGlobal = hasGlobal || !hasLocal;
346
+
347
+ if (platforms.length === 0 && !hasUninstall) {
348
+ const result = await promptUser();
349
+ platforms = result.platforms;
350
+ isGlobal = result.isGlobal;
351
+ } else if (platforms.length === 0 && hasUninstall) {
352
+ console.error(` ${yellow}Error:${reset} Specify a platform to uninstall from.`);
353
+ console.error(` Example: npx @faviovazquez/deliberate --claude --global --uninstall`);
354
+ process.exit(1);
355
+ }
356
+
357
+ console.log('');
358
+ for (const platform of platforms) {
359
+ fileCount = 0;
360
+ if (hasUninstall) {
361
+ uninstall(platform, isGlobal);
362
+ } else {
363
+ switch (platform) {
364
+ case 'claude-code': installClaudeCode(isGlobal); break;
365
+ case 'windsurf': installWindsurf(isGlobal); break;
366
+ case 'cursor': installCursor(isGlobal); break;
367
+ default:
368
+ console.error(` ${yellow}Unknown platform:${reset} ${platform}`);
369
+ process.exit(1);
370
+ }
371
+ }
372
+ }
373
+
374
+ if (!hasUninstall) {
375
+ console.log(`\n ${dim}Learn more: https://github.com/FavioVazquez/deliberate${reset}`);
376
+ }
377
+ }
378
+
379
+ main().catch(err => {
380
+ console.error(` Error: ${err.message}`);
381
+ process.exit(1);
69
382
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faviovazquez/deliberate",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "Multi-agent deliberation skill for AI coding assistants. Agreement is a bug.",
5
5
  "license": "MIT",
6
6
  "author": "Favio Vazquez",
package/scripts/release.sh DELETED
@@ -1,131 +0,0 @@
1
- #!/usr/bin/env bash
2
- set -euo pipefail
3
-
4
- # deliberate -- Release script
5
- # Usage: ./scripts/release.sh [patch|minor|major]
6
- #
7
- # This script:
8
- # 1. Bumps the version in package.json
9
- # 2. Updates CHANGELOG.md with the new version header
10
- # 3. Commits the version bump
11
- # 4. Creates a git tag
12
- # 5. Pushes to origin with tags
13
- # 6. Creates a GitHub release
14
- # 7. Publishes to npm
15
-
16
- SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
17
- ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
18
- BUMP_TYPE="${1:-patch}"
19
-
20
- if [[ "$BUMP_TYPE" != "patch" && "$BUMP_TYPE" != "minor" && "$BUMP_TYPE" != "major" ]]; then
21
- echo "Usage: release.sh [patch|minor|major]"
22
- echo " patch: 0.1.0 -> 0.1.1 (bug fixes)"
23
- echo " minor: 0.1.0 -> 0.2.0 (new features, new agents)"
24
- echo " major: 0.1.0 -> 1.0.0 (breaking changes)"
25
- exit 1
26
- fi
27
-
28
- cd "$ROOT_DIR"
29
-
30
- # Pre-flight checks
31
- echo "=== Pre-flight checks ==="
32
-
33
- if [[ -n "$(git status --porcelain)" ]]; then
34
- echo "ERROR: Working directory is not clean. Commit or stash changes first."
35
- git status --short
36
- exit 1
37
- fi
38
-
39
- if ! command -v gh >/dev/null 2>&1; then
40
- echo "ERROR: GitHub CLI (gh) is required. Install: https://cli.github.com"
41
- exit 1
42
- fi
43
-
44
- if ! command -v npm >/dev/null 2>&1; then
45
- echo "ERROR: npm is required."
46
- exit 1
47
- fi
48
-
49
- CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
50
- if [[ "$CURRENT_BRANCH" != "main" ]]; then
51
- echo "WARNING: You are on branch '$CURRENT_BRANCH', not 'main'."
52
- read -p "Continue? [y/N] " confirm
53
- [[ "$confirm" == "y" || "$confirm" == "Y" ]] || exit 1
54
- fi
55
-
56
- # Get current and new version
57
- CURRENT_VERSION=$(node -p "require('./package.json').version")
58
- echo "Current version: $CURRENT_VERSION"
59
-
60
- # Bump version (npm version updates package.json and creates git tag)
61
- NEW_VERSION=$(npm version "$BUMP_TYPE" --no-git-tag-version | sed 's/^v//')
62
- echo "New version: $NEW_VERSION"
63
-
64
- # Update CHANGELOG.md
65
- DATE=$(date +%Y-%m-%d)
66
- CHANGELOG_ENTRY="## [$NEW_VERSION] - $DATE"
67
-
68
- if grep -q "## \[Unreleased\]" CHANGELOG.md 2>/dev/null; then
69
- # Replace [Unreleased] with the new version
70
- sed -i "s/## \[Unreleased\]/$CHANGELOG_ENTRY/" CHANGELOG.md
71
- else
72
- # Insert new version header after the first ## line
73
- sed -i "/^## \[/i\\
74
- \\n$CHANGELOG_ENTRY\\n" CHANGELOG.md
75
- fi
76
-
77
- echo ""
78
- echo "=== CHANGELOG.md updated ==="
79
- echo "Please review and add release notes to CHANGELOG.md before continuing."
80
- echo "The new version header has been added. Add your changes under it."
81
- echo ""
82
- read -p "Open CHANGELOG.md for editing? [Y/n] " edit_changelog
83
- if [[ "$edit_changelog" != "n" && "$edit_changelog" != "N" ]]; then
84
- ${EDITOR:-vi} CHANGELOG.md
85
- fi
86
-
87
- # Commit and tag
88
- echo ""
89
- echo "=== Committing and tagging ==="
90
- git add package.json CHANGELOG.md
91
- git commit -m "release: v$NEW_VERSION"
92
- git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
93
-
94
- # Push
95
- echo ""
96
- echo "=== Pushing to origin ==="
97
- git push origin "$CURRENT_BRANCH"
98
- git push origin "v$NEW_VERSION"
99
-
100
- # Create GitHub release
101
- echo ""
102
- echo "=== Creating GitHub release ==="
103
-
104
- # Extract changelog for this version
105
- RELEASE_NOTES=$(awk "/^## \[$NEW_VERSION\]/{found=1; next} /^## \[/{if(found) exit} found{print}" CHANGELOG.md)
106
-
107
- if [[ -z "$RELEASE_NOTES" ]]; then
108
- RELEASE_NOTES="Release v$NEW_VERSION"
109
- fi
110
-
111
- gh release create "v$NEW_VERSION" \
112
- --title "v$NEW_VERSION" \
113
- --notes "$RELEASE_NOTES"
114
-
115
- # Publish to npm
116
- echo ""
117
- echo "=== Publishing to npm ==="
118
- read -p "Publish to npm? [Y/n] " publish
119
- if [[ "$publish" != "n" && "$publish" != "N" ]]; then
120
- npm publish
121
- echo ""
122
- echo "Published! Users can now run: npx deliberate"
123
- else
124
- echo "Skipped npm publish. Run 'npm publish' manually when ready."
125
- fi
126
-
127
- echo ""
128
- echo "=== Release v$NEW_VERSION complete ==="
129
- echo " Git tag: v$NEW_VERSION"
130
- echo " GitHub: https://github.com/FavioVazquez/deliberate/releases/tag/v$NEW_VERSION"
131
- echo " npm: https://www.npmjs.com/package/deliberate"