Team Dispatch

Subagent dispatch arm. The PhaseSpec v1 contract is the only handoff format used between parent and child agents.

PhaseSpec v1 (the contract)

phase_id: <stable id, used as filename prefix and progress.md anchor>
parent_plan_ref: <pointer to task_plan.md#phase-N>
goal: <one sentence>
done_when:                       # testable exit criteria, no goalpost moving
  - <criterion 1>
  - <criterion 2>
inputs:
  files: [<read-only file refs>]
  memory_keys: [<keys for memory-layer recall>]
tools_allowed: [<list>]
tools_denied: [<list>]
budget:
  max_tool_calls: <int>
  max_wall_seconds: <int>
hitl_checkpoints: [<named checkpoint strings the child surfaces>]
return_contract:
  format: markdown+frontmatter
  fields: [summary, artifacts, open_questions, next_phase_hint]

Six load-bearing properties:

1. parentplanref is a pointer (file path with anchor), not a copy of the phase text. The child reads the file itself.
2. done_when is testable. Without it, completion is hallucinatable.
3. toolsallowed and toolsdenied map onto the Claude Code permission model and any other framework's permission story.
4. hitlcheckpoints are named strings the child surfaces by printing HITLCHECKPOINT: <name> to stdout.
5. return_contract forces structured output. The child returns markdown with frontmatter; the parent parses it deterministically.
6. phase_id doubles as the filename prefix for any artifacts the child writes.

Available subagents

Each is defined as agents/<name>.md in this plugin.

Operation: /mddesign:team dispatch <phase_id> [--agent <name>]

Step 1: Resolve the phase

• Read task_plan.md.
• Find the section header matching phase_id (case-insensitive).
• If not found, refuse.

Step 2: Pick the subagent

• If --agent <name> was passed, use it.
• Else infer from the phase: phases with "design", "ui", "tokens" in the title default to design-archeologist if /mddesign:harvest-shaped, else executor. All others default to executor.

Step 3: Build the PhaseSpec

• Pull goal from the phase title or first bullet.
• Pull done_when from the phase's "Status / Done When / Acceptance" section if it exists, else infer from the bullets and ask the user to confirm.
• Set inputs.files to [task_plan.md, findings.md] plus any files the phase mentions.
• Set tools_allowed to a sensible subset based on the phase (default: Read Write Edit Bash Glob Grep).
• Set budget defaults: maxtoolcalls: 80, maxwallseconds: 600.
• Set hitlcheckpoints to [beforecommit, beforedestructiveedit] plus phase-specific ones.

Step 4: HITL gate before dispatch

• Print the full PhaseSpec to the user.
• The PreToolUse hook intercepts the next Agent tool invocation (named checkpoint: beforesubagentdispatch) and requires approval.

Step 5: Dispatch

• Call the Agent tool with subagent_type: <chosen subagent> and a prompt that contains:

- The full PhaseSpec YAML - Plain-English instruction: "You are running PhaseSpec phase-<id>. Read every file in inputs.files. Do the work. Return a markdown document with the four fields in returncontract. If you hit any hitlcheckpoint, print HITL_CHECKPOINT: <name> and stop."

Step 6: Receive the return, validate

• Parse the subagent's final message.
• Verify it has the four required fields (summary, artifacts, openquestions, nextphase_hint).
• If invalid, log the failure and surface to user.

Step 7: Write to progress.md

Append under ### Phase <phase_id> Result:

### Phase <phase_id> Result

**Subagent:** <name>
**Status:** complete | partial | blocked
**Wall time:** <seconds>
**Tool calls used:** <int>

#### Summary
<from return.summary>

#### Artifacts
<from return.artifacts>

#### Open questions
<from return.open_questions>

#### Next phase hint
<from return.next_phase_hint>

Step 8: Optional review

• If auto-approve mode is on, dispatch reviewer with the executor's return + the PhaseSpec.
• If reviewer says approve, mark phase as complete in progress.md.
• If reject, append the reason to progress.md and surface to user.
• If escalate, halt and ask user.

Core rules

• Subagents never edit task_plan.md directly. Only this skill writes to progress.md, and only under ### Phase <id> Result.
• The PhaseSpec is the entire handoff. Subagents do not see the parent conversation.
• Markdown on disk is the shared state. No in-memory shared store across agents.
• Every dispatch goes through the beforesubagentdispatch HITL gate.