crewly 1.5.22 → 1.6.0

package/config/skills/agent/core/schedule-followup/SKILL.md

@@ -0,0 +1,53 @@
+# schedule-followup
+
+Schedule a future check-in that creates a WorkItem for you or another agent.
+Use this when you need to **come back to something at a specific time** — most
+commonly to chase a response, verify an async result, or re-prompt an agent
+that went quiet.
+
+## When to use this vs other scheduling skills
+
+| Need | Use |
+|------|-----|
+| "Wake me up in 30 min to check X" (self) | `schedule-followup --in-minutes 30 --title "Check X"` |
+| "Check back on another agent at 9am" | `schedule-followup --fire-at 2026-04-24T09:00:00Z --target agent-session --title "..."` |
+| "Hourly for up to 3 tries, then give up" | `schedule-followup --cron "0 * * * *" --max-fires 3` |
+| "Whenever Rex goes idle, check progress" | `watch-for-event` (event-based, not this skill) |
+| Simple self-reminder with no team scope | `schedule-check` (older skill) |
+
+## Key invariants
+
+- Every followup is **team-scoped**. It shows up under `list-my-followups` and
+  can be cancelled by `name` via `cancel-followup`.
+- Every followup has a **finite lifetime**: either `maxFires` exhausts it, or
+  `maxIdleFires` (default 3) auto-cancels it after consecutive unproductive
+  fires.
+- If you forget to cancel a done followup, it will still terminate itself.
+  That's by design — we refuse to let followups live forever.
+
+## Examples
+
+```bash
+# One-shot self-reminder 30 minutes from now
+bash execute.sh --in-minutes 30 --title "Verify Rex delivered the draft"
+
+# One-shot absolute time, targeting Ella
+bash execute.sh --fire-at 2026-04-24T09:00:00Z \
+  --target crewly-marketing-ella-member-1 \
+  --title "Re-prompt Rex if no response yet"
+
+# Recurring with cap — will auto-stop after 3 tries even if you forget to cancel
+bash execute.sh --cron "0 * * * *" --max-fires 3 \
+  --title "Poll Rex hourly (give up after 3)"
+```
+
+## Output
+
+On success, returns the created `Trigger` object (JSON with `id`, `status`,
+`nextFireAt`, etc). Keep the `id` or `name` if you may need to cancel later.
+
+## Cancelling
+
+- By id: `cancel-followup --id <trigger-id>`
+- By name: `cancel-followup --name "followup:abc123"`
+- Or let `maxFires`/`maxIdleFires` do it automatically.

