--- name: ops-pocket description: Pocket voice-memo pipeline command center. Surfaces the watcher → triage → executor → notifier → bridges chain that turns Pocket-recorded voice memos into running Claude tasks, with WhatsApp + email notifications. Routes — status, setup, tasks, test, logs, restart, whatsapp on|off, email on|off. argument-hint: "[status|setup|tasks|test|logs [N]|restart|whatsapp on|off|email on|off]" allowed-tools: - Bash - Read - Grep - Glob - Skill - AskUserQuestion effort: low maxTurns: 25 --- # OPS ► POCKET Surfaces the Pocket voice-memo pipeline as a discoverable slash command. The pipeline was previously orphaned — 7 scripts, no entry point. This skill is the entry point. For the full architecture reference (every state file, every script, every failure mode) see [`STATUS.md`](./STATUS.md) sibling to this file. ## Runtime Context Before any route runs, resolve: 1. **State dir**: `${POCKET_STATE_DIR:-$HOME/.claude/state/pocket}`. Every file mentioned below is relative to this dir. 2. **Plugin root**: `${CLAUDE_PLUGIN_ROOT}` — used to invoke pipeline scripts under `scripts/`. 3. **Daemon health snapshot**: `${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/daemon-health.json` — surface its `pocket-*` service status if present. If `$POCKET_STATE_DIR` does not exist on disk, the pipeline has never been bootstrapped — route to `setup` automatically (no autoroute on `status` if the user explicitly asked for status). ## Routing table Parse `$ARGUMENTS` and route immediately. First token decides the route. | First arg | Route | | ---------------------- | --------------------------------------------------------------------------- | | (empty) / `status` | **Status dashboard** — daemon health + queue depths + cursors + counts | | `setup` | Delegate to `skills/setup/channels/pocket.md` if present; else inline steps | | `tasks` | Pending + in-progress + recently-completed task list | | `test` | End-to-end synthetic completion test (covered below) | | `logs [N]` | Tail N lines (default 50) of notifier + run + executor logs | | `restart` | Kickstart launchd notifier + (re)spawn `pocket-exec` tmux supervisor | | `whatsapp on` / `off` | Toggle WhatsApp self-chat sink | | `email on` / `off` | Toggle email self-mail sink | Anything else: print the routing table and exit. --- ## Route — `status` (default) The default route. Read state files, render a compact dashboard. **Read these — in parallel where possible:** ```bash STATE_DIR="${POCKET_STATE_DIR:-$HOME/.claude/state/pocket}" # Daemon plist liveness launchctl list com.claude-ops.pocket-activity-notifier 2>/dev/null \ | awk '/PID/{print "pid="$3} /LastExitStatus/{print "exit="$3}' # Supervisor tmux session tmux has-session -t pocket-exec 2>/dev/null && echo "tmux=up" || echo "tmux=down" tmux list-windows -t pocket-exec 2>/dev/null | wc -l # Queue depths (line counts) wc -l < "$STATE_DIR/pending-triage.jsonl" 2>/dev/null wc -l < "$STATE_DIR/tasks.jsonl" 2>/dev/null wc -l < "$STATE_DIR/spawn-ledger.jsonl" 2>/dev/null wc -l < "$STATE_DIR/supervisor-out-queue.jsonl" 2>/dev/null # Completed reports ls "$STATE_DIR/executor-results/"*.done.json 2>/dev/null | wc -l # Last pull cursor cat "$STATE_DIR/cursor.txt" 2>/dev/null # Last 3 notifications (from out-queue-sent.jsonl) tail -n 3 "$STATE_DIR/out-queue-sent.jsonl" 2>/dev/null # Per-component health for h in .activity-notifier-health .out-queue-health .email-bridge-health .health; do cat "$STATE_DIR/$h" 2>/dev/null done ``` **Output format (desktop):** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ OPS ► POCKET — [timestamp] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DAEMONS watcher [running|stalled] last tick [Xs ago] triage [running|idle] executor watchdog [running|stalled] tmux pocket-exec=[up|down] (N windows) activity-notifier [running|stalled] pid [N] out-queue [running|disabled|error] email-bridge [running|disabled|error] QUEUES pending-triage [N items] (awaiting ACT/SKIP decision) tasks.jsonl [N items] (canonical task store) spawn-ledger [N spawns] out-queue [N pending] executor-results [N .done.json] CURSORS watcher last pull [ISO timestamp from cursor.txt] last completion [latest .done.json mtime] CHANNELS whatsapp [on|off|misconfigured] chat_jid=[masked tail] email [on|off|misconfigured] to=[masked] LAST 3 NOTIFICATIONS [N. kind type | task_id | sent_at] ────────────────────────────────────────────────────── ``` **Mobile mode** (Rule 7 — `$SSH_CONNECTION`/`$SSH_CLIENT`/`$SSH_TTY` set OR `$OPS_MOBILE=1` OR `$COLUMNS<80`): plain text lines, no boxes, no emoji prefixes: ``` pocket: watcher running, exec tmux=up, notifier pid=N queues: triage 0, tasks 12 (3 active), out 0 last pull: 5m ago. last done: 12m ago. channels: whatsapp on, email off. ``` After the dashboard, use `AskUserQuestion` (max 4 — Rule 1) ONLY if there is something actionable (stalled daemon, pending-triage > 0, etc.). On a clean board, exit silently. --- ## Route — `setup` Delegate to the setup channel doc when it exists: ```bash SETUP_DOC="$CLAUDE_PLUGIN_ROOT/skills/setup/channels/pocket.md" [[ -f "$SETUP_DOC" ]] && cat "$SETUP_DOC" ``` If `pocket.md` does not exist, print the inline onboarding sequence: 1. Confirm `pocket-cli` (or equivalent Pocket API auth) is on PATH. 2. Drop a `whatsapp-config.json` and/or `email-config.json` under `$STATE_DIR` (see STATUS.md for schemas). 3. Run `bash $CLAUDE_PLUGIN_ROOT/scripts/install-pocket-notifier.sh` to register the launchd LaunchAgent. 4. Verify with `/ops:pocket status`. Per Rule 4 (background by default during setup) and Rule 2 (never delegate commands to the user) — run the install script via Bash with `run_in_background: true`. Per Rule 3, never auto-skip channel selection — if `whatsapp-config.json` and `email-config.json` are both missing, ask via `AskUserQuestion` which to configure first (`[WhatsApp]` / `[Email]` / `[Both]` / `[Skip]`). --- ## Route — `tasks` Render a single combined list. No `AskUserQuestion` — read-only by default. ```bash STATE_DIR="${POCKET_STATE_DIR:-$HOME/.claude/state/pocket}" # Pending triage (awaiting ACT/SKIP) tail -n 50 "$STATE_DIR/pending-triage.jsonl" 2>/dev/null # Live tasks (canonical store) tail -n 50 "$STATE_DIR/tasks.jsonl" 2>/dev/null # In-flight workers (windows in pocket-exec tmux, excluding _idle + supervisor) tmux list-windows -t pocket-exec -F '#{window_name}' 2>/dev/null \ | grep -vE '^(_idle|supervisor)$' # Recently completed (.done.json sorted by mtime, last 10) ls -t "$STATE_DIR/executor-results/"*.done.json 2>/dev/null | head -10 ``` Format: ``` PENDING TRIAGE (N) [id] [created] [title] ACTIVE TASKS (N) [task_id] [status] [title] [started] IN-FLIGHT WORKERS (N) [tmux window name] [up since] RECENTLY COMPLETED (last 10) [task_id] [duration] [report file] ``` --- ## Route — `test` (synthetic end-to-end) Smoke-tests the full notifier → out-queue → both bridges path **without** going through the watcher or triage. Same flow as the manual session-level test that was run when the notifier shipped. **Steps:** 1. **Pre-flight**: verify `$STATE_DIR/whatsapp-config.json` OR `email-config.json` has `enabled: true`. If neither: print `not configured — run /ops:pocket setup` and exit. 2. **Generate a synthetic task_id** like `test-$(date +%s)`. 3. **Append a tasks.jsonl entry** for the synthetic task (so the notifier can title-resolve it): ```bash echo "{\"task_id\":\"$TID\",\"title\":\"synthetic pocket test\",\"created_at\":\"$(date -u +%FT%TZ)\",\"verdict\":\"ACT\"}" \ >> "$STATE_DIR/tasks.jsonl" ``` 4. **Drop a synthetic `.done.json`** into `executor-results/`: ```bash cat > "$STATE_DIR/executor-results/$TID.done.json" < "$STATE_DIR/executor-results/$TID.out.md" ``` 5. **Manually invoke the notifier once** (don't wait 60s for launchd): ```bash "$CLAUDE_PLUGIN_ROOT/scripts/ops-pocket-activity-notifier.py" --once 2>&1 | tail -20 ``` (If `--once` is not supported, run the script with `POCKET_NOTIFIER_ONESHOT=1` env var, or just `python3 ops-pocket-activity-notifier.py`.) 6. **Drain both bridges** in parallel: ```bash "$CLAUDE_PLUGIN_ROOT/scripts/ops-pocket-out-queue.py" 2>&1 | tail -10 "$CLAUDE_PLUGIN_ROOT/scripts/ops-pocket-email-bridge.py" 2>&1 | tail -10 ``` 7. **Verify delivery** — for each enabled channel: - **WhatsApp**: tail `$STATE_DIR/out-queue-sent.jsonl` for an entry with the synthetic task_id. (Do NOT use `mcp__whatsapp__list_messages` — the bridge's own sent ledger is the source of truth.) - **Email**: tail `$STATE_DIR/email-bridge.log` for `SENT` on the synthetic task_id. 8. **Cleanup**: ```bash rm -f "$STATE_DIR/executor-results/$TID.done.json" \ "$STATE_DIR/executor-results/$TID.out.md" ``` Leave the `tasks.jsonl` line (append-only log; harmless). **Report:** ``` POCKET ► TEST task_id: [tid] whatsapp: [SENT|SKIPPED-disabled|FAIL: reason] email: [SENT|SKIPPED-disabled|FAIL: reason] duration: [Xs] ``` If any channel fails, surface the last error line from the corresponding `*.log` and `.health` file. --- ## Route — `logs [N]` ```bash N="${ARG_2:-50}" STATE_DIR="${POCKET_STATE_DIR:-$HOME/.claude/state/pocket}" for f in activity-notifier.log run.log executor.log out-queue.log email-bridge.log; do echo "==> $f <==" tail -n "$N" "$STATE_DIR/$f" 2>/dev/null || echo "(missing)" done ``` For Rule 7 mobile mode, default `N=20` and skip per-file headers. --- ## Route — `restart` ```bash # 1. Kickstart the launchd activity-notifier launchctl kickstart -k "gui/$(id -u)/com.claude-ops.pocket-activity-notifier" 2>&1 # 2. (Re)spawn the pocket-exec supervisor via the executor watchdog cron script "$CLAUDE_PLUGIN_ROOT/scripts/ops-cron-pocket-executor.py" 2>&1 | tail -10 ``` If the launchd label is missing (notifier never installed), prompt via `AskUserQuestion`: `[Install notifier now]` / `[Skip]`. On install: run `scripts/install-pocket-notifier.sh` (Rule 4: `run_in_background: true`). --- ## Route — `whatsapp on|off` and `email on|off` Both routes mutate a small JSON config file. Never overwrite the whole file — patch in place. ```bash STATE_DIR="${POCKET_STATE_DIR:-$HOME/.claude/state/pocket}" CFG="$STATE_DIR/whatsapp-config.json" # or email-config.json ACTION="${ARG_2}" # on | off mkdir -p "$STATE_DIR" if [[ ! -f "$CFG" ]]; then # Bootstrap empty config with enabled=false so subsequent `on` is meaningful. echo '{"enabled":false}' > "$CFG" fi case "$ACTION" in on) python3 -c "import json,sys,pathlib; p=pathlib.Path('$CFG'); d=json.loads(p.read_text()); d['enabled']=True; p.write_text(json.dumps(d,indent=2))" ;; off) python3 -c "import json,sys,pathlib; p=pathlib.Path('$CFG'); d=json.loads(p.read_text()); d['enabled']=False; p.write_text(json.dumps(d,indent=2))" ;; *) echo "usage: /ops:pocket {whatsapp|email} {on|off}"; exit 2 ;; esac # Echo new state cat "$CFG" ``` **Required keys per channel** (validated by `status`): - `whatsapp-config.json` — `chat_jid` (WhatsApp JID of the self-chat, e.g. `@s.whatsapp.net`). - `email-config.json` — `to` (self-email address). If `on` is requested but the required key is missing, switch state to `enabled: false` and route the user to `setup` via `AskUserQuestion`. --- ## Rule reminders - **Rule 1**: Max 4 options per `AskUserQuestion`. None of the routes above need more. - **Rule 2**: Never delegate commands to the user — every command runs through Bash. - **Rule 3**: Never auto-skip channels in `setup` — always ask explicitly. - **Rule 4**: Background by default in `setup` (`run_in_background: true`). - **Rule 5**: This skill performs NO destructive ops — no deletes, no terminates, no force-kills beyond `launchctl kickstart -k` (which is a graceful restart, not a wipe). - **Rule 6**: No outbound comms staged from this skill except the synthetic test message in `test`, which goes to the operator's OWN self-chat / self-email (already enabled by the user) — not to third parties. Per-message approval rule is satisfied by the test being a no-args opt-in. - **Rule 7**: Mobile mode renders plain text only — see `status` example. ## Native tool usage - `AskUserQuestion`: only when there is a real choice to make (stalled daemon → restart? missing channel config → bootstrap?). Never required on a green status. - `Skill`: `setup` route may delegate to the setup channel doc. ## See also - [`STATUS.md`](./STATUS.md) — full architecture: 8 scripts, every state file, lifecycle, troubleshooting. - `scripts/ops-cron-pocket-watcher.py`, `scripts/ops-pocket-triage.py`, `scripts/ops-cron-pocket-executor.py`, `scripts/ops-pocket-activity-notifier.py`, `scripts/ops-pocket-out-queue.py`, `scripts/ops-pocket-email-bridge.py`, `scripts/ops-pocket-whatsapp-bridge.py`. - `scripts/install-pocket-notifier.sh`, `scripts/com.claude-ops.pocket-activity-notifier.plist`. - `templates/pocket-supervisor-prompt.md` — the prompt the long-lived supervisor runs under.