@faviovazquez/deliberate 0.2.6 → 0.2.8

package/BRAINSTORM.md

@@ -36,6 +36,39 @@ Do NOT invoke any implementation skill, write any code, scaffold any project, or
 
 ## Process Flow
 
+### Phase 0: Model Selection (Claude Code only)
+
+**This step runs only on Claude Code.** On Windsurf and Cursor, agents use the active model in the current context — skip this phase entirely.
+
+Before doing anything else, ask the user:
+
+```
+⚙️ Model configuration for this brainstorm:
+
+High-tier agents (assumption-breaker, bias-detector, emergence-reader,
+reframer, risk-analyst, safety-frontier) will use:
+
+  A) Opus + Sonnet  — opus for high-tier, sonnet for mid-tier [DEFAULT]
+                      Best quality. Higher token cost.
+  B) Sonnet only    — sonnet for all agents
+                      Faster. Lower cost. Still strong.
+
+Which would you prefer? (A/B, or press Enter for default A)
+```
+
+**Wait for the user's response before proceeding.**
+
+- If the user selects **A** or presses Enter: `high → opus`, `mid → sonnet`
+- If the user selects **B**: both `high` and `mid` → `sonnet`
+
+`opus` and `sonnet` are Claude Code's accepted shorthands for claude-opus-4-6 and claude-sonnet-4-6.
+
+Store the resolved model map and use it when dispatching agents in Phase 5 (Divergent Phase). Pass the resolved shorthand as the `model` parameter for each agent subagent call.
+
+If `configs/provider-model-slots.yaml` exists in the project root, skip this prompt and use manual overrides from that file.
+
+---
+
 ### Phase 1: Context Exploration
 
 Read the relevant context before asking any questions:
@@ -260,6 +293,20 @@ If you want changes, tell me what to adjust.
 
 **Only proceed to implementation after explicit user approval.**
 
+### Phase 12: Visual Companion Shutdown (if active)
+
+If the visual companion server was started during this session, ask the user after they approve or conclude the brainstorm:
+
+```
+The visual companion server is still running at http://localhost:{port}.
+Stop it now? (Y/n)
+```
+
+- If **Y** or Enter: run `scripts/stop-server.sh` to shut it down cleanly.
+- If **N**: leave it running. Remind the user it will auto-shutdown after 30 minutes of inactivity.
+
+If the visual companion was NOT active during this session, skip this phase.
+
 ---
 
 ## Visual Companion in Brainstorm Mode

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.8] - 2026-04-04
+
+### Added
+- `README.md`: Expanded Visual Companion section with a dedicated "Starting and stopping the server" subsection — explains that the coordinator starts the server automatically, documents the shutdown prompt shown at the end of each session, the 30-minute auto-shutdown, and manual `start-server.sh` / `stop-server.sh` commands for both Claude Code and Windsurf install paths.
+- `SKILL.md`: Added **Step 12 — Visual Companion Shutdown**. After saving output, the coordinator asks the user whether to stop the server (`Y/n`). If yes, runs `scripts/stop-server.sh`. If no, reminds user of the 30-minute auto-shutdown. Skipped if visual companion was not active.
+- `BRAINSTORM.md`: Added **Phase 12 — Visual Companion Shutdown**, identical logic to SKILL.md Step 12, triggered after Phase 11 user approval.
+
+## [0.2.7] - 2026-04-04
+
+### Fixed
+- Renamed `model:` to `model_tier:` in all 17 agent frontmatter files — Claude Code's Agent tool was reading `model: mid/high` as a model identifier and rejecting it since `mid`/`high` are not valid model IDs (only `sonnet`, `opus`, `haiku` are accepted). `model_tier` is now treated as metadata only by Claude Code.
+
+### Changed
+- `configs/defaults.yaml`: `anthropic.high` now maps to `claude-opus-4-5` (was `claude-sonnet-4.6`), `anthropic.mid` maps to `claude-sonnet-4-5`. Opus is the default for high-tier agents.
+- `SKILL.md`: Added **Step 0.5 — Model Selection** (Claude Code only). Before any deliberation starts, the coordinator asks whether to use Opus+Sonnet (A, default) or Sonnet-only (B) for all agents. The resolved model map is passed as the `model` parameter when dispatching each subagent via the Agent tool. On Windsurf/Cursor, this step is skipped — the active context model is used.
+- `SKILL.md` Step 4 (Model Routing): Updated to read `model_tier` from agent frontmatter, resolve via the Step 0.5 selection, and pass the resolved model name to the Agent tool. Windsurf/Cursor behavior explicitly documented.
+- `BRAINSTORM.md`: Added **Phase 0 — Model Selection** (Claude Code only), identical logic to SKILL.md Step 0.5.
+
 ## [0.2.6] - 2025-04-03
 
 ### Fixed

