hm-l3-subagent-delegation-patterns

Files (8)

• SKILL.md
• evals.json · evals/
• rich-gate-scorecard.md · metrics/
• checkpoint-protocols.md · references/
• delegation-envelopes.md · references/
• handoff-edge-guardrails.md · references/
• wave-execution.md · references/
• validate-skill.sh · scripts/

SKILL.md (first lines)

## Overview

Document and apply delegation patterns for subagent dispatch in OpenCode. Use when dispatching subagents, resuming interrupted sessions, implementing checkpoint protocols, or designing wave-based execution flows. Produces validated delegation configurations with session tracking and recovery procedures.

## The Iron Law

```
Delegation without session tracking is fire-and-forget. Always track, always resume, never recreate.
```

# Subagent Delegation Patterns
## On Load

1. Read `references/delegation-envelopes.md` — canonical dispatch envelope templates
2. Read `references/checkpoint-protocols.md` — checkpoint types, return formats, resume logic
3. Read `references/wave-execution.md` — wave-based parallel execution patterns
4. Read `references/handoff-edge-guardrails.md` — metadata and guardrails for every agent boundary

## Delegation Protocol

## Rich Handoff Lineage

Phase 30 adopts handoff and boundary concepts from OpenAI Agents SDK handoffs/guardrails, AutoGen `HandoffMessage`, and Claude Code subagent lifecycle hooks. Local rule: a delegation is a durable handoff edge with metadata, guardrails, and a return envelope; it is not just a prompt.

### Handoff Metadata Required

Every dispatch or resume envelope must include:

| Field | Purpose |
|-------|---------|
| `source_agent` | Who initiated the handoff and owns verification. |
| `target_agent` | Exact specialist identity or configured agent name. |
| `handoff_reason` | Why this child is the correct boundary crossing. |
| `allowed_destinations` | Whether the child may delegate further; empty means no. |
| `history_policy` | What context is included, filtered, or intentionally omitted. |
| `expected_return` | Status values, artifacts, evidence, and checkpoint format. |
| `resume_pointer` | Exact continuation point if interrupted. |

Before accepting a child return, run boundary guardrails: output shape, scope compliance, verification evidence, and unauthorized-tool/delegation detection.

### The Real Execution Model

Subagent dispatch is NOT fire-and-forget. It is:

```bash
# 1. INIT — load context via CLI tool or state file
INIT=$(cat .planning/STATE.md 2>/dev/null)

# 2. PARSE — extract current phase, incomplete plans, session state
# Fields: current_phase, completed_plans, incomplete_plans, blockers

# 3. CONNECT — verify session exists and is resumable
# Check task_id from previous delegation; if absent, treat as new

# 4. LAUNCH — execute with explicit session tracking
# Each task gets atomic commit with hash tracking
git add <specific-files>  # NEVER git add .
git commit -m "phase: {phase}-{plan} — {description}"
TASK_COMMIT=$(git rev-parse --short HEAD)

# 5. FAIL/RESUME — checkpoint detection
grep -n "type=\"checkpoint\"" [plan-path]
# Pattern A: No checkpoints → execute all
# Pattern B: Has checkpoints → execute until checkpoint, STOP, return structured message
# Pattern C: Continuation → verify commits exist, resume from specified task
```

### Resume by Session ID (NEVER Recreate)

When a session disconnects:
1. **DO NOT create new tasks** — resume the existing delegated task
2. Use the session ID from the previous `task` call
3. The task tool supports `task_id` parameter for resuming
4. Check `.planning/phases/NN-name/SUMMARY.md` for completion status
5. Re-query plan index to get incomplete plans
6. Re-execute only incomplete plans

### Handoff Edge Guardrails

| Edge | Guardrail | Reject if |
|------|-----------|-----------|
| Parent → child | Envelope has identity, scope, allowed destinations, history policy | Missing field or ambiguous owner |
| Child → tool | Tool use is within envelope permissions | Tool changes out-of-scope files or hidden state |
| Child → parent | Return includes evidence and status protocol | DONE without verification evidence |
| Parent → next child | Prior child accepted and trace recorded | Handoff chain has unresolved blocker |

### Checkpoint Return Format

When a checkpoint is reached, the subagent returns:

```markdown
## CHECKPOINT REACHED
**Type:** [human-verify | decision | human-action]
**Plan:** {phase}-{plan}
**Progress:** {completed}/{total} tasks

### Completed Tasks
| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1    | [name] | [hash] | [key files] |

### Current Task
**Task {N}:** [name]
**Status:** [blocked | awaiting verification | awaiting decision]
**Blocked by:** [specific blocker]
```

### Deviation Rules (Auto-Fix Protocol)

| Rule | Action | When |
|------|--------|------|
| 1 | Auto-fix bugs | Broken behavior, errors, null pointers |
| 2 | Auto-add missing functionality | Error handling, auth, validation |
| 3 | Auto-fix blocking issues | Missing deps, broken imports |
| 4 | Stop and ask | Architectural changes (new DB tables, major schema) |

**Fix attempt limit:** 3 per task → STOP, document in SUMMARY.md

### Wave-Based Parallel Execution

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin