@brainst0rm/core 0.13.0 → 0.14.1

package/dist/skills/builtin/github-collaboration/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: github-collaboration
+description: Full GitHub workflow mastery — PRs, code review, CI/CD, releases, security, search, and team collaboration patterns for enterprise engineering teams
+---
+
+## Overview
+
+This skill covers the complete GitHub collaboration lifecycle: from creating branches and PRs through code review, CI integration, release management, and security monitoring. It enables agents to operate as a full GitHub power user across 8 tool domains and 60+ actions.
+
+## When to Use
+
+Activate this skill when:
+
+- Creating, reviewing, or merging pull requests
+- Managing issues (triage, label, assign, track progress)
+- Performing or responding to code reviews
+- Monitoring CI/CD pipelines (GitHub Actions)
+- Creating releases and managing versioning
+- Searching code, issues, or commits across repos
+- Responding to security alerts (Dependabot, CodeQL, secret scanning)
+- Understanding repository settings, branch protection, and team permissions
+
+## Available Tools
+
+| Tool          | Actions                                                                               | Permission       |
+| ------------- | ------------------------------------------------------------------------------------- | ---------------- |
+| `gh_pr`       | create, list, view, merge, close, reopen, diff, checks, comment, ready                | confirm          |
+| `gh_issue`    | create, list, view, comment, close, reopen, edit, label, assign, pin, unpin, transfer | confirm          |
+| `gh_review`   | list, create, approve, request-changes, comment, view-comments                        | confirm          |
+| `gh_actions`  | workflows, runs, view-run, trigger, cancel, rerun, logs, artifacts                    | confirm          |
+| `gh_release`  | create, list, view, delete, upload, download                                          | confirm          |
+| `gh_search`   | code, issues, commits, repos, prs                                                     | auto (read-only) |
+| `gh_security` | dependabot, code-scanning, secret-scanning, sbom                                      | confirm          |
+| `gh_repo`     | info, collaborators, branch-protection, topics, labels, milestones, fork, clone-url   | auto (read-only) |
+
+## Core Workflows
+
+### Pull Request Lifecycle
+
+```
+1. Create branch → make changes → commit
+2. gh_pr create (title, body, reviewers, labels)
+3. gh_actions runs (monitor CI status)
+4. gh_pr checks (verify all checks pass)
+5. gh_review approve / request-changes
+6. gh_pr merge (squash/merge/rebase)
+```
+
+**Best practices:**
+
+- Always check CI status (`gh_pr checks`) before merging
+- Use `draft: true` for work-in-progress PRs
+- Request specific reviewers who own the changed code
+- Write PR descriptions that explain _why_, not just _what_
+- Use `gh_pr diff` to verify the changeset before merging
+- Prefer squash merge for feature branches (clean history)
+
+### Code Review Protocol
+
+```
+1. gh_pr view (understand the PR: files, additions, deletions)
+2. gh_pr diff (read the actual changes)
+3. gh_review create with event: COMMENT / APPROVE / REQUEST_CHANGES
+4. gh_review comment (inline comments on specific files/lines)
+```
+
+**Review quality checklist:**
+
+- Read the full diff before commenting
+- Focus on bugs and logic errors, not style (linters handle style)
+- Use inline comments with file path + line number for precision
+- When requesting changes, explain _what_ to fix and _why_
+- Approve with a brief summary of what you verified
+- Never approve without reading the diff
+
+### CI/CD Integration
+
+```
+1. gh_actions workflows (list available workflows)
+2. gh_actions runs (check recent run status)
+3. gh_actions view-run (see job details)
+4. gh_actions logs (debug failures)
+5. gh_actions rerun (retry after transient failure)
+6. gh_actions trigger (manually dispatch workflow)
+```
+
+**Patterns:**
+
+- Before merging: always verify CI passes via `gh_pr checks`
+- Failed CI: use `gh_actions logs` to get failure details, then fix
+- Manual workflows: use `trigger` with `workflow_dispatch` inputs
+- Cache issues: check `gh_actions artifacts` for build artifacts
+
+### Issue Management
+
+```
+1. gh_issue create (title, body, labels, assignees, milestone)
+2. gh_issue list (filter by state, label, assignee)
+3. gh_issue comment (updates, findings, decisions)
+4. gh_issue close (with reason: completed or not_planned)
+```
+
+**Triage workflow:**
+
+- New issues: add labels (bug, feature, documentation, etc.)
+- Assign to owner based on code area
+- Link to milestone for release tracking
+- Cross-reference related issues and PRs in comments
+
+### Release Management
+
+```
+1. Verify CI passes on release branch
+2. gh_release create (tag, title, generate-notes)
+3. gh_release upload (attach build artifacts)
+4. gh_issue close (close issues resolved in this release)
+```
+
+**Versioning:**
+
+- Follow semver: MAJOR.MINOR.PATCH
+- Use `--generate-notes` for automatic changelog from commits
+- Tag format: `v1.2.3`
+- Prerelease for beta/rc: `v1.2.3-beta.1`
+
+### Security Monitoring
+
+```
+1. gh_security dependabot (check for vulnerable dependencies)
+2. gh_security code-scanning (check for code vulnerabilities)
+3. gh_security secret-scanning (check for exposed secrets)
+4. gh_security sbom (export dependency list for compliance)
+```
+
+**Response protocol:**
+
+- Critical/high Dependabot alerts: create PR to update dependency
+- Secret scanning alerts: rotate the credential immediately
+- CodeQL alerts: review and fix or dismiss with justification
+- SBOM: export for compliance audits
+
+### Cross-Repo Search
+
+```
+1. gh_search code (find implementations, patterns, usage)
+2. gh_search issues (find related bugs, prior discussions)
+3. gh_search commits (find when something changed)
+4. gh_search repos (discover relevant projects)
+```
+
+**Search syntax tips:**
+
+- `repo:owner/repo` limits to specific repo
+- `language:typescript` filters by language
+- `path:src/` limits to specific directory
+- `filename:*.test.ts` finds test files
+- `"exact phrase"` for exact matches
+
+## Enterprise Patterns
+
+### Branch Protection Awareness
+
+Before attempting operations, check branch protection:
+
+```
+gh_repo branch-protection (branch: "main")
+```
+
+This reveals:
+
+- Required status checks (which CI must pass)
+- Required reviewers (how many approvals needed)
+- Dismiss stale reviews (re-review after push)
+- Restrictions (who can push)
+
+**Never attempt to merge a PR that violates branch protection rules.**
+
+### Team Collaboration
+
+```
+gh_repo collaborators (see who has access)
+gh_repo info (repo metadata, default branch)
+gh_repo labels (organizational labels)
+gh_repo milestones (release planning)
+```
+
+### Multi-Repo Workflows
+
+For monorepos or multi-service architectures:
+
+1. Use `gh_search code` to find dependencies across repos
+2. Create linked issues across repos for coordinated changes
+3. Reference cross-repo PRs in comments using `owner/repo#123` format
+
+## Red Flags
+
+- Merging without CI checks passing
+- Approving PRs without reading the diff
+- Creating releases without a changelog
+- Dismissing security alerts without investigation
+- Force-pushing to protected branches
+- Creating PRs with bodies that don't explain the _why_
+- Assigning issues without context for the assignee
+
+## Verification
+
+Before completing any GitHub workflow:
+
+- [ ] CI status checked and passing
+- [ ] PR description explains motivation, not just changes
+- [ ] Reviewers appropriate for the code area
+- [ ] Labels applied for categorization
+- [ ] Related issues linked or referenced
+- [ ] Security alerts reviewed (no new critical/high)
+- [ ] Branch protection rules respected

