crewly 1.5.15 → 1.5.17

package/config/skills/agent/browse-stealth/stealth-browse.py

@@ -285,9 +285,14 @@ def main():
         }))
         sys.exit(1)
 
-    # Ensure Chrome is running with CDP
+    # Connect to Chrome via CDP on the specified port.
+    # For custom ports, connect directly. For default port (9222), fall back to
+    # ensure_chrome_running() which can auto-launch Chrome if needed.
     try:
-        ws_url = ensure_chrome_running()
+        if args.cdp_port != CDP_PORT:
+            ws_url = get_ws_url(args.cdp_port)
+        else:
+            ws_url = ensure_chrome_running()
     except Exception as e:
         print(json.dumps({"success": False, "error": f"chrome_launch_failed: {e}"}))
         sys.exit(1)

package/config/skills/agent/core/recall/SKILL.md

@@ -42,18 +42,31 @@ Retrieve stored memories relevant to a given context or query. Use this to look
 
 ## Parameters
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `agentId` | Yes | Your agent ID |
-| `context` | Yes | Search context or query describing what you want to recall |
-| `scope` | No | Filter by scope: `"project"`, `"team"`, or `"global"` |
-| `limit` | No | Maximum number of results to return |
-| `projectPath` | No | Filter by project path |
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--agent` / `-a` | `agentId` | Yes | Your agent ID / session name |
+| `--context` / `-c` | `context` | Yes | Search query (or pipe via stdin) |
+| `--scope` / `-s` | `scope` | No | Filter: `project`, `team`, or `global` |
+| `--limit` / `-l` | `limit` | No | Max number of results |
+| `--project` / `-p` | `projectPath` | No | Filter by project path |
 
-## Example
+## Examples — CLI Flags (preferred)
 
 ```bash
-bash config/skills/agent/recall/execute.sh '{"agentId":"dev-1","context":"authentication implementation patterns","scope":"project","limit":5}'
+# Search project memory
+bash execute.sh --agent dev-1 --context "authentication implementation patterns" --scope project --project /projects/app
+
+# Quick recall with limit
+bash execute.sh --agent dev-1 --context "deployment process" --limit 5
+
+# Context via stdin
+echo "how does the relay service work" | bash execute.sh --agent dev-1 --project /projects/app
+```
+
+## Examples — Legacy JSON (backward compatible)
+
+```bash
+bash execute.sh '{"agentId":"dev-1","context":"authentication patterns","scope":"project","limit":5}'
 ```
 
 ## Output

package/config/skills/agent/core/recall/execute.sh

@@ -1,24 +1,101 @@
 #!/bin/bash
-# Retrieve stored memories relevant to a given context
+# Retrieve stored memories relevant to a given context.
+# Supports CLI flags (preferred) and legacy JSON.
 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 '{\"agentId\":\"dev-1\",\"context\":\"...\"}' or echo '{...}' | execute.sh"
-
-AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agentId // empty')
-CONTEXT=$(printf '%s' "$INPUT" | jq -r '.context // empty')
-require_param "agentId" "$AGENT_ID"
-require_param "context" "$CONTEXT"
-
-# Build body with required and optional fields
-BODY=$(printf '%s' "$INPUT" | jq '{
-  agentId: .agentId,
-  context: .context
-} +
-  (if .scope then {scope: .scope} else {} end) +
-  (if .limit then {limit: (.limit | tonumber)} else {} end) +
-  (if .projectPath then {projectPath: .projectPath} else {} end)')
+INPUT_JSON=""
+AGENT_ID=""
+CONTEXT=""
+SCOPE=""
+LIMIT=""
+PROJECT_PATH=""
+
+# Detect legacy JSON argument
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --agent|-a)
+      AGENT_ID="$2"
+      shift 2
+      ;;
+    --context|-c)
+      CONTEXT="$2"
+      shift 2
+      ;;
+    --scope|-s)
+      SCOPE="$2"
+      shift 2
+      ;;
+    --limit|-l)
+      LIMIT="$2"
+      shift 2
+      ;;
+    --project|-p)
+      PROJECT_PATH="$2"
+      shift 2
+      ;;
+    --json|-j)
+      INPUT_JSON="$2"
+      shift 2
+      ;;
+    --help|-h)
+      echo "Usage: execute.sh --agent dev-1 --context 'topic to recall' --project /path [--scope project|agent] [--limit 10]"
+      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 from stdin if no context yet
+if [ -z "$INPUT_JSON" ] && [ -z "$CONTEXT" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  else
+    CONTEXT="$STDIN_DATA"
+  fi
+fi
+
+# Parse JSON if provided
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$AGENT_ID" ] && AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agentId // empty')
+  [ -z "$CONTEXT" ] && CONTEXT=$(printf '%s' "$INPUT" | jq -r '.context // empty')
+  [ -z "$SCOPE" ] && SCOPE=$(printf '%s' "$INPUT" | jq -r '.scope // empty')
+  [ -z "$LIMIT" ] && LIMIT=$(printf '%s' "$INPUT" | jq -r '.limit // empty')
+  [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+fi
+
+require_param "agentId (--agent)" "$AGENT_ID"
+require_param "context (--context)" "$CONTEXT"
+
+# Build body using env vars for safe escaping
+export _RCL_AGENT="$AGENT_ID"
+export _RCL_CTX="$CONTEXT"
+
+BODY=$(jq -n '{agentId: env._RCL_AGENT, context: env._RCL_CTX}')
+
+[ -n "$SCOPE" ] && BODY=$(echo "$BODY" | jq --arg s "$SCOPE" '. + {scope: $s}')
+[ -n "$LIMIT" ] && BODY=$(echo "$BODY" | jq --arg l "$LIMIT" '. + {limit: ($l | tonumber)}')
+[ -n "$PROJECT_PATH" ] && BODY=$(echo "$BODY" | jq --arg p "$PROJECT_PATH" '. + {projectPath: $p}')
+
+unset _RCL_AGENT _RCL_CTX
 
 api_call POST "/memory/recall" "$BODY"

package/config/skills/agent/core/record-learning/SKILL.md

@@ -42,19 +42,31 @@ Record a learning or insight gained during task execution. These learnings are s
 
 ## Parameters
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `agentId` | Yes | Your agent ID |
-| `agentRole` | Yes | Your role (e.g., `"developer"`, `"qa"`) |
-| `projectPath` | Yes | Absolute path to the project |
-| `learning` | Yes | Description of the learning or insight |
-| `relatedTask` | No | Path or ID of the task that triggered this learning |
-| `relatedFiles` | No | Array of file paths related to the learning |
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--agent` / `-a` | `agentId` | Yes | Your agent ID / session name |
+| `--role` / `-r` | `agentRole` | Yes | Your role (e.g., `developer`, `qa`) |
+| `--project` / `-p` | `projectPath` | Yes | Absolute path to the project |
+| `--learning` / `-l` | `learning` | Yes | The learning or insight (or pipe via stdin) |
+| `--learning-file` | — | No | Read learning from a file path |
 
