--- name: watcher-creator description: Guide for creating agent-deck watchers conversationally. This skill should be used when users want to set up a new watcher (webhook, ntfy, github, slack, gmail) to route events to a conductor. It walks the user through selecting an adapter type, gathering required settings, emitting the exact `agent-deck watcher create` command to run, and the watcher.toml and clients.json entries that go with it. Not for writing your own webhook server, GitHub Actions workflows, building Slack apps or bots, Gmail filters, or setting up the conductor itself. --- # Watcher Creator ## Overview This skill guides users through setting up a new agent-deck watcher from scratch. A watcher listens for incoming events (webhooks, ntfy notifications, GitHub events, Slack messages, or Gmail messages) and routes them to the appropriate conductor session. The skill asks clarifying questions, collects required settings, and emits the exact CLI command and configuration files to create a working watcher. ## When to use Invoke this skill when a user says things like: - "I want to set up a new watcher" - "How do I connect GitHub webhooks to agent-deck?" - "Help me route Slack messages to a conductor" - "Create a watcher for my Gmail inbox" - "I need agent-deck to listen for ntfy notifications" ## Step-by-step conversational flow ### Step 1: Choose adapter type Ask the user which source they want to receive events from. Present the five options: 1. **webhook** - Generic HTTP POST webhook (any service that can send HTTP) 2. **ntfy** - ntfy.sh push notification topic 3. **github** - GitHub repository webhooks (issues, PRs, pushes) 4. **slack** - Slack messages via a Cloudflare Worker bridge to ntfy 5. **gmail** - Gmail inbox via Google Cloud Pub/Sub watch (not available from `watcher create` yet: see the gmail section) ### Step 2: Gather required settings for the chosen type Once the user picks a type, ask for the settings specific to that adapter (see the per-type sections below). Ask for each required setting one at a time to avoid overwhelming the user. Also ask: - **Watcher name**: A short lowercase identifier (e.g., `my-webhook`, `github-alerts`). This becomes the directory name under the effective watcher data dir (`${XDG_DATA_HOME:-$HOME/.local/share}/agent-deck/watcher` for new users; legacy `~/.agent-deck/watcher` remains in use when existing watcher state is present). - **Conductor**: Which conductor should receive the events by default (the `conductor` field in `clients.json`): the name `agent-deck conductor list` shows, not a session title. - **Group**: Which group the conductor session lives in (the `group` field in `clients.json`). ### Step 3: Emit the exact agent-deck watcher create command Show the user the full CLI command to run (see each type's **Create command**). Only emit commands — do not execute them. Run `create` before anyone writes a `watcher.toml` by hand: create writes `//watcher.toml` itself (chmod 600) and refuses a name whose `watcher.toml` already exists ("agent-deck never overwrites a watcher config"). It also fails for a name that is already registered; to change an existing watcher, edit its `watcher.toml` instead of re-running create. ### Step 4: Optional settings go under [source] in that watcher.toml The engine reads a watcher's adapter settings only from the `[source]` table of `${XDG_DATA_HOME:-$HOME/.local/share}/agent-deck/watcher//watcher.toml` (or the legacy `~/.agent-deck/watcher//watcher.toml` if agent-deck is already using legacy watcher state). All values are TOML strings, ports too. Settings create has no flag for (such as `bind`) are added there after create, for example: ```toml # Auto-generated by: agent-deck watcher create webhook [source] port = "18460" secret = "" bind = "127.0.0.1" ``` Routing is not read from this file: which conductor gets an event comes only from `clients.json` (Step 5). A file that does not parse stops the watcher from starting; after editing it, run `agent-deck watcher reload`. ### Step 5: Generate a clients.json entry Produce the JSON entry keyed by the expected sender, for `/clients.json`. The key format depends on adapter type: - webhook: the `X-Webhook-Sender` header value the sender will use (e.g., a service name) - ntfy: `ntfy:@` (e.g., `ntfy:my-topic@ntfy.sh`) - github: `@github.com`, the login of the user whose action fired the event; `*@github.com` routes every GitHub sender - slack: `slack:` (e.g., `slack:C0AABSF5GKD`) - gmail: the sender's email address (e.g., `user@example.com`) A key of the form `*@` is a wildcard for every sender at that domain; an exact key wins over a wildcard, and keys match case-insensitively. Entry format: ```json { "sender-key": { "conductor": "main-conductor", "group": "inbox", "name": "Human-readable label" } } ``` ### Step 6: Start the watcher ``` agent-deck watcher start ``` `watcher start` only marks the watcher running: the profile's watcher engine, in an agent-deck TUI or web process, starts it within seconds, and `agent-deck watcher reload` applies it now and reports what changed. `agent-deck watcher list` shows health and events per hour. `agent-deck watcher test ` routes a synthetic event from the fixed sender `test@synthetic.local`, so it says "Match: none" unless `clients.json` has a rule for that sender; it does not test the user's own sender key (`agent-deck watcher routes` lists the loaded rules). ## Supported watcher types and required fields ### webhook The webhook adapter runs a local HTTP server that accepts POST requests on `/webhook`. Any service that can POST to an HTTP endpoint can deliver events. **Required settings:** - `port` (string): TCP port to listen on. `watcher create webhook` requires `--port` and stores it under `[source]`; the adapter falls back to `"18460"` only when a `watcher.toml` has no port. Must be available on the local machine. **Secret:** `secret` (string) in `[source]`. `watcher create webhook` generates one and stores it in `watcher.toml` (chmod 600), or takes it from `$WEBHOOK_SECRET` or `--secret-file ` (chmod 600). Never put it on the command line. The secret must be at least 16 bytes. Every request must carry `X-Webhook-Timestamp: ` (within 5 minutes of the watcher's clock) and `X-Webhook-Signature-256: sha256=` (sender `""` when the header is absent), or it gets 401; each signature is accepted once and a replay gets 409. On a loopback bind only, `X-Webhook-Token: ` is accepted instead (it is the secret in clear and replayable by local processes; refused with 401 on any other bind). Requests with an `Origin` header get 403. `--no-secret` creates a watcher that accepts unsigned requests from local processes (not recommended). **Optional settings:** - `bind` (string): Bind address. Default is `"127.0.0.1"` (loopback only). On a loopback bind with no secret, requests must address it as `localhost`, `127.0.0.1` or `[::1]`. A non-loopback bind such as `"0.0.0.0"` only starts with a secret. **Sender key in clients.json:** Set the `X-Webhook-Sender` header from the sending service. Without it the sender is the connection's remote address (`ip:port`, a new port per connection), which no clients.json key matches reliably. The header is only trusted when the signature covers it, on a loopback token request, or from a local process when the watcher has no secret. **Create command:** ``` agent-deck watcher create webhook --name --port ``` Tell the user to sign with the secret read from the `watcher.toml` path create prints, never passing it as a command argument (other local users can read process arguments), like this: ```bash python3 - <<'EOF' import hashlib, hmac, re, time, urllib.request toml = open("/watcher.toml").read() secret = re.search(r'^secret = "(.*)"$', toml, re.M).group(1).encode() body, sender, ts = b'{"text":"hello"}', 'my-service', str(int(time.time())) sig = hmac.new(secret, (ts + '\n' + sender + '\n').encode() + body, hashlib.sha256).hexdigest() req = urllib.request.Request('http://127.0.0.1:/webhook', data=body, headers={ 'X-Webhook-Timestamp': ts, 'X-Webhook-Sender': sender, 'X-Webhook-Signature-256': 'sha256=' + sig}) print(urllib.request.urlopen(req).status) EOF ``` ### ntfy The ntfy adapter subscribes to an ntfy.sh topic via NDJSON streaming. It auto-reconnects with exponential backoff. **Required settings:** - `topic` (string): The ntfy topic name (e.g., `"my-alerts"`), from `--topic`, or `--random-topic` to generate a hard-to-guess one (not both). **Optional settings:** - `server` (string): ntfy server URL (`--server`). Default is `"https://ntfy.sh"`. - `token` (string): ntfy access token, from `$NTFY_TOKEN` or `--token-file ` (chmod 600), never a CLI argument; stored under `[source]`. On the public `https://ntfy.sh` anyone who knows a topic can read it and post fake events to it, so prefer `--random-topic` there, or an access-protected topic on your own ntfy server with a token. Create warns about a guessable topic on ntfy.sh without a token. **Sender key in clients.json:** `ntfy:@` (e.g., `ntfy:my-alerts@ntfy.sh`). **Create command:** ``` agent-deck watcher create ntfy --name --random-topic # or: NTFY_TOKEN= agent-deck watcher create ntfy --name --server --topic ``` ### github The GitHub adapter runs a local HTTP server that receives GitHub webhook POST requests on `/github` and verifies HMAC-SHA256 signatures. **Required settings:** - `secret` (string): The webhook secret configured in GitHub (Settings > Webhooks > Secret). Used for HMAC-SHA256 signature verification. It comes from `$GITHUB_WEBHOOK_SECRET` or `--secret-file ` (chmod 600); an inline `--secret` is refused. **Optional settings:** - `port` (string): TCP port to listen on (`--port`). Default is `"18461"`. - `bind` (string): Bind address. Default is `"127.0.0.1"`. Use a public address or set up a tunnel (e.g., ngrok) if GitHub must reach this machine. **Supported event types:** issues, pull_request, push. Unknown event types produce a generic event. **Sender key in clients.json:** `@github.com` (e.g., `octocat@github.com`), or `*@github.com` for every sender. **Create command:** ``` GITHUB_WEBHOOK_SECRET= agent-deck watcher create github --name # or: agent-deck watcher create github --name --secret-file ``` ### slack The Slack adapter subscribes to an ntfy topic that receives bridged Slack events from a Cloudflare Worker. It supports both v1 (plain text) and v2 (structured JSON) payloads. **Required settings:** - `topic` (string): The ntfy topic that the Cloudflare Worker posts Slack events to (`--topic`, or `--random-topic`). **Optional settings:** - `server` (string): ntfy server URL. Default is `"https://ntfy.sh"`. **Sender key in clients.json:** `slack:` (e.g., `slack:C0AABSF5GKD`). The channel ID comes from the Slack API or the channel URL in the Slack app. A v1 (plain text) payload carries no channel and arrives as `slack:unknown`. **Create command:** ``` agent-deck watcher create slack --name --topic ``` ### gmail The Gmail adapter delivers normalized events from a Gmail account via Google Cloud Pub/Sub. It requires initial OAuth setup and a Pub/Sub topic + subscription. **Not available yet:** `agent-deck watcher create` accepts only webhook, ntfy, github and slack, and the watcher engine does not run a gmail adapter, so there is no create command to emit and no `watcher oauth` command. Tell the user so instead of inventing one, and offer another route for the mail (for example a webhook watcher fed by a script that reads the inbox). **Settings the adapter reads (for when it ships):** - `topic` (string, required): Full Pub/Sub topic resource name: `projects//topics/`. - `subscription` (string, required): Full Pub/Sub subscription resource name: `projects//subscriptions/`. - `credentials_path` (string): Path to the OAuth client credentials JSON file (downloaded from Google Cloud Console). Default: `//credentials.json`. - `token_path` (string): Path to the persisted OAuth token JSON. Default: `//token.json`. - `labels` (string): Comma-separated Gmail label filter (e.g., `"INBOX,UNREAD"`). If absent, all messages pass through. - `account` (string): Informational Gmail address for display purposes. **Google-side pre-requisites:** 1. Create a Google Cloud project and enable the Gmail API and Cloud Pub/Sub API. 2. Create a Pub/Sub topic and subscription. 3. Grant the Gmail service account (`gmail-api-push@system.gserviceaccount.com`) the `Pub/Sub Publisher` role on the topic. 4. Download OAuth client credentials (Desktop app type) to `credentials.json`. 5. Place an OAuth `token.json` in the watcher directory (no agent-deck command creates it). **Sender key in clients.json:** The sender's email address (e.g., `contact@example.com`), or `*@example.com` for a whole domain. ## Validation checklist Before emitting the final `agent-deck watcher create` command, confirm: 1. **Name is valid:** Lowercase letters, numbers, and hyphens only. No spaces or special characters. The name must not already be registered or have a `watcher.toml` (`agent-deck watcher list`). 2. **Port is available (webhook/github):** The chosen port is not already in use by another watcher or service. 3. **Conductor exists:** The conductor name matches a configured conductor (check with `agent-deck conductor list`); events are delivered to its session titled `conductor-`, which must not be archived. 4. **Required settings collected:** All required fields for the chosen adapter type are present and non-empty. 5. **clients.json entry is correct:** The sender key format matches the adapter's normalization (e.g., `slack:CHANNEL_ID` not just `CHANNEL_ID`). ## Example walkthrough **User:** I want to set up a watcher for GitHub webhook events on my repo. **Skill response:** Great, let me help you set up a GitHub watcher. 1. What name should this watcher have? (e.g., `github-myrepo`) 2. What port should it listen on? (default: 18461) 3. What webhook secret will you use? (you'll configure the same value in GitHub Settings > Webhooks) 4. Which conductor should receive the events? (e.g., `main-conductor`) 5. Which group is that conductor in? (e.g., `dev`) **User:** Name: github-myrepo, port: 18461, secret: mysecret, conductor: main-conductor, group: dev **Skill response:** Here is your setup. Run this first; it writes `github-myrepo/watcher.toml` with the secret under `[source]` (chmod 600): ``` GITHUB_WEBHOOK_SECRET=mysecret agent-deck watcher create github --name github-myrepo --port 18461 ``` Add this entry to `${XDG_DATA_HOME:-$HOME/.local/share}/agent-deck/watcher/clients.json` (key is `@github.com`, or `*@github.com` for anyone acting on the repo), or the legacy watcher `clients.json` if that is the effective watcher data dir: ```json { "octocat@github.com": { "conductor": "main-conductor", "group": "dev", "name": "My GitHub Repo" } } ``` Then start the watcher: ``` agent-deck watcher start github-myrepo ``` Configure GitHub to send webhooks to `http://:18461/github`. ## Notes This skill is read-only (D-22): it guides you through configuration and emits commands to run, but it does NOT execute `agent-deck watcher create` itself. Copy and run the commands shown above in your terminal. The adapter types that run (webhook, ntfy, github, slack) route incoming events through the same engine. Events are matched against `/clients.json` by sender. Unknown senders are sent to triage. Install this skill to your pool with: ``` agent-deck watcher install-skill watcher-creator ```