coordinate-handoffs

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 introduced by this story → fix and re-commit
        • If fails with pre-existing errors only → proceed (not this story's problem)
        • If unclear → ESCALATE with error list
     3. Verify tests: npx vitest run in worktree
        • Same triage: story-introduced failures → fix; pre-existing → proceed; unclear → ESCALATE 3b. Pre-push validation (project-defined commands): detect worker directories with changed source or config files in the story worktree diff, then for each affected worker execute the project-defined pre-push validation commands (see the project's delivery-validation rules in .gaai/project/contexts/rules/infrastructure.rules.md).
        • Skip condition: if git diff staging --name-only yields no files under any worker directory → skip with log note: no worker changes — skipping pre-push validation. A story modifying both .gaai/ files AND any worker file does NOT qualify for the skip — run validation for the affected worker(s).
        • Affected workers: collect unique worker root directories from the diff (any path under a workers/ subdirectory). For each directory: execute the project-defined validation commands from <worktree-root>/<worker-dir>/.
        • Triage logic (same as steps 2–3):
          • Failure introduced by this story → fix in worktree and re-commit before proceeding to step 4.
          • Failure pre-existing (reproducible on staging HEAD without this story's changes) → proceed without blocking. To verify: stash the story's changes, re-run the validation commands from the same worker directory, then pop the stash. If staging HEAD also fails → pre-existing; if only story HEAD fails → story-introduced.
          • Failure where provenance is unclear → ESCALATE with full error output; do not proceed to step 4.
        • Credential requirement: the project-defined validation commands MUST NOT require external API credentials. If any validation command requests credentials at runtime, ESCALATE immediately (project deploy-credential boundary); do not supply the credential.
     4. Push story branch to origin
     5. gh pr create --base staging --head story/{id}
     6. Wait for PR CI check to reach a terminal state (gh run watch)
        • If CI fails → diagnose: same triage as steps 2–3 (fix story issues, ignore pre-existing)
        • If CI fails on infra (missing secrets, missing bindings) → ESCALATE with logs
     7. gh pr merge --squash — immediate merge to staging
        • If merge fails (conflict): merge staging into branch, resolve, push, retry merge
        • If merge still fails after 2 attempts: ESCALATE with conflict details
        • If merge rejected (branch protection / checks required): wait for checks, then retry
     8. After successful merge: verify staging deploy CI (gh run list --branch staging --limit 1)
        • If staging deploy fails → ESCALATE with deploy logs (do not attempt infra fixes)
     9. If {id}.memory-delta.md exists in contexts/artefacts/memory-deltas/, validate that the file contains artefact_type: memory-delta in YAML frontmatter AND at least one of the canonical structural sections ## Confirmed Entries, ## Contradicted Entries, ## New Knowledge Candidates. If any check fails: SCHEMA_INVALID — RE-SPAWN QA Sub-Agent with the schema failure appended to the context bundle, up to 2 attempts, then ESCALATE. On ESCALATE after 2 RE-SPAWN attempts: the ESCALATE message MUST include (a) delta path contexts/artefacts/memory-deltas/{id}.memory-delta.md, (b) which check(s) failed — missing artefact_type: memory-delta frontmatter and/or which of the three canonical sections (## Confirmed Entries, ## Contradicted Entries, ## New Knowledge Candidates) were absent, (c) a reference to memory-alignment-check/SKILL.md Outputs section as the canonical schema authority. On PASS: flag the delta in the completion report for Discovery to action via memory-ingest. 9b. (Autonomous triage — daemon wrapper) The daemon wrapper also spawns a bounded Discovery subprocess in draft mode to pre-triage the delta. A new section Memory-Delta Triage (autonomous draft mode) is appended to the wrapper completion output (visible in the delivery log). Fields: drafts_produced, escalated_in_draft, circuit_breaker_tripped (boolean), autonomous_triage_failed (count). If no delta exists or circuit breaker is tripped, the section shows no triage — reason: {no_delta | circuit_breaker_tripped}. This section is additive — it does not replace step 9.
   10. Update backlog (push with retry-rebase pattern), cleanup worktree + delete remote branch NEVER leave a PR open. NEVER merge to production (staging only).
   • FAIL: spawn count < 2? → RE-SPAWN Implementation Sub-Agent with qa-report, then re-spawn QA Sub-Agent
   • FAIL after 2 cycles: → ESCALATE
   • ESCALATE: → ESCALATE (pass QA's escalation reason to human)

After MicroDelivery Sub-Agent terminates (Tier 1)

1. Read verdict from {id}.micro-delivery-report.md:
   • PASS: → COMPLETE Story
   • FAIL (attempt 1): → RE-SPAWN MicroDelivery Sub-Agent (max 1 retry)
   • FAIL (attempt 2): → ESCALATE
   • ESCALATE (complexity escalation): → RE-EVALUATE Story as Tier 2 and re-run with Core Team

---

Retry Limits

---

Escalation Package

When escalating, the Orchestrator surfaces to the human:

• Story ID and title
• Phase where escalation occurred
• Handoff artefact path (for full context)
• Specific failure reason
• Recommended next action (back to Discovery / manual fix / scope clarification)

---

Non-Goals

This skill must NOT:

• Make product decisions about what to implement
• Modify acceptance criteria
• Skip QA validation even under time pressure
• Delete worktrees containing uncommitted work without confirmation

---

Quality Checks

• No phase transition occurs without a validated handoff artefact
• Retry counts are tracked across the full Story lifecycle (not reset between phases)
• Escalation always includes a specific, actionable failure reason
• PASS is never issued unless {id}.qa-report.md contains explicit PASS verdict