@gempack/squad-mcp 0.3.1 → 0.6.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)
 
@@ -75,20 +75,31 @@ node dist/index.js
 
 ### Tools (deterministic, pure functions)
 
-| Tool | Purpose |
-|------|---------|
-| `detect_changed_files` | Hardened `git diff --name-status` 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. |
-| `slice_files_for_agent` | Filter a file list to those owned by a single agent. Used to build sliced advisory prompts. |
-| `validate_plan_text` | Advisory check for inviolable-rule violations in a plan (commit/push fences, emojis in code blocks, non-English identifiers, impl-before-approval). |
-| `compose_squad_workflow` | One-call pipeline: `detect_changed_files` → `classify_work_type` → `score_risk` → `select_squad`. |
-| `compose_advisory_bundle` | One-call full bundle: `compose_squad_workflow` + `slice_files_for_agent` per selected agent + `validate_plan_text`. |
-| `apply_consolidation_rules` | Aggregate advisory reports → final verdict (APPROVED / CHANGES_REQUIRED / REJECTED). |
-| `list_agents` | List configured agents with role, ownership, naming conventions. |
-| `get_agent_definition` | Return the full markdown system prompt for an agent (local override → embedded default). |
-| `init_local_config` | Copy embedded defaults to the local override directory so they can be edited. |
+| Tool                        | Purpose                                                                                                                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `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.                                                                                                         |
+| `slice_files_for_agent`     | Filter a file list to those owned by a single agent. Used to build sliced advisory prompts.                                                                                                                              |
+| `validate_plan_text`        | Advisory check for inviolable-rule violations in a plan (commit/push fences, emojis in code blocks, non-English identifiers, impl-before-approval).                                                                      |
+| `compose_squad_workflow`    | One-call pipeline: `detect_changed_files` → `classify_work_type` → `score_risk` → `select_squad`.                                                                                                                        |
+| `compose_advisory_bundle`   | One-call full bundle: `compose_squad_workflow` + `slice_files_for_agent` per selected agent + `validate_plan_text`.                                                                                                      |
+| `apply_consolidation_rules` | Aggregate advisory reports → final verdict (APPROVED / CHANGES_REQUIRED / REJECTED). Returns weighted rubric scorecard when reports carry per-dimension scores.                                                          |
+| `score_rubric`              | Pure rubric calculator. Takes per-agent scores (0-100) + optional weight overrides, returns weighted score, per-dimension breakdown, and pre-formatted ASCII scorecard.                                                  |
+| `read_squad_config`         | Read and resolve `.squad.yaml` (or `.squad.yml`) at workspace_root. Returns effective weights, threshold, min_score, skip_paths, disable_agents.                                                                         |
+| `read_learnings`            | Load past accept/reject decisions from `.squad/learnings.jsonl`. Filters by agent / decision / changed-file scope. Returns entries plus a markdown block ready to inject into agent or consolidator prompts.             |
+| `record_learning`           | Append one accept/reject decision to `.squad/learnings.jsonl`. Side-effecting; the skill (or CLI) is responsible for per-finding user authorisation.                                                                     |
+| `compose_prd_parse`         | Build a prompt + JSON schema for the host LLM to decompose a PRD into atomic tasks. Pure-MCP: server does NO LLM calls. Caller (skill) feeds the prompt to its model, then calls `record_tasks` after user confirmation. |
+| `list_tasks`                | Read tasks from `.squad/tasks.json`. Filters: status, agent (matches `agent_hints`), changed_files (glob match against task `scope`).                                                                                    |
+| `next_task`                 | Pick the next ready task: candidate status (default pending), all dependencies done, optional agent / changed_files filter. Tiebreak priority then id. Returns null + reason when none ready.                            |
+| `record_tasks`              | Bulk-create tasks. Allocates ids sequentially, validates dependencies resolve (forward refs in batch ok), rejects duplicates and self-deps. Atomic write.                                                                |
+| `update_task_status`        | Flip a task or subtask status: pending / in-progress / review / done / blocked / cancelled.                                                                                                                              |
+| `expand_task`               | Append subtasks to an existing task. Mechanical only — caller (skill or LLM) supplies the subtask inputs.                                                                                                                |
+| `slice_files_for_task`      | Filter a file list to those matching a task's `scope` glob. Same glob primitive as `skip_paths` and learnings scope.                                                                                                     |
+| `list_agents`               | List configured agents with role, ownership, naming conventions.                                                                                                                                                         |
+| `get_agent_definition`      | Return the full markdown system prompt for an agent (local override → embedded default).                                                                                                                                 |
+| `init_local_config`         | Copy embedded defaults to the local override directory so they can be edited.                                                                                                                                            |
 
 ### Prompts
 
@@ -98,10 +109,272 @@ node dist/index.js
 
 ### Resources
 
-- `agent://po`, `agent://tech-lead-planner`, `agent://tech-lead-consolidator`, `agent://senior-architect`, `agent://senior-dba`, `agent://senior-developer`, `agent://senior-dev-reviewer`, `agent://senior-dev-security`, `agent://senior-qa`.
+- `agent://product-owner`, `agent://tech-lead-planner`, `agent://tech-lead-consolidator`, `agent://senior-architect`, `agent://senior-dba`, `agent://senior-developer`, `agent://senior-dev-reviewer`, `agent://senior-dev-security`, `agent://senior-qa`. (Renamed from PascalCase / `po` in v0.6.0 — older 0.5.x consumers must use `agent://po` instead.)
 - `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/`:
