npm - @faviovazquez/deliberate - Versions diffs - 0.2.0 → 0.2.1 - Mend

@faviovazquez/deliberate 0.2.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 (3) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.2.1] - 2025-04-03
+### Added
+- 7 Gemini-generated images for the README (banner, sycophancy diagram, modes overview, agents wheel, triad map, enforcement rules, verdict output)
+- Expanded "The Problem" section with deep sycophancy analysis: confirmation bias amplification, delusional spiraling, simulated balance, hidden trade-offs, context collapse
+- "What deliberate brings to the table" section explaining structural disagreement, forced dissent, minority report, cross-examination, transparent verdicts
+- Images embedded throughout README at relevant sections
 ## [0.2.0] - 2025-04-03
 ### Changed

package/README.md CHANGED Viewed

@@ -1,163 +1,408 @@
+<p align="center">
+  <img src="assets/banner.png" alt="deliberate — Agreement is a bug" width="100%" />
+</p>
 # deliberate
 **Agreement is a bug.**
 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.
-## The Problem
+## The Problem: AI Sycophancy
+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.
+This is not a minor UX inconvenience. It is a structural failure mode:
-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)).
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
-A single LLM produces one coherent viewpoint per generation. It simulates balance. It does not achieve genuine adversarial deliberation.
+The research is clear: a single AI perspective is structurally insufficient for complex decisions.
+<p align="center">
+  <img src="assets/sycophancy.png" alt="The Sycophancy Problem — Single AI vs Multi-Agent Deliberation" width="100%" />
+</p>
 ## The Solution
-`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.
+`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.
 The disagreements are the point. A single model averages opposing views into one confident recommendation. `deliberate` keeps them separate so you can decide.
+**What deliberate brings to the table:**
+- **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.
+- **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.
+- **Minority report**: Dissenting positions are preserved in full, not averaged away. Sometimes the minority is right — you should see their reasoning.
+- **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.
+- **Transparent verdict**: The output shows you agreement, disagreement, the specific tensions, and unresolved questions. No confident recommendation hiding real trade-offs.
+---
 ## Quick Start
+### Install
 ```bash
 npx @faviovazquez/deliberate
 ```
-This auto-detects your platform (Claude Code, Windsurf, Cursor) and installs the skill to the current workspace. Then open your AI assistant and try:
+The interactive installer auto-detects your platform and lets you choose global or workspace installation. You can also pass flags directly:
-**Claude Code:**
+```bash
+# Claude Code — global (recommended)
+npx @faviovazquez/deliberate --claude --global
+# Windsurf — global
+npx @faviovazquez/deliberate --windsurf --global
+# Cursor — workspace only
+npx @faviovazquez/deliberate --cursor
+# All detected platforms — global
+npx @faviovazquez/deliberate --all --global
+# Preview without installing
+npx @faviovazquez/deliberate --claude --global --dry-run
+# Uninstall
+npx @faviovazquez/deliberate --claude --global --uninstall
+```
+### Your First Deliberation
+**Claude Code** — invoke with `/deliberate`:
 ```
 /deliberate "should we migrate from REST to GraphQL?"
 ```
-**Windsurf / Cursor:**
+**Windsurf** — invoke with `@deliberate` or just ask a complex question (Windsurf auto-invokes when the question matches the skill description):
 ```
 @deliberate should we migrate from REST to GraphQL?
 ```
-Windsurf also auto-invokes the skill when your question matches the skill description.
+**Cursor** — invoke with `@deliberate`:
+```
+@deliberate should we migrate from REST to GraphQL?
+```
-### Manual Installation
+### Manual Installation (git clone)
-**Claude Code (workspace):**
 ```bash
 git clone https://github.com/FavioVazquez/deliberate.git
 cd deliberate
-./install.sh --platform claude-code
 ```
-**Claude Code (global -- all projects):**
 ```bash
+# Claude Code
 ./install.sh --platform claude-code --global
-```
-**Windsurf (workspace -- into .windsurf/skills/):**
-```bash
-git clone https://github.com/FavioVazquez/deliberate.git
-cd deliberate
-./install.sh --platform windsurf
-```
-**Windsurf (global -- into ~/.codeium/windsurf/skills/):**
-```bash
+# Windsurf
 ./install.sh --platform windsurf --global
+# Both
+./install.sh --platform all --global
 ```
