coordinate-handoffs

name	coordinate-handoffs
description	Validate sub-agent handoff artefacts, sequence phase transitions, and manage retry and escalation logic. Activate after each sub-agent terminates to determine next action.
license	ELv2
compatibility	Works with any filesystem-based AI coding agent
metadata	{"author":"gaai-framework","version":"1.0","category":"delivery","track":"delivery","id":"SKILL-DEL-009","updated_at":"2026-02-18T00:00:00.000Z","status":"stable"}
inputs	["contexts/artefacts/plans/{id}.execution-plan.md (after Planning phase)","contexts/artefacts/impl-reports/{id}.impl-report.md (after Implementation phase)","contexts/artefacts/qa-reports/{id}.qa-report.md (after QA phase)","contexts/artefacts/delivery/{id}.micro-delivery-report.md (Tier 1)","contexts/artefacts/plans/{id}.plan-blocked.md (on Planning failure)"]
outputs	["next-action decision (inline — to Orchestrator)"]

Coordinate Handoffs

Purpose / When to Activate

Activate after each sub-agent writes its handoff artefact and terminates.

The Orchestrator cannot proceed to the next phase until it has validated the current phase's output. This skill validates artefact structure, interprets verdicts, and returns a clear next-action decision.

---

Process

After Planning Sub-Agent terminates

1. Check: does {id}.execution-plan.md exist?
   • No → check for {id}.plan-blocked.md
     • If blocked artefact exists: ESCALATE with block reason
     • If neither exists: RE-SPAWN Planning Sub-Agent (attempt 2)
2. Check: does the execution plan contain required sections? (Implementation Sequence, Edge Cases, Test Checkpoints, Risk Register)
   • No → RE-SPAWN Planning Sub-Agent with validation failure noted (attempt 2)
   • After 2 failed attempts: ESCALATE
3. Valid artefact: → PROCEED to Implementation phase

After Implementation Sub-Agent terminates

1. Check: does {id}.impl-report.md exist?
   • No: RE-SPAWN (attempt 2), then ESCALATE
2. Check: does impl-report contain required sections? (changes made, criteria mapping, rules applied)
   • No: RE-SPAWN with validation failure noted
3. Check: impl-report notes any blocking failures?
   • Yes: RE-SPAWN with enriched context (add failure details to bundle)
   • Note: implementation self-reported blocking failures (from impl-report) count as the first attempt. A single RE-SPAWN with enriched context is allowed. If the second attempt also reports blocking failures, escalate — do not enter QA.
4. Valid artefact: → PROCEED to QA phase

After QA Sub-Agent terminates

1. Read verdict from {id}.qa-report.md:
   • PASS: → INTEGRATE, MERGE & COMPLETE Story:
     1. Rebase on staging (in worktree): git merge staging into story branch
     2. Verify build: npx tsc --noEmit in worktree
        • If fails with errors → fix and re-commit