+
+| Skill             | Trigger                     | Purpose                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/squad`          | implementation workflow     | Single skill, two modes. `/squad <task>` builds an approved plan, distributes work to specialist subagents in parallel, implements the change, consolidates via tech-lead. `/squad-review [target]` is the same skill in review mode — never implements, just produces an advisory verdict on an existing diff/branch/PR. Optional `--codex` second-opinion. |
+| `/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.                                                                                                                                                              |
+
+### Bundled subagents
+
+The plugin's `agents/` directory registers nine native Claude Code subagents you can also dispatch directly via `Task(subagent_type=…)`:
+
+`product-owner`, `senior-architect`, `senior-dba`, `senior-developer`, `senior-dev-reviewer`, `senior-dev-security`, `senior-qa`, `tech-lead-planner`, `tech-lead-consolidator`.
+
+The `/squad` skill orchestrates them. For non-Claude-Code MCP clients (Cursor, Claude Desktop, Warp), the same role markdowns are accessible through the MCP `agent://…` resources and `get_agent_definition` tool.
+
+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.
+
+## Repo configuration — `.squad.yaml`
+
+Drop a `.squad.yaml` (or `.squad.yml`) at the repo root to override defaults per-project. Versioned with the code, picked up automatically by `compose_squad_workflow` and `compose_advisory_bundle`.
+
+```yaml
+# .squad.yaml — example for a regulated fintech backend
+
+# Rubric weights (must sum to 100 across the agents you list).
+# Agents NOT listed are zeroed out — listing weights is an explicit choice
+# of which dimensions count for this repo.
+weights:
+  senior-dev-security: 30 # PCI compliance — security weighted higher
+  senior-dba: 22 # double-entry ledger, money on the line
+  senior-developer: 20
+  senior-architect: 15
+  senior-qa: 13
+
+# Per-dimension flag threshold (default 75). Below this, the dimension is
+# marked with ⚠ in the scorecard.
+threshold: 80
+
+# Quality floor: APPROVED with weighted score below this becomes
+# CHANGES_REQUIRED. Severity rules (Blocker/Major) take precedence.
+min_score: 75
+
+# Files excluded from advisory. Glob syntax: ** for any depth, * for one
+# segment, ? for one char. Useful for docs-only or generated paths.
+skip_paths:
+  - "docs/**"
+  - "**/*.md"
+  - "**/generated/**"
+  - "vendor/**"
+
+# Agents not relevant for this repo (e.g. internal tool, no PO involved).
+disable_agents:
+  - product-owner
+```
+
+All keys are optional; partial files merge with package defaults. `force_agents` in tool calls still wins over `disable_agents` (config is a default policy, not a veto over explicit caller intent). Validation is strict: weights that don't sum to 100, unknown agent names, or invalid threshold ranges are rejected with a clear error.
+
+The reader is cached by mtime — long-running MCP servers automatically pick up edits without a restart.
+
+## Learnings — persistent accept/reject memory
+
+Each time the team accepts or rejects an advisory finding, the decision can be appended to `.squad/learnings.jsonl`. Future runs of the squad load recent decisions and inject them into per-agent and consolidator prompts so the squad stops re-raising findings the team has already considered.
+
+```jsonl
+{"ts":"2026-04-12T15:02:31Z","pr":42,"agent":"senior-dev-security","severity":"Major","finding":"missing CSRF on POST /api/refund","decision":"reject","reason":"CSRF terminated at API gateway, see infra/edge.tf","scope":"src/api/**"}
+{"ts":"2026-04-15T09:18:11Z","pr":47,"agent":"senior-architect","severity":"Major","finding":"cross-module coupling Auth → Billing","decision":"accept","reason":"refactored to event bus"}
+```
+
+The file lives in git. Decisions are auditable in PR diffs.
+
+### Recording decisions
+
+Inside Claude Code, after `/squad-review` produces the verdict, tell the skill to record:
+
+```
+record reject senior-dev-security "missing CSRF on POST /api/refund"
+  reason: CSRF terminated at API gateway
+  scope: src/api/**
+```
+
+The skill confirms each decision and calls the `record_learning` MCP tool. **Per-finding authorisation is required** — silence or "thanks" is not authorisation.
+
+For non-MCP environments, use the 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
+```
+
+### How the squad uses them
+
+In Phase 5 (per-agent advisory) the skill calls `read_learnings(workspace_root, agent, changed_files)` and injects the rendered `## Past team decisions` block into the agent's prompt. In Phase 10 (consolidator) it does the same without an agent filter — the consolidator sees the full picture across agents.
+
+Each agent is told: when a current finding matches a previously **rejected** decision (similar agent + similar finding text + matching scope), suppress or downgrade severity unless the diff materially changes the rationale. When a finding contradicts a previously **accepted** decision, flag the contradiction explicitly.
+
+### Configuration
+
+Override defaults via `.squad.yaml`:
+
+```yaml
+learnings:
+  path: .squad/learnings.jsonl # default
+  max_recent: 50 # how many recent entries to inject (hard cap 200)
+  enabled: true # set false to disable injection without deleting the journal
+```
+
+The store reader is mtime-cached. The journal is append-only by design — the skill never amends or deletes past entries; correcting a stale decision means appending a new one.
+
+## Tasks — PRD-decomposed atomic work units
+
+The biggest source of token bloat in a long-running squad session is the squad re-analysing the whole repo for every prompt. The tasks store fixes that by decomposing a PRD into atomic tasks up front, then running the squad on ONE task's narrowed scope at a time.
+
+```jsonc
+// .squad/tasks.json (excerpt)
+{
+  "version": 1,
+  "tasks": [
+    {
+      "id": 1,
+      "title": "Add CSRF token to checkout flow",
+      "status": "done",
+      "dependencies": [],
+      "priority": "high",
+      "scope": "src/api/checkout/**",
+      "agent_hints": ["senior-dev-security", "senior-developer"],
+      "test_strategy": "POST without token → 403; POST with token → 200.",
+      "subtasks": [],
+      "created_at": "2026-05-08T12:00:00Z",
+      "updated_at": "2026-05-09T15:30:00Z"
+    },
+    {
+      "id": 2,
+      "title": "Wire CSRF middleware into refund endpoint",
+      "status": "pending",
+      "dependencies": [1],
+      "priority": "high",
+      "scope": "src/api/refund/**",
+      "subtasks": [],
+      ...
+    }
+  ]
+}
+```
+
+`scope` (glob) and `agent_hints` are squad-mcp-specific additions on top of the claude-task-master shape — they let `slice_files_for_task` and `compose_squad_workflow` narrow the advisory automatically.
+
+### Decomposing a PRD
+
+Inside Claude Code:
+
+```
+/squad-tasks docs/prd-payments-refactor.md
+```
+
+The skill (Phase 0.5):
+
+1. Calls `compose_prd_parse` with the PRD text.
+2. Receives a prompt + JSON schema and runs them through Claude.
+3. Shows you the parsed tasks — title, deps, priority, scope, agent_hints — for review.
+4. Calls `record_tasks` only after you say "record" / "go" / "yes".
+
+The parse is **pure-MCP**: the squad-mcp server never makes LLM calls. The host (Claude Code, Cursor, Warp) does the inference. No provider keys in the server, no surprises for non-Claude clients.
+
+### Working 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`.
+- `compose_squad_workflow` runs against that slice; if `agent_hints` is set, only those agents wake up.
+- Phase 1 onward proceeds normally, just with much less context.
+- When done, the skill flips status to `done` via `update_task_status`.
+
+### Configuration
+
+Override defaults via `.squad.yaml`:
+
+```yaml
+tasks:
+  path: .squad/tasks.json # default
+  enabled: true # set false to silence reads without deleting the file
+```
+
+Writes (`record_tasks`, `update_task_status`, `expand_task`) stay open even when reads are disabled — same policy as learnings. Disabling injection should not throw away the journal.
+
+### CLI for non-MCP environments
+
+Mirroring the post-review and record-learning helpers:
+
+```bash
+# decompose offline (you generate the JSON yourself or via another tool)
+echo '[{"title":"Add CSRF","scope":"src/api/**"}]' | node tools/record-tasks.mjs
+
+# inspect
+node tools/list-tasks.mjs --status pending
+node tools/next-task.mjs --json
+
+# flip status from CI
+node tools/update-task-status.mjs --task 5 --status done
+```
+
+The CLIs share `tools/_tasks-io.mjs` for read/write and require only node 18+. Schema validation is lighter than the MCP tool — production use should prefer the MCP path.
+
+## Posting reviews to GitHub PRs
+
+Once the squad runs, you can post the verdict + scorecard as a `gh pr review` directly. The skill `/squad-review #42` runs the advisory and offers to post the result; default behaviour is **dry-run + confirmation** — Claude shows the exact `gh` command and the markdown body, then waits for your "go" before posting.
+
+```bash
+# manual usage (outside the skill)
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42 --dry-run
+# prints: gh pr review 42 --approve --body-file - <<'EOF' ... EOF
+
+# actually post
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42
+```
+
+The CLI maps verdict → `gh` action deterministically:
+
+| Verdict                                            | Score signal           | `gh` action                        |
+| -------------------------------------------------- | ---------------------- | ---------------------------------- |
+| `REJECTED`                                         | —                      | `--request-changes` (blocks merge) |
+| `CHANGES_REQUIRED`                                 | —                      | `--comment` (advisory)             |
+| `APPROVED` + `downgraded_by_score: true`           | weighted < `min_score` | `--comment`                        |
+| `APPROVED` + score < `request_changes_below_score` | (opt-in floor)         | `--request-changes`                |
+| `APPROVED` otherwise                               | passes threshold       | `--approve`                        |
+
+### Auto-post (opt-in)
+
+If `.squad.yaml` has `pr_posting.auto_post: true`, the skill posts without the second confirmation prompt — but **always shows the body first**. Auto-post means "skip the second yes/no", not "skip the preview".
+
+```yaml
+pr_posting:
+  auto_post: true # default false — always asks
+  request_changes_below_score: 50 # below this, post --request-changes instead of --approve
+  omit_attribution_footer: false # default false — footer present
+```
+
+Requires `gh` CLI in PATH and authenticated (`gh auth login`). The CLI exits 3 with a clear message if `gh` is missing.
+
 ## Detection strategy (`select_squad` / `slice_files_for_agent`)
 
 Three layers, in order of strength:
