---
name: rp-subagent-dispatch
description: >-
  How the orchestrator dispatches Developer and QA subagents so a run's token cost stays bounded: a fresh subagent per round, a short deterministic handoff file, a context budget with a clean handoff, and bounded helpers instead of raw ledgers.
title: rp-subagent-dispatch
canonical_url: https://skilld.dev/gh/wix/skills/rp-subagent-dispatch
last_updated: 2026-11-14T03:05:56.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install wix/skills/rp-subagent-dispatch`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/rp-subagent-dispatch`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/wix/skills/rp-subagent-dispatch) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/rp-subagent-dispatch`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/rp-subagent-dispatch --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/rp-subagent-dispatch --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# rp-subagent-dispatch

Most of a run's token cost is history re-sent on every model call, not tool output. A
subagent that is resumed round after round keeps re-sending everything it ever saw: one
measured run spent 239.5M tokens in a single resumed Developer whose context reached 919K,
out of 522M for the whole run. These rules keep each subagent short.

## A fresh subagent every round

- Every Developer or QA dispatch is a **new** subagent. Never resume or re-message one from
  an earlier round — not for QA findings, a crash fix, a retry, or "continue".
- Before each re-dispatch, write the handoff:

  ```bash
  node skills/wix-replatform/scripts/subagent-handoff.js write --project <dir> \
    --stage <stage> --resource <resources/rp-...> --outcome <outcome> \
    [--findings <QA result file>] [--changed <path,path>] [--notes <one line>]
  ```

  `outcome` is `done`, `failed`, `qa_findings`, `budget_exceeded`, `needs_decision` or
  `resume_limit`. It writes `state/handoffs/<stage>-<round>.json` (≤ 8 KB) from durable state
  only: the QA findings verbatim, a write-log summary (counts, never rows), the completion
  report status, open user actions and the paths changed last round. It prints
  `{ file, round, bytes, budgetRoundsWithoutProgress }`.
- The new subagent's prompt is only: the resource path, the project directory and the handoff
  file. Paste nothing else — no earlier result text, transcript or log. The subagent reads the
  handoff first; anything it trimmed is still in its source files.

## A context budget per subagent

- Each Developer works within about **200K context or 150 model calls**, whichever comes first.
- Near the budget it stops starting new work, runs `subagent-handoff.js write --reason
  budget_exceeded` (with `--changed` and `--notes` for where it stopped), and returns
  `budget_exceeded` with the handoff path.
- `budget_exceeded` is not a failure and not a QA miss. Dispatch a fresh Developer for the same
  resource with that handoff.
- When the printed `budgetRoundsWithoutProgress` reaches 3 (three budget rounds in a row with no
  new settled import progress), tell the operator in one status line that the stage is repeating
  without progress, add the same note to the next handoff (`--notes`), and keep going. Never stop
  the run for it.
- Where the host does not report context size, count your own model calls, and keep every tool
  output under 20 KB by using the bounded helpers below.

## Bounded helpers instead of raw files

- Never open, `cat`, `grep`, `tail` or `jq` `state/attempts/write-attempts.ndjson` or
  `logs/import-audit.ndjson` — they reach tens of MB and stay in context for the rest of the
  subagent's life. Use:

  ```bash
  node skills/wix-replatform/scripts/write-log-summary.js --project <dir> \
    [--entity <targetEntityType>] [--status <status>] [--limit 20] \
    [--run latest | --since-run <runId>] [--log audit] [--json]
  ```

  Default output: counts per entity × status (current status per attempt) and top error
  classes; `--entity`/`--status` add up to `--limit` matching rows. Output stays ≤ 4 KB.
- Run a generated import with `scripts/import-supervise.js` (see `rp-execute-import`): one
  tool call that launches, polls, resumes and returns `complete`, `needs_decision` or
  `resume_limit`, instead of one model call per poll.