+---
 ## Modes
+`deliberate` has 6 modes. Each mode works on every platform — only the invocation syntax differs.
+<p align="center">
+  <img src="assets/modes_overview.png" alt="Six Deliberation Modes" width="100%" />
+</p>
 ### Full Deliberation (3 rounds)
+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.
+**Claude Code:**
 ```
 /deliberate --full "is this acquisition worth pursuing at 8x revenue?"
+/deliberate --full "should we open-source our core library?"
+```
+**Windsurf / Cursor:**
+```
+@deliberate full deliberation: is this acquisition worth pursuing at 8x revenue?
+@deliberate run all 14 agents on: should we open-source our core library?
 ```
-All 14 agents. Round 1: independent analysis. Round 2: cross-examination (must disagree). Round 3: crystallization. Produces a structured verdict with minority report.
 ### Quick Deliberation (2 rounds)
+Auto-selected triad. Rounds 1 + 3 only (skips cross-examination). Faster, cheaper, still multi-perspective.
+**Claude Code:**
 ```
 /deliberate --quick "monorepo or polyrepo?"
+/deliberate --quick "should we add Redis caching?"
+```
+**Windsurf / Cursor:**
+```
+@deliberate quick: monorepo or polyrepo?
+@deliberate quick deliberation on whether to add Redis caching
 ```
-Auto-selected triad. Rounds 1 + 3 only (skip cross-examination). Faster, cheaper.
 ### Triad (domain-optimized)
+3 agents selected for a specific domain. 18 pre-defined triads available (see table below). Use when you know the domain of your question.
+**Claude Code:**
 ```
 /deliberate --triad architecture "should we split the monolith?"
 /deliberate --triad decision "build vs buy for notifications"
-/deliberate --triad risk "should we launch before the audit?"
+/deliberate --triad risk "should we launch before the security audit?"
+/deliberate --triad ai "should we fine-tune or use RAG?"
+/deliberate --triad shipping "can we ship v2 by Friday?"
+```
+**Windsurf / Cursor:**
+```
+@deliberate architecture triad: should we split the monolith?
+@deliberate use the decision triad for: build vs buy for notifications
+@deliberate risk triad: should we launch before the security audit?
+@deliberate ai triad: should we fine-tune or use RAG?
+@deliberate shipping triad: can we ship v2 by Friday?
 ```
-3 agents selected for the domain. 18 pre-defined triads available.
 ### Duo / Dialectic
+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.
+**Claude Code:**
 ```
 /deliberate --duo assumption-breaker,pragmatic-builder "rewrite the auth layer?"
+/deliberate --duo risk-analyst,pragmatic-builder "ship with known tech debt?"
+/deliberate --duo classifier,emergence-reader "impose strict types or keep it flexible?"
+```
+**Windsurf / Cursor:**
+```
+@deliberate duo with assumption-breaker and pragmatic-builder: should we rewrite the auth layer?
+@deliberate dialectic between risk-analyst and pragmatic-builder on shipping with known tech debt
+@deliberate duo: classifier vs emergence-reader on imposing strict types vs keeping it flexible
 ```
-Two agents, two rounds of exchange, then synthesis. Best for binary decisions.
 ### Brainstorm
+Creative exploration with multiple agents. Divergent ideas → cross-pollination → convergence into actionable designs. Optionally add `--visual` for an interactive browser companion.
+**Claude Code:**
 ```
 /deliberate --brainstorm "how should we redesign onboarding?"
 /deliberate --brainstorm --visual "landing page redesign"
+/deliberate --brainstorm "new pricing model for our API"
+```
+**Windsurf / Cursor:**
+```
+@deliberate brainstorm: how should we redesign onboarding?
+@deliberate brainstorm with visual companion: landing page redesign
+@deliberate brainstorm: new pricing model for our API
 ```
-Creative exploration with multiple agents. Divergent ideas, cross-pollination, convergence into actionable designs. Optional visual companion with interactive idea maps.
 ### Auto-Detect (no flag)
