@gempack/squad-mcp 0.3.1 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@
 
 MCP server that exposes the `squad-dev` workflow as deterministic tools, prompts, and resources. It classifies a task, scores its risk, picks an advisory squad of specialist reviewers, slices the changed files per agent, validates the plan, and consolidates the advisory verdicts. The host LLM (Claude Code, Cursor, Warp, Claude Desktop, …) orchestrates; `squad-mcp` provides the building blocks.
 
-It also ships as a Claude Code plugin that bundles the MCP server and the `/squad` and `/squad-review` slash commands behind a single `/plugin install`.
+It also ships as a Claude Code plugin that bundles the MCP server, four slash commands (`/squad`, `/squad-review`, `/brainstorm`, `/commit-suggest`), and the matching skills behind a single `/plugin install`.
 
 ## Install
 
@@ -17,7 +17,7 @@ It also ships as a Claude Code plugin that bundles the MCP server and the `/squa
 /plugin install squad@gempack
 ```
 
-The plugin bundles the MCP server, the `/squad` command, and the `/squad-review` command. After install, restart Claude Code to pick up the new commands and the `squad` MCP server.
+The plugin bundles the MCP server plus four slash commands and skills (`/squad`, `/squad-review`, `/brainstorm`, `/commit-suggest`). After install, restart Claude Code to pick up the new commands and the `squad` MCP server.
 
 ### npm package (any MCP client)
 
@@ -77,7 +77,7 @@ node dist/index.js
 
 | Tool | Purpose |
 |------|---------|
-| `detect_changed_files` | Hardened `git diff --name-status` for a workspace. Allowlisted refs, 10s timeout, 1MB stdout cap. |
+| `detect_changed_files` | Hardened `git diff --name-status --no-renames` for a workspace. Allowlisted refs, 10s timeout, 1MB stdout cap. |
 | `classify_work_type` | Heuristic `WorkType` from prompt + paths (`Feature` / `Bug Fix` / `Refactor` / `Performance` / `Security` / `Business Rule`) with Low/Medium/High confidence. |
 | `score_risk` | Compute Low/Medium/High from boolean signals (auth, money, migration, files_count, new_module, api_change). |
 | `select_squad` | Select advisory agents for a work type. Combines matrix + path hints + content sniff. Returns evidence per file. |
@@ -102,6 +102,31 @@ node dist/index.js
 - `severity://_severity-and-ownership` — severity matrix + ownership rules.
 - `severity://skill-squad-dev`, `severity://skill-squad-review` — full skill specs.
 
