@faviovazquez/deliberate 0.2.8 → 0.2.10

package/BRAINSTORM.md

@@ -302,7 +302,7 @@ 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 **Y** or Enter: run `scripts/stop-server.sh {session_dir}` where `{session_dir}` is the `session_dir` value returned by `start-server.sh` in Phase 2. This stops the exact session that was started.
 - 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.

package/CHANGELOG.md

@@ -5,6 +5,12 @@ 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

package/README.md

@@ -490,22 +490,41 @@ 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:
+If you ever need to manage the server manually, run these commands **from your project root**.
 
+- `start-server.sh --project-dir .` stores the session under `.deliberate/companion/` in your project. This is what allows `stop-server.sh` to find and kill it automatically.
+- `stop-server.sh` takes no arguments — it scans `.deliberate/companion/` and `/tmp/` to find running sessions and kills them.
+
+**Claude Code — global install:**
 ```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:
+**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
@@ -351,7 +368,7 @@ 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 **Y** or Enter: run `scripts/stop-server.sh {session_dir}` where `{session_dir}` is the `session_dir` value returned by `start-server.sh` in Step 5c. This stops the exact session that was started.
 - 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.

package/package.json

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

package/scripts/stop-server.sh

@@ -1,42 +1,90 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Stop a deliberate visual companion server session
+# Stop a deliberate visual companion server session.
+#
+# Usage:
+#   stop-server.sh                  Auto-discover and stop all running sessions
+#   stop-server.sh SESSION_DIR      Stop a specific session (coordinator use)
 
-if [[ $# -lt 1 ]]; then
-  echo "Usage: stop-server.sh SESSION_DIR" >&2
-  exit 1
-fi
+stop_session() {
+  local SESSION_DIR="$1"
+  local STATE_DIR="$SESSION_DIR/state"
+  local SERVER_JS="$SESSION_DIR/server.js"
+
+  if [[ ! -d "$SESSION_DIR" ]]; then
+    echo "Session directory not found: $SESSION_DIR" >&2
+    return 1
+  fi
+
+  local PIDS
+  PIDS=$(pgrep -f "$SERVER_JS" 2>/dev/null || true)
+
+  if [[ -n "$PIDS" ]]; then
+    echo "$PIDS" | xargs kill 2>/dev/null || true
+    echo "Server stopped (session: $SESSION_DIR)"
+  else
+    echo "No running server found for session: $SESSION_DIR"
+  fi
+
+  # Mark as stopped
+  mkdir -p "$STATE_DIR"
+  echo "$(date +%s)" > "$STATE_DIR/server-stopped"
 
-SESSION_DIR="$1"
-STATE_DIR="$SESSION_DIR/state"
+  # Clean up /tmp sessions only
+  if [[ "$SESSION_DIR" == /tmp/* ]]; then
+    rm -rf "$SESSION_DIR"
+    echo "Temporary session cleaned up."
+  fi
+}
 
-if [[ ! -d "$SESSION_DIR" ]]; then
-  echo "Session directory not found: $SESSION_DIR" >&2
-  exit 1
+# ── With explicit SESSION_DIR arg (coordinator use) ────────────────────────
+if [[ $# -ge 1 ]]; then
+  stop_session "$1"
+  exit 0
 fi
 
-# Read server info to find the process
-if [[ -f "$STATE_DIR/server-info" ]]; then
-  # Find the node process serving this session
-  SERVER_JS="$SESSION_DIR/server.js"
+# ── No args: auto-discover all running deliberate companion sessions ────────
+STOPPED=0
+
+# Search project-local sessions (.deliberate/companion/)
+for SERVER_JS in .deliberate/companion/*/server.js; do
+  [[ -f "$SERVER_JS" ]] || continue
+  SESSION_DIR="$(dirname "$SERVER_JS")"
   PIDS=$(pgrep -f "$SERVER_JS" 2>/dev/null || true)
+  if [[ -n "$PIDS" ]]; then
+    echo "$PIDS" | xargs kill 2>/dev/null || true
+    echo "Server stopped (session: $SESSION_DIR)"
+    mkdir -p "$SESSION_DIR/state"
+    echo "$(date +%s)" > "$SESSION_DIR/state/server-stopped"
+    STOPPED=$((STOPPED + 1))
+  fi
+done
 
+# Search /tmp sessions
+for SERVER_JS in /tmp/deliberate-companion/*/server.js; do
+  [[ -f "$SERVER_JS" ]] || continue
+  SESSION_DIR="$(dirname "$SERVER_JS")"
+  PIDS=$(pgrep -f "$SERVER_JS" 2>/dev/null || true)
+  if [[ -n "$PIDS" ]]; then
+    echo "$PIDS" | xargs kill 2>/dev/null || true
+    echo "Server stopped (session: $SESSION_DIR)"
+    rm -rf "$SESSION_DIR"
+    echo "Temporary session cleaned up."
+    STOPPED=$((STOPPED + 1))
+  fi
+done
+
+# Fallback: kill any node process running a deliberate server.js
+if [[ "$STOPPED" -eq 0 ]]; then
+  PIDS=$(pgrep -f "deliberate-companion.*/server.js" 2>/dev/null || true)
   if [[ -n "$PIDS" ]]; then
     echo "$PIDS" | xargs kill 2>/dev/null || true
     echo "Server stopped."
-  else
-    echo "No running server found for this session."
+    STOPPED=$((STOPPED + 1))
   fi
 fi
 
-# Mark as stopped
-echo "$(date +%s)" > "$STATE_DIR/server-stopped"
-
-# Clean up /tmp sessions only
-if [[ "$SESSION_DIR" == /tmp/* ]]; then
-  rm -rf "$SESSION_DIR"
-  echo "Temporary session cleaned up."
-else
-  echo "Session files preserved at: $SESSION_DIR"
+if [[ "$STOPPED" -eq 0 ]]; then
+  echo "No running deliberate visual companion server found."
 fi