Task Coordination

This skill provides a general coordination mechanism for shared task directories. It prevents conflicts when both Manager and Workers need to access/modify the same task workspace.

Problem

When a Worker delegates work to Manager (e.g., git operations), the Manager modifies the Worker's workspace. During this time, the Worker might also be modifying files, causing potential conflicts.

Solution

Use .processing marker files to signal "work in progress". Any party (Worker or Manager) must check for this marker before modifying a task directory.

Task Directory Structure

tasks/{task-id}/
├── workspace/          # Code workspace (shared between Worker and Manager)
├── notes/              # Worker's notes, plan.md, memory (not synced by Manager)
├── meta.json           # Task metadata
└── .processing         # Processing marker file (created when work in progress)

The `.processing` Marker

Format

Location: tasks/{task-id}/.processing

{
  "processor": "manager",
  "started_at": "2026-02-25T10:30:00Z",
  "expires_at": "2026-02-25T10:45:00Z",
  "operation": "git-delegation"
}

Fields

Field	Description
`processor`	Who is processing: `manager` or worker name
`started_at`	ISO 8601 timestamp when processing started
`expires_at`	ISO 8601 timestamp when marker expires (15 min default)
`operation`	What operation is in progress (optional)

Expiration

The marker auto-expires after 15 minutes (configurable). This prevents deadlocks if a process crashes without removing the marker.

Coordination Protocol

Before Modifying Task Directory

Always follow this sequence:

Sync from MinIO first:

mc mirror "${HICLAW_STORAGE_PREFIX}/shared/tasks/${task_id}/" "/root/hiclaw-fs/shared/tasks/${task_id}/"

Check for .processing:
```
bash /opt/hiclaw/agent/skills/task-coordination/scripts/check-processing-marker.sh "$task_id"
```
- Exit code 0: Safe to proceed (no marker or expired)
- Exit code 1: Processing in progress, do NOT modify

If safe, create marker:

bash /opt/hiclaw/agent/skills/task-coordination/scripts/create-processing-marker.sh "$task_id" "manager"

Perform modifications

Remove marker:

bash /opt/hiclaw/agent/skills/task-coordination/scripts/remove-processing-marker.sh "$task_id"

Sync to MinIO:

mc mirror "/root/hiclaw-fs/shared/tasks/${task_id}/" "${HICLAW_STORAGE_PREFIX}/shared/tasks/${task_id}/" --overwrite

Scripts

check-processing-marker.sh

Check if a task directory is being processed.

bash /opt/hiclaw/agent/skills/task-coordination/scripts/check-processing-marker.sh <task-id>

Exit codes:

0: No marker or marker expired (safe to proceed)
1: Valid marker exists (do not modify)

create-processing-marker.sh

Create a processing marker for a task.

bash /opt/hiclaw/agent/skills/task-coordination/scripts/create-processing-marker.sh <task-id> <processor-name> [timeout-mins]

Parameters:

task-id: Task identifier (e.g., task-20260225-103000)
processor-name: Who is processing (manager or worker name)
timeout-mins: (Optional) Expiration timeout in minutes (default: 15)

remove-processing-marker.sh

Remove the processing marker after work is done.

bash /opt/hiclaw/agent/skills/task-coordination/scripts/remove-processing-marker.sh <task-id>

Integration Points

This coordination mechanism is used by:

git-delegation-management: Manager creates marker before git ops, removes after
git-delegation (Worker skill): Worker checks marker before modifying workspace

Best Practices

Always sync first: Never assume local state is current
Check before create: Don't blindly create markers; check first
Remove promptly: Remove marker as soon as work completes
Handle crashes: The expiration mechanism handles unexpected failures
Respect the marker: Never modify a task directory with an active marker

task-coordination