From 5b98935a19c45126a5bc23392017cef6c54d5861 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 01:30:55 -0500 Subject: [PATCH 01/13] =?UTF-8?q?feat:=20add=20auto-review=20skill=20?= =?UTF-8?q?=E2=80=94=20post-implementation=20sidecar=20code=20review?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a skill that triggers after completing a feature/fix, offering to spawn a headless sidecar (Plan mode, read-only) to review changes for bugs, missed edge cases, and quality issues before claiming done. Key design decisions: - Dynamic model discovery via sidecar_guide (not hardcoded aliases) - Timeout omitted — uses sidecar platform default (15 min) - Polling cadence follows sidecar_status responses - Explicit terminal states: complete, timeout, crashed, error, aborted - Always unions staged + unstaged diffs before empty check - includeContext controls conversation history, not file access - Proof of failure required for each finding (reduces false positives) - git diff --stat for large diffs; Plan agent has read_file access - Briefing includes validation context and hardcoded-value checks - Dependency impact flagging for manifest/lockfile changes - Non-blocking: review runs in background while user gets completion msg Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 +- skill/auto-review/SKILL.md | 148 +++++++++++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 skill/auto-review/SKILL.md diff --git a/CLAUDE.md b/CLAUDE.md index 39a8918..f88293d 100644 --- 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/skill/auto-review/SKILL.md b/skill/auto-review/SKILL.md new file mode 100644 index 0000000..add9ab1 --- /dev/null +++ b/skill/auto-review/SKILL.md @@ -0,0 +1,148 @@ +--- +name: auto-review +description: > + Use after completing a feature implementation, bug fix, or significant code change — before + claiming the work is done. Offers to spawn a sidecar with a different model to review the + changes for bugs, missed edge cases, and quality issues. TRIGGER when: you have finished + implementing changes, tests pass (or no tests to run), and you are about to tell the user + "done" or summarize the completed work. Do NOT trigger for trivial one-line changes, config + edits, or documentation-only changes. +--- + +# Auto-Review: Post-Implementation Sidecar Review + +## Purpose + +Before claiming work is complete, offer to spawn a headless sidecar to get a second opinion on the changes from a different model. This catches bugs, missed edge cases, and quality issues that you may have overlooked. + +## When This Skill Fires + +- You have finished implementing a feature, bug fix, or significant refactor +- Tests pass (or there are no relevant tests) +- You are about to tell the user the work is done + +**Skip this skill when:** +- Changes are trivial (single-line fix, config change, docs-only) +- You are in the middle of iterating and not yet done +- A sidecar review is already running or was just completed for these changes +- An auto-security sidecar is about to run for the same changes (avoid duplicate scans) +- The `mcp__sidecar__sidecar_start` tool is not available in this environment (sidecar not installed) +- The diff is empty (all changes already committed, nothing to review) + +## Procedure + +### Step 1: Discover available models and prompt the user + +Before presenting the prompt, call `mcp__sidecar__sidecar_guide` to get the configured model alias table. Extract the alias names (e.g., `gemini`, `gpt`, `opus`) from the guide output. If the guide call fails, fall back to: "your configured models (run `sidecar setup` to see them)". + +Then present this confirmation prompt: + +```text +Sidecar code review? + + 1. Yes → send to: [default model] + (or specify models: e.g. "1 gemini gpt" for multi-model review) + 2. No → skip + +Available models: +Full provider/model IDs also accepted (e.g., google/gemini-3.1-flash). +``` + +Wait for the user's response: +- **"1"** or **"yes"**: Proceed with the user's configured default model +- **"1 gemini"** or **"1 gpt opus"**: Proceed with the specified model(s). If multiple models given, spawn one sidecar per model (all headless, in parallel). +- **"2"** or **"no"** or **"skip"**: Skip this skill entirely. Deliver your completion message and stop. +- Any other bypass phrase ("skip sidecar", "no sidecars", "we're good", etc.): Skip. + +**Do not proceed past this step without the user's explicit choice.** + +### Step 2: Capture the diff + +Run both `git diff` (unstaged changes) and `git diff --cached` (staged changes). Combine them into a single diff block before checking whether the review diff is empty. + +**If the combined diff is empty**, tell the user there is nothing to review and skip. + +**If the diff exceeds ~500 lines**, do not paste the raw diff. Instead: +- Run `git diff --stat` and include the output — this gives the reviewer a compact map of the blast radius (which files changed and by how much) before it dives into specifics +- Set `includeContext: true` in the sidecar call to pass conversation context (what was implemented and why) +- Provide a summary of what changed in each file +- The sidecar in Plan mode has full `read_file` access to the repository, so this is sufficient + +**If the diff is under ~500 lines**, paste it directly into the briefing. + +### Step 3: Spawn the sidecar(s) + +For **each model** the user selected, call `mcp__sidecar__sidecar_start` with: + +```text +model: +agent: "Plan" +noUi: true +includeContext: false +prompt: +``` + +Notes on parameters: +- **model**: Use the model(s) the user selected in Step 1. If they just said "1" with no model specified, omit this parameter to use their configured default. +- **agent: "Plan"** — read-only and headless-safe. Do not change to Chat (stalls in headless mode). +- **timeout**: Omitted — sidecar uses its platform default (currently 15 minutes). Only override if the user requests a specific timeout. +- **includeContext: false** — briefing is self-contained. Override to `true` for large diffs (see Step 2) to pass conversation context about what was implemented. Note: the Plan agent always has `read_file` access to the repository regardless of this flag — `includeContext` controls conversation context, not file access. + +If spawning multiple sidecars, launch them all in parallel. Save each task ID. + +**Briefing template** — fill in the placeholders: + +```text +## Code Review Request + +**Objective:** Review these code changes for bugs, logic errors, missed edge cases, and code quality issues. + +**Changes:** + + +**Context:** These changes were made to . + +**Validation performed:** + + +**Focus on:** +- Logic errors and off-by-one mistakes +- Missing error handling at trust boundaries +- Edge cases not covered +- Security concerns (injection, auth bypass, data exposure) +- Race conditions or concurrency issues +- Test adequacy: are new/modified tests happy-path only, or do they exercise edge cases and error paths? +- Hardcoded values that should be configurable, dynamic, or derived (magic numbers, hardcoded lists, environment-specific paths) +- Dependency changes: if package.json, Cargo.toml, requirements.txt, or similar manifests are in the diff, check for unnecessary new dependencies, version conflicts, or overly broad version ranges +- Anything that looks wrong or fragile + +**Do NOT flag:** Style preferences, naming opinions, minor nits, or suggestions for additional features. Only report issues you're confident about. + +**Output format:** If issues found, list each with: severity (critical/high/medium), file and location, description, proof of failure (a concrete scenario — e.g., "if input X is null, line Y will throw TypeError" — that demonstrates how the bug manifests; if you cannot construct one, downgrade or drop the finding), and suggested fix. If no issues found, say "No issues identified." +``` + +### Step 4: Continue with your completion message + +Do NOT block on the sidecar. Tell the user the work is done and mention the review is running: + +> "I've completed the implementation. Sidecar review running — I'll share findings when it completes." + +### Step 5: When the sidecar(s) complete + +Poll each sidecar's status using `mcp__sidecar__sidecar_status` with the saved task ID, following the polling cadence indicated by `sidecar_status` responses. Continue polling while status is `running`; treat `complete`, `timeout`, `crashed`, `error`, and `aborted` as terminal. Once terminal, read the output using `mcp__sidecar__sidecar_read`. If multiple models were used, label each result (e.g., "Gemini review:", "GPT review:"). Then: + +- **If substantive issues found:** Surface them as "Second opinion from review sidecar:" and offer to fix. +- **If no issues:** Briefly note: "Sidecar review came back clean — no issues found." +- **If the sidecar failed/timed out:** Mention it briefly and move on. Don't retry. +- **If `mcp__sidecar__sidecar_read` fails:** The sidecar may not be installed or configured. Mention once and move on. + +## Future: Configurable Settings + +The following settings are currently hardcoded in this skill. If sidecar adds an `autoSkills` config namespace, they could be moved to `autoSkills.review.*` in `~/.config/sidecar/config.json`: + +| Setting | Current Default | Description | +|---------|----------------|-------------| +| `autoSkills.review.largeDiffThreshold` | 500 lines | Line count above which diff is summarized instead of pasted | +| `autoSkills.review.maxBriefingChars` | 100,000 | Upper bound on briefing prompt size | +| `autoSkills.review.agent` | Plan | Agent mode for review sidecar (Plan vs Build) | +| `autoSkills.review.timeout` | 15 min | Max time for sidecar to complete review (currently hardcoded in sidecar platform) | From 6c385fa84862ff442aac2e8c143d3b64a6e0d3c3 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 01:31:08 -0500 Subject: [PATCH 02/13] =?UTF-8?q?feat:=20add=20auto-unblock=20skill=20?= =?UTF-8?q?=E2=80=94=20sidecar=20brainstorming=20when=20stuck=20debugging?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a skill that triggers after 5+ failed distinct approaches, offering an iterative brainstorming loop with a sidecar. The sidecar suggests ideas, Claude evaluates them against codebase knowledge, and feeds back what won't work — prompting deeper suggestions. Key design decisions: - Uses repeated sidecar_start (not sidecar_continue) to stay in Plan mode (headless sidecar_continue forces Build mode per mcp-server.js:275) - Dynamic model discovery via sidecar_guide (not hardcoded aliases) - Timeout omitted — uses sidecar platform default (15 min) - Polling cadence follows sidecar_status responses - Explicit terminal states: complete, timeout, crashed, error, aborted - Multi-model narrowing: all models round 1, best model only from round 2 - User check-in every 5 rounds to prevent theoretical spiraling - Rubber duck effect: abort sidecar if briefing prep solves the problem - Sidecar designs diagnostic probes, not just suggestions - Broadened context requests (dir listings, env vars, dep trees) - Token management guidance in follow-up briefings - Per-model task ID tracking for multi-model brainstorms - Max 20 iterations with clear termination conditions Co-Authored-By: Claude Opus 4.6 --- skill/auto-unblock/SKILL.md | 233 ++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 skill/auto-unblock/SKILL.md diff --git a/skill/auto-unblock/SKILL.md b/skill/auto-unblock/SKILL.md new file mode 100644 index 0000000..dd8d59a --- /dev/null +++ b/skill/auto-unblock/SKILL.md @@ -0,0 +1,233 @@ +--- +name: auto-unblock +description: > + Use when you have attempted 5 or more different approaches to fix a bug, pass a test, or + solve a problem and none have worked. Offers to spawn a sidecar brainstorming session with + a different model to get fresh debugging suggestions via an iterative "have you considered + trying..." loop. TRIGGER when: you are stuck in a debugging loop, have tried multiple fixes + that all failed, and are running out of ideas. Complements superpowers:systematic-debugging + — fires when systematic debugging has been exhausted. A "distinct approach" means a + meaningfully different strategy, not a minor variation (e.g., changing a type annotation + is not a distinct approach from the previous attempt). The attempt threshold (default: 5) + and max brainstorming iterations (default: 20) are configurable. +--- + +# Auto-Unblock: Escape Debugging Ruts with a Sidecar + +## Purpose + +When you're stuck — multiple approaches tried, all failing — offer to spawn a sidecar brainstorming session with a different model. Rather than trying to pass the full codebase (which rarely works well), this skill uses an iterative Q&A loop: the sidecar suggests ideas, Claude evaluates them against what it knows, and feeds back which ones won't work and why — prompting the sidecar to dig deeper. + +## Configuration + +| Setting | Default | Description | +|---------|---------|-------------| +| `attempt_threshold` | **5** | Number of distinct failed approaches before this skill offers to fire | +| `max_iterations` | **20** | Maximum brainstorming round-trips before stopping the loop | + +## When This Skill Fires + +- You have tried **5 or more meaningfully distinct approaches** to fix a bug or pass a test +- Each approach has failed (not just minor variations like tweaking a value) +- You recognize you are going in circles or running out of ideas + +**Skip this skill when:** +- You've only tried 4 or fewer approaches (keep debugging first) +- The failure is a simple typo or config issue you just spotted +- A sidecar is already running for this problem +- The `mcp__sidecar__sidecar_start` tool is not available in this environment (sidecar not installed) + +## Procedure + +### Step 1: Discover available models and prompt the user + +Before presenting the prompt, call `mcp__sidecar__sidecar_guide` to get the configured model alias table. Extract the alias names (e.g., `gemini`, `gpt`, `opus`) from the guide output. If the guide call fails, fall back to: "your configured models (run `sidecar setup` to see them)". + +Acknowledge you're stuck, then present the confirmation prompt: + +```text +I've tried [N] approaches and none have resolved this. + +Sidecar brainstorming session? + + 1. Yes → brainstorm with: [default model] + (or specify models: e.g. "1 gemini gpt" for multi-model brainstorm) + 2. No → skip (I'll keep debugging) + +The sidecar will suggest ideas in an iterative loop. I'll evaluate +each suggestion and feed back why it won't work, prompting deeper +ideas — up to 20 rounds. + +Available models: +Full provider/model IDs also accepted (e.g., google/gemini-3.1-flash). +``` + +Wait for the user's response: +- **"1"** or **"yes"**: Proceed with the user's configured default model +- **"1 gemini"** or **"1 gpt opus"**: Proceed with the specified model(s). If multiple models given, spawn one sidecar per model (all headless, in parallel). +- **"2"** or **"no"** or **"skip"**: Skip this skill. Continue debugging or ask the user for direction. +- Any other bypass phrase ("skip sidecar", "no sidecars", "I'll handle it", etc.): Skip. + +**Do not proceed past this step without the user's explicit choice.** + +### Step 2: Gather context for the initial briefing + +Collect: +- **The problem:** Error messages, failing test output, symptoms +- **Approaches tried:** Be concrete — reference actual commands you ran, files you edited, and the exact error output each attempt produced. Do not paraphrase from memory; review your tool history (shell commands, file edits) to provide accurate evidence of what was tried and what happened. +- **Relevant code:** Key file paths and brief descriptions (the sidecar may have limited local context — describe the relevant architecture concisely rather than assuming it can explore the codebase) +- **Your hypothesis:** What you suspect but haven't confirmed +- **Constraints:** Anything the sidecar should know (e.g., "this is a legacy system, can't upgrade dependencies") + +**Rubber duck effect:** The discipline of gathering and organizing this context often surfaces the answer. If you solve the problem while writing the briefing, skip the sidecar spawn — tell the user what clicked and proceed with the fix. + +**Truncation guidance:** If error output exceeds ~50 lines, include only the first and last 20 lines plus the core error message, and note that output was truncated. Keep the total briefing under ~100,000 characters. + +### Step 3: Spawn the sidecar(s) — initial brainstorm + +For **each model** the user selected, call `mcp__sidecar__sidecar_start` with: + +```text +model: +agent: "Plan" +noUi: true +includeContext: true +prompt: +``` + +Notes on parameters: +- **model**: Use the model(s) the user selected in Step 1. If they just said "1" with no model specified, omit this parameter to use their configured default. +- **agent: "Plan"** — headless-safe, read-only. The sidecar's role is to brainstorm, not to execute. +- **timeout**: Omitted — sidecar uses its platform default (currently 15 minutes). Only override if the user requests a specific timeout. +- **includeContext: true** — passes the parent conversation history to the sidecar, giving it visibility into prior debugging attempts, error output, and tool results. Note: `includeContext` controls conversation context, not file access — the Plan agent always has `read_file` access regardless. + +If spawning multiple sidecars, launch them all in parallel. Save each task ID per model. In subsequent rounds, track each model's task ID independently — each `sidecar_start` returns a new task ID. + +**Initial briefing template** — fill in the placeholders: + +```text +## Debugging Brainstorm — Fresh Ideas Needed + +I'm stuck on a bug and need your help brainstorming. I'll describe the situation and you suggest ideas. I'll tell you which ones won't work and why, and you can refine. You may have limited codebase context, so I'll provide relevant details below. + +**Problem:** + +**Tech stack / architecture:** + +**Approaches already tried** (be specific — include actual commands, edits, and error output): +1. : — Result: +2. : — Result: + + +**Error output:** + + +**Key files involved:** + + +**What I suspect but haven't confirmed:** + + +**Constraints:** + + +**What I need from you:** +1. **Challenge my assumptions.** What am I taking for granted that might be wrong? (e.g., "You assume this library is thread-safe — is it?" or "You assume the config is loaded before this runs — verify that.") List 2-3 hidden assumptions worth testing. +2. **Suggest 3-5 concrete debugging approaches** I haven't tried. For each, explain the reasoning and what it would confirm or rule out. Think laterally — the obvious approaches have failed. +3. **Design a diagnostic probe.** For your most promising suggestion, describe a minimal experiment to isolate the failure — e.g., a specific print/log statement to add, a value to hardcode temporarily, or a minimal reproduction case. Tell me exactly what to do and what the result would confirm or rule out. +4. **Ask me for specifics.** If you need to see a particular code snippet, config file, log output, directory listing, environment variables, or dependency tree to give better suggestions, tell me exactly what to provide in the next round. +``` + +Tell the user: + +> "Sidecar brainstorming session started with [model name(s)]. I'll share the first round of suggestions when it responds." + +### Step 4: Iterative brainstorming loop + +Poll each sidecar's status using `mcp__sidecar__sidecar_status` with the saved task ID, following the polling cadence indicated by `sidecar_status` responses. Continue polling while status is `running`; treat `complete`, `timeout`, `crashed`, `error`, and `aborted` as terminal. Once terminal, read the output using `mcp__sidecar__sidecar_read`. + +**For each suggestion the sidecar returns:** + +1. **Evaluate it** against your knowledge of the codebase and prior attempts +2. **If promising:** Present it to the user and try it. If it works, stop the loop. If it fails, continue to step 3. +3. **If already tried or clearly won't work:** Note why in a follow-up briefing +4. **If the sidecar requests code snippets or files:** Provide them in the next follow-up briefing. The sidecar may have limited codebase context — fulfilling its requests for specific code, config, or logs helps it give better-targeted suggestions. +5. **If needs more info:** Note what info would help + +**User check-in (every 5 rounds):** At rounds 5, 10, and 15, pause the loop and check in with the user before continuing. Briefly summarize what's been tried, what's been learned, and ask whether to continue, redirect, or stop. This prevents the two agents from spiraling into theoretical territory without human course correction. + +**Multi-model narrowing:** If the user selected multiple models, run all of them for round 1. From round 2 onward, continue with only the model that produced the most useful suggestions — this avoids combinatorial fan-out (N models × 20 rounds). Mention which model you're continuing with and why. + +**After evaluating all suggestions from a round**, if none solved the problem and you haven't hit the max iterations (20) and it's not a check-in round, spawn a fresh sidecar using `mcp__sidecar__sidecar_start` (not `sidecar_continue`): + +```text +model: +agent: "Plan" +noUi: true +includeContext: true +prompt: +``` + +**Why `sidecar_start` instead of `sidecar_continue`:** In the current sidecar implementation, headless `sidecar_continue` forces Build mode (full write access), which is inappropriate for a brainstorming-only workflow. Using fresh `sidecar_start` with `agent: "Plan"` keeps each round read-only. The follow-up briefing includes full context from prior rounds, so conversation continuity is preserved in the prompt itself. Save the new task ID returned by each round for status polling. + +After spawning, poll status using `mcp__sidecar__sidecar_status` (following the polling cadence indicated by `sidecar_status` responses) while `running`; treat `complete`, `timeout`, `crashed`, `error`, and `aborted` as terminal. Once terminal, read with `mcp__sidecar__sidecar_read`. + +**Follow-up briefing template:** + +```text +## Round [N] — Here's what happened + +**Suggestions that didn't work:** +- : Tried it — +- : Can't work because +- : Already tried in approach #3 (see above) + +**Code/config you requested:** + + +**New information uncovered:** + + +**What's still unexplained:** + + +**Important:** Be concise in your reasoning — focus on actionable suggestions rather than lengthy analysis. Long responses risk hitting output token limits. + +Please suggest 3-5 more approaches, avoiding the ones above. Go deeper — consider less obvious causes like: +- Environment/config issues +- Race conditions or timing +- Upstream dependencies behaving differently than expected +- Incorrect assumptions about how a library/framework works +- Data-related issues (encoding, format, edge cases) +``` + +**Loop termination conditions** (stop and report to user): +- A suggestion works (problem solved) +- The user says to stop (including during a check-in) +- Max iterations reached (default: 20) +- The sidecar starts repeating suggestions already tried +- The sidecar gives up or says it's out of ideas + +### Step 5: Report results + +After the loop ends, summarize for the user: + +- **If solved:** Report what worked and which round/suggestion cracked it. +- **If max iterations reached:** Summarize the most promising unexplored angles and ask the user for guidance. +- **If sidecar ran out of ideas:** Acknowledge it, list any partially-promising leads, and ask the user what to try next. +- **If the sidecar failed/timed out:** Mention it briefly and continue debugging or ask the user. +- **If `mcp__sidecar__sidecar_read` fails:** Sidecar may not be installed. Mention once and continue. + +## Future: Configurable Settings + +The following settings are currently hardcoded in this skill. If sidecar adds an `autoSkills` config namespace, they could be moved to `autoSkills.unblock.*` in `~/.config/sidecar/config.json`: + +| Setting | Current Default | Description | +|---------|----------------|-------------| +| `autoSkills.unblock.attemptThreshold` | 5 | Failed approaches before skill offers to fire | +| `autoSkills.unblock.maxIterations` | 20 | Maximum brainstorming round-trips | +| `autoSkills.unblock.userCheckinInterval` | 5 | Rounds between mandatory user check-ins | +| `autoSkills.unblock.suggestionsPerRound` | 3-5 | Number of suggestions requested per round | +| `autoSkills.unblock.maxBriefingChars` | 100,000 | Upper bound on briefing prompt size | +| `autoSkills.unblock.errorTruncationLines` | 50 | Max lines of error output in briefing | +| `autoSkills.unblock.timeout` | 15 min | Max time per sidecar round (currently hardcoded in sidecar platform) | From 9043a0dd924bc0b60a6d90e842badd8902f20ba1 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 01:31:18 -0500 Subject: [PATCH 03/13] =?UTF-8?q?feat:=20add=20auto-security=20skill=20?= =?UTF-8?q?=E2=80=94=20pre-commit=20sidecar=20security=20scan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a skill that triggers when user asks to commit/push/PR, offering a headless sidecar security audit before changes enter the repository. Sequential (blocks commit) to catch critical vulnerabilities first. Key design decisions: - Dynamic base branch resolution with full fallback chain (origin/HEAD -> @{upstream} -> main -> master -> ask user) - Audits union of staged + unstaged for commits; full branch diff for PRs - Dynamic model discovery via sidecar_guide (not hardcoded aliases) - Timeout omitted — uses sidecar platform default (15 min) - Polling cadence follows sidecar_status responses - Explicit terminal states: complete, timeout, crashed, error, aborted - Attack vector required for each finding (reduces false positives) - CI/CD files (.github/workflows/, etc.) in high-priority list - Suspicious dependency detection (typosquatting, unmaintained packages) - Security-relevant file prioritization for large diffs - Critical/high findings block commit; medium findings are user's choice - Does not fire on slash commands (/commit) — isolated context Co-Authored-By: Claude Opus 4.6 --- skill/auto-security/SKILL.md | 152 +++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 skill/auto-security/SKILL.md diff --git a/skill/auto-security/SKILL.md b/skill/auto-security/SKILL.md new file mode 100644 index 0000000..ce9c181 --- /dev/null +++ b/skill/auto-security/SKILL.md @@ -0,0 +1,152 @@ +--- +name: auto-security +description: > + Use when the user asks to commit changes, push code, or create a pull request. Offers to + spawn a sidecar to audit the diff for security vulnerabilities before the commit/push/PR + proceeds. TRIGGER when: user says "commit", "push", "create a PR", "open a PR", or you are + about to run git commit, git push, or gh pr create in conversational flow. Does NOT trigger + on slash commands like /commit or /commit-push-pr (those execute in isolated contexts). + Complements commit-commands:commit — runs before the commit proceeds. +--- + +# Auto-Security: Pre-Commit Security Scan via Sidecar + +## Purpose + +Before committing, pushing, or creating a PR, offer to spawn a headless sidecar to audit the changes for security vulnerabilities. Catches issues like hardcoded secrets, injection flaws, and auth bypass before they reach the repository. + +## When This Skill Fires + +- The user asks to commit, push, or create a PR in conversation (e.g., "commit my changes", "let's push this", "create a PR") +- You are about to run `git commit`, `git push`, or `gh pr create` in normal conversational flow + +**This skill does NOT fire on:** +- Slash commands (`/commit`, `/commit-push-pr`) — those execute in their own isolated context and cannot be intercepted by skills + +**Skip this skill when:** +- Changes contain zero executable code (only `*.md` files, only code comments, only whitespace) +- Changes are trivially safe (bumping a version number in `package.json` with no other changes) +- A security sidecar already ran for these exact changes +- An auto-review sidecar already ran for these same changes (its briefing covers security concerns) +- The `mcp__sidecar__sidecar_start` tool is not available in this environment (sidecar not installed) +- The diff is empty (nothing staged or unstaged to commit) + +## Procedure + +### Step 1: Discover available models and prompt the user + +Before presenting the prompt, call `mcp__sidecar__sidecar_guide` to get the configured model alias table. Extract the alias names (e.g., `gemini`, `gpt`, `opus`) from the guide output. If the guide call fails, fall back to: "your configured models (run `sidecar setup` to see them)". + +Then present this confirmation prompt: + +```text +Sidecar security scan before commit? + + 1. Yes → send to: [default model] + (or specify models: e.g. "1 gemini gpt" for multi-model audit) + 2. No → skip, proceed with commit + +Available models: +Full provider/model IDs also accepted (e.g., google/gemini-3.1-flash). +``` + +Wait for the user's response: +- **"1"** or **"yes"**: Proceed with the security scan before committing +- **"1 gemini"** or **"1 gpt opus"**: Proceed with the specified model(s). If multiple models given, spawn one sidecar per model (all headless, in parallel). +- **"2"** or **"no"** or **"skip"**: Skip the scan and proceed directly with the commit/push/PR. +- Any other bypass phrase ("skip sidecar", "no sidecars", "just commit", "no scan", "commit without review", etc.): Skip. + +**Do not proceed past this step without the user's explicit choice.** If the user chooses to skip, go straight to the commit flow. + +### Step 2: Capture the diff + +Choose the right diff for the operation: +- **For commits:** Run both `git diff` (unstaged) and `git diff --cached` (staged). Combine them into a single diff for the audit — this audits all changes, not just staged ones, to avoid silently missing unstaged code. Note: this is intentionally broader than strict Git staging semantics; if the user wants to audit only staged changes, they can say so. +- **For PRs/pushes:** Resolve the base branch using this fallback order: (1) `git symbolic-ref refs/remotes/origin/HEAD` to get the remote's default branch, (2) `@{upstream}` if no `origin` remote exists, (3) check if `main` or `master` branches exist locally, (4) ask the user. Then run `git diff $(git merge-base HEAD )...HEAD` to capture the full branch diff, not just the current working tree. This catches security issues from earlier commits on the branch. + +**If the diff is empty**, tell the user there are no changes to audit and skip to the commit flow. For commits, this means both staged and unstaged diffs are empty. For PRs/pushes, this means the branch diff against the default branch is empty (no commits to push). + +**If the diff exceeds ~500 lines**, prioritize files by security relevance rather than truncating arbitrarily. Include in full: files handling authentication/authorization, user input processing, API route definitions, database queries, cryptographic operations, CI/CD configuration (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, etc.), and any files containing secrets-adjacent patterns (environment config, credential setup). Deprioritize: tests, documentation, static assets, generated code. Truncate to ~100,000 characters max. For very large diffs, provide file paths and change summaries instead of raw diff — the Plan agent has `read_file` access and can read the source files directly. + +### Step 3: Spawn the sidecar(s) — BEFORE starting the commit + +**Important: Run the security scan FIRST, before executing the commit.** Do not start the commit in parallel. Wait for the scan to complete (or timeout) before proceeding. This ensures critical vulnerabilities are caught before they enter the repository. + +For **each model** the user selected, call `mcp__sidecar__sidecar_start` with: + +```text +model: +agent: "Plan" +noUi: true +includeContext: true +prompt: +``` + +Notes on parameters: +- **model**: Use the model(s) the user selected in Step 1. If they just said "1" with no model specified, omit this parameter to use their configured default. +- **agent: "Plan"** — read-only and headless-safe. Do not change to Chat (stalls in headless mode). +- **timeout**: Omitted — sidecar uses its platform default (currently 15 minutes). Only override if the user requests a specific timeout. +- **includeContext: true** — passes the parent conversation history to the sidecar, giving it visibility into prior discussion, error output, and what was implemented. Note: the Plan agent always has `read_file` access to the repository regardless of this flag — `includeContext` controls conversation context, not file access. + +If spawning multiple sidecars, launch them all in parallel. Save each task ID. + +Tell the user: + +> "Running security scan with [model name(s)]. This usually takes a minute or two." + +**Briefing template** — fill in the placeholders: + +```text +## Security Audit — Pre-Commit Review + +**Objective:** Audit these code changes for security vulnerabilities. + +**Changes:** + + +**Check for:** +- Injection vulnerabilities (SQL, command, XSS, template injection) +- Authentication/authorization bypass +- Hardcoded secrets, API keys, tokens, or credentials +- Insecure data handling (PII exposure, missing encryption, logging sensitive data) +- OWASP Top 10 issues +- Unsafe deserialization +- Path traversal +- Missing input validation at trust boundaries +- Insecure cryptographic practices +- SSRF, open redirects +- CI/CD pipeline tampering (modified workflow files, build scripts, or deployment configs) +- New dependencies that look suspicious (typosquatting, unnecessary permissions, unmaintained packages) + +**Output format:** List only confirmed or high-confidence issues. For each: +- **Severity:** critical / high / medium +- **File and line:** where the issue is +- **Description:** what's wrong +- **Attack vector:** how an attacker would exploit this (be specific — describe the input, the path through the code, and the impact). If you cannot articulate a concrete attack vector, downgrade or drop the finding. +- **Suggested fix:** how to resolve it + +If no security issues found, say: "No security issues identified." +``` + +### Step 4: Poll for completion, then proceed + +After spawning, poll each sidecar's status using `mcp__sidecar__sidecar_status` with the saved task ID, following the polling cadence indicated by `sidecar_status` responses. Continue polling while status is `running`; treat `complete`, `timeout`, `crashed`, `error`, and `aborted` as terminal. Only then read the output using `mcp__sidecar__sidecar_read`. If multiple models were used, label each result (e.g., "Gemini audit:", "GPT audit:"). Then: + +- **If critical/high severity issues found:** **Do not proceed with the commit.** Surface the findings: "Security scan found issues that should be addressed before committing:" — then list them and offer to fix. +- **If medium severity issues found:** Surface them as warnings and let the user decide: "Security scan flagged some medium-severity items. Want to address these before committing, or proceed?" +- **If no issues:** Proceed with the commit normally. Briefly note: "Security scan came back clean." +- **If the sidecar timed out:** Tell the user the scan timed out and ask if they want to proceed anyway or wait for a retry. +- **If `mcp__sidecar__sidecar_read` fails:** Sidecar may not be installed. Mention once and proceed with the commit. + +After resolving the scan results, proceed with the normal commit/push/PR flow. + +## Future: Configurable Settings + +The following settings are currently hardcoded in this skill. If sidecar adds an `autoSkills` config namespace, they could be moved to `autoSkills.security.*` in `~/.config/sidecar/config.json`: + +| Setting | Current Default | Description | +|---------|----------------|-------------| +| `autoSkills.security.largeDiffThreshold` | 500 lines | Line count above which diff is summarized by security relevance | +| `autoSkills.security.maxBriefingChars` | 100,000 | Upper bound on briefing prompt size | +| `autoSkills.security.blockingMode` | sequential | Whether scan blocks commit (sequential) or runs in parallel | +| `autoSkills.security.timeout` | 15 min | Max time for sidecar to complete scan (currently hardcoded in sidecar platform) | From 34aba520cdc378b618ad3419e425e0f100bc2a37 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 01:31:27 -0500 Subject: [PATCH 04/13] fix: postinstall copies auto-skill subdirectories Updates postinstall.js to also install auto-review, auto-unblock, and auto-security skills to ~/.claude/skills/sidecar//SKILL.md alongside the main SKILL.md. Without this, npm install would not deploy the auto-skills to the user's skill directory. Co-Authored-By: Claude Opus 4.6 --- scripts/postinstall.js | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/scripts/postinstall.js b/scripts/postinstall.js index 2f6b7d4..5056649 100644 --- a/scripts/postinstall.js +++ b/scripts/postinstall.js @@ -13,10 +13,13 @@ 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'); +const AUTO_SKILLS = ['auto-review', 'auto-unblock', 'auto-security']; + const MCP_CONFIG = { command: 'npx', args: ['-y', 'claude-sidecar@latest', 'mcp'] }; /** @@ -50,7 +53,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 +62,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 */ From 020a28559d53ca55c2c596ddfb6cdea78bc46e0a Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 09:14:41 -0500 Subject: [PATCH 05/13] fix: derive AUTO_SKILLS dynamically from filesystem Instead of hardcoding the list of auto-skills, scan the skill/ directory for auto-* subdirectories at install time. This ensures new auto-skills are picked up without updating the script. Co-Authored-By: Claude Opus 4.6 --- scripts/postinstall.js | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/postinstall.js b/scripts/postinstall.js index 5056649..b9648eb 100644 --- a/scripts/postinstall.js +++ b/scripts/postinstall.js @@ -18,7 +18,11 @@ 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'); -const AUTO_SKILLS = ['auto-review', 'auto-unblock', 'auto-security']; +const AUTO_SKILLS = fs + .readdirSync(SKILL_DIR, { withFileTypes: true }) + .filter((entry) => entry.isDirectory() && entry.name.startsWith('auto-')) + .map((entry) => entry.name) + .sort(); const MCP_CONFIG = { command: 'npx', args: ['-y', 'claude-sidecar@latest', 'mcp'] }; From e4f257b03a30eec949c42c3982e252dd6e891310 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 10:19:46 -0500 Subject: [PATCH 06/13] =?UTF-8?q?feat:=20add=20auto-bmad-method-check=20sk?= =?UTF-8?q?ill=20=E2=80=94=20sidecar=20review=20of=20BMAD=20artifacts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new auto-skill that offers second-opinion sidecar reviews at natural BMAD-METHOD workflow checkpoints. Covers 9 artifact types (PRD, architecture, epics, stories, etc.) with sequential multi-model review where each model sees improvements from prior rounds. Includes bmad-workflow.md reference doc. Co-Authored-By: Claude Opus 4.6 --- docs/bmad-workflow.md | 111 +++++++++++ skill/auto-bmad-method-check/SKILL.md | 276 ++++++++++++++++++++++++++ 2 files changed, 387 insertions(+) create mode 100644 docs/bmad-workflow.md create mode 100644 skill/auto-bmad-method-check/SKILL.md diff --git a/docs/bmad-workflow.md b/docs/bmad-workflow.md new file mode 100644 index 0000000..b303129 --- /dev/null +++ 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 + +``` +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 + +``` +_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/skill/auto-bmad-method-check/SKILL.md b/skill/auto-bmad-method-check/SKILL.md new file mode 100644 index 0000000..5eb3f7d --- /dev/null +++ b/skill/auto-bmad-method-check/SKILL.md @@ -0,0 +1,276 @@ +--- +name: auto-bmad-method-check +description: > + Use when a BMAD-METHOD workflow has just produced an output artifact (PRD, architecture doc, + epics, story file, etc.) and the user has not yet finalized it or moved to the next workflow + step. Offers to spawn sidecar(s) for a second-opinion review of the artifact along with its + input documents, then presents each model's suggestions sequentially for Claude to evaluate + and the user to approve. TRIGGER when: a BMAD planning or implementation artifact has just + been written or substantially updated in _bmad-output/, the artifact is substantive (not a + trivial edit), and the user is at a natural checkpoint before proceeding. Does NOT trigger + if _bmad/bmm/config.yaml is missing (BMAD-METHOD not installed), if the artifact is a minor + edit, or if a sidecar review already ran for this artifact version. +--- + +# Auto-BMAD-Method-Check: Artifact Review via Sidecar + +## Purpose + +When a BMAD-METHOD workflow produces a key artifact — PRD, architecture doc, epics, story file, or other checkpoint document — offer to send it to one or more sidecar models for a second opinion before the user finalizes and moves to the next workflow step. Claude evaluates each model's suggestions against the artifact and its input documents, presents an informed opinion, and the user decides what to apply. Multiple models are spawned and processed sequentially — each successive model reviews the artifact *after* changes from prior models have been applied, creating a genuine multi-model refinement pipeline. + +## Artifact Scope + +This skill covers planning and key implementation artifacts where a second opinion catches costly mistakes: + +| Artifact | Phase | Input Documents | +|---|---|---| +| `product-brief.md` | Analysis | `brainstorming-report.md`, `research-*.md` (if they exist) | +| `PRD.md` | Planning | `product-brief.md` (if exists) | +| `ux-design-specification.md` | Planning | `PRD.md` | +| `architecture.md` | Solutioning | `PRD.md`, `ux-design-specification.md` (if exists) | +| `epics.md` (or sharded `epics/` dir) | Solutioning | `PRD.md`, `architecture.md` | +| Implementation Readiness result | Solutioning | `PRD.md`, `architecture.md`, `epics.md`, `ux-design-specification.md` (if exists) | +| `story-*.md` | Implementation | `epics.md`, `PRD.md`, `architecture.md`, `sprint-status.yaml` | +| `sprint-change-proposal-*.md` | Implementation | `PRD.md`, `epics.md`, affected `story-*.md` files | +| `epic-*-retro-*.md` | Implementation | All `story-*.md` in that epic, previous retro (if exists) | + +## When This Skill Fires + +- A BMAD workflow has just written or substantially updated one of the artifacts above +- The user has not yet finalized the artifact or moved to the next workflow step +- The artifact represents a natural BMAD checkpoint where human review is expected + +**Skip this skill when:** +- `_bmad/bmm/config.yaml` does not exist in the project root (BMAD-METHOD not installed — this skill is designed specifically for the BMAD-METHOD framework at https://github.com/bmad-code-org/BMAD-METHOD) +- `_bmad-output/` directory does not exist (no artifact output location) +- The artifact change is trivial (typo fix, formatting, comment edit) +- A sidecar review already ran for this artifact version +- The user is in Quick Flow (`tech-spec.md`, `quick-dev`) — those have their own review cycle +- The `mcp__sidecar__sidecar_start` tool is not available in this environment (sidecar not installed) + +## Procedure + +### Step 0: Verify BMAD-METHOD installation + +Before anything else, check that the BMAD-METHOD is installed in the current project: + +1. Look for `_bmad/bmm/config.yaml` in the project root +2. Look for `_bmad-output/` directory + +If either is missing, do not fire this skill. Do not mention it to the user — silently skip. + +### Step 1: Discover available models and prompt the user + +Before presenting the prompt, call `mcp__sidecar__sidecar_guide` to get the configured model alias table. Extract the alias names (e.g., `gemini`, `gpt`, `opus`) from the guide output. If the guide call fails, fall back to: "your configured models (run `sidecar setup` to see them)". + +Identify the artifact that was just produced and present the confirmation prompt: + +```text +BMAD artifact review — [artifact name]? + +This [artifact type] is ready for second-opinion review before you finalize. + + 1. Yes → send to: [default model] + (or specify models: e.g. "1 gemini gpt" for multi-model sequential review) + 2. No → skip and finalize + +If multiple models selected, each reviews sequentially — later models +see improvements from earlier rounds. I'll evaluate each suggestion +and give my opinion before you decide. + +Available models: +Full provider/model IDs also accepted (e.g., google/gemini-3.1-flash). +``` + +Wait for the user's response: +- **"1"** or **"yes"**: Proceed with the user's configured default model +- **"1 gemini"** or **"1 gpt opus"**: Proceed with the specified model(s). If multiple models given, spawn and process them sequentially in the order specified — each model reviews the artifact after changes from prior models have been applied. +- **"2"** or **"no"** or **"skip"**: Skip this skill. Proceed with finalization. +- Any other bypass phrase ("skip sidecar", "no review", "finalize", etc.): Skip. + +**Do not proceed past this step without the user's explicit choice.** + +### Step 2: Gather context + +1. **Read the output artifact** in full. This is the primary document under review — never truncate it. + +2. **Resolve input documents.** Use this priority order: + - First, check if the artifact itself references its input documents (many BMAD artifacts cite their sources in headers, metadata, or "References" sections) + - If no references found, fall back to the Artifact Scope table above + - Scan `_bmad-output/planning-artifacts/` and `_bmad-output/implementation-artifacts/` for matching files + - For glob patterns (e.g., `research-*.md`, `story-*.md`), collect all matching files + +3. **Collect input document paths and descriptions.** For each input document, note its file path and a one-line description of what it contains (e.g., "`_bmad-output/planning-artifacts/PRD.md` — functional and non-functional requirements"). Do NOT read or paste their full content into the briefing — the sidecar has `read_file` access and will read them directly. This saves significant context in the parent session. + +4. **Truncation guidance:** The output artifact should always be included in full (it's what's being reviewed). If even the artifact alone exceeds ~80,000 characters, truncate to the most relevant sections and note what was omitted so the sidecar can use `read_file` for the rest. + +### Step 3: Spawn the first sidecar + +Spawn a sidecar for the **first** (or only) model the user selected. Call `mcp__sidecar__sidecar_start` with: + +```text +model: +agent: "Plan" +noUi: true +includeContext: true +prompt: +``` + +Notes on parameters: +- **model**: Use the first model the user selected. If they just said "1" with no model specified, omit this parameter to use their configured default. +- **agent: "Plan"** — read-only and headless-safe. The sidecar reviews but does not modify files. +- **timeout**: Omitted — sidecar uses its platform default (currently 15 minutes). Only override if the user requests a specific timeout. +- **includeContext: true** — passes the parent conversation history to the sidecar, giving it visibility into the workflow discussion that produced the artifact. The Plan agent also has `read_file` access to the repository for additional context. + +Save the task ID. If the user selected multiple models, subsequent models are spawned in Step 4e **after** the current model's approved changes have been applied to the artifact. This ensures each model reviews the improved version, not the original. + +**Briefing template** — fill in the placeholders: + +```text +## BMAD Artifact Review — [Artifact Type] + +**Objective:** Review this BMAD-METHOD artifact for completeness, internal consistency, +alignment with upstream documents, and quality. This artifact was produced by the +[workflow name] workflow and is at a checkpoint before the user finalizes it. + +**Artifact under review:** + + +**Input documents (upstream context) — read these with your file tools:** + +Use your read_file tool to examine these documents. They contain the upstream +decisions and requirements that this artifact must align with. + +**BMAD-METHOD context:** +This project uses the BMAD-METHOD framework (https://github.com/bmad-code-org/BMAD-METHOD). +The artifact above was produced by the [agent name] agent during the [phase name] phase. +The next workflow step will be [next step description]. + +**Review this artifact for:** + +1. **Completeness** — Are there gaps, missing sections, or requirements from the input + documents that aren't addressed? Are there implicit assumptions that should be explicit? + +2. **Internal consistency** — Does the artifact contradict itself? Are terms used + consistently? Do sections reference each other correctly? + +3. **Upstream alignment** — Does this artifact faithfully reflect decisions made in its + input documents? Flag any drift, contradiction, or silent omission of upstream + requirements. + +4. **Quality and clarity** — Is the writing clear and unambiguous? Would the next + agent/workflow in the BMAD pipeline be able to use this artifact effectively? + Are acceptance criteria testable? Are architecture decisions justified? + +5. **Risk and gaps** — What risks or edge cases does this artifact not address? + What questions should be resolved before moving to the next phase? + +**Do NOT flag:** Stylistic preferences, formatting opinions, or suggestions for +scope expansion beyond what the input documents require. + +**Output format:** For each finding: +- **Category:** completeness | consistency | alignment | quality | risk +- **Severity:** critical (blocks next phase) | important (should fix) | suggestion (nice to have) +- **Location:** section or line reference in the artifact +- **Finding:** what's wrong or missing +- **Evidence:** quote from input document or artifact that supports this finding +- **Suggested fix:** concrete recommendation + +If no issues found, say: "No issues identified — artifact is ready to finalize." +``` + +Tell the user: + +> "Sidecar review started with [model name(s)]. I'll present findings for each model as they complete." + +### Step 4: Sequential review loop + +Process models in the order the user specified them. For each model: + +**4a. Poll and read results** + +Poll the sidecar's status using `mcp__sidecar__sidecar_status` with the saved task ID, following the polling cadence indicated by `sidecar_status` responses. Continue polling while status is `running`; treat `complete`, `timeout`, `crashed`, `error`, and `aborted` as terminal. Once terminal, read the output using `mcp__sidecar__sidecar_read`. + +**4b. Claude evaluates each suggestion** + +For each finding the sidecar returned, evaluate it against: +- The artifact content — is the finding accurate? +- The input documents — does the suggestion align with upstream decisions? +- BMAD method conventions — does it follow the framework's patterns and expectations? +- Prior models' changes (if this is Model 2+) — does it conflict with already-applied changes? + +**4c. Present to user with Claude's opinion** + +Format the presentation as: + +```text +Review from [Model Name]: + +Finding 1: [summary] + Sidecar says: [the suggestion] + My assessment: [Agree / Disagree / Partially agree] — [reasoning] + Recommendation: [Apply / Skip / Modify to...] + +Finding 2: ... + ... + +Summary: [N] findings — I recommend applying [X], skipping [Y]. +Which changes would you like to apply? (all / none / list numbers, e.g. "1 3 5") +``` + +**4d. Apply approved changes** + +For each change the user approves: +- Update the artifact in place +- If a suggestion needs modification (user or Claude adjusted it), apply the modified version + +**4e. Spawn next model (if any)** + +If there are more models to process: +- Re-read the now-updated artifact (with all approved changes applied) +- Spawn the next model's sidecar using `mcp__sidecar__sidecar_start` with the same parameters as Step 3, but with the **updated artifact content** in the briefing +- This ensures the next model reviews the improved version, not the original +- Poll, read, and evaluate the next model's results the same way (repeat 4a–4d) +- When presenting: flag explicitly if this model raised something the previous model missed, or contradicts a change already applied + +### Step 5: Consolidation check + +After all models have been processed and changes applied: + +**If changes were minor (1-3 small edits):** Perform a quick internal coherence check yourself — re-read the updated artifact and verify the edits flow naturally. Report briefly: "Applied changes look coherent. Ready to finalize." + +**If changes were substantial (4+ edits, or structural changes across multiple sections):** Re-read the full updated artifact and check for: +- New contradictions or redundancies introduced by the edits +- Sections that no longer flow coherently after patching in changes +- Content that was inadvertently weakened or removed + +If you spot issues, fix them and note what you adjusted. If the artifact needs deeper review after heavy edits, offer a sidecar consolidation round: + +```text +This artifact had substantial edits from [N] reviews. Want a final +consolidation review with [model] to check coherence, or finalize as-is? +``` + +If the user wants a sidecar round, spawn one with the updated artifact only (no input documents) focused on internal consistency. Process results the same way: evaluate, present, user approves. + +### Step 6: Completion + +After the review process (with or without consolidation): + +> "Artifact review complete. [Summarize: N changes applied from M models, or no changes needed.] Ready to proceed with the next BMAD workflow step." + +**If all models failed/timed out:** Mention briefly and let the user decide whether to retry or finalize as-is. + +**If `mcp__sidecar__sidecar_read` fails:** Sidecar may not be installed or configured. Mention once and proceed. + +## Future: Configurable Settings + +The following settings are currently hardcoded in this skill. If sidecar adds an `autoSkills` config namespace, they could be moved to `autoSkills.bmadMethodCheck.*` in `~/.config/sidecar/config.json`: + +| Setting | Current Default | Description | +|---------|----------------|-------------| +| `autoSkills.bmadMethodCheck.maxBriefingChars` | 80,000 | Upper bound on total briefing content before summarizing inputs | +| `autoSkills.bmadMethodCheck.agent` | Plan | Agent mode for review sidecar | +| `autoSkills.bmadMethodCheck.timeout` | 15 min | Max time per sidecar round (currently hardcoded in sidecar platform) | +| `autoSkills.bmadMethodCheck.artifactDir` | `_bmad-output/` | Root directory for BMAD artifacts | +| `autoSkills.bmadMethodCheck.skipQuickFlow` | true | Whether to skip Quick Flow artifacts | From 5165ae23b3043f9c670283519cfca751c450e183 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 10:30:16 -0500 Subject: [PATCH 07/13] fix: address ChatGPT review findings for auto-bmad-method-check - Add sharded epics handling (concatenate shards with headers in briefing) - Remove Implementation Readiness from scope (gate, not persisted artifact) - Add partial pipeline failure handling (preserve changes, continue to next model) - Add explicit sleep 25 polling rule in Step 4a - Add prioritization guidance for large input document sets - Add scope rationale note explaining intentional artifact selectivity Co-Authored-By: Claude Opus 4.6 --- skill/auto-bmad-method-check/SKILL.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/skill/auto-bmad-method-check/SKILL.md b/skill/auto-bmad-method-check/SKILL.md index 5eb3f7d..f4fb1dc 100644 --- a/skill/auto-bmad-method-check/SKILL.md +++ b/skill/auto-bmad-method-check/SKILL.md @@ -29,11 +29,12 @@ This skill covers planning and key implementation artifacts where a second opini | `ux-design-specification.md` | Planning | `PRD.md` | | `architecture.md` | Solutioning | `PRD.md`, `ux-design-specification.md` (if exists) | | `epics.md` (or sharded `epics/` dir) | Solutioning | `PRD.md`, `architecture.md` | -| Implementation Readiness result | Solutioning | `PRD.md`, `architecture.md`, `epics.md`, `ux-design-specification.md` (if exists) | | `story-*.md` | Implementation | `epics.md`, `PRD.md`, `architecture.md`, `sprint-status.yaml` | | `sprint-change-proposal-*.md` | Implementation | `PRD.md`, `epics.md`, affected `story-*.md` files | | `epic-*-retro-*.md` | Implementation | All `story-*.md` in that epic, previous retro (if exists) | +**Scope rationale:** This table is intentionally selective — it covers high-leverage checkpoint artifacts where a second opinion catches costly mistakes. Lower-leverage artifacts (`brainstorming-report.md`, `research-*.md`, `sprint-status.yaml`, `project-context.md`) and non-persisted gates (Implementation Readiness) are excluded. ADRs produced alongside `architecture.md` are reviewed as part of the architecture artifact, not separately. + ## When This Skill Fires - A BMAD workflow has just written or substantially updated one of the artifacts above @@ -99,10 +100,13 @@ Wait for the user's response: - If no references found, fall back to the Artifact Scope table above - Scan `_bmad-output/planning-artifacts/` and `_bmad-output/implementation-artifacts/` for matching files - For glob patterns (e.g., `research-*.md`, `story-*.md`), collect all matching files + - **Large input sets:** If a glob matches many files (e.g., 10+ stories for a retrospective), list all paths in the briefing but mark the most directly relevant ones (e.g., same-epic completed stories, previous retro). The sidecar can read additional files on demand via `read_file`. 3. **Collect input document paths and descriptions.** For each input document, note its file path and a one-line description of what it contains (e.g., "`_bmad-output/planning-artifacts/PRD.md` — functional and non-functional requirements"). Do NOT read or paste their full content into the briefing — the sidecar has `read_file` access and will read them directly. This saves significant context in the parent session. -4. **Truncation guidance:** The output artifact should always be included in full (it's what's being reviewed). If even the artifact alone exceeds ~80,000 characters, truncate to the most relevant sections and note what was omitted so the sidecar can use `read_file` for the rest. +4. **Sharded artifacts (e.g., `epics/` directory):** If the artifact is a directory of shard files rather than a single file, concatenate all shards into the briefing with clear `--- filename.md ---` headers between each. Apply approved changes to the specific shard file(s) they target, not to a single monolithic file. When listing the artifact in the briefing, note that it spans multiple files so the sidecar references the correct shard in its findings. + +5. **Truncation guidance:** The output artifact should always be included in full (it's what's being reviewed). If even the artifact alone exceeds ~80,000 characters, truncate to the most relevant sections and note what was omitted so the sidecar can use `read_file` for the rest. ### Step 3: Spawn the first sidecar @@ -189,7 +193,7 @@ Process models in the order the user specified them. For each model: **4a. Poll and read results** -Poll the sidecar's status using `mcp__sidecar__sidecar_status` with the saved task ID, following the polling cadence indicated by `sidecar_status` responses. Continue polling while status is `running`; treat `complete`, `timeout`, `crashed`, `error`, and `aborted` as terminal. Once terminal, read the output using `mcp__sidecar__sidecar_read`. +Run `sleep 25` in your shell before the first and every subsequent `mcp__sidecar__sidecar_status` call — this enforces the mandatory polling interval and prevents token waste. Continue polling while status is `running`; treat `complete`, `timeout`, `crashed`, `error`, and `aborted` as terminal. Once terminal, read the output using `mcp__sidecar__sidecar_read`. **4b. Claude evaluates each suggestion** @@ -232,6 +236,7 @@ If there are more models to process: - This ensures the next model reviews the improved version, not the original - Poll, read, and evaluate the next model's results the same way (repeat 4a–4d) - When presenting: flag explicitly if this model raised something the previous model missed, or contradicts a change already applied +- **If a model fails or times out mid-pipeline:** Preserve all changes already applied from prior models. Inform the user briefly (e.g., "[model] timed out after 15 minutes"). Continue to the next model in the queue using the current artifact state. The user can choose to retry the failed model later or proceed without it. ### Step 5: Consolidation check From d0da1db42264aab3eabdf497af1e520fa14b82a7 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 10:33:33 -0500 Subject: [PATCH 08/13] =?UTF-8?q?fix:=20address=20CodeRabbit=20nitpicks=20?= =?UTF-8?q?=E2=80=94=20code=20fence=20tags=20and=20defensive=20try-catch?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add `text` language tags to bare code fences in bmad-workflow.md - Wrap AUTO_SKILLS readdirSync in try-catch for resilience Co-Authored-By: Claude Opus 4.6 --- docs/bmad-workflow.md | 4 ++-- scripts/postinstall.js | 15 ++++++++++----- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/bmad-workflow.md b/docs/bmad-workflow.md index b303129..fde2bb5 100644 --- a/docs/bmad-workflow.md +++ b/docs/bmad-workflow.md @@ -32,7 +32,7 @@ Reference for the auto-bmad-method-check skill. Captures all workflows, artifact ## Dependency Chain -``` +```text Brainstorming/Research ──> Product Brief ──> PRD ──> UX Design (optional) ├──> Architecture └──> Architecture ──> Epics/Stories @@ -92,7 +92,7 @@ Used by auto-bmad-method-check to determine which input documents to include in ## Standard Artifact Locations -``` +```text _bmad-output/ planning-artifacts/ brainstorming-report.md diff --git a/scripts/postinstall.js b/scripts/postinstall.js index b9648eb..e729122 100644 --- a/scripts/postinstall.js +++ b/scripts/postinstall.js @@ -18,11 +18,16 @@ 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'); -const AUTO_SKILLS = fs - .readdirSync(SKILL_DIR, { withFileTypes: true }) - .filter((entry) => entry.isDirectory() && entry.name.startsWith('auto-')) - .map((entry) => entry.name) - .sort(); +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'] }; From f01b2bf4f37961177971635d421174b9e98d56ac Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 10:53:15 -0500 Subject: [PATCH 09/13] feat: add auto-skills section to main SKILL.md + invocation research Adds an "Auto-Skills" section to the main sidecar SKILL.md listing all four auto-skills with trigger conditions. Since the main skill appears in Claude's available skills list, this gives Claude passive awareness of auto-skill triggers without requiring new hook infrastructure. Also adds docs/auto-skill-invocation-research.md with findings on how Superpowers achieves reliable skill invocation and recommendations for improving sidecar auto-skill reliability (SessionStart hook, etc.). Co-Authored-By: Claude Opus 4.6 --- docs/auto-skill-invocation-research.md | 177 +++++++++++++++++++++++++ skill/SKILL.md | 17 +++ 2 files changed, 194 insertions(+) create mode 100644 docs/auto-skill-invocation-research.md diff --git a/docs/auto-skill-invocation-research.md b/docs/auto-skill-invocation-research.md new file mode 100644 index 0000000..cef3187 --- /dev/null +++ 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//SKILL.md` — user/package skills +- `~/.claude/plugins/cache//skills//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 `` 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 — `` 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//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/skill/SKILL.md b/skill/SKILL.md index b440434..6d00595 100644 --- 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.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` From 2cf996768e70d1775cde8b11b6896b3b96fb4666 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 11:00:01 -0500 Subject: [PATCH 10/13] feat: make auto-skills user-invocable via top-level installation Install auto-skills as top-level skill directories (~/.claude/skills/sidecar-auto-*/) instead of nested under sidecar/. This makes them appear in Claude Code's available skills list, enabling both auto-fire on trigger conditions AND manual invocation via slash commands (/sidecar-auto-review, /sidecar-auto-security, etc.). - Rename frontmatter `name` fields to sidecar-auto-* prefix - Update postinstall.js to install to top-level with cleanup of old path - Update main SKILL.md reference to new location Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 +- scripts/postinstall.js | 20 +++++++++++++++++--- skill/SKILL.md | 2 +- skill/auto-bmad-method-check/SKILL.md | 2 +- skill/auto-review/SKILL.md | 2 +- skill/auto-security/SKILL.md | 2 +- skill/auto-unblock/SKILL.md | 2 +- 7 files changed, 23 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f88293d..d6bd1df 100644 --- 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 files to ~/.claude/skills/sidecar/ +├── postinstall.js # Install skill files to ~/.claude/skills/ ├── test-tools.sh ├── validate-docs.js # * Main entry point. ├── validate-thinking.js diff --git a/scripts/postinstall.js b/scripts/postinstall.js index e729122..6f1b206 100644 --- a/scripts/postinstall.js +++ b/scripts/postinstall.js @@ -62,7 +62,7 @@ function addMcpToConfigFile(configPath, name, config) { return status; } -/** Install skill files to ~/.claude/skills/sidecar/ */ +/** Install skill files to ~/.claude/skills/ */ function installSkill() { try { fs.mkdirSync(SKILL_DEST_DIR, { recursive: true }); @@ -72,13 +72,27 @@ function installSkill() { 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'); - const destDir = path.join(SKILL_DEST_DIR, name); + // 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: ${name}`); + console.log(`[claude-sidecar] Skill installed: sidecar-${name}`); + + // Clean up old nested location (~/.claude/skills/sidecar//) + 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}`); } diff --git a/skill/SKILL.md b/skill/SKILL.md index 6d00595..d377077 100644 --- a/skill/SKILL.md +++ b/skill/SKILL.md @@ -1016,7 +1016,7 @@ Sidecar includes auto-skills that fire automatically at key workflow moments. Th | `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.md` and follow its procedure. Each skill will prompt the user for confirmation before spawning any sidecars. +**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.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. diff --git a/skill/auto-bmad-method-check/SKILL.md b/skill/auto-bmad-method-check/SKILL.md index f4fb1dc..0517e4d 100644 --- a/skill/auto-bmad-method-check/SKILL.md +++ b/skill/auto-bmad-method-check/SKILL.md @@ -1,5 +1,5 @@ --- -name: auto-bmad-method-check +name: sidecar-auto-bmad-method-check description: > Use when a BMAD-METHOD workflow has just produced an output artifact (PRD, architecture doc, epics, story file, etc.) and the user has not yet finalized it or moved to the next workflow diff --git a/skill/auto-review/SKILL.md b/skill/auto-review/SKILL.md index add9ab1..c56d51c 100644 --- a/skill/auto-review/SKILL.md +++ b/skill/auto-review/SKILL.md @@ -1,5 +1,5 @@ --- -name: auto-review +name: sidecar-auto-review description: > Use after completing a feature implementation, bug fix, or significant code change — before claiming the work is done. Offers to spawn a sidecar with a different model to review the diff --git a/skill/auto-security/SKILL.md b/skill/auto-security/SKILL.md index ce9c181..1e74e58 100644 --- a/skill/auto-security/SKILL.md +++ b/skill/auto-security/SKILL.md @@ -1,5 +1,5 @@ --- -name: auto-security +name: sidecar-auto-security description: > Use when the user asks to commit changes, push code, or create a pull request. Offers to spawn a sidecar to audit the diff for security vulnerabilities before the commit/push/PR diff --git a/skill/auto-unblock/SKILL.md b/skill/auto-unblock/SKILL.md index dd8d59a..5c6b382 100644 --- a/skill/auto-unblock/SKILL.md +++ b/skill/auto-unblock/SKILL.md @@ -1,5 +1,5 @@ --- -name: auto-unblock +name: sidecar-auto-unblock description: > Use when you have attempted 5 or more different approaches to fix a bug, pass a test, or solve a problem and none have worked. Offers to spawn a sidecar brainstorming session with From e0b284b9e7c9fae9ea264dbba10910da88dbdd6b Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 11:06:30 -0500 Subject: [PATCH 11/13] docs: update auto-skill invocation research with completed work Reflects that Options B and D are now implemented. Updates the gap analysis table, adds verified skills list output, documents the nesting depth discovery, and refocuses remaining recommendations on SessionStart hook and config framework. Co-Authored-By: Claude Opus 4.6 --- docs/auto-skill-invocation-research.md | 108 ++++++++++++++----------- 1 file changed, 61 insertions(+), 47 deletions(-) diff --git a/docs/auto-skill-invocation-research.md b/docs/auto-skill-invocation-research.md index cef3187..ab932ea 100644 --- a/docs/auto-skill-invocation-research.md +++ b/docs/auto-skill-invocation-research.md @@ -4,7 +4,7 @@ Research into how Claude Code skills achieve reliable invocation, with specific ## 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. +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 were originally designed to rely solely 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?** @@ -31,6 +31,10 @@ Claude discovers skills via the **Skill tool**, which scans these directories an 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. +### Critical Discovery: Nesting Depth Matters + +Claude Code only discovers skills at the **top level** of `~/.claude/skills/`. A skill at `~/.claude/skills/my-skill/SKILL.md` appears in the available skills list; a skill nested at `~/.claude/skills/parent/child/SKILL.md` does **not**. This was the root cause of the original visibility gap — auto-skills were installed as nested subdirectories under the main sidecar skill. + ## How Superpowers Achieves Near-100% Reliability The Superpowers plugin (Claude's official skill framework) uses a three-layer reinforcement strategy: @@ -84,42 +88,52 @@ The three layers create **redundant triggering paths**: - 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've Done -### What We Have +### Step 1: Add Auto-Skills to Main SKILL.md (Option B) ✅ Done -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 +Added an "Auto-Skills: Contextual Sidecar Triggers" section to the main `skill/SKILL.md` listing all four auto-skills with their trigger conditions in a table. Since the main sidecar skill appears in the available skills list, Claude gets passive awareness of auto-skill triggers when it reads the main skill. -### The Gap +**Pros:** Simple one-file change, no new infrastructure needed. +**Cons:** Only provides awareness when sidecar context is active — Claude has to read the main skill first. -| Mechanism | Superpowers | Sidecar Auto-Skills | -|-----------|-------------|---------------------| -| SessionStart hook | Yes — injects meta-instruction | No | -| System prompt injection | Yes — `` 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) | +### Step 2: Top-Level Installation for Skills List Visibility (Option D) ✅ Done -*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. +Moved auto-skills from nested directories (`~/.claude/skills/sidecar/auto-*/`) to top-level directories (`~/.claude/skills/sidecar-auto-*/`). This makes them appear in Claude Code's "available skills" system reminder every turn. -### Practical Impact +**Changes made:** +- `postinstall.js` — installs auto-skills to `~/.claude/skills/sidecar-auto-review/` etc. (top-level), cleans up old nested path +- All 4 SKILL.md frontmatters — `name` field updated to `sidecar-auto-review`, `sidecar-auto-unblock`, `sidecar-auto-security`, `sidecar-auto-bmad-method-check` +- Main SKILL.md — updated reference path, mentions slash-command invocation -- 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. +**Result:** All four auto-skills now appear in the available skills list with their full trigger descriptions. They support both: +- **Auto-fire** — Claude pattern-matches trigger conditions from the skills list every turn +- **Manual invocation** — user can type `/sidecar-auto-review`, `/sidecar-auto-security`, etc. + +**Verified:** After local installation, the system reminder now includes entries like: +```text +- sidecar-auto-review: Use after completing a feature implementation, bug fix, or significant code change... +- sidecar-auto-unblock: Use when you have attempted 5 or more different approaches to fix a bug... +- sidecar-auto-security: Use when the user asks to commit changes, push code, or create a pull request... +- sidecar-auto-bmad-method-check: Use when a BMAD-METHOD workflow has just produced an output artifact... +``` -## Recommendations +### Current State -### Immediate: Add Auto-Skills to Main SKILL.md (Option B) ✅ Done +| Mechanism | Superpowers | Sidecar Auto-Skills | +|-----------|-------------|---------------------| +| SessionStart hook | Yes — injects meta-instruction | Not yet | +| System prompt injection | Yes — `` tags | Not yet | +| Available skills list | Yes — all skills listed with descriptions | **Yes** — all 4 auto-skills listed ✅ | +| Meta-instruction forcing skill checks | Yes — "ABSOLUTELY MUST" language | No — benefits from Superpowers if installed | +| Trigger specification | Description field | Description field (same format) ✅ | +| Manual invocation fallback | Yes — slash commands | **Yes** — `/sidecar-auto-*` commands ✅ | -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. +The critical gap (skills list visibility) is now closed. The remaining gap is the SessionStart hook — without it, sidecar auto-skills rely on either (a) Superpowers being installed to force skill checking, or (b) Claude independently deciding to check skills based on the available skills list. -**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. +## Remaining Recommendations -### Short-Term: SessionStart Hook (Option A) +### Next: 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. @@ -127,28 +141,21 @@ Register a lightweight SessionStart hook in sidecar's postinstall that injects a 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//SKILL.md when triggered. + Sidecar auto-skills are installed. When you recognize these trigger conditions, + invoke the corresponding skill: + - /sidecar-auto-review — after implementing changes, before telling user "done" + - /sidecar-auto-unblock — after 5+ failed fix attempts + - /sidecar-auto-security — before git commit/push/PR + - /sidecar-auto-bmad-method-check — after writing BMAD artifacts in _bmad-output/ ``` 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. +**Pros:** Matches Superpowers' proven pattern. Always present from session start. Works independent of Superpowers. Combined with skills list visibility (already done), this would give two independent triggering paths. **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 +### Future: Auto-Skills Framework in Sidecar Config If sidecar adds an `autoSkills` config namespace, centralize trigger definitions and enable/disable switches: @@ -165,13 +172,20 @@ If sidecar adds an `autoSkills` config namespace, centralize trigger definitions This would let users customize which auto-skills fire and with what defaults, without editing SKILL.md files. +### Future: Community Auto-Skills + +The top-level installation pattern (`~/.claude/skills/sidecar-auto-*/`) and dynamic discovery in postinstall (`fs.readdirSync` for `auto-*` directories) means third-party auto-skills could be contributed by following the same convention: +1. Add a `skill/auto-/SKILL.md` to the repo +2. Postinstall automatically discovers and installs it as `~/.claude/skills/sidecar-auto-/` +3. No hardcoded lists to maintain + ## 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 | +| Approach | Effort | Reliability | Status | +|----------|--------|-------------|--------| +| **B: Main SKILL.md section** | Low | Medium — works when sidecar context is active | ✅ Done | +| **D: Top-level installation** | Low | High — Claude checks skills list every turn | ✅ Done | +| **A: SessionStart hook** | Medium | Very high — always present from session start | Recommended next | +| **Config framework** | High | Very high — user-configurable | Future | -**Recommended path:** B (done) → A (next PR) → Config framework (when sidecar adds autoSkills namespace). +**Current reliability:** With options B and D both implemented, auto-skills have strong visibility through the available skills list. The main remaining improvement is a SessionStart hook (Option A) for environments where Superpowers is not installed, ensuring skill awareness is always injected at session start regardless of other plugins. From 66f937d6c8adcede9257d540b59eadd6ae99b5d2 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 11:07:31 -0500 Subject: [PATCH 12/13] chore: remove internal research doc from PR Co-Authored-By: Claude Opus 4.6 --- docs/auto-skill-invocation-research.md | 191 ------------------------- 1 file changed, 191 deletions(-) delete mode 100644 docs/auto-skill-invocation-research.md diff --git a/docs/auto-skill-invocation-research.md b/docs/auto-skill-invocation-research.md deleted file mode 100644 index ab932ea..0000000 --- a/docs/auto-skill-invocation-research.md +++ /dev/null @@ -1,191 +0,0 @@ -# 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 were originally designed to rely solely 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//SKILL.md` — user/package skills -- `~/.claude/plugins/cache//skills//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. - -### Critical Discovery: Nesting Depth Matters - -Claude Code only discovers skills at the **top level** of `~/.claude/skills/`. A skill at `~/.claude/skills/my-skill/SKILL.md` appears in the available skills list; a skill nested at `~/.claude/skills/parent/child/SKILL.md` does **not**. This was the root cause of the original visibility gap — auto-skills were installed as nested subdirectories under the main sidecar skill. - -## 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 `` 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 - -## What We've Done - -### Step 1: Add Auto-Skills to Main SKILL.md (Option B) ✅ Done - -Added an "Auto-Skills: Contextual Sidecar Triggers" section to the main `skill/SKILL.md` listing all four auto-skills with their trigger conditions in a table. Since the main sidecar skill appears in the available skills list, Claude gets passive awareness of auto-skill triggers when it reads the main skill. - -**Pros:** Simple one-file change, no new infrastructure needed. -**Cons:** Only provides awareness when sidecar context is active — Claude has to read the main skill first. - -### Step 2: Top-Level Installation for Skills List Visibility (Option D) ✅ Done - -Moved auto-skills from nested directories (`~/.claude/skills/sidecar/auto-*/`) to top-level directories (`~/.claude/skills/sidecar-auto-*/`). This makes them appear in Claude Code's "available skills" system reminder every turn. - -**Changes made:** -- `postinstall.js` — installs auto-skills to `~/.claude/skills/sidecar-auto-review/` etc. (top-level), cleans up old nested path -- All 4 SKILL.md frontmatters — `name` field updated to `sidecar-auto-review`, `sidecar-auto-unblock`, `sidecar-auto-security`, `sidecar-auto-bmad-method-check` -- Main SKILL.md — updated reference path, mentions slash-command invocation - -**Result:** All four auto-skills now appear in the available skills list with their full trigger descriptions. They support both: -- **Auto-fire** — Claude pattern-matches trigger conditions from the skills list every turn -- **Manual invocation** — user can type `/sidecar-auto-review`, `/sidecar-auto-security`, etc. - -**Verified:** After local installation, the system reminder now includes entries like: -```text -- sidecar-auto-review: Use after completing a feature implementation, bug fix, or significant code change... -- sidecar-auto-unblock: Use when you have attempted 5 or more different approaches to fix a bug... -- sidecar-auto-security: Use when the user asks to commit changes, push code, or create a pull request... -- sidecar-auto-bmad-method-check: Use when a BMAD-METHOD workflow has just produced an output artifact... -``` - -### Current State - -| Mechanism | Superpowers | Sidecar Auto-Skills | -|-----------|-------------|---------------------| -| SessionStart hook | Yes — injects meta-instruction | Not yet | -| System prompt injection | Yes — `` tags | Not yet | -| Available skills list | Yes — all skills listed with descriptions | **Yes** — all 4 auto-skills listed ✅ | -| Meta-instruction forcing skill checks | Yes — "ABSOLUTELY MUST" language | No — benefits from Superpowers if installed | -| Trigger specification | Description field | Description field (same format) ✅ | -| Manual invocation fallback | Yes — slash commands | **Yes** — `/sidecar-auto-*` commands ✅ | - -The critical gap (skills list visibility) is now closed. The remaining gap is the SessionStart hook — without it, sidecar auto-skills rely on either (a) Superpowers being installed to force skill checking, or (b) Claude independently deciding to check skills based on the available skills list. - -## Remaining Recommendations - -### Next: 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 installed. When you recognize these trigger conditions, - invoke the corresponding skill: - - /sidecar-auto-review — after implementing changes, before telling user "done" - - /sidecar-auto-unblock — after 5+ failed fix attempts - - /sidecar-auto-security — before git commit/push/PR - - /sidecar-auto-bmad-method-check — after writing BMAD artifacts in _bmad-output/ - ``` -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. Combined with skills list visibility (already done), this would give two independent triggering paths. -**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. - -### Future: 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. - -### Future: Community Auto-Skills - -The top-level installation pattern (`~/.claude/skills/sidecar-auto-*/`) and dynamic discovery in postinstall (`fs.readdirSync` for `auto-*` directories) means third-party auto-skills could be contributed by following the same convention: -1. Add a `skill/auto-/SKILL.md` to the repo -2. Postinstall automatically discovers and installs it as `~/.claude/skills/sidecar-auto-/` -3. No hardcoded lists to maintain - -## Summary - -| Approach | Effort | Reliability | Status | -|----------|--------|-------------|--------| -| **B: Main SKILL.md section** | Low | Medium — works when sidecar context is active | ✅ Done | -| **D: Top-level installation** | Low | High — Claude checks skills list every turn | ✅ Done | -| **A: SessionStart hook** | Medium | Very high — always present from session start | Recommended next | -| **Config framework** | High | Very high — user-configurable | Future | - -**Current reliability:** With options B and D both implemented, auto-skills have strong visibility through the available skills list. The main remaining improvement is a SessionStart hook (Option A) for environments where Superpowers is not installed, ensuring skill awareness is always injected at session start regardless of other plugins. From 464de2155ced1ab258662c87d4dd2df99fb94bd9 Mon Sep 17 00:00:00 2001 From: ellisjr Date: Thu, 12 Mar 2026 11:26:28 -0500 Subject: [PATCH 13/13] fix: remove blank line breaking markdown table in bmad-workflow.md Co-Authored-By: Claude Opus 4.6 --- docs/bmad-workflow.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/bmad-workflow.md b/docs/bmad-workflow.md index fde2bb5..f6b0b02 100644 --- a/docs/bmad-workflow.md +++ b/docs/bmad-workflow.md @@ -64,7 +64,6 @@ Used by auto-bmad-method-check to determine which input documents to include in | 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) |