package/dist/skills/builtin/godmode-operations/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: godmode-operations
+description: Operate brainstorm's God Mode infrastructure control plane. Use when managing endpoints, agents, email security, VMs, or any connected product.
+---
+
+# God Mode Operations
+
+God Mode connects brainstorm to external infrastructure through the platform contract. Every product that implements `GET /health`, `GET /api/v1/god-mode/tools`, and `POST /api/v1/god-mode/execute` becomes controllable.
+
+## ChangeSet Protocol
+
+Every destructive action returns a **ChangeSet** — a simulation of what will happen:
+
+```
+1. Call a mutating God Mode tool (e.g., msp_isolate_device)
+2. Tool returns a ChangeSet with:
+   - changeset_id
+   - simulation (statePreview, cascades, constraints)
+   - risk score (0-100)
+   - risk factors
+3. Present the ChangeSet to the user
+4. User approves → call gm_changeset_approve with the ID
+5. User rejects → call gm_changeset_reject with the ID
+```
+
+**Rules:**
+
+- NEVER auto-approve a ChangeSet — always present and wait
+- If risk score > 50, explicitly warn about each risk factor
+- If cascading effects include data loss or service interruption, highlight them
+- One approval gates the entire operation
+
+## Entity Resolution
+
+Users refer to things by name, not by system ID:
+
+- "John's computer" → search devices by owner name → resolve to device ID
+- "the QA server" → search by hostname pattern → confirm with user if multiple matches
+
+## Cross-System Actions
+
+When a request involves multiple products:
+
+1. Identify all systems that need to act
+2. Call each system's tools in sequence
+3. Present a unified summary of ALL changesets
+4. One approval gates everything
+
+## Connected Products
+
+| Product          | What it manages                  | Example tools                                |
+| ---------------- | -------------------------------- | -------------------------------------------- |
+| BrainstormMSP    | Endpoints, users, backup, agents | msp_list_devices, agent_list, agent_run_tool |
+| BrainstormRouter | AI routing, cost tracking        | br_status, br_budget, br_models              |
+| BrainstormGTM    | Marketing, campaigns             | gtm_campaigns, gtm_leads                     |
+| BrainstormVM     | Virtual machines                 | vm_create, vm_migrate                        |
+| BrainstormShield | Email security                   | shield_scan, shield_quarantine               |
+
+## Edge Agent Operations
+
+The agent connector provides direct control over edge agents:
+
+- `agent_list` — fleet overview
+- `agent_status` — detail + trust score
+- `agent_ooda_events` — autonomous reasoning trail
+- `agent_workflow_approve` — approve/reject OODA decisions
+- `agent_run_tool` — dispatch any of 73 tools to remote endpoint
+- `agent_kill_switch` — emergency stop (ChangeSet-gated)

