crewly 1.2.1 → 1.2.4

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/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="[TASK] 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 ---
@@ -95,9 +159,10 @@ if [ "$MONITOR_FALLBACK_MINUTES" != "0" ] && [ -n "$MONITOR_FALLBACK_MINUTES" ];
   SCHED_BODY=$(jq -n \
     --arg target "$SCHEDULE_TARGET" \
     --arg minutes "$MONITOR_FALLBACK_MINUTES" \
-    --arg message "[CHECK] Review progress of ${TO} — 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 message "Progress check: review ${TO} status — task: ${TASK:0:100}" \
+    --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/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"

package/config/skills/team-leader/aggregate-results/execute.sh

@@ -0,0 +1,168 @@
+#!/bin/bash
+# Aggregate results from worker sub-tasks into a structured markdown report.
+# Fetches task data from the task-management API and compiles a report.
+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 '{\"teamId\":\"team-123\",\"objective\":\"Build auth module\",\"reportType\":\"final\",\"taskPaths\":[\"/path/to/task1.md\",\"/path/to/task2.md\"],\"projectPath\":\"/path/to/project\"}'"
+
+TEAM_ID=$(echo "$INPUT" | jq -r '.teamId // empty')
+OBJECTIVE=$(echo "$INPUT" | jq -r '.objective // "Objective not specified"')
+REPORT_TYPE=$(echo "$INPUT" | jq -r '.reportType // "final"')
+TASK_PATHS=$(echo "$INPUT" | jq -c '.taskPaths // []')
+PROJECT_PATH=$(echo "$INPUT" | jq -r '.projectPath // empty')
+INCLUDE_VERIFICATION=$(echo "$INPUT" | jq -r '.includeVerification // "true"')
+
+# Collect task data
+TASK_RESULTS="[]"
+SUCCESS_COUNT=0
+FAILURE_COUNT=0
+BLOCKED_COUNT=0
+PENDING_COUNT=0
+
+TASK_COUNT=$(echo "$TASK_PATHS" | jq 'length')
+
+# If task paths provided, read each task
+if [ "$TASK_COUNT" -gt 0 ]; then
+  for i in $(seq 0 $((TASK_COUNT - 1))); do
+    TASK_PATH=$(echo "$TASK_PATHS" | jq -r ".[$i]")
+    READ_BODY=$(jq -n --arg taskPath "$TASK_PATH" '{taskPath: $taskPath}')
+    TASK_DATA=$(api_call POST "/task-management/read-task" "$READ_BODY" 2>/dev/null || echo '{}')
+
+    TASK_STATUS=$(echo "$TASK_DATA" | jq -r '.data.metadata.status // "unknown"' 2>/dev/null || echo "unknown")
+    TASK_TITLE=$(echo "$TASK_DATA" | jq -r '.data.metadata.title // .data.metadata.task // "Untitled"' 2>/dev/null || echo "Untitled")
+    TASK_ASSIGNEE=$(echo "$TASK_DATA" | jq -r '.data.metadata.assignedTo // "unassigned"' 2>/dev/null || echo "unassigned")
+    TASK_SUMMARY=$(echo "$TASK_DATA" | jq -r '.data.metadata.summary // ""' 2>/dev/null || true)
+
+    case "$TASK_STATUS" in
+      done|completed) SUCCESS_COUNT=$((SUCCESS_COUNT + 1)) ;;
+      blocked) BLOCKED_COUNT=$((BLOCKED_COUNT + 1)) ;;
+      failed) FAILURE_COUNT=$((FAILURE_COUNT + 1)) ;;
+      *) PENDING_COUNT=$((PENDING_COUNT + 1)) ;;
+    esac
+
+    TASK_RESULTS=$(echo "$TASK_RESULTS" | jq \
+      --arg title "$TASK_TITLE" \
+      --arg status "$TASK_STATUS" \
+      --arg assignee "$TASK_ASSIGNEE" \
+      --arg summary "$TASK_SUMMARY" \
+      --arg path "$TASK_PATH" \
+      '. + [{title: $title, status: $status, assignee: $assignee, summary: $summary, path: $path}]')
+  done
+fi
+
+# If no task paths but teamId provided, get team progress
+if [ "$TASK_COUNT" = "0" ] && [ -n "$PROJECT_PATH" ]; then
+  PROGRESS_DATA=$(api_call GET "/task-management/team-progress?projectPath=${PROJECT_PATH}" 2>/dev/null || echo '{}')
+  # Extract counts from team progress if available
+  SUCCESS_COUNT=$(echo "$PROGRESS_DATA" | jq -r '.data.done // 0' 2>/dev/null || echo "0")
+  FAILURE_COUNT=$(echo "$PROGRESS_DATA" | jq -r '.data.failed // 0' 2>/dev/null || echo "0")
+  BLOCKED_COUNT=$(echo "$PROGRESS_DATA" | jq -r '.data.blocked // 0' 2>/dev/null || echo "0")
+  PENDING_COUNT=$(echo "$PROGRESS_DATA" | jq -r '.data.open // 0' 2>/dev/null || echo "0")
+fi
+
+TOTAL=$((SUCCESS_COUNT + FAILURE_COUNT + BLOCKED_COUNT + PENDING_COUNT))
+
+# Generate the report
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+REPORT_TITLE=""
+case "$REPORT_TYPE" in
+  milestone) REPORT_TITLE="Milestone Report" ;;
+  daily) REPORT_TITLE="Daily Progress Report" ;;
+  final) REPORT_TITLE="Final Completion Report" ;;
+  *) REPORT_TITLE="Progress Report" ;;
+esac
+
+# Build markdown report
+REPORT="[TL_REPORT]
+
+# ${REPORT_TITLE}
+
+**Objective**: ${OBJECTIVE}
+**Report Type**: ${REPORT_TYPE}
+**Generated**: ${TIMESTAMP}
+**Team**: ${TEAM_ID:-N/A}
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Tasks | ${TOTAL} |
+| Completed | ${SUCCESS_COUNT} |
+| Failed | ${FAILURE_COUNT} |
+| Blocked | ${BLOCKED_COUNT} |
+| Pending | ${PENDING_COUNT} |
+
+**Completion Rate**: $([ "$TOTAL" -gt 0 ] && echo "$((SUCCESS_COUNT * 100 / TOTAL))%" || echo "N/A")
+"
+
+# Add individual task details if available
+RESULT_COUNT=$(echo "$TASK_RESULTS" | jq 'length')
+if [ "$RESULT_COUNT" -gt 0 ]; then
+  REPORT="${REPORT}
+## Task Details
+"
+  for i in $(seq 0 $((RESULT_COUNT - 1))); do
+    T_TITLE=$(echo "$TASK_RESULTS" | jq -r ".[$i].title")
+    T_STATUS=$(echo "$TASK_RESULTS" | jq -r ".[$i].status")
+    T_ASSIGNEE=$(echo "$TASK_RESULTS" | jq -r ".[$i].assignee")
+    T_SUMMARY=$(echo "$TASK_RESULTS" | jq -r ".[$i].summary")
+
+    # Status emoji
+    case "$T_STATUS" in
+      done|completed) STATUS_MARK="DONE" ;;
+      blocked) STATUS_MARK="BLOCKED" ;;
+      failed) STATUS_MARK="FAILED" ;;
+      *) STATUS_MARK="PENDING" ;;
+    esac
+
+    REPORT="${REPORT}
+### [${STATUS_MARK}] ${T_TITLE}
+- **Assignee**: ${T_ASSIGNEE}
+- **Status**: ${T_STATUS}
+$([ -n "$T_SUMMARY" ] && echo "- **Summary**: ${T_SUMMARY}" || true)
+"
+  done
+fi
+
+# Add action items for non-complete items
+if [ "$FAILURE_COUNT" -gt 0 ] || [ "$BLOCKED_COUNT" -gt 0 ]; then
+  REPORT="${REPORT}
+## Action Items
+
+$([ "$FAILURE_COUNT" -gt 0 ] && echo "- ${FAILURE_COUNT} task(s) failed — review via handle-failure skill" || true)
+$([ "$BLOCKED_COUNT" -gt 0 ] && echo "- ${BLOCKED_COUNT} task(s) blocked — escalate to Orchestrator if unresolvable" || true)
+"
+fi
+
+# Write report to temp file for reliable output
+REPORT_FILE="/tmp/tl-report-${TEAM_ID:-unknown}-$(date +%s).md"
+echo "$REPORT" > "$REPORT_FILE"
+
+# Output JSON result
+jq -n \
+  --arg reportType "$REPORT_TYPE" \
+  --arg objective "$OBJECTIVE" \
+  --arg reportFile "$REPORT_FILE" \
+  --arg timestamp "$TIMESTAMP" \
+  --arg total "$TOTAL" \
+  --arg success "$SUCCESS_COUNT" \
+  --arg failed "$FAILURE_COUNT" \
+  --arg blocked "$BLOCKED_COUNT" \
+  --arg pending "$PENDING_COUNT" \
+  '{
+    success: true,
+    reportType: $reportType,
+    objective: $objective,
+    reportFile: $reportFile,
+    timestamp: $timestamp,
+    stats: {
+      total: ($total | tonumber),
+      completed: ($success | tonumber),
+      failed: ($failed | tonumber),
+      blocked: ($blocked | tonumber),
+      pending: ($pending | tonumber)
+    }
+  }'