crewly 1.2.1 → 1.2.4

package/config/skills/team-leader/handle-failure/instructions.md

@@ -0,0 +1,93 @@
+# Handle Failure
+
+Decides the next action when a worker task fails verification or execution. Implements a three-tier decision logic: retry, reassign, or escalate.
+
+## When to Use
+
+- When `verify-output` returns `passed: false`
+- When a worker reports a `blocked` status
+- When a worker session crashes or becomes unresponsive
+
+## Usage
+
+```bash
+bash {{SKILLS_PATH}}/team-leader/handle-failure/execute.sh '{"workerId":"worker-1","workerSession":"worker-session","teamId":"team-123","failureInfo":{"error":"3 tests failed","failedSteps":["tests"],"retries":0,"failureType":"verification"},"requiredRole":"developer"}'
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `workerId` | Yes | ID of the failed worker |
+| `workerSession` | No | Session name of the failed worker |
+| `teamId` | No | Team ID (needed for reassignment lookup) |
+| `requiredRole` | No | Role required for the task (helps find alternatives) |
+| `taskDescription` | No | Brief task description for context |
+| `failureInfo` | Yes | Failure details object (see below) |
+
+### failureInfo Object
+
+| Field | Description |
+|-------|-------------|
+| `error` | Error message or description |
+| `failedSteps` | Array of failed verification step names |
+| `retries` | Number of retries already attempted |
+| `failureType` | Category of failure (see below) |
+
+### Failure Types
+
+| Type | Description | Default Action |
+|------|-------------|----------------|
+| `verification` | Verification checks failed | Retry (< 2 retries) |
+| `format` | Output format issues | Retry |
+| `test_failure` | Tests failed | Retry |
+| `pty_error` | PTY session error | Retry |
+| `session_error` | Session crashed | Retry |
+| `skill_mismatch` | Worker lacks required skills | Reassign |
+| `resource_error` | Resource unavailable | Escalate |
+| `permission_error` | Permission denied | Escalate |
+| `budget_error` | Token/API budget exceeded | Escalate |
+
+## Decision Logic
+
+```
+1. retries < 2 AND recoverable failure → RETRY
+   (verification, format, test_failure, pty_error, session_error, unknown)
+
+2. retries >= 2 OR skill_mismatch → REASSIGN
+   - Searches team for another active worker with matching role
+   - If no alternative found → ESCALATE
+
+3. resource/permission/budget error → ESCALATE immediately
+   (These cannot be resolved at the TL level)
+```
+
+## Output
+
+```json
+{
+  "action": "retry",
+  "nextWorkerId": null,
+  "nextWorkerSession": null,
+  "instructions": "Retry attempt 1/2. Previous failure: 3 tests failed. Please fix the issues and try again.",
+  "context": {
+    "originalWorkerId": "worker-1",
+    "failureType": "verification",
+    "retriesSoFar": 0
+  }
+}
+```
+
+## After Getting the Decision
+
+| Action | Next Step |
+|--------|-----------|
+| `retry` | Send instructions to the original worker via `delegate-task` with incremented retry count |
+| `reassign` | Use `delegate-task` to send the task to `nextWorkerId`/`nextWorkerSession` |
+| `escalate` | Report to Orchestrator via `report-status` with the failure details |
+
+## Related Skills
+
+- `verify-output` — Triggers handle-failure when verification fails
+- `delegate-task` — Used for retry and reassign actions
+- `aggregate-results` — Include failure handling in reports

package/config/skills/team-leader/handle-failure/skill.json

@@ -0,0 +1,20 @@
+{
+  "id": "tl-handle-failure",
+  "name": "Handle Failure",
+  "description": "Decide the next action when a worker task fails verification or execution: retry the same worker, reassign to another worker, or escalate to the Orchestrator.",
+  "category": "management",
+  "skillType": "claude-skill",
+  "promptFile": "instructions.md",
+  "execution": {
+    "type": "script",
+    "script": {
+      "file": "execute.sh",
+      "interpreter": "bash",
+      "timeoutMs": 30000
+    }
+  },
+  "assignableRoles": ["team-leader"],
+  "triggers": ["handle failure", "task failed", "worker error", "decide next action"],
+  "tags": ["failure", "recovery", "retry", "escalation", "management"],
+  "version": "1.0.0"
+}

package/config/skills/team-leader/schedule-check/execute.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Schedule a future check-in reminder (Team Leader version).
+# Validates that the target is self or a subordinate worker.
+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 '{\"minutes\":5,\"message\":\"Check worker progress\",\"teamId\":\"team-123\",\"tlMemberId\":\"tl-id\",\"sessionName\":\"my-session\"}'"
+
+MINUTES=$(echo "$INPUT" | jq -r '.minutes // empty')
+MESSAGE=$(echo "$INPUT" | jq -r '.message // empty')
+TARGET=$(echo "$INPUT" | jq -r '.target // empty')
+RECURRING=$(echo "$INPUT" | jq -r '.recurring // false')
+MAX_OCCURRENCES=$(echo "$INPUT" | jq -r '.maxOccurrences // empty')
+TEAM_ID=$(echo "$INPUT" | jq -r '.teamId // empty')
+TL_MEMBER_ID=$(echo "$INPUT" | jq -r '.tlMemberId // empty')
+# sessionName: explicit caller identity, used as fallback when CREWLY_SESSION_NAME is not set
+SESSION_NAME=$(echo "$INPUT" | jq -r '.sessionName // empty')
+require_param "minutes" "$MINUTES"
+require_param "message" "$MESSAGE"
+
+# Resolve caller identity: env var > input param
+CALLER_SESSION="${CREWLY_SESSION_NAME:-${SESSION_NAME}}"
+
+# Default target to the caller's own session when not specified
+TARGET_SESSION="${TARGET:-${CALLER_SESSION}}"
+[ -z "$TARGET_SESSION" ] && error_exit "No target session specified and CREWLY_SESSION_NAME not set. Pass sessionName in input."
+
+# Validate hierarchy: only when targeting a different session (not self)
+if [ -n "$TARGET_SESSION" ] && [ "$TARGET_SESSION" != "$CALLER_SESSION" ]; then
+  if [ -n "$TEAM_ID" ] && [ -n "$TL_MEMBER_ID" ]; then
+    TEAM_DATA=$(api_call GET "/teams/${TEAM_ID}" 2>/dev/null || echo '{}')
+    TEAM_SUCCESS=$(echo "$TEAM_DATA" | jq -r '.success // false' 2>/dev/null || echo "false")
+
+    if [ "$TEAM_SUCCESS" = "true" ]; then
+      WORKER_PARENT=$(echo "$TEAM_DATA" | jq -r --arg session "$TARGET_SESSION" \
+        '.data.members[] | select(.sessionName == $session) | .parentMemberId // empty' 2>/dev/null || true)
+
+      if [ -z "$WORKER_PARENT" ]; then
+        error_exit "Hierarchy violation: target ${TARGET_SESSION} is not a member of team ${TEAM_ID}"
+      fi
+
+      if [ "$WORKER_PARENT" != "$TL_MEMBER_ID" ]; then
+        error_exit "Hierarchy violation: target ${TARGET_SESSION} (parentMemberId=${WORKER_PARENT}) is not a subordinate of TL ${TL_MEMBER_ID}"
+      fi
+    fi
+  else
+    error_exit "teamId and tlMemberId are required when scheduling checks for other sessions"
+  fi
+fi
+
+# Build API request body
+if [ "$RECURRING" = "true" ]; then
+  BODY=$(jq -n --arg target "$TARGET_SESSION" --arg minutes "$MINUTES" --arg message "$MESSAGE" \
+    '{targetSession: $target, minutes: ($minutes | tonumber), intervalMinutes: ($minutes | tonumber), message: $message, isRecurring: true}')
+  if [ -n "$MAX_OCCURRENCES" ]; then
+    BODY=$(echo "$BODY" | jq --arg max "$MAX_OCCURRENCES" '. + {maxOccurrences: ($max | tonumber)}')
+  fi
+else
+  BODY=$(jq -n --arg target "$TARGET_SESSION" --arg minutes "$MINUTES" --arg message "$MESSAGE" \
+    '{targetSession: $target, minutes: ($minutes | tonumber), message: $message}')
+fi
+
+api_call POST "/schedule" "$BODY"

package/config/skills/team-leader/schedule-check/execute.test.sh

@@ -0,0 +1,247 @@
+#!/bin/bash
+# Tests for TL schedule-check execute.sh
+# Covers: self-scheduling, worker scheduling, hierarchy violation, missing params
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXECUTE="$SCRIPT_DIR/execute.sh"
+PASS=0
+FAIL=0
+
+assert_succeeds() {
+  local desc="$1"
+  shift
+  if OUTPUT=$("$@" 2>&1); then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc (expected success, got exit $? — output: $OUTPUT)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_fails() {
+  local desc="$1"
+  shift
+  if OUTPUT=$("$@" 2>&1); then
+    echo "  FAIL: $desc (expected failure, got success — output: $OUTPUT)"
+    FAIL=$((FAIL + 1))
+  else
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  fi
+}
+
+assert_fails_with() {
+  local desc="$1" expected_msg="$2"
+  shift 2
+  local OUTPUT=""
+  if OUTPUT=$("$@" 2>&1); then
+    echo "  FAIL: $desc (expected failure, got success)"
+    FAIL=$((FAIL + 1))
+  elif echo "$OUTPUT" | grep -q "$expected_msg"; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc (expected '$expected_msg' in output, got: $OUTPUT)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Create a mock wrapper that overrides api_call to avoid real HTTP calls.
+# The mock returns team data with known members for hierarchy testing.
+MOCK_DIR=$(mktemp -d)
+MOCK_SCRIPT="$MOCK_DIR/run_schedule_check.sh"
+cat > "$MOCK_SCRIPT" << 'MOCK_EOF'
+#!/bin/bash
+# Mock wrapper for schedule-check execute.sh
+# Overrides api_call to return controlled responses
+set -euo pipefail
+SCRIPT_DIR_INNER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Load the real shared lib first to get require_param, error_exit, etc.
+REAL_SKILL_DIR="$1"
+shift
+source "${REAL_SKILL_DIR}/../_common/lib.sh"
+
+# Override api_call with mock
+api_call() {
+  local method="$1" endpoint="$2" body="${3:-}"
+
+  if [ "$method" = "GET" ] && echo "$endpoint" | grep -q "^/teams/"; then
+    # Return mock team data with known hierarchy:
+    # TL: ella-tl (member-id: tl-001, sessionName: crewly-marketing-ella-abc123)
+    # Worker: mila-worker (member-id: worker-001, sessionName: crewly-marketing-mila-def456, parent: tl-001)
+    cat << 'TEAMJSON'
+{"success":true,"data":{"id":"team-123","name":"Marketing","members":[{"id":"tl-001","sessionName":"crewly-marketing-ella-abc123","role":"team-leader","parentMemberId":""},{"id":"worker-001","sessionName":"crewly-marketing-mila-def456","role":"developer","parentMemberId":"tl-001"},{"id":"worker-002","sessionName":"crewly-marketing-luna-ghi789","role":"developer","parentMemberId":"other-tl"}]}}
+TEAMJSON
+    return 0
+  fi
+
+  if [ "$method" = "POST" ] && [ "$endpoint" = "/schedule" ]; then
+    echo '{"success":true,"data":{"checkId":"mock-check-id-001"},"message":"Check-in scheduled successfully"}'
+    return 0
+  fi
+
+  echo '{"error":true,"status":404,"details":"Unknown endpoint"}' >&2
+  return 1
+}
+
+# Now source and execute the main script logic inline
+# (We can't just call execute.sh because it sources lib.sh again which would
+# override our mock. Instead, we replicate the sourcing chain.)
+INPUT="${1:-}"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{...}'"
+
+MINUTES=$(echo "$INPUT" | jq -r '.minutes // empty')
+MESSAGE=$(echo "$INPUT" | jq -r '.message // empty')
+TARGET=$(echo "$INPUT" | jq -r '.target // empty')
+RECURRING=$(echo "$INPUT" | jq -r '.recurring // false')
+MAX_OCCURRENCES=$(echo "$INPUT" | jq -r '.maxOccurrences // empty')
+TEAM_ID=$(echo "$INPUT" | jq -r '.teamId // empty')
+TL_MEMBER_ID=$(echo "$INPUT" | jq -r '.tlMemberId // empty')
+SESSION_NAME=$(echo "$INPUT" | jq -r '.sessionName // empty')
+require_param "minutes" "$MINUTES"
+require_param "message" "$MESSAGE"
+
+CALLER_SESSION="${CREWLY_SESSION_NAME:-${SESSION_NAME}}"
+TARGET_SESSION="${TARGET:-${CALLER_SESSION}}"
+[ -z "$TARGET_SESSION" ] && error_exit "No target session specified and CREWLY_SESSION_NAME not set. Pass sessionName in input."
+
+if [ -n "$TARGET_SESSION" ] && [ "$TARGET_SESSION" != "$CALLER_SESSION" ]; then
+  if [ -n "$TEAM_ID" ] && [ -n "$TL_MEMBER_ID" ]; then
+    TEAM_DATA=$(api_call GET "/teams/${TEAM_ID}" 2>/dev/null || echo '{}')
+    TEAM_SUCCESS=$(echo "$TEAM_DATA" | jq -r '.success // false' 2>/dev/null || echo "false")
+
+    if [ "$TEAM_SUCCESS" = "true" ]; then
+      WORKER_PARENT=$(echo "$TEAM_DATA" | jq -r --arg session "$TARGET_SESSION" \
+        '.data.members[] | select(.sessionName == $session) | .parentMemberId // empty' 2>/dev/null || true)
+
+      if [ -z "$WORKER_PARENT" ]; then
+        error_exit "Hierarchy violation: target ${TARGET_SESSION} is not a member of team ${TEAM_ID}"
+      fi
+
+      if [ "$WORKER_PARENT" != "$TL_MEMBER_ID" ]; then
+        error_exit "Hierarchy violation: target ${TARGET_SESSION} (parentMemberId=${WORKER_PARENT}) is not a subordinate of TL ${TL_MEMBER_ID}"
+      fi
+    fi
+  else
+    error_exit "teamId and tlMemberId are required when scheduling checks for other sessions"
+  fi
+fi
+
+if [ "$RECURRING" = "true" ]; then
+  BODY=$(jq -n --arg target "$TARGET_SESSION" --arg minutes "$MINUTES" --arg message "$MESSAGE" \
+    '{targetSession: $target, minutes: ($minutes | tonumber), intervalMinutes: ($minutes | tonumber), message: $message, isRecurring: true}')
+  if [ -n "$MAX_OCCURRENCES" ]; then
+    BODY=$(echo "$BODY" | jq --arg max "$MAX_OCCURRENCES" '. + {maxOccurrences: ($max | tonumber)}')
+  fi
+else
+  BODY=$(jq -n --arg target "$TARGET_SESSION" --arg minutes "$MINUTES" --arg message "$MESSAGE" \
+    '{targetSession: $target, minutes: ($minutes | tonumber), message: $message}')
+fi
+
+api_call POST "/schedule" "$BODY"
+MOCK_EOF
+chmod +x "$MOCK_SCRIPT"
+
+SKILL_DIR="$SCRIPT_DIR"
+
+echo "=== TL schedule-check tests ==="
+
+# -----------------------------------------------------------------------
+# Scenario 1: TL schedules self-check using sessionName param
+#   (CREWLY_SESSION_NAME not set — Gemini CLI scenario)
+# -----------------------------------------------------------------------
+echo "Scenario 1: TL self-check via sessionName param (no env var)"
+assert_succeeds "self-check with sessionName, no CREWLY_SESSION_NAME" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":15,"message":"Follow up on progress","sessionName":"crewly-marketing-ella-abc123"}'
+
+# -----------------------------------------------------------------------
+# Scenario 2: TL schedules self-check using CREWLY_SESSION_NAME env var
+# -----------------------------------------------------------------------
+echo "Scenario 2: TL self-check via CREWLY_SESSION_NAME env var"
+assert_succeeds "self-check with CREWLY_SESSION_NAME set" \
+  env CREWLY_SESSION_NAME="crewly-marketing-ella-abc123" bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":15,"message":"Follow up on progress"}'
+
+# -----------------------------------------------------------------------
+# Scenario 3: TL schedules self-check with explicit target = self session
+# -----------------------------------------------------------------------
+echo "Scenario 3: TL self-check with explicit target = own session"
+assert_succeeds "self-check with explicit target matching sessionName" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":15,"message":"Follow up","sessionName":"crewly-marketing-ella-abc123","target":"crewly-marketing-ella-abc123"}'
+
+# -----------------------------------------------------------------------
+# Scenario 4: TL schedules worker check — valid subordinate
+# -----------------------------------------------------------------------
+echo "Scenario 4: TL schedules check on valid subordinate"
+assert_succeeds "worker check on subordinate mila" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":10,"message":"Check mila progress","sessionName":"crewly-marketing-ella-abc123","target":"crewly-marketing-mila-def456","teamId":"team-123","tlMemberId":"tl-001"}'
+
+# -----------------------------------------------------------------------
+# Scenario 5: TL targets non-subordinate — hierarchy violation
+# -----------------------------------------------------------------------
+echo "Scenario 5: TL targets non-subordinate worker"
+assert_fails_with "hierarchy violation on non-subordinate luna" "Hierarchy violation" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":10,"message":"Check luna","sessionName":"crewly-marketing-ella-abc123","target":"crewly-marketing-luna-ghi789","teamId":"team-123","tlMemberId":"tl-001"}'
+
+# -----------------------------------------------------------------------
+# Scenario 6: TL targets unknown session — not a member
+# -----------------------------------------------------------------------
+echo "Scenario 6: TL targets unknown session"
+assert_fails_with "hierarchy violation on unknown target" "Hierarchy violation" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":10,"message":"Check unknown","sessionName":"crewly-marketing-ella-abc123","target":"crewly-unknown-agent","teamId":"team-123","tlMemberId":"tl-001"}'
+
+# -----------------------------------------------------------------------
+# Scenario 7: TL targets other session without teamId — error
+# -----------------------------------------------------------------------
+echo "Scenario 7: Missing teamId/tlMemberId for other-session target"
+assert_fails_with "requires teamId and tlMemberId" "teamId and tlMemberId are required" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":10,"message":"Check worker","sessionName":"crewly-marketing-ella-abc123","target":"crewly-marketing-mila-def456"}'
+
+# -----------------------------------------------------------------------
+# Scenario 8: No session identity at all — should fail
+# -----------------------------------------------------------------------
+echo "Scenario 8: No session identity (no env, no sessionName, no target)"
+assert_fails_with "fails without any session identity" "No target session specified" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":10,"message":"Check something"}'
+
+# -----------------------------------------------------------------------
+# Scenario 9: Missing required params
+# -----------------------------------------------------------------------
+echo "Scenario 9: Missing required params"
+assert_fails "fails on missing minutes" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"message":"Check","sessionName":"ella"}'
+
+assert_fails "fails on missing message" \
+  env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":10,"sessionName":"ella"}'
+
+# -----------------------------------------------------------------------
+# Scenario 10: Recurring check self-scheduling
+# -----------------------------------------------------------------------
+echo "Scenario 10: Recurring self-check"
+OUTPUT=$(env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"minutes":15,"message":"Recurring follow up","sessionName":"crewly-marketing-ella-abc123","recurring":true}')
+if echo "$OUTPUT" | jq -e '.success' > /dev/null 2>&1; then
+  echo "  PASS: recurring self-check succeeds"
+  PASS=$((PASS + 1))
+else
+  echo "  FAIL: recurring self-check failed (output: $OUTPUT)"
+  FAIL=$((FAIL + 1))
+fi
+
+# Cleanup
+rm -rf "$MOCK_DIR"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/config/skills/team-leader/schedule-check/instructions.md

@@ -0,0 +1,49 @@
+# Schedule Check (Team Leader)
+
+Schedule a future check-in reminder. Unlike the orchestrator version, this skill enforces hierarchy — you can only schedule checks targeting yourself or your subordinate workers.
+
+## Usage
+
+### Self-reminder (default target)
+```bash
+bash config/skills/team-leader/schedule-check/execute.sh '{"minutes":5,"message":"Check worker progress on feature X","sessionName":"my-session-name"}'
+```
+
+### Target a specific subordinate
+```bash
+bash config/skills/team-leader/schedule-check/execute.sh '{"minutes":10,"message":"Status update needed","target":"worker-session-name","teamId":"team-123","tlMemberId":"tl-member-id"}'
+```
+
+### Recurring check
+```bash
+bash config/skills/team-leader/schedule-check/execute.sh '{"minutes":10,"message":"Periodic progress check","recurring":true,"maxOccurrences":6}'
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `minutes` | Yes | Delay in minutes before the check fires |
+| `message` | Yes | Reminder message text |
+| `target` | No | Target session name (defaults to self). Must be self or a subordinate |
+| `sessionName` | No | Caller's own session name. Used as fallback when `CREWLY_SESSION_NAME` env var is not set (e.g. Gemini CLI) |
+| `recurring` | No | When `true`, the check repeats every `minutes` interval (default: `false`) |
+| `maxOccurrences` | No | Max times a recurring check fires (default: unlimited). Only for `recurring: true` |
+| `teamId` | Conditional | Required when targeting a subordinate (for hierarchy validation) |
+| `tlMemberId` | Conditional | Required when targeting a subordinate (your member ID for hierarchy validation) |
+
+## Hierarchy Rules
+
+- **Self target**: Always allowed — no `teamId`/`tlMemberId` needed. Pass `sessionName` if `CREWLY_SESSION_NAME` env var is not available
+- **Subordinate target**: Requires `teamId` and `tlMemberId`. The script verifies the target's `parentMemberId` matches your `tlMemberId`
+- **Non-subordinate target**: Rejected with hierarchy violation error
+
+## Output
+
+JSON with the scheduled check ID and fire time.
+
+## Best Practices
+
+- **Use `maxOccurrences`** for time-bounded tasks to prevent stale schedules
+- **Include worker name and task context** in the message for quick triage when the check fires
+- **Prefer self-targeted checks** — schedule reminders to yourself to review worker status rather than interrupting workers directly

