crewly 1.5.15 → 1.5.17

package/config/skills/agent/core/report-status/execute.sh

@@ -1,26 +1,149 @@
 #!/bin/bash
 # Report task status to the orchestrator
+# 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 '{\"sessionName\":\"dev-1\",\"status\":\"done\",\"summary\":\"...\"}' or echo '{...}' | execute.sh"
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  # CLI flags (preferred — avoids shell escaping issues)
+  bash execute.sh --session dev-1 --status done --summary "Fixed the bug" --project /path/to/project
 
-SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
-STATUS=$(printf '%s' "$INPUT" | jq -r '.status // empty')
-SUMMARY=$(printf '%s' "$INPUT" | jq -r '.summary // empty')
-TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.taskPath // empty')
-require_param "sessionName" "$SESSION_NAME"
-require_param "status" "$STATUS"
-require_param "summary" "$SUMMARY"
+  # Summary from stdin (for multi-line or special characters)
+  echo "Fixed the bug — it's working" | bash execute.sh --session dev-1 --status done --project /path
 
-# Optional structured StatusReport fields (for hierarchical workflows)
-TASK_ID=$(printf '%s' "$INPUT" | jq -r '.taskId // empty')
-PROGRESS=$(printf '%s' "$INPUT" | jq -r '.progress // empty')
-ARTIFACTS=$(printf '%s' "$INPUT" | jq -c '.artifacts // empty')
-BLOCKERS=$(printf '%s' "$INPUT" | jq -c '.blockers // empty')
-USE_STRUCTURED=$(printf '%s' "$INPUT" | jq -r '.structured // "false"')
+  # Summary from file
+  bash execute.sh --session dev-1 --status done --summary-file /tmp/summary.txt --project /path
+
+  # Legacy JSON argument (backward compatible)
+  bash execute.sh '{"sessionName":"dev-1","status":"done","summary":"Fixed the bug"}'
+
+Options:
+  --session  | -s   Agent session name (required)
+  --status   | -S   Status: done, blocked, failed, in_progress, active (required)
+  --summary  | -m   Status summary text (required unless piped via stdin)
+  --summary-file    Read summary from file path
+  --project  | -p   Project path for auto-remember on completion
+  --task-path       Task file path to auto-complete
+  --task-id         Task ID (for structured StatusReport format)
+  --progress        Progress percentage (0-100, for structured format)
+  --structured      Use structured StatusReport format (true/false)
+  --json     | -j   Raw JSON payload (same as legacy)
+  --help     | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+SESSION_NAME=""
+STATUS=""
+SUMMARY=""
+PROJECT_PATH=""
+TASK_PATH=""
+TASK_ID=""
+PROGRESS=""
+STRUCTURED="false"
+
+# 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
+      ;;
+    --status|-S)
+      STATUS="$2"
+      shift 2
+      ;;
+    --summary|-m)
+      SUMMARY="$2"
+      shift 2
+      ;;
+    --summary-file)
+      SUMMARY="$(cat "$2")"
+      shift 2
+      ;;
+    --project|-p)
+      PROJECT_PATH="$2"
+      shift 2
+      ;;
+    --task-path)
+      TASK_PATH="$2"
+      shift 2
+      ;;
+    --task-id)
+      TASK_ID="$2"
+      shift 2
+      ;;
+    --progress)
+      PROGRESS="$2"
+      shift 2
+      ;;
+    --structured)
+      STRUCTURED="true"
+      shift
+      ;;
+    --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 summary
+if [ -z "$INPUT_JSON" ] && [ -z "$SUMMARY" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  else
+    SUMMARY="$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 // empty')
+  [ -z "$STATUS" ] && STATUS=$(printf '%s' "$INPUT" | jq -r '.status // empty')
+  [ -z "$SUMMARY" ] && SUMMARY=$(printf '%s' "$INPUT" | jq -r '.summary // empty')
+  [ -z "$TASK_PATH" ] && TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.taskPath // empty')
+  [ -z "$TASK_ID" ] && TASK_ID=$(printf '%s' "$INPUT" | jq -r '.taskId // empty')
+  [ -z "$PROGRESS" ] && PROGRESS=$(printf '%s' "$INPUT" | jq -r '.progress // empty')
+  [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+  ARTIFACTS=$(printf '%s' "$INPUT" | jq -c '.artifacts // empty')
+  BLOCKERS=$(printf '%s' "$INPUT" | jq -c '.blockers // empty')
+  USE_STRUCTURED=$(printf '%s' "$INPUT" | jq -r '.structured // "false"')
+  [ "$USE_STRUCTURED" = "true" ] && STRUCTURED="true"
+else
+  ARTIFACTS=""
+  BLOCKERS=""
+fi
+
+require_param "sessionName (--session)" "$SESSION_NAME"
+require_param "status (--status)" "$STATUS"
+require_param "summary (--summary)" "$SUMMARY"
 
 # Map simple status strings to InProgressTaskStatus values
 map_status_to_state() {
@@ -34,7 +157,7 @@ map_status_to_state() {
 }
 
 # Build the message the orchestrator will receive
-if [ "$USE_STRUCTURED" = "true" ] && [ -n "$TASK_ID" ]; then
+if [ "$STRUCTURED" = "true" ] && [ -n "$TASK_ID" ]; then
   # Structured StatusReport format for hierarchical teams
   STATE=$(map_status_to_state "$STATUS")
   MESSAGE="---\n[STATUS REPORT]\nTask ID: ${TASK_ID}\nState: ${STATE}"
@@ -68,12 +191,6 @@ BODY=$(jq -n --arg content "$MESSAGE" --arg senderName "$SESSION_NAME" \
 
 api_call POST "/chat/agent-response" "$BODY"
 
-# Auto-register as active when reporting "active" or first status.
-# This ensures the agent's agentStatus transitions from "started" to "active"
-# in storage, which the queue processor requires before delivering messages.
-# Without this, agents that call report-status instead of register-self
-# remain stuck in "started" state indefinitely.
-
 # If task is done and taskPath provided, move task file to done folder
 if [ "$STATUS" = "done" ] && [ -n "$TASK_PATH" ]; then
   COMPLETE_BODY=$(jq -n \
@@ -90,9 +207,6 @@ if [ "$STATUS" = "done" ]; then
 fi
 
 # Auto-persist key findings as project knowledge when task is done (#127, #219).
-# Use [COMPLETED] prefix so recall can distinguish completed tasks from other patterns.
-# This prevents PM from re-delegating tasks that were already done.
 if [ "$STATUS" = "done" ] && [ -n "$SUMMARY" ]; then
-  PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
   auto_remember "$SESSION_NAME" "[COMPLETED] Task completed by ${SESSION_NAME}: ${SUMMARY}" "decision" "project" "$PROJECT_PATH"
 fi

package/config/skills/agent/core/send-message/SKILL.md

@@ -42,15 +42,29 @@ Send a direct message to another agent's terminal session. The message is writte
 
 ## Parameters
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `to` | Yes | Target agent's PTY session name |
-| `message` | Yes | The message text to send |
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--to` / `-t` | `to` | Yes | Target agent's PTY session name |
+| `--message` / `-m` | `message` | Yes | Message text (or pipe via stdin) |
+| `--message-file` | — | No | Read message from a file path |
 
-## Example
+## Examples — CLI Flags (preferred)
 
 ```bash
-bash config/skills/agent/send-message/execute.sh '{"to":"qa-1","message":"PR #42 is ready for review. I added unit tests for the auth module."}'
+# Simple message
+bash execute.sh --to qa-1 --message "PR #42 is ready for review"
+
+# Multi-line message via stdin (avoids shell escaping)
+echo "PR #42 is ready for review. It's passing all tests." | bash execute.sh --to qa-1
+
+# Message from file
+bash execute.sh --to qa-1 --message-file /tmp/task-details.txt
+```
+
+## Examples — Legacy JSON (backward compatible)
+
+```bash
+bash execute.sh '{"to":"qa-1","message":"PR #42 is ready for review."}'
 ```
 
 ## Output

package/config/skills/agent/core/send-message/execute.sh

@@ -1,18 +1,100 @@
 #!/bin/bash
 # Send a direct message to another agent's terminal session.
-# Supports: argument, stdin pipe, or @filepath for JSON input (#292, #293).
+# Supports CLI flags (preferred), legacy JSON, stdin pipe, or @filepath.
 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 '{\"to\":\"agent-session\",\"message\":\"...\"}' or echo '{...}' | execute.sh"
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  # CLI flags (preferred)
+  bash execute.sh --to agent-session --message "Please implement feature X"
 
-# Accept both "to" and "sessionName" for compatibility (#231)
-TO=$(printf '%s' "$INPUT" | jq -r '.to // .sessionName // empty')
-MESSAGE=$(printf '%s' "$INPUT" | jq -r '.message // empty')
-require_param "to (or sessionName)" "$TO"
-require_param "message" "$MESSAGE"
+  # Message from stdin (for multi-line or special characters)
+  echo "Implement feature X — it's urgent" | bash execute.sh --to agent-session
+
+  # Message from file
+  bash execute.sh --to agent-session --message-file /tmp/task.txt
+
+  # Legacy JSON (backward compatible)
+  bash execute.sh '{"to":"agent-session","message":"..."}'
+
+Options:
+  --to       | -t   Target agent session name (required)
+  --message  | -m   Message text (required unless piped via stdin)
+  --message-file    Read message from file path
+  --json     | -j   Raw JSON payload (same as legacy)
+  --help     | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+TO=""
+MESSAGE=""
+
+# Detect legacy JSON argument
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --to|-t)
+      TO="$2"
+      shift 2
+      ;;
+    --message|-m)
+      MESSAGE="$2"
+      shift 2
+      ;;
+    --message-file)
+      MESSAGE="$(cat "$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
+
+# Read from stdin if no message yet
+if [ -z "$INPUT_JSON" ] && [ -z "$MESSAGE" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  else
+    MESSAGE="$STDIN_DATA"
+  fi
+fi
+
+# Parse JSON if provided
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$TO" ] && TO=$(printf '%s' "$INPUT" | jq -r '.to // .sessionName // empty')
+  [ -z "$MESSAGE" ] && MESSAGE=$(printf '%s' "$INPUT" | jq -r '.message // empty')
+fi
+
+require_param "to (--to)" "$TO"
+require_param "message (--message)" "$MESSAGE"
 
 BODY=$(jq -n --arg data "$MESSAGE" --arg mode "message" '{data: $data, mode: $mode}')
 

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

@@ -32,30 +32,48 @@ The script auto-resolves `config/skills/...` references to absolute paths so del
 
 **Monitoring is enabled by default** — idle event subscriptions and recurring fallback checks (every 5 minutes) are automatically set up for every delegation. These are linked to the task and will be **automatically cleaned up** when the task is completed via `report-status` or `complete-task`. To disable monitoring, explicitly pass `"monitor": {"idleEvent": false, "fallbackCheckMinutes": 0}`.
 
-## Usage
+## Parameters
+
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--to` / `-t` | `to` | Yes | Target agent's PTY session name |
+| `--task` / `-T` | `task` | Yes | Task description (or pipe via stdin) |
+| `--task-file` | — | No | Read task description from a file path |
+| `--priority` / `-P` | `priority` | No | Priority: `low`, `normal`, `high` (default: `normal`) |
+| `--context` / `-c` | `context` | No | Additional context for the task |
+| `--project` / `-p` | `projectPath` | No | Project path; creates task file in `.crewly/tasks/` |
+| `--team` / `-g` | `teamId` | No | Team ID for cross-team validation |
+| `--task-type` | `taskType` | No | Task type: `general`, `technical` (default: `general`) |
+| `--force-cross-team` | `forceCrossTeam` | No | Allow cross-team delegation |
+| `monitor` (JSON only) | `monitor` | No | Auto-monitoring config (see below) |
+
+## Usage — CLI Flags (preferred)
 
 ```bash
-bash config/skills/orchestrator/delegate-task/execute.sh '{"to":"agent-joe","task":"Implement the login form","priority":"high","context":"Use React hooks","projectPath":"/path/to/project"}'
+# Basic delegation
+bash execute.sh --to agent-joe --task "Implement the login form" --priority high --project /path/to/project
+
+# With context
+bash execute.sh --to agent-joe --task "Implement login form" --priority high --context "Use React hooks" --project /path
+
+# Task from stdin (for long descriptions with special characters)
+echo "Implement the OAuth2 flow — it's critical for launch" | bash execute.sh --to agent-joe --priority high --project /path
+
+# Task from file
+bash execute.sh --to agent-joe --task-file /tmp/task-description.txt --priority high --project /path
 ```
 
-### With monitoring disabled (opt-out)
+## Usage — Legacy JSON (backward compatible)
 
 ```bash
-bash config/skills/orchestrator/delegate-task/execute.sh '{"to":"agent-joe","task":"Implement the login form","priority":"high","projectPath":"/path/to/project","monitor":{"idleEvent":false,"fallbackCheckMinutes":0}}'
+bash execute.sh '{"to":"agent-joe","task":"Implement the login form","priority":"high","context":"Use React hooks","projectPath":"/path/to/project"}'
 ```
 
-## Parameters
+### With monitoring disabled (opt-out, JSON only)
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `to` | Yes | Target agent's PTY session name |
-| `task` | Yes | Task description |
-| `priority` | No | Task priority: `low`, `normal`, `high` (default: `normal`) |
-| `context` | No | Additional context for the task |
-| `projectPath` | No | Project path; when provided, creates a task MD file in `.crewly/tasks/` |
-| `monitor` | No | Auto-monitoring configuration (see below). Enabled by default. |
-| `monitor.idleEvent` | No | If `true`, subscribes to `agent:idle` event for the target agent (default: `true`) |
-| `monitor.fallbackCheckMinutes` | No | If > 0, sets up a recurring fallback check every N minutes (default: `5`) |
+```bash
+bash execute.sh '{"to":"agent-joe","task":"Implement the login form","priority":"high","projectPath":"/path/to/project","monitor":{"idleEvent":false,"fallbackCheckMinutes":0}}'
+```
 
 ## Examples
 

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

@@ -6,21 +6,75 @@ 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 '{\"to\":\"agent-session\",\"task\":\"...\"}' or echo '{...}' | execute.sh"
-
-TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
-TASK=$(printf '%s' "$INPUT" | jq -r '.task // empty')
-PRIORITY=$(printf '%s' "$INPUT" | jq -r '.priority // "normal"')
-CONTEXT=$(printf '%s' "$INPUT" | jq -r '.context // empty')
-PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
-# #150: Task type classification — 'technical' tasks can bypass PM routing
-TASK_TYPE=$(printf '%s' "$INPUT" | jq -r '.taskType // "general"')
-# #180: Cross-team validation
-TEAM_ID=$(printf '%s' "$INPUT" | jq -r '.teamId // empty')
-FORCE_CROSS_TEAM=$(printf '%s' "$INPUT" | jq -r '.forceCrossTeam // "false"')
-require_param "to" "$TO"
-require_param "task" "$TASK"
+# --- Input parsing: CLI flags (preferred) or legacy JSON ---
+INPUT_JSON=""
+TO=""
+TASK=""
+PRIORITY="normal"
+CONTEXT=""
+PROJECT_PATH=""
+TASK_TYPE="general"
+TEAM_ID=""
+FORCE_CROSS_TEAM="false"
+
+# Detect legacy JSON argument
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --to|-t)         TO="$2";              shift 2 ;;
+    --task|-T)       TASK="$2";             shift 2 ;;
+    --task-file)     TASK="$(cat "$2")";    shift 2 ;;
+    --priority|-P)   PRIORITY="$2";         shift 2 ;;
+    --context|-c)    CONTEXT="$2";          shift 2 ;;
+    --project|-p)    PROJECT_PATH="$2";     shift 2 ;;
+    --task-type)     TASK_TYPE="$2";        shift 2 ;;
+    --team|-g)       TEAM_ID="$2";          shift 2 ;;
+    --force-cross-team) FORCE_CROSS_TEAM="true"; shift ;;
+    --json|-j)       INPUT_JSON="$2";       shift 2 ;;
+    --help|-h)
+      echo "Usage: execute.sh --to agent-session --task 'implement feature' --priority high --project /path [--team teamId] [--context 'extra info']"
+      exit 0
+      ;;
+    --)              shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then
+        INPUT_JSON="$1"; shift
+      else
+        error_exit "Unknown argument: $1"
+      fi
+      ;;
+  esac
+done
+
+# Read task from stdin if not yet provided
+if [ -z "$INPUT_JSON" ] && [ -z "$TASK" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  else
+    TASK="$STDIN_DATA"
+  fi
+fi
+
+# Parse JSON if provided (backward compatible)
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$TO" ] && TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
+  [ -z "$TASK" ] && TASK=$(printf '%s' "$INPUT" | jq -r '.task // empty')
+  [ "$PRIORITY" = "normal" ] && { P=$(printf '%s' "$INPUT" | jq -r '.priority // empty'); [ -n "$P" ] && PRIORITY="$P"; }
+  [ -z "$CONTEXT" ] && CONTEXT=$(printf '%s' "$INPUT" | jq -r '.context // empty')
+  [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+  [ "$TASK_TYPE" = "general" ] && { TT=$(printf '%s' "$INPUT" | jq -r '.taskType // empty'); [ -n "$TT" ] && TASK_TYPE="$TT"; }
+  [ -z "$TEAM_ID" ] && TEAM_ID=$(printf '%s' "$INPUT" | jq -r '.teamId // empty')
+  [ "$FORCE_CROSS_TEAM" = "false" ] && FORCE_CROSS_TEAM=$(printf '%s' "$INPUT" | jq -r '.forceCrossTeam // "false"')
+fi
+
+require_param "to (--to)" "$TO"
+require_param "task (--task)" "$TASK"
 
 # #180: Validate target agent belongs to the specified team
 if [ -n "$TEAM_ID" ] && [ "$FORCE_CROSS_TEAM" != "true" ]; then

package/config/skills/team-leader/delegate-task/SKILL.md

@@ -34,24 +34,41 @@ Assigns a task to a worker within the Team Leader's subordinate scope. Validates
 - When `handle-failure` decides to `reassign` a task
 - When a new worker needs to be given work
 
-## Usage
+## Parameters
+
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--to` / `-t` | `to` | Yes | Target worker's PTY session name |
+| `--task` / `-T` | `task` | Yes | Task description (or pipe via stdin) |
+| `--task-file` | — | No | Read task description from a file path |
+| `--priority` / `-P` | `priority` | No | Priority: `low`, `normal`, `high` (default: `normal`) |
+| `--context` / `-c` | `context` | No | Additional context for the worker |
+| `--project` / `-p` | `projectPath` | No | Project path; creates task file in `.crewly/tasks/` |
+| `--team` / `-g` | `teamId` | No | Team ID for hierarchy validation |
+| `--tl-member` | `tlMemberId` | No | TL's member ID for hierarchy validation |
+| `--from` | `fromSession` | No | Delegating TL's session name (for monitoring) |
+
+## Usage — CLI Flags (preferred)
 
 ```bash
-bash {{SKILLS_PATH}}/team-leader/delegate-task/execute.sh '{"to":"worker-session","task":"Implement login form","priority":"high","teamId":"team-123","tlMemberId":"tl-member-id","projectPath":"/path/to/project"}'
+# Basic delegation
+bash execute.sh --to worker-session --task "Implement login form" --priority high --project /path/to/project
+
+# With hierarchy validation
+bash execute.sh --to worker-session --task "Implement login form" --priority high --team team-123 --tl-member tl-member-id --project /path/to/project
+
+# Task from stdin (for long descriptions with special characters)
+echo "Implement the OAuth2 flow — it's critical for launch" | bash execute.sh --to worker-session --priority high --project /path
+
+# Task from file
+bash execute.sh --to worker-session --task-file /tmp/task-description.txt --priority high --project /path
 ```
 
-## Parameters
+## Usage — Legacy JSON (backward compatible)
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `to` | Yes | Target worker's PTY session name |
-| `task` | Yes | Task description (skill paths auto-resolved to absolute) |
-| `priority` | No | Task priority: `low`, `normal`, `high` (default: `normal`) |
-| `context` | No | Additional context for the worker |
-| `teamId` | No | Team ID for hierarchy validation |
-| `tlMemberId` | No | TL's member ID for hierarchy validation |
-| `projectPath` | No | Project path; creates task file in `.crewly/tasks/` |
-| `monitor` | No | Auto-monitoring config (same as orchestrator delegate-task) |
+```bash
+bash execute.sh '{"to":"worker-session","task":"Implement login form","priority":"high","teamId":"team-123","tlMemberId":"tl-member-id","projectPath":"/path/to/project"}'
+```
 
 ## Hierarchy Validation
 

package/config/skills/team-leader/delegate-task/execute.sh

@@ -6,19 +6,75 @@ 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 '{\"to\":\"worker-session\",\"task\":\"...\"}' or echo '{...}' | execute.sh"
-
-TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
-TASK=$(printf '%s' "$INPUT" | jq -r '.task // empty')
-PRIORITY=$(printf '%s' "$INPUT" | jq -r '.priority // "normal"')
-CONTEXT=$(printf '%s' "$INPUT" | jq -r '.context // empty')
-PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
-TEAM_ID=$(printf '%s' "$INPUT" | jq -r '.teamId // empty')
-TL_MEMBER_ID=$(printf '%s' "$INPUT" | jq -r '.tlMemberId // empty')
-FROM_SESSION=$(printf '%s' "$INPUT" | jq -r '.fromSession // empty')
-require_param "to" "$TO"
-require_param "task" "$TASK"
+# --- Input parsing: CLI flags (preferred) or legacy JSON ---
+INPUT_JSON=""
+TO=""
+TASK=""
+PRIORITY="normal"
+CONTEXT=""
+PROJECT_PATH=""
+TEAM_ID=""
+TL_MEMBER_ID=""
+FROM_SESSION=""
+
+# Detect legacy JSON argument
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --to|-t)       TO="$2";            shift 2 ;;
+    --task|-T)     TASK="$2";           shift 2 ;;
+    --task-file)   TASK="$(cat "$2")";  shift 2 ;;
+    --priority|-P) PRIORITY="$2";       shift 2 ;;
+    --context|-c)  CONTEXT="$2";        shift 2 ;;
+    --project|-p)  PROJECT_PATH="$2";   shift 2 ;;
+    --team|-g)     TEAM_ID="$2";        shift 2 ;;
+    --tl-member)   TL_MEMBER_ID="$2";   shift 2 ;;
+    --from)        FROM_SESSION="$2";   shift 2 ;;
+    --json|-j)     INPUT_JSON="$2";     shift 2 ;;
+    --help|-h)
+      echo "Usage: execute.sh --to worker-session --task 'implement feature' --priority high --project /path [--team teamId] [--tl-member memberId]"
+      exit 0
+      ;;
+    --)            shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then
+        INPUT_JSON="$1"; shift
+      else
+        error_exit "Unknown argument: $1"
+      fi
+      ;;
+  esac
+done
+
+# Read task from stdin if not yet provided
+if [ -z "$INPUT_JSON" ] && [ -z "$TASK" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  else
+    TASK="$STDIN_DATA"
+  fi
+fi
+
+# Parse JSON if provided (backward compatible)
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$TO" ] && TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
+  [ -z "$TASK" ] && TASK=$(printf '%s' "$INPUT" | jq -r '.task // empty')
+  [ "$PRIORITY" = "normal" ] && { P=$(printf '%s' "$INPUT" | jq -r '.priority // empty'); [ -n "$P" ] && PRIORITY="$P"; }
+  [ -z "$CONTEXT" ] && CONTEXT=$(printf '%s' "$INPUT" | jq -r '.context // empty')
+  [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+  [ -z "$TEAM_ID" ] && TEAM_ID=$(printf '%s' "$INPUT" | jq -r '.teamId // empty')
+  [ -z "$TL_MEMBER_ID" ] && TL_MEMBER_ID=$(printf '%s' "$INPUT" | jq -r '.tlMemberId // empty')
+  [ -z "$FROM_SESSION" ] && FROM_SESSION=$(printf '%s' "$INPUT" | jq -r '.fromSession // empty')
+fi
+
+require_param "to (--to)" "$TO"
+require_param "task (--task)" "$TASK"
 
 # Resolve Crewly root from this script path:
 # config/skills/team-leader/delegate-task/execute.sh -> project root