maxsimcli 5.0.6 → 5.1.0

package/README.md

@@ -1,427 +1,455 @@
-<div align="center">
-
 # MAXSIM
 
-**Your AI coding assistant is forgetting things. MAXSIM fixes that.**
-
-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.
+Meta-prompting and project orchestration system for Claude Code.
 
 [![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)
 [![GitHub stars](https://img.shields.io/github/stars/maystudios/maxsimcli?style=for-the-badge&logo=github&logoColor=white&color=24292e)](https://github.com/maystudios/maxsimcli)
 [![License](https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge)](LICENSE)
 
-<br>
-
 [![Website](https://img.shields.io/badge/Website-maxsimcli.dev-3b82f6?style=for-the-badge&logo=googlechrome&logoColor=white)](https://maxsimcli.dev/)
 [![Docs](https://img.shields.io/badge/Docs-maxsimcli.dev%2Fdocs-6366f1?style=for-the-badge&logo=readthedocs&logoColor=white)](https://maxsimcli.dev/docs)
 
-<br>
-
-```bash
-npx maxsimcli@latest
-```
+---
 
-**Works with Claude Code — on Mac, Windows, and Linux.**
+## The Problem
 
-> **Early Alpha** — APIs, commands, and workflows may change between releases. Expect rough edges.
+You start a Claude Code session. The first 20 minutes go well. Then it forgets your architecture decisions, repeats the same mistakes, and output quality drops. You open a fresh session and lose all context.
 
-</div>
+That is context rot. It gets worse the bigger your project grows.
 
----
+## What MAXSIM Does
 
-## The Problem in 30 Seconds
+MAXSIM breaks your work into phases, plans each one separately, and runs every task in a fresh agent with only the context it needs. Your decisions, requirements, and project state live in a `.planning/` directory. Agents read from it and write back to it. Nothing gets lost between sessions.
 
-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.
+It does not call any LLM API directly. MAXSIM orchestrates Claude Code agents through markdown prompts and workflow files. No API keys, no extra costs beyond your existing Claude Code usage. v6 is Claude Code only.
 
-This is **context rot** — and it gets worse the bigger your project is.
+You install it with one command. It lands in your project's `.claude/` directory and shows up as slash commands in Claude Code.
 
-**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.
+```sh
+npx maxsimcli@latest
+```
 
 ---
 
-## Try It in 1 Minute
+## Quick Start
 
 ```bash
-# Install into your project
 npx maxsimcli@latest
+```
 
-# In Claude Code, initialize:
-/maxsim:init
-
-# Plan the first phase:
-/maxsim:plan 1
+Then inside Claude Code:
 
-# Execute it:
-/maxsim:execute 1
+```
+/maxsim:init        # Set up the planning structure
+/maxsim:plan 1      # Plan phase 1
+/maxsim:execute 1   # Run phase 1
 ```
 
-That's the loop. **Init → Plan → Execute → Verify.** Each phase is isolated, each task gets a fresh agent, every change gets an atomic commit.
+That is the core loop. Init, plan, execute, verify. Each phase is isolated, each task gets a fresh agent, every change gets an atomic commit.
 
 ---
 
-## Who Is This For
+## What You Get
 
-**Individual developers** who want to ship complex projects with Claude without losing coherence over long sessions.
+MAXSIM ships 9 slash commands, 4 agents, 14 skills, and 20 workflows. Here is what that means in practice.
 
-**Teams** who want a shared structure for AI-assisted development — consistent planning, traceable decisions, reproducible phases.
+**Spec-driven development.** All work flows through structured markdown files in `.planning/`. PROJECT.md, ROADMAP.md, STATE.md, REQUIREMENTS.md. The spec is the single source of truth. Agents read from it and update it as they work.
 
-**AI-heavy projects** (SaaS, CLIs, data pipelines) where a single Claude session can't hold the full project context.
+**4 generic agents with clear roles.** Executor builds things. Planner creates plans. Researcher investigates the codebase. Verifier checks the results. Each one does one job.
 
-**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.
+**3 model profiles.** Pick `quality`, `balanced`, or `budget` to control which Claude model tier each agent uses. You can override individual agents too.
 
----
+**GitHub Issues as the source of truth.** Phases become tracking issues. Plans become sub-issues. A 4-column project board (To Do, In Progress, In Review, Done) tracks execution progress.
 
-## How It Works
+**Parallel execution with git worktrees.** Independent plans run concurrently in separate worktrees. MAXSIM groups them into dependency-ordered waves and runs each wave in parallel.
 
-MAXSIM installs 9 slash commands, 19 skills, and an MCP server into Claude Code. Each command is a structured workflow that spawns specialized subagents with fresh context.
+**Review gates you can toggle.** Three gates (spec review, code review, simplify review) can be turned on or off. Each supports a retry limit before it escalates.
 
-### The Core Loop
+**Drift detection.** MAXSIM compares your codebase against the spec and flags divergence before it snowballs.
 
-**1. Initialize your project**
-```
-/maxsim:init
-```
-Answer a few questions → MAXSIM researches your domain, scopes v1/v2, and creates a phased roadmap in `.planning/`. Works for new projects, existing codebases, and milestone transitions.
+---
 
-**2. Plan a phase**
-```
-/maxsim:plan 1
-```
-State-machine workflow: Discussion → Research → Planning. Research agent investigates your domain. Planner creates atomic task plans. Plan-checker verifies them. You get a PLAN.md ready to execute.
+## Installation
 
-**3. Execute**
-```
-/maxsim:execute 1
-```
-Plans run in parallel waves. Each task gets its own fresh executor agent and atomic git commit. Two-stage review (spec compliance → code quality) with automatic retry. Verifier checks the codebase delivered what the phase promised.
+You need Node.js 22+ and Claude Code. Git is required for parallel execution. GitHub CLI (`gh`) is optional, only needed for the Issues integration.
 
-**4. Check progress and continue**
-```
-/maxsim:progress
+```bash
+npx maxsimcli@latest
 ```
-See where you are, what's next. Intelligent routing to the next action — whether that's planning the next phase, executing, or completing a milestone.
 
-**5. Or just let MAXSIM decide**
+Run this from your project root. Everything goes into `.claude/`.
+
+### CLI Flags
+
+| Flag | Alias | What it does |
+|------|-------|-------------|
+| `--uninstall` | | Remove all MAXSIM files from `.claude/` |
+| `--quiet` | `-q` | Suppress output |
+| `--help` | `-h` | Show usage |
+| `--version` | `-v` | Print version |
+
+### What Lands in Your Project
+
+The installer copies these files into `.claude/`:
+
+- 9 slash commands (`/maxsim:init`, `/maxsim:plan`, etc.)
+- 4 agent definitions (executor, planner, researcher, verifier)
+- 14 skills (TDD, debugging, code review, and more)
+- 20 workflow files
+- 15 reference documents, 2 rules files
+- 6 hooks (statusline, update checker, sounds, capture-learnings)
+- 1 tool binary (`maxsim-tools.cjs`)
+- `CLAUDE.md` in your project root
+
+### Directory Layout
+
 ```
-/maxsim:go
+.claude/
+├── commands/maxsim/          # 9 slash commands
+├── maxsim/
+│   ├── bin/maxsim-tools.cjs  # Tool binary
+│   ├── workflows/            # 20 workflows
+│   ├── templates/            # Planning document templates
+│   ├── references/           # 15 reference docs
+│   └── hooks/                # 6 hook scripts (.cjs)
+├── agents/                   # 4 agents
+├── skills/                   # 14 skill directories
+├── rules/                    # 2 rules files
+├── settings.json
+└── CLAUDE.md                 # Generated project context
 ```
-Auto-detects project state, surfaces blockers, and dispatches to the right command. No arguments needed.
 
----
+### Upgrading
 
-## Real-World CLI Flow
+Run `npx maxsimcli@latest` again. The installer overwrites MAXSIM-managed files. Custom skills you have added to `.claude/skills/` and your own agents are not touched.
 
+### Uninstall
+
+```bash
+npx maxsimcli --uninstall
 ```
-You: /maxsim:init
-MAXSIM: Tell me about your project...
-You: A CLI tool that converts PDFs to structured JSON using AI
-MAXSIM: [researches domain, scopes requirements]
-        [creates REQUIREMENTS.md and ROADMAP.md with 8 phases]
-        Phase 1: PDF parsing + text extraction
-        Phase 2: AI-powered structure detection
-        ...
-
-You: /maxsim:plan 1
-MAXSIM: [research agent investigates pdf libraries]
-        [planner creates 3 atomic task plans]
-        [plan-checker verifies feasibility]
-        Ready. Run /maxsim:execute 1
-
-You: /maxsim:execute 1
-MAXSIM: [wave 1: executor installs dependencies, commits]
-        [wave 2: executor implements PDF reader, commits]
-        [wave 3: executor adds tests, commits]
-        [spec review ✓ → code review ✓ → verifier confirms goal achieved]
-        Phase 1 complete. 3 commits.
-```
+
+Removes MAXSIM files from `.claude/`. Your own skills, agents, and Claude Code config stay untouched.
 
 ---
 
 ## Commands
 
-9 commands, each backed by state-machine logic:
-
-| Command | Description |
+| Command | What it does |
 |---------|-------------|
-| `/maxsim:init` | Initialize: new project, existing codebase, or next milestone |
-| `/maxsim:plan [N]` | Discussion → Research → Planning for a phase |
-| `/maxsim:execute <N>` | Execute plans in parallel waves with two-stage review |
-| `/maxsim:progress` | Where am I? What's next? Routes to the right action. |
-| `/maxsim:go` | Auto-detect state and dispatch — zero arguments |
-| `/maxsim:quick [--todo]` | Ad-hoc task with atomic commits, or todo management |
-| `/maxsim:debug [desc]` | Systematic debugging with persistent state |
-| `/maxsim:settings` | Configure model profile and workflow toggles |
-| `/maxsim:help` | Show command reference |
-
-Every command is **idempotent** — you can re-run it and it picks up where you left off. No work gets lost.
+| `/maxsim:init` | Initialize MaxsimCLI in current project with GitHub integration |
+| `/maxsim:plan <phase>` | Plan a specific phase with discussion, research, and task breakdown |
+| `/maxsim:execute <phase>` | Execute all plans in a phase with parallel agents and auto-verification |
+| `/maxsim:go` | Auto-detect project state and execute the right action |
+| `/maxsim:quick <description>` | Quick task — create a GitHub Issue and execute in simplified flow |
+| `/maxsim:progress` | Show project status from GitHub Project Board with next-action recommendation |
+| `/maxsim:debug` | Systematic debugging with reproduce-hypothesize-isolate-verify-fix cycle |
+| `/maxsim:settings` | View and modify MaxsimCLI configuration |
+| `/maxsim:help` | Show available MaxsimCLI commands and usage |
 
----
+## Core Workflow
 
-## Installation
+MAXSIM organizes development into phases. Each phase moves through five stages.
 
-```bash
-npx maxsimcli@latest
-```
+**1. Initialize** (`/maxsim:init`)
 
-Installs locally into your project's `.claude/` directory. This sets up:
+Run once per project. Creates the `.planning/` directory with PROJECT.md, ROADMAP.md, STATE.md, REQUIREMENTS.md, and config files. Optionally connects GitHub Issues and a Project Board for tracking.
 
-- **9 commands** → `.claude/commands/maxsim/`
-- **4 agents** → `.claude/agents/`
-- **19 skills** → `.claude/skills/`
-- **26 workflows** → `.claude/maxsim/workflows/`
-- **3 hooks** → `.claude/hooks/`
-- **MCP server** → `.claude/maxsim/bin/mcp-server.cjs`
+**2. Plan** (`/maxsim:plan <phase>`)
 
-Verify with: `/maxsim:help`
+Three steps happen in sequence. A researcher agent inspects the codebase. You discuss scope and acceptance criteria. A planner agent writes structured plan files into `.planning/phases/<phase>/`.
 
-Subsequent runs of `npx maxsimcli@latest` perform an incremental update — your local modifications are preserved via patch backup.
+**3. Execute** (`/maxsim:execute <phase>`)
 
-<details>
-<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
+An executor agent picks up each plan, makes the code changes, commits atomically, and runs verification before moving on. Independent plans can run in parallel across multiple agents.
+
+**4. Verify**
+
+A verifier agent checks that every plan has a summary, expected artifacts exist, requirements have evidence, and the project passes health checks. Gaps get surfaced before the phase closes.
+
+**5. Complete**
+
+The phase is marked done and progress updates. The next phase becomes active.
+
+Want to plan and execute in one go? Use `/maxsim:go <phase>`. Got a quick fix that does not fit a phase? Use `/maxsim:quick <description>`.
+
+## Phase Lifecycle
 
-```bash
-npx maxsimcli --local     # Project-scoped install → ./.claude/
+```
+empty → discussed → researched → planned → partial → complete
 ```
 
-</details>
+| State | Meaning |
+|-------|---------|
+| `empty` | Phase directory exists, no work started |
+| `discussed` | Requirements gathered |
+| `researched` | Codebase research done |
+| `planned` | Plan files written |
+| `partial` | Execution started but not finished |
+| `complete` | All plans executed and verified |
 
-**Requirements:** Node.js >= 22, `gh` CLI (for GitHub Issues integration)
+Phase numbers are flexible. Integer (`01`, `02`), letter suffixes for parallel tracks (`02A`, `02B`), and decimal inserts (`02.1`) all work.
 
 ---
 
-## Configuration
+## Agents
 
-Project settings live in `.planning/config.json`, created during `/maxsim:init` or editable via `/maxsim:settings`.
+4 agents, each with one job:
 
-```json
-{
-  "model_profile": "balanced",
-  "branching_strategy": "none",
-  "commit_docs": true,
-  "search_gitignored": false,
-  "parallelization": true,
-  "worktree_mode": "auto",
-  "max_parallel_agents": 10,
-  "brave_search": false,
-  "workflow": {
-    "research": true,
-    "plan_checker": true,
-    "verifier": true
-  },
-  "review": {
-    "spec_review": true,
-    "code_review": true,
-    "simplify_review": true,
-    "retry_limit": 3
-  }
-}
-```
+| Agent | Role | What it does |
+|-------|------|-------------|
+| Executor | Builds things | Reads plans, makes code changes, commits atomically, handles deviations |
+| Planner | Creates plans | Turns research into structured PLAN.md files with tasks, waves, and dependencies |
+| Researcher | Investigates | Explores the codebase, gathers technical context, can use Brave Search |
+| Verifier | Checks results | Validates plan structure, artifacts, requirement evidence, commit integrity |
 
-| 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 |
-| `parallelization` | boolean | `true` | Enable wave-based parallel plan execution |
-| `worktree_mode` | `auto` \| `always` \| `never` | `auto` | Git worktree isolation for parallel agents |
-| `workflow.research` | boolean | `true` | Enable research agent before planning |
-| `workflow.plan_checker` | boolean | `true` | Enable plan-checker verification before execution |
-| `workflow.verifier` | boolean | `true` | Enable verifier agent after execution |
-| `review.spec_review` | boolean | `true` | Spec compliance review after each plan |
-| `review.code_review` | boolean | `true` | Code quality review after each plan |
-| `review.simplify_review` | boolean | `true` | Simplification pass after reviews |
-| `review.retry_limit` | number | `3` | Max review cycle retries before escalation |
-| `brave_search` | boolean | `false` | Enable Brave Search API in research agents |
+Each agent is a markdown file at `.claude/agents/{name}.md` with YAML frontmatter for tools, model tier, and preloaded skills.
 
 ### Model Profiles
 
-4 profiles control which Claude model each agent type uses:
+Set `model_profile` in `.planning/config.json` to control which Claude model each agent uses:
 
-| Agent | `quality` | `balanced` | `budget` | `tokenburner` |
-|-------|-----------|------------|----------|---------------|
-| Executor | Opus | Sonnet | Sonnet | Opus |
-| Planner | Opus | Opus | Sonnet | Opus |
-| Researcher | Opus | Sonnet | Haiku | Opus |
-| Verifier | Sonnet | Sonnet | Haiku | Opus |
+| Agent Type | `quality` | `balanced` (default) | `budget` |
+|------------|-----------|---------------------|----------|
+| planner | opus | opus | sonnet |
+| executor | opus | sonnet | sonnet |
+| researcher | opus | sonnet | haiku |
+| verifier | sonnet | sonnet | haiku |
 
-> `tokenburner` assigns Opus to every agent. Use it when cost is no concern and you want maximum quality end-to-end.
+`opus` maps to `inherit`, meaning it uses your Claude Code session model. `sonnet` and `haiku` are passed directly to subagent invocations.
 
-Switch profiles at any time:
+### Per-Agent Overrides
 
-```
-/maxsim:settings
-```
-
-You can also override individual agents in `config.json`:
+Override individual agents regardless of profile:
 
 ```json
 {
   "model_profile": "balanced",
   "model_overrides": {
-    "planner": "opus",
-    "executor": "opus"
+    "executor": "opus",
+    "researcher": "haiku"
   }
 }
 ```
 
 ---
 
-## Agents
+## GitHub Integration
 
-4 consolidated generic agents, each spawned with fresh context and a single responsibility:
+MAXSIM tracks phase and plan progress through GitHub Issues. Your `.planning/` files hold project-level documents (roadmap, state, config). Execution progress lives in GitHub. GitHub CLI (`gh`) and a GitHub-hosted repository are required for this feature.
 
-| Agent | Role | Replaces (v4.x) |
-|-------|------|------------------|
-| `executor` | Implements plans with atomic commits and deviation handling | maxsim-executor |
-| `planner` | Creates PLAN.md files with task breakdown and goal-backward verification | maxsim-planner, maxsim-roadmapper, maxsim-plan-checker |
-| `researcher` | Investigates domains with source evaluation and confidence levels | maxsim-phase-researcher, maxsim-project-researcher, maxsim-research-synthesizer, maxsim-codebase-mapper |
-| `verifier` | Verifies work against specs with fresh evidence and hard gates | maxsim-verifier, maxsim-code-reviewer, maxsim-spec-reviewer, maxsim-debugger, maxsim-integration-checker, maxsim-drift-checker |
+### Setup
 
-Agents communicate through structured handoff contracts. The orchestrator (your main Claude Code session) carries specialization context — agents themselves are generic. Subagents cannot spawn other subagents; all coordination is orchestrator-mediated.
+Configured during `/maxsim:init`:
 
----
+1. Creates a "MAXSIM Task Board" project with 4 columns (To Do, In Progress, In Review, Done)
+2. Creates labels: `phase` (purple), `task` (blue), `blocker` (red)
+3. Optionally creates a GitHub Milestone
 
-## Skills
+### How It Works
+
+Each phase gets a tracking issue. Each plan becomes a sub-issue linked to its phase. Plan content goes into structured comments. Completion data (commit SHA, files changed) gets posted to task issues. Progress is computed from open vs closed sub-issue counts.
 
-19 built-in skills provide on-demand context to agents. Skills auto-trigger based on context — they're not optional guidelines, they're active workflow enforcement.
-
-### Protocol Skills
-| Skill | Description |
-|-------|-------------|
-| `handoff-contract` | Structured format for agent returns |
-| `verification-gates` | Hard gates with evidence requirements |
-| `input-validation` | Input validation patterns |
-
-### Methodology Skills
-| Skill | Description |
-|-------|-------------|
-| `evidence-collection` | How to gather and validate evidence |
-| `research-methodology` | How to research effectively |
-| `sdd` | Spec-driven development — fresh agent per task |
-| `tdd` | Test-driven development — failing test before implementation |
-| `systematic-debugging` | Reproduce → hypothesize → isolate → verify → fix |
-| `brainstorming` | Multi-approach exploration before design decisions |
-| `code-review` | Security, interfaces, error handling, test coverage |
-| `verification-before-completion` | 5-step verification with evidence requirements |
-
-### Execution Skills
-| Skill | Description |
-|-------|-------------|
-| `maxsim-batch` | Parallel worktree execution for independent work units |
-| `maxsim-simplify` | Review changed code for reuse, quality, and efficiency |
-| `commit-conventions` | Project git commit standards |
-
-### Reference Skills
-| Skill | Description |
-|-------|-------------|
-| `agent-system-map` | Agent capabilities and tool mappings |
-| `tool-priority-guide` | Tool usage priority and best practices |
-| `memory-management` | Persistent memory across sessions |
-| `roadmap-writing` | Guided roadmap and requirements authoring |
-| `using-maxsim` | Guide for effective MAXSIM usage |
+A local cache file maps phase numbers to GitHub issue numbers and is rebuilt from GitHub when needed.
+
+### Tool Commands
+
+| Subcommand | What it does |
+|---|---|
+| `github setup` | Create board, labels, milestone |
+| `github create-phase` | Create a phase tracking issue |
+| `github create-task` / `batch-create-tasks` | Create task sub-issues |
+| `github move-issue` | Move issue between board columns |
+| `github status` | Show progress and board overview |
+| `github sync-check` | Verify local cache matches GitHub |
+| `github all-progress` | Show progress for all phases |
 
 ---
 
-## Hook System
+## Configuration
+
+Project config lives in `.planning/config.json`, created during `/maxsim:init`.
+
+### Full Reference
+
+| Setting | Type | Default | What it does |
+|---------|------|---------|-------------|
+| `execution.modelProfile` | `'quality' \| 'balanced' \| 'budget'` | `'balanced'` | Model tier for all agents |
+| `model_overrides` | `Record<AgentType, ModelTier>` | | Per-agent model overrides |
+| `execution.parallelism.maxAgentsPerWave` | `number` | `3` | Cap on concurrent agents per wave |
+| `execution.parallelism.maxRetries` | `number` | `3` | Max retries per failed plan |
+| `execution.parallelism.competitionStrategy` | `'none' \| 'quick' \| 'standard' \| 'deep'` | `'standard'` | Parallel competition strategy |
+| `execution.verification.strictMode` | `boolean` | `true` | Enforce all verification gates |
+| `execution.verification.requireCodeReview` | `boolean` | `true` | Code review gate |
+| `execution.verification.autoResolveConflicts` | `boolean` | `true` | Auto-resolve merge conflicts |
+| `worktrees.basePath` | `string` | `'.maxsim-worktrees/'` | Worktree base directory |
+| `worktrees.autoCleanup` | `boolean` | `true` | Remove worktrees after completion |
+| `worktrees.branchPrefix` | `string` | `'maxsim/'` | Branch prefix for worktree branches |
+| `automation.autoCommitOnSuccess` | `boolean` | `true` | Auto-commit `.planning/` changes |
+| `automation.conventionalCommits` | `boolean` | `true` | Enforce conventional commit format |
+| `planning.commit_docs` | `boolean` | `true` | Commit planning artifacts to git |
+| `planning.search_gitignored` | `boolean` | `false` | Include gitignored files in searches |
+| `git.branching_strategy` | `'none' \| 'phase' \| 'milestone'` | `'none'` | Git branching strategy |
+| `git.phase_branch_template` | `string` | `'maxsim/phase-{phase}-{slug}'` | Branch name template for phases |
+| `git.milestone_branch_template` | `string` | `'maxsim/{milestone}-{slug}'` | Branch name template for milestones |
+| `workflow.research` | `boolean` | `true` | Run research before planning |
+| `workflow.plan_checker` | `boolean` | `true` | Run plan checker agent |
+| `workflow.verifier` | `boolean` | `true` | Run verifier after execution |
+
+### Config Example
+
+```json
+{
+  "execution": {
+    "modelProfile": "balanced",
+    "parallelism": {
+      "maxAgentsPerWave": 3,
+      "maxRetries": 3,
+      "competitionStrategy": "standard"
+    },
+    "verification": {
+      "strictMode": true,
+      "requireCodeReview": true,
+      "autoResolveConflicts": true
+    }
+  },
+  "worktrees": {
+    "basePath": ".maxsim-worktrees/",
+    "autoCleanup": true,
+    "branchPrefix": "maxsim/"
+  },
+  "automation": {
+    "autoCommitOnSuccess": true,
+    "conventionalCommits": true
+  }
+}
+```
+
+### User-Level Defaults
 
-3 compiled hooks installed into Claude Code:
+Put global defaults in `~/.maxsim/defaults.json`. These merge with hardcoded defaults when a new `.planning/config.json` gets created. They do not override existing project configs.
 
-| Hook | Function |
-|------|----------|
-| `maxsim-statusline` | Status bar: model · task · directory · context usage bar (blinks red above 95%) |
-| `maxsim-sync-reminder` | Prompts to sync when `.planning/` files change (PostToolUse hook) |
-| `maxsim-check-update` | Periodic npm update check with automatic backup before updating |
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `BRAVE_API_KEY` | Brave Search API key (or put it in `~/.maxsim/brave_api_key`) |
+| `MAXSIM_DEBUG` | Verbose debug logging to stderr |
+| `MAXSIM_SOUND=0` | Turn off notification sounds |
+| `CI=true` | Suppress sounds in CI |
+| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | Enable Agent Teams for parallel execution |
 
 ---
 
-## MCP Server
+## Skills
 
-MAXSIM installs an MCP (Model Context Protocol) server that exposes project tools directly to Claude Code. The server is auto-configured during installation via `.mcp.json`.
+Skills are reusable prompt modules that agents load on demand. Each skill is a `SKILL.md` file with YAML frontmatter and a markdown body.
 
-**Exposed tools:**
-- **Phase operations** — list, add, complete, insert, and remove phases
-- **State management** — read/update STATE.md (decisions, blockers, metrics)
-- **Todo operations** — create, list, and complete todos
-- **Roadmap analysis** — phase status, progress calculation, missing details
-- **Context loading** — intelligent file selection based on task topic
-- **Config management** — read/write `.planning/config.json` settings
-- **GitHub integration** — issue creation, board queries, status tracking
+### Built-in Skills (14)
 
-The MCP server runs as a stdio process managed by Claude Code — no manual startup needed.
+| Skill | Category | What it does |
+|-------|----------|-------------|
+| `tdd` | Task | Test-driven development, Red-Green-Refactor cycle with atomic commits |
+| `systematic-debugging` | Methodology | Root-cause analysis: reproduce, hypothesize, isolate, verify, fix |
+| `verification` | Methodology | Evidence-based verification with quality gates and anti-rationalization enforcement |
+| `maxsim-simplify` | Task | Reviews changed code for reuse opportunities and unnecessary complexity |
+| `code-review` | Task | Checks security, interfaces, error handling, test coverage |
+| `project-memory` | Task | GitHub-native persistence for learnings, decisions, and patterns |
+| `using-maxsim` | Task | Routes work through MaxsimCLI commands based on project state |
+| `brainstorming` | Task | Explores multiple approaches with structured comparison before committing |
+| `roadmap-writing` | Task | Creates phased roadmaps with dependency graphs and GitHub Milestone structure |
+| `maxsim-batch` | Task | Decomposes tasks for parallel worktree execution |
+| `commit-conventions` | Convention | Conventional commit format and version trigger rules |
+| `github-operations` | Reference | Unified GitHub interaction: artifacts, comments, CLI, issue lifecycle |
+| `handoff-contract` | Protocol | Agent-to-agent handoff protocol |
+| `research` | Methodology | Systematic investigation using parallel agents and source hierarchy |
 
----
+### Skill Types
 
-## Project Structure
+Protocol skills load automatically (handoff-contract). Methodology skills guide how agents think. Task skills are user-invocable workflows like TDD or code review. Reference skills provide static information.
 
-When you initialize a project, MAXSIM creates a `.planning/` directory:
+### Managing Skills
 
-```
-.planning/
-├── config.json           # Model profile, workflow flags, branching strategy
-├── PROJECT.md            # Vision and scope (always loaded)
-├── REQUIREMENTS.md       # v1/v2/out-of-scope requirements
-├── ROADMAP.md            # Phase structure with goals and dependencies
-├── STATE.md              # Memory: decisions, blockers, metrics, session history
-├── phases/
-│   └── 01-Foundation/
-│       ├── 01-CONTEXT.md        # User decisions from discussion
-│       ├── 01-RESEARCH.md       # Research findings
-│       ├── 01-01-PLAN.md        # Task plan (numbered per attempt)
-│       ├── 01-01-SUMMARY.md     # Completion record with evidence
-│       ├── 01-VERIFICATION.md   # Verification results
-│       └── 01-UAT.md            # User acceptance tests
-└── todos/
-    ├── pending/
-    └── completed/
-```
+Built-in skills update when you upgrade MAXSIM. Custom skills you place in `.claude/skills/` are preserved.
 
 ---
 
-## Architecture (For Contributors)
+## Parallel Execution
 
-MAXSIM is a three-layer system where commands are markdown prompts, not executable code:
+MAXSIM can run multiple plans at the same time using git worktrees. Each plan gets its own isolated working directory.
 
-```
-templates/commands/maxsim/*.md  ← User-facing commands (9 files, user types /maxsim:*)
-templates/workflows/*.md        ← Implementation workflows (26 files, loaded via @path)
-templates/agents/*.md           ← Subagent prompts (4 agents)
-templates/skills/*/             ← On-demand context modules (19 skills)
-```
+Plans within a phase are grouped into waves. Wave 1 runs first, wave 2 starts after wave 1 finishes. Plans in the same wave run in parallel if they do not touch the same files.
 
-Commands load workflows which spawn agents. Agents call `cli.cjs` (the tools router) via the Bash tool. The "runtime" for MAXSIM is the AI itself.
+Each parallel plan gets a worktree at `.maxsim-worktrees/{planId}/` on its own branch. Worktrees are cleaned up automatically after completion.
 
-The npm package (`maxsimcli`) ships all of this as an installer that copies files into `.claude/`. If you want to improve a workflow or add a command, you're editing markdown.
+### When It Activates
 
-**Tech stack:** TypeScript 5.9, Node.js 22+, npm workspaces monorepo, tsdown bundler
+Parallel execution kicks in when a wave has at least `parallelization.min_plans_for_parallel` plans (default 2). `execution.parallelism.maxAgentsPerWave` caps concurrent agents per wave (default 3). `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set automatically in `settings.json` during installation.
 
-See [CLAUDE.md](CLAUDE.md) for the full architecture guide.
+Before running in parallel, MAXSIM checks that plans do not modify the same files. If there is a conflict, it falls back to sequential mode.
 
 ---
 
-## Contributing
+## Hooks
+
+MAXSIM installs 6 Claude Code hooks:
+
+| Hook | Event | What it does |
+|------|-------|-------------|
+| `maxsim-statusline` | `statusLine` | Shows model tier, phase number, board column, and milestone progress |
+| `maxsim-check-update` | `SessionStart` | Checks npm for new MAXSIM versions in the background |
+| `maxsim-notification-sound` | `Notification` | Plays a sound when Claude asks you a question |
+| `maxsim-stop-sound` | `Stop` | Plays a sound when Claude finishes |
+| `maxsim-capture-learnings` | `Stop` | Appends a dated learning entry to `.claude/agent-memory/` from the last 5 commits |
+| `maxsim-sync-reminder` | `PostToolUse` | No-op stub, kept for structural reasons |
 
-MAXSIM is open source and contributions are welcome.
+### Statusline
+
+```
+[update] model | P{N} {BoardColumn} | milestone: pct% | dirname
+```
 
-- **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
+Sounds are suppressed when `MAXSIM_SOUND=0`, `CI=true`, or `SSH_CONNECTION` is set. On Windows sounds play as .wav via PowerShell, on macOS as .aiff via afplay, on Linux it falls back to a terminal bell.
 
 ---
 
-## Acknowledgments
+## Architecture
 
-Inspired by [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done).
+### Monorepo
 
-## License
+npm workspaces monorepo with two packages:
 
-MIT License. See [LICENSE](LICENSE) for details.
+```
+maxsim/
+├── packages/
+│   ├── cli/          # maxsimcli, the published npm package
+│   └── website/      # maxsimcli.dev, project website (private)
+├── templates/        # Markdown assets copied into dist during build
+└── package.json      # Workspace root
+```
 
----
+Only `packages/cli` gets published to npm as `maxsimcli`.
 
-<div align="center">
+### Build
+
+```bash
+npm run build        # tsdown (CJS) then copy-assets into dist/
+npm test             # Vitest unit tests
+npm run e2e          # Vitest e2e tests
+npm run lint         # Biome
+```
 
-**Built and maintained by [MayStudios](https://github.com/maystudios).**
+tsdown compiles TypeScript to CJS. copy-assets bundles templates, workflows, agents, skills, hooks, and references into `dist/assets/`. semantic-release handles versioning and npm publish on push to `main`.
+
+## Contributing
+
+Conventional commits. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+- `fix:` triggers a patch release
+- `feat:` triggers a minor release
+- `feat!:` or `BREAKING CHANGE:` triggers a major release
+
+## License
 
-</div>
+[MIT](LICENSE)