@faviovazquez/deliberate 0.2.7 → 0.2.9

package/BRAINSTORM.md

@@ -293,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,19 @@ 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.9] - 2026-04-04
+
+### Added
+- `README.md`: Added local install path examples for `start-server.sh` / `stop-server.sh` under "Starting and stopping the server" — covers Claude Code global/local, Windsurf global/local, and Cursor local install paths.
+- `SKILL.md`: Step 5 now always offers the visual companion before starting the deliberation, even when `--visual` was not passed. Mirrors the behavior already present in BRAINSTORM.md Phase 2. The offer is a standalone message; the user can accept (y) or decline (N/Enter).
+
+## [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

package/README.md

@@ -479,6 +479,49 @@ 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:
+
+**Claude Code — global install:**
+```bash
+bash ~/.claude/skills/deliberate/scripts/start-server.sh --project-dir .
+bash ~/.claude/skills/deliberate/scripts/stop-server.sh
+```
+
+**Claude Code — local install:**
+```bash
+bash .claude/skills/deliberate/scripts/start-server.sh --project-dir .
+bash .claude/skills/deliberate/scripts/stop-server.sh
+```
+
+**Windsurf — global install:**
+```bash
+bash ~/.codeium/windsurf/skills/deliberate/scripts/start-server.sh --project-dir .
+bash ~/.codeium/windsurf/skills/deliberate/scripts/stop-server.sh
+```
+
+**Windsurf — local install:**
+```bash
+bash .windsurf/skills/deliberate/scripts/start-server.sh --project-dir .
+bash .windsurf/skills/deliberate/scripts/stop-server.sh
+```
+
+**Cursor — local install:**
+```bash
+bash .cursor/skills/deliberate/scripts/start-server.sh --project-dir .
+bash .cursor/skills/deliberate/scripts/stop-server.sh
+```
+
 ---
 
 ## Platforms

package/SKILL.md

@@ -207,12 +207,29 @@ Use the resolved model map from Step 0.5 (Claude Code) or the active context mod
 - `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)
+### Step 5: Visual Companion Offer
 
-If `--visual` flag is set, or if the user has previously accepted the visual companion in this session:
-1. Launch `scripts/start-server.sh --project-dir {project_root}`
+If `--visual` flag is set, skip directly to launching the server (step 5c below).
+
+Otherwise, **always offer the visual companion** before starting the deliberation:
+
+```
+Would you like to follow the deliberation in real time in your browser?
+The visual companion shows agent positions, agreement/disagreement maps,
+and verdict formation as it happens. (Requires opening a local URL)
+
+Open visual companion? (y/N)
+```
+
+**This offer MUST be its own message.** Wait for the user's response before continuing.
+
+- If **yes**: proceed to launch (5c)
+- If **no** or Enter: proceed without visual companion
+
+**5c — Launch:**
+1. Run `scripts/start-server.sh --project-dir {project_root}`
 2. Save `screen_dir` and `state_dir` from the response
-3. Tell user to open the URL
+3. Tell the user to open the URL
 4. Visual companion will be updated after each round
 
 ### Step 6: Round 1 -- Independent Analysis
@@ -342,6 +359,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/package.json

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