+Just ask your question. The coordinator parses domain keywords, selects the best-matching triad, and runs the 3-round protocol automatically.
+**Claude Code:**
 ```
 /deliberate "should we migrate from REST to GraphQL?"
+/deliberate "is our microservices architecture causing more problems than it solves?"
+/deliberate "should we hire senior engineers or train juniors?"
+```
+**Windsurf / Cursor:**
+```
+@deliberate should we migrate from REST to GraphQL?
+@deliberate is our microservices architecture causing more problems than it solves?
+@deliberate should we hire senior engineers or train juniors?
+```
+### Custom Agent Selection
+Pick specific agents by name for full control over who deliberates.
+**Claude Code:**
+```
+/deliberate --members assumption-breaker,first-principles,bias-detector "why does our cache keep failing?"
+/deliberate --members pragmatic-builder,risk-analyst,systems-thinker,inverter "refactor the payment system?"
+```
+**Windsurf / Cursor:**
+```
+@deliberate use agents assumption-breaker, first-principles, and bias-detector: why does our cache keep failing?
+@deliberate members pragmatic-builder, risk-analyst, systems-thinker, inverter: should we refactor the payment system?
+```
+### Profiles
+Pre-defined agent groups for common scenarios. Use when you don't want to pick individual agents.
+| Profile | Agents | When to Use |
+|---------|--------|-------------|
+| `full` | All 14 core agents | Complex decisions with real trade-offs. **Claude Code default.** |
+| `lean` | assumption-breaker, first-principles, bias-detector, pragmatic-builder, inverter | Fast decisions, limited context. **Windsurf/Cursor default.** |
+| `exploration` | assumption-breaker, classifier, emergence-reader, reframer, systems-thinker, inverter, risk-analyst | Discovery, open-ended investigation |
+| `execution` | pragmatic-builder, first-principles, adversarial-strategist, bias-detector, formal-verifier | Shipping decisions, technical trade-offs |
+**Claude Code:**
+```
+/deliberate --profile exploration "what's the right approach to AI safety for our product?"
+/deliberate --profile execution "can we ship this feature by next sprint?"
+/deliberate --profile lean "quick take: should we use Postgres or MongoDB?"
+```
+**Windsurf / Cursor:**
+```
+@deliberate exploration profile: what's the right approach to AI safety for our product?
+@deliberate execution profile: can we ship this feature by next sprint?
+@deliberate lean profile: should we use Postgres or MongoDB?
 ```