package/config/skills/team-leader/schedule-check/skill.json

@@ -0,0 +1,20 @@
+{
+  "id": "tl-schedule-check",
+  "name": "Schedule Check (TL)",
+  "description": "Schedule a future check-in or reminder. TL can only target self or subordinate workers (hierarchy-validated).",
+  "category": "monitoring",
+  "skillType": "claude-skill",
+  "promptFile": "instructions.md",
+  "execution": {
+    "type": "script",
+    "script": {
+      "file": "execute.sh",
+      "interpreter": "bash",
+      "timeoutMs": 15000
+    }
+  },
+  "assignableRoles": ["team-leader"],
+  "triggers": ["schedule check", "remind me", "check in later", "follow up"],
+  "tags": ["scheduling", "monitoring", "reminder", "hierarchy"],
+  "version": "1.0.0"
+}

package/config/skills/team-leader/start-agent/execute.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Start a worker agent within this Team Leader's subordinate scope.
+# Validates hierarchy (worker.parentMemberId == TL.memberId) before starting.
+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-uuid\",\"memberId\":\"member-uuid\",\"tlMemberId\":\"tl-member-id\"}'"
+
+TEAM_ID=$(echo "$INPUT" | jq -r '.teamId // empty')
+MEMBER_ID=$(echo "$INPUT" | jq -r '.memberId // empty')
+TL_MEMBER_ID=$(echo "$INPUT" | jq -r '.tlMemberId // empty')
+require_param "teamId" "$TEAM_ID"
+require_param "memberId" "$MEMBER_ID"
+require_param "tlMemberId" "$TL_MEMBER_ID"
+
+# Validate hierarchy: target worker must be a subordinate of this TL
+TEAM_DATA=$(api_call GET "/teams/${TEAM_ID}" 2>/dev/null || echo '{}')
+TEAM_SUCCESS=$(echo "$TEAM_DATA" | jq -r '.success // false' 2>/dev/null || echo "false")
+
+if [ "$TEAM_SUCCESS" != "true" ]; then
+  error_exit "Failed to fetch team data for team ${TEAM_ID}"
+fi
+
+# Find the target member and check parentMemberId
+WORKER_PARENT=$(echo "$TEAM_DATA" | jq -r --arg mid "$MEMBER_ID" \
+  '.data.members[] | select(.id == $mid) | .parentMemberId // empty' 2>/dev/null || true)
+
+if [ -z "$WORKER_PARENT" ]; then
+  error_exit "Member ${MEMBER_ID} not found in team ${TEAM_ID} or has no parentMemberId set"
+fi
+
+if [ "$WORKER_PARENT" != "$TL_MEMBER_ID" ]; then
+  error_exit "Hierarchy violation: member ${MEMBER_ID} (parentMemberId=${WORKER_PARENT}) is not a subordinate of TL ${TL_MEMBER_ID}"
+fi
+
+# Hierarchy validated — start the agent
+api_call POST "/teams/${TEAM_ID}/members/${MEMBER_ID}/start"

