maxsimcli 3.5.2 → 3.5.3

package/README.md

@@ -2,11 +2,10 @@
 
 # MAXSIM
 
-> ⚠️ **Early Alpha** — MAXSIM is in active early development. APIs, commands, and workflows may change between releases. Use with that in mind and expect rough edges.
+**Your AI coding assistant is forgetting things. MAXSIM fixes that.**
 
-**A meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Gemini CLI, and Codex.**
-
-**Solves context rot — the quality degradation that happens as Claude fills its context window.**
+As Claude fills its context window, code quality degrades — wrong decisions, repeated mistakes, lost intent.
+MAXSIM solves this by offloading work to fresh-context subagents, each with a single responsibility and no memory of the mess before.
 
 [![npm version](https://img.shields.io/npm/v/maxsimcli?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/maxsimcli)
 [![npm downloads](https://img.shields.io/npm/dm/maxsimcli?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/maxsimcli)
@@ -24,129 +23,151 @@
 npx maxsimcli@latest
 ```
 
-**Works on Mac, Windows, and Linux.**
+**Works with Claude Code, OpenCode, Gemini CLI, and Codex — on Mac, Windows, and Linux.**
+
+> ⚠️ **Early Alpha** — APIs, commands, and workflows may change between releases. Expect rough edges.
 
 </div>
 
 ---
 
-## Getting Started
+## The Problem in 30 Seconds
 
-```bash
-npx maxsimcli@latest
-```
+You start a session with Claude. The first 20 minutes are great. Then it starts forgetting your architecture decisions. It repeats the same mistakes. Output quality drops. You start a new session and lose all context.
 
-The installer prompts you to choose:
-1. **Runtime** — Claude Code, OpenCode, Gemini, Codex, or all
-2. **Location** — Global (all projects) or local (current project only)
+This is **context rot** — and it gets worse the bigger your project is.
 
-Verify with:
-- Claude Code / Gemini: `/maxsim:help`
-- OpenCode: `/maxsim-help`
-- Codex: `$maxsim-help`
+**MAXSIM fixes this** by breaking your build into phases, planning each one independently, and running each task in a fresh subagent with only the context it needs. No rot. No drift. Consistent quality from phase 1 to phase 50.
 
-<details>
-<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
-
-```bash
-npx maxsimcli --claude --global    # Claude Code → ~/.claude/
-npx maxsimcli --opencode --global  # OpenCode → ~/.config/opencode/
-npx maxsimcli --gemini --global    # Gemini CLI → ~/.gemini/
-npx maxsimcli --codex --global     # Codex → ~/.codex/
-npx maxsimcli --all --global       # All runtimes
-```
-
-Add `--local` instead of `--global` for project-scoped installs.
+---
 
-</details>
+## Try It in 1 Minute
 
----
+```bash
+# Install
+npx maxsimcli@latest
 
-## Live Dashboard
+# In Claude Code, start a new project:
+/maxsim:new-project
 
-MAXSIM ships with a real-time web dashboard — bundled inside the CLI, no separate setup needed.
+# Or jump straight to planning a phase:
+/maxsim:plan-phase 1
 
-```bash
-npx maxsimcli dashboard
+# Execute it:
+/maxsim:execute-phase 1
 ```
 
-The dashboard opens in your browser and updates instantly as `.planning/` files change via WebSocket.
+That's the loop. Discuss → Plan → Execute → Verify. Each phase is isolated, each task gets a fresh agent, every change gets an atomic commit.
 
-**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
+## Who Is This For
 
-```bash
-npx maxsimcli dashboard --network
-```
+**Individual developers** who want to ship complex projects with Claude without losing coherence over long sessions.
+
+**Teams** who want a shared structure for AI-assisted development — consistent planning, traceable decisions, reproducible phases.
 
-Enables LAN sharing so anyone on your local network (or Tailscale VPN) can open the dashboard in their browser. MAXSIM:
+**AI-heavy projects** (SaaS, CLIs, data pipelines) where a single Claude session can't hold the full project context.
 
-- 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
+**Not a fit if** your project is a single file, a one-shot script, or you just want quick answers from Claude — MAXSIM is a workflow system, not a chat interface.
 
 ---
 
 ## How It Works
 
-### 1. Initialize Project
+MAXSIM installs 30+ slash commands into your AI runtime. Each command is a structured workflow that spawns specialized subagents with fresh context.
 
+### The Core Loop
+
+**1. Initialize your project**
 ```
 /maxsim:new-project
 ```
+Answer a few questions → MAXSIM researches your domain, scopes v1/v2, and creates a phased roadmap in `.planning/`.
 
-Questions → Research → Requirements → Roadmap. One command captures your idea, scopes v1/v2, and creates a phased build plan.
-
-### 2. Discuss Phase
-
+**2. Discuss a phase** _(optional but recommended)_
 ```
 /maxsim:discuss-phase 1
 ```
+Shape the implementation before anything gets built. Surfaces gray areas and locks in decisions.
 
-Shape the implementation before anything gets built. The system identifies gray areas and asks until your vision is clear.
-
-### 3. Plan Phase
-
+**3. Plan the phase**
 ```
 /maxsim:plan-phase 1
 ```
+Research agent investigates. Planner creates atomic task plans. Plan-checker verifies them. You get a PLAN.md ready to execute.
 
-Researches how to implement, creates atomic task plans, and verifies them against requirements.
+**4. Execute**
+```
+/maxsim:execute-phase 1
+```
+Plans run in parallel waves. Each task gets its own fresh executor agent and atomic git commit. Verifier checks the codebase delivered what the phase promised.
 
-### 4. Execute Phase
+**5. Verify**
+```
+/maxsim:verify-work 1
+```
+Walk through testable deliverables. Broken things get fix plans automatically.
 
+**6. Repeat until shipped**
 ```
-/maxsim:execute-phase 1
+/maxsim:complete-milestone
+/maxsim:new-milestone
 ```
 
-Runs plans in parallel waves with fresh context per plan. Each task gets its own atomic commit. Verifies the codebase delivers what the phase promised.
+---
 
-### 5. Verify Work
+## Real-World CLI Flow
 
 ```
-/maxsim:verify-work 1
+You: /maxsim:new-project
+MAXSIM: Tell me about your project...
+You: A CLI tool that converts PDFs to structured JSON using AI
+MAXSIM: [spawns 4 research agents in parallel]
+        [synthesizes findings]
+        [creates REQUIREMENTS.md and ROADMAP.md with 8 phases]
+        Phase 1: PDF parsing + text extraction
+        Phase 2: AI-powered structure detection
+        ...
+
+You: /maxsim:plan-phase 1
+MAXSIM: [research agent investigates pdf libraries]
+        [planner creates 3 atomic task plans]
+        [plan-checker verifies feasibility]
+        Ready. Run /maxsim:execute-phase 1
+
+You: /maxsim:execute-phase 1
+MAXSIM: [wave 1: executor installs dependencies, commits]
+        [wave 2: executor implements PDF reader, commits]
+        [wave 3: executor adds tests, commits]
+        [verifier confirms phase goal achieved]
+        ✓ Phase 1 complete. 3 commits. Dashboard updated.
 ```
 
-Walk through testable deliverables one by one. If something's broken, the system creates fix plans automatically.
+---
 
-### 6. Repeat → Ship
+## Live Dashboard
 
+```bash
+npx maxsimcli dashboard
 ```
-/maxsim:complete-milestone
-/maxsim:new-milestone
+
+Real-time web dashboard — bundled inside the CLI, no separate setup needed.
+
+- **Phase overview** — progress bars, milestone stats, completion percentage
+- **Phase drill-down** — expand phases to see individual tasks with checkboxes
+- **Inline Markdown editor** — edit plan files directly in the browser (CodeMirror, Ctrl+S)
+- **Todos & Blockers** — manage todos and resolve blockers from STATE.md
+- **Auto-launches** during `/maxsim:execute-phase` so you always have a live view
+- **LAN sharing** — share with teammates on the same network
+
+```bash
+npx maxsimcli dashboard --network  # LAN sharing + QR code
 ```
 
-Loop **discuss → plan → execute → verify** until done. Archive the milestone and start the next version.
+![MAXSIM Dashboard — Phase Overview](https://raw.githubusercontent.com/maystudios/maxsimcli/main/assets/dashboard-phases.png)
+
+![MAXSIM Dashboard — Integrated Terminal](https://raw.githubusercontent.com/maystudios/maxsimcli/main/assets/dashboard-terminal.png)
 
 ---
 
@@ -223,6 +244,38 @@ Loop **discuss → plan → execute → verify** until done. Archive the milesto
 
 ---
 
+## Installation
+
+```bash
+npx maxsimcli@latest
+```
+
+The installer prompts you to choose:
+1. **Runtime** — Claude Code, OpenCode, Gemini, Codex, or all
+2. **Location** — Global (all projects) or local (current project only)
+
+Verify with:
+- Claude Code / Gemini: `/maxsim:help`
+- OpenCode: `/maxsim-help`
+- Codex: `$maxsim-help`
+
+<details>
+<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
+
+```bash
+npx maxsimcli --claude --global    # Claude Code → ~/.claude/
+npx maxsimcli --opencode --global  # OpenCode → ~/.config/opencode/
+npx maxsimcli --gemini --global    # Gemini CLI → ~/.gemini/
+npx maxsimcli --codex --global     # Codex → ~/.codex/
+npx maxsimcli --all --global       # All runtimes
+```
+
+Add `--local` instead of `--global` for project-scoped installs.
+
+</details>
+
+---
+
 ## Configuration
 
 Project settings live in `.planning/config.json`, created during `/maxsim:new-project` or editable via `/maxsim:settings`.
@@ -297,7 +350,7 @@ MAXSIM installs three compiled hooks into Claude Code:
 | `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.
+The context bar shows a 10-segment indicator that turns red and blinks above 95% — your signal to spawn a new session before quality degrades.
 
 ---
 
@@ -321,6 +374,18 @@ The context bar in the statusline shows a 10-segment progress indicator that tur
 
 ---
 
+## Contributing
+
+MAXSIM is open source and contributions are welcome.
+
+- **Bug reports:** [Open an issue](https://github.com/maystudios/maxsimcli/issues)
+- **Feature requests:** [Start a discussion](https://github.com/maystudios/maxsimcli/discussions)
+- **PRs:** Fork, branch, and open a pull request — see [CLAUDE.md](CLAUDE.md) for architecture overview
+
+The "runtime" for MAXSIM is the AI itself — commands are markdown prompts in `templates/`, not compiled code. If you want to improve a workflow or add a command, you're editing markdown.
+
+---
+
 ## Acknowledgments
 
 Inspired by [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done).