crewly 1.6.3 → 1.6.5

package/config/skills/agent/core/block-task/execute.sh

@@ -1,28 +1,46 @@
 #!/bin/bash
-# Mark a task as blocked with a reason and optional questions
+# Mark a WorkItem as blocked with a reason.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. The
+# legacy `/task-management/block` endpoint (which moved a `.md` file to
+# `delegated/blocked/`) is no longer the source of truth — V3 task-pool's
+# `/task-pool/block/:workItemId` is.
+#
+# Input shape:
+#   { "workItemId": "abc-123", "reason": "missing creds", "questions"?: "...", "urgency"?: "..." }
+#
+# Backwards-compat: if `absoluteTaskPath` is provided instead of
+# `workItemId`, we emit a warning and skip the call rather than fall back
+# to the deprecated v1 path. Callers should obtain `workItemId` from the
+# claim response or from a [CREWLY-DISPATCH] terminal message.
+
 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 '{\"absoluteTaskPath\":\"/path/to/task\",\"reason\":\"Missing API credentials\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"abc-123\",\"reason\":\"Missing API credentials\"}'"
 
-ABSOLUTE_TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
 REASON=$(printf '%s' "$INPUT" | jq -r '.reason // empty')
 QUESTIONS=$(printf '%s' "$INPUT" | jq -r '.questions // empty')
 URGENCY=$(printf '%s' "$INPUT" | jq -r '.urgency // empty')