+### Bundled skills
+
+The plugin auto-registers these skills via `skills/` (or sync them to `~/.claude/skills/` for non-plugin clients with `node tools/sync-agents.mjs`):
+
+| Skill | Trigger | Purpose |
+|-------|---------|---------|
+| `/squad` | implementation workflow | Builds an approved plan, distributes work to specialist agents in parallel, implements the change, consolidates via tech-lead. Optional `--codex` second-opinion. New `--quick` mode reduces to 1 specialist + tech-lead with terse prompts (mutually exclusive with `--codex`; auto-fallback to normal mode on security/data-layer scope). |
+| `/squad-review` | multi-perspective review | Auto-detects affected domains, spawns specialist agents in parallel, scores on a weighted rubric (Code Quality 20%, Security 20%, Maintainability 20%, Performance 20%, Async/Concurrency 8%, Error Handling 7%, Architecture Fit 5%), tech-lead consolidates the verdict. New `--quick` mode for fast iteration. |
+| `/brainstorm` | pre-implementation research | Web research in parallel + specialist agent perspectives → options matrix with cited sources and a recommendation. Produces no code. Position: `/brainstorm` decides what to build, `/squad` implements, `/squad-review` reviews. |
+| `/commit-suggest` | commit message generator | Read-only suggester for Conventional Commits messages. Runs only an allowlist of git commands; never executes mutations; never adds AI co-author trailers. The user runs the commit themselves. |
+
+Workflow positioning:
+
+```
+/brainstorm   ->  decide what to build
+     v
+/squad        ->  implement what was decided
+     v
+/squad-review ->  review what was implemented
+     v
+/commit-suggest -> craft the commit message
+```
+
+See [INSTALL.md](INSTALL.md#bundled-skills) for trigger examples and the optional `commit-msg` git hook + `permissions.deny` snippet that hard-enforce the read-only and no-AI-attribution invariants at the OS / Claude Code layer.
+
 ## Detection strategy (`select_squad` / `slice_files_for_agent`)
 
 Three layers, in order of strength:
@@ -114,13 +139,18 @@ Output of `select_squad` includes per-file `evidence` with `confidence` and `low
 
 ## Local override of agent definitions
 
-Agent markdown is loaded with this priority:
+The loader picks ONE local override directory:
+
+- If `SQUAD_AGENTS_DIR` is set, that path is used **exclusively** (the platform default is not consulted).
+- Otherwise: `%APPDATA%\squad-mcp\agents` on Windows, `$XDG_CONFIG_HOME/squad-mcp/agents` on Unix (falls back to `~/.config/squad-mcp/agents` if `XDG_CONFIG_HOME` is unset).
+
+Per-file resolution: if the agent's `*.md` exists in the chosen local directory, it wins. Otherwise, the embedded default bundled in the package is used.
+
+Override files are loaded verbatim and rendered into the LLM's context with full agent authority — treat the directory as code (user-only writable, not on shared volumes, never sourced from untrusted input).
 
-1. `$SQUAD_AGENTS_DIR` (env var, if set)
-2. `%APPDATA%\squad-mcp\agents` (Windows) / `$XDG_CONFIG_HOME/squad-mcp/agents` (Unix)
-3. Embedded defaults bundled in the package
+Since v0.4.0, the override directory is validated against an allowlist (`HOME`, `APPDATA`, `LOCALAPPDATA`, `XDG_CONFIG_HOME`, `process.cwd()`); paths outside the allowlist are rejected with `OVERRIDE_REJECTED`. Set `SQUAD_AGENTS_ALLOW_UNSAFE=1` to bypass for unusual setups (logs a warn banner). See [INSTALL.md](INSTALL.md#local-override-of-agent-definitions) for the full security guidance.
 
-Run the `init_local_config` tool once to seed the local directory with defaults you can edit.
+Run the `init_local_config` tool once to seed the local directory with editable defaults.
 
 ## Repo layout
 
@@ -129,10 +159,11 @@ squad-mcp/
 ├── .claude-plugin/             # Claude Code plugin manifest + marketplace
 ├── .github/workflows/          # CI + release workflows
 ├── agents/                     # Bundled agent markdown defaults
-├── commands/                   # Plugin slash commands (/squad, /squad-review)
+├── commands/                   # Plugin slash commands (/squad, /squad-review, /brainstorm, /commit-suggest)
+├── skills/                     # Bundled skills (commit-suggest, brainstorm)
 ├── src/
 │   ├── index.ts                # stdio entry
-│   ├── tools/                  # MCP tools (10 deterministic functions)
+│   ├── tools/                  # MCP tools (12 deterministic functions)
 │   ├── resources/              # MCP resources + agent loader
 │   ├── prompts/                # MCP prompt templates
 │   ├── exec/git.ts             # hardened git execution layer
@@ -141,6 +172,9 @@ squad-mcp/
 │   └── config/
 │       └── ownership-matrix.ts # agents, work types, content/path patterns
 ├── tests/                      # vitest unit + integration + stdio smoke
+├── tools/
+│   ├── sync-agents.mjs         # mirror agents + skills into ~/.claude/ for non-plugin clients
+│   └── git-hooks/commit-msg    # opt-in hook rejecting AI-attribution trailers
 └── dist/                       # compiled JS (gitignored, shipped via npm)
 ```