@gempack/squad-mcp 0.3.1 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
         "repo": "ggemba/squad-mcp"
       },
       "description": "Squad-dev workflow: deterministic classification, risk scoring, agent selection, advisory orchestration over MCP, plus /squad and /squad-review slash commands.",
-      "version": "0.3.1",
+      "version": "0.4.0",
       "license": "Apache-2.0",
       "homepage": "https://github.com/ggemba/squad-mcp"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "squad",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Squad-dev workflow as a Claude Code plugin: classification, risk scoring, agent selection, advisory orchestration. Bundles an MCP server and the /squad and /squad-review slash commands.",
   "license": "Apache-2.0",
   "author": {
@@ -11,6 +11,7 @@
   "repository": "https://github.com/ggemba/squad-mcp",
   "keywords": ["mcp", "squad-dev", "code-review", "advisory", "agent"],
   "commands": "./commands/",
+  "skills": "./skills/",
   "mcpServers": {
     "squad": {
       "command": "node",

package/CHANGELOG.md

@@ -7,13 +7,155 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
-Planned for `0.4.0`:
+Planned for a future minor:
 
 - Promote bundled agent markdowns to Claude Code native plugin agents (rename to
   kebab-case + add YAML frontmatter), with a migration path for existing
   `%APPDATA%\squad-mcp\agents` overrides.
 - Retire the legacy `/squad` and `/squad-review` skills now that the plugin
   ships them as slash commands.
+- Extract `tools/sync-agents.mjs` helpers into a `tools/sync/` module
+  (`baseline-store.mjs`, `safe-copy.mjs`, `agents.mjs`, `skills.mjs`) once a
+  third sync target lands.
+- Streaming SHA-256 over `fs.createReadStream` for skill files larger than a
+  threshold (avoids `readFileSync` doubling memory on large bundled assets).
+- Property-based tests for `hasPathSeparator` and the tri-state baseline
+  policy state machine via `fast-check`.
+
+## [0.5.0] - 2026-05-04
+
+### Added
+
+- **`Senior-Dev-Reviewer` weighted scorecard.** Reviewer agent now produces a
+  numeric scorecard (0–10 per dimension, weighted average overall) across Code
+  Quality 20%, Security 20%, Maintainability 20%, Performance 20%,
+  Async/Concurrency 8%, Error Handling 7%, Architecture Fit 5%. Includes
+  per-stack idiomatic checklists for the top 5 backend (C#/.NET, Python, Java,
+  Go, Node.js) and top 5 frontend (TypeScript, React, Vue, Angular, Svelte)
+  stacks with auto-detection. Severity table drives the scorecard penalty.
+  Dimensions lacking diff evidence are reported as `N/A` rather than zero.
+- **`brainstorm` skill.** Collaborative pre-implementation exploration. Takes a
+  problem, decision, or implementation idea; runs deep web research in parallel
+  (market patterns, best practices, pitfalls, examples); spawns specialist
+  agents for multi-domain perspectives; synthesizes findings into a sourced
+  options matrix with a recommendation. Exploratory only — produces no code or
+  file changes. Position in the workflow: `/brainstorm` decides *what* to
+  build; `/squad` implements; `/squad-review` reviews. Triggered via
+  `/brainstorm` or natural-language asks ("brainstorm", "research approaches",
+  "explore options", "what does the industry use"). Supports `--depth
+  quick|medium|deep`, `--no-web`, `--focus <domain>`, and `--sources <N>`.
+- **`commit-suggest` skill.** Read-only Conventional Commits message suggester.
+  Runs only an allowlist of git commands (`status`, `diff`, `log`, `rev-parse`,
+  `config --get`, `ls-files`, `show <ref>:<path>`); never executes any
+  state-mutating git command; never adds AI co-author trailers. Output is text
+  only — the user runs the commit themselves. Triggered via `/commit-suggest`
+  or natural-language asks ("suggest a commit", "commit message").
+- **Plugin manifest exports `skills/`**. The `commit-suggest` skill (and any
+  future skill bundled under `skills/`) is auto-registered when the plugin is
+  enabled in Claude Code.
+- **`tools/git-hooks/commit-msg`**. Optional opt-in hook that rejects commits
+  whose messages contain AI-attribution trailers (`Co-Authored-By: Claude /
+  Anthropic / GPT / OpenAI / Gemini / Copilot / AI`, `Generated with [Claude
+  Code]`, `Made by AI`, `<noreply@anthropic.com>`). Install via `cp` to
+  `.git/hooks/` or repo-wide via `git config core.hooksPath tools/git-hooks`.
+- **`tools/sync-agents.mjs` skills sync.** Mirrors bundled skills to
+  `~/.claude/skills/` for non-plugin clients (Claude Desktop, Cursor, Warp).
+  Recursive walker; baseline-hash store at `~/.claude/skills/.bundle-hashes.json`
+  with versioned envelope (`{version: 1, baselines: {...}}`); tri-state policy
+  (identical / stale-baseline / user-modified) preserves user edits with a
+  `skip-with-warning` log; symlink refusal at source, destination, leaf, and
+  baseline-file layers; containment assert against escape-via-skill-name;
+  `COPYFILE_EXCL` race guard with EEXIST recurse fallback; mode `0o600` on
+  baseline file (Unix); atomic temp+rename writes; non-zero exit on
+  `skillsFailed > 0`.
+- **`tools/sync-agents.mjs` agents sync hardening.** Symmetric symlink-at-
+  destination defense for the agents path: refuses to write through a symlinked
+  `~/.claude/agents/<file>.md` (matches the existing skills behavior).
+- **8 integration tests** for the skills sync (`tests/sync-agents.test.ts`):
+  cold sync + baseline persistence, bundle update overwrites stale dst, user
+  edits preserved, symlink-dst refused (Unix-only), corrupt baseline graceful
+  fallback, idempotent rerun, HOME/USERPROFILE guard.
+
+### Changed
+
+- **Global `~/.claude/CLAUDE.md` rule** (user-side, not shipped): commits
+  produced or suggested by Claude must never carry AI-attribution trailers.
+
+### Documentation
+
+- **`INSTALL.md` Path B note**: documents that npm-package users must run
+  `node tools/sync-agents.mjs` to mirror agents and skills to `~/.claude/`,
+  and that the manual sync is idempotent.
+- **`INSTALL.md` Optional hardening section**: documents how to install the
+  `commit-msg` hook and a recommended `permissions.deny` block in
+  `.claude/settings.json` for structural enforcement of the read-only invariant.
+- **`INSTALL.md` baseline file note**: documents that
+  `~/.claude/skills/.bundle-hashes.json` is installer state and should not be
+  edited or deleted manually.
+
+## [0.4.0] - 2026-05-02
+
+### Security
+
+- **BREAKING:** `SQUAD_AGENTS_DIR` is now validated against an allowlist of
+  user-controlled prefixes (`HOME`, `APPDATA`, `LOCALAPPDATA`, `XDG_CONFIG_HOME`,
+  `process.cwd()`). Override directories outside the allowlist are rejected with
+  a new structured `OVERRIDE_REJECTED` error. UNC and device-namespace paths on
+  Windows (`\\?\…`, `\\.\…`, `\\server\share\…`) are rejected before any
+  filesystem access. Migration: move the directory under one of the allowed
+  prefixes, or set `SQUAD_AGENTS_ALLOW_UNSAFE=1` to bypass the allowlist (logs a
+  warn-level banner once per process).
+- **BREAKING:** Per-file resolution now realpath-checks each agent file. If a
+  file inside the override directory is a symlink whose target escapes the
+  directory, that file silently falls back to the embedded default — preserving
+  the operator's per-file customizations while blocking the symlink-out
+  primitive.
+- Lexical AND realpath checks are both required for an override directory to
+  match the allowlist (closes the lexical-allowed-but-symlinked-out bypass).
+- `init_local_config` now creates the override directory with mode `0o700` and
+  copied agent files with mode `0o600` on Unix (`fs.chmod` after `mkdir` /
+  `copyFile` to override the umask). Windows relies on `%APPDATA%`'s default
+  user-only DACL; custom paths outside `APPDATA` on Windows fall back to the
+  parent directory's DACL — document and use with care.
+- `agent-loader` warns once per process if the resolved override directory is
+  world-writable (`mode & 0o002 !== 0`). Group-writable does not trigger the
+  warning (single-user-host convention). Skipped on Windows since `fs.stat`
+  does not surface DACL semantics.
+
+### Added
+
+- `src/util/override-allowlist.ts` — new module exposing `validateOverrideDir`
+  and `validateOverrideFile`.
+- `src/util/path-internal.ts` — extracted shared helpers (`rejectIfMalformed`,
+  `realpathOrSelf`) reused by `path-safety` and `override-allowlist`.
+- `OVERRIDE_REJECTED` added to `SquadErrorCode`.
+- `SQUAD_AGENTS_ALLOW_UNSAFE=1` opt-in escape hatch for power users / CI on
+  unusual paths.
+- `tests/agent-loader.test.ts` and `tests/override-allowlist.test.ts` covering
+  the accept/reject matrix, escape hatch, agent-name traversal guard, symlink
+  escape, and Unix filesystem permissions (`0o700` dir, `0o600` files,
+  world-writable warn-once).
+
+### Changed
+
+- `agent-loader` now logs a structured `agent override active` line on first
+  resolution with `resolved_path`, `allowlist_match`, `has_unsafe_override`,
+  `source` (`env` vs `platform_default`). Escape-hatch resolutions log at
+  `warn` instead of `info`.
+- `getLocalDir()` now returns `{ rawDir, explicit }` — the `list_agents` tool
+  output exposes both `local_dir` (the raw path) and `local_dir_explicit`.
+
+### Migration
+
+- If you set `SQUAD_AGENTS_DIR` to a path under your home / APPDATA / XDG dir,
+  no action is needed.
+- If you set it to `/opt/...`, `/srv/...`, a CI runner path, or any other
+  location outside those prefixes, you have two options:
+  1. Move the directory under `~/`, `~/AppData/Local/`, `~/.config/`, or your
+     project's working directory.
+  2. Set `SQUAD_AGENTS_ALLOW_UNSAFE=1` in the environment that launches the MCP
+     host. This bypasses the allowlist and logs a warning on every process
+     start so the choice stays auditable.
 
 ## [0.3.1] - 2026-05-02
 
@@ -276,7 +418,9 @@ update at commit `052c2ad`.
 - Smoke test (`tests/smoke.mjs`) plus initial unit tests for `score_risk`,
   `select_squad`, `consolidate`.
 
-[Unreleased]: https://github.com/ggemba/squad-mcp/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/ggemba/squad-mcp/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/ggemba/squad-mcp/releases/tag/v0.5.0
+[0.4.0]: https://github.com/ggemba/squad-mcp/releases/tag/v0.4.0
 [0.3.1]: https://github.com/ggemba/squad-mcp/releases/tag/v0.3.1
 [0.3.0]: https://github.com/ggemba/squad-mcp/releases/tag/v0.3.0
 [0.1.0]: https://github.com/ggemba/squad-mcp/commit/548adc2

package/INSTALL.md

@@ -0,0 +1,422 @@
+# Installation guide
+
+This guide walks through installing `squad-mcp` in every supported host: Claude Code (as a plugin), and any other MCP-capable client (Claude Desktop, Cursor, Warp, Continue, etc.) via the npm package.
+
+After install you get:
+
+- 12 deterministic MCP tools (Claude Code exposes them as `mcp__squad__*`; other hosts may use a different prefix)
+- 12 MCP resources (`agent://*`, `severity://*`)
+- 3 MCP prompts (`squad_orchestration`, `agent_advisory`, `consolidator`)
+- 2 slash commands (`/squad`, `/squad-review`) — Claude Code only
+
+## Prerequisites
+
+- Node.js 20+ on `PATH`. Both the npm path and the Claude Code plugin path shell out to `node` (the plugin manifest runs `node ${CLAUDE_PLUGIN_ROOT}/dist/index.js`); CI tests on Node 20 and 22.
+- A host that speaks MCP (Claude Code, Claude Desktop, Cursor, Warp, Continue, …)
+- Git available on `PATH` (used by `detect_changed_files`)
+
+Verify Node:
+
+```bash
+node --version   # v20+
+```
+
+## Path A — Claude Code plugin (recommended)
+
+The plugin bundles the MCP server, the slash commands, and the agent definitions behind a single install. No JSON config to edit.
+
+1. **Add the marketplace.** In a Claude Code session, paste:
+
+   ```text
+   /plugin marketplace add ggemba/squad-mcp
+   ```
+
+   Wait for `marketplace added`.
+
+2. **Install the plugin.**
+
+   ```text
+   /plugin install squad@gempack
+   ```
+
+   Wait for `plugin installed`.
+
+3. **Restart Claude Code** (close and reopen). The slash-command registry is populated at startup, so the new `/squad` and `/squad-review` commands and the `squad` MCP server only become available after a restart.
+
+4. **Verify the install.** In a fresh prompt:
+
+   - Type `/squad ` (with the trailing space) — the autocomplete should suggest `/squad <task description>`.
+   - Type `/squad-review` — same check.
+   - Open Settings → MCP. You should see `squad` listed and connected.
+   - Ask Claude to call the `list_agents` tool from the `squad` MCP server. It should return 9 agents (`po`, `tech-lead-planner`, `tech-lead-consolidator`, `senior-architect`, `senior-dba`, `senior-developer`, `senior-dev-reviewer`, `senior-dev-security`, `senior-qa`).
+
+5. **Use it.**
+
+   ```text
+   /squad add a /health endpoint that returns build SHA and uptime
+   /squad-review
+   /squad-review 1234        # PR number
+   /squad-review feature/x   # branch
+   ```
+
+   `/squad` runs the full Phase 0–12 orchestration (classify → score risk → pick agents → plan → Gate 1 → advisory squad → Gate 2 → implement → consolidate). `/squad-review` is review-only — it never implements, commits, or pushes.
+
+### Updating the plugin
+
+```text
+/plugin update squad@gempack
+```
+
+Then restart Claude Code.
+
+### Uninstalling
+
+```text
+/plugin uninstall squad@gempack
+/plugin marketplace remove gempack
+```
+
+## Path B — npm package (any MCP client)
+
+Use this path for hosts that don't have a plugin marketplace (Claude Desktop, Cursor, Warp, Continue, etc.) or when you want the MCP server only without the slash commands.
+
+> **Path B vs Path A — what gets installed:** the npm package ships **only the MCP server** (`dist/index.js`). The bundled agents (`agents/*.md`), shared docs (`agents/_squad-shared/`), and skills (`skills/*/SKILL.md`) are **not** auto-mirrored to `~/.claude/` by `npx`. Path A (Claude Code plugin) registers them via the manifest; Path B users who want the slash commands and skills materialized in `~/.claude/agents/` and `~/.claude/skills/` must run the bundled sync script after installing:
+>
+> ```bash
+> # From a checkout of https://github.com/ggemba/squad-mcp at the matching tag:
+> node tools/sync-agents.mjs
+> ```
+>
+> The sync is idempotent. Re-running it preserves any skill files you have edited locally (skip-with-warning policy). Delete a skill file under `~/.claude/skills/<name>/` (losing your edits) to receive the next bundled update.
+>
+> The script maintains a `~/.claude/skills/.bundle-hashes.json` baseline file that records the hash of the last bundled version of each skill file. It distinguishes "unmodified prior bundle" (overwrite on update) from "user-modified" (preserve with warning). Do **not** edit or delete this file manually — deleting it forces all existing skills to be classified as user-modified until they happen to match a future bundle.
+
+The package is published as [`@gempack/squad-mcp`](https://www.npmjs.com/package/@gempack/squad-mcp). You don't need to install it globally — `npx` will fetch and cache it on first run.
+
+### Version pinning and provenance
+
+The default `npx -y @gempack/squad-mcp` resolves to the latest published version on every host launch. To pin a specific version, append `@<version>`:
+
+```bash
+npx -y @gempack/squad-mcp@0.4.0
+```
+
+Releases are published from CI with [npm provenance](https://docs.npmjs.com/generating-provenance-statements). Verify the published tarball before configuring a host:
+
+```bash
+npm audit signatures @gempack/squad-mcp
+```
+
+Pin in your host config the same way (e.g. `args: ["-y", "@gempack/squad-mcp@0.4.0"]`).
+
+> **Note:** the per-host examples below use the unpinned default (`@gempack/squad-mcp`) for readability. For production setups, replace `@gempack/squad-mcp` with `@gempack/squad-mcp@<version>` in every host's `args` array.
+
+### Smoke test
+
+Verify the binary downloads and runs:
+
+```bash
+npx -y @gempack/squad-mcp
+```
+
+The server starts on stdio and waits silently for JSON-RPC on stdin (Ctrl+C to exit). Any error during `npx` resolution prints to stderr.
+
+### Claude Desktop
+
+Edit the config file:
+
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json` (unofficial — not all Claude Desktop builds support Linux)
+
+Add (or merge) the `squad` entry:
+
+```json
+{
+  "mcpServers": {
+    "squad": {
+      "command": "npx",
+      "args": ["-y", "@gempack/squad-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. In a chat, the MCP indicator (hammer icon) should show the `squad` server with its tools.
+
+### Cursor
+
+Workspace-scoped: create `.cursor/mcp.json` in the repo root.
+Global: open Cursor Settings → MCP and add the same JSON.
+
+```json
+{
+  "mcpServers": {
+    "squad": {
+      "command": "npx",
+      "args": ["-y", "@gempack/squad-mcp"]
+    }
+  }
+}
+```
+
+Reload Cursor. The `squad` server appears under Settings → MCP. Tools become callable from chat.
+
+### Warp
+
+Settings → MCP servers → Add server.
+
+- **Name:** `squad`
+- **Command:** `npx`
+- **Args:** `["-y", "@gempack/squad-mcp"]`. If your Warp build's UI takes a single space-separated string instead, enter `-y @gempack/squad-mcp`.
+
+Save. The server status should turn green.
+
+### Continue (VS Code / JetBrains)
+
+In `~/.continue/config.json` (or the workspace equivalent):
+
+```json
+{
+  "mcpServers": {
+    "squad": {
+      "command": "npx",
+      "args": ["-y", "@gempack/squad-mcp"]
+    }
+  }
+}
+```
+
+Reload the Continue extension.
+
+> Older Continue releases (pre-1.x) used `experimental.modelContextProtocolServers` with a `transport` envelope. If your build does not pick up the `mcpServers` key, check the [Continue MCP docs](https://docs.continue.dev/customize/deep-dives/mcp) for the schema your version expects.
+
+### Any other MCP client
+
+Same shape. The server is a stdio MCP server. Command + args:
+
+```text
+command: npx
+args:    -y @gempack/squad-mcp
+```
+
+Most hosts accept either a JSON config block or a UI form with these two fields.
+
+### Faster startup / offline / corporate-proxy setups
+
+Install once globally and reference the binary by name (avoids the per-launch `npx` resolution):
+
+```bash
+npm install -g @gempack/squad-mcp
+```
+
+Then in any host config, replace `command: npx` + `args: ["-y", "@gempack/squad-mcp"]` with:
+
+```json
+{
+  "command": "squad-mcp",
+  "args": []
+}
+```
+
+This also works behind a registry proxy that rejects on-the-fly `npx` lookups.
+
+## Path C — From source (development)
+
+```bash
+git clone https://github.com/ggemba/squad-mcp.git
+cd squad-mcp
+npm install
+npm run build
+node dist/index.js   # speaks MCP over stdio
+```
+
+To point a host at your local build, replace `command: npx, args: -y @gempack/squad-mcp` with:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/squad-mcp/dist/index.js"]
+}
+```
+
+## Local override of agent definitions
+
+The bundled agent markdowns can be overridden without forking. 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.
+
+**Security: override files are agent system prompts.** Files in the local override directory are loaded verbatim and rendered into the LLM's context with full agent authority. Treat the directory as code:
+
+- It must be writable only by the running user.
+- Never place it on a shared volume, network mount, or world-writable path.
+- `SQUAD_AGENTS_DIR` must never be set from untrusted input (env files, CI variables sourced from PRs, etc.).
+
+### Allowlist (since v0.4.0)
+
+The override directory is validated at load time. It must resolve (after symlink realpath) inside one of these user-controlled prefixes:
+
+- `os.homedir()` — your home directory
+- `APPDATA` and `LOCALAPPDATA` (Windows)
+- `XDG_CONFIG_HOME` or `~/.config` (Unix)
+- `process.cwd()` — the host's working directory at launch
+
+UNC paths (`\\server\share\…`) and device-namespace paths (`\\?\…`, `\\.\…`) on Windows are rejected before any filesystem access. Per-file symlinks that escape the override directory silently fall back to the embedded default for that file.
+
+If the validation fails, the MCP server throws `OVERRIDE_REJECTED` on the first tool call that resolves an agent. The host shows the structured error so the misconfiguration surfaces immediately rather than degrading silently.
+
+### Escape hatch: SQUAD_AGENTS_ALLOW_UNSAFE
+
+For power users on unusual paths (NixOS, custom CI runners, `/opt/…`), set `SQUAD_AGENTS_ALLOW_UNSAFE=1` in the environment that launches the MCP host. This bypasses the allowlist while still rejecting malformed input (NUL bytes, ADS markers, tilde-prefixed paths). Every load logs a warn-level banner so the decision stays auditable.
+
+### Filesystem permissions (since v0.4.0)
+
+`init_local_config` creates the override directory and copied agent files with restrictive permissions:
+
+- **Unix:** directory is `chmod 0o700` (user-only rwx) and each agent file is `chmod 0o600` (user-only rw). The explicit `chmod` overrides any permissive `umask`.
+- **Windows:** `%APPDATA%` typically inherits a user-only DACL on stand-alone profiles, and the loader does not verify Windows ACLs at runtime. On managed, domain-joined, or VDI machines the inherited DACL may be broader; verify with `icacls "$env:APPDATA\squad-mcp\agents"` if the host is multi-user. For custom `SQUAD_AGENTS_DIR` paths outside `APPDATA`, the directory inherits the parent's DACL — set the ACL explicitly before pointing the env var there.
+
+`agent-loader` checks the resolved override directory at startup and emits a `warn`-level log once per process if it is world-writable (`mode & 0o002 !== 0` on Unix). To remediate:
+
+```bash
+chmod 700 "$SQUAD_AGENTS_DIR"
+chmod 600 "$SQUAD_AGENTS_DIR"/*.md
+```
+
+The warning does not block the override — it is advisory. Override files are still loaded and used.
+
+Seed the local directory with editable copies:
+
+```text
+Call the `init_local_config` MCP tool from your host.
+```
+
+Then edit any `*.md` in that directory. Restart the host (or reconnect the MCP server) to pick up changes.
+
+## Optional hardening — commit-suggest skill
+
+The `commit-suggest` skill is read-only by spec and never adds AI co-author trailers, but the rule is enforced at the prompt layer only — a sufficiently adversarial prompt-injection or model regression could violate it. For repos where you want a structural guarantee, install the bundled `commit-msg` hook:
+
+```bash
+# Per-repo install
+cp tools/git-hooks/commit-msg .git/hooks/commit-msg
+chmod +x .git/hooks/commit-msg
+
+# Or repo-wide enforcement on every clone (preferred):
+git config core.hooksPath tools/git-hooks
+```
+
+The hook rejects any commit whose message contains `Co-Authored-By: Claude/Anthropic/GPT/OpenAI/Gemini/Copilot/AI`, `Generated with [Claude Code]`, `Made by AI`, or `<noreply@anthropic.com>` trailers. Comment lines (`#`-prefixed) are ignored so commit-message templates can still document the rule.
+
+For host-level enforcement of read-only behavior during `/commit-suggest` invocations, add a `permissions.deny` block to your Claude Code project settings. Example `.claude/settings.json` snippet:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(git commit*)",
+      "Bash(git add*)",
+      "Bash(git push*)",
+      "Bash(git reset*)",
+      "Bash(git rebase*)",
+      "Bash(git merge*)",
+      "Bash(git checkout*)",
+      "Bash(git switch*)",
+      "Bash(git stash*)",
+      "Bash(git tag*)",
+      "Bash(git branch*)",
+      "Bash(git apply*)",
+      "Bash(git cherry-pick*)",
+      "Bash(git revert*)",
+      "Bash(git rm*)",
+      "Bash(git mv*)",
+      "Bash(git restore*)",
+      "Bash(git clean*)",
+      "Bash(git update-ref*)"
+    ]
+  }
+}
+```
+
+Both layers compose: prompt rule, `permissions.deny`, and the `commit-msg` hook. A tampered skill or a prompt-injection attempt has to defeat all three.
+
+## Bundled skills
+
+The plugin ships these skills under `skills/` (auto-registered when the plugin is enabled, or mirrored to `~/.claude/skills/` via `node tools/sync-agents.mjs` for non-plugin clients):
+
+| Skill | Trigger | Purpose |
+|-------|---------|---------|
+| `commit-suggest` | `/commit-suggest` | Read-only Conventional Commits message suggester. No AI co-author trailers. |
+| `brainstorm` | `/brainstorm <topic>` | Pre-implementation exploration. Web research + multi-agent perspectives + options matrix with cited sources. Produces no code. |
+
+Workflow positioning:
+
+```
+/brainstorm   ->  decide what to build (research + options)
+     v
+/squad        ->  implement what was decided
+     v
+/squad-review ->  review what was implemented
+     v
+/commit-suggest -> craft the commit message
+```
+
+`/brainstorm` examples:
+
+```
+/brainstorm choosing between SQLite and PostgreSQL for a desktop app
+-> Default depth: medium (~6 web queries + 2-3 agents)
+
+/brainstorm --depth deep how to design idempotent payment retries
+-> 10+ queries + 4 agents + tech-lead consolidator
+
+/brainstorm --no-web should we extract this module into a separate package
+-> Agents-only (offline / repo-internal topic)
+
+/brainstorm --focus security how to store API keys in a desktop app
+-> Forces senior-dev-security as the primary specialist
+```
+
+## Verification checklist
+
+After install, regardless of host:
+
+- [ ] `squad` MCP server shows as connected in the host's MCP settings.
+- [ ] `list_agents` tool returns 9 agents.
+- [ ] `compose_squad_workflow` with arguments `{"workspace_root": ".", "user_prompt": "smoke"}` returns `work_type`, `risk`, `squad.agents`. Requires a git repo with at least one prior commit (the tool defaults `base_ref` to `HEAD~1` internally).
+- [ ] Resources `agent://senior-architect` and `severity://_severity-and-ownership` are readable.
+- [ ] (Claude Code only) `/squad` and `/squad-review` autocomplete.
+
+## Troubleshooting
+
+**`/plugin marketplace add` fails with "not found".**
+Make sure you typed `ggemba/squad-mcp` exactly. The marketplace manifest lives at `.claude-plugin/marketplace.json` on the `main` branch of that repo.
+
+**Plugin installed but `/squad` does not appear.**
+Restart Claude Code. The slash command registry is populated at startup. If still missing, run `/plugin list` and confirm `squad@gempack` is listed and enabled.
+
+**MCP server shows as failed / disconnected.**
+Check the host's MCP log:
+
+- Claude Code: Help → Show Logs → MCP.
+- Claude Desktop: `%APPDATA%\Claude\logs\mcp-server-squad.log` (Windows), `~/Library/Logs/Claude/mcp-server-squad.log` (macOS), `~/.config/Claude/logs/mcp-server-squad.log` (Linux — note that Claude Desktop on Linux is unofficial; verify your build).
+
+The log can include workspace file paths and `git diff` output. Review and redact before sharing for support.
+
+Common causes: Node not on `PATH`, corporate proxy blocking npm, or `npx` cache permission errors. Run `npx -y @gempack/squad-mcp` in a terminal to surface the real error.
+
+**`detect_changed_files` returns an error.**
+The tool runs `git diff --name-status --no-renames` (renames are reported as add+delete pairs) and is hardened: 10s timeout, 1MB stdout cap, allowlisted subcommands only. Verify `git --version` works and the workspace is a git repo. Refs must satisfy: matches `^[a-zA-Z0-9_/][a-zA-Z0-9_./-]*$`, max 200 chars, no leading `-`, no trailing `.`, must not contain `..`, `@{`, or `.lock`.
+
+**Tools work but the agents look wrong.**
+You probably have a stale local override. If `SQUAD_AGENTS_DIR` is set, only that directory is consulted; otherwise check `%APPDATA%\squad-mcp\agents` (Windows) or `$XDG_CONFIG_HOME/squad-mcp/agents` / `~/.config/squad-mcp/agents` (Unix). Delete or edit the file — the loader prefers the local copy over the bundled defaults.
+
+**Tools missing on Cursor / Warp after editing JSON.**
+Both hosts cache the MCP server list. Fully quit and relaunch (not just reload window).
+
+## Where to file issues
+
+<https://github.com/ggemba/squad-mcp/issues> — include host name + version, OS, Node version, and the relevant log excerpt.