@gempack/squad-mcp 0.5.0 → 0.6.1

package/.claude-plugin/marketplace.json

@@ -11,8 +11,8 @@
         "source": "github",
         "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.4.0",
+      "description": "Squad-dev workflow: deterministic classification, risk scoring, agent selection, advisory orchestration over MCP, native subagents, plus /squad and /squad-review slash commands.",
+      "version": "0.6.0",
       "license": "Apache-2.0",
       "homepage": "https://github.com/ggemba/squad-mcp"
     }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "squad",
-  "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.",
+  "version": "0.6.1",
+  "description": "Squad-dev workflow as a Claude Code plugin: classification, risk scoring, agent selection, advisory orchestration. Bundles an MCP server, native subagents, and the /squad and /squad-review slash commands.",
   "license": "Apache-2.0",
   "author": {
     "name": "Gustavo",
@@ -10,6 +10,7 @@
   "homepage": "https://github.com/ggemba/squad-mcp#readme",
   "repository": "https://github.com/ggemba/squad-mcp",
   "keywords": ["mcp", "squad-dev", "code-review", "advisory", "agent"],
+  "agents": "./agents/",
   "commands": "./commands/",
   "skills": "./skills/",
   "mcpServers": {

package/CHANGELOG.md

@@ -7,20 +7,274 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — Plugin manifest validation: shared docs lifted out of `agents/`
+
+Claude Code's `/plugin install` rejected the v0.6.0 plugin with `Validation errors: agents: Invalid input`. The plugin manifest's `agents: "./agents/"` directive iterated every `.md` file under `agents/`, including the three `_shared/*.md` reference docs (severity matrix + skill specs) — they lack subagent frontmatter and fail validation.
+
+- Moved `agents/_shared/` → top-level `shared/` so the plugin's agent validator only sees real subagent files.
+- `src/resources/agent-loader.ts` adds `getEmbeddedSharedDir()` (resolves to `<repo>/shared/`); `SHARED_FILES` now lists bare filenames; `resolveSharedFile` reads from the new dir; `initLocalConfig` mirrors shared docs to `<localOverrideDir>/shared/<file>` (was `<localOverrideDir>/_shared/<file>`).
+- `src/tools/consolidate.ts`, `skills/squad/SKILL.md`, `README.md` — references updated to `shared/_Severity-and-Ownership.md`.
+- `package.json` now ships the `shared/` dir + the new task CLI helpers (`tools/_tasks-io.mjs`, `tools/{list,next,record,update}-task*.mjs`) and `tools/record-learning.mjs` in the published tarball (was missing).
+
+Migration for users with an existing local override at `~/.config/squad-mcp/agents/_shared/`: run `init_local_config` again to mirror to the new `shared/` sub-directory, or move the files manually. Override resolution in v0.6.1 looks at `<localOverrideDir>/shared/<file>`; old `_shared/` overrides fall through to embedded defaults.
+
+### Added — Tasks: PRD-decomposed atomic work units (anti-bloat for the squad)
+
+Borrows the core idea from claude-task-master and adapts it to squad-mcp's primitives. A PRD is decomposed by the host LLM into atomic tasks; each task carries optional `scope` (glob) and `agent_hints`; the squad runs against ONE task's scope at a time. Less context per pass, fewer tokens, less drift.
+
+- `src/tasks/store.ts` — mutable JSON store with mtime-keyed cache, atomic write (tmp + rename), stable id-sorted serialisation. Schema (zod): `{ id, title, description, status, dependencies, priority, details, test_strategy, scope?, agent_hints?, subtasks[], created_at, updated_at }`. Status: pending / in-progress / review / done / blocked / cancelled. Schema-versioned (`version: 1`) so future breaking changes can ship cleanly.
+- `src/tasks/select.ts` — pure helpers. `listTasks` filters by status / agent / scope. `nextTask` does topo-aware selection: candidate status (default pending), all deps in done_statuses, optional agent + changed_files filter; tiebreak priority then id; returns a structured result with `reason: no_candidates | all_blocked | ok` + the blocked list (so callers can show "X is next when Y completes").
+- 7 new MCP tools:
+  - `list_tasks`, `next_task`, `record_tasks`, `update_task_status`, `expand_task`, `slice_files_for_task` — the data-plane operations.
+  - `compose_prd_parse` — pure-MCP composer that builds a prompt + JSON schema for the host LLM to decompose a PRD. Server does NO LLM calls; the host already has provider keys and user consent. Includes existing tasks in the prompt so the LLM doesn't duplicate.
+- New `.squad.yaml` section `tasks`:
+  - `path` (default `.squad/tasks.json`)
+  - `enabled` (default true — turn off to silence reads without deleting the file; writes stay open, matching the learnings policy)
+- `tools/{list-tasks,next-task,record-tasks,update-task-status}.mjs` — non-MCP CLI helpers sharing a tiny `tools/_tasks-io.mjs` module. Run anywhere with node 18+.
+- `skills/squad/SKILL.md` adds:
+  - **Phase 0.5 — Decompose PRD into tasks** (task-mode only). Build prompt → run LLM → preview → user-confirm → `record_tasks`. Inviolable: never bulk-record without per-list confirmation, never invent dependencies, never alter ids the user reviewed.
+  - **Phase 0.6 — Pick a task** via `/squad-next` or `/squad-task <id>`. Slice files via `slice_files_for_task`, narrow squad via the task's `agent_hints`, run normal advisory. When done, flip status via `update_task_status`.
+- 38 new tests cover store (read / record / update / expand / cache invalidation / on-disk format) and select (filter / topo / priority tiebreak / blocked surfacing). Smoke test now verifies 23 tools (was 16).
+
+### Added — Learning JSONL: persistent accept/reject memory
+
+Closes the squad's biggest UX gap: re-running review on the same repo no
+longer re-raises findings the team already considered and rejected (with
+reason). Every accept/reject decision becomes one append-only line in
+`.squad/learnings.jsonl`, versioned in git, surfaced as a markdown block
+injected into the next run's agent and consolidator prompts.
+
+- `src/learning/store.ts` — JSONL store with mtime-keyed cache.
+  `readLearnings`, `appendLearning`, and `tailRecent` (filterable by agent
+  / decision). Schema: `{ ts, pr?, branch?, agent, severity?, finding,
+decision, reason?, scope? }`. Schema violations on read are loud
+  rejections — silent corruption is worse.
+- `src/learning/format.ts` — pure formatter rendering a most-recent-first
+  numbered list under a `## Past team decisions` heading. Filters scoped
+  entries by glob match against `changedFiles`; entries without a scope
+  are repo-wide and always pass. Returns `''` when no entries qualify
+  (callers check before injecting — no empty headers in prompts).
+- New tool `read_learnings` — load, filter (agent / decision / scope),
+  return both raw entries and the rendered markdown block. Honors the
+  master switch `learnings.enabled` from `.squad.yaml`.
+- New tool `record_learning` — append a decision. Side-effecting; the
+  skill (or CLI) is responsible for user confirmation per finding.
+- New `.squad.yaml` section `learnings`:
+  - `path` (default `.squad/learnings.jsonl`)
+  - `max_recent` (default 50, hard cap 200)
+  - `enabled` (default true — turn off to disable injection without
+    deleting the journal)
+- `tools/record-learning.mjs` — CLI helper for non-MCP clients. Direct
+  JSONL append, no MCP round-trip. Same flags as the MCP tool plus
+  `--workspace` / `--file`.
+- `skills/squad/SKILL.md` adds **Phase 14 — Post-PR record decision**
+  (opt-in, per-finding authorisation required) and injects
+  `read_learnings` output into Phase 5 (per-agent advisory) and Phase 10
+  (consolidator). Inviolable rules: never record without explicit
+  per-finding authorisation, never invent a `reason`, never amend or
+  delete past entries through the skill.
+
+38 new tests cover the store (read / append / cache invalidation /
+schema violations) and the formatter (limits, scope filtering,
+rendering variants). Smoke test now verifies 16 tools (was 14).
+
+### Added — Post `/squad-review` results as a GitHub PR review
+
+Closes the loop from "advisory in your terminal" to "advisory on the PR
+where the team works". The verdict + scorecard go up as a `gh pr review`
+with the appropriate action (`--approve` / `--comment` / `--request-changes`)
+chosen deterministically from verdict + score.
+
+- `src/format/pr-review.ts` — pure formatter taking `ConsolidationOutput`
+  plus options, returning markdown body, chosen `gh` action, and summary
+  line. Header, fenced rubric scorecard, per-agent finding sections
+  (sorted), severity totals, footer. Verdict-to-action mapping in
+  `chooseGhAction` (exported separately for testability).
+- `tools/post-review.mjs` — CLI helper that lives outside the MCP server
+  (alongside the commit-msg hook). Reads consolidation JSON from stdin,
+  formats, invokes `gh pr review --<action> --body-file -`. Supports
+  `--dry-run`, `--repo owner/name`, `--request-changes-below N`,
+  `--no-footer`, `--pr <n>` (required). Exit codes:
+  `2` invalid input, `3` gh missing/unauthenticated, `4` gh failed.
+- New `.squad.yaml` section `pr_posting`:
+  - `auto_post: bool` (default false — skill always confirms)
+  - `request_changes_below_score: number` (opt-in floor)
+  - `omit_attribution_footer: bool` (default false)
+- `skills/squad/SKILL.md` adds **Phase 13 — Post to PR** (review mode,
+  opt-in). Inviolable rules: never post without showing the body first,
+  never post `--request-changes` on someone else's PR without explicit
+  user instruction, never amend or delete a posted review.
+
+23 new tests cover the formatter (header variants, rubric block, findings
+section, footer, summary, action mapping). The action mapping never
+promotes a verdict (low-severity can't become approve) and only demotes
+APPROVED — never downgrades CHANGES_REQUIRED further.
+
+### Added — `.squad.yaml` repo configuration
+
+Per-repo configuration file (versioned with the code) lets each project tune
+the rubric, thresholds, and scope without editing call sites.
+
+- `src/config/squad-yaml.ts` — reader with zod schema, mtime-keyed cache, and
+  the `applySkipPaths` / `applyDisableAgents` helpers. YAML-to-zod path uses
+  `js-yaml` (FAILSAFE_SCHEMA + numeric coercion for known fields). Looks up
+  `.squad.yaml` then `.squad.yml` at workspace_root; absent file falls back to
+  package defaults silently.
+- New tool `read_squad_config` — MCP wrapper for direct introspection by
+  non-Claude-Code clients or callers that build their own bundle.
+- `compose_squad_workflow` now reads `.squad.yaml` and: applies `skip_paths`
+  to changed_files BEFORE classification (skipped paths still count toward
+  risk signals — disabling a file from advisory does not make the change
+  less risky), then applies `disable_agents` to the selected squad. Returns
+  the resolved `config`, `skipped_paths`, and `disabled_agents` so callers
+  see why the slice list got narrower.
+- `compose_advisory_bundle` propagates `skip_paths` filtering through to
+  per-agent slices, so an agent never receives a path the composer hid.
+- New `CONFIG_READ_FAILED` error code.
+- New dep: `js-yaml` (^4.1) + `@types/js-yaml`. Battle-tested, MIT, ~70KB.
+- `force_agents` in tool calls still wins over `config.disable_agents` —
+  config is a default policy, not a veto over explicit caller intent.
+
+Validation: weights that don't sum to 100 across the listed agents → reject.
+Unknown agent names in `weights` or `disable_agents` → reject. Threshold or
+min_score outside 0-100 → reject. Errors carry `source` (file path) for
+diagnosability.
+
+Example `.squad.yaml`:
+
+```yaml
+weights:
+  senior-dev-security: 30 # PCI compliance
+  senior-dba: 22
+  senior-developer: 20
+  senior-architect: 15
+  senior-qa: 13
+threshold: 80
+min_score: 75
+skip_paths:
+  - "docs/**"
+  - "**/*.md"
+  - "**/generated/**"
+disable_agents:
+  - product-owner # internal tool, no PO involved
+```
+
+22 new tests cover reader (file presence, weights override, skip_paths,
+disable_agents, caching, mtime invalidation, glob matching). Backward
+compatible: callers that don't pass `workspace_root` to non-composer tools
+get the legacy behaviour (no config read).
+
+### Added — weighted rubric scorecard
+
+Each advisory agent now represents a dimension of a multi-dimensional rubric
+with a default weight. The consolidator emits a pre-formatted ASCII scorecard
+alongside the legacy verdict.
+
+- New tool `score_rubric` (`src/tools/score-rubric.ts`): pure function over
+  per-agent scores (0-100) and optional weight overrides; returns
+  `weighted_score`, per-dimension breakdown with bars, `passes_threshold`,
+  `ignored_agents`, and a pre-formatted `scorecard_text`.
+- `AgentDef` extended with `weight: number` and `dimension: string`. Default
+  weights sum to 100 across the seven advisory agents (Architecture 18%,
+  Security 18%, Application Code 18%, Data Layer 14%, Testing & QA 14%, Code
+  Quality 10%, Business & UX 8%). Meta-agents (tech-lead-planner,
+  tech-lead-consolidator) carry weight 0 — they don't score a dimension.
+- `apply_consolidation_rules` accepts optional per-agent `score`/`score_rationale`,
+  optional `weights` override, optional `threshold` (default 75), and optional
+  `min_score`. Returns `rubric: RubricOutput | null` and `downgraded_by_score`.
+  When `min_score` is set, an APPROVED verdict with weighted score below the
+  floor is downgraded to CHANGES_REQUIRED. Backward compatible: callers that
+  omit scores get the legacy output shape and verdict logic.
+- Each advisory agent file (`agents/*.md`) now ships a `## Score` section with
+  a calibration table (90-100 / 70-89 / 50-69 / 30-49 / 0-29 bands) specific
+  to that dimension, plus the protocol for emitting `Score: NN/100`.
+- Skill `skills/squad/SKILL.md` updated to capture per-agent scores into the
+  reports array and surface `rubric.scorecard_text` verbatim in the final
+  output. Tech-lead-planner/consolidator excluded (weight 0).
+- Weight renormalisation: when only a subset of agents scores (partial pass),
+  the rubric renormalises across the agents that actually scored. A 4-of-9
+  advisory still produces a meaningful weighted score over those 4.
+- `tests/score-rubric.test.ts` and `tests/consolidate-rubric.test.ts` cover
+  the math (renormalisation, weight overrides, sum=100 validation, threshold
+  edge cases), backward compatibility, and the `min_score` downgrade rule.
+
 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`.
+- Per-PR memory of accept/reject decisions feeding back into agent prompts.
+- Inline line-by-line annotations on the diff (one `gh` review comment per finding with file:line links).
+- GitHub Action wrapper for PR posting in CI.
+- Streaming SHA-256 over `fs.createReadStream` for any large bundled asset
+  reads (avoids `readFileSync` doubling memory).
+- Property-based tests for severity/consolidation rules via `fast-check`.
+
+## [0.6.0] - 2026-05-10
+
+### Architectural cleanup — separation of concerns
+
+This release rationalizes the role of each layer of the project. The MCP server
+owns deterministic primitives + agent definitions. The Claude Code plugin owns
+packaging (skill, commands, native subagents, MCP wiring). One skill (`squad`)
+hosts both `implement` and `review` modes — no client bifurcation, no skill
+fragmentation. Agent markdowns live in **one** place per install: the plugin's
+`agents/` directory at install time, exposed both as native Claude Code
+subagents and as MCP `agent://…` resources for non-Claude-Code clients.
+
+### Changed (BREAKING)
+
+- **Agent markdown filenames renamed to kebab-case** with YAML frontmatter so
+  Claude Code registers them as native subagents. Old (PascalCase) filenames
+  no longer exist:
+  - `agents/PO.md` → `agents/product-owner.md`
+  - `agents/Senior-Architect.md` → `agents/senior-architect.md`
+  - `agents/Senior-DBA.md` → `agents/senior-dba.md`
+  - `agents/Senior-Developer.md` → `agents/senior-developer.md`
+  - `agents/Senior-Dev-Reviewer.md` → `agents/senior-dev-reviewer.md`
+  - `agents/Senior-Dev-Security.md` → `agents/senior-dev-security.md`
+  - `agents/Senior-QA.md` → `agents/senior-qa.md`
+  - `agents/TechLead-Planner.md` → `agents/tech-lead-planner.md`
+  - `agents/TechLead-Consolidator.md` → `agents/tech-lead-consolidator.md`
+- **Shared docs moved to `agents/_shared/`**: `_Severity-and-Ownership.md`,
+  `Skill-Squad-Dev.md`, `Skill-Squad-Review.md`. They are not registered as
+  subagents; they're reference material. Cross-references inside agent files
+  updated accordingly.
+- **AgentName `'po'` renamed to `'product-owner'`** across the type, AGENTS
+  registry, AGENT_FILE_MAP, ownership matrix entries, MCP resource URI, and
+  tests — full consistency with the file/frontmatter name. MCP resource URI
+  changes from `agent://po` to `agent://product-owner`.
+- **Plugin manifest declares `agents/`**: `.claude-plugin/plugin.json` now
+  includes `"agents": "./agents/"`, registering the nine subagents natively
+  in Claude Code.
+- **Single `squad` skill replaces the two command-only entries.** Both
+  `/squad` and `/squad-review` invoke `skills/squad/SKILL.md`; the entry
+  command selects mode (`implement` vs `review`). Phases 2/4/8/9/11 only run
+  in implement mode.
+
+### Removed (BREAKING)
+
+- **`tools/sync-agents.mjs` deleted.** The plugin install path is the canonical
+  Claude Code distribution; non-Claude-Code MCP clients consume agent
+  definitions over MCP. Users on the previous "npm install + sync to
+  `~/.claude/`" flow should migrate to the plugin install (Path A in
+  INSTALL.md).
+- **`tests/sync-agents.test.ts` deleted** alongside the script.
+
+### Migration
+
+If you had `%APPDATA%\squad-mcp\agents` (Windows) or
+`$XDG_CONFIG_HOME/squad-mcp/agents` (Unix) overrides for the old PascalCase
+filenames, rename them to the new kebab-case names. The override allowlist and
+loader semantics are unchanged. Shared-doc overrides moved into a `_shared/`
+subdirectory under the same override root.
+
+If you depended on `~/.claude/agents/` being populated by the sync script,
+install the plugin (`/plugin install squad@gempack`) — Claude Code now
+registers the agents directly from the plugin's bundled `agents/` directory.
+
+### Added
+
+- `initLocalConfig` ensures the `_shared/` subdirectory exists before copying
+  shared docs (previously a latent bug on first init when the override root
+  did not yet contain a subdirectory).
 
 ## [0.5.0] - 2026-05-04
 
@@ -39,11 +293,11 @@ Planned for a future minor:
   (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
+  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>`.
+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
@@ -55,8 +309,8 @@ Planned for a future minor:
   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
+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).
@@ -291,7 +545,7 @@ content signals). No `0.2.0` git tag was created; that scope ships as part of
   - **CWD validation**: must be absolute, must exist, must be a directory,
     must contain a `.git` entry. Resolved via `realpath`.
   - **Hardening prefix**: every invocation prepends `-c core.fsmonitor=false
-    -c diff.external= -c core.hooksPath=NUL` (or `/dev/null`).
+-c diff.external= -c core.hooksPath=NUL` (or `/dev/null`).
   - **Environment scrub**: drops user env, sets `GIT_TERMINAL_PROMPT=0`,
     `GIT_OPTIONAL_LOCKS=0`, `GIT_CONFIG_NOSYSTEM=1`,
     `GIT_CEILING_DIRECTORIES=<parent of cwd>`.

package/INSTALL.md

@@ -4,10 +4,18 @@ This guide walks through installing `squad-mcp` in every supported host: Claude
 
 After install you get:
 
-- 12 deterministic MCP tools (Claude Code exposes them as `mcp__squad__*`; other hosts may use a different prefix)
+- 23 deterministic MCP tools (Claude Code exposes them as `mcp__squad__*`; other hosts may use a different prefix). Counts grow as new features land — the running server is authoritative; call `tools/list` to see the live count.
 - 12 MCP resources (`agent://*`, `severity://*`)
 - 3 MCP prompts (`squad_orchestration`, `agent_advisory`, `consolidator`)
-- 2 slash commands (`/squad`, `/squad-review`) — Claude Code only
+- 4 slash commands — Claude Code only:
+  - `/squad <task>` — implementation workflow
+  - `/squad-review [target]` — advisory-only review of an existing diff/branch/PR
+  - `/brainstorm <topic>` — pre-implementation research
+  - `/commit-suggest` — Conventional Commits message suggester (read-only)
+- Two on-disk stores under `.squad/` (versioned in git):
+  - `.squad/tasks.json` — atomic tasks decomposed from a PRD (see [`Tasks`](#path-d--using-the-tasks-store))
+  - `.squad/learnings.jsonl` — accept/reject decisions on past advisory findings (see [`Learnings`](#path-e--using-the-learnings-store))
+- Optional repo configuration in [`.squad.yaml`](#repo-configuration--squadyaml) (weights, skip paths, disabled agents, learnings/tasks paths, PR-posting policy).
 
 ## Prerequisites
 
@@ -44,11 +52,10 @@ The plugin bundles the MCP server, the slash commands, and the agent definitions
 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`).
+   - Ask Claude to call the `list_agents` tool from the `squad` MCP server. It should return 9 agents (`product-owner`, `tech-lead-planner`, `tech-lead-consolidator`, `senior-architect`, `senior-dba`, `senior-developer`, `senior-dev-reviewer`, `senior-dev-security`, `senior-qa`).
 
 5. **Use it.**
 
@@ -80,16 +87,9 @@ Then restart Claude Code.
 
 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
-> ```
+> **Path B vs Path A — what each path provides:** Path A (Claude Code plugin) registers agents, skills, slash commands, and the MCP server via the plugin manifest. Path B (npm package) ships **only the MCP server** (`dist/index.js`); slash commands and native subagents are Claude Code-specific concepts and don't apply to non-Claude-Code MCP clients. Those clients access the same agent definitions via MCP `agent://…` resources or the `get_agent_definition` tool exposed by the server.
 >
-> 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.
+> If you're running Claude Code, **always prefer Path A**. Path B exists for clients without a Claude-Code plugin layer (Claude Desktop, Cursor, Warp, Continue).
 
 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.
 
@@ -98,7 +98,7 @@ The package is published as [`@gempack/squad-mcp`](https://www.npmjs.com/package
 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
+npx -y @gempack/squad-mcp@0.6.0
 ```
 
 Releases are published from CI with [npm provenance](https://docs.npmjs.com/generating-provenance-statements). Verify the published tarball before configuring a host:
@@ -107,7 +107,7 @@ Releases are published from CI with [npm provenance](https://docs.npmjs.com/gene
 npm audit signatures @gempack/squad-mcp
 ```
 
-Pin in your host config the same way (e.g. `args: ["-y", "@gempack/squad-mcp@0.4.0"]`).
+Pin in your host config the same way (e.g. `args: ["-y", "@gempack/squad-mcp@0.6.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.
 
@@ -127,7 +127,7 @@ 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)
+- **Linux:** `~/.config/Claude/claude_desktop_config.json` (unofficial — not all Claude Desktop builds support Linux). Flatpak builds sandbox `~/.config/`; check `~/.var/app/com.anthropic.Claude/config/Claude/` if the standard path doesn't load. Snap builds use `~/snap/claude/current/.config/Claude/`.
 
 Add (or merge) the `squad` entry:
 
@@ -240,6 +240,137 @@ To point a host at your local build, replace `command: npx, args: -y @gempack/sq
 }
 ```
 
+## Repo configuration — `.squad.yaml`
+
+Drop a `.squad.yaml` (or `.squad.yml`) at the workspace root to override defaults per-project. Versioned with the code. Picked up automatically by the composers (`compose_squad_workflow`, `compose_advisory_bundle`).
+
+All keys optional; partial files merge with package defaults. Cached by mtime — long-running MCP servers pick up edits without restart.
+
+```yaml
+# .squad.yaml — example for a regulated fintech backend
+
+# Rubric weights (must sum to 100 across the agents you list).
+weights:
+  senior-dev-security: 30
+  senior-dba: 22
+  senior-developer: 20
+  senior-architect: 15
+  senior-qa: 13
+
+# Per-dimension flag threshold (default 75).
+threshold: 80
+
+# Quality floor: APPROVED with weighted score below this becomes CHANGES_REQUIRED.
+min_score: 75
+
+# Files excluded from advisory.
+skip_paths:
+  - "docs/**"
+  - "**/*.md"
+  - "**/generated/**"
+
+# Agents not relevant for this repo.
+disable_agents:
+  - product-owner
+
+# Tasks store (Path D below).
+tasks:
+  path: .squad/tasks.json
+  enabled: true
+
+# Learnings store (Path E below).
+learnings:
+  path: .squad/learnings.jsonl
+  max_recent: 50
+  enabled: true
+
+# PR posting (used by /squad-review with PR refs).
+pr_posting:
+  auto_post: false
+  request_changes_below_score: 60
+  omit_attribution_footer: false
+```
+
+Validation is strict: weights must sum to 100, unknown agent names rejected, threshold/min_score 0-100. `force_agents` in tool calls still wins over `disable_agents`.
+
+## Path D — Using the tasks store
+
+The squad's biggest source of token bloat is re-analysing the whole repo on every prompt. The tasks store fixes that: a PRD is decomposed into atomic tasks up front; the squad runs against ONE task's narrowed scope at a time.
+
+**Decompose a PRD (Claude Code):**
+
+```
+/squad-tasks docs/my-prd.md
+```
+
+The skill:
+
+1. Calls `compose_prd_parse` with the PRD text.
+2. Decomposes via the host LLM (no provider keys on the server).
+3. Shows you the parsed tasks; waits for your "record".
+4. Calls `record_tasks` only after confirmation.
+
+**Work tasks:**
+
+```
+/squad-next        # picks the highest-priority ready task
+/squad-task 5      # explicit pick by id
+```
+
+For each task, `slice_files_for_task` narrows the changed-files list to the task's `scope` glob; `compose_squad_workflow` runs against that slice with `agent_hints` as `force_agents` so only the relevant specialists wake up. When done, the skill flips status via `update_task_status`.
+
+**CLI for non-MCP environments:**
+
+```bash
+echo '[{"title":"Add CSRF","scope":"src/api/**"}]' | node tools/record-tasks.mjs
+node tools/list-tasks.mjs --status pending
+node tools/next-task.mjs --json
+node tools/update-task-status.mjs --task 5 --status done
+```
+
+The tasks file (`.squad/tasks.json` by default) is intended to live in git so the team's decomposition ships with the repo.
+
+## Path E — Using the learnings store
+
+Once `/squad-review` produces a verdict, you can record per-finding decisions (accept / reject + reason) into `.squad/learnings.jsonl`. Future advisory runs read the recent tail and inject it into agent + consolidator prompts so the squad stops re-raising findings the team has already considered.
+
+**Record a decision (Claude Code):**
+
+```
+record reject senior-dev-security "missing CSRF on POST /api/refund"
+  reason: CSRF terminated at API gateway
+  scope: src/api/**
+```
+
+The skill restates the decision and waits for explicit confirmation before calling `record_learning`. Per-finding authorisation is required — silence or "thanks" is not authorisation.
+
+**CLI helper:**
+
+```bash
+node tools/record-learning.mjs --reject \
+  --agent senior-dev-security \
+  --finding "missing CSRF on POST /api/refund" \
+  --reason "CSRF terminated at API gateway" \
+  --scope "src/api/**" \
+  --pr 42
+```
+
+The journal is append-only by design — corrections are appended, never amended.
+
+## Path F — Posting `/squad-review` to GitHub PRs
+
+When `/squad-review #42` runs, the verdict + scorecard can be posted to the PR via `gh pr review`. Default behaviour: dry-run + confirmation.
+
+```bash
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42 --dry-run
+# review the body, then:
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42
+```
+
+The CLI maps verdict → `gh` action deterministically (APPROVED → `--approve`, CHANGES_REQUIRED → `--comment`, REJECTED → `--request-changes`). Set `pr_posting.auto_post: true` in `.squad.yaml` to skip the second confirmation, but the skill still always shows the body before posting.
+
+Inviolable: never amend or delete a posted review through this skill (re-run for a fresh review); never post `--request-changes` on a PR you do not own without explicit user instruction.
+
 ## Local override of agent definitions
 
 The bundled agent markdowns can be overridden without forking. The loader picks ONE local override directory:
@@ -345,12 +476,13 @@ Both layers compose: prompt rule, `permissions.deny`, and the `commit-msg` hook.
 
 ## 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):
+The plugin ships these skills under `skills/` (auto-registered when the plugin is enabled):
 
-| 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. |
+| Skill            | Trigger                                                                                         | Purpose                                                                                                                                                                                                                           |
+| ---------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `squad`          | `/squad <task>`, `/squad-review [tgt]`, `/squad-tasks <prd>`, `/squad-next`, `/squad-task <id>` | Single skill, three modes. Implement runs the full orchestration. Review runs the advisory portion only on an existing diff/branch/PR. Tasks decomposes a PRD into atomic tasks and runs the squad on one task's scope at a time. |
+| `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:
 
@@ -385,10 +517,10 @@ Workflow positioning:
 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).
+- [ ] `list_agents` tool returns 9 agents (names: `product-owner`, `tech-lead-planner`, `tech-lead-consolidator`, `senior-architect`, `senior-dba`, `senior-developer`, `senior-dev-reviewer`, `senior-dev-security`, `senior-qa`).
+- [ ] `compose_squad_workflow` with arguments `{"workspace_root": "<absolute path to a git repo>", "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). **`workspace_root` must be an absolute path** — relative paths are rejected with `PATH_INVALID`.
 - [ ] Resources `agent://senior-architect` and `severity://_severity-and-ownership` are readable.
-- [ ] (Claude Code only) `/squad` and `/squad-review` autocomplete.
+- [ ] (Claude Code only) `/squad`, `/squad-review`, `/brainstorm`, and `/commit-suggest` autocomplete.
 
 ## Troubleshooting