-require_param "absoluteTaskPath" "$ABSOLUTE_TASK_PATH"
+LEGACY_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
+
+if [ -z "$WORK_ITEM_ID" ] && [ -n "$LEGACY_PATH" ]; then
+  echo '{"error":"`absoluteTaskPath` is no longer accepted — pass `workItemId` instead. See spec/2026-05-06-task-management-v1-deprecation.md"}' >&2
+  exit 1
+fi
+
+require_param "workItemId" "$WORK_ITEM_ID"
 require_param "reason" "$REASON"
 
 BODY=$(jq -n \
-  --arg absoluteTaskPath "$ABSOLUTE_TASK_PATH" \
-  --arg taskPath "$ABSOLUTE_TASK_PATH" \
   --arg reason "$REASON" \
-  --arg blockReason "$REASON" \
   --arg questions "$QUESTIONS" \
   --arg urgency "$URGENCY" \
-  '{absoluteTaskPath: $absoluteTaskPath, taskPath: $taskPath, reason: $reason, blockReason: $blockReason} +
+  '{reason: $reason} +
    (if $questions != "" then {questions: $questions} else {} end) +
    (if $urgency != "" then {urgency: $urgency} else {} end)')
 
-api_call POST "/task-management/block" "$BODY"
+api_call POST "/task-pool/block/${WORK_ITEM_ID}" "$BODY"

package/config/skills/agent/core/cancel-followup/SKILL.md

@@ -1,3 +1,21 @@
+---
+name: cancel-followup
+description: Cancel a follow-up trigger previously created with `schedule-followup` or `watch-for-event`, by trigger id or by team-scoped name.
+version: 1.0.0
+category: followup
+skillType: claude-skill
+tags:
+  - followup
+  - trigger
+  - lifecycle
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 15000
+---
+
 # cancel-followup
 
 Cancel a follow-up trigger you previously created with `schedule-followup` or

package/config/skills/agent/core/complete-task/execute.sh

@@ -61,18 +61,56 @@ if echo "$ABSOLUTE_TASK_PATH" | grep -q '/in_progress/'; then
   fi
 fi
 
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md.
+# Resolve which V3 WorkItem to complete:
+#   1. Explicit `workItemId` from input (preferred)
+#   2. Fall back: query the pool for the agent's currently-running WI
+#
+# The legacy `absoluteTaskPath` input is still accepted but no longer
+# drives the API call — it's only used for logging context. Callers
+# should switch to passing `workItemId`.
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
+if [ -z "$WORK_ITEM_ID" ]; then
+  POOL_RESP=$(api_call GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
+  WORK_ITEM_ID=$(echo "$POOL_RESP" | jq -r '.workItems[0].id // .data[0].id // empty' 2>/dev/null || true)
+fi
+
+if [ -z "$WORK_ITEM_ID" ]; then
+  echo '{"error":"Could not resolve a running WorkItem for this session — pass `workItemId` explicitly."}' >&2
+  exit 1
+fi
+
+# Hygiene #4: emit canonical body shape `{agentId, result:{summary, ...output}}`
+# required by /api/task-pool/complete (task-pool.controller.ts `completeItem`).
+# Prior shape `{summary, ..., result: $output}` 400'd because top-level summary
+# was ignored (controller looks at result.summary) and `result` was overloaded
+# with the output payload instead of the summary wrapper.
+#
+# The optional `output` is now MERGED into `result` alongside `summary` —
+# this matches the controller's mergedOutput behavior (task-pool.controller.ts
+# §405-419) which spreads result fields beyond `summary` into WorkItem.output.
+#
+# Precedence (per Sam #527 review note): jq's `+` operator is right-side-wins
+# on key conflicts. The spread order here is `{summary: $summary} + $output`,
+# so a caller-supplied `output.summary` WILL override the explicit `--summary`
+# parameter. Intentional — callers passing structured output already have an
+# authoritative summary in there; the explicit param is the fallback. If you
+# need the param to win, swap the operands.
 BODY=$(jq -n \
-  --arg absoluteTaskPath "$ABSOLUTE_TASK_PATH" \
-  --arg taskPath "$ABSOLUTE_TASK_PATH" \
-  --arg sessionName "$SESSION_NAME" \
+  --arg agentId "$SESSION_NAME" \
   --arg summary "$SUMMARY" \
   --arg skipGates "$SKIP_GATES" \
   --argjson output "${OUTPUT_JSON:-null}" \
-  '{absoluteTaskPath: $absoluteTaskPath, taskPath: $taskPath, sessionName: $sessionName, summary: $summary} +
-   (if $skipGates == "true" then {skipGates: true} else {} end) +
-   (if $output != null then {output: $output} else {} end)')
+  '{
+    agentId: $agentId,
+    result: ({summary: $summary}
+              + (if $output != null and ($output | type) == "object"
+                 then $output
+                 else {} end))
+  }
+   + (if $skipGates == "true" then {skipGates: true} else {} end)')
 
-api_call POST "/task-management/complete" "$BODY"
+api_call POST "/task-pool/complete/${WORK_ITEM_ID}" "$BODY"
 
 # Auto-persist the task summary as project knowledge (#127, #219).
 # Use [COMPLETED] prefix so recall can distinguish completed tasks from other patterns.

package/config/skills/agent/core/create-task/execute.sh

@@ -1,6 +1,10 @@
 #!/bin/bash
-# Create a new task via the task-management API.
-# Allows TLs and agents to autonomously decompose work into sub-tasks.
+# Create a new task as a V3 WorkItem in the task-pool.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. Replaces
+# the v1 `POST /task-management/create` endpoint, which wrote a `.md` file
+# to the project's `.crewly/tasks/` filesystem. The V3 task-pool's
+# `POST /task-pool/add` endpoint is now the sole way to create new tasks.
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
@@ -116,19 +120,43 @@ MILESTONE="${MILESTONE:-delegated}"
 require_param "projectPath (--project-path)" "$PROJECT_PATH"
 require_param "task (--task)" "$TASK"
 
-# Build the request body
-BODY=$(jq -n \
+# Build a V3 WorkItem for the task-pool.
+# `addToPool` accepts the WorkItem directly (id auto-generated server-side
+# when omitted). `priority` is mapped to V3's numeric priority scale where
+# critical=1, high=2, medium=3, low=4 — lower number = higher priority.
+case "$PRIORITY" in
+  critical) PRIORITY_NUM=1 ;;
+  high)     PRIORITY_NUM=2 ;;
+  medium)   PRIORITY_NUM=3 ;;
+  low)      PRIORITY_NUM=4 ;;
+  *)        PRIORITY_NUM=3 ;;
+esac
+
+WI_ID="task-$(date +%s%N | cut -c1-13)-$$"
+
+WORK_ITEM=$(jq -n \
+  --arg id "$WI_ID" \
+  --arg title "$TASK" \
+  --arg target "$SESSION_NAME" \
+  --arg owner "${SESSION_NAME:-system}" \
   --arg projectPath "$PROJECT_PATH" \
-  --arg task "$TASK" \
-  --arg priority "$PRIORITY" \
   --arg milestone "$MILESTONE" \
-  --arg sessionName "$SESSION_NAME" \
-  '{projectPath: $projectPath, task: $task, priority: $priority, milestone: $milestone} +
-   (if $sessionName != "" then {sessionName: $sessionName} else {} end)')
+  --argjson priority "$PRIORITY_NUM" \
+  '{
+    id: $id,
+    title: $title,
+    type: "delegate",
+    owner: $owner,
+    priority: $priority,
+    status: "queued",
+    target: (if $target == "" then null else $target end),
+    metadata: { projectPath: $projectPath, milestone: $milestone }
+  } | with_entries(select(.value != null))')
 
