monomind 1.16.6 → 1.16.8

package/packages/@monomind/cli/.claude/skills/mastermind/routine-detail.md

@@ -0,0 +1,253 @@
+---
+name: mastermind-routine-detail
+description: Mastermind routine-detail — deep inspection and management of a single routine: trigger config (schedule/webhook), variables, concurrency/catchup policies, run history, webhook rotation, and revision tracking.
+type: domain-skill
+default_mode: auto
+---
+
+# Mastermind Routine Detail
+
+This skill is invoked by `mastermind:routine-detail` or directly via `/mastermind:routine-detail`.
+
+---
+
+## Inputs
+
+- `brain_context`: BRAIN CONTEXT block (injected by command, or loaded below if standalone)
+- `org_name`: org the routine belongs to (required)
+- `routine_id`: routine id/slug (required)
+- `action`: show | runs | config | variables | rotate-webhook | revisions
+- `days`: lookback window for run history (default 14)
+- `var_key`: variable key (for variables --set)
+- `var_value`: variable value
+- `caller`: command | master
+
+---
+
+## Trigger Types
+
+| Kind | Description |
+|------|-------------|
+| `schedule` | Cron expression — agent fires on schedule |
+| `webhook` | HTTP POST to generated endpoint; signed via signing_mode |
+
+## Signing Modes (webhook only)
+
+| Mode | Description |
+|------|-------------|
+| `none` | No signature verification |
+| `bearer` | Authorization: Bearer <token> header |
+| `hmac_sha256` | X-Hub-Signature-256 header (HMAC-SHA256 of body) |
+| `github_hmac` | GitHub-style HMAC — identical to hmac_sha256 + secret stored in mastermind:secrets |
+
+## Concurrency Policies
+
+| Policy | Behavior |
+|--------|----------|
+| `coalesce_if_active` | Skip trigger if a run is already active; record as coalesced |
+| `always_enqueue` | Always create a new run regardless of active runs |
+| `skip_if_active` | Silently discard trigger if a run is active |
+
+## Catchup Policies (schedule only)
+
+| Policy | Behavior |
+|--------|----------|
+| `skip_missed` | Missed scheduled runs are discarded |
+| `enqueue_missed_with_cap` | Enqueue missed runs up to `catchup_cap` (default 3) |
+
+---
+
+## Step 0 — Brain Load (standalone only)
+
+If `caller` is not "command", load brain context following _protocol.md Brain Load Procedure with namespace: `ops`.
+
+---
+
+## Step 1 — Load Routine Data
+
+```bash
+orgFile=".monomind/orgs/${org_name}.json"
+[ ! -f "$orgFile" ] && { echo "ERROR: Org '${org_name}' not found."; exit 1; }
+
+routinesFile=".monomind/orgs/${org_name}-routines.json"
+[ ! -f "$routinesFile" ] && { echo "ERROR: No routines file for org '$org_name'. Create routines first via /mastermind:runorg."; exit 1; }
+
+routineDef=$(jq -r --arg id "$routine_id" '(.routines // [])[] | select(.id == $id)' "$routinesFile")
+[ -z "$routineDef" ] && { echo "ERROR: Routine '$routine_id' not found in org '$org_name'."; exit 1; }
+
+stateFile=".monomind/orgs/${org_name}-state.json"
+days=${days:-14}
+cutoff=$(date -u -v-${days}d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "${days} days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+```
+
+---
+
+## Step 2 — Execute Action
+
+### show (default)
+
+```bash
+echo "ROUTINE DETAIL — $routine_id @ $org_name"
+echo "────────────────────────────────────────────────────────"
+
+echo "$routineDef" | jq -r '
+  "  ID:              \(.id)",
+  "  Name:            \(.name // "-")",
+  "  Assigned agent:  \(.agent_id // "(any)")",
+  "  Enabled:         \(.enabled // false)",
+  "",
+  "TRIGGER",
+  "  Kind:            \(.trigger.kind // "schedule")",
+  (if (.trigger.kind // "schedule") == "schedule" then
+    "  Cron:            \(.trigger.cron // "-")",
+    "  Catchup policy:  \(.catchup_policy // "skip_missed")",
+    "  Catchup cap:     \(.catchup_cap // 3 | tostring)"
+  else
+    "  Endpoint:        \(.trigger.endpoint // "(not generated)")",
+    "  Signing mode:    \(.trigger.signing_mode // "none")"
+  end),
+  "",
+  "CONCURRENCY",
+  "  Policy:          \(.concurrency_policy // "coalesce_if_active")",
+  "",
+  "VARIABLES",
+  "  Count:           \((.variables // {}) | length | tostring)"
+'
+
+# Show last run summary from state
+lastRun=$([ -f "$stateFile" ] && jq -r --arg id "$routine_id" '.routines[$id].last_run // "-"' "$stateFile" || echo "-")
+runCount=$([ -f "$stateFile" ] && jq -r --arg id "$routine_id" '.routines[$id].run_count // 0' "$stateFile" || echo "0")
+echo ""
+echo "  Last run:   $lastRun"
+echo "  Run count:  $runCount"
+```
+
+### runs
+
+```bash
+echo "RUN HISTORY — $routine_id (last ${days} days)"
+echo "────────────────────────────────────────────────────────"
+printf "%-26s %-12s %-8s %-14s %s\n" "TIMESTAMP" "STATUS" "TOKENS" "TRIGGER KIND" "COALESCED"
+echo "────────────────────────────────────────────────────────"
+
+runsFile=".monomind/orgs/${org_name}-routine-runs.jsonl"
+found=0
+
+if [ -f "$runsFile" ]; then
+  while IFS= read -r line; do
+    rid=$(echo "$line" | jq -r '.routine_id // ""')
+    [ "$rid" != "$routine_id" ] && continue
+    ts=$(echo "$line" | jq -r '.ts // ""')
+    [ -n "$cutoff" ] && [ "$ts" \< "$cutoff" ] && continue
+    st=$(echo "$line" | jq -r '.status // "-"')
+    tok=$(echo "$line" | jq -r '.tokens // "-"')
+    tkind=$(echo "$line" | jq -r '.trigger_kind // "schedule"')
+    coal=$(echo "$line" | jq -r 'if .coalesced then "yes" else "-" end')
+    printf "%-26s %-12s %-8s %-14s %s\n" "$ts" "$st" "$tok" "$tkind" "$coal"
+    found=$((found + 1))
+  done < "$runsFile"
+fi
+
+[ "$found" -eq 0 ] && echo "  No runs in the last $days days."
+```
+
+### config
+
+```bash
+echo "FULL CONFIG — $routine_id"
+echo "────────────────────────────────────────────────────────"
+echo "$routineDef" | jq 'del(.variables)'
+echo ""
+echo "TRIGGER DETAIL"
+echo "$routineDef" | jq '.trigger'
+```
+
+### variables
+
+```bash
+echo "VARIABLES — $routine_id"
+echo "────────────────────────────────────────────────────────"
+
+vars=$(echo "$routineDef" | jq -r '.variables // {} | to_entries[] | "  \(.key) = \(.value)"')
+[ -z "$vars" ] && echo "  No variables defined." || echo "$vars"
+
+# Set a variable if var_key provided
+if [ -n "$var_key" ]; then
+  [ -z "$var_value" ] && { echo "ERROR: --var-value required when setting a variable."; exit 1; }
+  tmp="${routinesFile}.tmp"
+  jq --arg id "$routine_id" --arg k "$var_key" --arg v "$var_value" \
+    '.routines = [(.routines // [])[] | if .id == $id then .variables[$k] = $v else . end]' \
+    "$routinesFile" > "$tmp" && mv "$tmp" "$routinesFile"
+  echo ""
+  echo "Set variable: $var_key = $var_value"
+fi
+```
+
+### rotate-webhook
+
+```bash
+triggerKind=$(echo "$routineDef" | jq -r '.trigger.kind // "schedule"')
+[ "$triggerKind" != "webhook" ] && { echo "ERROR: Routine '$routine_id' is not a webhook-triggered routine."; exit 1; }
+
+newToken=$(openssl rand -hex 24 2>/dev/null || python3 -c "import secrets; print(secrets.token_hex(24))")
+newEndpoint="/api/webhook/${org_name}/${routine_id}/${newToken}"
+ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+tmp="${routinesFile}.tmp"
+jq --arg id "$routine_id" --arg ep "$newEndpoint" --arg ts "$ts" \
+  '.routines = [(.routines // [])[] | if .id == $id then
+     .trigger.endpoint = $ep | .trigger.rotated_at = $ts
+   else . end]' \
+  "$routinesFile" > "$tmp" && mv "$tmp" "$routinesFile"
+
+echo "Webhook rotated for '$routine_id'"
+echo "  New endpoint: $newEndpoint"
+echo "  Rotated at:   $ts"
+echo ""
+echo "Update your webhook source to use the new endpoint."
+signingMode=$(echo "$routineDef" | jq -r '.trigger.signing_mode // "none"')
+[ "$signingMode" != "none" ] && echo "  Signing mode '$signingMode' is unchanged — re-generate the signing secret if required."
+```
+
+### revisions
+
+```bash
+revisionsFile=".monomind/orgs/${org_name}-routine-revisions.jsonl"
+echo "REVISIONS — $routine_id"
+echo "────────────────────────────────────────────────────────"
+
+if [ ! -f "$revisionsFile" ]; then
+  echo "  No revision history found."
+else
+  found=0
+  while IFS= read -r line; do
+    rid=$(echo "$line" | jq -r '.routine_id // ""')
+    [ "$rid" != "$routine_id" ] && continue
+    ts=$(echo "$line" | jq -r '.ts // ""')
+    who=$(echo "$line" | jq -r '.changed_by // "system"')
+    what=$(echo "$line" | jq -r '.change_summary // "-"')
+    printf "  [%s] by %-16s  %s\n" "$ts" "$who" "$what"
+    found=$((found + 1))
+  done < "$revisionsFile"
+  [ "$found" -eq 0 ] && echo "  No revisions found for '$routine_id'."
+fi
+```
+
+---
+
+## Step 3 — Return Output
+
+```yaml
+domain: ops
+status: complete
+action: <action>
+org: <org_name>
+routine_id: <routine_id>
+trigger_kind: <schedule|webhook>
+```
+
+---
+
+## Step 4 — Brain Write (standalone only)
+
+If `caller` is not "command", follow _protocol.md Brain Write Procedure for domain `ops`.