package/config/skills/team-leader/start-agent/instructions.md

@@ -0,0 +1,48 @@
+# Start Agent (TL Version)
+
+Starts a worker agent within the Team Leader's subordinate scope. Validates hierarchy before starting — the target worker's `parentMemberId` must match the TL's `memberId`.
+
+## When to Use
+
+- When a worker needs to be activated for task assignment
+- After a worker was previously stopped and needs to be restarted
+- When scaling up the sub-team for a new objective
+
+## Usage
+
+```bash
+bash {{TL_SKILLS_PATH}}/start-agent/execute.sh '{"teamId":"{{TEAM_ID}}","memberId":"worker-member-uuid","tlMemberId":"{{MEMBER_ID}}"}'
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `teamId` | Yes | The team's UUID |
+| `memberId` | Yes | The target worker's member UUID |
+| `tlMemberId` | Yes | The TL's own member ID for hierarchy validation |
+
+## Hierarchy Validation
+
+The script fetches team data and validates:
+- The target member exists in the team
+- The member's `parentMemberId` matches the TL's `memberId`
+
+If validation fails, the start is rejected with a hierarchy violation error. TLs can only start their own subordinates — not agents in other teams or under other TLs.
+
+## Differences from Orchestrator start-agent
+
+| Aspect | Orchestrator | Team Leader |
+|--------|-------------|-------------|
+| Scope | Any agent in any team | Only subordinates |
+| Hierarchy check | None | Validates parentMemberId |
+| Extra parameter | None | `tlMemberId` required |
+
+## Output
+
+JSON confirmation with agent startup status, same format as orchestrator start-agent.
+
+## Related Skills
+
+- `stop-agent` — Stop a subordinate worker
+- `delegate-task` — Assign tasks to workers after starting them

package/config/skills/team-leader/start-agent/skill.json

@@ -0,0 +1,20 @@
+{
+  "id": "tl-start-agent",
+  "name": "Start Agent (TL)",
+  "description": "Start a worker agent within the Team Leader's subordinate scope. Validates that the target worker's parentMemberId matches the TL's memberId before starting.",
+  "category": "management",
+  "skillType": "claude-skill",
+  "promptFile": "instructions.md",
+  "execution": {
+    "type": "script",
+    "script": {
+      "file": "execute.sh",
+      "interpreter": "bash",
+      "timeoutMs": 60000
+    }
+  },
+  "assignableRoles": ["team-leader"],
+  "triggers": ["start agent", "start worker", "activate worker", "boot worker"],
+  "tags": ["agent", "management", "lifecycle", "hierarchy"],
+  "version": "1.0.0"
+}

package/config/skills/team-leader/stop-agent/execute.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Stop a worker agent within this Team Leader's subordinate scope.
+# Validates hierarchy (worker.parentMemberId == TL.memberId) before stopping.
+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-uuid\",\"memberId\":\"member-uuid\",\"tlMemberId\":\"tl-member-id\"}'"
+
+TEAM_ID=$(echo "$INPUT" | jq -r '.teamId // empty')
+MEMBER_ID=$(echo "$INPUT" | jq -r '.memberId // empty')
+TL_MEMBER_ID=$(echo "$INPUT" | jq -r '.tlMemberId // empty')
+require_param "teamId" "$TEAM_ID"
+require_param "memberId" "$MEMBER_ID"
+require_param "tlMemberId" "$TL_MEMBER_ID"
+
+# Validate hierarchy: target worker must be a subordinate of this TL
+TEAM_DATA=$(api_call GET "/teams/${TEAM_ID}" 2>/dev/null || echo '{}')
+TEAM_SUCCESS=$(echo "$TEAM_DATA" | jq -r '.success // false' 2>/dev/null || echo "false")
+
+if [ "$TEAM_SUCCESS" != "true" ]; then
+  error_exit "Failed to fetch team data for team ${TEAM_ID}"
+fi
+
+# Find the target member and check parentMemberId
+WORKER_PARENT=$(echo "$TEAM_DATA" | jq -r --arg mid "$MEMBER_ID" \
+  '.data.members[] | select(.id == $mid) | .parentMemberId // empty' 2>/dev/null || true)
+
+if [ -z "$WORKER_PARENT" ]; then
+  error_exit "Member ${MEMBER_ID} not found in team ${TEAM_ID} or has no parentMemberId set"
+fi
+
+if [ "$WORKER_PARENT" != "$TL_MEMBER_ID" ]; then
+  error_exit "Hierarchy violation: member ${MEMBER_ID} (parentMemberId=${WORKER_PARENT}) is not a subordinate of TL ${TL_MEMBER_ID}"
+fi
+
+# Hierarchy validated — stop the agent
+api_call POST "/teams/${TEAM_ID}/members/${MEMBER_ID}/stop"