-Parses your question, selects the best-matching triad, runs 3-round protocol.
+---
+## Flags Reference
+| Flag | Effect | Example (Claude Code) |
+|------|--------|----------------------|
+| *(no flag)* | Auto-detect domain, select matching triad | `/deliberate "your question"` |
+| `--full` | All 14 core agents, 3-round protocol | `/deliberate --full "question"` |
+| `--quick` | Auto-detect triad, 2-round protocol (skip cross-examination) | `/deliberate --quick "question"` |
+| `--duo a,b` | Dialectic mode: 2 agents, 2 exchange rounds, then synthesis | `/deliberate --duo risk-analyst,pragmatic-builder "question"` |
+| `--triad {domain}` | Pre-defined triad for domain, 3-round protocol | `/deliberate --triad architecture "question"` |
+| `--members a,b,c` | Custom agent selection (2-14 agents), 3-round protocol | `/deliberate --members a,b,c "question"` |
+| `--brainstorm` | Creative exploration with divergent-convergent flow | `/deliberate --brainstorm "question"` |
+| `--profile {name}` | Use named profile (full, lean, exploration, execution) | `/deliberate --profile exploration "question"` |
+| `--visual` | Launch browser-based visual companion | `/deliberate --visual --full "question"` |
+| `--save {slug}` | Override auto-generated filename slug for output | `/deliberate --save my-decision "question"` |
+> **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: ...`.
+---
 ## The 14 Core Agents
-| Agent | Function |
-|-------|----------|
-| `assumption-breaker` | Destroys hidden premises, tests by contradiction |
-| `first-principles` | Bottom-up derivation, refuses unexplained complexity |
-| `classifier` | Taxonomic structure, category errors, four-cause analysis |
-| `formal-verifier` | Computational skeleton, mechanization boundaries |
-| `bias-detector` | Cognitive bias detection, pre-mortem, de-biasing |
-| `systems-thinker` | Feedback loops, leverage points, unintended consequences |
-| `resilience-anchor` | Control vs acceptance, moral clarity, anti-panic |
-| `adversarial-strategist` | Terrain reading, competitive dynamics, strategic timing |
-| `emergence-reader` | Non-action, subtraction, minimum intervention |
-| `incentive-mapper` | Power dynamics, actor incentives, how people actually behave |
-| `pragmatic-builder` | Ship it, maintenance cost, over-engineering detection |
-| `reframer` | Dissolves false problems, frame audit, perspective shift |
-| `risk-analyst` | Antifragility, tail risk, fragility profile |
-| `inverter` | Multi-model reasoning, inversion ("what guarantees failure?") |
-Plus 3 **optional specialists** activated for domain-specific triads: `ml-intuition` (AI/ML), `safety-frontier` (AI safety), `design-lens` (UX/design).
-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.
+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.
+<p align="center">
+  <img src="assets/agents_wheel.png" alt="The 14 Core Agents" width="100%" />
+</p>
+| # | Agent | Function | Tier |
+|---|-------|----------|------|
+| 1 | `assumption-breaker` | Destroys hidden premises, tests by contradiction, dialectical questioning | high |
+| 2 | `first-principles` | Bottom-up derivation, refuses unexplained complexity | mid |
+| 3 | `classifier` | Taxonomic structure, category errors, four-cause analysis | mid |
+| 4 | `formal-verifier` | Computational skeleton, mechanization boundaries, abstraction | mid |
+| 5 | `bias-detector` | Cognitive bias detection, pre-mortem, de-biasing interventions | high |
+| 6 | `systems-thinker` | Feedback loops, leverage points, unintended consequences | mid |
+| 7 | `resilience-anchor` | Control vs acceptance, moral clarity, anti-panic grounding | mid |
+| 8 | `adversarial-strategist` | Terrain reading, competitive dynamics, strategic timing | mid |
+| 9 | `emergence-reader` | Non-action, subtraction, intervention audit, minimum intervention | high |
+| 10 | `incentive-mapper` | Power dynamics, actor incentives, principal-agent problems | mid |
+| 11 | `pragmatic-builder` | Ship it, maintenance cost, over-engineering detection | mid |
+| 12 | `reframer` | Dissolves false problems, frame audit, false dichotomies | high |
+| 13 | `risk-analyst` | Antifragility, tail risk, fragility profile, barbell strategy | high |
+| 14 | `inverter` | Multi-model reasoning, inversion ("what guarantees failure?"), opportunity cost | mid |
+### Optional Specialists
+Activated only when their domain-specific triad is selected:
+| Agent | Function | Triads |
+|-------|----------|--------|
+| `ml-intuition` | Neural net intuition, training dynamics, jagged frontier | ai, ai-product |
+| `safety-frontier` | Scaling dynamics, capability-safety frontier, phase transitions | ai |
+| `design-lens` | User-centered design, honesty audit, "less but better" | design, ai-product |
+### Polarity Pairs
+These agents are structural counterweights. When both are present, genuine disagreement is almost guaranteed. Use these pairings for `--duo` mode:
+| Pair | Tension |
+|------|---------|
+| `assumption-breaker` vs `first-principles` | Top-down destruction vs bottom-up construction |
+| `classifier` vs `emergence-reader` | Impose structure vs let it emerge |
+| `adversarial-strategist` vs `resilience-anchor` | Win externally vs govern internally |
+| `formal-verifier` vs `incentive-mapper` | Abstract purity vs messy human reality |
+| `pragmatic-builder` vs `reframer` | Ship it vs does it need to exist? |
+| `pragmatic-builder` vs `systems-thinker` | Fix the bug vs redesign the system |
+| `risk-analyst` vs `ml-intuition` | Tail paranoia vs empirical iteration |
+---
 ## 18 Pre-defined Triads
-| Domain | Agents |
-|--------|--------|
-| architecture | classifier + formal-verifier + first-principles |
-| strategy | adversarial-strategist + incentive-mapper + resilience-anchor |
-| ethics | resilience-anchor + assumption-breaker + emergence-reader |
-| debugging | first-principles + assumption-breaker + formal-verifier |
-| innovation | formal-verifier + emergence-reader + classifier |
-| conflict | assumption-breaker + incentive-mapper + resilience-anchor |
-| complexity | emergence-reader + classifier + formal-verifier |
-| risk | adversarial-strategist + resilience-anchor + first-principles |
-| shipping | pragmatic-builder + adversarial-strategist + first-principles |
-| product | pragmatic-builder + incentive-mapper + reframer |
-| decision | inverter + bias-detector + risk-analyst |
-| systems | systems-thinker + emergence-reader + classifier |
-| economics | adversarial-strategist + inverter + incentive-mapper |
-| uncertainty | risk-analyst + adversarial-strategist + assumption-breaker |
-| bias | bias-detector + reframer + assumption-breaker |
-| ai | formal-verifier + ml-intuition + safety-frontier |
-| ai-product | pragmatic-builder + ml-intuition + design-lens |
-| design | design-lens + reframer + pragmatic-builder |
+Each triad is a team of 3 agents optimized for a domain. The reasoning chain shows the deliberation flow.
+<p align="center">
+  <img src="assets/triad_map.png" alt="18 Pre-defined Triads" width="100%" />
+</p>
+| Domain | Agents | Reasoning Chain |
+|--------|--------|-----------------|
+| `architecture` | classifier + formal-verifier + first-principles | categorize → formalize → simplicity-test |
+| `strategy` | adversarial-strategist + incentive-mapper + resilience-anchor | terrain → incentives → moral grounding |
+| `ethics` | resilience-anchor + assumption-breaker + emergence-reader | duty → questioning → natural order |
+| `debugging` | first-principles + assumption-breaker + formal-verifier | bottom-up → assumptions → formal verify |
+| `innovation` | formal-verifier + emergence-reader + classifier | abstraction → emergence → classification |
+| `conflict` | assumption-breaker + incentive-mapper + resilience-anchor | expose → predict → ground |
+| `complexity` | emergence-reader + classifier + formal-verifier | emergence → categories → formalism |
+| `risk` | adversarial-strategist + resilience-anchor + first-principles | threats → resilience → empirical verify |
+| `shipping` | pragmatic-builder + adversarial-strategist + first-principles | pragmatism → timing → first-principles |
+| `product` | pragmatic-builder + incentive-mapper + reframer | ship it → incentives → reframing |
+| `decision` | inverter + bias-detector + risk-analyst | inversion → biases → tail risk |
+| `systems` | systems-thinker + emergence-reader + classifier | feedback → emergence → structure |
+| `economics` | adversarial-strategist + inverter + incentive-mapper | terrain → models → power |
+| `uncertainty` | risk-analyst + adversarial-strategist + assumption-breaker | tails → threats → premises |
+| `bias` | bias-detector + reframer + assumption-breaker | biases → frame → premises |
+| `ai` | formal-verifier + ml-intuition + safety-frontier | formalism → empirical ML → safety |
+| `ai-product` | pragmatic-builder + ml-intuition + design-lens | ship → ML reality → user |
+| `design` | design-lens + reframer + pragmatic-builder | user → frame → ship |
+**Which triad should I use?**
+| If your question is about... | Use triad |
+|------------------------------|-----------|
+| Code structure, API design, monolith vs micro | `architecture` |
+| Build vs buy, go/no-go, pricing | `decision` |
+| Should we launch/ship? | `shipping` |
+| Competitive moves, market entry | `strategy` |
+| Something feels risky | `risk` or `uncertainty` |
+| Root cause analysis, why is X broken | `debugging` |
+| Feature design, user experience | `product` or `design` |
+| AI/ML architecture, model selection | `ai` |
+| AI product decisions | `ai-product` |
+| Team dynamics, organizational change | `conflict` |
+| System reliability, scaling | `systems` or `complexity` |
+| Ethical implications | `ethics` |
+| Cognitive biases in your decision | `bias` |
+---
 ## Visual Companion
-The visual companion is a browser-based interface that shows deliberation progress in real time. Launch it with `--visual`:
+A browser-based interface that shows deliberation progress in real time. Available on all platforms.
+**Claude Code:**
 ```
 /deliberate --visual --full "major architecture decision"
 /deliberate --brainstorm --visual "redesign the dashboard"
 ```
+**Windsurf / Cursor:**
+```
+@deliberate full deliberation with visual companion: major architecture decision
+@deliberate brainstorm with visual: redesign the dashboard
+```
 It provides:
 - **Agent Position Map**: Force-directed graph showing agents as colored nodes positioned by agreement/disagreement
 - **Agreement Matrix**: Heatmap of which agents agree/disagree on which points
@@ -167,62 +412,189 @@ It provides:
 Built with plain HTML + JS + Canvas 2D. No framework, no build step. Served locally via a lightweight Node.js file-watcher server.
+---
 ## Platforms
 | Platform | Execution Model | Default Profile | Invocation | Install Paths |
 |----------|----------------|-----------------|------------|---------------|
-| Claude Code | Parallel subagents (`context: fork`) | full (14 agents) | `/deliberate` | `~/.claude/skills/` (global), `.claude/skills/` (workspace) |
-| Windsurf | Sequential role-prompting | lean (5 agents) | `@deliberate` or auto | `~/.codeium/windsurf/skills/` (global), `.windsurf/skills/` (workspace) |
-| Cursor | Sequential role-prompting | lean (5 agents) | `@deliberate` or auto | `.cursor/skills/` (workspace) |
+| Claude Code | Parallel subagents (`context: fork`) | full (14 agents) | `/deliberate` + flags | `~/.claude/skills/` + `~/.claude/agents/` |
+| Windsurf | Sequential role-prompting | lean (5 agents) | `@deliberate` or auto-invoke | `~/.codeium/windsurf/skills/deliberate/` |
+| Cursor | Sequential role-prompting | lean (5 agents) | `@deliberate` | `.cursor/skills/deliberate/` |
 ### How it works on each platform
-**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.
+**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/`.
+**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`.
-**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.
+**Cursor**: Same sequential execution as Windsurf. Agents bundled inside `.cursor/skills/deliberate/agents/`. Workspace-local installation only.
-**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).
+---
 ## Configuration
-### Model tiers
-All agents use sonnet-equivalent models by default. To enable higher-tier models:
+### Model Tiers
+All agents use sonnet-equivalent models by default. The tier determines model quality:
+| Tier | Model | Agents at this tier |
+|------|-------|--------------------|
+| `high` | claude-sonnet-4 / equivalent | assumption-breaker, bias-detector, emergence-reader, reframer, risk-analyst |
+| `mid` | claude-sonnet-4 / equivalent | All other agents |
+To override all agents to a higher tier:
 ```yaml
 # In your project's config.yaml:
 model_tier: high
 # WARNING: high-tier models consume significantly more tokens/credits
 ```
-### Custom model routing
-Copy `configs/provider-model-slots.example.yaml` to `configs/provider-model-slots.yaml` and customize per-agent model assignments.
+### Custom Model Routing
-### Output
-All deliberation and brainstorm records are saved to `deliberations/` in your project root.
+For per-agent model control, copy the example config:
+```bash
+cp configs/provider-model-slots.example.yaml configs/provider-model-slots.yaml
+```
+Then edit to assign specific models per agent:
+```yaml
+# configs/provider-model-slots.yaml
+assumption-breaker:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+first-principles:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+# ... customize per agent
+```
+### Output Location
+All deliberation and brainstorm records are saved to `deliberations/` in your project root:
+```
+deliberations/
+  2025-04-03-14-30-triad-architecture-monolith.md
+  2025-04-03-15-00-full-acquisition.md
+  2025-04-03-16-00-brainstorm-onboarding.md
+```
+### Platform Defaults
+The `configs/defaults.yaml` file controls per-platform behavior:
+```yaml
+platforms:
+  claude-code:
+    execution: parallel       # Agents run as parallel subagents
+    default_profile: full     # All 14 agents
+  windsurf:
+    execution: sequential     # Single context, role-prompting
+    default_profile: lean     # 5 agents (saves context)
+  cursor:
+    execution: sequential
+    default_profile: lean
+```
+You can override the default profile per invocation with `--profile`.
+---
 ## When to Use
-**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.
+**Use `deliberate` for:**
+- Complex decisions where trade-offs are real: architecture choices, strategic pivots, build-vs-buy
+- Pricing models, go/no-go decisions, risk assessment
+- Any situation where you suspect a single confident answer hides real trade-offs
+- Decisions where you already have an opinion but suspect you're missing something
-**Don't use `/deliberate` for** questions with clear correct answers. Don't convene 14 agents to debate tabs vs spaces.
+**Don't use `deliberate` for:**
+- Questions with clear correct answers
+- Don't convene 14 agents to debate tabs vs spaces
+- Don't use `--full` when a triad covers the domain (14 agents consume significant context and API cost)
-**The sweet spot:** Decisions where you already have an opinion but suspect you're missing something.
+**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.
+---
 ## Enforcement
 The protocol includes safeguards against common failure modes:
-- **Hemlock rule**: Prevents infinite questioning spirals
-- **3-level depth limit**: Forces position commitment after 3 rounds of questioning
-- **2-message cutoff**: Prevents any pair from dominating the discussion
-- **Dissent quota**: At least 30% of agents must disagree in Round 2
-- **Novelty gate**: Round 2 must introduce new ideas
-- **Groupthink flag**: Unanimous agreement triggers explicit warning
+<p align="center">
+  <img src="assets/enforcement.png" alt="Protocol Enforcement" width="100%" />
+</p>
+| Rule | What it prevents |
+|------|-----------------|
+| **Hemlock rule** | Infinite questioning spirals — forces 50-word position statement |
+| **3-level depth limit** | Endless depth — forces position commitment after 3 rounds of questioning |
+| **2-message cutoff** | Any pair dominating the discussion |
+| **Dissent quota (30%)** | Groupthink — at least 30% of agents must disagree in Round 2 |
+| **Novelty gate** | Stale deliberation — Round 2 must introduce new ideas not in Round 1 |
+| **Groupthink flag** | Unanimous agreement triggers explicit warning to the user |
+---
+## Verdict Output
+Every deliberation produces a structured verdict saved to `deliberations/`:
+<p align="center">
+  <img src="assets/verdict.png" alt="Structured Verdict Output" width="100%" />
+</p>
+```markdown
+## Deliberation Verdict
+### Problem
+{Original question}
+### Agents Present
+{List of agents with functions}
+### Mode
+{Full / Quick / Duo / Triad: {domain}}
+### Consensus Position
+{Position held by 2/3+ agents, if one exists}
+### Key Insights by Agent
+{2-3 sentence summary per agent}
+### Points of Agreement
+{Where agents converged}
+### Points of Disagreement
+{Where agents diverged, with the specific tension}
+### Minority Report
+{Dissenting positions with full reasoning — sometimes the minority is right}
+### Verdict Type
+{consensus | majority | split | dilemma}
+### Recommended Next Steps
+{1-3 concrete actions}
+### Unresolved Questions
+{Questions raised but not resolved}
+```
+**Verdict types:**
+- **consensus**: 2/3+ agree, minority report recorded
+- **majority**: Simple majority, significant dissent recorded
+- **split**: No majority, all positions presented equally
+- **dilemma**: Genuine dilemma with no clear resolution — the agents surfaced the tension, you decide
+---
 ## References
-- **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.
-- **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.
-- **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).
+- **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.
+- **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.
+- **Superpowers Brainstorming Skill** — [github.com/obra/superpowers](https://github.com/obra/superpowers) — The brainstorming skill and browser-based visual companion architecture.
 ## License

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@faviovazquez/deliberate",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Multi-agent deliberation skill for AI coding assistants. Agreement is a bug.",
   "license": "MIT",
   "author": "Favio Vazquez",