From ai-agents-workflow
Owns dispatch orchestration — subtask skeleton, pre-dispatch checklist, post-dispatch artifact gate, clarifying-questions hold, rework routing, and token-saving rules. Use before EVERY agent dispatch (except direct-answer and Delivery PM task-level intake) and after every return. Bundle composition itself is delegated to context-minimizer.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-agents-workflow:orchestrator-dispatchThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Every agent dispatch MUST be preceded by the Pre-Dispatch Checklist and followed by the Artifact Gate. This skill owns all procedures from "orchestrator is about to dispatch an agent" through "orchestrator has accepted the returned artifact."
Every agent dispatch MUST be preceded by the Pre-Dispatch Checklist and followed by the Artifact Gate. This skill owns all procedures from "orchestrator is about to dispatch an agent" through "orchestrator has accepted the returned artifact."
All agents (Lead, Executor, Reviewer, Delivery PM, Design Agent, Integration Checker) receive their context via a dispatch bundle — a single markdown payload composed in memory by the orchestrator and embedded inline in the Task prompt parameter at dispatch time. Bundles are NOT written to disk. Agents do NOT independently read canonical contracts, PROJECT_CONFIG.md sections, or governance files.
Dispatch bundles are valid only in mode: normal. In mode: degraded-inline, the orchestrator MUST NOT compose synthetic bundles or record synthetic dispatch outcomes for those roles.
Startup sequence:
agents/<role>.md) — spins up with tools, model, permissionMode.<!-- dispatch-bundle:start ... --> and <!-- dispatch-bundle:end --> markers).ai-work.md.Bundle contents are assembled by the context-minimizer skill — see ${CLAUDE_PLUGIN_ROOT}/skills/context-minimizer/SKILL.md → "Bundle Format" for the section list (role contract, project context, governance, artifact input) and the inline-delivery rules.
Menu guard rail: the agent's allowed skills for the subtask are base_skills ∪ domain.skills; allowed plugins are base_plugins ∪ domain.plugins. Both lists are included in the dispatch bundle's Project Context section.
Audit trail: The only on-disk record of a bundle is a one-line entry in <subtask_id>/summary.md → <!-- section:dispatch-bundles -->: - <role> for <subtask_id> (cycle <n>): <token_count> tokens; sections: <list>; cache_misses: <list-or-none>. Reviewer reads these lines as part of the rollup.
Before every agent dispatch, the orchestrator MUST:
context-minimizer skill for the target agent role to assemble the bundle content in memory.context-minimizer skill's "Token Ceilings per Role" table. If exceeded, re-excerpt until it fits — never silently exceed.prompt parameter when dispatching the agent (wrapped in the <!-- dispatch-bundle:start ... --> / <!-- dispatch-bundle:end --> markers). Append the role-specific instruction line after the closing marker.<subtask_id>/summary.md → <!-- section:dispatch-bundles --> capturing role, target subtask, cycle, token count, sections included, and any cache misses.Agents work from the inline bundle (plus their own stub for tool/model config). Violation of this protocol is an orchestration defect.
The full procedure — skeleton creation steps, ultra-light variant, the file-existence bash checklist, and the missing-file recovery protocol — lives in ${CLAUDE_PLUGIN_ROOT}/skills/orchestrator-dispatch/references/pre-dispatch-procedure.md. Read once per session.
These checks are MANDATORY before every agent dispatch (including Lead, Executor, Reviewer, Design Agent, Integration Checker). They do NOT apply to Delivery PM (task-level, not subtask-level).
After the Lead returns, but BEFORE dispatching Executor (or Integration Checker when it would precede implementation), inspect the subtask's ai-work.md for a non-empty <!-- section:tep-clarifying-questions --> block:
awk '/<!-- section:tep-clarifying-questions -->/,/<!-- \/section:tep-clarifying-questions -->/' \
<artifact-root>/tasks/<task_id>/<subtask_id>/ai-work.md \
| grep -E '^\s*[0-9]+\.\s+\*\*' | head -1
If the grep returns a line (i.e., at least one numbered question exists), enter the clarifying-questions hold:
AskUserQuestion, one question per call (respecting the AskUserQuestion 2–4-options constraint; use "Other" for free text when the question cannot be pre-multi-choiced).### Answered <YYYY-MM-DD HH:MM UTC> subsection appended inside <!-- section:tep-clarifying-questions -->.orchestration-state.json → pending_user_actions to clear the hold once every question carries an answer.Answered subsection does Executor dispatch resume.This hold is a first-class user gate (sibling to P1 / P2 / P4). It does NOT require a P-number because it is subtask-local, but it is surfaced through the same orchestrator-user-gates skill so the UX is consistent.
An empty <!-- section:tep-clarifying-questions --> block, or its absence entirely, means no hold — proceed with Executor dispatch normally.
Every agent dispatch must terminate in one of exactly two valid outcomes:
ai-work.md (and finalized summary.md if the agent is the Reviewer — the orchestrator creates the summary.md skeleton during pre-dispatch; the Reviewer fills in the body fields), OR<!-- section:escalation-N --> in ai-work.md via the blocker-escalation-report skill.Reject any dispatch result that violates the footer protocol (${CLAUDE_PLUGIN_ROOT}/skills/orchestrator-telemetry/references/artifact-footer-protocol.md). Specifically, reject if the result:
ai-work.md (agent returns prose only, returns mid-investigation, or times out mid-turn).<subtask_id>/summary.md → ## Telemetry.### <role> in <subtask_id>/summary.md → ## Context Manifest.Stage-based section requirements (check after each agent):
| Stage | Required in ai-work.md |
|---|---|
| subtask-initialized | section:spec non-empty; sibling summary.md exists with ## Status, ## Telemetry, ## Context Manifest, and ## Open Gates headings |
| after-design-agent | + section:plan-addendum non-empty (if triggered) |
| after-lead | + section:tep non-empty |
| after-executor | + section:implementation non-empty |
| after-integration-checker | + section:integration-check non-empty (if triggered) |
| after-reviewer | + section:review non-empty; <subtask_id>/summary.md exists |
| escalation | + section:escalation-N matching count |
| task-done | task-root <artifact-root>/tasks/<task_id>/summary.md exists AND ## Task Status says workflow_state: complete with zero open gates and zero pending user actions |
Escalation-N assignment rule: Before appending an escalation section, count all existing <!-- section:escalation-* --> blocks in the subtask's ai-work.md and set N = count + 1. Always recount from the file — never rely on in-memory state.
On rejection for reason (1), do NOT re-dispatch the same agent. Inspect ai-work.md to determine what partial work occurred, then route to the relevant Lead for re-validation or surface the gap to the user.
Exception — context-exhaustion re-dispatch (executor only). The "do NOT re-dispatch" rule above has one explicit exception: when ALL of these hold, you MAY re-dispatch the executor instead of routing to Lead:
executorsection:implementation is empty or absent in ai-work.mdgit diff --stat from the consumer repo shows modifications to the task's target files (on the trivial path, check against the single target file from the inline TEP in the dispatch bundle — no persisted tep-target-files exists on that path)In this case the executor exhausted its context after applying edits but before writing its report. Do NOT discard the on-disk changes. Re-dispatch with a completion-only bundle: include the TEP (abbreviated), explicitly note that edits are already on disk (cite the git diff output), and instruct executor to verify the edits, run quality gates, and write the implementation report WITHOUT re-applying edits.
After every agent dispatch returns, run:
ls <artifact-root>/tasks/<task_id>/<subtask_id>/
head -20 <artifact-root>/tasks/<task_id>/<subtask_id>/summary.md
Verify:
ai-work.md exists and was modified (not just the skeleton).summary.md contains diagnostic headings (## Telemetry, ## Context Manifest).ai-work.md is missing entirely, this indicates the Pre-Dispatch Checklist was skipped — flag as an orchestration defect and do NOT proceed to the next agent in the chain.After accepting a subtask completion, read <subtask_id>/summary.md (written by Reviewer) and extend <artifact-root>/tasks/<task_id>/summary.md with a new row in the Context Breakdown table using the manifest totals from <!-- section:context-manifest -->, and refresh the Repeat reads line. Use the telemetry-summary skill for the exact template.
ai-work.md, not the full filetask-data.md, send only the matching delivery-subtask-* section by default<subtask_id>/summary.md directlydesign-* body sections from <!-- section:plan-addendum -->impl-files-changed, impl-tests-run, and direct contract excerpts from <!-- section:implementation -->delivery-routing, delivery-context-manifest, and delivery-telemetry are orchestrator-facing sections and should NOT be included in dispatch bundlessubtask_offsets from orchestration-state.json for targeted reads of task-data.md — never load the full file after the planning phaseFor review cycle N > 1, dispatch bundles carry only delta context. The canonical rules — Medium/Low routing (Executor → Reviewer direct), High routing (Executor → Lead → Executor → Reviewer), and the cycle-N>2 finding-ID delta — live in ${CLAUDE_PLUGIN_ROOT}/skills/context-minimizer/SKILL.md under ### executor → "Rework bundle (cycle N > 1)" / "Executor rework bundle (cycle N > 2) — finding-ID delta", and under ### reviewer → "Re-review bundle". Apply those rules when invoking context-minimizer for the rework dispatch; do not duplicate them here.
needs-replan and reversal triggers (schema_version 3+)The canonical reopen protocol (Reviewer needs-replan, P2-elected replan, reversal-packet, soft cap at stage_reopen_count >= 3, auto-diff for pending_subtasks_needing_rereview[]) lives in ${CLAUDE_PLUGIN_ROOT}/skills/orchestrator-state/references/stage-discipline.md. The orchestrator MUST evaluate it on every dispatch return and every P2 gate close BEFORE proceeding to the next subtask. Skipping the check is an orchestration defect — a needs-replan verdict with no stage rewind leaves the orchestrator stuck (planning-stage agents are not legal in stage=execution).
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub kingsharkg/ai-agents-workflow --plugin ai-agents-workflow