crewly 1.5.17 → 1.5.19

package/config/skills/agent/core/poll-tasks/execute.sh

@@ -0,0 +1,182 @@
+#!/bin/bash
+# =============================================================================
+# poll-tasks — Agent polls the Task Pool for available work and claims a match
+#
+# An idle agent calls this skill to find and claim work from the Task Pool.
+# The skill queries available WorkItems, filters by agent capabilities, and
+# claims the first matching item. Returns the claimed WorkItem for execution.
+#
+# Usage:
+#   bash execute.sh '{"sessionName":"agent-1","role":"developer","skills":["typescript","react"]}'
+#
+# Parameters:
+#   sessionName  (required) — Agent session name used as claimant ID
+#   role         (optional) — Agent role for capability matching (developer, researcher, etc.)
+#   skills       (optional) — JSON array of skill tags for fine-grained matching
+#   types        (optional) — Comma-separated WorkItemTypes to filter (default: delegate,project_task,review)
+#   projectPath  (optional) — Project path for memory persistence
+#
+# Returns:
+#   On claim: { success: true, claimed: true, workItem: {...}, claim: {...} }
+#   No match: { success: true, claimed: false, available: 0, message: "..." }
+#   Error:    { error: "..." } on stderr, exit 1
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+INPUT=$(read_json_input "${1:-}")
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"sessionName\":\"agent-1\",\"role\":\"developer\"}'"
+
+# ---------------------------------------------------------------------------
+# Parse parameters
+# ---------------------------------------------------------------------------
+
+SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
+require_param "sessionName" "$SESSION_NAME"
+
+ROLE=$(printf '%s' "$INPUT" | jq -r '.role // empty')
+SKILLS_JSON=$(printf '%s' "$INPUT" | jq -c '.skills // []')
+TYPES=$(printf '%s' "$INPUT" | jq -r '.types // empty')
+PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+
+# ---------------------------------------------------------------------------
+# Defaults — which WorkItemTypes this agent can handle, keyed by role
+# ---------------------------------------------------------------------------
+
+if [ -z "$TYPES" ]; then
+  case "${ROLE}" in
+    developer)
+      TYPES="delegate,project_task,review"
+      ;;
+    researcher|analyst)
+      TYPES="delegate,check,review"
+      ;;
+    team_lead|team-lead)
+      TYPES="delegate,project_task,review,check"
+      ;;
+    *)
+      # Sensible default: delegate + project_task
+      TYPES="delegate,project_task"
+      ;;
+  esac
+fi
+
+# ---------------------------------------------------------------------------
+# Step 1: Query available WorkItems from Task Pool
+# ---------------------------------------------------------------------------
+
+QUERY_PARAMS="?types=${TYPES}&owner=agent"
+
+AVAILABLE_RESPONSE=$(api_call GET "/task-pool${QUERY_PARAMS}" 2>&1) || {
+  # Also try without owner filter — some items may target specific agents
+  AVAILABLE_RESPONSE=$(api_call GET "/task-pool?types=${TYPES}&target=${SESSION_NAME}" 2>&1) || {
+    error_exit "Failed to query Task Pool: ${AVAILABLE_RESPONSE}"
+  }
+}
+
+AVAILABLE_COUNT=$(printf '%s' "$AVAILABLE_RESPONSE" | jq -r '.count // 0')
+
+if [ "$AVAILABLE_COUNT" -eq 0 ]; then
+  # No available work — return early
+  jq -n \
+    --argjson count "$AVAILABLE_COUNT" \
+    '{success: true, claimed: false, available: $count, message: "No available work items matching agent capabilities"}'
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2: Skill-based filtering (client-side)
+#
+# If the agent declared skills (e.g. ["typescript","react"]), we check each
+# available item's title + description for keyword overlap. Items whose
+# title/description contain at least one of the agent's skills are preferred.
+# If no skill-matched item exists, fall back to FIFO (server default).
+# ---------------------------------------------------------------------------
+
+SKILL_COUNT=$(printf '%s' "$SKILLS_JSON" | jq 'length')
+
+if [ "$SKILL_COUNT" -gt 0 ]; then
+  # Build a regex pattern from skills: typescript|react|...
+  SKILL_PATTERN=$(printf '%s' "$SKILLS_JSON" | jq -r 'map(ascii_downcase) | join("|")')
+
+  # Find first item whose title or description matches agent skills
+  MATCHED_ITEM=$(printf '%s' "$AVAILABLE_RESPONSE" | jq -c --arg pat "$SKILL_PATTERN" '
+    .data // [] |
+    map(select(
+      ((.title // "") | ascii_downcase | test($pat)) or
+      ((.description // "") | ascii_downcase | test($pat))
+    )) |
+    first // null
+  ')
+
+  if [ "$MATCHED_ITEM" != "null" ] && [ -n "$MATCHED_ITEM" ]; then
+    # Use target filter to claim this specific item if it has a target
+    MATCHED_ID=$(printf '%s' "$MATCHED_ITEM" | jq -r '.id')
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 3: Claim from the Task Pool
+#
+# The POST /api/task-pool/claim endpoint handles FIFO selection server-side.
+# We pass our agentId and filters so the server picks the best match.
+# ---------------------------------------------------------------------------
+
+CLAIM_BODY=$(jq -n \
+  --arg agentId "$SESSION_NAME" \
+  --arg types "$TYPES" \
+  '{
+    agentId: $agentId,
+    filters: {
+      types: ($types | split(","))
+    }
+  }')
+
+CLAIM_RESPONSE=$(api_call POST "/task-pool/claim" "$CLAIM_BODY" 2>&1) || {
+  CLAIM_ERROR="$CLAIM_RESPONSE"
+  # 404 = no available items (race condition — someone else claimed it)
+  if printf '%s' "$CLAIM_ERROR" | grep -q '"status":404'; then
+    jq -n '{success: true, claimed: false, available: 0, message: "No work items available (claimed by another agent)"}'
+    exit 0
+  fi
+  error_exit "Failed to claim from Task Pool: ${CLAIM_ERROR}"
+}
+
+# ---------------------------------------------------------------------------
+# Step 4: Extract result and return
+# ---------------------------------------------------------------------------
+
+WORK_ITEM=$(printf '%s' "$CLAIM_RESPONSE" | jq -c '.data.workItem // null')
+CLAIM_OBJ=$(printf '%s' "$CLAIM_RESPONSE" | jq -c '.data.claim // null')
+
+if [ "$WORK_ITEM" = "null" ] || [ -z "$WORK_ITEM" ]; then
+  jq -n '{success: true, claimed: false, available: 0, message: "Claim returned no work item"}'
+  exit 0
+fi
+
+WORK_ITEM_TITLE=$(printf '%s' "$WORK_ITEM" | jq -r '.title // "untitled"')
+WORK_ITEM_ID=$(printf '%s' "$WORK_ITEM" | jq -r '.id // "unknown"')
+CLAIM_ID=$(printf '%s' "$CLAIM_OBJ" | jq -r '.id // "unknown"')
+
+# Persist the claim as a learning so the agent recovers context on restart
+if [ -n "$PROJECT_PATH" ]; then
+  auto_remember "$SESSION_NAME" \
+    "Claimed WorkItem '${WORK_ITEM_TITLE}' (id: ${WORK_ITEM_ID}, claim: ${CLAIM_ID}) from Task Pool" \
+    "fact" "agent" "$PROJECT_PATH"
+fi
+
+# Return structured result
+jq -n \
+  --argjson workItem "$WORK_ITEM" \
+  --argjson claim "$CLAIM_OBJ" \
+  --arg workItemId "$WORK_ITEM_ID" \
+  --arg claimId "$CLAIM_ID" \
+  '{
+    success: true,
+    claimed: true,
+    workItemId: $workItemId,
+    claimId: $claimId,
+    workItem: $workItem,
+    claim: $claim
+  }'

package/config/skills/agent/core/poll-tasks/execute.test.sh

@@ -0,0 +1,215 @@
+#!/bin/bash
+# =============================================================================
+# Tests for poll-tasks skill
+#
+# Tests verify parameter validation, API call construction, and output format.
+# Uses mock api_call to simulate backend responses without a running server.
+# =============================================================================
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0
+FAIL=0
+ERRORS=""
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+assert_eq() {
+  local test_name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    ERRORS="${ERRORS}\n  ✗ ${test_name}\n    expected: ${expected}\n    actual:   ${actual}"
+    echo "  ✗ ${test_name}"
+    echo "    expected: ${expected}"
+    echo "    actual:   ${actual}"
+  fi
+}
+
+assert_contains() {
+  local test_name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -q "$needle"; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    ERRORS="${ERRORS}\n  ✗ ${test_name}\n    expected to contain: ${needle}\n    actual: ${haystack}"
+    echo "  ✗ ${test_name}"
+    echo "    expected to contain: ${needle}"
+    echo "    actual: ${haystack}"
+  fi
+}
+
+assert_json_field() {
+  local test_name="$1" json="$2" field="$3" expected="$4"
+  local actual
+  actual=$(printf '%s' "$json" | jq -r "$field" 2>/dev/null || echo "PARSE_ERROR")
+  assert_eq "$test_name" "$expected" "$actual"
+}
+
+# ---------------------------------------------------------------------------
+# Test 1: Missing sessionName should fail
+# ---------------------------------------------------------------------------
+echo "Test 1: Missing sessionName should fail"
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" '{}' 2>&1) && EXIT_CODE=$? || EXIT_CODE=$?
+assert_eq "exits with error code" "1" "$EXIT_CODE"
+assert_contains "error mentions sessionName" "sessionName" "$OUTPUT"
+
+# ---------------------------------------------------------------------------
+# Test 2: Empty input should fail
+# ---------------------------------------------------------------------------
+echo "Test 2: Empty input should fail"
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" '' 2>&1) && EXIT_CODE=$? || EXIT_CODE=$?
+assert_eq "exits with error code" "1" "$EXIT_CODE"
+
+# ---------------------------------------------------------------------------
+# Test 3: Role-based type defaults
+# ---------------------------------------------------------------------------
+echo "Test 3: Role-based type defaults"
+
+get_types_for_role() {
+  local role="$1"
+  local types=""
+  case "${role}" in
+    developer)
+      types="delegate,project_task,review"
+      ;;
+    researcher|analyst)
+      types="delegate,check,review"
+      ;;
+    team_lead|team-lead)
+      types="delegate,project_task,review,check"
+      ;;
+    *)
+      types="delegate,project_task"
+      ;;
+  esac
+  echo "$types"
+}
+
+assert_eq "developer types" "delegate,project_task,review" "$(get_types_for_role developer)"
+assert_eq "researcher types" "delegate,check,review" "$(get_types_for_role researcher)"
+assert_eq "analyst types" "delegate,check,review" "$(get_types_for_role analyst)"
+assert_eq "team_lead types" "delegate,project_task,review,check" "$(get_types_for_role team_lead)"
+assert_eq "team-lead types" "delegate,project_task,review,check" "$(get_types_for_role team-lead)"
+assert_eq "unknown role types" "delegate,project_task" "$(get_types_for_role designer)"
+
+# ---------------------------------------------------------------------------
+# Test 4: Skill matching logic
+# ---------------------------------------------------------------------------
+echo "Test 4: Skill matching logic"
+
+ITEMS='[
+  {"id":"item-1","title":"Implement Python scraper","description":"Write a data scraper in Python","status":"queued"},
+  {"id":"item-2","title":"Build React dashboard","description":"Create a TypeScript React component","status":"queued"},
+  {"id":"item-3","title":"Write Rust parser","description":"Parser for log files in Rust","status":"queued"}
+]'
+SKILLS='["typescript","react"]'
+PATTERN=$(printf '%s' "$SKILLS" | jq -r 'map(ascii_downcase) | join("|")')
+
+# Should match item-2 (React/TypeScript)
+MATCHED=$(printf '%s' "$ITEMS" | jq -c --arg pat "$PATTERN" '
+  map(select(
+    ((.title // "") | ascii_downcase | test($pat)) or
+    ((.description // "") | ascii_downcase | test($pat))
+  )) | first // null
+')
+MATCHED_ID=$(printf '%s' "$MATCHED" | jq -r '.id')
+assert_eq "skill match finds React/TS item" "item-2" "$MATCHED_ID"
+
+# No matching skills
+SKILLS_NONE='["java","golang"]'
+PATTERN_NONE=$(printf '%s' "$SKILLS_NONE" | jq -r 'map(ascii_downcase) | join("|")')
+MATCHED_NONE=$(printf '%s' "$ITEMS" | jq -c --arg pat "$PATTERN_NONE" '
+  map(select(
+    ((.title // "") | ascii_downcase | test($pat)) or
+    ((.description // "") | ascii_downcase | test($pat))
+  )) | first // null
+')
+assert_eq "no skill match returns null" "null" "$MATCHED_NONE"
+
+# Match by description only (TypeScript is in description of item-2)
+SKILLS_DESC='["typescript"]'
+PATTERN_DESC=$(printf '%s' "$SKILLS_DESC" | jq -r 'map(ascii_downcase) | join("|")')
+MATCHED_DESC=$(printf '%s' "$ITEMS" | jq -c --arg pat "$PATTERN_DESC" '
+  map(select(
+    ((.title // "") | ascii_downcase | test($pat)) or
+    ((.description // "") | ascii_downcase | test($pat))
+  )) | first // null
+')
+MATCHED_DESC_ID=$(printf '%s' "$MATCHED_DESC" | jq -r '.id')
+assert_eq "skill match by description" "item-2" "$MATCHED_DESC_ID"
+
+# ---------------------------------------------------------------------------
+# Test 5: Output format for no-work scenario
+# ---------------------------------------------------------------------------
+echo "Test 5: Output format validation"
+
+# Simulate no-work output
+NO_WORK_OUTPUT=$(jq -n '{success: true, claimed: false, available: 0, message: "No available work items matching agent capabilities"}')
+assert_json_field "success is true" "$NO_WORK_OUTPUT" ".success" "true"
+assert_json_field "claimed is false" "$NO_WORK_OUTPUT" ".claimed" "false"
+assert_json_field "available is 0" "$NO_WORK_OUTPUT" ".available" "0"
+assert_contains "message present" "No available" "$NO_WORK_OUTPUT"
+
+# Simulate claimed output
+CLAIMED_OUTPUT=$(jq -n '
+  {
+    success: true,
+    claimed: true,
+    workItemId: "wi-123",
+    claimId: "cl-456",
+    workItem: {id: "wi-123", title: "Test task", type: "delegate"},
+    claim: {id: "cl-456", agentId: "test-agent"}
+  }')
+assert_json_field "claim success" "$CLAIMED_OUTPUT" ".success" "true"
+assert_json_field "claim claimed" "$CLAIMED_OUTPUT" ".claimed" "true"
+assert_json_field "workItemId" "$CLAIMED_OUTPUT" ".workItemId" "wi-123"
+assert_json_field "claimId" "$CLAIMED_OUTPUT" ".claimId" "cl-456"
+assert_json_field "workItem.title" "$CLAIMED_OUTPUT" ".workItem.title" "Test task"
+assert_json_field "workItem.type" "$CLAIMED_OUTPUT" ".workItem.type" "delegate"
+assert_json_field "claim.agentId" "$CLAIMED_OUTPUT" ".claim.agentId" "test-agent"
+
+# ---------------------------------------------------------------------------
+# Test 6: Custom types parameter overrides role defaults
+# ---------------------------------------------------------------------------
+echo "Test 6: Custom types override"
+
+# When types is explicitly set, role default should NOT apply
+TYPES_EXPLICIT="check,notify"
+ROLE="developer"
+if [ -n "$TYPES_EXPLICIT" ]; then
+  FINAL_TYPES="$TYPES_EXPLICIT"
+else
+  FINAL_TYPES="$(get_types_for_role "$ROLE")"
+fi
+assert_eq "explicit types override role default" "check,notify" "$FINAL_TYPES"
+
+# When types is empty, role default applies
+TYPES_EMPTY=""
+ROLE="developer"
+if [ -n "$TYPES_EMPTY" ]; then
+  FINAL_TYPES2="$TYPES_EMPTY"
+else
+  FINAL_TYPES2="$(get_types_for_role "$ROLE")"
+fi
+assert_eq "empty types uses role default" "delegate,project_task,review" "$FINAL_TYPES2"
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "======================================="
+echo "Results: ${PASS} passed, ${FAIL} failed"
+echo "======================================="
+
+if [ $FAIL -gt 0 ]; then
+  echo -e "\nFailures:${ERRORS}"
+  exit 1
+fi
+
+exit 0

package/config/skills/agent/core/register-self/execute.sh

@@ -1,29 +1,117 @@
 #!/bin/bash
 # Register an agent with the Crewly backend
+# Supports both CLI flags (preferred) and legacy JSON argument.
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
 
-INPUT=$(read_json_input "${1:-}")
-[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"role\":\"developer\",\"sessionName\":\"dev-1\"}' or echo '{...}' | execute.sh"
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  # CLI flags (preferred — avoids shell escaping issues)
+  bash execute.sh --session dev-1 --role developer
 
-# Accept both canonical (role/sessionName) and legacy (agentRole/agentId) parameter names
-ROLE=$(printf '%s' "$INPUT" | jq -r '.role // .agentRole // empty')
-SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // .agentId // empty')
-require_param "role" "$ROLE"
-require_param "sessionName" "$SESSION_NAME"
+  # Legacy JSON argument (backward compatible)
+  bash execute.sh '{"sessionName":"dev-1","role":"developer"}'
 
-# Optional: claudeSessionId for resume support
-CLAUDE_SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.claudeSessionId // empty')
-TEAM_MEMBER_ID=$(printf '%s' "$INPUT" | jq -r '.teamMemberId // empty')
+Options:
+  --session  | -s   Agent session name (required)
+  --role     | -r   Agent role: product-manager, developer, etc. (required)
+  --team-member     Team member UUID (optional)
+  --claude-session  Claude session ID for resume support (optional)
+  --json     | -j   Raw JSON payload (same as legacy)
+  --help     | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+SESSION_NAME=""
+ROLE=""
+TEAM_MEMBER_ID=""
+CLAUDE_SESSION_ID=""
+
+# Detect legacy JSON argument as the first parameter
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session|-s)
+      SESSION_NAME="$2"
+      shift 2
+      ;;
+    --role|-r)
+      ROLE="$2"
+      shift 2
+      ;;
+    --team-member)
+      TEAM_MEMBER_ID="$2"
+      shift 2
+      ;;
+    --claude-session)
+      CLAUDE_SESSION_ID="$2"
+      shift 2
+      ;;
+    --json|-j)
+      INPUT_JSON="$2"
+      shift 2
+      ;;
+    --help|-h)
+      print_usage
+      exit 0
+      ;;
+    --)
+      shift
+      break
+      ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then
+        INPUT_JSON="$1"
+        shift
+      else
+        error_exit "Unknown argument: $1. Use --help for usage."
+      fi
+      ;;
+  esac
+done
+
+# If nothing provided yet but stdin has data, read it as JSON
+if [ -z "$INPUT_JSON" ] && [ -z "$SESSION_NAME" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  fi
+fi
+
+# Parse JSON input if provided (backward compatible)
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$SESSION_NAME" ] && SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // .agentId // empty')
+  [ -z "$ROLE" ] && ROLE=$(printf '%s' "$INPUT" | jq -r '.role // .agentRole // empty')
+  [ -z "$TEAM_MEMBER_ID" ] && TEAM_MEMBER_ID=$(printf '%s' "$INPUT" | jq -r '.teamMemberId // empty')
+  [ -z "$CLAUDE_SESSION_ID" ] && CLAUDE_SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.claudeSessionId // empty')
+fi
+
+require_param "sessionName (--session)" "$SESSION_NAME"
+require_param "role (--role)" "$ROLE"
+
+# Build body using env vars for safe escaping
+export _REG_ROLE="$ROLE"
+export _REG_SESSION="$SESSION_NAME"
+export _REG_CLAUDE="$CLAUDE_SESSION_ID"
+export _REG_MEMBER="$TEAM_MEMBER_ID"
 
 BODY=$(jq -n \
-  --arg role "$ROLE" \
-  --arg sessionName "$SESSION_NAME" \
-  --arg claudeSessionId "$CLAUDE_SESSION_ID" \
-  --arg teamMemberId "$TEAM_MEMBER_ID" \
+  --arg role "$_REG_ROLE" \
+  --arg sessionName "$_REG_SESSION" \
+  --arg claudeSessionId "$_REG_CLAUDE" \
+  --arg teamMemberId "$_REG_MEMBER" \
   '{role: $role, sessionName: $sessionName} +
    (if $claudeSessionId != "" then {claudeSessionId: $claudeSessionId} else {} end) +
    (if $teamMemberId != "" then {teamMemberId: $teamMemberId} else {} end)')
 
+unset _REG_ROLE _REG_SESSION _REG_CLAUDE _REG_MEMBER
+
 api_call POST "/teams/members/register" "$BODY"

package/config/skills/agent/core/release-claim/execute.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# =============================================================================
+# release-claim — Release an active claim back to the Task Pool
+#
+# When an agent finishes a task or cannot continue, it releases its claim
+# so the work item can be re-queued or marked as done/failed.
+#
+# Usage:
+#   bash execute.sh '{"workItemId":"wi-abc","reason":"completed"}'
+#
+# Parameters:
+#   workItemId   (required) — The work item ID to release
+#   reason       (required) — Why the claim is being released
+#                             Use "completed" for finished tasks,
+#                             "cannot_complete" for blocked tasks,
+#                             "reassign" for hand-off to another agent
+#
+# Returns:
+#   Success: { success: true, released: true }
+#   Error:   { success: false, reason: "..." }
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+INPUT=$(read_json_input "${1:-}")
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"wi-abc\",\"reason\":\"completed\"}'"
+
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
+REASON=$(printf '%s' "$INPUT" | jq -r '.reason // empty')
+require_param "workItemId" "$WORK_ITEM_ID"
+require_param "reason" "$REASON"
+
+# ---------------------------------------------------------------------------
+# Release the work item back to the pool
+# ---------------------------------------------------------------------------
+
+BODY=$(jq -n --arg reason "$REASON" '{reason: $reason}')
+
+RESPONSE=$(api_call POST "/task-pool/release/${WORK_ITEM_ID}" "$BODY" 2>&1) || {
+  ERROR_MSG=$(printf '%s' "$RESPONSE" | jq -r '.error // .message // "Unknown error"' 2>/dev/null || echo "$RESPONSE")
+  jq -n --arg reason "$ERROR_MSG" '{success: false, reason: $reason}'
+  exit 0
+}
+
+SUCCESS=$(printf '%s' "$RESPONSE" | jq -r '.success // false')
+
+if [ "$SUCCESS" = "true" ]; then
+  jq -n '{success: true, released: true}'
+else
+  ERROR=$(printf '%s' "$RESPONSE" | jq -r '.error // .message // "Release failed"')
+  jq -n --arg reason "$ERROR" '{success: false, reason: $reason}'
+fi

package/config/skills/agent/core/release-claim/execute.test.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# =============================================================================
+# Tests for release-claim skill
+#
+# Verifies parameter validation and output format.
+# =============================================================================
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0
+FAIL=0
+ERRORS=""
+
+assert_contains() {
+  local test_name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -q "$needle"; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    ERRORS="${ERRORS}\n  ✗ ${test_name}\n    expected to contain: ${needle}\n    actual: ${haystack}"
+    echo "  ✗ ${test_name}"
+    echo "    expected to contain: ${needle}"
+  fi
+}
+
+echo "=== release-claim tests ==="
+
+echo ""
+echo "--- Missing parameters ---"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" '{"reason":"completed"}' 2>&1) || true
+assert_contains "Missing workItemId returns error" "workItemId" "$OUTPUT"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" '{"workItemId":"wi-1"}' 2>&1) || true
+assert_contains "Missing reason returns error" "reason" "$OUTPUT"
+
+OUTPUT=$(bash "$SCRIPT_DIR/execute.sh" '' 2>&1) || true
+assert_contains "Empty input returns usage error" "Usage" "$OUTPUT"
+
+echo ""
+echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
+if [ $FAIL -gt 0 ]; then
+  echo -e "\nFailures:${ERRORS}"
+  exit 1
+fi