@spinabot/brigade 0.1.1 → 1.0.0

package/skills/oauth-setup/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: oauth-setup
+description: Connect an OAuth 2.0 service (Gmail, Google APIs, etc.) using the built-in oauth_authorize tool — get a click-to-authorize link, auto-capture the code, and seal the tokens. Use whenever the operator asks to connect Gmail / a Google API / any OAuth account.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🔐",
+      },
+  }
+---
+
+# OAuth setup
+
+Use the **`oauth_authorize`** tool — NEVER hand-roll an `http` listener in bash. It opens a one-shot loopback listener on a free port (no EADDRINUSE, no port juggling), captures the code, and seals the tokens into the credential store.
+
+## The two mistakes to avoid (they cost a whole session once)
+
+1. **Use a Desktop-app OAuth client**, not a Web client. In Google Cloud Console → Credentials → Create OAuth client ID → **Application type: Desktop app**. Desktop clients accept ANY `http://127.0.0.1:<port>` loopback redirect with **no redirect-URI registration**. A *Web* client requires the exact redirect URI pre-registered, which is what causes `redirect_uri_mismatch`.
+2. **Use the real scope.** Gmail send is `https://www.googleapis.com/auth/gmail.send` (NOT `https://gmail.com/...`, which doesn't exist). Add `openid https://www.googleapis.com/auth/userinfo.email` if you want the account address auto-filled.
+
+## Flow
+
+1. Ask the operator to create a **Desktop-app** OAuth client (Gmail API enabled, consent screen in Testing with themselves as a test user) and paste the **client id + secret**.
+2. **Start** the flow:
+   ```
+   oauth_authorize({
+     action: "start",
+     provider: "google-gmail",
+     authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+     tokenEndpoint: "https://oauth2.googleapis.com/token",
+     userInfoEndpoint: "https://www.googleapis.com/oauth2/v3/userinfo",
+     clientId: "<id>", clientSecret: "<secret>",
+     scopes: ["https://www.googleapis.com/auth/gmail.send", "openid", "https://www.googleapis.com/auth/userinfo.email"],
+     extraAuthParams: { access_type: "offline", prompt: "consent" }
+   })
+   ```
+   `access_type=offline` + `prompt=consent` are required for a **refresh token** (otherwise re-auth is needed when the access token expires).
+3. Send the operator the returned `authUrl` to click.
+4. **Await** the redirect — it exchanges the code and seals the tokens:
+   ```
+   oauth_authorize({ action: "await", flowId: "<flowId from start>" })
+   ```
+   If it returns status `pending`, the operator hasn't clicked yet — tell them, then call `await` again.
+
+## Using a connected account (sending mail)
+
+The tokens are sealed in the credential store — you can't read them from a file or the DB, and you shouldn't try. To use a connected account:
+
+1. **Check what's connected:** `oauth_authorize({ action: "status" })` → lists each account (provider, email, scopes, expiry). No secrets.
+2. **Get a usable token:** `oauth_authorize({ action: "token", provider: "google-gmail" })` → returns `accessToken`. It auto-refreshes from the sealed refresh token when the old one expired, so you always get a live token. (Pass `provider` only if more than one account is connected.)
+3. **Call the API** with it. Gmail send:
+   `POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send`, header `Authorization: Bearer <accessToken>`, body `{ "raw": "<base64url RFC-822 message>" }`.
+
+Never `cat` the credential store, grep for the token, or hand-roll a refresh — `action:"token"` is the only retrieval path, and it keeps the refresh token + client secret sealed.

package/skills/obsidian/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: obsidian
+description: Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.
+homepage: https://help.obsidian.md
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "💎",
+        "requires": { "bins": ["obsidian-cli"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "yakitrak/yakitrak/obsidian-cli",
+              "bins": ["obsidian-cli"],
+              "label": "Install obsidian-cli (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Obsidian
+
+Obsidian vault = a normal folder on disk.
+
+Vault structure (typical)
+
+- Notes: `*.md` (plain text Markdown; edit with any editor)
+- Config: `.obsidian/` (workspace + plugin settings; usually don’t touch from scripts)
+- Canvases: `*.canvas` (JSON)
+- Attachments: whatever folder you chose in Obsidian settings (images/PDFs/etc.)
+
+## Find the active vault(s)
+
+Obsidian desktop tracks vaults here (source of truth):
+
+- `~/Library/Application Support/obsidian/obsidian.json`
+
+`obsidian-cli` resolves vaults from that file; vault name is typically the **folder name** (path suffix).
+
+Fast “what vault is active / where are the notes?”
+
+- If you’ve already set a default: `obsidian-cli print-default --path-only`
+- Otherwise, read `~/Library/Application Support/obsidian/obsidian.json` and use the vault entry with `"open": true`.
+
+Notes
+
+- Multiple vaults common (iCloud vs `~/Documents`, work/personal, etc.). Don’t guess; read config.
+- Avoid writing hardcoded vault paths into scripts; prefer reading the config or using `print-default`.
+
+## obsidian-cli quick start
+
+Pick a default vault (once):
+
+- `obsidian-cli set-default "<vault-folder-name>"`
+- `obsidian-cli print-default` / `obsidian-cli print-default --path-only`
+
+Search
+
+- `obsidian-cli search "query"` (note names)
+- `obsidian-cli search-content "query"` (inside notes; shows snippets + lines)
+
+Create
+
+- `obsidian-cli create "Folder/New note" --content "..." --open`
+- Requires Obsidian URI handler (`obsidian://…`) working (Obsidian installed).
+- Avoid creating notes under “hidden” dot-folders (e.g. `.something/...`) via URI; Obsidian may refuse.
+
+Move/rename (safe refactor)
+
+- `obsidian-cli move "old/path/note" "new/path/note"`
+- Updates `[[wikilinks]]` and common Markdown links across the vault (this is the main win vs `mv`).
+
+Delete
+
+- `obsidian-cli delete "path/note"`
+
+Prefer direct edits when appropriate: open the `.md` file and change it; Obsidian will pick it up.

package/skills/openai-whisper/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: openai-whisper
+description: Local speech-to-text with the Whisper CLI (no API key).
+homepage: https://openai.com/research/whisper
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🎤",
+        "requires": { "bins": ["whisper"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "openai-whisper",
+              "bins": ["whisper"],
+              "label": "Install OpenAI Whisper (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Whisper (CLI)
+
+Use `whisper` to transcribe audio locally.
+
+Quick start
+
+- `whisper /path/audio.mp3 --model medium --output_format txt --output_dir .`
+- `whisper /path/audio.m4a --task translate --output_format srt`
+
+Notes
+
+- Models download to `~/.cache/whisper` on first run.
+- `--model` defaults to `turbo` on this install.
+- Use smaller models for speed, larger for accuracy.

package/skills/openai-whisper-api/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: openai-whisper-api
+description: Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
+homepage: https://platform.openai.com/docs/guides/speech-to-text
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🌐",
+        "requires": { "bins": ["curl"], "env": ["OPENAI_API_KEY"] },
+        "primaryEnv": "OPENAI_API_KEY",
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "curl",
+              "bins": ["curl"],
+              "label": "Install curl (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# OpenAI Whisper API (curl)
+
+Transcribe an audio file via OpenAI’s `/v1/audio/transcriptions` endpoint. Set `OPENAI_BASE_URL` to use an OpenAI-compatible proxy or local gateway.
+
+## Quick start
+
+```bash
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a
+```
+
+Defaults:
+
+- Model: `whisper-1`
+- Output: `<input>.txt`
+
+## Useful flags
+
+```bash
+{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model whisper-1 --out /tmp/transcript.txt
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --language en
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --prompt "Speaker names: Peter, Daniel"
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --json --out /tmp/transcript.json
+```
+
+## API key
+
+Set `OPENAI_API_KEY`, or configure it in the active Brigade config file (`$BRIGADE_CONFIG_PATH`, default `~/.brigade/brigade.json`). Optionally set `OPENAI_BASE_URL` (for example `http://127.0.0.1:51805/v1`) to use an OpenAI-compatible proxy or local gateway:
+
+```json5
+{
+  skills: {
+    "openai-whisper-api": {
+      apiKey: "OPENAI_KEY_HERE",
+    },
+  },
+}
+```

package/skills/openai-whisper-api/scripts/transcribe.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  transcribe.sh <audio-file> [--model whisper-1] [--out /path/to/out.txt] [--language en] [--prompt "hint"] [--json]
+EOF
+  exit 2
+}
+
+if [[ "${1:-}" == "" || "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+fi
+
+in="${1:-}"
+shift || true
+
+model="whisper-1"
+out=""
+language=""
+prompt=""
+response_format="text"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --model)
+      model="${2:-}"
+      shift 2
+      ;;
+    --out)
+      out="${2:-}"
+      shift 2
+      ;;
+    --language)
+      language="${2:-}"
+      shift 2
+      ;;
+    --prompt)
+      prompt="${2:-}"
+      shift 2
+      ;;
+    --json)
+      response_format="json"
+      shift 1
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage
+      ;;
+  esac
+done
+
+if [[ ! -f "$in" ]]; then
+  echo "File not found: $in" >&2
+  exit 1
+fi
+
+if [[ "${OPENAI_API_KEY:-}" == "" ]]; then
+  echo "Missing OPENAI_API_KEY" >&2
+  exit 1
+fi
+
+if [[ "$out" == "" ]]; then
+  base="${in%.*}"
+  if [[ "$response_format" == "json" ]]; then
+    out="${base}.json"
+  else
+    out="${base}.txt"
+  fi
+fi
+
+mkdir -p "$(dirname "$out")"
+
+api_base="${OPENAI_BASE_URL:-https://api.openai.com/v1}"
+api_base="${api_base%/}"
+
+curl -sS "${api_base}/audio/transcriptions" \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Accept: application/json" \
+  -F "file=@${in}" \
+  -F "model=${model}" \
+  -F "response_format=${response_format}" \
+  ${language:+-F "language=${language}"} \
+  ${prompt:+-F "prompt=${prompt}"} \
+  >"$out"
+
+echo "$out"

package/skills/openhue/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: openhue
+description: Control Philips Hue lights and scenes via the OpenHue CLI.
+homepage: https://www.openhue.io/cli
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "💡",
+        "requires": { "bins": ["openhue"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "openhue/cli/openhue-cli",
+              "bins": ["openhue"],
+              "label": "Install OpenHue CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# OpenHue CLI
+
+Use `openhue` to control Philips Hue lights and scenes via a Hue Bridge.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- "Turn on/off the lights"
+- "Dim the living room lights"
+- "Set a scene" or "movie mode"
+- Controlling specific Hue rooms or zones
+- Adjusting brightness, color, or color temperature
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Non-Hue smart devices (other brands) → not supported
+- HomeKit scenes or Shortcuts → use Apple's ecosystem
+- TV or entertainment system control
+- Thermostat or HVAC
+- Smart plugs (unless Hue smart plugs)
+
+## Common Commands
+
+### List Resources
+
+```bash
+openhue get light       # List all lights
+openhue get room        # List all rooms
+openhue get scene       # List all scenes
+```
+
+### Control Lights
+
+```bash
+# Turn on/off
+openhue set light "Bedroom Lamp" --on
+openhue set light "Bedroom Lamp" --off
+
+# Brightness (0-100)
+openhue set light "Bedroom Lamp" --on --brightness 50
+
+# Color temperature (warm to cool: 153-500 mirek)
+openhue set light "Bedroom Lamp" --on --temperature 300
+
+# Color (by name or hex)
+openhue set light "Bedroom Lamp" --on --color red
+openhue set light "Bedroom Lamp" --on --rgb "#FF5500"
+```
+
+### Control Rooms
+
+```bash
+# Turn off entire room
+openhue set room "Bedroom" --off
+
+# Set room brightness
+openhue set room "Bedroom" --on --brightness 30
+```
+
+### Scenes
+
+```bash
+# Activate scene
+openhue set scene "Relax" --room "Bedroom"
+openhue set scene "Concentrate" --room "Office"
+```
+
+## Quick Presets
+
+```bash
+# Bedtime (dim warm)
+openhue set room "Bedroom" --on --brightness 20 --temperature 450
+
+# Work mode (bright cool)
+openhue set room "Office" --on --brightness 100 --temperature 250
+
+# Movie mode (dim)
+openhue set room "Living Room" --on --brightness 10
+```
+
+## Notes
+
+- Bridge must be on local network
+- First run requires button press on Hue bridge to pair
+- Colors only work on color-capable bulbs (not white-only)

package/skills/oracle/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: oracle
+description: Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).
+homepage: https://askoracle.dev
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🧿",
+        "requires": { "bins": ["oracle"] },
+        "install":
+          [
+            {
+              "id": "node",
+              "kind": "node",
+              "package": "@steipete/oracle",
+              "bins": ["oracle"],
+              "label": "Install oracle (node)",
+            },
+          ],
+      },
+  }
+---
+
+# oracle — best use
+
+Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat output as advisory: verify against code + tests.
+
+## Main use case (browser, GPT‑5.2 Pro)
+
+Default workflow here: `--engine browser` with GPT‑5.2 Pro in ChatGPT. This is the common “long think” path: ~10 minutes to ~1 hour is normal; expect a stored session you can reattach to.
+
+Recommended defaults:
+
+- Engine: browser (`--engine browser`)
+- Model: GPT‑5.2 Pro (`--model gpt-5.2-pro` or `--model "5.2 Pro"`)
+
+## Golden path
+
+1. Pick a tight file set (fewest files that still contain the truth).
+2. Preview payload + token spend (`--dry-run` + `--files-report`).
+3. Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.
+4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).
+
+## Commands (preferred)
+
+- Help:
+  - `oracle --help`
+  - If the binary isn’t installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).
+
+- Preview (no tokens):
+  - `oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"`
+  - `oracle --dry-run full -p "<task>" --file "src/**"`
+
+- Token sanity:
+  - `oracle --dry-run summary --files-report -p "<task>" --file "src/**"`
+
+- Browser run (main path; long-running is normal):
+  - `oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"`
+
+- Manual paste fallback:
+  - `oracle --render --copy -p "<task>" --file "src/**"`
+  - Note: `--copy` is a hidden alias for `--copy-markdown`.
+
+## Attaching files (`--file`)
+
+`--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated.
+
+- Include:
+  - `--file "src/**"`
+  - `--file src/index.ts`
+  - `--file docs --file README.md`
+
+- Exclude:
+  - `--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"`
+
+- Defaults (implementation behavior):
+  - Default-ignored dirs: `node_modules`, `dist`, `coverage`, `.git`, `.turbo`, `.next`, `build`, `tmp` (skipped unless explicitly passed as literal dirs/files).
+  - Honors `.gitignore` when expanding globs.
+  - Does not follow symlinks.
+  - Dotfiles filtered unless opted in via pattern (e.g. `--file ".github/**"`).
+  - Files > 1 MB rejected.
+
+## Engines (API vs browser)
+
+- Auto-pick: `api` when `OPENAI_API_KEY` is set; otherwise `browser`.
+- Browser supports GPT + Gemini only; use `--engine api` for Claude/Grok/the agent or multi-model runs.
+- Browser attachments:
+  - `--browser-attachments auto|never|always` (auto pastes inline up to ~60k chars then uploads).
+- Remote browser host:
+  - Host: `oracle serve --host 0.0.0.0 --port 9473 --token <secret>`
+  - Client: `oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"`
+
+## Sessions + slugs
+
+- Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
+- Runs may detach or take a long time (browser + GPT‑5.2 Pro often does). If the CLI times out: don’t re-run; reattach.
+  - List: `oracle status --hours 72`
+  - Attach: `oracle session <id> --render`
+- Use `--slug "<3-5 words>"` to keep session IDs readable.
+- Duplicate prompt guard exists; use `--force` only when you truly want a fresh run.
+
+## Prompt template (high signal)
+
+Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include:
+
+- Project briefing (stack + build/test commands + platform constraints).
+- “Where things live” (key directories, entrypoints, config files, boundaries).
+- Exact question + what you tried + the error text (verbatim).
+- Constraints (“don’t change X”, “must keep public API”, etc).
+- Desired output (“return patch plan + tests”, “give 3 options with tradeoffs”).
+
+## Safety
+
+- Don’t attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what’s required.
+
+## “Exhaustive prompt” restoration pattern
+
+For long investigations, write a standalone prompt + file set so you can rerun days later:
+
+- 6–30 sentence project briefing + the goal.
+- Repro steps + exact errors + what you tried.
+- Attach all context files needed (entrypoints, configs, key modules, docs).
+
+Oracle runs are one-shot; the model doesn’t remember prior runs. “Restoring context” means re-running with the same prompt + `--file …` set (or reattaching a still-running stored session).