-# Attach outputSchema if provided
 if [ -n "$OUTPUT_SCHEMA" ] && [ "$OUTPUT_SCHEMA" != "" ]; then
-  BODY=$(printf '%s' "$BODY" | jq --argjson schema "$OUTPUT_SCHEMA" '. + {outputSchema: $schema}')
+  WORK_ITEM=$(printf '%s' "$WORK_ITEM" | jq --argjson schema "$OUTPUT_SCHEMA" '.metadata += {outputSchema: $schema}')
 fi
 
-api_call POST "/task-management/create" "$BODY"
+BODY=$(jq -n --argjson workItem "$WORK_ITEM" '{workItem: $workItem}')
+
+api_call POST "/task-pool/add" "$BODY"

package/config/skills/agent/core/get-my-active-work/SKILL.md

@@ -19,8 +19,10 @@ assignableRoles:
   - generalist
   - sales
   - support
+  # Canonical convention is hyphenated (`team-lead`); the underscore variant
+  # (`team_lead`) was a duplicate-key typo discovered during the 4-piece skill-mistake
+  # audit (post-PR #446 merge). Removing it to keep the role-name surface single-shape.
   - team-lead
-  - team_lead
   - orchestrator
 triggers:
   - get my active work

package/config/skills/agent/core/get-my-tasks/execute.sh

@@ -81,10 +81,12 @@ if [ -n "$INPUT_JSON" ]; then
 fi
 
 require_param "sessionName (--session)" "$SESSION_NAME"
-require_param "projectPath (--project)" "$PROJECT_PATH"
+# `projectPath` is no longer required for V3 — kept in the input shape
+# for backwards compat with callers who pass it.
 
-# URL-encode the session name and project path for query parameters
+# Per spec 2026-05-06-task-management-v1-deprecation.md, this skill now
+# queries the V3 task-pool. Returns all WorkItems targeted at this agent
+# session that are still in a non-terminal status. Callers wanting only
+# the running one can filter on `.workItems[] | select(.status=="running")`.
 ENCODED_SESSION=$(printf '%s' "$SESSION_NAME" | jq -sRr @uri)
-ENCODED_PROJECT=$(printf '%s' "$PROJECT_PATH" | jq -sRr @uri)
-
-api_call GET "/task-management/tasks?sessionName=${ENCODED_SESSION}&projectPath=${ENCODED_PROJECT}"
+api_call GET "/task-pool/items?target=${ENCODED_SESSION}"

package/config/skills/agent/core/handoff-task/execute.sh

@@ -30,12 +30,12 @@ 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\":\"from-agent\",\"to\":\"target-session\",\"reason\":\"...\",\"progress\":\"...\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"sessionName\":\"from-agent\",\"to\":\"target-session\",\"workItemId\":\"abc-123\",\"reason\":\"...\",\"progress\":\"...\"}'"
 
 # --- Parse parameters ---
 SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
 TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
-TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.taskPath // .absoluteTaskPath // empty')
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
 REASON=$(printf '%s' "$INPUT" | jq -r '.reason // "Task handoff"')
 PROGRESS=$(printf '%s' "$INPUT" | jq -r '.progress // empty')
 FINDINGS=$(printf '%s' "$INPUT" | jq -r '.findings // empty')
@@ -53,10 +53,17 @@ require_param "reason" "$REASON"
 CREWLY_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
 TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 
-# --- Step 0: Fission guard check (rate limit before handoff) ---
+# --- Step 0: Resolve target WorkItem if not supplied ---
+# Resolve order: explicit workItemId > the agent's currently-running claim.
+if [ -z "$WORK_ITEM_ID" ]; then
+  POOL_RESP=$(api_call GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
+  WORK_ITEM_ID=$(echo "$POOL_RESP" | jq -r '.workItems[0].id // .data[0].id // empty' 2>/dev/null || true)
+fi
+
+# --- Step 1: Fission guard check (rate limit before handoff) ---
 # Non-blocking: if the fission API is unavailable, proceed with handoff.
 FISSION_BODY=$(jq -n \
-  --arg parentWorkItemId "${TASK_PATH:-handoff-stub}" \
+  --arg parentWorkItemId "${WORK_ITEM_ID:-handoff-stub}" \
   --arg agentId "$SESSION_NAME" \
   '{parentWorkItemId: $parentWorkItemId, agentId: $agentId}')
 
@@ -69,40 +76,23 @@ if [ "$fission_allowed" = "false" ]; then
   exit 1
 fi
 
-# --- Step 1: Record handoff in backend (reassigns task on the task board) ---
-HANDOFF_BODY=$(jq -n \
-  --arg from "$SESSION_NAME" \
-  --arg to "$TO" \
-  --arg taskPath "${TASK_PATH:-}" \
-  --arg reason "$REASON" \
-  --arg progress "${PROGRESS:-}" \
-  --arg projectPath "${PROJECT_PATH:-}" \
-  '{from: $from, to: $to, taskPath: $taskPath, reason: $reason, progress: $progress, projectPath: $projectPath}')
-
-echo "Recording handoff ${SESSION_NAME} → ${TO}..." >&2
-handoff_result=$(api_call POST "/task-management/handoff" "$HANDOFF_BODY" 2>/dev/null) || handoff_result='{"tracked":false,"error":"handoff API unavailable"}'
-
-# --- Step 2: Append handoff metadata to task file (if provided and exists) ---
-if [ -n "$TASK_PATH" ] && [ -f "$TASK_PATH" ]; then
-  cat >> "$TASK_PATH" << HANDOFF_EOF
-
-## Handoff Record
-- **Handed off to**: ${TO}
-- **Handed off from**: ${SESSION_NAME}
-- **Reason**: ${REASON}
-- **Timestamp**: ${TIMESTAMP}
-HANDOFF_EOF
-
-  # Append progress/findings/blockers if provided
-  if [ -n "$PROGRESS" ]; then
-    printf '\n### Progress at Handoff\n%s\n' "$PROGRESS" >> "$TASK_PATH"
-  fi
-  if [ -n "$FINDINGS" ]; then
-    printf '\n### Key Findings\n%s\n' "$FINDINGS" >> "$TASK_PATH"
-  fi
-  if [ -n "$BLOCKERS" ]; then
-    printf '\n### Blockers\n%s\n' "$BLOCKERS" >> "$TASK_PATH"
-  fi
+# --- Step 2: Record handoff via V3 (reassigns target on the WorkItem) ---
+# Spec 2026-05-06-task-management-v1-deprecation.md: handoff is now a
+# `target` field flip on the WorkItem plus an audit-trail note. The legacy
+# `/task-management/handoff` endpoint (which moved a `.md` file between
+# agent task directories) is gone.
+if [ -n "$WORK_ITEM_ID" ]; then
+  HANDOFF_BODY=$(jq -n \
+    --arg fromAgent "$SESSION_NAME" \
+    --arg newTarget "$TO" \
+    --arg reason "$REASON" \
+    '{newTarget: $newTarget, fromAgent: $fromAgent, reason: $reason}')
+
+  echo "Recording handoff ${SESSION_NAME} → ${TO} on WI ${WORK_ITEM_ID}..." >&2
+  handoff_result=$(api_call POST "/task-pool/items/${WORK_ITEM_ID}/handoff" "$HANDOFF_BODY" 2>/dev/null) \
+    || handoff_result='{"tracked":false,"error":"handoff API unavailable"}'
+else
+  handoff_result='{"tracked":false,"warning":"no active WorkItem for handing-off agent"}'
 fi
 
 # --- Step 3: Build and deliver context message to target agent ---
@@ -129,14 +119,10 @@ if [ -n "$BLOCKERS" ]; then
   printf '\n## Blockers / Notes\n%s\n' "$BLOCKERS" >> "$HANDOFF_MSG_FILE"
 fi
 
-if [ -n "$TASK_PATH" ]; then
-  printf '\n## Task File\n%s\n' "$TASK_PATH" >> "$HANDOFF_MSG_FILE"
-  # Include task content if file exists (first 100 lines)
-  if [ -f "$TASK_PATH" ]; then
-    printf '\n## Original Task Content\n```\n' >> "$HANDOFF_MSG_FILE"
-    head -100 "$TASK_PATH" >> "$HANDOFF_MSG_FILE" 2>/dev/null || true
-    printf '\n```\n' >> "$HANDOFF_MSG_FILE"
-  fi
+if [ -n "$WORK_ITEM_ID" ]; then
+  printf '\n## WorkItem\n%s\n' "$WORK_ITEM_ID" >> "$HANDOFF_MSG_FILE"
+  printf '\nFetch full brief: bash %s/config/skills/agent/core/read-task/execute.sh '"'"'{"workItemId":"%s"}'"'"'\n' \
+    "$CREWLY_ROOT" "$WORK_ITEM_ID" >> "$HANDOFF_MSG_FILE"
 fi
 
 cat >> "$HANDOFF_MSG_FILE" << FOOTER_EOF
@@ -173,7 +159,7 @@ jq -n \
   --arg from "$SESSION_NAME" \
   --arg to "$TO" \
   --arg reason "$REASON" \
-  --arg taskPath "${TASK_PATH:-}" \
+  --arg workItemId "${WORK_ITEM_ID:-}" \
   --arg timestamp "$TIMESTAMP" \
   --argjson delivery "$(echo "$deliver_result" | jq '.' 2>/dev/null || echo '{"raw":"'"${deliver_result//\"/\\\"}"'"}')" \
   --argjson tracking "$(echo "$handoff_result" | jq '.' 2>/dev/null || echo '{"raw":"'"${handoff_result//\"/\\\"}"'"}')" \
@@ -183,7 +169,7 @@ jq -n \
       from: $from,
       to: $to,
       reason: $reason,
-      taskPath: (if $taskPath == "" then null else $taskPath end),
+      workItemId: (if $workItemId == "" then null else $workItemId end),
       timestamp: $timestamp
     },
     delivery: $delivery,

