crewly 1.5.16 → 1.5.17

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/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/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/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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewly",
-  "version": "1.5.16",
+  "version": "1.5.17",
   "type": "module",
   "description": "Multi-agent orchestration platform for AI coding teams — coordinates Claude Code, Gemini CLI, and Codex agents with a real-time web dashboard",
   "main": "dist/cli/cli/src/index.js",