package/skills/ordercli/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ordercli
+description: Foodora-only CLI for checking past orders and active order status (Deliveroo WIP).
+homepage: https://ordercli.sh
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🛵",
+        "requires": { "bins": ["ordercli"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/ordercli",
+              "bins": ["ordercli"],
+              "label": "Install ordercli (brew)",
+            },
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/ordercli/cmd/ordercli@latest",
+              "bins": ["ordercli"],
+              "label": "Install ordercli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# ordercli
+
+Use `ordercli` to check past orders and track active order status (Foodora only right now).
+
+Quick start (Foodora)
+
+- `ordercli foodora countries`
+- `ordercli foodora config set --country AT`
+- `ordercli foodora login --email you@example.com --password-stdin`
+- `ordercli foodora orders`
+- `ordercli foodora history --limit 20`
+- `ordercli foodora history show <orderCode>`
+
+Orders
+
+- Active list (arrival/status): `ordercli foodora orders`
+- Watch: `ordercli foodora orders --watch`
+- Active order detail: `ordercli foodora order <orderCode>`
+- History detail JSON: `ordercli foodora history show <orderCode> --json`
+
+Reorder (adds to cart)
+
+- Preview: `ordercli foodora reorder <orderCode>`
+- Confirm: `ordercli foodora reorder <orderCode> --confirm`
+- Address: `ordercli foodora reorder <orderCode> --confirm --address-id <id>`
+
+Cloudflare / bot protection
+
+- Browser login: `ordercli foodora login --email you@example.com --password-stdin --browser`
+- Reuse profile: `--browser-profile "$HOME/Library/Application Support/ordercli/browser-profile"`
+- Import Chrome cookies: `ordercli foodora cookies chrome --profile "Default"`
+
+Session import (no password)
+
+- `ordercli foodora session chrome --url https://www.foodora.at/ --profile "Default"`
+- `ordercli foodora session refresh --client-id android`
+
+Deliveroo (WIP, not working yet)
+
+- Requires `DELIVEROO_BEARER_TOKEN` (optional `DELIVEROO_COOKIE`).
+- `ordercli deliveroo config set --market uk`
+- `ordercli deliveroo history`
+
+Notes
+
+- Use `--config /tmp/ordercli.json` for testing.
+- Confirm before any reorder or cart-changing action.