maxsimcli 3.2.1 → 3.3.0

package/README.md

@@ -55,6 +55,41 @@ Add `--local` instead of `--global` for project-scoped installs.
 
 ---
 
+## Live Dashboard
+
+MAXSIM ships with a real-time web dashboard — bundled inside the CLI, no separate setup needed.
+
+```bash
+npx maxsimcli dashboard
+```
+
+The dashboard opens in your browser and updates instantly as `.planning/` files change via WebSocket.
+
+**Dashboard features:**
+- **Phase overview** — progress bars, milestone stats, and completion percentage
+- **Phase drill-down** — expand any phase to see individual plan tasks with toggleable checkboxes
+- **Inline Markdown editor** — edit plan files directly in the browser (CodeMirror, Ctrl+S to save)
+- **Todos panel** — create, complete, and delete todos
+- **Blockers panel** — view and resolve blockers from STATE.md
+- **STATE.md editor** — edit project state inline
+- **Auto-launches** during `/maxsim:execute-phase` so you always have a live view
+- **Idempotent** — running the command again when a server is already up does nothing
+- **LAN sharing** — share your dashboard with teammates on the same network
+
+### Network / LAN Sharing
+
+```bash
+npx maxsimcli dashboard --network
+```
+
+Enables LAN sharing so anyone on your local network (or Tailscale VPN) can open the dashboard in their browser. MAXSIM:
+
+- Detects your local IP and Tailscale IP automatically
+- Configures firewall rules on Windows (`netsh`) and Linux (`ufw`/`iptables`) with one command
+- Generates a **QR code** so you can open the dashboard on your phone in seconds
+
+---
+
 ## How It Works
 
 ### 1. Initialize Project
@@ -128,51 +163,56 @@ Loop **discuss → plan → execute → verify** until done. Archive the milesto
 |---------|-------------|
 | `/maxsim:progress` | Where am I? What's next? |
 | `/maxsim:help` | Show all commands |
-| `/maxsim:quick` | Ad-hoc task with atomic commits |
+| `/maxsim:quick` | Ad-hoc task with atomic commits (skips optional agents) |
 | `/maxsim:debug [desc]` | Systematic debugging with persistent state |
-| `/maxsim:map-codebase` | Analyze existing codebase |
+| `/maxsim:map-codebase` | Analyze existing codebase with parallel mapper agents |
 | `/maxsim:pause-work` | Create handoff when stopping mid-phase |
 | `/maxsim:resume-work` | Restore from last session |
+| `/maxsim:roadmap` | Display the full project roadmap |
+| `/maxsim:health [--repair]` | Diagnose and auto-repair `.planning/` directory |
+| `/maxsim:update` | Check and install MAXSIM updates |
 
-### Live Dashboard
+### Phase Management
 
 | Command | Description |
 |---------|-------------|
-| `npx maxsimcli dashboard` | Launch the live project dashboard |
+| `/maxsim:add-phase` | Append phase to roadmap |
+| `/maxsim:insert-phase [N]` | Insert urgent work between phases (decimal numbering) |
+| `/maxsim:remove-phase [N]` | Remove future phase, renumber |
+| `/maxsim:list-phase-assumptions [N]` | Surface Claude's assumptions before planning |
+| `/maxsim:research-phase [N]` | Standalone phase research |
 
-MAXSIM includes a real-time web dashboard that shows phase progress, open tasks, blockers,
-and allows inline plan editing.
+### Milestone & Quality
 
-```bash
-npx maxsimcli dashboard
-```
+| Command | Description |
+|---------|-------------|
+| `/maxsim:audit-milestone` | Audit completion against original intent before archiving |
+| `/maxsim:plan-milestone-gaps` | Create phases for all gaps found by audit |
+| `/maxsim:add-tests <N>` | Generate tests from UAT criteria and implementation |
+| `/maxsim:cleanup` | Archive accumulated phase directories |
+
+### Todos
 
-The dashboard auto-detects a free port starting from 3333 and opens your browser.
-It watches `.planning/` for changes and updates in real-time via WebSocket.
+| Command | Description |
+|---------|-------------|
+| `/maxsim:add-todo` | Capture idea as a todo from current conversation |
+| `/maxsim:check-todos` | List pending todos and select one to work on |
 
-- **Auto-installed** during `npx maxsimcli@latest` -- no separate setup needed
-- **Works with both global and local installs**
-- **Auto-opens browser** on launch
-- **Detects running instances** -- won't start a duplicate server
-- **Auto-launches** during `/maxsim:execute-phase`
+### Live Dashboard
 
-**Features:**
-- Real-time updates via WebSocket -- edit a `.planning/` file and the dashboard refreshes instantly
-- Phase overview with animated progress bars and milestone stats
-- Phase drill-down with plan tasks and toggleable checkboxes
-- Inline CodeMirror Markdown editor for plan files (Ctrl+S to save)
-- Todos panel -- create, complete, and manage todos
-- Blockers panel -- view and resolve blockers from STATE.md
-- Swiss Style Design dark theme
+| Command | Description |
+|---------|-------------|
+| `npx maxsimcli dashboard` | Launch the real-time web dashboard |
+| `npx maxsimcli dashboard --network` | Launch with LAN/Tailscale sharing + QR code |
+| `npx maxsimcli dashboard --stop` | Shut down the running dashboard server |
 