package/packages/@monomind/cli/.claude/skills/mastermind/routines.md

@@ -0,0 +1,203 @@
+---
+name: mastermind-routines
+description: Mastermind routines — schedule recurring tasks that trigger agent heartbeats on a cron-like schedule within a running org. Configure concurrency policy and catch-up behavior.
+type: domain-skill
+default_mode: confirm
+---
+
+# Mastermind Routines
+
+This skill is invoked by `mastermind:routines` or directly via `/mastermind:routines`.
+
+---
+
+## Inputs
+
+- `brain_context`: BRAIN CONTEXT block
+- `org_name`: org to manage routines for
+- `action`: list | add | pause | resume | remove | trigger
+- `routine_id`: slug of the routine (for pause/resume/remove/trigger)
+- `routine_name`: display name (for add)
+- `agent_id`: role id of the agent to trigger
+- `schedule`: cron expression (e.g. "0 9 * * 1-5" = weekdays at 9am)
+- `task_title`: task to create on each trigger
+- `context`: optional context passed to agent on each heartbeat
+- `concurrency`: coalesce_if_active | always_enqueue | skip_if_active (default: coalesce_if_active)
+- `catchup`: skip_missed | enqueue_missed_with_cap (default: skip_missed)
+- `caller`: command | master
+
+---
+
+## Step 0 — Brain Load (standalone only)
+
+If `caller` is not "command", load brain context following _protocol.md Brain Load Procedure with namespace: `ops`.
+
+---
+
+## Step 1 — Load Routines
+
+Routines are stored in `.monomind/orgs/<org_name>-routines.json`:
+
+```bash
+routinesFile=".monomind/orgs/${org_name}-routines.json"
+[ ! -f "$routinesFile" ] && echo '{"routines":[]}' > "$routinesFile"
+```
+
+---
+
+## Step 2 — Execute Action
+
+### list (default)
+
+Show all routines with their schedule and status:
+
+```bash
+jq -r '
+  (.routines // [])[] |
+  "[\(.id)] \(.name)  agent=\(.agent_id)  schedule=\"\(.schedule)\"  status=\(.status // "active")\n" +
+  "  task: \(.task_title)\n  concurrency: \(.concurrency)  catchup: \(.catchup)\n  last_run: \(.last_run // "never")  next_run: \(.next_run // "unknown")"
+' "$routinesFile" 2>/dev/null || echo "No routines defined."
+```
+
+Render as:
+```
+ROUTINES — org: <org_name>
+──────────────────────────────────────────────────────
+[weekly-report] Weekly Status Report
+  Agent:    boss  |  Schedule: 0 9 * * 1 (Mondays 9am)
+  Status:   active
+  Task:     "Compile weekly progress report from all agents"
+  Concurrency: coalesce_if_active  |  Catchup: skip_missed
+  Last run: 3 days ago  |  Next run: in 4 days
+
+[daily-content] Daily Content Draft
+  Agent:    content-writer  |  Schedule: 0 10 * * 1-5 (weekdays 10am)
+  Status:   active
+  Task:     "Draft one content piece for the content calendar"
+  Concurrency: skip_if_active  |  Catchup: skip_missed
+  Last run: yesterday  |  Next run: tomorrow 10am
+```
+
+### add
+
+Add a new routine and register a ScheduleWakeup via Claude's native scheduler:
+
+```bash
+routine_id=$(echo "$routine_name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | tr -s '-')
+tmp="${routinesFile}.tmp"
+jq --arg id "$routine_id" \
+   --arg name "$routine_name" \
+   --arg agent "$agent_id" \
+   --arg schedule "$schedule" \
+   --arg task "$task_title" \
+   --arg context "${context:-}" \
+   --arg concurrency "${concurrency:-coalesce_if_active}" \
+   --arg catchup "${catchup:-skip_missed}" \
+   '.routines += [{
+     "id":$id,"name":$name,"agent_id":$agent,"schedule":$schedule,
+     "task_title":$task,"context":$context,"concurrency":$concurrency,
+     "catchup":$catchup,"status":"active","created_at":(now|todate)
+   }]' \
+   "$routinesFile" > "$tmp" && mv "$tmp" "$routinesFile"
+echo "Routine added: $routine_id"
+echo "Schedule: $schedule"
+echo ""
+echo "NOTE: To activate this routine, use ScheduleWakeup with:"
+echo "  prompt: '/mastermind:routines --action trigger --org $org_name --routine-id $routine_id'"
+echo "  delaySeconds: <seconds until next scheduled run>"
+```
+
+After creating, use `ScheduleWakeup` to schedule the first trigger at the appropriate delay based on the cron expression.
+
+### trigger
+
+Manually trigger a routine immediately (same as a scheduled run):
+
+```bash
+routine=$(jq --arg id "$routine_id" '(.routines // [])[] | select(.id == $id)' "$routinesFile")
+rt_agent=$(echo "$routine" | jq -r '.agent_id')
+rt_task=$(echo "$routine" | jq -r '.task_title')
+rt_context=$(echo "$routine" | jq -r '.context // ""')
+rt_concurrency=$(echo "$routine" | jq -r '.concurrency')
+
+# Check concurrency policy
+stateFile=".monomind/orgs/${org_name}-state.json"
+[ ! -f "$stateFile" ] && echo '{"agents":{}}' > "$stateFile"
+agent_status=$(jq -r --arg a "$rt_agent" '.agents[$a].status // "idle"' "$stateFile")
+
+case "$rt_concurrency" in
+  skip_if_active)
+    [ "$agent_status" = "running" ] && { echo "Skipped: agent $rt_agent is already running (skip_if_active policy)"; exit 0; }
+    ;;
+  coalesce_if_active)
+    # Queue at most one pending run
+    ;;
+esac
+```
+
+Then invoke the heartbeat skill logic: create a task card for `rt_task`, trigger the agent heartbeat.
+
+Update routine's `last_run` and schedule next wakeup:
+
+```bash
+tmp="${routinesFile}.tmp"
+jq --arg id "$routine_id" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+   '.routines = [(.routines // [])[] | if .id == $id then .last_run = $ts else . end]' \
+   "$routinesFile" > "$tmp" && mv "$tmp" "$routinesFile"
+```
+
+### pause / resume
+
+```bash
+tmp="${routinesFile}.tmp"
+jq --arg id "$routine_id" --arg status "$action" \
+   '.routines = [(.routines // [])[] | if .id == $id then .status = $status else . end]' \
+   "$routinesFile" > "$tmp" && mv "$tmp" "$routinesFile"
+echo "Routine $routine_id set to: $action"
+```
+
+### remove
+
+```bash
+tmp="${routinesFile}.tmp"
+jq --arg id "$routine_id" '.routines = [(.routines // [])[] | select(.id != $id)]' \
+   "$routinesFile" > "$tmp" && mv "$tmp" "$routinesFile"
+echo "Routine $routine_id removed."
+```
+
+---
+
+## Concurrency Policies
+
+| Policy | Behavior |
+|--------|----------|
+| `coalesce_if_active` | If a run is already active, keep just one follow-up queued |
+| `always_enqueue` | Queue every trigger, even if routine is already running |
+| `skip_if_active` | Drop new triggers while a run is active |
+
+## Catch-up Policies
+
+| Policy | Behavior |
+|--------|----------|
+| `skip_missed` | Ignore windows missed while paused/down |
+| `enqueue_missed_with_cap` | Catch up missed windows in capped batches |
+
+---
+
+## Step 3 — Return Output
+
+```yaml
+domain: ops
+status: complete
+action: <action>
+org: <org_name>
+routine_id: <routine_id if applicable>
+routines_count: <N>
+routines_file: .monomind/orgs/<org_name>-routines.json
+```
+
+---
+
+## Step 4 — Brain Write (standalone only)
+
+If `caller` is not "command", follow _protocol.md Brain Write Procedure for domain `ops`.