package/config/skills/agent/core/list-my-followups/SKILL.md

@@ -1,3 +1,21 @@
+---
+name: list-my-followups
+description: List every follow-up trigger owned by your team — call before creating a new watcher to avoid duplicates, or when auditing why something keeps firing.
+version: 1.0.0
+category: followup
+skillType: claude-skill
+tags:
+  - followup
+  - trigger
+  - audit
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 15000
+---
+
 # list-my-followups
 
 List every follow-up trigger owned by your team. Call this **before** creating

package/config/skills/agent/core/read-task/execute.sh

@@ -1,17 +1,30 @@
 #!/bin/bash
-# Read the full details of a task file by its absolute path
+# Fetch a single WorkItem by id from the V3 task-pool.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. Replaces
+# `POST /task-management/read-task`, which read the `.md` file body from
+# the project's `.crewly/tasks/` filesystem. With v1 retired, the full
+# task body, brief, and worker output live on the WorkItem itself.
+#
+# Input: { "workItemId": "abc-123" }
+# Backwards-compat shim: if `absoluteTaskPath` is supplied instead, refuse
+# with a hard error directing callers to pass `workItemId`.
+
 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 '{\"absoluteTaskPath\":\"/path/to/task\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"abc-123\"}'"
+
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
+LEGACY_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
 