package/dist/skills/builtin/idea-refine/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: idea-refine
+description: Refines ideas iteratively. Refine ideas through structured divergent and convergent thinking. Use "idea-refine" or "ideate" to trigger.
+---
+
+# Idea Refine
+
+Refines raw ideas into sharp, actionable concepts worth building through structured divergent and convergent thinking.
+
+## How It Works
+
+1.  **Understand & Expand (Divergent):** Restate the idea, ask sharpening questions, and generate variations.
+2.  **Evaluate & Converge:** Cluster ideas, stress-test them, and surface hidden assumptions.
+3.  **Sharpen & Ship:** Produce a concrete markdown one-pager moving work forward.
+
+## Usage
+
+This skill is primarily an interactive dialogue. Invoke it with an idea, and the agent will guide you through the process.
+
+```bash
+# Optional: Initialize the ideas directory
+bash /mnt/skills/user/idea-refine/scripts/idea-refine.sh
+```
+
+**Trigger Phrases:**
+
+- "Help me refine this idea"
+- "Ideate on [concept]"
+- "Stress-test my plan"
+
+## Output
+
+The final output is a markdown one-pager saved to `docs/ideas/[idea-name].md` (after user confirmation), containing:
+
+- Problem Statement
+- Recommended Direction
+- Key Assumptions
+- MVP Scope
+- Not Doing list
+
+## Detailed Instructions
+
+You are an ideation partner. Your job is to help refine raw ideas into sharp, actionable concepts worth building.
+
+### Philosophy
+
+- Simplicity is the ultimate sophistication. Push toward the simplest version that still solves the real problem.
+- Start with the user experience, work backwards to technology.
+- Say no to 1,000 things. Focus beats breadth.
+- Challenge every assumption. "How it's usually done" is not a reason.
+- Show people the future — don't just give them better horses.
+- The parts you can't see should be as beautiful as the parts you can.
+
+### Process
+
+When the user invokes this skill with an idea (`$ARGUMENTS`), guide them through three phases. Adapt your approach based on what they say — this is a conversation, not a template.
+
+#### Phase 1: Understand & Expand (Divergent)
+
+**Goal:** Take the raw idea and open it up.
+
+1. **Restate the idea** as a crisp "How Might We" problem statement. This forces clarity on what's actually being solved.
+
+2. **Ask 3-5 sharpening questions** — no more. Focus on:
+   - Who is this for, specifically?
+   - What does success look like?
+   - What are the real constraints (time, tech, resources)?
+   - What's been tried before?
+   - Why now?
+
+   Use the `AskUserQuestion` tool to gather this input. Do NOT proceed until you understand who this is for and what success looks like.
+
+3. **Generate 5-8 idea variations** using these lenses:
+   - **Inversion:** "What if we did the opposite?"
+   - **Constraint removal:** "What if budget/time/tech weren't factors?"
+   - **Audience shift:** "What if this were for [different user]?"
+   - **Combination:** "What if we merged this with [adjacent idea]?"
+   - **Simplification:** "What's the version that's 10x simpler?"
+   - **10x version:** "What would this look like at massive scale?"
+   - **Expert lens:** "What would [domain] experts find obvious that outsiders wouldn't?"
+
+   Push beyond what the user initially asked for. Create products people don't know they need yet.
+
+**If running inside a codebase:** Use `Glob`, `Grep`, and `Read` to scan for relevant context — existing architecture, patterns, constraints, prior art. Ground your variations in what actually exists. Reference specific files and patterns when relevant.
+
+Read `frameworks.md` in this skill directory for additional ideation frameworks you can draw from. Use them selectively — pick the lens that fits the idea, don't run every framework mechanically.
+
+#### Phase 2: Evaluate & Converge
+
+After the user reacts to Phase 1 (indicates which ideas resonate, pushes back, adds context), shift to convergent mode:
+
+1. **Cluster** the ideas that resonated into 2-3 distinct directions. Each direction should feel meaningfully different, not just variations on a theme.
+
+2. **Stress-test** each direction against three criteria:
+   - **User value:** Who benefits and how much? Is this a painkiller or a vitamin?
+   - **Feasibility:** What's the technical and resource cost? What's the hardest part?
+   - **Differentiation:** What makes this genuinely different? Would someone switch from their current solution?
+
+   Read `refinement-criteria.md` in this skill directory for the full evaluation rubric.
+
+3. **Surface hidden assumptions.** For each direction, explicitly name:
+   - What you're betting is true (but haven't validated)
+   - What could kill this idea
+   - What you're choosing to ignore (and why that's okay for now)
+
+   This is where most ideation fails. Don't skip it.
+
+**Be honest, not supportive.** If an idea is weak, say so with kindness. A good ideation partner is not a yes-machine. Push back on complexity, question real value, and point out when the emperor has no clothes.
+
+#### Phase 3: Sharpen & Ship
+
+Produce a concrete artifact — a markdown one-pager that moves work forward:
+
+```markdown
+# [Idea Name]
+
+## Problem Statement
+
+[One-sentence "How Might We" framing]
+
+## Recommended Direction
+
+[The chosen direction and why — 2-3 paragraphs max]
+
+## Key Assumptions to Validate
+
+- [ ] [Assumption 1 — how to test it]
+- [ ] [Assumption 2 — how to test it]
+- [ ] [Assumption 3 — how to test it]
+
+## MVP Scope
+
+[The minimum version that tests the core assumption. What's in, what's out.]
+
+## Not Doing (and Why)
+
+- [Thing 1] — [reason]
+- [Thing 2] — [reason]
+- [Thing 3] — [reason]
+
+## Open Questions
+
+- [Question that needs answering before building]
+```
+
+**The "Not Doing" list is arguably the most valuable part.** Focus is about saying no to good ideas. Make the trade-offs explicit.
+
+Ask the user if they'd like to save this to `docs/ideas/[idea-name].md` (or a location of their choosing). Only save if they confirm.
+
+### Anti-patterns to Avoid
+
+- **Don't generate 20+ ideas.** Quality over quantity. 5-8 well-considered variations beat 20 shallow ones.
+- **Don't be a yes-machine.** Push back on weak ideas with specificity and kindness.
+- **Don't skip "who is this for."** Every good idea starts with a person and their problem.
+- **Don't produce a plan without surfacing assumptions.** Untested assumptions are the #1 killer of good ideas.
+- **Don't over-engineer the process.** Three phases, each doing one thing well. Resist adding steps.
+- **Don't just list ideas — tell a story.** Each variation should have a reason it exists, not just be a bullet point.
+- **Don't ignore the codebase.** If you're in a project, the existing architecture is a constraint and an opportunity. Use it.
+
+### Tone
+
+Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a facilitator reading from a script. Channel the energy of "that's interesting, but what if..." -- always pushing one step further without being exhausting.
+
+Read `examples.md` in this skill directory for examples of what great ideation sessions look like.
+
+## Red Flags
+
+- Generating 20+ shallow variations instead of 5-8 considered ones
+- Skipping the "who is this for" question
+- No assumptions surfaced before committing to a direction
+- Yes-machining weak ideas instead of pushing back with specificity
+- Producing a plan without a "Not Doing" list
+- Ignoring existing codebase constraints when ideating inside a project
+- Jumping straight to Phase 3 output without running Phases 1 and 2
+
+## Verification
+
+After completing an ideation session:
+
+- [ ] A clear "How Might We" problem statement exists
+- [ ] The target user and success criteria are defined
+- [ ] Multiple directions were explored, not just the first idea
+- [ ] Hidden assumptions are explicitly listed with validation strategies
+- [ ] A "Not Doing" list makes trade-offs explicit
+- [ ] The output is a concrete artifact (markdown one-pager), not just conversation
+- [ ] The user confirmed the final direction before any implementation work