maxsimcli 5.0.6 → 5.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +314 -288
- package/dist/assets/CHANGELOG.md +7 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,427 +1,453 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
1
|
# MAXSIM
|
|
4
2
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
As Claude fills its context window, code quality degrades — wrong decisions, repeated mistakes, lost intent.
|
|
8
|
-
MAXSIM solves this by offloading work to fresh-context subagents, each with a single responsibility and no memory of the mess before.
|
|
3
|
+
Your AI coding assistant forgets things between sessions. MAXSIM keeps it on track.
|
|
9
4
|
|
|
10
5
|
[](https://www.npmjs.com/package/maxsimcli)
|
|
11
6
|
[](https://www.npmjs.com/package/maxsimcli)
|
|
12
7
|
[](https://github.com/maystudios/maxsimcli)
|
|
13
8
|
[](LICENSE)
|
|
14
9
|
|
|
15
|
-
<br>
|
|
16
|
-
|
|
17
10
|
[](https://maxsimcli.dev/)
|
|
18
11
|
[](https://maxsimcli.dev/docs)
|
|
19
12
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
npx maxsimcli@latest
|
|
24
|
-
```
|
|
13
|
+
---
|
|
25
14
|
|
|
26
|
-
|
|
15
|
+
## The Problem
|
|
27
16
|
|
|
28
|
-
|
|
17
|
+
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.
|
|
29
18
|
|
|
30
|
-
|
|
19
|
+
That is context rot. It gets worse the bigger your project grows.
|
|
31
20
|
|
|
32
|
-
|
|
21
|
+
## What MAXSIM Does
|
|
33
22
|
|
|
34
|
-
|
|
23
|
+
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.
|
|
35
24
|
|
|
36
|
-
|
|
25
|
+
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.
|
|
37
26
|
|
|
38
|
-
|
|
27
|
+
You install it with one command. It lands in your project's `.claude/` directory and shows up as slash commands in Claude Code.
|
|
39
28
|
|
|
40
|
-
|
|
29
|
+
```sh
|
|
30
|
+
npx maxsimcli@latest
|
|
31
|
+
```
|
|
41
32
|
|
|
42
33
|
---
|
|
43
34
|
|
|
44
|
-
##
|
|
35
|
+
## Quick Start
|
|
45
36
|
|
|
46
37
|
```bash
|
|
47
|
-
# Install into your project
|
|
48
38
|
npx maxsimcli@latest
|
|
39
|
+
```
|
|
49
40
|
|
|
50
|
-
|
|
51
|
-
/maxsim:init
|
|
52
|
-
|
|
53
|
-
# Plan the first phase:
|
|
54
|
-
/maxsim:plan 1
|
|
41
|
+
Then inside Claude Code:
|
|
55
42
|
|
|
56
|
-
|
|
57
|
-
/maxsim:
|
|
43
|
+
```
|
|
44
|
+
/maxsim:init # Set up the planning structure
|
|
45
|
+
/maxsim:plan 1 # Plan phase 1
|
|
46
|
+
/maxsim:execute 1 # Run phase 1
|
|
58
47
|
```
|
|
59
48
|
|
|
60
|
-
That
|
|
49
|
+
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.
|
|
61
50
|
|
|
62
51
|
---
|
|
63
52
|
|
|
64
|
-
##
|
|
53
|
+
## What You Get
|
|
65
54
|
|
|
66
|
-
|
|
55
|
+
MAXSIM ships 9 slash commands, 4 agents, 21 skills, and 23 workflows. Here is what that means in practice.
|
|
67
56
|
|
|
68
|
-
**
|
|
57
|
+
**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.
|
|
69
58
|
|
|
70
|
-
**
|
|
59
|
+
**4 agents with clear roles.** Executor builds things. Planner creates plans. Researcher investigates the codebase. Verifier checks the results. Each one does one job.
|
|
71
60
|
|
|
72
|
-
**
|
|
61
|
+
**4 model profiles.** Pick `quality`, `balanced`, `budget`, or `tokenburner` to control which Claude model tier each agent uses. You can override individual agents too.
|
|
73
62
|
|
|
74
|
-
|
|
63
|
+
**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) mirrors your `.planning/` state.
|
|
75
64
|
|
|
76
|
-
|
|
65
|
+
**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.
|
|
77
66
|
|
|
78
|
-
|
|
67
|
+
**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.
|
|
79
68
|
|
|
80
|
-
|
|
69
|
+
**Drift detection.** MAXSIM compares your codebase against the spec and flags divergence before it snowballs.
|
|
81
70
|
|
|
82
|
-
|
|
83
|
-
```
|
|
84
|
-
/maxsim:init
|
|
85
|
-
```
|
|
86
|
-
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.
|
|
71
|
+
---
|
|
87
72
|
|
|
88
|
-
|
|
89
|
-
```
|
|
90
|
-
/maxsim:plan 1
|
|
91
|
-
```
|
|
92
|
-
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.
|
|
73
|
+
## Installation
|
|
93
74
|
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
/maxsim:execute 1
|
|
97
|
-
```
|
|
98
|
-
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.
|
|
75
|
+
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.
|
|
99
76
|
|
|
100
|
-
|
|
77
|
+
```bash
|
|
78
|
+
npx maxsimcli@latest
|
|
101
79
|
```
|
|
102
|
-
|
|
80
|
+
|
|
81
|
+
Run this from your project root. Everything goes into `.claude/`.
|
|
82
|
+
|
|
83
|
+
### CLI Flags
|
|
84
|
+
|
|
85
|
+
| Flag | Alias | What it does |
|
|
86
|
+
|------|-------|-------------|
|
|
87
|
+
| `--local` | `-l` | Install to current project (default) |
|
|
88
|
+
| `--uninstall` | `-u` | Remove all MAXSIM files |
|
|
89
|
+
| `--config-dir <path>` | `-c` | Custom target directory |
|
|
90
|
+
| `--force-statusline` | | Replace existing statusline config |
|
|
91
|
+
| `--help` | `-h` | Show usage |
|
|
92
|
+
| `--version` | | Print version |
|
|
93
|
+
|
|
94
|
+
### Skill Management
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npx maxsimcli skill-list # Show installed skills
|
|
98
|
+
npx maxsimcli skill-install <name> # Add a skill
|
|
99
|
+
npx maxsimcli skill-update [name] # Update one or all
|
|
103
100
|
```
|
|
104
|
-
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.
|
|
105
101
|
|
|
106
|
-
|
|
102
|
+
### What Lands in Your Project
|
|
103
|
+
|
|
104
|
+
The installer copies these files into `.claude/`:
|
|
105
|
+
|
|
106
|
+
- 9 slash commands (`/maxsim:init`, `/maxsim:plan`, etc.)
|
|
107
|
+
- 4 agent definitions (executor, planner, researcher, verifier)
|
|
108
|
+
- 21 skills (TDD, debugging, code review, and more)
|
|
109
|
+
- 23 workflow files
|
|
110
|
+
- 14 reference documents, 2 rules files
|
|
111
|
+
- 5 hooks (statusline, update checker, sounds)
|
|
112
|
+
- 1 tool binary (`maxsim-tools.cjs`)
|
|
113
|
+
|
|
114
|
+
### Directory Layout
|
|
115
|
+
|
|
107
116
|
```
|
|
108
|
-
/
|
|
117
|
+
.claude/
|
|
118
|
+
├── commands/maxsim/ # 9 slash commands
|
|
119
|
+
├── maxsim/
|
|
120
|
+
│ ├── bin/maxsim-tools.cjs # Tool binary
|
|
121
|
+
│ ├── workflows/ # 23 workflows
|
|
122
|
+
│ ├── templates/ # Planning document templates
|
|
123
|
+
│ ├── references/ # 14 reference docs
|
|
124
|
+
│ ├── VERSION
|
|
125
|
+
│ └── CHANGELOG.md
|
|
126
|
+
├── agents/ # 4 agents (maxsim-*.md)
|
|
127
|
+
├── skills/ # 21 skill directories
|
|
128
|
+
├── rules/ # 2 rules files
|
|
129
|
+
├── hooks/ # 5 hook scripts (.js)
|
|
130
|
+
├── settings.json
|
|
131
|
+
└── package.json
|
|
109
132
|
```
|
|
110
|
-
Auto-detects project state, surfaces blockers, and dispatches to the right command. No arguments needed.
|
|
111
133
|
|
|
112
|
-
|
|
134
|
+
### Upgrading
|
|
113
135
|
|
|
114
|
-
|
|
136
|
+
Run `npx maxsimcli@latest` again. The installer backs up your current install to `.claude/maxsim-backup/`, saves your local modifications to `.claude/maxsim-local-patches/`, preserves custom skills and agents, then updates everything.
|
|
115
137
|
|
|
138
|
+
### Uninstall
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
npx maxsimcli --uninstall
|
|
116
142
|
```
|
|
117
|
-
|
|
118
|
-
MAXSIM
|
|
119
|
-
You: A CLI tool that converts PDFs to structured JSON using AI
|
|
120
|
-
MAXSIM: [researches domain, scopes requirements]
|
|
121
|
-
[creates REQUIREMENTS.md and ROADMAP.md with 8 phases]
|
|
122
|
-
Phase 1: PDF parsing + text extraction
|
|
123
|
-
Phase 2: AI-powered structure detection
|
|
124
|
-
...
|
|
125
|
-
|
|
126
|
-
You: /maxsim:plan 1
|
|
127
|
-
MAXSIM: [research agent investigates pdf libraries]
|
|
128
|
-
[planner creates 3 atomic task plans]
|
|
129
|
-
[plan-checker verifies feasibility]
|
|
130
|
-
Ready. Run /maxsim:execute 1
|
|
131
|
-
|
|
132
|
-
You: /maxsim:execute 1
|
|
133
|
-
MAXSIM: [wave 1: executor installs dependencies, commits]
|
|
134
|
-
[wave 2: executor implements PDF reader, commits]
|
|
135
|
-
[wave 3: executor adds tests, commits]
|
|
136
|
-
[spec review ✓ → code review ✓ → verifier confirms goal achieved]
|
|
137
|
-
Phase 1 complete. 3 commits.
|
|
138
|
-
```
|
|
143
|
+
|
|
144
|
+
Removes MAXSIM files from `.claude/`. Your own skills, agents, and Claude Code config stay untouched.
|
|
139
145
|
|
|
140
146
|
---
|
|
141
147
|
|
|
142
148
|
## Commands
|
|
143
149
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
| Command | Description |
|
|
150
|
+
| Command | What it does |
|
|
147
151
|
|---------|-------------|
|
|
148
|
-
| `/maxsim:init` |
|
|
149
|
-
| `/maxsim:plan
|
|
150
|
-
| `/maxsim:execute <
|
|
151
|
-
| `/maxsim:
|
|
152
|
-
| `/maxsim:
|
|
153
|
-
| `/maxsim:
|
|
154
|
-
| `/maxsim:debug
|
|
155
|
-
| `/maxsim:settings` |
|
|
156
|
-
| `/maxsim:help` | Show
|
|
157
|
-
|
|
158
|
-
Every command is **idempotent** — you can re-run it and it picks up where you left off. No work gets lost.
|
|
152
|
+
| `/maxsim:init` | Set up a new project or onboard an existing codebase |
|
|
153
|
+
| `/maxsim:plan <phase>` | Research, discuss, and create plans for a phase |
|
|
154
|
+
| `/maxsim:execute <phase>` | Run plans for a phase (serial or parallel) |
|
|
155
|
+
| `/maxsim:go <phase>` | Plan + execute in one step |
|
|
156
|
+
| `/maxsim:quick <description>` | Run an ad-hoc task outside the phase system |
|
|
157
|
+
| `/maxsim:progress` | Show project progress |
|
|
158
|
+
| `/maxsim:debug` | Start a debug session |
|
|
159
|
+
| `/maxsim:settings` | View and change configuration |
|
|
160
|
+
| `/maxsim:help` | Show available commands |
|
|
159
161
|
|
|
160
|
-
|
|
162
|
+
## Core Workflow
|
|
161
163
|
|
|
162
|
-
|
|
164
|
+
MAXSIM organizes development into phases. Each phase moves through five stages.
|
|
163
165
|
|
|
164
|
-
|
|
165
|
-
npx maxsimcli@latest
|
|
166
|
-
```
|
|
166
|
+
**1. Initialize** (`/maxsim:init`)
|
|
167
167
|
|
|
168
|
-
|
|
168
|
+
Run once per project. Creates the `.planning/` directory with PROJECT.md, ROADMAP.md, STATE.md, REQUIREMENTS.md, and config.json. Optionally connects GitHub Issues for tracking.
|
|
169
169
|
|
|
170
|
-
|
|
171
|
-
- **4 agents** → `.claude/agents/`
|
|
172
|
-
- **19 skills** → `.claude/skills/`
|
|
173
|
-
- **26 workflows** → `.claude/maxsim/workflows/`
|
|
174
|
-
- **3 hooks** → `.claude/hooks/`
|
|
175
|
-
- **MCP server** → `.claude/maxsim/bin/mcp-server.cjs`
|
|
170
|
+
**2. Plan** (`/maxsim:plan <phase>`)
|
|
176
171
|
|
|
177
|
-
|
|
172
|
+
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>/`.
|
|
178
173
|
|
|
179
|
-
|
|
174
|
+
**3. Execute** (`/maxsim:execute <phase>`)
|
|
180
175
|
|
|
181
|
-
|
|
182
|
-
<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
|
|
176
|
+
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.
|
|
183
177
|
|
|
184
|
-
|
|
185
|
-
|
|
178
|
+
**4. Verify**
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
182
|
+
**5. Complete**
|
|
183
|
+
|
|
184
|
+
The phase is marked done and progress updates. The next phase becomes active.
|
|
185
|
+
|
|
186
|
+
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>`.
|
|
187
|
+
|
|
188
|
+
## Phase Lifecycle
|
|
189
|
+
|
|
190
|
+
```
|
|
191
|
+
empty → discussed → researched → planned → partial → complete
|
|
186
192
|
```
|
|
187
193
|
|
|
188
|
-
|
|
194
|
+
| State | Meaning |
|
|
195
|
+
|-------|---------|
|
|
196
|
+
| `empty` | Phase directory exists, no work started |
|
|
197
|
+
| `discussed` | Requirements gathered |
|
|
198
|
+
| `researched` | Codebase research done |
|
|
199
|
+
| `planned` | Plan files written |
|
|
200
|
+
| `partial` | Execution started but not finished |
|
|
201
|
+
| `complete` | All plans executed and verified |
|
|
189
202
|
|
|
190
|
-
|
|
203
|
+
Phase numbers are flexible. Integer (`01`, `02`), letter suffixes for parallel tracks (`02A`, `02B`), and decimal inserts (`02.1`) all work.
|
|
191
204
|
|
|
192
205
|
---
|
|
193
206
|
|
|
194
|
-
##
|
|
207
|
+
## Agents
|
|
195
208
|
|
|
196
|
-
|
|
209
|
+
4 agents, each with one job:
|
|
197
210
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
"parallelization": true,
|
|
205
|
-
"worktree_mode": "auto",
|
|
206
|
-
"max_parallel_agents": 10,
|
|
207
|
-
"brave_search": false,
|
|
208
|
-
"workflow": {
|
|
209
|
-
"research": true,
|
|
210
|
-
"plan_checker": true,
|
|
211
|
-
"verifier": true
|
|
212
|
-
},
|
|
213
|
-
"review": {
|
|
214
|
-
"spec_review": true,
|
|
215
|
-
"code_review": true,
|
|
216
|
-
"simplify_review": true,
|
|
217
|
-
"retry_limit": 3
|
|
218
|
-
}
|
|
219
|
-
}
|
|
220
|
-
```
|
|
211
|
+
| Agent | Role | What it does |
|
|
212
|
+
|-------|------|-------------|
|
|
213
|
+
| Executor | Builds things | Reads plans, makes code changes, commits atomically, handles deviations |
|
|
214
|
+
| Planner | Creates plans | Turns research into structured PLAN.md files with tasks, waves, and dependencies |
|
|
215
|
+
| Researcher | Investigates | Explores the codebase, gathers technical context, can use Brave Search |
|
|
216
|
+
| Verifier | Checks results | Validates plan structure, artifacts, requirement evidence, commit integrity |
|
|
221
217
|
|
|
222
|
-
|
|
223
|
-
|-----|--------|---------|-------------|
|
|
224
|
-
| `model_profile` | `quality` \| `balanced` \| `budget` \| `tokenburner` | `balanced` | Which models agents use |
|
|
225
|
-
| `branching_strategy` | `none` \| `phase` \| `milestone` | `none` | Git branch creation per phase or milestone |
|
|
226
|
-
| `commit_docs` | boolean | `true` | Commit documentation changes separately |
|
|
227
|
-
| `parallelization` | boolean | `true` | Enable wave-based parallel plan execution |
|
|
228
|
-
| `worktree_mode` | `auto` \| `always` \| `never` | `auto` | Git worktree isolation for parallel agents |
|
|
229
|
-
| `workflow.research` | boolean | `true` | Enable research agent before planning |
|
|
230
|
-
| `workflow.plan_checker` | boolean | `true` | Enable plan-checker verification before execution |
|
|
231
|
-
| `workflow.verifier` | boolean | `true` | Enable verifier agent after execution |
|
|
232
|
-
| `review.spec_review` | boolean | `true` | Spec compliance review after each plan |
|
|
233
|
-
| `review.code_review` | boolean | `true` | Code quality review after each plan |
|
|
234
|
-
| `review.simplify_review` | boolean | `true` | Simplification pass after reviews |
|
|
235
|
-
| `review.retry_limit` | number | `3` | Max review cycle retries before escalation |
|
|
236
|
-
| `brave_search` | boolean | `false` | Enable Brave Search API in research agents |
|
|
218
|
+
Each agent is a markdown file at `.claude/agents/maxsim-{name}.md` with YAML frontmatter for tools, model tier, and preloaded skills.
|
|
237
219
|
|
|
238
|
-
|
|
220
|
+
A 5th type, Debugger, exists in the model profile system for debug sessions but has no standalone agent file.
|
|
239
221
|
|
|
240
|
-
|
|
222
|
+
### Model Profiles
|
|
241
223
|
|
|
242
|
-
|
|
243
|
-
|-------|-----------|------------|----------|---------------|
|
|
244
|
-
| Executor | Opus | Sonnet | Sonnet | Opus |
|
|
245
|
-
| Planner | Opus | Opus | Sonnet | Opus |
|
|
246
|
-
| Researcher | Opus | Sonnet | Haiku | Opus |
|
|
247
|
-
| Verifier | Sonnet | Sonnet | Haiku | Opus |
|
|
224
|
+
Set `model_profile` in `.planning/config.json` to control which Claude model each agent uses:
|
|
248
225
|
|
|
249
|
-
|
|
226
|
+
| Agent Type | `quality` | `balanced` (default) | `budget` | `tokenburner` |
|
|
227
|
+
|------------|-----------|---------------------|----------|---------------|
|
|
228
|
+
| executor | opus | sonnet | sonnet | opus |
|
|
229
|
+
| planner | opus | opus | sonnet | opus |
|
|
230
|
+
| researcher | opus | sonnet | haiku | opus |
|
|
231
|
+
| verifier | sonnet | sonnet | haiku | opus |
|
|
232
|
+
| debugger | sonnet | sonnet | haiku | opus |
|
|
250
233
|
|
|
251
|
-
|
|
234
|
+
`opus` maps to `inherit`, meaning it uses your Claude Code session model. `sonnet` and `haiku` are passed directly to subagent invocations.
|
|
252
235
|
|
|
253
|
-
|
|
254
|
-
/maxsim:settings
|
|
255
|
-
```
|
|
236
|
+
### Per-Agent Overrides
|
|
256
237
|
|
|
257
|
-
|
|
238
|
+
Override individual agents regardless of profile:
|
|
258
239
|
|
|
259
240
|
```json
|
|
260
241
|
{
|
|
261
242
|
"model_profile": "balanced",
|
|
262
243
|
"model_overrides": {
|
|
263
|
-
"
|
|
264
|
-
"
|
|
244
|
+
"executor": "opus",
|
|
245
|
+
"researcher": "haiku"
|
|
265
246
|
}
|
|
266
247
|
}
|
|
267
248
|
```
|
|
268
249
|
|
|
269
250
|
---
|
|
270
251
|
|
|
271
|
-
##
|
|
252
|
+
## GitHub Integration
|
|
272
253
|
|
|
273
|
-
|
|
254
|
+
MAXSIM tracks phase and plan progress through GitHub Issues. Your `.planning/` files hold project-level documents (roadmap, state, config). Execution progress lives in GitHub.
|
|
274
255
|
|
|
275
|
-
|
|
276
|
-
|-------|------|------------------|
|
|
277
|
-
| `executor` | Implements plans with atomic commits and deviation handling | maxsim-executor |
|
|
278
|
-
| `planner` | Creates PLAN.md files with task breakdown and goal-backward verification | maxsim-planner, maxsim-roadmapper, maxsim-plan-checker |
|
|
279
|
-
| `researcher` | Investigates domains with source evaluation and confidence levels | maxsim-phase-researcher, maxsim-project-researcher, maxsim-research-synthesizer, maxsim-codebase-mapper |
|
|
280
|
-
| `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 |
|
|
256
|
+
You need GitHub CLI (`gh`) installed and authenticated, plus a GitHub-hosted repository.
|
|
281
257
|
|
|
282
|
-
|
|
258
|
+
### Setup
|
|
283
259
|
|
|
284
|
-
|
|
260
|
+
Configured during `/maxsim:init`:
|
|
285
261
|
|
|
286
|
-
|
|
262
|
+
1. Creates a "MAXSIM Task Board" project with 4 columns (To Do, In Progress, In Review, Done)
|
|
263
|
+
2. Creates labels: `phase` (purple), `task` (blue), `blocker` (red)
|
|
264
|
+
3. Optionally creates a GitHub Milestone
|
|
287
265
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
### Protocol Skills
|
|
291
|
-
| Skill | Description |
|
|
292
|
-
|-------|-------------|
|
|
293
|
-
| `handoff-contract` | Structured format for agent returns |
|
|
294
|
-
| `verification-gates` | Hard gates with evidence requirements |
|
|
295
|
-
| `input-validation` | Input validation patterns |
|
|
296
|
-
|
|
297
|
-
### Methodology Skills
|
|
298
|
-
| Skill | Description |
|
|
299
|
-
|-------|-------------|
|
|
300
|
-
| `evidence-collection` | How to gather and validate evidence |
|
|
301
|
-
| `research-methodology` | How to research effectively |
|
|
302
|
-
| `sdd` | Spec-driven development — fresh agent per task |
|
|
303
|
-
| `tdd` | Test-driven development — failing test before implementation |
|
|
304
|
-
| `systematic-debugging` | Reproduce → hypothesize → isolate → verify → fix |
|
|
305
|
-
| `brainstorming` | Multi-approach exploration before design decisions |
|
|
306
|
-
| `code-review` | Security, interfaces, error handling, test coverage |
|
|
307
|
-
| `verification-before-completion` | 5-step verification with evidence requirements |
|
|
308
|
-
|
|
309
|
-
### Execution Skills
|
|
310
|
-
| Skill | Description |
|
|
311
|
-
|-------|-------------|
|
|
312
|
-
| `maxsim-batch` | Parallel worktree execution for independent work units |
|
|
313
|
-
| `maxsim-simplify` | Review changed code for reuse, quality, and efficiency |
|
|
314
|
-
| `commit-conventions` | Project git commit standards |
|
|
315
|
-
|
|
316
|
-
### Reference Skills
|
|
317
|
-
| Skill | Description |
|
|
318
|
-
|-------|-------------|
|
|
319
|
-
| `agent-system-map` | Agent capabilities and tool mappings |
|
|
320
|
-
| `tool-priority-guide` | Tool usage priority and best practices |
|
|
321
|
-
| `memory-management` | Persistent memory across sessions |
|
|
322
|
-
| `roadmap-writing` | Guided roadmap and requirements authoring |
|
|
323
|
-
| `using-maxsim` | Guide for effective MAXSIM usage |
|
|
266
|
+
### How It Works
|
|
324
267
|
|
|
325
|
-
|
|
268
|
+
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.
|
|
326
269
|
|
|
327
|
-
|
|
270
|
+
A local `.planning/github-issues.json` caches the mapping between phase numbers and issue numbers. It is a performance cache, the system rebuilds it from GitHub when needed.
|
|
328
271
|
|
|
329
|
-
|
|
272
|
+
### Tool Commands
|
|
330
273
|
|
|
331
|
-
|
|
|
332
|
-
|
|
333
|
-
| `
|
|
334
|
-
| `
|
|
335
|
-
| `
|
|
274
|
+
| Subcommand | What it does |
|
|
275
|
+
|---|---|
|
|
276
|
+
| `github setup` | Create board, labels, milestone |
|
|
277
|
+
| `github create-phase` | Create a phase tracking issue |
|
|
278
|
+
| `github create-task` / `batch-create-tasks` | Create task sub-issues |
|
|
279
|
+
| `github move-issue` | Move issue between board columns |
|
|
280
|
+
| `github status` | Show progress and board overview |
|
|
281
|
+
| `github sync-check` | Verify local cache matches GitHub |
|
|
282
|
+
| `github all-progress` | Show progress for all phases |
|
|
336
283
|
|
|
337
284
|
---
|
|
338
285
|
|
|
339
|
-
##
|
|
340
|
-
|
|
341
|
-
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`.
|
|
342
|
-
|
|
343
|
-
**Exposed tools:**
|
|
344
|
-
- **Phase operations** — list, add, complete, insert, and remove phases
|
|
345
|
-
- **State management** — read/update STATE.md (decisions, blockers, metrics)
|
|
346
|
-
- **Todo operations** — create, list, and complete todos
|
|
347
|
-
- **Roadmap analysis** — phase status, progress calculation, missing details
|
|
348
|
-
- **Context loading** — intelligent file selection based on task topic
|
|
349
|
-
- **Config management** — read/write `.planning/config.json` settings
|
|
350
|
-
- **GitHub integration** — issue creation, board queries, status tracking
|
|
286
|
+
## Configuration
|
|
351
287
|
|
|
352
|
-
|
|
288
|
+
Project config lives in `.planning/config.json`, created during `/maxsim:init`.
|
|
289
|
+
|
|
290
|
+
### Full Reference
|
|
291
|
+
|
|
292
|
+
| Setting | Type | Default | What it does |
|
|
293
|
+
|---------|------|---------|-------------|
|
|
294
|
+
| `model_profile` | `'quality' \| 'balanced' \| 'budget' \| 'tokenburner'` | `'balanced'` | Model tier for all agents |
|
|
295
|
+
| `model_overrides` | `Record<AgentType, ModelTier>` | | Per-agent model overrides |
|
|
296
|
+
| `commit_docs` | `boolean` | `true` | Auto-commit `.planning/` changes |
|
|
297
|
+
| `search_gitignored` | `boolean` | `false` | Include gitignored files in codebase mapping |
|
|
298
|
+
| `branching_strategy` | `'none' \| 'phase' \| 'milestone'` | `'none'` | Git branching strategy |
|
|
299
|
+
| `phase_branch_template` | `string` | `'maxsim/phase-{phase}-{slug}'` | Branch name template for phases |
|
|
300
|
+
| `milestone_branch_template` | `string` | `'maxsim/{milestone}-{slug}'` | Branch name template for milestones |
|
|
301
|
+
| `workflow.research` | `boolean` | `true` | Run research before planning |
|
|
302
|
+
| `workflow.plan_checker` | `boolean` | `true` | Run plan checker agent |
|
|
303
|
+
| `workflow.verifier` | `boolean` | `true` | Run verifier after execution |
|
|
304
|
+
| `parallelization` | `boolean` | `true` | Allow parallel plan execution |
|
|
305
|
+
| `worktree_mode` | `'auto' \| 'always' \| 'never'` | `'auto'` | When to use git worktrees |
|
|
306
|
+
| `max_parallel_agents` | `number` | `10` | Cap on concurrent agents |
|
|
307
|
+
| `brave_search` | `boolean` | `false` | Let researcher agents use Brave Search |
|
|
308
|
+
| `review.spec_review` | `boolean` | `true` | Spec review gate |
|
|
309
|
+
| `review.code_review` | `boolean` | `true` | Code review gate |
|
|
310
|
+
| `review.simplify_review` | `boolean` | `true` | Simplification review gate |
|
|
311
|
+
| `review.retry_limit` | `number` | `3` | Max retries per review gate |
|
|
312
|
+
|
|
313
|
+
### User-Level Defaults
|
|
314
|
+
|
|
315
|
+
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.
|
|
316
|
+
|
|
317
|
+
### Environment Variables
|
|
318
|
+
|
|
319
|
+
| Variable | Purpose |
|
|
320
|
+
|----------|---------|
|
|
321
|
+
| `BRAVE_API_KEY` | Brave Search API key (or put it in `~/.maxsim/brave_api_key`) |
|
|
322
|
+
| `MAXSIM_DEBUG` | Verbose debug logging to stderr |
|
|
323
|
+
| `MAXSIM_SOUND=0` | Turn off notification sounds |
|
|
324
|
+
| `CI=true` | Suppress sounds in CI |
|
|
325
|
+
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | Enable Agent Teams for parallel execution |
|
|
353
326
|
|
|
354
327
|
---
|
|
355
328
|
|
|
356
|
-
##
|
|
329
|
+
## Skills
|
|
357
330
|
|
|
358
|
-
|
|
331
|
+
Skills are reusable prompt modules that agents load on demand. Each skill is a `SKILL.md` file with YAML frontmatter and a markdown body.
|
|
332
|
+
|
|
333
|
+
### Built-in Skills (21)
|
|
334
|
+
|
|
335
|
+
| Skill | Category | What it does |
|
|
336
|
+
|-------|----------|-------------|
|
|
337
|
+
| `tdd` | Task | Test-driven development, Red-Green-Refactor cycle |
|
|
338
|
+
| `systematic-debugging` | Methodology | Root-cause analysis: reproduce, hypothesize, isolate, verify, fix |
|
|
339
|
+
| `verification-before-completion` | Methodology | Requires evidence before marking work as done |
|
|
340
|
+
| `maxsim-simplify` | Task | Finds duplication, dead code, and unnecessary complexity |
|
|
341
|
+
| `code-review` | Task | Checks security, interfaces, error handling, test coverage |
|
|
342
|
+
| `memory-management` | Task | Persists patterns and decisions to project memory |
|
|
343
|
+
| `using-maxsim` | Task | Routes work through the spec-driven workflow |
|
|
344
|
+
| `brainstorming` | Task | Explores multiple approaches before picking a design |
|
|
345
|
+
| `roadmap-writing` | Task | Creates structured roadmaps with phased planning |
|
|
346
|
+
| `sdd` | Task | Spec-driven development, sequential tasks with fresh context |
|
|
347
|
+
| `maxsim-batch` | Task | Decomposes tasks for parallel worktree execution |
|
|
348
|
+
| `agent-system-map` | Reference | Overview of the agent system |
|
|
349
|
+
| `commit-conventions` | Convention | Conventional commit format and version trigger rules |
|
|
350
|
+
| `evidence-collection` | Methodology | Structured evidence gathering for verification |
|
|
351
|
+
| `github-artifact-protocol` | Reference | How to read and write GitHub Issue artifacts |
|
|
352
|
+
| `github-tools-guide` | Reference | Guide to the GitHub CLI commands |
|
|
353
|
+
| `handoff-contract` | Protocol | Agent-to-agent handoff protocol |
|
|
354
|
+
| `input-validation` | Protocol | Input validation rules for agents |
|
|
355
|
+
| `research-methodology` | Methodology | Structured research approach for agents |
|
|
356
|
+
| `tool-priority-guide` | Reference | Which tools to prefer for which tasks |
|
|
357
|
+
| `verification-gates` | Protocol | Review gate protocol with pass/fail criteria |
|
|
358
|
+
|
|
359
|
+
### Skill Types
|
|
360
|
+
|
|
361
|
+
Protocol skills load automatically (handoff-contract, verification-gates, input-validation). Methodology skills guide how agents think. Task skills are user-invocable workflows like TDD or code review. Reference skills provide static information.
|
|
362
|
+
|
|
363
|
+
### Managing Skills
|
|
359
364
|
|
|
365
|
+
```bash
|
|
366
|
+
npx maxsimcli skill-list # Show installed skills
|
|
367
|
+
npx maxsimcli skill-install <name> # Add a skill
|
|
368
|
+
npx maxsimcli skill-update [name] # Update one or all
|
|
360
369
|
```
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
├── PROJECT.md # Vision and scope (always loaded)
|
|
364
|
-
├── REQUIREMENTS.md # v1/v2/out-of-scope requirements
|
|
365
|
-
├── ROADMAP.md # Phase structure with goals and dependencies
|
|
366
|
-
├── STATE.md # Memory: decisions, blockers, metrics, session history
|
|
367
|
-
├── phases/
|
|
368
|
-
│ └── 01-Foundation/
|
|
369
|
-
│ ├── 01-CONTEXT.md # User decisions from discussion
|
|
370
|
-
│ ├── 01-RESEARCH.md # Research findings
|
|
371
|
-
│ ├── 01-01-PLAN.md # Task plan (numbered per attempt)
|
|
372
|
-
│ ├── 01-01-SUMMARY.md # Completion record with evidence
|
|
373
|
-
│ ├── 01-VERIFICATION.md # Verification results
|
|
374
|
-
│ └── 01-UAT.md # User acceptance tests
|
|
375
|
-
└── todos/
|
|
376
|
-
├── pending/
|
|
377
|
-
└── completed/
|
|
378
|
-
```
|
|
370
|
+
|
|
371
|
+
Built-in skills update when you upgrade MAXSIM. Custom skills you place in `.claude/skills/` are preserved.
|
|
379
372
|
|
|
380
373
|
---
|
|
381
374
|
|
|
382
|
-
##
|
|
375
|
+
## Parallel Execution
|
|
383
376
|
|
|
384
|
-
MAXSIM
|
|
377
|
+
MAXSIM can run multiple plans at the same time using git worktrees. Each plan gets its own isolated working directory.
|
|
385
378
|
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
templates/agents/*.md ← Subagent prompts (4 agents)
|
|
390
|
-
templates/skills/*/ ← On-demand context modules (19 skills)
|
|
391
|
-
```
|
|
379
|
+
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.
|
|
380
|
+
|
|
381
|
+
Each parallel plan gets a worktree at `.maxsim-worktrees/{planId}/` on its own branch. Worktrees are cleaned up automatically after completion.
|
|
392
382
|
|
|
393
|
-
|
|
383
|
+
### When It Activates
|
|
394
384
|
|
|
395
|
-
|
|
385
|
+
In `auto` mode (default), parallel execution kicks in when one wave has more than 2 plans and `parallelization` is `true` in config. Set `worktree_mode` to `always` or `never` for manual control. `max_parallel_agents` caps concurrent agents at 10 by default.
|
|
396
386
|
|
|
397
|
-
|
|
387
|
+
You need `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` set in your environment and a git repository.
|
|
398
388
|
|
|
399
|
-
|
|
389
|
+
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.
|
|
400
390
|
|
|
401
391
|
---
|
|
402
392
|
|
|
403
|
-
##
|
|
393
|
+
## Hooks
|
|
404
394
|
|
|
405
|
-
MAXSIM
|
|
395
|
+
MAXSIM installs 5 Claude Code hooks:
|
|
406
396
|
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
-
|
|
397
|
+
| Hook | Event | What it does |
|
|
398
|
+
|------|-------|-------------|
|
|
399
|
+
| `maxsim-statusline` | `statusLine` | Shows model tier, phase number, board column, and milestone progress |
|
|
400
|
+
| `maxsim-check-update` | `SessionStart` | Checks npm for new MAXSIM versions in the background |
|
|
401
|
+
| `maxsim-notification-sound` | `PostToolUse` | Plays a sound when Claude asks you a question |
|
|
402
|
+
| `maxsim-stop-sound` | `Stop` | Plays a sound when Claude finishes |
|
|
403
|
+
| `maxsim-sync-reminder` | `PostToolUse` | No-op stub, kept for structural reasons |
|
|
404
|
+
|
|
405
|
+
### Statusline
|
|
406
|
+
|
|
407
|
+
```
|
|
408
|
+
[update] model | P{N} {BoardColumn} | milestone: pct% | dirname
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
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.
|
|
410
412
|
|
|
411
413
|
---
|
|
412
414
|
|
|
413
|
-
##
|
|
415
|
+
## Architecture
|
|
414
416
|
|
|
415
|
-
|
|
417
|
+
### Monorepo
|
|
416
418
|
|
|
417
|
-
|
|
419
|
+
npm workspaces monorepo with two packages:
|
|
418
420
|
|
|
419
|
-
|
|
421
|
+
```
|
|
422
|
+
maxsim/
|
|
423
|
+
├── packages/
|
|
424
|
+
│ ├── cli/ # maxsimcli, the published npm package
|
|
425
|
+
│ └── website/ # maxsimcli.dev, project website (private)
|
|
426
|
+
├── templates/ # Markdown assets copied into dist during build
|
|
427
|
+
└── package.json # Workspace root
|
|
428
|
+
```
|
|
420
429
|
|
|
421
|
-
|
|
430
|
+
Only `packages/cli` gets published to npm as `maxsimcli`.
|
|
431
|
+
|
|
432
|
+
### Build
|
|
433
|
+
|
|
434
|
+
```bash
|
|
435
|
+
npm run build # tsdown (CJS) then copy-assets into dist/
|
|
436
|
+
npm test # Vitest unit tests
|
|
437
|
+
npm run e2e # Vitest e2e tests
|
|
438
|
+
npm run lint # Biome
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
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`.
|
|
442
|
+
|
|
443
|
+
## Contributing
|
|
444
|
+
|
|
445
|
+
Conventional commits. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
422
446
|
|
|
423
|
-
|
|
447
|
+
- `fix:` triggers a patch release
|
|
448
|
+
- `feat:` triggers a minor release
|
|
449
|
+
- `feat!:` or `BREAKING CHANGE:` triggers a major release
|
|
424
450
|
|
|
425
|
-
|
|
451
|
+
## License
|
|
426
452
|
|
|
427
|
-
|
|
453
|
+
[MIT](LICENSE)
|
package/dist/assets/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,10 @@
|
|
|
1
|
+
## [5.0.6](https://github.com/maystudios/maxsimcli/compare/v5.0.5...v5.0.6) (2026-03-12)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
### Bug Fixes
|
|
5
|
+
|
|
6
|
+
* correct all critical template-CLI discrepancies (K1-K5) ([f298990](https://github.com/maystudios/maxsimcli/commit/f2989908b03ac2772c6b2d3091b2169f0871c1ec))
|
|
7
|
+
|
|
1
8
|
## [5.0.5](https://github.com/maystudios/maxsimcli/compare/v5.0.4...v5.0.5) (2026-03-12)
|
|
2
9
|
|
|
3
10
|
|
package/package.json
CHANGED