crewly 1.2.3 → 1.2.6

package/config/skills/orchestrator/broadcast-to-org/execute.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Broadcast a message to all Team Leaders within an organization (parent team's child teams).
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+INPUT="${1:-}"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"parentTeamId\":\"org-team-id\",\"message\":\"Please submit status reports\"}'"
+
+PARENT_TEAM_ID=$(echo "$INPUT" | jq -r '.parentTeamId // empty')
+MESSAGE=$(echo "$INPUT" | jq -r '.message // empty')
+require_param "parentTeamId" "$PARENT_TEAM_ID"
+require_param "message" "$MESSAGE"
+
+# Fetch all teams
+ALL_TEAMS=$(api_call GET "/teams" 2>/dev/null) || error_exit "Failed to fetch teams"
+
+# Verify parent team exists
+PARENT_EXISTS=$(echo "$ALL_TEAMS" | jq -r --arg pid "$PARENT_TEAM_ID" \
+  '[.data // . | if type == "array" then .[] else empty end | select(.id == $pid)] | length' 2>/dev/null || echo "0")
+
+if [ "$PARENT_EXISTS" = "0" ]; then
+  error_exit "Parent team '${PARENT_TEAM_ID}' not found"
+fi
+
+# Find child teams whose parentTeamId matches
+CHILD_TEAMS=$(echo "$ALL_TEAMS" | jq -c --arg pid "$PARENT_TEAM_ID" \
+  '[.data // . | if type == "array" then .[] else empty end | select(.parentTeamId == $pid)]' 2>/dev/null || echo "[]")
+
+CHILD_COUNT=$(echo "$CHILD_TEAMS" | jq 'length')
+
+if [ "$CHILD_COUNT" = "0" ]; then
+  echo "{\"sent\":0,\"failed\":0,\"skipped\":0,\"message\":\"No child teams found under parent ${PARENT_TEAM_ID}\"}"
+  exit 0
+fi
+
+SENT=0
+FAILED=0
+SKIPPED=0
+DETAILS="[]"
+
+# Iterate through child teams and find their leaders
+for i in $(seq 0 $((CHILD_COUNT - 1))); do
+  TEAM=$(echo "$CHILD_TEAMS" | jq -c ".[$i]")
+  TEAM_NAME=$(echo "$TEAM" | jq -r '.name // "unknown"')
+
+  # Find leader sessions: use leaderIds first, fallback to hierarchyLevel==1
+  LEADER_SESSIONS=$(echo "$TEAM" | jq -r '
+    if (.leaderIds // []) | length > 0 then
+      .members[] | select(.id as $id | any(.leaderIds[]; . == $id)) | .sessionName // empty
+    else
+      .members[] | select(.hierarchyLevel == 1) | .sessionName // empty
+    end
+  ' 2>/dev/null || true)
+
+  # Fallback: look for team-leader role
+  if [ -z "$LEADER_SESSIONS" ]; then
+    LEADER_SESSIONS=$(echo "$TEAM" | jq -r '.members[] | select(.role == "team-leader") | .sessionName // empty' 2>/dev/null || true)
+  fi
+
+  if [ -z "$LEADER_SESSIONS" ]; then
+    SKIPPED=$((SKIPPED + 1))
+    DETAILS=$(echo "$DETAILS" | jq --arg team "$TEAM_NAME" '. + [{"team": $team, "status": "skipped", "reason": "no leader found"}]')
+    continue
+  fi
+
+  for SESSION in $LEADER_SESSIONS; do
+    [ -z "$SESSION" ] && continue
+    BODY=$(jq -n --arg message "$MESSAGE" '{message: $message}')
+    if api_call POST "/terminal/${SESSION}/deliver" "$BODY" >/dev/null 2>&1; then
+      SENT=$((SENT + 1))
+      DETAILS=$(echo "$DETAILS" | jq --arg team "$TEAM_NAME" --arg session "$SESSION" \
+        '. + [{"team": $team, "session": $session, "status": "sent"}]')
+    else
+      FAILED=$((FAILED + 1))
+      DETAILS=$(echo "$DETAILS" | jq --arg team "$TEAM_NAME" --arg session "$SESSION" \
+        '. + [{"team": $team, "session": $session, "status": "failed"}]')
+    fi
+  done
+done
+
+jq -n \
+  --argjson sent "$SENT" \
+  --argjson failed "$FAILED" \
+  --argjson skipped "$SKIPPED" \
+  --argjson childTeams "$CHILD_COUNT" \
+  --argjson details "$DETAILS" \
+  '{sent: $sent, failed: $failed, skipped: $skipped, childTeams: $childTeams, details: $details, message: "Broadcast to organization complete"}'

package/config/skills/orchestrator/broadcast-to-org/instructions.md

@@ -0,0 +1,51 @@
+# Broadcast to Organization
+
+Send a message to all Team Leaders within a specific organization. Given a parent team ID, this skill finds all child teams, identifies their leaders, and delivers the message to each leader's session.
+
+## Usage
+
+```bash
+bash config/skills/orchestrator/broadcast-to-org/execute.sh '{"parentTeamId":"org-team-id","message":"Please submit your weekly status reports by EOD"}'
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `parentTeamId` | Yes | The ID of the parent/organization team |
+| `message` | Yes | The message to send to all TLs in the organization |
+
+## How It Works
+
+1. Fetches all teams from the API
+2. Filters child teams whose `parentTeamId` matches the given ID
+3. For each child team, finds leaders using (in priority order):
+   - `leaderIds` array on the team
+   - Members with `hierarchyLevel == 1`
+   - Members with `role == "team-leader"` (fallback)
+4. Delivers the message to each leader's session via `/terminal/{session}/deliver`
+
+## Output
+
+JSON with delivery summary:
+
+```json
+{
+  "sent": 3,
+  "failed": 0,
+  "skipped": 1,
+  "childTeams": 4,
+  "details": [
+    {"team": "Frontend", "session": "crewly-frontend-tl", "status": "sent"},
+    {"team": "Backend", "session": "crewly-backend-tl", "status": "sent"},
+    {"team": "QA", "status": "skipped", "reason": "no leader found"}
+  ],
+  "message": "Broadcast to organization complete"
+}
+```
+
+## Best Practices
+
+- Use this for organization-wide announcements like deadlines, priority changes, or standup reminders
+- For individual team communication, use `send-message` or `delegate-task` instead
+- Check the `skipped` count — teams without leaders won't receive the message

package/config/skills/orchestrator/broadcast-to-org/skill.json

@@ -0,0 +1,20 @@
+{
+  "id": "orc-broadcast-to-org",
+  "name": "Broadcast to Organization",
+  "description": "Send a message to all Team Leaders within a specific organization (parent team and its child teams).",
+  "category": "communication",
+  "skillType": "claude-skill",
+  "promptFile": "instructions.md",
+  "execution": {
+    "type": "script",
+    "script": {
+      "file": "execute.sh",
+      "interpreter": "bash",
+      "timeoutMs": 60000
+    }
+  },
+  "assignableRoles": ["orchestrator"],
+  "triggers": ["broadcast to org", "message org leaders", "notify organization"],
+  "tags": ["communication", "broadcast", "organization", "hierarchy"],
+  "version": "1.0.0"
+}

package/config/skills/orchestrator/cancel-all-schedules/execute.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Cancel all scheduled checks with optional filters
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+INPUT="${1:-}"
+
+# Build query string from optional filters
+QUERY=""
+if [ -n "$INPUT" ]; then
+  SESSION=$(echo "$INPUT" | jq -r '.session // empty')
+  OLDER_THAN=$(echo "$INPUT" | jq -r '.olderThanMinutes // empty')
+
+  PARAMS=""
+  [ -n "$SESSION" ] && PARAMS="session=${SESSION}"
+  if [ -n "$OLDER_THAN" ]; then
+    [ -n "$PARAMS" ] && PARAMS="${PARAMS}&"
+    PARAMS="${PARAMS}olderThanMinutes=${OLDER_THAN}"
+  fi
+  [ -n "$PARAMS" ] && QUERY="?${PARAMS}"
+fi
+
+api_call DELETE "/schedule${QUERY}"

package/config/skills/orchestrator/cancel-all-schedules/instructions.md

@@ -0,0 +1,23 @@
+# cancel-all-schedules
+
+Cancel all active scheduled checks with optional filters.
+
+## Usage
+
+```bash
+# Cancel ALL scheduled checks (nuclear option)
+bash config/skills/orchestrator/cancel-all-schedules/execute.sh
+
+# Cancel all checks for a specific session
+bash config/skills/orchestrator/cancel-all-schedules/execute.sh '{"session":"agent-sam"}'
+
+# Cancel checks older than 60 minutes
+bash config/skills/orchestrator/cancel-all-schedules/execute.sh '{"olderThanMinutes":60}'
+
+# Combine filters
+bash config/skills/orchestrator/cancel-all-schedules/execute.sh '{"session":"agent-sam","olderThanMinutes":30}'
+```
+
+## Output
+
+Returns `{"success": true, "data": {"cancelled": N}, "message": "Cancelled N scheduled check(s)"}`.

package/config/skills/orchestrator/cancel-all-schedules/skill.json

@@ -0,0 +1,17 @@
+{
+  "name": "cancel-all-schedules",
+  "description": "Cancel all active scheduled checks. Optionally filter by session or age.",
+  "usage": "execute.sh '{\"session\":\"agent-session\",\"olderThanMinutes\":60}'",
+  "parameters": {
+    "session": {
+      "type": "string",
+      "required": false,
+      "description": "Only cancel checks targeting this session"
+    },
+    "olderThanMinutes": {
+      "type": "number",
+      "required": false,
+      "description": "Only cancel checks older than N minutes"
+    }
+  }
+}

package/config/skills/orchestrator/delegate-task/execute.sh

@@ -17,6 +17,14 @@ PROJECT_PATH=$(echo "$INPUT" | jq -r '.projectPath // empty')
 require_param "to" "$TO"
 require_param "task" "$TASK"
 
+# Structured message parameters (for hierarchical teams)
+TITLE=$(echo "$INPUT" | jq -r '.title // empty')
+PARENT_TASK_ID=$(echo "$INPUT" | jq -r '.parentTaskId // empty')
+EXPECTED_ARTIFACTS=$(echo "$INPUT" | jq -c '.expectedArtifacts // empty')
+CONTEXT_FILES=$(echo "$INPUT" | jq -c '.contextFiles // empty')
+DEADLINE_HINT=$(echo "$INPUT" | jq -r '.deadlineHint // empty')
+USE_STRUCTURED=$(echo "$INPUT" | jq -r '.structured // "false"')
+
 # Monitor parameters — enabled by default to ensure proactive progress notifications.
 # Use explicit null-check so that `false` / `0` are respected as opt-out values,
 # while omitted fields default to enabled (idleEvent=true, fallbackCheckMinutes=5).
@@ -43,18 +51,65 @@ if [ -n "$CONTEXT" ]; then
   CONTEXT="$(CREWLY_ROOT="$CREWLY_ROOT" resolve_skill_paths "$CONTEXT")"
 fi
 
-# Build a structured task message
-TASK_MESSAGE="New task from orchestrator (priority: ${PRIORITY}):\n\n${TASK}"
-[ -n "$CONTEXT" ] && TASK_MESSAGE="${TASK_MESSAGE}\n\nContext: ${CONTEXT}"
-TASK_MESSAGE="${TASK_MESSAGE}\n\nWhen done, report back using: bash ${CREWLY_ROOT}/config/skills/agent/core/report-status/execute.sh '{\"sessionName\":\"${TO}\",\"status\":\"done\",\"summary\":\"<brief summary>\"}'"
+# Build the task message
+# If structured=true and title is provided, use the [TASK ASSIGNMENT] format
+# Otherwise, use the legacy free-text format for backwards compatibility
+DELEGATOR="${CREWLY_SESSION_NAME:-crewly-orc}"
+
+if [ "$USE_STRUCTURED" = "true" ] && [ -n "$TITLE" ]; then
+  # Structured TaskAssignment format for hierarchical teams
+  TASK_MESSAGE="---\n[TASK ASSIGNMENT]\nTask ID: ${TASK_ID:-pending}\nTitle: ${TITLE}\nPriority: ${PRIORITY}\nDelegated by: ${DELEGATOR}\nParent Task: ${PARENT_TASK_ID:-none}\n---\n\n## Instructions\n${TASK}"
+
+  # Add expected artifacts if provided
+  if [ -n "$EXPECTED_ARTIFACTS" ] && [ "$EXPECTED_ARTIFACTS" != "" ]; then
+    ARTIFACT_LIST=$(echo "$EXPECTED_ARTIFACTS" | jq -r '.[]? // empty' 2>/dev/null | while read -r a; do echo "- ${a}"; done)
+    if [ -n "$ARTIFACT_LIST" ]; then
+      TASK_MESSAGE="${TASK_MESSAGE}\n\n## Expected Deliverables\n${ARTIFACT_LIST}"
+    fi
+  fi
 
-# waitTimeout matches EVENT_DELIVERY_CONSTANTS.AGENT_READY_TIMEOUT (120000ms)
-BODY=$(jq -n --arg message "$TASK_MESSAGE" '{message: $message, waitForReady: true, waitTimeout: 120000}')
+  # Add context files if provided
+  if [ -n "$CONTEXT_FILES" ] && [ "$CONTEXT_FILES" != "" ]; then
+    FILE_LIST=$(echo "$CONTEXT_FILES" | jq -r '.[]? // empty' 2>/dev/null | while read -r f; do echo "- ${f}"; done)
+    if [ -n "$FILE_LIST" ]; then
+      TASK_MESSAGE="${TASK_MESSAGE}\n\n## Context\nRead these files first:\n${FILE_LIST}"
+    fi
+  fi
 
-api_call POST "/terminal/${TO}/deliver" "$BODY"
+  [ -n "$CONTEXT" ] && TASK_MESSAGE="${TASK_MESSAGE}\n\nAdditional context: ${CONTEXT}"
+  [ -n "$DEADLINE_HINT" ] && TASK_MESSAGE="${TASK_MESSAGE}\n\n**Deadline hint**: ${DEADLINE_HINT}"
+  TASK_MESSAGE="${TASK_MESSAGE}\n\n---\nWhen done, report back using: bash ${CREWLY_ROOT}/config/skills/agent/core/report-status/execute.sh '{\"sessionName\":\"${TO}\",\"status\":\"done\",\"summary\":\"<brief summary>\",\"projectPath\":\"${PROJECT_PATH}\"}'"
+  TASK_MESSAGE="${TASK_MESSAGE}\n\nBefore reporting done, persist key findings using: bash ${CREWLY_ROOT}/config/skills/agent/core/remember/execute.sh '{\"agentId\":\"${TO}\",\"content\":\"<key findings>\",\"category\":\"pattern\",\"scope\":\"project\"}'"
+else
+  # Legacy free-text format (backwards compatible)
+  TASK_MESSAGE="New task from orchestrator (priority: ${PRIORITY}):\n\n${TASK}"
+  [ -n "$CONTEXT" ] && TASK_MESSAGE="${TASK_MESSAGE}\n\nContext: ${CONTEXT}"
+  TASK_MESSAGE="${TASK_MESSAGE}\n\nWhen done, report back using: bash ${CREWLY_ROOT}/config/skills/agent/core/report-status/execute.sh '{\"sessionName\":\"${TO}\",\"status\":\"done\",\"summary\":\"<brief summary>\",\"projectPath\":\"${PROJECT_PATH}\"}'"
+  TASK_MESSAGE="${TASK_MESSAGE}\n\nBefore reporting done, persist key findings using: bash ${CREWLY_ROOT}/config/skills/agent/core/remember/execute.sh '{\"agentId\":\"${TO}\",\"content\":\"<key findings>\",\"category\":\"pattern\",\"scope\":\"project\"}'"
+fi
 
-# Track the task file path from create response for monitoring linkage
+# Deliver the task message with fallback strategy:
+# 1. Try reliable delivery with waitForReady (15s timeout)
+# 2. If agent not ready, fall back to force mode (direct PTY write)
+# 3. If both fail, output error to stdout (so orchestrator can see it) and exit 1
+BODY=$(jq -n --arg message "$TASK_MESSAGE" '{message: $message, waitForReady: true, waitTimeout: 15000}')
+
+DELIVER_OK=true
+api_call POST "/terminal/${TO}/deliver" "$BODY" || DELIVER_OK=false
+
+if [ "$DELIVER_OK" = "false" ]; then
+  # Agent not ready or session not found — retry with force mode (direct PTY write)
+  FORCE_BODY=$(jq -n --arg message "$TASK_MESSAGE" '{message: $message, force: true}')
+  api_call POST "/terminal/${TO}/deliver" "$FORCE_BODY" || {
+    # Both delivery attempts failed — output error to stdout for orchestrator visibility
+    echo '{"error":"Failed to deliver task to '"$TO"'. Session may not exist or agent is not running."}'
+    exit 1
+  }
+fi
+
+# Track the task file path and task ID from create response for monitoring linkage
 TASK_FILE_PATH=""
+TASK_ID=""
 
 # Create task file in project's .crewly/tasks/ directory
 if [ -n "$PROJECT_PATH" ]; then
@@ -67,6 +122,15 @@ if [ -n "$PROJECT_PATH" ]; then
     '{projectPath: $projectPath, task: $task, priority: $priority, sessionName: $sessionName, milestone: $milestone}')
   CREATE_RESULT=$(api_call POST "/task-management/create" "$CREATE_BODY" 2>/dev/null || true)
   TASK_FILE_PATH=$(echo "$CREATE_RESULT" | jq -r '.taskPath // empty' 2>/dev/null || true)
+  TASK_ID=$(echo "$CREATE_RESULT" | jq -r '.taskId // empty' 2>/dev/null || true)
+
+  # Deliver a follow-up message with complete-task instructions now that taskPath is known (#137).
+  # This ensures agents call complete-task with the exact path, not just report-status.
+  if [ -n "$TASK_FILE_PATH" ]; then
+    COMPLETE_INSTR="After finishing and calling report-status, also run: bash ${CREWLY_ROOT}/config/skills/agent/core/complete-task/execute.sh '{\"absoluteTaskPath\":\"${TASK_FILE_PATH}\",\"sessionName\":\"${TO}\",\"summary\":\"<brief summary>\"}'"
+    FOLLOWUP_BODY=$(jq -n --arg message "$COMPLETE_INSTR" '{message: $message, force: true}')
+    api_call POST "/terminal/${TO}/deliver" "$FOLLOWUP_BODY" 2>/dev/null || true
+  fi
 fi
 
 # --- Auto-monitoring setup ---
@@ -96,8 +160,9 @@ if [ "$MONITOR_FALLBACK_MINUTES" != "0" ] && [ -n "$MONITOR_FALLBACK_MINUTES" ];
     --arg target "$SCHEDULE_TARGET" \
     --arg minutes "$MONITOR_FALLBACK_MINUTES" \
     --arg message "Progress check: review ${TO} status — task: ${TASK:0:100}" \
-    '{targetSession: $target, minutes: ($minutes | tonumber), intervalMinutes: ($minutes | tonumber), message: $message, isRecurring: true}')
-  SCHED_RESULT=$(api_call POST "/schedule" "$SCHED_BODY" 2>/dev/null || true)
+    --arg taskId "$TASK_ID" \
+    '{targetSession: $target, minutes: ($minutes | tonumber), intervalMinutes: ($minutes | tonumber), message: $message, isRecurring: true} + (if $taskId != "" then {taskId: $taskId} else {} end)' 2>/dev/null) || true
+  [ -n "$SCHED_BODY" ] && SCHED_RESULT=$(api_call POST "/schedule" "$SCHED_BODY" 2>/dev/null || true)
   SCHED_ID=$(echo "$SCHED_RESULT" | jq -r '.checkId // .data.checkId // empty' 2>/dev/null || true)
   if [ -n "$SCHED_ID" ]; then
     COLLECTED_SCHEDULE_IDS=$(echo "$COLLECTED_SCHEDULE_IDS" | jq --arg id "$SCHED_ID" '. + [$id]')

package/config/skills/orchestrator/delegate-task/instructions.md

@@ -70,15 +70,25 @@ When the agent completes the task (via `report-status` with `status: done` or `c
 
 No manual cleanup needed.
 
+## Delivery Strategy
+
+The script uses a two-stage delivery strategy:
+
+1. **Reliable delivery** (15s timeout) — Waits for the agent to be at a prompt, then delivers with verification. This is the preferred path.
+2. **Force fallback** — If the agent is busy or not ready within 15 seconds, the message is written directly to the PTY session without waiting. The task is still delivered, but may appear mid-output.
+
+This ensures tasks are always delivered even when agents are busy processing previous work.
+
 ## Error Handling
 
 | Error | Cause | Solution |
 |-------|-------|----------|
 | `Missing required parameter: to` | `to` not provided | Include target session name |
 | `Missing required parameter: task` | `task` not provided | Include task description |
+| `Failed to deliver task to X` | Session doesn't exist or agent crashed | Check agent status, restart if needed |
 | `curl failed with exit code N` | Backend not running | Start the Crewly backend |
 
-Monitoring setup failures are non-fatal — if subscribe-event or schedule-check fails, the task is still delegated successfully.
+Error messages are output to **stdout** (JSON format) so the orchestrator can read them. Monitoring setup failures are non-fatal — if subscribe-event or schedule-check fails, the task is still delegated successfully.
 
 ## Related Skills
 

package/config/skills/orchestrator/handle-agent-failure/execute.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Notify the orchestrator about an agent failure so it can take recovery actions (#129)
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+INPUT="${1:-}"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"agentSession\":\"agent-dev-1\",\"reason\":\"runtime_exited\",\"hadActiveTasks\":true}'"
+
+AGENT_SESSION=$(echo "$INPUT" | jq -r '.agentSession // empty')
+REASON=$(echo "$INPUT" | jq -r '.reason // "unknown"')
+HAD_ACTIVE_TASKS=$(echo "$INPUT" | jq -r '.hadActiveTasks // false')
+TASK_SUMMARY=$(echo "$INPUT" | jq -r '.taskSummary // empty')
+RESTART_ATTEMPTED=$(echo "$INPUT" | jq -r '.restartAttempted // false')
+RESTART_SUCCEEDED=$(echo "$INPUT" | jq -r '.restartSucceeded // false')
+require_param "agentSession" "$AGENT_SESSION"
+
+# Build a structured notification message for the orchestrator
+MESSAGE="Agent failure notification: ${AGENT_SESSION} became inactive.\nReason: ${REASON}"
+
+if [ "$HAD_ACTIVE_TASKS" = "true" ]; then
+  MESSAGE="${MESSAGE}\nThe agent had active tasks in progress."
+  [ -n "$TASK_SUMMARY" ] && MESSAGE="${MESSAGE}\nTask: ${TASK_SUMMARY}"
+fi
+
+if [ "$RESTART_ATTEMPTED" = "true" ]; then
+  if [ "$RESTART_SUCCEEDED" = "true" ]; then
+    MESSAGE="${MESSAGE}\nAutomatic restart succeeded — agent is recovering."
+  else
+    MESSAGE="${MESSAGE}\nAutomatic restart FAILED — manual intervention needed."
+    MESSAGE="${MESSAGE}\n\nPlease take one of the following actions:"
+    MESSAGE="${MESSAGE}\n1. Restart the agent and re-delegate the task"
+    MESSAGE="${MESSAGE}\n2. Reassign the task to another available agent"
+    MESSAGE="${MESSAGE}\n3. Inform the user about the failure"
+  fi
+else
+  MESSAGE="${MESSAGE}\nNo automatic restart was attempted."
+  MESSAGE="${MESSAGE}\n\nPlease decide whether to restart the agent or reassign its tasks."
+fi
+
+# Send the notification to the orchestrator via the chat API
+BODY=$(jq -n --arg content "$MESSAGE" --arg senderName "system" \
+  '{content: $content, senderName: $senderName, senderType: "system"}')
+
+api_call POST "/chat/agent-response" "$BODY"

package/config/skills/orchestrator/handle-agent-failure/instructions.md

@@ -0,0 +1,29 @@
+# Handle Agent Failure
+
+Sends a failure notification to the orchestrator when an agent becomes inactive unexpectedly (runtime exit, API failure, crash). The orchestrator can then decide to restart the agent, reassign the task, or inform the user.
+
+## Usage
+
+```bash
+bash config/skills/orchestrator/handle-agent-failure/execute.sh '{"agentSession":"agent-dev-1","reason":"runtime_exited","hadActiveTasks":true,"taskSummary":"Implementing login form","restartAttempted":true,"restartSucceeded":false}'
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `agentSession` | Yes | The failed agent's PTY session name |
+| `reason` | Yes | Failure reason: `runtime_exited`, `api_failure`, `connectivity_stuck`, `update_interrupted` |
+| `hadActiveTasks` | No | Whether the agent had in-progress tasks (default: false) |
+| `taskSummary` | No | Brief description of what the agent was working on |
+| `restartAttempted` | No | Whether an automatic restart was attempted |
+| `restartSucceeded` | No | Whether the automatic restart succeeded |
+
+## Behavior
+
+The script sends a structured failure notification to the orchestrator via the chat API. The orchestrator receives the message and can:
+
+1. **Restart the agent** if the failure was transient
+2. **Reassign the task** to another available agent
+3. **Notify the user** about the failure and ask for guidance
+4. **Record the failure** for future prevention

package/config/skills/orchestrator/handle-agent-failure/skill.json

@@ -0,0 +1,20 @@
+{
+  "id": "orc-handle-agent-failure",
+  "name": "Handle Agent Failure",
+  "description": "Notify the orchestrator when an agent fails or becomes inactive unexpectedly, so recovery actions can be taken.",
+  "category": "monitoring",
+  "skillType": "claude-skill",
+  "promptFile": "instructions.md",
+  "execution": {
+    "type": "script",
+    "script": {
+      "file": "execute.sh",
+      "interpreter": "bash",
+      "timeoutMs": 15000
+    }
+  },
+  "assignableRoles": ["orchestrator"],
+  "triggers": ["agent failed", "agent crashed", "agent inactive", "handle failure", "recovery"],
+  "tags": ["monitoring", "failure", "recovery", "agent-lifecycle"],
+  "version": "1.0.0"
+}

package/config/skills/orchestrator/list-schedules/execute.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# List all active scheduled checks with optional session filter
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+INPUT="${1:-}"
+
+# Optional session filter
+SESSION=""
+if [ -n "$INPUT" ]; then
+  SESSION=$(echo "$INPUT" | jq -r '.session // empty')
+fi
+
+if [ -n "$SESSION" ]; then
+  api_call GET "/schedule?session=${SESSION}"
+else
+  api_call GET "/schedule"
+fi

package/config/skills/orchestrator/list-schedules/instructions.md

@@ -0,0 +1,24 @@
+# list-schedules
+
+List all active scheduled checks (one-time and recurring).
+
+## Usage
+
+```bash
+# List all scheduled checks
+bash config/skills/orchestrator/list-schedules/execute.sh
+
+# List checks for a specific session
+bash config/skills/orchestrator/list-schedules/execute.sh '{"session":"agent-sam"}'
+```
+
+## Output
+
+Returns a JSON array of scheduled checks with fields:
+- `id` — Schedule ID
+- `targetSession` — Target agent session
+- `message` — Check message content
+- `scheduledFor` — Next fire time (ISO)
+- `isRecurring` — Whether it repeats
+- `intervalMinutes` — Repeat interval (if recurring)
+- `createdAt` — Creation timestamp

package/config/skills/orchestrator/list-schedules/skill.json

@@ -0,0 +1,12 @@
+{
+  "name": "list-schedules",
+  "description": "List all active scheduled checks. Optionally filter by session name.",
+  "usage": "execute.sh '{\"session\":\"agent-session\"}'",
+  "parameters": {
+    "session": {
+      "type": "string",
+      "required": false,
+      "description": "Filter by target session name"
+    }
+  }
+}

package/config/skills/orchestrator/restart-crewly/instructions.md

@@ -16,8 +16,15 @@ None required.
 
 JSON confirming the restart was initiated and how many sessions were saved.
 
+## How It Works
+
+1. The backend saves all PTY session state to disk
+2. The backend exits with a special restart exit code (120)
+3. The CLI parent process detects this code and automatically respawns the backend
+4. The new backend instance restores saved sessions and resumes normal operation
+
 ## Notes
 
-- The server process exits with code 0 after saving state
-- The external process manager (nodemon, systemd, ECS) handles restarting
+- The restart is fully automatic when launched via `crewly start` — no external process manager needed
+- In development mode (`npm run dev`), the tsx file watcher handles restarts
 - Agents will auto-resume their previous sessions on restart if the "Auto-Resume on Restart" setting is enabled

package/config/skills/team-leader/_common/lib.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Team Leader Skills Common Library - delegates to shared library
+SHARED_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/_common"
+source "${SHARED_LIB_DIR}/lib.sh"