-## Example
+## Examples — CLI Flags (preferred)
 
 ```bash
-bash config/skills/agent/record-learning/execute.sh '{"agentId":"dev-1","agentRole":"developer","projectPath":"/projects/app","learning":"Jest mock resets are required between tests when using shared module mocks","relatedTask":"implement-auth-tests","relatedFiles":["src/auth.service.test.ts"]}'
+# Record a learning
+bash execute.sh --agent dev-1 --role developer --project /projects/app --learning "Jest mock resets are required between tests"
+
+# Learning via stdin (for text with special characters)
+echo "Don't use git add -A — it catches .env files" | bash execute.sh --agent dev-1 --role developer --project /projects/app
+
+# Learning from file
+bash execute.sh --agent dev-1 --role developer --project /projects/app --learning-file /tmp/insight.txt
+```
+
+## Examples — Legacy JSON (backward compatible)
+
+```bash
+bash execute.sh '{"agentId":"dev-1","agentRole":"developer","projectPath":"/projects/app","learning":"Jest mock resets are required between tests"}'
 ```
 
 ## Output

package/config/skills/agent/core/record-learning/execute.sh

@@ -1,29 +1,98 @@
 #!/bin/bash
-# Record a learning or insight for team knowledge sharing
+# Record a learning or insight for team knowledge sharing.
+# Supports CLI flags (preferred) and legacy JSON.
 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 '{\"agentId\":\"dev-1\",\"agentRole\":\"developer\",\"projectPath\":\"...\",\"learning\":\"...\"}' or echo '{...}' | execute.sh"
