diff --git a/CLAUDE.md b/CLAUDE.md index 39a8918..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 file to ~/.claude/skills/sidecar/ +├── postinstall.js # Install skill files to ~/.claude/skills/ ├── test-tools.sh ├── validate-docs.js # * Main entry point. ├── validate-thinking.js diff --git a/docs/bmad-workflow.md b/docs/bmad-workflow.md new file mode 100644 index 0000000..f6b0b02 --- /dev/null +++ b/docs/bmad-workflow.md @@ -0,0 +1,110 @@ +# BMAD-METHOD Workflow Reference + +Reference for the auto-bmad-method-check skill. Captures all workflows, artifacts, dependencies, and checkpoints. + +## Phases & Workflows + +| Phase | Workflow | Agent | Input Dependencies | Output Artifact | Checkpoint | +|---|---|---|---|---|---| +| **1: Analysis** (optional) | Brainstorming | Mary (Analyst) | None | `brainstorming-report.md` | Human reviews report | +| | Market Research | Mary | None (needs web search) | `research-*.md` | Human reviews findings | +| | Domain Research | Mary | None | `research-*.md` | Human reviews findings | +| | Technical Research | Mary | None | `research-*.md` | Human reviews findings | +| | Create Product Brief | Mary | Brainstorming/research (optional) | `product-brief.md` | Human reviews brief | +| **2: Planning** (required) | Create PRD | John (PM) | Product brief (optional) | `PRD.md` | Human reviews PRD | +| | Validate PRD | John | `PRD.md` | Validation report | Human reviews findings | +| | Edit PRD | John | `PRD.md` | Updated `PRD.md` | Human reviews edits | +| | Create UX Design | Sally (UX) | `PRD.md` | `ux-design-specification.md` | Human reviews UX spec | +| **3: Solutioning** | Create Architecture | Winston (Architect) | `PRD.md` (+ UX spec optional) | `architecture.md` + ADRs | Human reviews arch decisions | +| | Create Epics & Stories | John | `PRD.md` + `architecture.md` | `epics.md` (or sharded) | Human reviews breakdown | +| | Check Implementation Readiness | Winston/John | PRD + Architecture + Epics (+ UX) | PASS / CONCERNS / FAIL | **Gate** — must pass before Phase 4 | +| **4: Implementation** | Sprint Planning | Bob (SM) | Epics files | `sprint-status.yaml` | One-time setup | +| | Sprint Status | Bob | `sprint-status.yaml` | Status summary + risk flags | Informational | +| | Create Story | Bob | Sprint status + Epics + all artifacts | `story-{e}-{s}-{slug}.md` | Human reviews story before dev | +| | Dev Story | Amelia (Dev) | Story file (status: ready-for-dev) | Working code + tests | HALTs on blockers | +| | Code Review | Amelia/Barry | Story file + git changes | Approved or Changes Requested | Human decides on action items | +| | Correct Course | Bob/John | PRD + Epics + sprint context | `sprint-change-proposal-*.md` | Human approves proposal | +| | Retrospective | Bob | All completed stories in epic | `epic-{N}-retro-{date}.md` | Significant Discovery Alert if assumptions shifted | +| **Quick Flow** | Quick Spec | Barry (Solo Dev) | None | `tech-spec.md` | Human reviews spec | +| | Quick Dev | Barry | `tech-spec.md` or direct instructions | Working code + tests | Self-review then human | +| **Cross-cutting** | Generate Project Context | Mary | Codebase scan | `project-context.md` | Used by 7+ workflows | +| | BMad Help | Any | Project state inspection | Next-step guidance | Runs after every workflow | + +## Dependency Chain + +```text +Brainstorming/Research ──> Product Brief ──> PRD ──> UX Design (optional) + ├──> Architecture + └──> Architecture ──> Epics/Stories + │ + Implementation Readiness <┘ (GATE) + │ + Sprint Planning (once) + │ + Create Story ──> Dev Story ──> Code Review + ^ │ + └─────── (next story) ────────┘ + │ + Epic complete ──> Retrospective ───┘ +``` + +## Artifact-to-Input Mapping + +Used by auto-bmad-method-check to determine which input documents to include in sidecar reviews. + +| Output Artifact | Input Documents | +|---|---| +| `brainstorming-report.md` | None (freeform ideation) | +| `research-*.md` | None (primary research) | +| `product-brief.md` | `brainstorming-report.md`, `research-*.md` (if they exist) | +| `PRD.md` | `product-brief.md` (if exists) | +| `ux-design-specification.md` | `PRD.md` | +| `architecture.md` | `PRD.md`, `ux-design-specification.md` (if exists) | +| `epics.md` | `PRD.md`, `architecture.md` | +| Implementation Readiness | `PRD.md`, `architecture.md`, `epics.md`, `ux-design-specification.md` (if exists) | +| `sprint-status.yaml` | `epics.md` | +| `story-*.md` | `epics.md`, `PRD.md`, `architecture.md`, `sprint-status.yaml` | +| `sprint-change-proposal-*.md` | `PRD.md`, `epics.md`, affected `story-*.md` files | +| `epic-*-retro-*.md` | All `story-*.md` in that epic, previous retro (if exists) | +| `tech-spec.md` | None (Quick Flow — standalone) | + +## Agents + +| Agent | Name | Personality | Primary Workflows | +|---|---|---|---| +| Analyst | Mary | "Excited treasure hunter" | Brainstorming, Research, Product Brief, Project Context | +| Product Manager | John | "Asks WHY relentlessly like a detective" | PRD, Validate/Edit PRD, Epics, Readiness Check, Course Correction | +| Architect | Winston | "Calm, pragmatic tones" | Architecture, Readiness Check | +| Scrum Master | Bob | "Crisp, checklist-driven, zero ambiguity tolerance" | Sprint Planning/Status, Create Story, Retrospective, Course Correction | +| Developer | Amelia | "Ultra-succinct, speaks in file paths" | Dev Story, Code Review | +| UX Designer | Sally | "Paints pictures with words" | UX Design | +| Quick Flow Solo Dev | Barry | "Direct, no fluff, just results" | Quick Spec, Quick Dev, Code Review | +| Tech Writer | Paige | "Patient educator" | Document Project | + +## Key Design Principles + +- **Micro-file architecture**: Steps loaded one at a time to prevent LLM "lost in middle" issues +- **Human must approve** every step transition — no autonomous progression +- **Fresh conversations** per workflow to keep context clean +- **Scale-adaptive**: Quick Flow (1-15 stories), BMad Method (10-50+), Enterprise (30+) +- **`project-context.md`** acts as the "constitution" for consistent AI agent behavior + +## Standard Artifact Locations + +```text +_bmad-output/ + planning-artifacts/ + brainstorming-report.md + product-brief.md + research-*.md + PRD.md + ux-design-specification.md + architecture.md + epics.md (or epics/ directory) + sprint-change-proposal-*.md + implementation-artifacts/ + sprint-status.yaml + story-*.md + epic-*-retro-*.md + project-context.md +``` diff --git a/scripts/postinstall.js b/scripts/postinstall.js index 2f6b7d4..6f1b206 100644 --- a/scripts/postinstall.js +++ b/scripts/postinstall.js @@ -13,10 +13,22 @@ const path = require('path'); const os = require('os'); const { execFileSync } = require('child_process'); -const SKILL_SOURCE = path.join(__dirname, '..', 'skill', 'SKILL.md'); +const SKILL_DIR = path.join(__dirname, '..', 'skill'); +const SKILL_SOURCE = path.join(SKILL_DIR, 'SKILL.md'); const SKILL_DEST_DIR = path.join(os.homedir(), '.claude', 'skills', 'sidecar'); const SKILL_DEST = path.join(SKILL_DEST_DIR, 'SKILL.md'); +let AUTO_SKILLS = []; +try { + AUTO_SKILLS = fs + .readdirSync(SKILL_DIR, { withFileTypes: true }) + .filter((entry) => entry.isDirectory() && entry.name.startsWith('auto-')) + .map((entry) => entry.name) + .sort(); +} catch { + // skill/ directory missing — continue with empty list +} + const MCP_CONFIG = { command: 'npx', args: ['-y', 'claude-sidecar@latest', 'mcp'] }; /** @@ -50,7 +62,7 @@ function addMcpToConfigFile(configPath, name, config) { return status; } -/** Install skill file to ~/.claude/skills/sidecar/ */ +/** Install skill files to ~/.claude/skills/ */ function installSkill() { try { fs.mkdirSync(SKILL_DEST_DIR, { recursive: true }); @@ -59,6 +71,32 @@ function installSkill() { } catch (err) { console.error(`[claude-sidecar] Warning: Could not install skill: ${err.message}`); } + + const skillsRoot = path.join(os.homedir(), '.claude', 'skills'); + for (const name of AUTO_SKILLS) { + try { + const src = path.join(SKILL_DIR, name, 'SKILL.md'); + // Install as top-level skill (e.g., ~/.claude/skills/sidecar-auto-review/) + // so Claude Code discovers it in the available skills list + const destDir = path.join(skillsRoot, `sidecar-${name}`); + fs.mkdirSync(destDir, { recursive: true }); + fs.copyFileSync(src, path.join(destDir, 'SKILL.md')); + console.log(`[claude-sidecar] Skill installed: sidecar-${name}`); + + // Clean up old nested location (~/.claude/skills/sidecar//) + const oldDir = path.join(SKILL_DEST_DIR, name); + try { + if (fs.existsSync(path.join(oldDir, 'SKILL.md'))) { + fs.unlinkSync(path.join(oldDir, 'SKILL.md')); + fs.rmdirSync(oldDir); + } + } catch { + // Old location doesn't exist or already cleaned — ignore + } + } catch (err) { + console.error(`[claude-sidecar] Warning: Could not install ${name} skill: ${err.message}`); + } + } } /** Register MCP server in Claude Code config */ diff --git a/skill/SKILL.md b/skill/SKILL.md index b440434..d377077 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, 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. + +--- + ## Quick Start Checklist 1. [ ] Install sidecar: `npm install -g claude-sidecar` diff --git a/skill/auto-bmad-method-check/SKILL.md b/skill/auto-bmad-method-check/SKILL.md new file mode 100644 index 0000000..0517e4d --- /dev/null +++ b/skill/auto-bmad-method-check/SKILL.md @@ -0,0 +1,281 @@ +--- +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 + 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` | +| `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 +- 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 + - **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. **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 + +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** + +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** + +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 +- **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 + +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 | diff --git a/skill/auto-review/SKILL.md b/skill/auto-review/SKILL.md new file mode 100644 index 0000000..c56d51c --- /dev/null +++ b/skill/auto-review/SKILL.md @@ -0,0 +1,148 @@ +--- +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 + 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) | diff --git a/skill/auto-security/SKILL.md b/skill/auto-security/SKILL.md new file mode 100644 index 0000000..1e74e58 --- /dev/null +++ b/skill/auto-security/SKILL.md @@ -0,0 +1,152 @@ +--- +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 + 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) | diff --git a/skill/auto-unblock/SKILL.md b/skill/auto-unblock/SKILL.md new file mode 100644 index 0000000..5c6b382 --- /dev/null +++ b/skill/auto-unblock/SKILL.md @@ -0,0 +1,233 @@ +--- +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 + 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) |