@spinabot/brigade 0.1.2 → 1.0.1

package/skills/wacli/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: wacli
+description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).
+homepage: https://wacli.sh
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📱",
+        "requires": { "bins": ["wacli"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/wacli",
+              "bins": ["wacli"],
+              "label": "Install wacli (brew)",
+            },
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/wacli/cmd/wacli@latest",
+              "bins": ["wacli"],
+              "label": "Install wacli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# wacli
+
+Use `wacli` only when the user explicitly asks you to message someone else on WhatsApp or when they ask to sync/search WhatsApp history.
+Do NOT use `wacli` for normal user chats; Brigade routes WhatsApp conversations automatically.
+If the user is chatting with you on WhatsApp, you should not reach for this tool unless they ask you to contact a third party.
+
+Safety
+
+- Require explicit recipient + message text.
+- Confirm recipient + message before sending.
+- If anything is ambiguous, ask a clarifying question.
+
+Auth + sync
+
+- `wacli auth` (QR login + initial sync)
+- `wacli sync --follow` (continuous sync)
+- `wacli doctor`
+
+Find chats + messages
+
+- `wacli chats list --limit 20 --query "name or number"`
+- `wacli messages search "query" --limit 20 --chat <jid>`
+- `wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31`
+
+History backfill
+
+- `wacli history backfill --chat <jid> --requests 2 --count 50`
+
+Send
+
+- Text: `wacli send text --to "+14155551212" --message "Hello! Are you free at 3pm?"`
+- Group: `wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late."`
+- File: `wacli send file --to "+14155551212" --file /path/agenda.pdf --caption "Agenda"`
+
+Notes
+
+- Store dir: `~/.wacli` (override with `--store`).
+- Use `--json` for machine-readable output when parsing.
+- Backfill requires your phone online; results are best-effort.
+- WhatsApp CLI is not needed for routine user chats; it’s for messaging other people.
+- JIDs: direct chats look like `<number>@s.whatsapp.net`; groups look like `<id>@g.us` (use `wacli chats list` to find).

package/skills/weather/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: weather
+description: "Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed."
+homepage: https://wttr.in/:help
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "☔",
+        "requires": { "bins": ["curl"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "curl",
+              "bins": ["curl"],
+              "label": "Install curl (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Weather Skill
+
+Get current weather conditions and forecasts.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- "What's the weather?"
+- "Will it rain today/tomorrow?"
+- "Temperature in [city]"
+- "Weather forecast for the week"
+- Travel planning weather checks
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Historical weather data → use weather archives/APIs
+- Climate analysis or trends → use specialized data sources
+- Hyper-local microclimate data → use local sensors
+- Severe weather alerts → check official NWS sources
+- Aviation/marine weather → use specialized services (METAR, etc.)
+
+## Location
+
+Always include a city, region, or airport code in weather queries.
+
+## Commands
+
+### Current Weather
+
+```bash
+# One-line summary
+curl "wttr.in/London?format=3"
+
+# Detailed current conditions
+curl "wttr.in/London?0"
+
+# Specific city
+curl "wttr.in/New+York?format=3"
+```
+
+### Forecasts
+
+```bash
+# 3-day forecast
+curl "wttr.in/London"
+
+# Week forecast
+curl "wttr.in/London?format=v2"
+
+# Specific day (0=today, 1=tomorrow, 2=day after)
+curl "wttr.in/London?1"
+```
+
+### Format Options
+
+```bash
+# One-liner
+curl "wttr.in/London?format=%l:+%c+%t+%w"
+
+# JSON output
+curl "wttr.in/London?format=j1"
+
+# PNG image
+curl "wttr.in/London.png"
+```
+
+### Format Codes
+
+- `%c` — Weather condition emoji
+- `%t` — Temperature
+- `%f` — "Feels like"
+- `%w` — Wind
+- `%h` — Humidity
+- `%p` — Precipitation
+- `%l` — Location
+
+## Quick Responses
+
+**"What's the weather?"**
+
+```bash
+curl -s "wttr.in/London?format=%l:+%c+%t+(feels+like+%f),+%w+wind,+%h+humidity"
+```
+
+**"Will it rain?"**
+
+```bash
+curl -s "wttr.in/London?format=%l:+%c+%p"
+```
+
+**"Weekend forecast"**
+
+```bash
+curl "wttr.in/London?format=v2"
+```
+
+## Notes
+
+- No API key needed (uses wttr.in)
+- Rate limited; don't spam requests
+- Works for most global cities
+- Supports airport codes: `curl wttr.in/ORD`

package/skills/xurl/SKILL.md

@@ -0,0 +1,461 @@
+---
+name: xurl
+description: A CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🐦",
+        "requires": { "bins": ["xurl"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "xdevplatform/tap/xurl",
+              "bins": ["xurl"],
+              "label": "Install xurl (brew)",
+            },
+            {
+              "id": "npm",
+              "kind": "npm",
+              "package": "@xdevplatform/xurl",
+              "bins": ["xurl"],
+              "label": "Install xurl (npm)",
+            },
+          ],
+      },
+  }
+---
+
+# xurl — Agent Skill Reference
+
+`xurl` is a CLI tool for the X API. It supports both **shortcut commands** (human/agent‑friendly one‑liners) and **raw curl‑style** access to any v2 endpoint. All commands return JSON to stdout.
+
+---
+
+## Installation
+
+### Homebrew (macOS)
+
+```bash
+brew install --cask xdevplatform/tap/xurl
+```
+
+### npm
+
+```bash
+npm install -g @xdevplatform/xurl
+```
+
+### Shell script
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
+```
+
+Installs to `~/.local/bin`. If it's not in your PATH, the script will tell you what to add.
+
+### Go
+
+```bash
+go install github.com/xdevplatform/xurl@latest
+```
+
+---
+
+## Prerequisites
+
+This skill requires the `xurl` CLI utility: <https://github.com/xdevplatform/xurl>.
+
+Before using any command you must be authenticated. Run `xurl auth status` to check.
+
+### Secret Safety (Mandatory)
+
+- Never read, print, parse, summarize, upload, or send `~/.xurl` (or copies of it) to the LLM context.
+- Never ask the user to paste credentials/tokens into chat.
+- The user must fill `~/.xurl` with required secrets manually on their own machine.
+- Do not recommend or execute auth commands with inline secrets in agent/LLM sessions.
+- Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history).
+- Never use `--verbose` / `-v` in agent/LLM sessions; it can expose sensitive headers/tokens in output.
+- Sensitive flags that must never be used in agent commands: `--bearer-token`, `--consumer-key`, `--consumer-secret`, `--access-token`, `--token-secret`, `--client-id`, `--client-secret`.
+- To verify whether at least one app with credentials is already registered, run: `xurl auth status`.
+
+### Register an app (recommended)
+
+App credential registration must be done manually by the user outside the agent/LLM session.
+After credentials are registered, authenticate with:
+
+```bash
+xurl auth oauth2
+```
+
+For multiple pre-configured apps, switch between them:
+
+```bash
+xurl auth default prod-app          # set default app
+xurl auth default prod-app alice    # set default app + user
+xurl --app dev-app /2/users/me      # one-off override
+```
+
+### Other auth methods
+
+Examples with inline secret flags are intentionally omitted. If OAuth1 or app-only auth is needed, the user must run those commands manually outside agent/LLM context.
+
+Tokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated tokens. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right `Authorization` header.
+
+---
+
+## Quick Reference
+
+| Action                    | Command                                               |
+| ------------------------- | ----------------------------------------------------- |
+| Post                      | `xurl post "Hello world!"`                            |
+| Reply                     | `xurl reply POST_ID "Nice post!"`                     |
+| Quote                     | `xurl quote POST_ID "My take"`                        |
+| Delete a post             | `xurl delete POST_ID`                                 |
+| Read a post               | `xurl read POST_ID`                                   |
+| Search posts              | `xurl search "QUERY" -n 10`                           |
+| Who am I                  | `xurl whoami`                                         |
+| Look up a user            | `xurl user @handle`                                   |
+| Home timeline             | `xurl timeline -n 20`                                 |
+| Mentions                  | `xurl mentions -n 10`                                 |
+| Like                      | `xurl like POST_ID`                                   |
+| Unlike                    | `xurl unlike POST_ID`                                 |
+| Repost                    | `xurl repost POST_ID`                                 |
+| Undo repost               | `xurl unrepost POST_ID`                               |
+| Bookmark                  | `xurl bookmark POST_ID`                               |
+| Remove bookmark           | `xurl unbookmark POST_ID`                             |
+| List bookmarks            | `xurl bookmarks -n 10`                                |
+| List likes                | `xurl likes -n 10`                                    |
+| Follow                    | `xurl follow @handle`                                 |
+| Unfollow                  | `xurl unfollow @handle`                               |
+| List following            | `xurl following -n 20`                                |
+| List followers            | `xurl followers -n 20`                                |
+| Block                     | `xurl block @handle`                                  |
+| Unblock                   | `xurl unblock @handle`                                |
+| Mute                      | `xurl mute @handle`                                   |
+| Unmute                    | `xurl unmute @handle`                                 |
+| Send DM                   | `xurl dm @handle "message"`                           |
+| List DMs                  | `xurl dms -n 10`                                      |
+| Upload media              | `xurl media upload path/to/file.mp4`                  |
+| Media status              | `xurl media status MEDIA_ID`                          |
+| **App Management**        |                                                       |
+| Register app              | Manual, outside agent (do not pass secrets via agent) |
+| List apps                 | `xurl auth apps list`                                 |
+| Update app creds          | Manual, outside agent (do not pass secrets via agent) |
+| Remove app                | `xurl auth apps remove NAME`                          |
+| Set default (interactive) | `xurl auth default`                                   |
+| Set default (command)     | `xurl auth default APP_NAME [USERNAME]`               |
+| Use app per-request       | `xurl --app NAME /2/users/me`                         |
+| Auth status               | `xurl auth status`                                    |
+
+> **Post IDs vs URLs:** Anywhere `POST_ID` appears above you can also paste a full post URL (e.g. `https://x.com/user/status/1234567890`) — xurl extracts the ID automatically.
+
+> **Usernames:** Leading `@` is optional. `@elonmusk` and `elonmusk` both work.
+
+---
+
+## Command Details
+
+### Posting
+
+```bash
+# Simple post
+xurl post "Hello world!"
+
+# Post with media (upload first, then attach)
+xurl media upload photo.jpg          # → note the media_id from response
+xurl post "Check this out" --media-id MEDIA_ID
+
+# Multiple media
+xurl post "Thread pics" --media-id 111 --media-id 222
+
+# Reply to a post (by ID or URL)
+xurl reply 1234567890 "Great point!"
+xurl reply https://x.com/user/status/1234567890 "Agreed!"
+
+# Reply with media
+xurl reply 1234567890 "Look at this" --media-id MEDIA_ID
+
+# Quote a post
+xurl quote 1234567890 "Adding my thoughts"
+
+# Delete your own post
+xurl delete 1234567890
+```
+
+### Reading
+
+```bash
+# Read a single post (returns author, text, metrics, entities)
+xurl read 1234567890
+xurl read https://x.com/user/status/1234567890
+
+# Search recent posts (default 10 results)
+xurl search "golang"
+xurl search "from:elonmusk" -n 20
+xurl search "#buildinpublic lang:en" -n 15
+```
+
+### User Info
+
+```bash
+# Your own profile
+xurl whoami
+
+# Look up any user
+xurl user elonmusk
+xurl user @XDevelopers
+```
+
+### Timelines & Mentions
+
+```bash
+# Home timeline (reverse chronological)
+xurl timeline
+xurl timeline -n 25
+
+# Your mentions
+xurl mentions
+xurl mentions -n 20
+```
+
+### Engagement
+
+```bash
+# Like / unlike
+xurl like 1234567890
+xurl unlike 1234567890
+
+# Repost / undo
+xurl repost 1234567890
+xurl unrepost 1234567890
+
+# Bookmark / remove
+xurl bookmark 1234567890
+xurl unbookmark 1234567890
+
+# List your bookmarks / likes
+xurl bookmarks -n 20
+xurl likes -n 20
+```
+
+### Social Graph
+
+```bash
+# Follow / unfollow
+xurl follow @XDevelopers
+xurl unfollow @XDevelopers
+
+# List who you follow / your followers
+xurl following -n 50
+xurl followers -n 50
+
+# List another user's following/followers
+xurl following --of elonmusk -n 20
+xurl followers --of elonmusk -n 20
+
+# Block / unblock
+xurl block @spammer
+xurl unblock @spammer
+
+# Mute / unmute
+xurl mute @annoying
+xurl unmute @annoying
+```
+
+### Direct Messages
+
+```bash
+# Send a DM
+xurl dm @someuser "Hey, saw your post!"
+
+# List recent DM events
+xurl dms
+xurl dms -n 25
+```
+
+### Media Upload
+
+```bash
+# Upload a file (auto‑detects type for images/videos)
+xurl media upload photo.jpg
+xurl media upload video.mp4
+
+# Specify type and category explicitly
+xurl media upload --media-type image/jpeg --category tweet_image photo.jpg
+
+# Check processing status (videos need server‑side processing)
+xurl media status MEDIA_ID
+xurl media status --wait MEDIA_ID    # poll until done
+
+# Full workflow: upload then post
+xurl media upload meme.png           # response includes media id
+xurl post "lol" --media-id MEDIA_ID
+```
+
+---
+
+## Global Flags
+
+These flags work on every command:
+
+| Flag         | Short | Description                                                        |
+| ------------ | ----- | ------------------------------------------------------------------ |
+| `--app`      |       | Use a specific registered app for this request (overrides default) |
+| `--auth`     |       | Force auth type: `oauth1`, `oauth2`, or `app`                      |
+| `--username` | `-u`  | Which OAuth2 account to use (if you have multiple)                 |
+| `--verbose`  | `-v`  | Forbidden in agent/LLM sessions (can leak auth headers/tokens)     |
+| `--trace`    | `-t`  | Add `X-B3-Flags: 1` trace header                                   |
+
+---
+
+## Raw API Access
+
+The shortcut commands cover the most common operations. For anything else, use xurl's raw curl‑style mode — it works with **any** X API v2 endpoint:
+
+```bash
+# GET request (default)
+xurl /2/users/me
+
+# POST with JSON body
+xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
+
+# PUT, PATCH, DELETE
+xurl -X DELETE /2/tweets/1234567890
+
+# Custom headers
+xurl -H "Content-Type: application/json" /2/some/endpoint
+
+# Force streaming mode
+xurl -s /2/tweets/search/stream
+
+# Full URLs also work
+xurl https://api.x.com/2/users/me
+```
+
+---
+
+## Streaming
+
+Streaming endpoints are auto‑detected. Known streaming endpoints include:
+
+- `/2/tweets/search/stream`
+- `/2/tweets/sample/stream`
+- `/2/tweets/sample10/stream`
+
+You can force streaming on any endpoint with `-s`:
+
+```bash
+xurl -s /2/some/endpoint
+```
+
+---
+
+## Output Format
+
+All commands return **JSON** to stdout, pretty‑printed with syntax highlighting. The output structure matches the X API v2 response format. A typical response looks like:
+
+```json
+{
+  "data": {
+    "id": "1234567890",
+    "text": "Hello world!"
+  }
+}
+```
+
+Errors are also returned as JSON:
+
+```json
+{
+  "errors": [
+    {
+      "message": "Not authorized",
+      "code": 403
+    }
+  ]
+}
+```
+
+---
+
+## Common Workflows
+
+### Post with an image
+
+```bash
+# 1. Upload the image
+xurl media upload photo.jpg
+# 2. Copy the media_id from the response, then post
+xurl post "Check out this photo!" --media-id MEDIA_ID
+```
+
+### Reply to a conversation
+
+```bash
+# 1. Read the post to understand context
+xurl read https://x.com/user/status/1234567890
+# 2. Reply
+xurl reply 1234567890 "Here are my thoughts..."
+```
+
+### Search and engage
+
+```bash
+# 1. Search for relevant posts
+xurl search "topic of interest" -n 10
+# 2. Like an interesting one
+xurl like POST_ID_FROM_RESULTS
+# 3. Reply to it
+xurl reply POST_ID_FROM_RESULTS "Great point!"
+```
+
+### Check your activity
+
+```bash
+# See who you are
+xurl whoami
+# Check your mentions
+xurl mentions -n 20
+# Check your timeline
+xurl timeline -n 20
+```
+
+### Set up multiple apps
+
+```bash
+# App credentials must already be configured manually outside agent/LLM context.
+# Authenticate users on each pre-configured app
+xurl auth default prod
+xurl auth oauth2                       # authenticates on prod app
+
+xurl auth default staging
+xurl auth oauth2                       # authenticates on staging app
+
+# Switch between them
+xurl auth default prod alice           # prod app, alice user
+xurl --app staging /2/users/me         # one-off request against staging
+```
+
+---
+
+## Error Handling
+
+- Non‑zero exit code on any error.
+- API errors are printed as JSON to stdout (so you can still parse them).
+- Auth errors suggest re‑running `xurl auth oauth2` or checking your tokens.
+- If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via `/2/users/me`. If that fails, you'll see an auth error.
+
+---
+
+## Notes
+
+- **Rate limits:** The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints.
+- **Scopes:** OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run `xurl auth oauth2` to get a fresh token.
+- **Token refresh:** OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.
+- **Multiple apps:** Each app has its own isolated credentials and tokens. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `--app`.
+- **Multiple accounts:** You can authenticate multiple OAuth 2.0 accounts per app and switch between them with `--username` / `-u` or set a default with `xurl auth default APP USER`.
+- **Default user:** When no `-u` flag is given, xurl uses the default user for the active app (set via `xurl auth default`). If no default user is set, it uses the first available token.
+- **Token storage:** `~/.xurl` is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.