package/README.md

@@ -479,6 +479,33 @@ It provides:
 
 Built with plain HTML + JS + Canvas 2D. No framework, no build step. Served locally via a lightweight Node.js file-watcher server.
 
+### Starting and stopping the server
+
+The coordinator starts the server automatically when `--visual` is active. You do not need to start it manually. When your deliberation or brainstorm ends, the coordinator will ask you:
+
+```
+The visual companion server is still running at http://localhost:{port}.
+Stop it now? (Y/n)
+```
+
+If you say yes (or press Enter), it runs `scripts/stop-server.sh` to shut it down cleanly. If you say no, the server keeps running — useful if you want to review the session in the browser after the deliberation ends. **It will auto-shutdown after 30 minutes of inactivity regardless.**
+
+If you ever need to manage the server manually:
+
+```bash
+# Start the server (from your project root)
+bash ~/.claude/skills/deliberate/scripts/start-server.sh --project-dir .
+
+# Stop the server
+bash ~/.claude/skills/deliberate/scripts/stop-server.sh
+```
+
+For Windsurf:
+```bash
+bash ~/.codeium/windsurf/skills/deliberate/scripts/start-server.sh --project-dir .
+bash ~/.codeium/windsurf/skills/deliberate/scripts/stop-server.sh
+```
+
 ---
 
 ## Platforms

package/SKILL.md

@@ -133,6 +133,37 @@ If `--research` is NOT set, skip this step entirely. Do not spontaneously resear
 
 ---
 
+### Step 0.5: Model Selection (Claude Code only)
+
+**This step runs only on Claude Code.** On Windsurf and Cursor, agents use the active model in the current context — no selection needed.
+
+Before doing anything else, ask the user:
+
+```
+⚙️ Model configuration for this deliberation:
+
+High-tier agents (assumption-breaker, bias-detector, emergence-reader,
+reframer, risk-analyst, safety-frontier) will use:
+
+  A) Opus + Sonnet  — opus for high-tier, sonnet for mid-tier [DEFAULT]
+                      Best quality. Higher token cost.
+  B) Sonnet only    — sonnet for all agents
+                      Faster. Lower cost. Still strong.
+
+Which would you prefer? (A/B, or press Enter for default A)
+```
+
+**Wait for the user's response before proceeding.**
+
+- If the user selects **A** or presses Enter: resolve `high → opus`, `mid → sonnet` from `configs/defaults.yaml`
+- If the user selects **B**: resolve both `high` and `mid` → `sonnet`
+
+Store the resolved model map for use in Step 4. This selection applies for the entire session.
+
+If `configs/provider-model-slots.yaml` exists in the project root, skip this prompt entirely and use manual overrides from that file.
+
+---
+
 ### Step 1: Platform Detection
 
 Read `configs/defaults.yaml` to determine:
@@ -163,12 +194,18 @@ If auto-detection is ambiguous, present the top 2-3 triad matches and let the us
 
 ### Step 4: Model Routing
 
-Read `configs/defaults.yaml` for tier mapping:
-- Agents marked `model: high` get the high-tier model
-- Agents marked `model: mid` get the mid-tier model
-- If `config.yaml` in project root sets `model_tier: mid`, ALL agents use mid tier regardless of their default
+Use the resolved model map from Step 0.5 (Claude Code) or the active context model (Windsurf/Cursor):
 
-If `configs/provider-model-slots.yaml` exists, use manual overrides instead of auto-routing.
+**Claude Code:**
+- Agents with `model_tier: high` → pass `model: opus` (or `model: sonnet` if user chose B) to the Agent tool
+- Agents with `model_tier: mid` → pass `model: sonnet` to the Agent tool
+- `opus` and `sonnet` are Claude Code's accepted shorthands for the current claude-opus-4-6 and claude-sonnet-4-6
+- If `configs/provider-model-slots.yaml` exists, use manual overrides instead
+
+**Windsurf / Cursor:**
+- All agents run sequentially within the current context window using the model already active in the session
+- `model_tier` in agent frontmatter is treated as metadata only — no model switching occurs
+- No model selection prompt is shown
 
 ### Step 5: Visual Companion (optional)
 
