@xcraftmind/mastermind 0.22.1 → 0.23.1

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.
Files changed (2) hide show
  1. package/README.md +81 -38
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -8,29 +8,68 @@ Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec /
8
8
 
9
9
  Prebuilt native binaries via optional platform packages — **no Rust toolchain required**.
10
10
 
11
- ## Install
11
+ ## What it does
12
12
 
13
- Requires **Node.js 18+**. The CLI is a thin JS wrapper around a prebuilt native binary — no Rust toolchain needed (except the build-from-source path below).
13
+ `mastermind` parses your codebase into a queryable graph (definitions, callers/callees, imports, blast radius) with tree-sitter, and serves it to Claude Code over MCP — so the agent asks structural questions instead of grepping. It also ships the Mastermind workflow gates: `verify-spec` (pre-flight) and `audit-spec` (post-flight) for running coding tasks against mechanical checks.
14
14
 
15
- ### One-shot (no install)
15
+ ## Quick start
16
+
17
+ Requires **Node.js 18+**. The CLI is a thin JS wrapper over a prebuilt native binary — no Rust toolchain needed.
18
+
19
+ **1. Install**
16
20
 
17
21
  ```sh
18
- npx -y @xcraftmind/mastermind doctor
19
- npx -y @xcraftmind/mastermind init --profile typescript-api
20
- npx -y @xcraftmind/mastermind run-task .mastermind/tasks/042-feature.md
22
+ npm install -g @xcraftmind/mastermind
23
+ ```
24
+
25
+ **2. Set up your project** — run inside each repo you want Claude to understand:
26
+
27
+ ```sh
28
+ cd your-project
29
+ mastermind init # scaffold .mastermind/, build the index, draft CONTEXT.md
30
+ echo ".mastermind/" >> .gitignore # index + local specs are local state
31
+ ```
32
+
33
+ `init` builds the index and drafts `CONTEXT.md` from your code via `claude -p` (pass `--no-claude` or `--no-index` to skip). Re-run `mastermind index .` to refresh, or `mastermind watch` to keep it live.
34
+
35
+ **3. Register with Claude Code** — once, globally:
36
+
37
+ ```sh
38
+ mastermind setup claude --write-mcp
21
39
  ```
22
40
 
23
- `npx` is great for these one-shot commands. **Avoid it for the MCP server**, though: an MCP config that runs `npx ... serve` pays an npm-cache/network resolution cost on every Claude Code launch and is less deterministic than a real install. For `setup claude`, prefer **global** or **project-local** (below). If you do register via npx, `setup claude` pins the version (`npx -y @xcraftmind/mastermind@<ver> serve`) so at least the version is stable — but it's an escape hatch, not the recommended path.
41
+ **4. Verify**
42
+
43
+ ```sh
44
+ mastermind doctor # should now be all green
45
+ ```
46
+
47
+ Restart Claude Code — the codegraph tools (search, callers, callees, impact, …) are now available in any project you've indexed.
48
+
49
+ ## What gets set up where
50
+
51
+ Two separate things — and the split is the part that trips people up:
24
52
 
25
- ### Global (recommended for most users)
53
+ | | Scope | Lives in | How often |
54
+ |---|---|---|---|
55
+ | **Index** — `init` + `index` | **per project** | `.mastermind/mmcg.db` in each repo | once per repo, refresh with `index` / `watch` |
56
+ | **MCP registration** — `setup claude` | once | `~/.claude/.mcp.json` (global) | once for all projects |
57
+
58
+ - **The index is always per-project.** Run `mastermind init && mastermind index .` in *every* repo you want indexed. `doctor` reporting `index database not found` just means you haven't done this in the current directory yet (the exact situation if you run `doctor` from `/tmp` or a fresh shell).
59
+ - **The MCP registration is usually once, globally.** The global entry launches `mastermind serve` from whichever project you open in Claude Code, so it picks up *that* project's `.mastermind/mmcg.db` automatically. You do **not** re-run `setup claude` per repo.
60
+ - Use **per-project registration** only if you want the MCP config committed with the repo and version-pinned: `mastermind setup claude --project . --write-mcp` writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` (pair it with a project-local install — see below).
61
+
62
+ > `setup claude` is safe by default: without `--write-mcp` it prints the diff and exits without touching anything.
63
+
64
+ ## Install options
65
+
66
+ ### Global (recommended)
26
67
 
27
68
  ```sh
28
69
  npm install -g @xcraftmind/mastermind
29
- mastermind setup claude --write-mcp # register mmcg as an MCP server
30
- mastermind doctor # verify the environment
31
70
  ```
32
71
 
33
- `setup claude` writes `~/.claude/.mcp.json` with `command: "mastermind"` so Claude Code launches the wrapper from PATH.
72
+ Puts `mastermind` on your PATH. `setup claude --write-mcp` registers `command: "mastermind"` in `~/.claude/.mcp.json`.
34
73
 
35
74
  ### Project-local
36
75
 
@@ -39,15 +78,43 @@ npm install -D @xcraftmind/mastermind
39
78
  npx mastermind setup claude --project . --write-mcp
40
79
  ```
41
80
 
42
- `setup claude --project .` writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` so the project gets a reproducible, version-pinned MCP server.
81
+ Writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` — reproducible and version-pinned with the repo. Commit `./.mcp.json`; keep ignoring `.mastermind/`.
82
+
83
+ ### One-shot with npx (no install)
84
+
85
+ ```sh
86
+ npx -y @xcraftmind/mastermind doctor
87
+ npx -y @xcraftmind/mastermind init --profile typescript-api
88
+ ```
89
+
90
+ Fine for one-off commands. **Avoid npx for the MCP server** — running `npx … serve` on every Claude Code launch pays an npm-resolution cost and is less deterministic than a real install. For `serve` / `setup claude`, prefer global or project-local.
43
91
 