-ABSOLUTE_TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
-require_param "absoluteTaskPath" "$ABSOLUTE_TASK_PATH"
+if [ -z "$WORK_ITEM_ID" ] && [ -n "$LEGACY_PATH" ]; then
+  echo '{"error":"`absoluteTaskPath` is no longer accepted — pass `workItemId`. See spec/2026-05-06-task-management-v1-deprecation.md"}' >&2
+  exit 1
+fi
 
-BODY=$(jq -n --arg absoluteTaskPath "$ABSOLUTE_TASK_PATH" \
-  --arg taskPath "$ABSOLUTE_TASK_PATH" \
-  '{absoluteTaskPath: $absoluteTaskPath, taskPath: $taskPath}')
+require_param "workItemId" "$WORK_ITEM_ID"
 
-api_call POST "/task-management/read-task" "$BODY"
+api_call GET "/task-pool/items/${WORK_ITEM_ID}"

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

@@ -4,6 +4,13 @@ description: Retrieve stored memories relevant to a given context or query.
 version: 1.0.0
 category: memory
 skillType: claude-skill
+# Per orchestrator-namespace convention: orc accesses memory via a different
+# mechanism (internal `recallFromAllAgents()` in backend/src/services/memory/memory.service.ts:1047,
+# not surfaced as a skill — orc reads the cross-agent view directly through the
+# service layer when assembling team context). If a future PR adds an
+# orc-namespaced recall wrapper, update this comment to cross-ref. Until then,
+# keep orchestrator EXCLUDED here.
+# Spec provenance: 4-piece skill-mistake fix dispatch (Sam→Quinn, post-PR #446 merge).
 assignableRoles:
   - developer
   - qa

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

@@ -46,10 +46,26 @@ Store a memory entry for future recall. Use this to persist important context, d
 | `--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` |
+| `--category` / `-C` | `category` | Yes | See category × scope matrix below |
 | `--scope` / `-s` | `scope` | Yes | Scope: `agent` or `project` |
 | `--project` / `-p` | `projectPath` | No | Project path (required for `project` scope) |
 