-### Phase Management
+### Settings
 
 | Command | Description |
 |---------|-------------|
-| `/maxsim:add-phase` | Append phase to roadmap |
-| `/maxsim:insert-phase [N]` | Insert urgent work between phases |
-| `/maxsim:remove-phase [N]` | Remove future phase, renumber |
-| `/maxsim:settings` | Configure model profile and workflow agents |
+| `/maxsim:settings` | Configure model profile and workflow agent toggles |
+| `/maxsim:set-profile <profile>` | Switch model profile |
+| `/maxsim:reapply-patches` | Reapply local modifications after a MAXSIM update |
 
 ---
 
@@ -180,15 +220,97 @@ It watches `.planning/` for changes and updates in real-time via WebSocket.
 
 Project settings live in `.planning/config.json`, created during `/maxsim:new-project` or editable via `/maxsim:settings`.
 
-**Model Profiles** control which Claude model each agent uses:
+```json
+{
+  "model_profile": "balanced",
+  "branching_strategy": "none",
+  "commit_docs": true,
+  "research": true,
+  "plan_checker": true,
+  "verifier": true,
+  "parallelization": true,
+  "brave_search": false
+}
+```
+
+| Key | Values | Default | Description |
+|-----|--------|---------|-------------|
+| `model_profile` | `quality` \| `balanced` \| `budget` \| `tokenburner` | `balanced` | Which models agents use |
+| `branching_strategy` | `none` \| `phase` \| `milestone` | `none` | Git branch creation per phase or milestone |
+| `commit_docs` | boolean | `true` | Commit documentation changes separately |
+| `research` | boolean | `true` | Enable research agent before planning |
+| `plan_checker` | boolean | `true` | Enable plan-checker agent before execution |
+| `verifier` | boolean | `true` | Enable verifier agent after execution |
+| `parallelization` | boolean | `true` | Enable wave-based parallel plan execution |
+| `brave_search` | boolean | `false` | Enable Brave Search API in research agents |
+
+### Model Profiles
+
+MAXSIM has **4 model profiles** that control which Claude model each of the 11 specialized agents uses:
 
-| Profile | Planning | Execution | Verification |
-|---------|----------|-----------|--------------|
+| Profile | Planners & Executors | Researchers | Orchestrators |
+|---------|---------------------|-------------|---------------|
 | `quality` | Opus | Opus | Sonnet |
-| `balanced` (default) | Opus | Sonnet | Sonnet |
-| `budget` | Sonnet | Sonnet | Haiku |
+| `balanced` *(default)* | Sonnet | Sonnet | Haiku |
+| `budget` | Sonnet | Haiku | Haiku |
+| `tokenburner` | **Opus everywhere** | **Opus everywhere** | **Opus everywhere** |
+
+> `tokenburner` assigns Opus to every single agent. Use it when cost is no concern and you want maximum quality end-to-end.
+
+Switch profiles at any time:
+
+```bash
+/maxsim:set-profile quality
+/maxsim:set-profile balanced
+/maxsim:set-profile budget
+/maxsim:set-profile tokenburner
+```
+
+You can also override individual agents in `config.json`:
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "maxsim-planner": "opus",
+    "maxsim-executor": "opus"
+  }
+}
+```
+
+---
+
+## Hook System
+
+MAXSIM installs three compiled hooks into Claude Code:
+
+| Hook | Function |
+|------|----------|
+| `maxsim-statusline` | Status bar: model · task · directory · context usage bar |
+| `maxsim-context-monitor` | Warns when context window is running low (35% / 25% thresholds) |
+| `maxsim-check-update` | Periodic npm update check with statusline notification |
+
+The context bar in the statusline shows a 10-segment progress indicator that turns red and blinks when context is above 95% — giving you a clear signal to spawn a new session before quality degrades.
+
+---
 
-Switch with `/maxsim:set-profile <profile>`.
+## Agents
+
+11 specialized subagents, each with fresh context and a single responsibility:
+
+| Agent | Role |
+|-------|------|
+| `maxsim-phase-researcher` | Researches how to implement a phase |
+| `maxsim-project-researcher` | Domain research before roadmap creation |
+| `maxsim-research-synthesizer` | Synthesizes parallel research outputs |
+| `maxsim-planner` | Creates executable plans with task breakdown |
+| `maxsim-roadmapper` | Creates project roadmaps with phase breakdown |
+| `maxsim-plan-checker` | Verifies plans will achieve the phase goal |
+| `maxsim-executor` | Implements plans with atomic commits |
+| `maxsim-verifier` | Goal-backward verification after execution |
+| `maxsim-debugger` | Scientific-method debugging with persistent state |
+| `maxsim-integration-checker` | Verifies cross-phase integration and E2E flows |
+| `maxsim-codebase-mapper` | Explores codebase and writes structured analysis |
 
 ---