-
-AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agentId // empty')
-AGENT_ROLE=$(printf '%s' "$INPUT" | jq -r '.agentRole // empty')
-PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
-LEARNING=$(printf '%s' "$INPUT" | jq -r '.learning // empty')
-require_param "agentId" "$AGENT_ID"
-require_param "agentRole" "$AGENT_ROLE"
-require_param "projectPath" "$PROJECT_PATH"
-require_param "learning" "$LEARNING"
-
-# Build body with required and optional fields
-BODY=$(printf '%s' "$INPUT" | jq '{
-  agentId: .agentId,
-  agentRole: .agentRole,
-  projectPath: .projectPath,
-  learning: .learning
-} +
-  (if .relatedTask then {relatedTask: .relatedTask} else {} end) +
-  (if .relatedFiles then {relatedFiles: .relatedFiles} else {} end)')
+INPUT_JSON=""
+AGENT_ID=""
+AGENT_ROLE=""
+PROJECT_PATH=""
+LEARNING=""
+
+# Detect legacy JSON argument
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --agent|-a)
+      AGENT_ID="$2"
+      shift 2
+      ;;
+    --role|-r)
+      AGENT_ROLE="$2"
+      shift 2
+      ;;
+    --project|-p)
+      PROJECT_PATH="$2"
+      shift 2
+      ;;
+    --learning|-l)
+      LEARNING="$2"
+      shift 2
+      ;;
+    --learning-file)
+      LEARNING="$(cat "$2")"
+      shift 2
+      ;;
+    --json|-j)
+      INPUT_JSON="$2"
+      shift 2
+      ;;
+    --help|-h)
+      echo "Usage: execute.sh --agent dev-1 --role developer --project /path --learning 'What I learned'"
+      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 from stdin if no learning yet
+if [ -z "$INPUT_JSON" ] && [ -z "$LEARNING" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  else
+    LEARNING="$STDIN_DATA"
+  fi
+fi
+
+# Parse JSON if provided
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$AGENT_ID" ] && AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agentId // empty')
+  [ -z "$AGENT_ROLE" ] && AGENT_ROLE=$(printf '%s' "$INPUT" | jq -r '.agentRole // empty')
+  [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+  [ -z "$LEARNING" ] && LEARNING=$(printf '%s' "$INPUT" | jq -r '.learning // empty')
+fi
+
+require_param "agentId (--agent)" "$AGENT_ID"
+require_param "agentRole (--role)" "$AGENT_ROLE"
+require_param "projectPath (--project)" "$PROJECT_PATH"
+require_param "learning (--learning)" "$LEARNING"
+
+# Build body using env vars for safe escaping
+export _LRN_AGENT="$AGENT_ID"
+export _LRN_ROLE="$AGENT_ROLE"
+export _LRN_PROJECT="$PROJECT_PATH"
+export _LRN_CONTENT="$LEARNING"
+
+BODY=$(jq -n '{agentId: env._LRN_AGENT, agentRole: env._LRN_ROLE, projectPath: env._LRN_PROJECT, learning: env._LRN_CONTENT}')
+unset _LRN_AGENT _LRN_ROLE _LRN_PROJECT _LRN_CONTENT
 
 api_call POST "/memory/record-learning" "$BODY"

package/config/skills/agent/core/remember/SKILL.md

@@ -41,19 +41,32 @@ Store a memory entry for future recall. Use this to persist important context, d
 
 ## Parameters
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `agentId` | Yes | Your agent ID |
-| `content` | Yes | The content to remember |
-| `category` | Yes | Memory category. Agent scope supports `fact`, `pattern`, `preference`. Project scope supports `pattern`, `decision`, `gotcha`, `relationship`, `user_preference` |
-| `scope` | Yes | Memory scope: `"agent"` or `"project"` |
-| `projectPath` | No | Associated project path |
-| `metadata` | No | Additional metadata object |
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--agent` / `-a` | `agentId` | Yes | Your agent ID / session name |
+| `--content` / `-c` | `content` | Yes | Content to remember (or pipe via stdin) |
+| `--content-file` | — | No | Read content from a file path |
+| `--category` / `-C` | `category` | Yes | Category: `pattern`, `decision`, `gotcha`, `fact`, `preference`, `relationship`, `user_preference` |
+| `--scope` / `-s` | `scope` | Yes | Scope: `agent` or `project` |
+| `--project` / `-p` | `projectPath` | No | Project path (required for `project` scope) |
 
-## Example
+## Examples — CLI Flags (preferred)
 
 ```bash
-bash config/skills/agent/core/remember/execute.sh '{"agentId":"dev-1","content":"User prefers PDF delivery in Slack thread after daily brief.","category":"user_preference","scope":"project","projectPath":"/projects/app"}'
+# Store a project-wide pattern
+bash execute.sh --agent dev-1 --content "User prefers PDF delivery in Slack thread" --category user_preference --scope project --project /projects/app
+
+# Content via stdin (for text with special characters)
+echo "Jest mock resets are required between tests — don't forget" | bash execute.sh --agent dev-1 --category gotcha --scope project --project /projects/app
+
+# Content from file
+bash execute.sh --agent dev-1 --content-file /tmp/finding.txt --category decision --scope project --project /projects/app
+```
+
+## Examples — Legacy JSON (backward compatible)
+
+```bash
+bash execute.sh '{"agentId":"dev-1","content":"User prefers PDF delivery","category":"user_preference","scope":"project","projectPath":"/projects/app"}'
 ```
 
 ## Output

package/config/skills/agent/core/remember/execute.sh

@@ -1,35 +1,142 @@
 #!/bin/bash
-# Store a memory entry for future recall
+# Store a memory entry for future recall.
+# Supports CLI flags (preferred) and legacy JSON.
 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 '{\"agentId\":\"dev-1\",\"content\":\"...\",\"category\":\"...\",\"scope\":\"...\"}' or echo '{...}' | execute.sh"
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  # CLI flags (preferred)
+  bash execute.sh --agent dev-1 --content "Important finding" --category pattern --scope project --project /path
 
-AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agentId // empty')
-CONTENT=$(printf '%s' "$INPUT" | jq -r '.content // empty')
-CATEGORY=$(printf '%s' "$INPUT" | jq -r '.category // empty')
-SCOPE=$(printf '%s' "$INPUT" | jq -r '.scope // empty')
-require_param "agentId" "$AGENT_ID"
-require_param "content" "$CONTENT"
-require_param "category" "$CATEGORY"
-require_param "scope" "$SCOPE"
+  # Content from stdin
+  echo "Multi-line finding" | bash execute.sh --agent dev-1 --category pattern --scope project --project /path
+
+  # Content from file
+  bash execute.sh --agent dev-1 --content-file /tmp/finding.txt --category pattern --scope project
+
+  # Legacy JSON (backward compatible)
+  bash execute.sh '{"agentId":"dev-1","content":"...","category":"pattern","scope":"project"}'
+
+Options:
+  --agent    | -a   Agent ID / session name (required)
+  --content  | -c   Memory content text (required unless piped via stdin)
+  --content-file    Read content from file path
+  --category | -C   Category: pattern, decision, gotcha, fact, preference (required)
+  --scope    | -s   Scope: project or agent (required)
+  --project  | -p   Project path (required for project scope)
+  --json     | -j   Raw JSON payload
+  --help     | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+AGENT_ID=""
+CONTENT=""
+CATEGORY=""
+SCOPE=""
+PROJECT_PATH=""
+
+# Detect legacy JSON argument
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --agent|-a)
+      AGENT_ID="$2"
+      shift 2
+      ;;
+    --content|-c)
+      CONTENT="$2"
+      shift 2
+      ;;
+    --content-file)
+      CONTENT="$(cat "$2")"
+      shift 2
+      ;;
+    --category|-C)
+      CATEGORY="$2"
+      shift 2
+      ;;
+    --scope|-s)
+      SCOPE="$2"
+      shift 2
+      ;;
+    --project|-p)
+      PROJECT_PATH="$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 content yet
+if [ -z "$INPUT_JSON" ] && [ -z "$CONTENT" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  else
+    CONTENT="$STDIN_DATA"
+  fi
+fi
+
+# Parse JSON if provided
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$AGENT_ID" ] && AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agentId // empty')
+  [ -z "$CONTENT" ] && CONTENT=$(printf '%s' "$INPUT" | jq -r '.content // empty')
+  [ -z "$CATEGORY" ] && CATEGORY=$(printf '%s' "$INPUT" | jq -r '.category // empty')
+  [ -z "$SCOPE" ] && SCOPE=$(printf '%s' "$INPUT" | jq -r '.scope // empty')
+  [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+fi
+
+require_param "agentId (--agent)" "$AGENT_ID"
+require_param "content (--content)" "$CONTENT"
+require_param "category (--category)" "$CATEGORY"
+require_param "scope (--scope)" "$SCOPE"
 
 # #187: Auto-inject projectPath from CREWLY_PROJECT_PATH env var when not provided
-PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
 if [ -z "$PROJECT_PATH" ] && [ -n "${CREWLY_PROJECT_PATH:-}" ]; then
-  INPUT=$(printf '%s' "$INPUT" | jq --arg pp "$CREWLY_PROJECT_PATH" '. + {projectPath: $pp}')
+  PROJECT_PATH="$CREWLY_PROJECT_PATH"
 fi
 
-# Build body with required and optional fields
-BODY=$(printf '%s' "$INPUT" | jq '{
-  agentId: .agentId,
-  content: .content,
-  category: .category,
-  scope: .scope
-} +
-  (if .projectPath then {projectPath: .projectPath} else {} end) +
-  (if .metadata then {metadata: .metadata} else {} end)')
+# Build body using env vars to safely handle special characters
+export _MEM_AGENT="$AGENT_ID"
+export _MEM_CONTENT="$CONTENT"
+export _MEM_CATEGORY="$CATEGORY"
+export _MEM_SCOPE="$SCOPE"
+
+if [ -n "$PROJECT_PATH" ]; then
+  export _MEM_PROJECT="$PROJECT_PATH"
+  BODY=$(jq -n '{agentId: env._MEM_AGENT, content: env._MEM_CONTENT, category: env._MEM_CATEGORY, scope: env._MEM_SCOPE, projectPath: env._MEM_PROJECT}')
+  unset _MEM_PROJECT
+else
+  BODY=$(jq -n '{agentId: env._MEM_AGENT, content: env._MEM_CONTENT, category: env._MEM_CATEGORY, scope: env._MEM_SCOPE}')
+fi
+unset _MEM_AGENT _MEM_CONTENT _MEM_CATEGORY _MEM_SCOPE
 
 api_call POST "/memory/remember" "$BODY"

package/config/skills/agent/core/report-status/SKILL.md

@@ -45,29 +45,41 @@ When `status` is `done` and a `taskPath` is provided, the task file is automatic
 
 ## Parameters
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `sessionName` | Yes | Your agent session name |
-| `status` | Yes | Current status: `done`, `blocked`, or `failed` |
-| `summary` | Yes | Brief description of what happened or what is needed |
-| `taskPath` | No | Path to the task MD file; when provided with `status=done`, moves it to the `done/` folder |
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--session` / `-s` | `sessionName` | Yes | Your agent session name |
+| `--status` / `-S` | `status` | Yes | Status: `done`, `blocked`, `failed`, `in_progress`, `active` |
+| `--summary` / `-m` | `summary` | Yes | Brief description (or pipe via stdin) |
+| `--summary-file` | — | No | Read summary from a file path |
+| `--project` / `-p` | `projectPath` | No | Project path for auto-remember on completion |
+| `--task-path` | `taskPath` | No | Task file path; auto-moves to `done/` on completion |
+| `--task-id` | `taskId` | No | Task ID (for structured StatusReport format) |
+| `--progress` | `progress` | No | Progress percentage 0-100 |
+| `--structured` | `structured` | No | Use structured StatusReport format |
 
-## Example
+## Examples — CLI Flags (preferred)
 
 ```bash
-bash config/skills/agent/report-status/execute.sh '{"sessionName":"dev-1","status":"done","summary":"Finished implementing auth module and all tests pass","taskPath":"/path/to/project/.crewly/tasks/delegated/in_progress/implement_auth_1234.md"}'
-```
+# Report done
+bash execute.sh --session dev-1 --status done --summary "Finished auth module, all tests pass" --project /path/to/project
 
-### Reporting a blocker
+# Report a blocker
+bash execute.sh --session dev-1 --status blocked --summary "Waiting on API credentials from ops team"
 
-```bash
-bash config/skills/agent/report-status/execute.sh '{"sessionName":"dev-1","status":"blocked","summary":"Waiting on API credentials from ops team"}'
+# Report failure
+bash execute.sh --session dev-1 --status failed --summary "Build fails due to missing dependency"
+
+# Multi-line summary via stdin (avoids shell escaping)
+echo "Fixed the bug — it's working now" | bash execute.sh --session dev-1 --status done --project /path
+
+# Summary from file
+bash execute.sh --session dev-1 --status done --summary-file /tmp/summary.txt --project /path
 ```
 
-### Reporting a failure
+## Examples — Legacy JSON (backward compatible)
 
 ```bash
-bash config/skills/agent/report-status/execute.sh '{"sessionName":"dev-1","status":"failed","summary":"Build fails due to missing dependency in package.json"}'
+bash execute.sh '{"sessionName":"dev-1","status":"done","summary":"Finished implementing auth module","taskPath":"/path/.crewly/tasks/delegated/in_progress/implement_auth_1234.md"}'
 ```
 
 ## Output