@@ -114,13 +387,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
 
@@ -128,11 +406,17 @@ Run the `init_local_config` tool once to seed the local directory with defaults
 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)
+├── agents/                     # Native subagents + shared docs
+│   ├── *.md                    # 9 subagent definitions (kebab-case, with frontmatter)
+│   └── _shared/                # severity matrix + skill specs (not loaded as subagents)
+├── commands/                   # Slash commands (/squad, /squad-review, /brainstorm, /commit-suggest)
+├── skills/                     # Bundled skills
+│   ├── squad/                  # single skill, two modes (implement | review)
+│   ├── brainstorm/
+│   └── commit-suggest/
 ├── src/
 │   ├── index.ts                # stdio entry
-│   ├── tools/                  # MCP tools (10 deterministic functions)
+│   ├── tools/                  # MCP tools (23 deterministic functions)
 │   ├── resources/              # MCP resources + agent loader
 │   ├── prompts/                # MCP prompt templates
 │   ├── exec/git.ts             # hardened git execution layer
@@ -141,6 +425,8 @@ squad-mcp/
 │   └── config/
 │       └── ownership-matrix.ts # agents, work types, content/path patterns
 ├── tests/                      # vitest unit + integration + stdio smoke
+├── tools/
+│   └── git-hooks/commit-msg    # opt-in hook rejecting AI-attribution trailers
 └── dist/                       # compiled JS (gitignored, shipped via npm)
 ```
 

package/agents/{Skill-Squad-Dev.md → _shared/Skill-Squad-Dev.md}

@@ -341,10 +341,30 @@ Spawn `tech-lead-consolidator` with every advisory report and the delivered delt
 | Parameter | Type   | Default | Description |
 |-----------|--------|---------|-------------|
 | --codex   | flag   | off     | Enable Codex for plan validation and implementation review |
+| --quick   | flag   | off     | Quick mode (see below). Trades depth for speed. Mutually exclusive with `--codex`. |
 | squad     | string | auto    | Specific squad or "auto" for detection |
 | plan-only | bool   | false   | Build the plan only, do not execute |
 | verbose   | bool   | false   | Show individual agent reports inline |
 
+## Quick Mode (`--quick`)
+
+Reduced agent set, terse prompts, condensed delivery. Suitable for small fixes, isolated changes, or iterative work where a full squad pass is overkill. Roughly one third of the normal time and tokens.
+
+Phase deltas vs. normal mode:
+
+| Phase | Normal | Quick |
+|-------|--------|-------|
+| Plan | Full plan with risks/decisions/tests | Condensed: objective, files, top 1-2 risks. Skip alternatives table. |
+| Codex plan validation | Opt-in via `--codex` | Force-disabled. `--quick --codex` is rejected. |
+| User approval gate | Always required | Auto-proceed when risk Low AND scope ≤3 files AND no security/data path. Otherwise still gates. |
+| Squad | Auto-detect 3-7 specialists + tech-lead | Hard cap: 1 specialist + tech-lead. Specialist = work-type primary. |
+| Agent prompts | Full template | "Flag only Blocker/Major. ≤200 words. No long template. If clean, reply 'No issues in scope.'" |
+| Codex review | Opt-in | Skipped (force-disabled with `--quick`) |
+| Tech-lead consolidator | Always | Skipped when zero Blocker/Major from specialist |
+| Delivery | Full report | Condensed: objective, files, tests, residual risks |
+
+Critical-change auto-fallback: if scope touches `auth`, `crypto`, `permissions`, `Program.cs`, `Startup.cs`, migrations, EF mappings, or `appsettings`, fall back to normal mode with warning `Quick mode disabled — change touches security/data layer. Running full workflow.`.
+
 ## Usage Examples
 
 ```
