plan-dispatcher

Files (6)

• SKILL.md
• host-matrix.md · references/
• protocol.md · references/
• dispatch.js · scripts/
• planning-context.js · scripts/
• state.js · scripts/

SKILL.md (first lines)

# Plan dispatcher

The main conversation is the sole dispatcher. Native workers perform bounded
tasks and report evidence; only the dispatcher accepts results and schedules
successors. Use the available ask-agent skill for fresh native contexts. An
explicitly serial caller may instead execute one task in its current main context
through the durable `main-context` identity described below; the caller enforces
capacity one. If neither path is available, report that boundary; do not
substitute a model subprocess.
Without the exact compact profile marker, every Ask-Agent delegation selects a
compatible package before execution. Bind
its selected absolute `SKILL.md` and helper, run `capabilities --skill-card ABS`,
and accept only its declared `shiploop-chain-ask-agent-managed-worktree/v1`
schema with the full current capability set: `helper-managed-worktree`,
`prepared-inspection`, `returned-commit-delivery`, `fingerprint-bound-close`
and `ignored-output-report`. The capability set is the gate, not a version
number; do not infer compatibility from a version, frontmatter or prose. Then use the existing `identity --skill-card ABS` binding and
preserve that selected-card/helper identity. For every Git task, explicitly select
Ask Agent's helper-managed route (it is not Ask Agent's default) and use that
selected managed-worktree helper before freezing dispatcher context. Non-Git delegation
uses the same compatible selected package but retains its generic context without
managed workspace preparation. The dispatcher is Ask-Agent's parent for Git
preparation, integration ordering and acceptance; it may delegate integration
execution.

The exact graph marker `source.agent_harness` equal to
`{"schema":"agent-harness/v1","ask_agent_interface":"compact"}` selects the
compact standalone Ask-Agent task interface for this new Dispatcher run. The
coordinator owns the run from `init`; the plan initiator is not a second owner.
This profile does not take over ShipLoop callbacks or reuse an existing
ShipLoop run. For each claim, prepare one compact task packet with the selected
Ask-Agent task package,
retain its path and both hashes, and use the emitted prompt and workspace
unchanged. The worker runs the packet-pinned `worker-start` and `worker-finish`
commands. After native collection, the coordinator runs the retained
`verify-return` command, then writes and publishes the Dispatcher report. Do not
repeat task preparation, run the legacy capability/workspace-helper preparation
path, or ask the worker to publish the Dispatcher report. Dispatcher actions,
ownership, verification, settlement, and dependency release remain authoritative.
Graphs without the exact marker keep the full-capability path described above.
For read-only assignments, start with `context.read_only: true` and
`context.write_scope: []`; otherwise omit `read_only` and provide a nonempty
write scope. Active attempts may share a workspace only when both explicitly
declare read-only and their canonical workspace paths are identical. Resource
collisions remain reserved.

Every run-scoped helper response includes an `instruction`. A `next` response's
`actions` are the graph-navigation authority. For dispatcher-scoped responses,
the dispatcher executes that prompt and the returned exact `next_argv`; do not
derive successors, recovery work, or a parallel schedule from the graph or this
document. In the default profile, the task-facing `report` response ends the
bounded task phase: the task returns it, including its `next_argv`, to the
dispatcher. In the exact compact profile, the coordinator publishes the report
after native collection and follows that response's `next_argv`. This skill
explains the response fields and fallbacks, but it is not another scheduler.

For a fresh native `launch` in the default profile, the parent assembles the complete returned worker
packet unchanged beside a compact **Current learnings** block with a Markdown
heading and short labeled bullets from the current conversation. State explicitly
when no learnings are relevant. Keep essential
facts and rationale inline, with evidence locators for detail; the block cannot
broaden the frozen task contract. Retain the effective assignment and launch
identity in the existing parent record or retained handoff, durably outside the
worker workspace, before recording the confirmed native handle. Parent launch,
status, collection, and waiting directions stay in parent
responses. The already-started worker receives its bounded task role, workspace,
scope-authorized facilities, checks, handoff, and report-return obligations.

For user-facing status, use the returned `progress` rather than reconstructing
task categories from conversation history. `next` computes it from the current
durable state and observed receipts; initialization, claim, start, launch
confirmation, settlement, retry and takeover also return it. The parent refreshes
it through the existing `next_argv` at the normal continuation boundary, after
executing the current instruction. A worker returns its exact report response
to the parent; it does not run the refresh itself.

`progress` accounts for every required task exactly once in `completed`, `active`,
`awaiting_verification`, `pending`, `blocked`, or `failed`, with a task description,
state, reason and unmet dependencies. `counts.remaining` includes all five
non-completed groups. `pending` includes tasks waiting on dependencies as well as
dependency-ready work; its `dependency_ready` flag never authorizes a launch.
`active` includes claimed and unconfirmed launching work, so read the row's state
instead of assuming the worker is running. A receipt remains awaiting verification
until settlement accepts it. `actions` still determines what the parent may do
next. These internal categories are facts to explain, not a required display
template. See [the status projection contract](references/protocol.md#categorical-progress)
for classification and observation limits.

At every native-agent boundary, status is mandatory. Write meaningful status
changes in clear, thoughtfully formatted Markdown, choosing the structure and
detail that fit the facts instead of following a fixed template or mechanically
dumping packet fields. Explain what happened, what has been accomplished, and
the immediate next work or remaining condition; emphasize significant findings,
blockers, or required user action. Ground the update in returned facts and
observed evidence. For each affected task, include a natural account of its
assignment, accepted or completed work, and any active, pending, or blocked
condition that determines the next work; choose useful wording and layout rather
than mechanically copying field names. Preserve pending dependencies and any gap between a worker result and
parent acceptance. Do not invent unreported work, future steps, percentages, or
an ETA.

Immediately before every native-agent call that starts or continues work,
including an initial launch, retry, or follow-up turn, identify the assignment and
say that it is launch intent until the native tool confirms it. On every native
return, including failed, blocked, or cancelled work, promptly describe the
reported outcome and state that it is not acceptance. A worker report remains a
claim about task work and checks until the parent independently accepts it; only
then may task work be described as accepted or completed. Describe whole-run
completion only when the script reports it. The parent dispatcher incorporates
worker results without duplicate overall updates, keeps protocol IDs and callbacks
internal unless they explain a problem, and preserves the required exact
launch/return notices and handoffs. Cadence, a native UI, or notification does not
replace either boundary update. Reporting does not change control flow: follow the
current authorized action or returned stop/handoff. A worker report or handoff
returns control to the parent; it does not end the run. If a dispatcher-scoped
response stops, describe prerequisites for future work without starting a wait or
retry.

Bind `scripts/dispatch.js` to the absolute directory containing this loaded

From whichguy/skill-craft, MIT.

More from whichguy/skill-craft