---

name: mastermind-monitor description: "Mastermind monitor — long-running executor that watches Linear, GitHub, Monotask boards and folders for new tasks, claims and runs them with the right agent, and reports progress." type: domain-skill default_mode: confirm

Mastermind Monitor

Invoked via mastermind:monitor or /mastermind-monitor.

A monitor is a named, forever-running task executor. It polls one or more task sources on a configurable interval, claims matching tasks, hands them off to a Claude agent for execution, posts back results as comments/status updates, and self-reschedules via ScheduleWakeup.

---

CLI Flags

--action   start | stop | pause | resume | status | list | add-source | tick
--name     monitor name (slug, e.g. "dev-agent")
--source   linear | github | monotask | filesystem
--interval poll interval in seconds (default: 120)
--user     filter by assignee username/email (can be repeated)
--state    filter by task state/status (can be repeated, default: open/todo)
--max-concurrent  max tasks in flight (default: 1)
--agent    agent type to execute tasks (default: coder)
--project  monotask project/board name, or gh repo (org/repo)
--team     Linear team ID or slug
--folder   filesystem folder path to watch (for source=filesystem)
--label    filter by label (can be repeated)
--caller   command | master (internal — skip brain load if "command")

---

Step 0 — Brain Load (standalone only)

If caller is not "command", load brain context following mastermind-protocol/SKILL.md Brain Load Procedure with namespace: ops.

---

Step 1 — Resolve Monitor Config Directory

MONITOR_DIR=".monomind/monitor"
mkdir -p "$MONITOR_DIR"

---

Step 2 — Dispatch by Action

list (default when no --action)