@@ -358,12 +378,19 @@ Spawn `tech-lead-consolidator` with every advisory report and the delivered delt
 
 /squad refactor ExchangeUsdService to split responsibilities
 -> Plan + Planner -> User approves -> Advisory -> Implement -> Consolidator
+
+/squad --quick rename a misspelled local variable in BalanceController
+-> Quick mode: condensed plan, 1 specialist + tech-lead, terse prompts, condensed delivery
+
+/squad --quick --codex anything
+-> Error: --quick is mutually exclusive with --codex
 ```
 
 ## Inviolable Rules
-1. Every implementation starts from an approved plan.
-2. Codex only runs with user consent (flag or confirmed auto-suggestion).
-3. TechLead-Consolidator always delivers the final verdict.
+1. Every implementation starts from a plan (approved explicitly, or auto-proceeded under `--quick` when risk Low).
+2. Codex only runs with user consent (flag or confirmed auto-suggestion). Never combined with `--quick`.
+3. TechLead-Consolidator always delivers the final verdict in normal mode. Under `--quick`, skipped only when the specialist reports zero Blocker/Major findings.
 4. Advisory agents do not implement — they assess and recommend; Claude implements.
 5. Method names in English. No emojis.
 6. Never run commit or push.
+7. Quick mode auto-fallback: scope touching security/data layers forces full workflow.

package/agents/{Skill-Squad-Review.md → _shared/Skill-Squad-Review.md}

@@ -232,6 +232,67 @@ If an agent did not participate, mark as "Not evaluated".
 | scope     | string | branch  | "branch" (branch diff), "file:path" (specific file), "commit:hash" |
 | base      | string | master  | Base branch for the diff |
 | verbose   | bool   | false   | If true, show full individual reports; if false, only the consolidated one |
+| --quick   | flag   | off     | Quick mode (see below). Trades depth for speed. Mutually exclusive with `--codex`. |
+
+## Quick Mode (`--quick`)
+
+Reduced agent set, terse prompts, condensed output. Goal: usable verdict in roughly one third of the normal time and tokens. Suitable for iterative work, small diffs, or sanity checks before a full review.
+
+Phase deltas vs. normal mode:
+
+| Aspect | Normal | Quick |
+|--------|--------|-------|
+| Agents | Auto-detect 3-7 specialists + tech-lead | Hard cap: 1 specialist + tech-lead. Specialist defaults to `senior-dev-reviewer` (or focus mode primary) |
+| Per-agent prompt | Full template | "Flag only Blocker/Major in your domain. ≤200 words. No scorecard. No comments-by-file table. If clean: 'No issues in scope.'" |
+| Tech-lead consolidator | Always runs | Skipped when zero Blocker/Major reported by specialist |
+| Codex | Opt-in via `--codex` | Force-disabled. `--quick --codex` rejected. |
+| Critical-change auto-fallback | N/A | Diff touching `auth`, `crypto`, `permissions`, `Program.cs`, `Startup.cs`, migrations, `appsettings` falls back to normal mode with warning |
+| Output | Full Markdown with scorecard, per-file comments, individual reports | Condensed: verdict + top 3 issues + "run without --quick for full review" hint |
+
+Quick agent prompt:
+
+```
+You are participating in a quick squad review. Be terse.
+
+## Context
+{user prompt}
+
+## Files to Review
+{diff stat + the diff itself}
+
+## Your Task
+Report ONLY Blocker and Major findings within your ownership.
+Hard limit: 200 words total. No scorecard. No table.
+If you find nothing, reply exactly: "No issues in scope."
+Format each finding as one line: `[Severity] file:line — problem; fix.`
+```
+
+Quick output:
+
+```
+# Squad Review (quick) — {short description}
+
+Squad: {agent names}
+Verdict: {APPROVED | CHANGES REQUIRED | REJECTED}
+
+Top issues:
+1. [Severity] file:line — problem; fix.
+2. [Severity] file:line — problem; fix.
+3. [Severity] file:line — problem; fix.
+
+(Run without --quick for full scorecard, per-file comments, and individual reports.)
+```
+
+When the specialist reports `No issues in scope.` and tech-lead is skipped:
+
+```
+# Squad Review (quick) — {short description}
+
+Squad: {specialist}
+Verdict: APPROVED — no Blocker or Major findings.
+
+(Run without --quick for full scorecard.)
+```
 
 ## Usage Examples
 
@@ -247,6 +308,15 @@ If an agent did not participate, mark as "Not evaluated".
 
 /squad-review full
 -> Every agent; complete review
+
+/squad-review --quick
+-> Quick mode: 1 specialist + tech-lead, terse prompts, condensed output
+
+/squad-review --quick code
+-> Quick code-quality review (senior-dev-reviewer + tech-lead)
+
+/squad-review --quick --codex
+-> Error: --quick is mutually exclusive with --codex
 ```
 
 ## Considerations

