feat: add auto-sidecar skills (review, unblock, security)

CLAUDE.md

@@ -163,7 +163,7 @@ scripts/
 ├── generate-icon.js  # Generate app icon PNG from SVG source.
 ├── integration-test.sh
 ├── list-models.js
-├── postinstall.js  # Install skill file to ~/.claude/skills/sidecar/
+├── postinstall.js  # Install skill files to ~/.claude/skills/
 ├── test-tools.sh
 ├── validate-docs.js  # * Main entry point.
 ├── validate-thinking.js

docs/bmad-workflow.md

@@ -0,0 +1,110 @@
+# BMAD-METHOD Workflow Reference
+
+Reference for the auto-bmad-method-check skill. Captures all workflows, artifacts, dependencies, and checkpoints.
+
+## Phases & Workflows
+
+| Phase | Workflow | Agent | Input Dependencies | Output Artifact | Checkpoint |
+|---|---|---|---|---|---|
+| **1: Analysis** (optional) | Brainstorming | Mary (Analyst) | None | `brainstorming-report.md` | Human reviews report |
+| | Market Research | Mary | None (needs web search) | `research-*.md` | Human reviews findings |
+| | Domain Research | Mary | None | `research-*.md` | Human reviews findings |
+| | Technical Research | Mary | None | `research-*.md` | Human reviews findings |
+| | Create Product Brief | Mary | Brainstorming/research (optional) | `product-brief.md` | Human reviews brief |
+| **2: Planning** (required) | Create PRD | John (PM) | Product brief (optional) | `PRD.md` | Human reviews PRD |
+| | Validate PRD | John | `PRD.md` | Validation report | Human reviews findings |
+| | Edit PRD | John | `PRD.md` | Updated `PRD.md` | Human reviews edits |
+| | Create UX Design | Sally (UX) | `PRD.md` | `ux-design-specification.md` | Human reviews UX spec |
+| **3: Solutioning** | Create Architecture | Winston (Architect) | `PRD.md` (+ UX spec optional) | `architecture.md` + ADRs | Human reviews arch decisions |
+| | Create Epics & Stories | John | `PRD.md` + `architecture.md` | `epics.md` (or sharded) | Human reviews breakdown |
+| | Check Implementation Readiness | Winston/John | PRD + Architecture + Epics (+ UX) | PASS / CONCERNS / FAIL | **Gate** — must pass before Phase 4 |
+| **4: Implementation** | Sprint Planning | Bob (SM) | Epics files | `sprint-status.yaml` | One-time setup |
+| | Sprint Status | Bob | `sprint-status.yaml` | Status summary + risk flags | Informational |
+| | Create Story | Bob | Sprint status + Epics + all artifacts | `story-{e}-{s}-{slug}.md` | Human reviews story before dev |
+| | Dev Story | Amelia (Dev) | Story file (status: ready-for-dev) | Working code + tests | HALTs on blockers |
+| | Code Review | Amelia/Barry | Story file + git changes | Approved or Changes Requested | Human decides on action items |
+| | Correct Course | Bob/John | PRD + Epics + sprint context | `sprint-change-proposal-*.md` | Human approves proposal |
+| | Retrospective | Bob | All completed stories in epic | `epic-{N}-retro-{date}.md` | Significant Discovery Alert if assumptions shifted |
+| **Quick Flow** | Quick Spec | Barry (Solo Dev) | None | `tech-spec.md` | Human reviews spec |
+| | Quick Dev | Barry | `tech-spec.md` or direct instructions | Working code + tests | Self-review then human |
+| **Cross-cutting** | Generate Project Context | Mary | Codebase scan | `project-context.md` | Used by 7+ workflows |
+| | BMad Help | Any | Project state inspection | Next-step guidance | Runs after every workflow |
+
+## Dependency Chain
+
+```text
+Brainstorming/Research ──> Product Brief ──> PRD ──> UX Design (optional)
+                                               ├──> Architecture
+                                               └──> Architecture ──> Epics/Stories
+                                                                       │
+                                              Implementation Readiness <┘ (GATE)
+                                                        │
+                                              Sprint Planning (once)
+                                                        │
+                                              Create Story ──> Dev Story ──> Code Review
+                                                   ^                             │
+                                                   └─────── (next story) ────────┘
+                                                                                 │
+                                              Epic complete ──> Retrospective ───┘
+```
+
+## Artifact-to-Input Mapping
+
+Used by auto-bmad-method-check to determine which input documents to include in sidecar reviews.
+
+| Output Artifact | Input Documents |
+|---|---|
+| `brainstorming-report.md` | None (freeform ideation) |
+| `research-*.md` | None (primary research) |
+| `product-brief.md` | `brainstorming-report.md`, `research-*.md` (if they exist) |
+| `PRD.md` | `product-brief.md` (if exists) |
+| `ux-design-specification.md` | `PRD.md` |
+| `architecture.md` | `PRD.md`, `ux-design-specification.md` (if exists) |
+| `epics.md` | `PRD.md`, `architecture.md` |
+| Implementation Readiness | `PRD.md`, `architecture.md`, `epics.md`, `ux-design-specification.md` (if exists) |
+| `sprint-status.yaml` | `epics.md` |
+| `story-*.md` | `epics.md`, `PRD.md`, `architecture.md`, `sprint-status.yaml` |
+| `sprint-change-proposal-*.md` | `PRD.md`, `epics.md`, affected `story-*.md` files |
+| `epic-*-retro-*.md` | All `story-*.md` in that epic, previous retro (if exists) |
+| `tech-spec.md` | None (Quick Flow — standalone) |
+
+## Agents
+
+| Agent | Name | Personality | Primary Workflows |
+|---|---|---|---|
+| Analyst | Mary | "Excited treasure hunter" | Brainstorming, Research, Product Brief, Project Context |
+| Product Manager | John | "Asks WHY relentlessly like a detective" | PRD, Validate/Edit PRD, Epics, Readiness Check, Course Correction |
+| Architect | Winston | "Calm, pragmatic tones" | Architecture, Readiness Check |
+| Scrum Master | Bob | "Crisp, checklist-driven, zero ambiguity tolerance" | Sprint Planning/Status, Create Story, Retrospective, Course Correction |
+| Developer | Amelia | "Ultra-succinct, speaks in file paths" | Dev Story, Code Review |
+| UX Designer | Sally | "Paints pictures with words" | UX Design |
+| Quick Flow Solo Dev | Barry | "Direct, no fluff, just results" | Quick Spec, Quick Dev, Code Review |
+| Tech Writer | Paige | "Patient educator" | Document Project |
+
+## Key Design Principles
+
+- **Micro-file architecture**: Steps loaded one at a time to prevent LLM "lost in middle" issues
+- **Human must approve** every step transition — no autonomous progression
+- **Fresh conversations** per workflow to keep context clean
+- **Scale-adaptive**: Quick Flow (1-15 stories), BMad Method (10-50+), Enterprise (30+)
+- **`project-context.md`** acts as the "constitution" for consistent AI agent behavior
+
+## Standard Artifact Locations
+
+```text
+_bmad-output/
+  planning-artifacts/
+    brainstorming-report.md
+    product-brief.md
+    research-*.md
+    PRD.md
+    ux-design-specification.md
+    architecture.md
+    epics.md (or epics/ directory)
+    sprint-change-proposal-*.md
+  implementation-artifacts/
+    sprint-status.yaml
+    story-*.md
+    epic-*-retro-*.md
+  project-context.md
+```

scripts/postinstall.js

@@ -13,10 +13,22 @@ const path = require('path');
 const os = require('os');
 const { execFileSync } = require('child_process');
 
-const SKILL_SOURCE = path.join(__dirname, '..', 'skill', 'SKILL.md');
+const SKILL_DIR = path.join(__dirname, '..', 'skill');
+const SKILL_SOURCE = path.join(SKILL_DIR, 'SKILL.md');
 const SKILL_DEST_DIR = path.join(os.homedir(), '.claude', 'skills', 'sidecar');
 const SKILL_DEST = path.join(SKILL_DEST_DIR, 'SKILL.md');
 
+let AUTO_SKILLS = [];
+try {
+  AUTO_SKILLS = fs
+    .readdirSync(SKILL_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith('auto-'))
+    .map((entry) => entry.name)
+    .sort();
+} catch {
+  // skill/ directory missing — continue with empty list
+}
+
 const MCP_CONFIG = { command: 'npx', args: ['-y', 'claude-sidecar@latest', 'mcp'] };
 
 /**
@@ -50,7 +62,7 @@ function addMcpToConfigFile(configPath, name, config) {
   return status;
 }
 
-/** Install skill file to ~/.claude/skills/sidecar/ */
+/** Install skill files to ~/.claude/skills/ */
 function installSkill() {
   try {
     fs.mkdirSync(SKILL_DEST_DIR, { recursive: true });
@@ -59,6 +71,32 @@ function installSkill() {
   } catch (err) {
     console.error(`[claude-sidecar] Warning: Could not install skill: ${err.message}`);
   }
+
+  const skillsRoot = path.join(os.homedir(), '.claude', 'skills');
+  for (const name of AUTO_SKILLS) {
+    try {
+      const src = path.join(SKILL_DIR, name, 'SKILL.md');
+      // Install as top-level skill (e.g., ~/.claude/skills/sidecar-auto-review/)
+      // so Claude Code discovers it in the available skills list
+      const destDir = path.join(skillsRoot, `sidecar-${name}`);
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(src, path.join(destDir, 'SKILL.md'));
+      console.log(`[claude-sidecar] Skill installed: sidecar-${name}`);
+
+      // Clean up old nested location (~/.claude/skills/sidecar/<name>/)
+      const oldDir = path.join(SKILL_DEST_DIR, name);
+      try {
+        if (fs.existsSync(path.join(oldDir, 'SKILL.md'))) {
+          fs.unlinkSync(path.join(oldDir, 'SKILL.md'));
+          fs.rmdirSync(oldDir);
+        }
+      } catch {
+        // Old location doesn't exist or already cleaned — ignore
+      }
+    } catch (err) {
+      console.error(`[claude-sidecar] Warning: Could not install ${name} skill: ${err.message}`);
+    }
+  }
 }
 
 /** Register MCP server in Claude Code config */

skill/SKILL.md

@@ -1005,6 +1005,23 @@ sidecar start --model gemini --prompt "Task"
 
 ---
 
+## Auto-Skills: Contextual Sidecar Triggers
+
+Sidecar includes auto-skills that fire automatically at key workflow moments. These are NOT user-invocable — they trigger based on conversation context. When their conditions are met, you MUST check the corresponding skill and offer to run it.
+
+| Auto-Skill | Trigger Condition | What It Does |
+|------------|-------------------|--------------|
+| `auto-review` | You have finished implementing changes and are about to tell the user "done" | Offers sidecar code review of the diff before finalizing |
+| `auto-unblock` | You have tried 5+ distinct approaches to fix a bug and all have failed | Offers sidecar brainstorming session with a different model |
+| `auto-security` | User says "commit", "push", "create PR", or you are about to run git commit/push/gh pr create | Offers sidecar security scan of staged changes before commit |
+| `auto-bmad-method-check` | A BMAD-METHOD artifact (PRD, architecture, epics, story, etc.) has just been written or updated in `_bmad-output/` | Offers sidecar second-opinion review of the artifact |
+
+**How to use:** When you recognize a trigger condition above, invoke the skill (e.g., `/sidecar-auto-review`) or read it from `~/.claude/skills/sidecar-<skill-name>/SKILL.md` and follow its procedure. Each skill will prompt the user for confirmation before spawning any sidecars.
+
+**Skip conditions (common to all):** Skip if the `mcp__sidecar__sidecar_start` tool is not available, or if a sidecar review already ran for the same content.
+
+---
+
 ## Quick Start Checklist
 
 1. [ ] Install sidecar: `npm install -g claude-sidecar`