@@ -305,6 +342,20 @@ Save the full deliberation record to `deliberations/YYYY-MM-DD-HH-MM-{mode}-{slu
 
 If visual companion is active, push the verdict formation view to the browser.
 
+### Step 12: Visual Companion Shutdown (if active)
+
+If the visual companion server was started during this session, ask the user:
+
+```
+The visual companion server is still running at http://localhost:{port}.
+Stop it now? (Y/n)
+```
+
+- If **Y** or Enter: run `scripts/stop-server.sh` to shut it down cleanly.
+- If **N**: leave it running. Remind the user it will auto-shutdown after 30 minutes of inactivity.
+
+If the visual companion was NOT active during this session, skip this step.
+
 ---
 
 ## Quick Mode Execution

package/agents/adversarial-strategist.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-adversarial-strategist
 description: "Deliberate agent. Use standalone for adversarial strategy, competitive analysis & strategic timing, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: red
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/assumption-breaker.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-assumption-breaker
 description: "Deliberate agent. Use standalone for assumption destruction & dialectical analysis, or via /deliberate for multi-perspective deliberation."
-model: high
+model_tier: high
 color: coral
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/bias-detector.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-bias-detector
 description: "Deliberate agent. Use standalone for cognitive bias detection & de-biasing, or via /deliberate for multi-perspective deliberation."
-model: high
+model_tier: high
 color: violet
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/classifier.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-classifier
 description: "Deliberate agent. Use standalone for categorization & structural analysis, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: amber
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/emergence-reader.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-emergence-reader
 description: "Deliberate agent. Use standalone for emergence & non-intervention analysis, or via /deliberate for multi-perspective deliberation."
-model: high
+model_tier: high
 color: indigo
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/first-principles.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-first-principles
 description: "Deliberate agent. Use standalone for first-principles debugging & bottom-up derivation, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: orange
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/formal-verifier.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-formal-verifier
 description: "Deliberate agent. Use standalone for formal systems & computational analysis, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: cyan
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/incentive-mapper.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-incentive-mapper
 description: "Deliberate agent. Use standalone for power dynamics & incentive analysis, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: dark-red
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/inverter.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-inverter
 description: "Deliberate agent. Use standalone for multi-model reasoning & inversion analysis, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: gold
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/pragmatic-builder.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-pragmatic-builder
 description: "Deliberate agent. Use standalone for pragmatic engineering & shipping analysis, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/reframer.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-reframer
 description: "Deliberate agent. Use standalone for perspective dissolution & reframing, or via /deliberate for multi-perspective deliberation."
-model: high
+model_tier: high
 color: purple
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/resilience-anchor.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-resilience-anchor
 description: "Deliberate agent. Use standalone for resilience & moral clarity analysis, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: silver
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/risk-analyst.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-risk-analyst
 description: "Deliberate agent. Use standalone for antifragility & tail risk analysis, or via /deliberate for multi-perspective deliberation."
-model: high
+model_tier: high
 color: black
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/specialists/design-lens.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-design-lens
 description: "Deliberate specialist agent. Activated for design/UX triads. Use standalone for user-centered design & simplicity analysis."
-model: mid
+model_tier: mid
 color: white-smoke
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/specialists/ml-intuition.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-ml-intuition
 description: "Deliberate specialist agent. Activated for AI/ML triads. Use standalone for neural network intuition & empirical ML analysis."
-model: mid
+model_tier: mid
 color: green
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/specialists/safety-frontier.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-safety-frontier
 description: "Deliberate specialist agent. Activated for AI safety triads. Use standalone for scaling frontier & AI safety analysis."
-model: high
+model_tier: high
 color: ice-blue
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/agents/systems-thinker.md

@@ -1,7 +1,7 @@
 ---
 name: deliberate-systems-thinker
 description: "Deliberate agent. Use standalone for systems thinking & feedback loop analysis, or via /deliberate for multi-perspective deliberation."
-model: mid
+model_tier: mid
 color: teal
 tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
 deliberate:

package/configs/defaults.yaml

@@ -8,12 +8,12 @@
 
 tiers:
   anthropic:
-    high: claude-sonnet-4.6
-    mid: claude-sonnet-4.6
-    # NOTE: Opus is NOT used by default. To enable:
-    # 1. Copy provider-model-slots.example.yaml
-    # 2. Set high: claude-opus-4.6
-    # 3. Accept that this will consume significantly more tokens/credits
+    high: opus      # Claude Code shorthand — resolves to claude-opus-4-6
+    mid: sonnet     # Claude Code shorthand — resolves to claude-sonnet-4-6
+    # Opus is used for high-tier agents by default.
+    # At startup, the coordinator asks the user whether to keep opus (high)
+    # or switch all agents to sonnet. The user's choice overrides this mapping
+    # for the session. See SKILL.md Step 0.5 for the selection prompt.
 
   openai:
     high: gpt-5.4

package/package.json

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