echo "MONITORS"
echo "────────────────────────────────────────"
for f in "$MONITOR_DIR"/*.json; do
  [ -f "$f" ] || continue
  jq -r '
    "[\(.name)]  status=\(.status // "active")  interval=\(.poll_interval)s  agent=\(.agent_type)
    sources: \([(.sources // [])[].type] | join(", "))
    last_tick: \(.last_tick // "never")  tasks_done: \(.stats.done // 0)  tasks_failed: \(.stats.failed // 0)"
  ' "$f"
  echo ""
done

---

start

Creates a new monitor config and triggers the first tick.

Required: --name

cfg="$MONITOR_DIR/${name}.json"
if [ -f "$cfg" ]; then
  echo "Monitor '$name' already exists. Use --action resume to restart it."
  exit 0
fi

cat > "$cfg" <<EOF
{
  "name": "${name}",
  "status": "active",
  "poll_interval": ${interval:-120},
  "agent_type": "${agent:-coder}",
  "max_concurrent": ${max_concurrent:-1},
  "sources": [],
  "users": [],
  "states": [],
  "labels": [],
  "stats": { "done": 0, "failed": 0, "retried": 0, "total_claimed": 0 },
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "last_tick": null
}
EOF

echo "Monitor '$name' created."
echo "Add sources with: /mastermind-monitor --action add-source --name $name --source linear ..."
echo "Then start the tick loop."

After creating the config, if at least one source was provided (via --source + related flags), also run the add-source logic for each provided source before the loop starts.

Then immediately call ScheduleWakeup with:

• delaySeconds: 10 (first tick almost immediately)
• prompt: /mastermind-monitor --action tick --name <name>
• reason: First tick for monitor: <name>

---

stop

cfg="$MONITOR_DIR/${name}.json"
[ ! -f "$cfg" ] && echo "Monitor '$name' not found." && exit 1
tmp="${cfg}.tmp"
jq '.status = "stopped"' "$cfg" > "$tmp" && mv "$tmp" "$cfg"
echo "Monitor '$name' stopped. It will not reschedule after the current tick finishes."

---

pause / resume

cfg="$MONITOR_DIR/${name}.json"
[ ! -f "$cfg" ] && echo "Monitor '$name' not found." && exit 1
tmp="${cfg}.tmp"
new_status=$([ "$action" = "pause" ] && echo "paused" || echo "active")
jq --arg s "$new_status" '.status = $s' "$cfg" > "$tmp" && mv "$tmp" "$cfg"
echo "Monitor '$name' is now: $new_status"
[ "$action" = "resume" ] && echo "Scheduling next tick..." # then call ScheduleWakeup

If action=resume, call ScheduleWakeup:

• delaySeconds: 10
• prompt: /mastermind-monitor --action tick --name <name>
• reason: Resuming monitor: <name>

---

status

cfg="$MONITOR_DIR/${name}.json"
state_file="$MONITOR_DIR/${name}-state.json"
[ ! -f "$cfg" ] && echo "Monitor '$name' not found." && exit 1

jq -r '
  "MONITOR: \(.name)",
  "Status:  \(.status)",
  "Agent:   \(.agent_type)  |  Interval: \(.poll_interval)s  |  Max concurrent: \(.max_concurrent)",
  "Last tick: \(.last_tick // "never")",
  "",
  "Stats:",
  "  Claimed: \(.stats.total_claimed)  Done: \(.stats.done)  Failed: \(.stats.failed)  Retried: \(.stats.retried)",
  "",
  "Sources (\(.sources | length)):"
' "$cfg"

jq -r '(.sources // [])[] | "  [\(.type)] \(.filter | to_entries | map("\(.key)=\(.value)") | join("  "))"' "$cfg"

if [ -f "$state_file" ]; then
  in_flight=$(jq '.in_flight // [] | length' "$state_file" 2>/dev/null || echo 0)
  echo ""
  echo "In-flight tasks: $in_flight"
  jq -r '.in_flight[]? |
    "  [\(.source_type):\(.external_id)] claimed_at=\(.claimed_at) retry=\(.retry_count) last_failure=\(.last_failure // "n/a")"' \
    "$state_file" 2>/dev/null
fi

---

add-source

Appends a new source adapter config to an existing monitor.

Required: --name, --source

cfg="$MONITOR_DIR/${name}.json"
[ ! -f "$cfg" ] && echo "Monitor '$name' not found. Run --action start first." && exit 1

Build the source object based on --source:

linear:

{
  "type": "linear",
  "filter": {
    "team": "<--team value>",
    "assignees": ["<--user values>"],
    "states": ["<--state values, default: Todo>"],
    "labels": ["<--label values>"],
    "project": "<--project value if given>"
  }
}

github:

{
  "type": "github",
  "filter": {
    "repo": "<--project value, e.g. org/repo>",
    "assignee": "<--user value>",
    "labels": ["<--label values>"],
    "state": "<--state value, default: open>",
    "type": "issue"
  }
}

monotask:

{
  "type": "monotask",
  "filter": {
    "board": "<--project value>",
    "column": "<--state value, default: Todo>",
    "label": "<--label value, default: role:ai-agent>"
  }
}

filesystem:

{
  "type": "filesystem",
  "filter": {
    "folder": "<--folder value>",
    "glob": "*.task",
    "user": "<--user value>"
  }
}

Repeated-flag parsing rule: When --user, --state, or --label is specified multiple times, collect the values into space-separated shell variables $users, $states, $labels (e.g. users="alice bob" from --user alice --user bob). Single-occurrence flags (--team, --project, --folder) map to $team, $project, $folder directly.

Linear multi-assignee: The Linear MCP tool (mcp__claude_ai_Linear__list_issues) does not support multiple assignees in a single query. When $users contains more than one value, loop over each user and merge results client-side before dedup filtering. For simplicity in v1, only filter.assignees[0] is sent per query cycle — document this limitation to users.

Before calling any mcp__claude_ai_Linear__* tool, confirm availability with ToolSearch (select:mcp__claude_ai_Linear__list_issues,mcp__claude_ai_Linear__save_issue,mcp__claude_ai_Linear__save_comment) and load the schema. If the Linear MCP server is not registered, skip the Linear source for this tick with a warning.

Build and append the source object using jq -n — construct the JSON from flags, then append:

# Build src_json based on --source type:
# Repeated flags collected as space-separated: $users, $states, $labels
# Derive singular $user / $state / $label from first value (adapters that take one value)
user="${users%% *}"
state="${states%% *}"
label="${labels%% *}"

case "$source" in
  linear)
    assignees_json=$([ -n "$users"  ] && printf '%s\n' $users  | jq -R . | jq -sc '.' || echo '[]')
    states_json=$([ -n "$states" ] && printf '%s\n' $states | jq -R . | jq -sc '.' || echo '["Todo"]')
    labels_json=$([ -n "$labels" ] && printf '%s\n' $labels | jq -R . | jq -sc '.' || echo '[]')
    src_json=$(jq -cn \
      --arg team "${team:-}" \
      --arg project "${project:-}" \
      --argjson assignees "$assignees_json" \
      --argjson states "$states_json" \
      --argjson labels "$labels_json" \
      '{"type":"linear","filter":{"team":$team,"assignees":$assignees,"states":$states,"labels":$labels,"project":$project}}')
    ;;
  github)
    labels_json=$([ -n "$labels" ] && printf '%s\n' $labels | jq -R . | jq -sc '.' || echo '[]')
    src_json=$(jq -cn \
      --arg repo "${project:-}" \
      --arg assignee "${user:-}" \
      --argjson labels "$labels_json" \
      --arg state "${state:-open}" \
      '{"type":"github","filter":{"repo":$repo,"assignee":$assignee,"labels":$labels,"state":$state,"type":"issue"}}')
    ;;
  monotask)
    src_json=$(jq -cn \
      --arg board "${project:-}" \
      --arg column "${state:-Todo}" \
      --arg label "${label:-role:ai-agent}" \
      '{"type":"monotask","filter":{"board":$board,"column":$column,"label":$label}}')
    ;;
  filesystem)
    src_json=$(jq -cn \
      --arg folder "${folder:-./tasks}" \
      --arg user "${user:-}" \
      '{"type":"filesystem","filter":{"folder":$folder,"glob":"*.task","user":$user}}')
    ;;
  *)
    echo "Unknown source type: $source. Supported: linear | github | monotask | filesystem"
    exit 1
    ;;
esac

tmp="${cfg}.tmp"
jq --argjson src "$src_json" '.sources += [$src]' "$cfg" > "$tmp" && mv "$tmp" "$cfg"
echo "Source added to monitor '$name'."

---

tick — The Main Execution Loop

This is the heart of the monitor. Called by ScheduleWakeup every poll_interval seconds.

Execution model: bash code blocks in this section are executable fragments. Prose instructions between blocks complete the control flow (ScheduleWakeup calls, conditional branches, fi closures). Follow both the code and the prose — neither is complete without the other.

Required: --name

cfg="$MONITOR_DIR/${name}.json"
state_file="$MONITOR_DIR/${name}-state.json"

# Load config
[ ! -f "$cfg" ] && echo "Monitor '$name' not found — loop terminated." && exit 0

monitor_status=$(jq -r '.status // "active"' "$cfg")
[ "$monitor_status" = "stopped" ]  && echo "Monitor '$name' stopped — loop terminated." && exit 0
[ "$monitor_status" = "paused" ]   && echo "Monitor '$name' paused — will not reschedule." && exit 0

# Init state file if missing
[ ! -f "$state_file" ] && echo '{"processed_ids":{},"in_flight":[]}' > "$state_file"

max_concurrent=$(jq -r '.max_concurrent // 1' "$cfg")
agent_type=$(jq -r '.agent_type // "coder"' "$cfg")
poll_interval=$(jq -r '.poll_interval // 120' "$cfg")

In-flight guard — if at capacity, reschedule and stop this tick:

in_flight_count=$(jq '.in_flight // [] | length' "$state_file")
in_flight_count=${in_flight_count:-0}
if [ "$in_flight_count" -ge "$max_concurrent" ]; then
  echo "[$name] In-flight ($in_flight_count) >= max_concurrent ($max_concurrent) — skipping claim this tick."
  # Reschedule next tick — do this BEFORE exit so the loop survives
  # ScheduleWakeup: delaySeconds=poll_interval, prompt="/mastermind-monitor --action tick --name <name>",
  #   reason="Monitor <name> in-flight throttle — will retry next tick"
  exit 0
fi

Note: The ScheduleWakeup call above is pseudocode inside the comment. Claude must call the actual ScheduleWakeup tool at this point, then exit 0. The exit 0 here is a bash signal that the tick logic description treats as "stop further processing in this tick"; it does NOT skip the ScheduleWakeup — that fires first.

Check for retry-pending tasks (before polling sources):

If a previous task failed but has retry_count < 3, it remains in in_flight with `statu