parallel-tasks

Files (1)

• SKILL.md

SKILL.md (first lines)

# parallel-tasks

## When this skill applies

Only activate this workflow when ALL of the following are true:

1. The environment variable `HERMES_LEAD_PARALLELISM` is set to `1`.
2. The operator request contains two or more clearly separable tasks.

If the flag is absent or the request is a single task, operate exactly as
before (serial, no ledger).

## Step 0 -- check the flag

```bash
echo "${HERMES_LEAD_PARALLELISM:-0}"
```

If the output is not `1`, stop here and handle the request serially.

## Step 1 -- classify each task

For every discrete task in the operator request, assign one of two
contention classes:

- `FREE` -- stateless work: research, drafting, file edits, web/HF
  lookups, code analysis, data processing, summarisation.  No shared
  browser session, no shared write handle, no voice synthesis.

- `EXCLUSIVE` -- anything that touches a shared, stateful resource:
  Playwright (any platform), image generation, voice synthesis, or any
  shared file or queue.  When in doubt, default to `EXCLUSIVE`.

Phase-1 rule: EXCLUSIVE tasks are NOT parallelised.  Run them yourself
one at a time after all FREE tasks are dispatched.

## Step 2 -- create a batch in the ledger

```bash
BATCH=$(
  HERMES_ORCH_DB="${HERMES_ORCH_DB:-/opt/claude-soma/registry.sqlite}" \
  python -m claude_soma.parallelism.ledger create-batch \
    --lead  "${HERMES_LEAD_NAME}" \
    --request "$(echo '<operator request text here>')" \
    --tasks-json '[
      {"task_id": "t1", "brief": "<worker prompt>", "contention_class": "FREE"},
      {"task_id": "t2", "brief": "<worker prompt>", "contention_class": "FREE"}
    ]' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['batch_id'])"
)
```

Record `$BATCH` -- you need it for every subsequent ledger call.

## Step 3 -- dispatch FREE tasks (respecting the cap)

The cap is `HERMES_LEAD_TEAM_CAP` (default 3).

For each FREE task:

1. Attempt to claim a slot:

   ```bash
   CLAIMED=$(
     python -m claude_soma.parallelism.ledger claim \
       --batch "$BATCH" --task "t1" --worker "worker-t1" \
       --cap "${HERMES_LEAD_TEAM_CAP:-3}" \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['claimed'])"
   )
   ```

2. If `CLAIMED` is `True`: dispatch via `Agent(prompt=<brief>, model="opus", run_in_background=True)` and record the agent handle as the worker.

3. If `CLAIMED` is `False` (at cap): leave the task pending.  Dispatch it
   once a running worker returns and frees a slot (see Step 5).

Never dispatch more workers than the cap allows.

## Step 4 -- EXCLUSIVE tasks run serially

Do each EXCLUSIVE task yourself, inline, one at a time, in the order the
operator listed them.  Do NOT dispatch them as background agents in Phase 1.
There are no leases or Playwright-parallelism mechanisms in Phase 1.

## Step 5 -- handle worker returns

As each background agent returns:

- Mark the task done in the ledger:

  ```bash
  python -m claude_soma.parallelism.ledger done \
    --batch "$BATCH" --task "t1" \
    --summary "<one-sentence result>"
  ```

- If the agent returned an error, mark it failed:

  ```bash
  python -m claude_soma.parallelism.ledger fail \
    --batch "$BATCH" --task "t1" \
    --error "<error text>"
  ```

- After marking done/failed, check for pending FREE tasks and dispatch
  the next one (claim-then-dispatch, same as Step 3).

## Step 6 -- consolidated report

When all tasks are in a terminal state (done, failed, or skipped):

1. Query batch state:

   ```bash
   python -m claude_soma.parallelism.ledger state --batch "$BATCH"
   ```

2. Synthesise a single reply to the operator summarising all results.
   The ledger is the authoritative record; do not rely on transcript alone.

From techfreakworm/claude-soma, MIT.

More from techfreakworm/claude-soma