package/config/skills/agent/core/schedule-followup/execute.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+# Schedule a one-shot (or bounded-recurring) follow-up trigger that fires in
+# the future and drops a WorkItem into the pool for you or another agent.
+#
+# This is the "timer-based follow-up" pattern: you commit to checking back on
+# something at time T, and the system wakes you (or the target) when T arrives.
+# The trigger is scoped to your team so it shows up under list-my-followups,
+# and it auto-cancels after maxFires / maxIdleFires — there is no silent
+# forever-loop risk.
+#
+# Contrast with:
+#   - `schedule-check`   — self-timer that just messages you; no team scope.
+#   - orchestrator `create-cron` — for recurring org-level schedules.
+#
+# Supports CLI flags (preferred), legacy JSON, stdin pipe, or @filepath.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+CREWLY_HOME="${HOME}/.crewly"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  # Fire once, 30 minutes from now, target self
+  bash execute.sh --in-minutes 30 --title "Check Rex response"
+
+  # Fire once at a specific absolute time (ISO8601), target another agent
+  bash execute.sh --fire-at 2026-04-24T09:00:00Z --target crewly-marketing-ella-member-1 --title "Re-prompt Rex"
+
+  # Recurring with a hard cap — 3 tries, 1h apart
+  bash execute.sh --cron "0 * * * *" --max-fires 3 --title "Hourly Rex check"
+
+  # Legacy JSON
+  bash execute.sh '{"inMinutes":30,"title":"Check Rex","target":"ella"}'
+
+Options:
+  --in-minutes | -m   Fire once N minutes from now (mutually exclusive with --fire-at/--cron)
+  --fire-at          Fire once at ISO8601 datetime (e.g. 2026-04-24T09:00:00Z)
+  --cron             Cron expression for recurring fires (UTC by default)
+  --timezone         IANA timezone for cron (default: UTC)
+  --target           Agent session to receive the follow-up WorkItem (default: yourself)
+  --title     | -T   Title for the generated WorkItem (required)
+  --description     Longer description / context
+  --name             Stable name (used for cancel / dedup). Auto-generated if absent.
+  --max-fires        Stop after N fires (default: 1 for --in-minutes/--fire-at, unlimited for --cron)
+  --max-idle-fires   Auto-cancel after N consecutive fires that produced no work (default: 3)
+  --json      | -j   Raw JSON payload (same as legacy)
+  --help      | -h   Show this help
+EOF_USAGE
+}
+
+resolve_team_id() {
+  local session="${1:-${CREWLY_SESSION_NAME:-}}"
+  [ -z "$session" ] && return 1
+  local teams_dir="${CREWLY_HOME}/teams"
+  [ ! -d "$teams_dir" ] && return 1
+  for config in "$teams_dir"/*/config.json; do
+    [ -f "$config" ] || continue
+    local found
+    found=$(jq -r --arg s "$session" '.members[]? | select(.sessionName == $s) | "found"' "$config" 2>/dev/null | head -1)
+    if [ "$found" = "found" ]; then
+      basename "$(dirname "$config")"
+      return 0
+    fi
+  done
+  return 1
+}
+
+INPUT_JSON=""
+IN_MINUTES=""
+FIRE_AT=""
+CRON_EXPR=""
+TIMEZONE="UTC"
+TARGET=""
+TITLE=""
+DESCRIPTION=""
+NAME=""
+MAX_FIRES=""
+MAX_IDLE_FIRES="3"
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --in-minutes|-m)      IN_MINUTES="$2"; shift 2 ;;
+    --fire-at)            FIRE_AT="$2"; shift 2 ;;
+    --cron)               CRON_EXPR="$2"; shift 2 ;;
+    --timezone)           TIMEZONE="$2"; shift 2 ;;
+    --target)             TARGET="$2"; shift 2 ;;
+    --title|-T)           TITLE="$2"; shift 2 ;;
+    --description)        DESCRIPTION="$2"; shift 2 ;;
+    --name)               NAME="$2"; shift 2 ;;
+    --max-fires)          MAX_FIRES="$2"; shift 2 ;;
+    --max-idle-fires)     MAX_IDLE_FIRES="$2"; shift 2 ;;
+    --json|-j)            INPUT_JSON="$2"; shift 2 ;;
+    --help|-h)            print_usage; exit 0 ;;
+    --)                   shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then
+        INPUT_JSON="$1"; shift
+      else
+        echo '{"error":"Unknown argument: '"$1"'"}' >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
+# Legacy JSON → populate vars
+if [ -n "$INPUT_JSON" ]; then
+  IN_MINUTES=$(printf '%s' "$INPUT_JSON" | jq -r '.inMinutes // empty')
+  FIRE_AT=$(printf '%s' "$INPUT_JSON" | jq -r '.fireAt // empty')
+  CRON_EXPR=$(printf '%s' "$INPUT_JSON" | jq -r '.cron // empty')
+  TIMEZONE=$(printf '%s' "$INPUT_JSON" | jq -r '.timezone // "UTC"')
+  TARGET=$(printf '%s' "$INPUT_JSON" | jq -r '.target // empty')
+  TITLE=$(printf '%s' "$INPUT_JSON" | jq -r '.title // empty')
+  DESCRIPTION=$(printf '%s' "$INPUT_JSON" | jq -r '.description // empty')
+  NAME=$(printf '%s' "$INPUT_JSON" | jq -r '.name // empty')
+  MAX_FIRES=$(printf '%s' "$INPUT_JSON" | jq -r '.maxFires // empty')
+  MAX_IDLE_FIRES=$(printf '%s' "$INPUT_JSON" | jq -r '.maxIdleFires // "3"')
+fi
+
+# Validation
+[ -z "$TITLE" ] && { echo '{"error":"--title is required"}' >&2; exit 1; }
+
+TIMING_COUNT=0
+[ -n "$IN_MINUTES" ] && TIMING_COUNT=$((TIMING_COUNT + 1))
+[ -n "$FIRE_AT" ] && TIMING_COUNT=$((TIMING_COUNT + 1))
+[ -n "$CRON_EXPR" ] && TIMING_COUNT=$((TIMING_COUNT + 1))
+if [ "$TIMING_COUNT" -ne 1 ]; then
+  echo '{"error":"Exactly one of --in-minutes, --fire-at, or --cron must be provided"}' >&2
+  exit 1
+fi
+
+# Default target = self
+[ -z "$TARGET" ] && TARGET="${CREWLY_SESSION_NAME:-}"
+[ -z "$TARGET" ] && { echo '{"error":"No --target and CREWLY_SESSION_NAME is unset"}' >&2; exit 1; }
+
+# Resolve owning team (for team-scoped listing / cancel)
+TEAM_ID=$(resolve_team_id || true)
+
+# Auto-generate name if caller didn't supply one (stable per target+title)
+if [ -z "$NAME" ]; then
+  HASH=$(printf '%s|%s' "$TARGET" "$TITLE" | shasum -a 1 | awk '{print substr($1,1,8)}')
+  NAME="followup:${HASH}"
+fi
+
+# Build TimeTriggerConfig
+CONFIG_JSON=""
+if [ -n "$IN_MINUTES" ]; then
+  DELAY_MS=$((IN_MINUTES * 60 * 1000))
+  CONFIG_JSON=$(jq -n --argjson d "$DELAY_MS" '{type:"time", delayMs:$d}')
+  # Sensible default for one-shot
+  [ -z "$MAX_FIRES" ] && MAX_FIRES="1"
+elif [ -n "$FIRE_AT" ]; then
+  CONFIG_JSON=$(jq -n --arg f "$FIRE_AT" '{type:"time", fireAt:$f}')
+  [ -z "$MAX_FIRES" ] && MAX_FIRES="1"
+else
+  CONFIG_JSON=$(jq -n --arg c "$CRON_EXPR" --arg tz "$TIMEZONE" '{type:"time", cronExpression:$c, timezone:$tz}')
+  # Recurring: no implicit maxFires cap (caller should set one for followup hygiene)
+fi
+
+# Build TriggerAction.createWorkItem
+WI_JSON=$(jq -n \
+  --arg type "delegate" \
+  --arg owner "team_lead" \
+  --arg target "$TARGET" \
+  --arg title "$TITLE" \
+  --arg description "$DESCRIPTION" \
+  '{type:$type, owner:$owner, target:$target, title:$title}
+   + (if $description != "" then {description:$description} else {} end)')
+
+ACTION_JSON=$(jq -n --argjson wi "$WI_JSON" '{createWorkItem: $wi}')
+
+# Assemble final CreateTriggerInput
+BODY=$(jq -n \
+  --arg type "time" \
+  --argjson config "$CONFIG_JSON" \
+  --argjson action "$ACTION_JSON" \
+  --arg createdBy "system" \
+  --arg name "$NAME" \
+  --arg teamId "$TEAM_ID" \
+  --arg maxFires "$MAX_FIRES" \
+  --arg maxIdle "$MAX_IDLE_FIRES" \
+  '{type:$type, config:$config, action:$action, createdBy:$createdBy, name:$name}
+   + (if $teamId != "" then {teamId:$teamId} else {} end)
+   + (if $maxFires != "" then {maxFires:($maxFires|tonumber)} else {} end)
+   + (if $maxIdle != "" then {maxIdleFires:($maxIdle|tonumber)} else {} end)')
+
+RESP=$(api_call POST "/triggers" "$BODY")
+echo "$RESP"

package/config/skills/agent/core/schedule-followup/execute.test.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Validation tests for schedule-followup skill.
+# End-to-end behaviour (actually POSTing to /api/triggers) is verified by the
+# backend integration tests; here we cover argument parsing + guard rails.
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0
+FAIL=0
+
+assert_contains() {
+  local test_name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -q -- "$needle"; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    echo "  ✗ ${test_name}"
+    echo "    expected to contain: ${needle}"
+    echo "    got: ${haystack}"
+  fi
+}
+
+echo "=== schedule-followup tests ==="
+
+echo ""
+echo "--- Required args ---"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --in-minutes 30 2>&1) || true
+assert_contains "Missing --title rejected" "title is required" "$OUTPUT"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --title "Check Rex" 2>&1) || true
+assert_contains "No timing spec rejected" "one of --in-minutes" "$OUTPUT"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --title "Check" --in-minutes 30 --fire-at "2026-01-01T00:00:00Z" 2>&1) || true
+assert_contains "Conflicting timing specs rejected" "one of --in-minutes" "$OUTPUT"
+
+echo ""
+echo "--- Help ---"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --help 2>&1) || true
+assert_contains "Help lists --in-minutes" -- "--in-minutes" "$OUTPUT"
+assert_contains "Help lists --fire-at" -- "--fire-at" "$OUTPUT"
+assert_contains "Help lists --cron" -- "--cron" "$OUTPUT"
+
+echo ""
+echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
+[ $FAIL -eq 0 ]

package/config/skills/agent/core/watch-for-event/SKILL.md

@@ -0,0 +1,60 @@
+# watch-for-event
+
+Subscribe to a system event (like `agent:idle` or `task:completed`) and create
+a WorkItem for yourself or another agent every time it fires. Use this when
+your follow-up should be **reactive to what Rex/the system does**, not tied to
+a wall-clock time.
+
+## When to use this vs `schedule-followup`
+
+| Need | Use |
+|------|-----|
+| "Whenever Rex goes idle, check progress" | `watch-for-event --event-type agent:idle --filter-session rex-session` |
+| "Alert me when any task completes" | `watch-for-event --event-type task:completed` |
+| "Poll at 9am tomorrow" | `schedule-followup --fire-at ...` (time, not event) |
+| "Check every hour up to 3 times" | `schedule-followup --cron "0 * * * *" --max-fires 3` |
+
+## Common event types
+
+| Event | When it fires |
+|-------|---------------|
+| `agent:idle` | An agent's `workingStatus` flipped to `idle` |
+| `agent:active` | An agent started working |
+| `agent:inactive` | An agent stopped heartbeating |
+| `task:completed` | A task was marked done |
+| `task:failed` | A task failed |
+
+See `types/event-bus.types.ts` for the authoritative list.
+
+## Filtering
+
+By default the watcher fires on **every** occurrence of the event type. Narrow
+it with `--filter-session` (most common) to only fire for one specific agent,
+or `--filter-json` for arbitrary payload matching.
+
+```bash
+# Only when THIS agent goes idle
+bash execute.sh --event-type agent:idle \
+  --filter-session crewly-marketing-rex-member-1 \
+  --title "Rex idle — verify Rex task"
+
+# Match a richer filter shape
+bash execute.sh --event-type task:completed \
+  --filter-json '{"missionId":"q2-growth"}' \
+  --title "Q2 mission task landed"
+```
+
+## Key invariants
+
+- Every watcher is **team-scoped**, listed under `list-my-followups`,
+  cancellable by `name` via `cancel-followup`.
+- **No implicit upper bound on fires**: if you set `--max-fires`, great.
+  Otherwise rely on `--max-idle-fires` (default 3) to auto-cancel once the
+  watcher stops producing useful work.
+- A watcher that fires 20× in a minute because an agent is flapping is YOUR
+  responsibility to handle (either narrower filter, or cap with max-fires).
+
+## Cancelling
+
+- Explicit: `cancel-followup --id <trigger-id>` or `--name <name>`
+- Automatic: `maxFires` exhausts, or `maxIdleFires` trips.

package/config/skills/agent/core/watch-for-event/execute.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# Subscribe to an EventBus event (e.g. `agent:idle`, `task:completed`) and
+# create a WorkItem for you or another agent when it fires.
+#
+# This is the "event-based follow-up" pattern: you commit to reacting to a
+# specific signal, rather than polling on a timer. Most common use is "when
+# Rex stops working, check whether the task is done and if not, re-prompt".
+#
+# Known event types (see types/event-bus.types.ts for the authoritative list):
+#   agent:idle        — an agent entered idle state
+#   agent:active      — an agent started working
+#   agent:inactive    — an agent was marked inactive (stopped heartbeating)
+#   task:completed    — a task was marked done
+#   task:failed       — a task failed
+#
+# Supports CLI flags (preferred), legacy JSON, stdin pipe, or @filepath.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+CREWLY_HOME="${HOME}/.crewly"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  # Watch Rex for idle and route a follow-up WorkItem back to yourself
+  bash execute.sh --event-type agent:idle \
+    --filter-session crewly-marketing-rex-member-1 \
+    --title "Rex went idle — check task status"
+
+  # Watch for any task:completed event, fire-and-done after 1 hit
+  bash execute.sh --event-type task:completed --max-fires 1 --title "Task done — ack"
+
+Options:
+  --event-type      Event type to watch (required). Examples: agent:idle, task:completed, task:failed.
+  --filter-session  Only fire when the event's sessionName matches this value
+  --filter-json     Raw JSON filter object (advanced; merged with --filter-session)
+  --target          Session that should receive the generated WorkItem (default: yourself)
+  --title     | -T  Title for the generated WorkItem (required)
+  --description     Longer description / context
+  --name            Stable name for cancel/dedup. Auto-generated if absent.
+  --max-fires       Stop after N fires (default: unlimited — use --max-idle-fires as safety)
+  --max-idle-fires  Auto-cancel after N consecutive unproductive fires (default: 3)
+  --json      | -j  Raw JSON payload (legacy)
+  --help      | -h  Show this help
+EOF_USAGE
+}
+
+resolve_team_id() {
+  local session="${1:-${CREWLY_SESSION_NAME:-}}"
+  [ -z "$session" ] && return 1
+  local teams_dir="${CREWLY_HOME}/teams"
+  [ ! -d "$teams_dir" ] && return 1
+  for config in "$teams_dir"/*/config.json; do
+    [ -f "$config" ] || continue
+    local found
+    found=$(jq -r --arg s "$session" '.members[]? | select(.sessionName == $s) | "found"' "$config" 2>/dev/null | head -1)
+    if [ "$found" = "found" ]; then
+      basename "$(dirname "$config")"
+      return 0
+    fi
+  done
+  return 1
+}
+
+INPUT_JSON=""
+EVENT_TYPE=""
+FILTER_SESSION=""
+FILTER_JSON=""
+TARGET=""
+TITLE=""
+DESCRIPTION=""
+NAME=""
+MAX_FIRES=""
+MAX_IDLE_FIRES="3"
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --event-type)         EVENT_TYPE="$2"; shift 2 ;;
+    --filter-session)     FILTER_SESSION="$2"; shift 2 ;;
+    --filter-json)        FILTER_JSON="$2"; shift 2 ;;
+    --target)             TARGET="$2"; shift 2 ;;
+    --title|-T)           TITLE="$2"; shift 2 ;;
+    --description)        DESCRIPTION="$2"; shift 2 ;;
+    --name)               NAME="$2"; shift 2 ;;
+    --max-fires)          MAX_FIRES="$2"; shift 2 ;;
+    --max-idle-fires)     MAX_IDLE_FIRES="$2"; shift 2 ;;
+    --json|-j)            INPUT_JSON="$2"; shift 2 ;;
+    --help|-h)            print_usage; exit 0 ;;
+    --)                   shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then
+        INPUT_JSON="$1"; shift
+      else
+        echo '{"error":"Unknown argument: '"$1"'"}' >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
+if [ -n "$INPUT_JSON" ]; then
+  EVENT_TYPE=$(printf '%s' "$INPUT_JSON" | jq -r '.eventType // empty')
+  FILTER_SESSION=$(printf '%s' "$INPUT_JSON" | jq -r '.filterSession // empty')
+  FILTER_JSON=$(printf '%s' "$INPUT_JSON" | jq -rc '.filter // empty')
+  TARGET=$(printf '%s' "$INPUT_JSON" | jq -r '.target // empty')
+  TITLE=$(printf '%s' "$INPUT_JSON" | jq -r '.title // empty')
+  DESCRIPTION=$(printf '%s' "$INPUT_JSON" | jq -r '.description // empty')
+  NAME=$(printf '%s' "$INPUT_JSON" | jq -r '.name // empty')
+  MAX_FIRES=$(printf '%s' "$INPUT_JSON" | jq -r '.maxFires // empty')
+  MAX_IDLE_FIRES=$(printf '%s' "$INPUT_JSON" | jq -r '.maxIdleFires // "3"')
+fi
+
+[ -z "$EVENT_TYPE" ] && { echo '{"error":"--event-type is required"}' >&2; exit 1; }
+[ -z "$TITLE" ] && { echo '{"error":"--title is required"}' >&2; exit 1; }
+
+[ -z "$TARGET" ] && TARGET="${CREWLY_SESSION_NAME:-}"
+[ -z "$TARGET" ] && { echo '{"error":"No --target and CREWLY_SESSION_NAME is unset"}' >&2; exit 1; }
+
+TEAM_ID=$(resolve_team_id || true)
+
+if [ -z "$NAME" ]; then
+  HASH=$(printf '%s|%s|%s' "$EVENT_TYPE" "$TARGET" "$TITLE" | shasum -a 1 | awk '{print substr($1,1,8)}')
+  NAME="watch:${HASH}"
+fi
+
+# Build the filter object. --filter-session is sugar for {sessionName: "..."}.
+FILTER_OBJ=""
+if [ -n "$FILTER_JSON" ]; then
+  FILTER_OBJ="$FILTER_JSON"
+fi
+if [ -n "$FILTER_SESSION" ]; then
+  if [ -n "$FILTER_OBJ" ]; then
+    FILTER_OBJ=$(printf '%s' "$FILTER_OBJ" | jq --arg s "$FILTER_SESSION" '. + {sessionName:$s}')
+  else
+    FILTER_OBJ=$(jq -n --arg s "$FILTER_SESSION" '{sessionName:$s}')
+  fi
+fi
+
+if [ -n "$FILTER_OBJ" ]; then
+  CONFIG_JSON=$(jq -n --arg et "$EVENT_TYPE" --argjson f "$FILTER_OBJ" '{type:"signal", eventType:$et, filter:$f}')
+else
+  CONFIG_JSON=$(jq -n --arg et "$EVENT_TYPE" '{type:"signal", eventType:$et}')
+fi
+
+WI_JSON=$(jq -n \
+  --arg type "delegate" \
+  --arg owner "team_lead" \
+  --arg target "$TARGET" \
+  --arg title "$TITLE" \
+  --arg description "$DESCRIPTION" \
+  '{type:$type, owner:$owner, target:$target, title:$title}
+   + (if $description != "" then {description:$description} else {} end)')
+
+ACTION_JSON=$(jq -n --argjson wi "$WI_JSON" '{createWorkItem: $wi}')
+
+BODY=$(jq -n \
+  --arg type "signal" \
+  --argjson config "$CONFIG_JSON" \
+  --argjson action "$ACTION_JSON" \
+  --arg createdBy "system" \
+  --arg name "$NAME" \
+  --arg teamId "$TEAM_ID" \
+  --arg maxFires "$MAX_FIRES" \
+  --arg maxIdle "$MAX_IDLE_FIRES" \
+  '{type:$type, config:$config, action:$action, createdBy:$createdBy, name:$name}
+   + (if $teamId != "" then {teamId:$teamId} else {} end)
+   + (if $maxFires != "" then {maxFires:($maxFires|tonumber)} else {} end)
+   + (if $maxIdle != "" then {maxIdleFires:($maxIdle|tonumber)} else {} end)')
+
+RESP=$(api_call POST "/triggers" "$BODY")
+echo "$RESP"

package/config/skills/agent/core/watch-for-event/execute.test.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Validation tests for watch-for-event skill.
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0
+FAIL=0
+
+assert_contains() {
+  local test_name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -q -- "$needle"; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    echo "  ✗ ${test_name}"
+    echo "    expected to contain: ${needle}"
+    echo "    got: ${haystack}"
+  fi
+}
+
+echo "=== watch-for-event tests ==="
+
+echo ""
+echo "--- Required args ---"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --title "Check" 2>&1) || true
+assert_contains "Missing --event-type rejected" "event-type is required" "$OUTPUT"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --event-type agent:idle 2>&1) || true
+assert_contains "Missing --title rejected" "title is required" "$OUTPUT"
+
+echo ""
+echo "--- Help ---"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" --help 2>&1) || true
+assert_contains "Help lists --event-type" -- "--event-type" "$OUTPUT"
+assert_contains "Help lists --filter-session" -- "--filter-session" "$OUTPUT"
+assert_contains "Help mentions agent:idle example" "agent:idle" "$OUTPUT"
+
+echo ""
+echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
+[ $FAIL -eq 0 ]