humania-org · zevorn · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026
diff --git a/commands/start-rlcr-loop.md b/commands/start-rlcr-loop.md
@@ -3,6 +3,7 @@ description: "Start iterative loop with Codex review"
 argument-hint: "[path/to/plan.md | --plan-file path/to/plan.md] [--max N] [--codex-model MODEL:EFFORT] [--codex-timeout SECONDS] [--track-plan-file] [--push-every-round] [--base-branch BRANCH] [--full-review-round N] [--skip-impl] [--claude-answer-codex] [--agent-teams] [--yolo] [--skip-quiz] [--privacy]"
 allowed-tools:
   - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh:*)"
+  - "Bash(${CLAUDE_PLUGIN_ROOT}/viz/scripts/viz-start.sh:*)"
   - "Read"
   - "Task"
   - "AskUserQuestion"
@@ -114,6 +115,18 @@ If the pre-check passed (or was skipped), and the quiz passed (or was skipped or
 "${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
 ```
 
+### Viz Dashboard Offer
+
+After the setup script completes, check its output for the marker `VIZ_AVAILABLE=`. If found:
+
+1. Use `AskUserQuestion` to ask: "A web visualization dashboard is available for this RLCR session. Would you like to open it?"
+   - Option 1: "Yes, open dashboard" — Run the viz start script shown in the `VIZ_AVAILABLE` line, passing the project path from the `VIZ_PROJECT` line
+   - Option 2: "No, skip" — Print: "You can open the dashboard later with: `/humanize:viz start`"
+
+If the marker is not found (viz not available), skip this step silently.
+
+---
+
 This command starts an iterative development loop where:
 
 1. You execute the implementation plan with task-tag routing

diff --git a/commands/viz.md b/commands/viz.md
@@ -0,0 +1,45 @@
+# Humanize Viz Dashboard
+
+Manage the local web visualization dashboard for RLCR loop sessions.
+
+## Usage
+
+```
+/humanize:viz <subcommand>
+```
+
+### Subcommands
+
+- `start` — Launch the dashboard server (creates venv on first run, opens browser)
+- `stop` — Stop the dashboard server
+- `restart` — Restart the dashboard server
+- `status` — Check if the dashboard server is running
+
+## Implementation
+
+Run the appropriate shell script based on the subcommand:
+
+```bash
+# Determine paths
+VIZ_DIR="${CLAUDE_PLUGIN_ROOT}/viz/scripts"
+PROJECT_DIR="$(pwd)"
+
+# Route subcommand
+case "$1" in
+  start)   bash "$VIZ_DIR/viz-start.sh" "$PROJECT_DIR" ;;
+  stop)    bash "$VIZ_DIR/viz-stop.sh" "$PROJECT_DIR" ;;
+  restart) bash "$VIZ_DIR/viz-restart.sh" "$PROJECT_DIR" ;;
+  status)  bash "$VIZ_DIR/viz-status.sh" "$PROJECT_DIR" ;;
+  *)       bash "$VIZ_DIR/viz-status.sh" "$PROJECT_DIR" ;;
+esac
+```
+
+If no subcommand is provided, default to `status`.
+
+## Requirements
+
+- Python 3 (for Flask server)
+- tmux (for background process management)
+- A `.humanize/` directory in the project (created by RLCR loop)
+
+The first `start` will automatically create a Python venv in `.humanize/viz-venv/` and install dependencies.
diff --git a/scripts/cancel-rlcr-loop.sh b/scripts/cancel-rlcr-loop.sh
@@ -165,6 +165,12 @@ mv "$ACTIVE_STATE_FILE" "$LOOP_DIR/cancel-state.md"
 # Output Result
 # ========================================
 
+# Stop viz dashboard if running
+VIZ_STOP="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/../viz/scripts/viz-stop.sh"
+if [[ -f "$VIZ_STOP" ]]; then
+    bash "$VIZ_STOP" "$PROJECT_ROOT" 2>/dev/null || true
+fi
+
 if [[ "$LOOP_STATE" == "NORMAL_LOOP" ]]; then
     echo "CANCELLED"
     echo "Cancelled RLCR loop (was at round $CURRENT_ROUND of $MAX_ITERATIONS)."

diff --git a/scripts/setup-rlcr-loop.sh b/scripts/setup-rlcr-loop.sh
@@ -1500,6 +1500,15 @@ To cancel: /humanize:cancel-rlcr-loop
 EOF
 fi
 
+# ─── Viz Dashboard Availability Marker ───
+# Output a marker that the command handler can detect to prompt the user
+VIZ_SCRIPT="$SCRIPT_DIR/../viz/scripts/viz-start.sh"
+if [[ -f "$VIZ_SCRIPT" ]] && command -v tmux &>/dev/null && command -v python3 &>/dev/null; then
+    echo ""
+    echo "VIZ_AVAILABLE=$VIZ_SCRIPT"
+    echo "VIZ_PROJECT=$PROJECT_ROOT"
+fi
+
 # Output the initial prompt
 cat "$LOOP_DIR/round-0-prompt.md"
 

diff --git a/skills/humanize-viz/SKILL.md b/skills/humanize-viz/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: humanize-viz
+description: Launch and manage the RLCR loop visualization dashboard — a local web UI showing round nodes, session analytics, and methodology reports
+triggers:
+  - viz
+  - dashboard
+  - visualization
+---
+
+# Humanize Viz
+
+Manage the RLCR loop visualization dashboard.
+
+## How to Use
+
+Route the subcommand to the appropriate viz script:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/viz/scripts/viz-start.sh" "<project_dir>"   # start
+"${CLAUDE_PLUGIN_ROOT}/viz/scripts/viz-stop.sh" "<project_dir>"    # stop
+"${CLAUDE_PLUGIN_ROOT}/viz/scripts/viz-status.sh" "<project_dir>"  # status
+```
+
+Where `<project_dir>` is the current working directory.
+
+### Subcommands
+
+- **start**: Creates a Python venv (first run), installs Flask dependencies, finds an available port (18000-18099), launches the server in a tmux session, and opens the browser.
+- **stop**: Kills the tmux session and cleans up the port file.
+- **status**: Reports whether the server is running and its URL.
+
+### Prerequisites
+
+- Python 3 with venv support
+- tmux
+- A `.humanize/` directory in the project