44
92
  ### Build from source (contributors / unsupported platforms)
45
93
 
46
94
  ```sh
47
- cargo install mmcg
95
+ cargo install mmcg # requires Rust 1.75+
96
+ ```
97
+
98
+ The cargo-installed binary is `mmcg`, not `mastermind` — same code, same subcommands, only the wrapper name differs.
99
+
100
+ ## Commands
101
+
102
+ ```sh
103
+ mastermind init [--profile <p>] # scaffold .mastermind/, build index, draft CONTEXT.md (--no-index / --no-claude to skip)
104
+ mastermind index . # build/refresh the codegraph (incremental; --force to re-parse all)
105
+ mastermind watch # long-running watcher — re-indexes on file changes
106
+ mastermind status # file count, symbol count, db path
107
+ mastermind doctor # environment health check
108
+ mastermind serve # MCP stdio server (this is what Claude Code launches)
109
+ mastermind setup claude --write-mcp # register with Claude Code's MCP layer
110
+ mastermind verify-spec <path> # pre-execution mechanical gate on a task spec
111
+ mastermind audit-spec <path> --since main # post-execution audit vs a git baseline
112
+ mastermind run-task <path> # two-phase orchestrator: verify → executor → audit
113
+ mastermind query callers <symbol> # one-shot CLI query (agents use the MCP tools instead)
114
+ mastermind uninstall [--scope <s>] # remove project setup (.mastermind/ + project .mcp.json); --scope global|all for the global MCP entry
48
115
  ```
49
116
 
50
- Requires Rust 1.75+. The cargo-installed binary is `mmcg`, not `mastermind` — same code, same subcommands, only the wrapper name differs.
117
+ `mmcg` is a legacy alias for the same binary (cargo installs expose it under that name) — prefer `mastermind`. See `mastermind <subcommand> --help` for full options.
51
118
 
52
119
  ## Supported platforms
53
120
 
@@ -63,30 +130,6 @@ Prebuilt binaries ship for:
63
130
 
64
131
  Other targets fall back to `cargo install mmcg`.
65
132
 
66
- ## What's in the box
67
-
68
- - `mastermind` — public CLI command (alias for `mmcg` with install-mode hints)
69
- - `mmcg` — compatibility command (same binary, same subcommands as cargo-installed `mmcg`)
70
-
71
- Both commands resolve to the same native binary. Use whichever your team has documented.
72
-
73
- ### Top-level subcommands
74
-
75
- ```sh
76
- mastermind init --profile typescript-api # scaffold .mastermind/ with stack-specific CONTEXT.md
77
- mastermind index . # build/refresh the codegraph index
78
- mastermind watch # long-running watcher (re-indexes on file changes)
79
- mastermind doctor # environment health check
80
- mastermind serve # MCP stdio server
81
- mastermind setup claude --write-mcp # register with Claude Code's MCP layer
82
- mastermind verify-spec <path> # pre-execution mechanical gate on a task spec
83
- mastermind audit-spec <path> --since main # post-execution audit vs git baseline
84
- mastermind run-task <path> # two-phase orchestrator: verify → executor → audit
85
- mastermind query callers <symbol> # one-shot CLI query (use MCP for agents)
86
- ```
87
-
88
- See `mastermind <subcommand> --help` for full options.
89
-
90
133
  ## Architecture
91
134
 
92
135
  The npm package uses the prebuilt-platform-package pattern (same as `esbuild`, `swc`, `lefthook`, `turbo`). The root `@xcraftmind/mastermind` package contains only JavaScript wrappers and lists all seven platform packages as `optionalDependencies`. npm installs only the package matching the host's `os` + `cpu` (+ `libc` for Linux); the others are skipped.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xcraftmind/mastermind",
3
- "version": "0.22.1",
3
+ "version": "0.23.1",
4
4
  "description": "Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec / audit-spec gates, MCP server, multi-language tree-sitter indexer (Python, TypeScript, JavaScript, Rust, C#, Go, Java, PHP, C/C++). Prebuilt native binaries via optional platform packages — no Rust toolchain required.",
5
5
  "license": "MIT",
6
6
  "author": "xcraftmind",
@@ -37,12 +37,12 @@
37
37
  "mastermind"
38
38
  ],
39
39
  "optionalDependencies": {
40
- "@xcraftmind/mmcg-darwin-arm64": "0.22.1",
41
- "@xcraftmind/mmcg-darwin-x64": "0.22.1",
42
- "@xcraftmind/mmcg-linux-x64-gnu": "0.22.1",
43
- "@xcraftmind/mmcg-linux-arm64-gnu": "0.22.1",
44
- "@xcraftmind/mmcg-linux-x64-musl": "0.22.1",
45
- "@xcraftmind/mmcg-linux-arm64-musl": "0.22.1",
46
- "@xcraftmind/mmcg-win32-x64-msvc": "0.22.1"
40
+ "@xcraftmind/mmcg-darwin-arm64": "0.23.1",
41
+ "@xcraftmind/mmcg-darwin-x64": "0.23.1",
42
+ "@xcraftmind/mmcg-linux-x64-gnu": "0.23.1",
43
+ "@xcraftmind/mmcg-linux-arm64-gnu": "0.23.1",
44
+ "@xcraftmind/mmcg-linux-x64-musl": "0.23.1",
45
+ "@xcraftmind/mmcg-linux-arm64-musl": "0.23.1",
46
+ "@xcraftmind/mmcg-win32-x64-msvc": "0.23.1"
47
47
  }
48
48
  }