+### Valid `category` × `scope` matrix
+
+| Category          | `scope=agent` | `scope=project` | Notes |
+|-------------------|:-------------:|:---------------:|-------|
+| `fact`            | ✅            | —               | Personal best-practice / "always do X". |
+| `pattern`         | ✅            | ✅              | Reusable workflow or code pattern. |
+| `gotcha`          | ✅ (F4 fix)   | ✅              | Things to avoid; agent-scope = personal, project-scope = team-wide. |
+| `preference`      | ✅            | —               | Updates your `AgentPreferences` (verbosity, breakdown size, etc.). |
+| `decision`        | —             | ✅              | Architectural / design decision (project-only). |
+| `relationship`    | —             | ✅              | Component-to-component edge in the codebase (project-only). |
+| `user_preference` | —             | ✅              | Project-scoped user preference (project-only). |
+
+> **Aliases / common mistakes:**
+> - `workflow` is **not** a public category — use `pattern` (it maps to internal `workflow` automatically).
+> - For "this approach failed for me last time" → use `category=gotcha scope=agent` (don't pollute project memory).
+
 ## Examples — CLI Flags (preferred)
 
 ```bash

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

@@ -24,7 +24,11 @@ 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)
+  --category | -C   Category (required) — valid values depend on scope:
+                      scope=agent   : fact, pattern, gotcha, preference
+                      scope=project : pattern, decision, gotcha, relationship, user_preference
+                    Aliases / common mistakes:
+                      'workflow' is NOT a public category — use 'pattern' instead.
   --scope    | -s   Scope: project or agent (required)
   --project  | -p   Project path (required for project scope)
   --json     | -j   Raw JSON payload

package/config/skills/agent/core/reply-channel/SKILL.md

@@ -1,3 +1,22 @@
+---
+name: reply-channel
+description: Send an agent-authored message back to a chat channel — used by the chat MVP dispatch loop after processing a `[CHAT:<channelId>]` prompt.
+version: 1.0.0
+category: comm
+skillType: claude-skill
+tags:
+  - chat
+  - comm
+  - channel
+  - reply
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 15000
+---
+
 # reply-channel
 
 Send an agent-authored message back to a chat channel. Used by the chat MVP

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

@@ -1,30 +1,53 @@
 #!/bin/bash
-# Report progress on the current task
+# Append a progress note to the agent's currently-claimed WorkItem.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. Replaces
+# `POST /task-management/sync`, which appended progress lines to the `.md`
+# task body. Notes now accumulate under `WorkItem.metadata.notes[]`.
+#
+# Input shape:
+#   { "sessionName": "dev-1", "progress": 50, "current": "Implementing tests",
+#     "workItemId"?: "abc-123",  // optional override
+#     "completed"?: ["t1"], "nextSteps"?: ["t2"], "blockers"?: ["..."] }
+#
+# If `workItemId` is omitted, the agent's currently-running claim is
+# resolved from the pool.
+
 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\",\"progress\":50,\"current\":\"Implementing tests\",\"taskGroup\":\"delegated\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"sessionName\":\"dev-1\",\"progress\":50,\"current\":\"Implementing tests\"}'"
 
 SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
 PROGRESS=$(printf '%s' "$INPUT" | jq -r '.progress // empty')
 CURRENT=$(printf '%s' "$INPUT" | jq -r '.current // empty')
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
 require_param "sessionName" "$SESSION_NAME"
 require_param "progress" "$PROGRESS"
 require_param "current" "$CURRENT"
 
-# Build body with required and optional fields
-BODY=$(printf '%s' "$INPUT" | jq '{
-  sessionName: .sessionName,
-  progress: (.progress | tonumber),
-  current: .current
-} +
-  (if .projectPath then {projectPath: .projectPath} else {} end) +
-  (if .taskGroup then {taskGroup: .taskGroup} else {} end) +
-  (if .completed then {completed: .completed} else {} end) +
-  (if .nextSteps then {nextSteps: .nextSteps} else {} end) +
-  (if .blockers then {blockers: .blockers} else {} end) +
-  (if .ticketId then {ticketId: .ticketId} else {} end)')
-
-api_call POST "/task-management/sync" "$BODY"
+# Resolve target WI: explicit > running claim for this agent
+if [ -z "$WORK_ITEM_ID" ]; then
+  POOL_RESP=$(api_call GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
+  WORK_ITEM_ID=$(echo "$POOL_RESP" | jq -r '.workItems[0].id // .data[0].id // empty' 2>/dev/null || true)
+fi
+
+if [ -z "$WORK_ITEM_ID" ]; then
+  echo '{"warning":"no active WorkItem for session — progress note discarded"}' >&2
+  exit 0
+fi
+
+# Compose a single multi-line note from the structured fields
+NOTE=$(printf '%s' "$INPUT" | jq -r '
+  ([
+    "Progress: \(.progress)% — \(.current)",
+    (if (.completed // [] | length) > 0 then "Completed: \(.completed | join(", "))" else empty end),
+    (if (.nextSteps // [] | length) > 0 then "Next: \(.nextSteps | join(", "))" else empty end),
+    (if (.blockers // [] | length) > 0 then "Blockers: \(.blockers | join(", "))" else empty end)
+  ] | join("\n"))')
+
+BODY=$(jq -n --arg author "$SESSION_NAME" --arg note "$NOTE" '{author: $author, note: $note}')
+
+api_call POST "/task-pool/items/${WORK_ITEM_ID}/notes" "$BODY"