jrenaldi79 · ellisjr · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/CLAUDE.md b/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/sidecar/
 ├── test-tools.sh
 ├── validate-docs.js  # * Main entry point.
 ├── validate-thinking.js

diff --git a/docs/auto-skill-invocation-research.md b/docs/auto-skill-invocation-research.md
@@ -0,0 +1,177 @@
+# Auto-Skill Invocation: Research & Recommendations
+
+Research into how Claude Code skills achieve reliable invocation, with specific recommendations for improving sidecar auto-skill trigger reliability.
+
+## Background
+
+Sidecar ships four auto-skills — `auto-review`, `auto-unblock`, `auto-security`, and `auto-bmad-method-check` — that fire contextually at key workflow moments. Unlike user-invocable skills (which have slash commands like `/commit`), auto-skills rely on Claude recognizing trigger conditions in the conversation and reading the skill file proactively.
+
+The question: **how do we ensure Claude actually fires these skills when conditions are met?**
+
+## How Claude Code Skills Work
+
+### Skill Discovery
+
+Skills live as `SKILL.md` files with YAML frontmatter in two locations:
+- `~/.claude/skills/<name>/SKILL.md` — user/package skills
+- `~/.claude/plugins/cache/<plugin>/skills/<name>/SKILL.md` — plugin skills
+
+Claude discovers skills via the **Skill tool**, which scans these directories and exposes all SKILL.md files. The `description` field in frontmatter serves as the **declarative trigger specification** — Claude evaluates it against conversation state to decide whether to invoke.
+
+### Invocation Pipeline
+
+```text
+1. Skill tool scans filesystem → builds list of available skills
+2. Skill descriptions appear in system reminders ("available skills" block)
+3. Claude evaluates descriptions against conversation state each turn
+4. If match → Claude reads the full SKILL.md and follows its procedure
+```
+
+### Key Mechanism: The "Available Skills" System Reminder
+
+Every turn, Claude sees a system reminder listing available skills with their descriptions. This is the primary discovery mechanism. **Skills that appear in this list are far more likely to be invoked** because Claude evaluates them on every turn.
+
+## How Superpowers Achieves Near-100% Reliability
+
+The Superpowers plugin (Claude's official skill framework) uses a three-layer reinforcement strategy:
+
+### Layer 1: SessionStart Hook (Most Critical)
+
+Superpowers registers a **synchronous SessionStart hook** that fires on every startup, resume, clear, and compact event. This hook:
+
+1. Reads `using-superpowers/SKILL.md` from disk
+2. Injects its content into the system prompt via `experimental.chat.system.transform`
+3. Wraps it in `<EXTREMELY_IMPORTANT>` tags
+
+This means the meta-instruction is present **before any user input**, on every session.
+
+**Hook registration** (`hooks.json`):
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "startup|resume|clear|compact",
+      "hooks": [{
+        "type": "command",
+        "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+        "async": false
+      }]
+    }]
+  }
+}
+```
+
+### Layer 2: Meta-Instruction
+
+The injected content contains a forceful meta-instruction:
+
+> "If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill. This is not negotiable. This is not optional. You cannot rationalize your way out of this."
+
+It also includes a "Red Flags" table of rationalizations Claude should watch for (e.g., "This is just a simple question" → "Questions are tasks. Check for skills.").
+
+### Layer 3: Available Skills List
+
+All Superpowers skills appear in the "available skills" system reminder with descriptions like:
+- `systematic-debugging: Use when encountering any bug, test failure, or unexpected behavior`
+- `brainstorming: You MUST use this before any creative work`
+
+Claude sees these every turn, making pattern matching automatic.
+
+### Why This Works
+
+The three layers create **redundant triggering paths**:
+- Even if Claude skips the skill check, the meta-instruction reminds it
+- Even if the meta-instruction is missed, the skills list surfaces matches
+- Even if the skills list is scrolled past, the SessionStart hook re-injects on context reset
+
+## Where Sidecar Auto-Skills Stand Today
+
+### What We Have
+
+1. **SKILL.md files** with `TRIGGER when:` clauses in descriptions — installed to `~/.claude/skills/sidecar/auto-*/`
+2. **Main sidecar skill** (`~/.claude/skills/sidecar/SKILL.md`) — appears in the available skills list
+3. **MCP tools** — `sidecar_start`, `sidecar_status`, `sidecar_read` available when MCP server is running
+
+### The Gap
+
+| Mechanism | Superpowers | Sidecar Auto-Skills |
+|-----------|-------------|---------------------|
+| SessionStart hook | Yes — injects meta-instruction | No |
+| System prompt injection | Yes — `<EXTREMELY_IMPORTANT>` tags | No |
+| Available skills list | Yes — all skills listed with descriptions | No — auto-skills not listed* |
+| Meta-instruction forcing skill checks | Yes — "ABSOLUTELY MUST" language | No — relies on Superpowers being installed |
+| Trigger specification | Description field | Description field (same format) |
+
+*Auto-skills are discoverable via the Skill tool filesystem scan but do **not** appear in the "available skills" system reminder that Claude sees every turn. This is the critical gap.
+
+### Practical Impact
+
+- If Superpowers is installed: auto-skills **may** fire because Superpowers forces Claude to check for skills. But Claude still has to discover them via filesystem scan rather than seeing them in the skills list.
+- If Superpowers is NOT installed: auto-skills have **no mechanism** prompting Claude to check for them. They exist on disk but Claude has no reason to look.
+- Auto-skills are **invisible** in the available skills reminder, so even an instruction-following Claude won't pattern-match against them unless something else prompts a skill check.
+
+## Recommendations
+
+### Immediate: Add Auto-Skills to Main SKILL.md (Option B) ✅ Done
+
+Add a section to the main `skill/SKILL.md` that lists all auto-skills with their trigger conditions. Since the main sidecar skill already appears in the available skills list, Claude will see the auto-skill triggers when reading the main skill.
+
+**Pros:** Simple one-file change, no new infrastructure needed, works today.
+**Cons:** Relies on Claude reading the full main skill (which it does when sidecar is relevant, but not every turn). Only provides awareness when sidecar context is active.
+
+### Short-Term: SessionStart Hook (Option A)
+
+Register a lightweight SessionStart hook in sidecar's postinstall that injects a brief auto-skills reminder into the system prompt. This would mirror what Superpowers does but scoped to sidecar triggers.
+
+**Implementation:**
+1. Create `hooks/hooks.json` with SessionStart matcher
+2. Create a hook script that injects a compact reminder:
+   ```text
+   Sidecar auto-skills are available. Check trigger conditions:
+   - auto-review: after implementing changes, before telling user "done"
+   - auto-unblock: after 5+ failed fix attempts
+   - auto-security: before git commit/push/PR
+   - auto-bmad-method-check: after writing BMAD artifacts in _bmad-output/
+   Read the full skill from ~/.claude/skills/sidecar/<name>/SKILL.md when triggered.
+   ```
+3. Register the hook during postinstall alongside MCP and skill file installation
+
+**Pros:** Matches Superpowers' proven pattern. Always present from session start. Works independent of Superpowers.
+**Cons:** Requires hook infrastructure (hooks.json, hook script, postinstall changes). Adds to system prompt size every session.
+
+**Open question:** Does the Claude Code hooks API support `experimental.chat.system.transform` for third-party packages, or is this restricted to plugins? If restricted, the hook could use the simpler `command` type to emit the reminder, though this is less reliable than system prompt injection.
+
+### Medium-Term: Make Auto-Skills Appear in Skills List (Option D)
+
+Give auto-skills optional slash-command names (e.g., `/auto-review`, `/auto-security`) so they appear in the available skills system reminder. Keep the auto-fire behavior — the slash command would just be an alternative manual trigger.
+
+**Pros:** Skills appear in the list Claude checks every turn. Belt and suspenders with auto-fire.
+**Cons:** May confuse users who see skills they didn't know about. Pollutes the skills namespace. May not be possible without changes to how Claude Code lists skills.
+
+### Long-Term: Auto-Skills Framework in Sidecar Config
+
+If sidecar adds an `autoSkills` config namespace, centralize trigger definitions and enable/disable switches:
+
+```json
+{
+  "autoSkills": {
+    "review": { "enabled": true, "model": "gemini" },
+    "unblock": { "enabled": true, "attemptThreshold": 5 },
+    "security": { "enabled": true, "scanOnCommit": true },
+    "bmadMethodCheck": { "enabled": true, "artifactDir": "_bmad-output/" }
+  }
+}
+```
+
+This would let users customize which auto-skills fire and with what defaults, without editing SKILL.md files.
+
+## Summary
+
+| Approach | Effort | Reliability | Independence from Superpowers |
+|----------|--------|-------------|-------------------------------|
+| **B: Main SKILL.md section** (done) | Low | Medium — works when sidecar context is active | Partial — still benefits from Superpowers |
+| **A: SessionStart hook** | Medium | High — always present from session start | Full — self-contained |
+| **D: Skills list appearance** | Low-Medium | High — Claude checks every turn | Full |
+| **Config framework** | High | High — user-configurable | Full |
+
+**Recommended path:** B (done) → A (next PR) → Config framework (when sidecar adds autoSkills namespace).
diff --git a/docs/bmad-workflow.md b/docs/bmad-workflow.md
@@ -0,0 +1,111 @@
+# 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
+```
diff --git a/scripts/postinstall.js b/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/sidecar/ */
 function installSkill() {
   try {
     fs.mkdirSync(SKILL_DEST_DIR, { recursive: true });
@@ -59,6 +71,18 @@ function installSkill() {
   } catch (err) {
     console.error(`[claude-sidecar] Warning: Could not install skill: ${err.message}`);
   }
+
+  for (const name of AUTO_SKILLS) {
+    try {
+      const src = path.join(SKILL_DIR, name, 'SKILL.md');
+      const destDir = path.join(SKILL_DEST_DIR, name);
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(src, path.join(destDir, 'SKILL.md'));
+      console.log(`[claude-sidecar] Skill installed: ${name}`);
+    } catch (err) {
+      console.error(`[claude-sidecar] Warning: Could not install ${name} skill: ${err.message}`);
+    }
+  }
 }
 
 /** Register MCP server in Claude Code config */

diff --git a/skill/SKILL.md b/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, read the full skill 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`