package/agents/{PO.md → product-owner.md}

@@ -1,6 +1,12 @@
+---
+name: product-owner
+description: Product Owner. Validates business value, functional requirements, and UX. Use for features, business-rule changes, and user-facing surfaces.
+model: inherit
+---
+
 # PO (Product Owner)
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Business representative in technical review. Ensures every implementation delivers real value to the end user and aligns with product goals.
@@ -82,3 +88,29 @@ Objective summary of the evaluation.
 - Be pragmatic: not every gap is a blocker, classify by severity
 - Frame impact in business terms, not technical ones
 - Without a user story, judge by observable behavior and product common sense
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Business & UX`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: requirement matches the change; UX clear; business value evident.
+- 70-89: minor mismatch with stated requirement or UX awkwardness.
+- **50-69: one Major — business rule contradicted, UX broken on critical flow, requirement absent.**
+- 30-49: change does not deliver claimed value; conflicts with PO intent.
+- 0-29: should not be built; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.

package/agents/{Senior-Architect.md → senior-architect.md}

@@ -1,6 +1,12 @@
+---
+name: senior-architect
+description: Senior Architect. Guards module boundaries, coupling, dependency direction, DI lifetimes, and scalability. Use for structural changes and new modules.
+model: inherit
+---
+
 # Senior-Architect
 
-> Reference: [Severity and Ownership Matrix](_Severity-and-Ownership.md)
+> Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
 Guardian of architectural integrity. Evaluates design decisions with a long-term lens and keeps the solution from eroding boundaries.
@@ -119,3 +125,29 @@ Summary of the diagnosis and long-term view.
 - Distinguish "ideal" from "acceptable for now"
 - Avoid astronaut architecture — prefer pragmatic solutions
 - If the issue is implementation (not design), forward to the right agent
+
+## Score
+
+At the end of your advisory output, emit exactly:
+
+```
+Score: <NN>/100
+Score rationale: <one sentence on what drove the score>
+```
+
+The score is YOUR dimension's contribution to the squad rubric (`Architecture`). The consolidator will weight it against other agents and compare against the threshold (default 75) to produce the final scorecard.
+
+### Calibration
+
+- 90-100: clean module/domain boundaries, DI lifetimes correct, no coupling regression, extensibility clear.
+- 70-89: minor issues (over-eager abstraction, ambiguous responsibility split) but no actionable Major.
+- **50-69: at least one Major (cross-module coupling, wrong DI lifetime, hidden mutable state).**
+- 30-49: multiple Majors or one Blocker that endangers structural integrity.
+- 0-29: architecture-level break; halt.
+
+### Notes
+
+- Score is per-agent. Do not score other dimensions.
+- Score reflects the slice of files you reviewed, not the whole change.
+- A score of 0 means halt — equivalent to a Blocker. Do not emit 0 unless you would also raise a Blocker.
+- An honest 65 is more useful than a generous 80; the rubric is auditable.