Typed Phase Handoff Contracts and Validator for Multi-Agent Pipelines

Has Claude Code define schema-based handoff contracts between agent phases, generate a validator, and add contract tests. Supports the decision of which phase boundaries need strict contracts versus lightweight checks.

You get: Handoff inventory table, classification table and files changed with purpose

More like this

The prompt

typed-phase-handoff-contracts-and-validator-for-multi-agent-pipelines.md
Role: You are a pipeline reliability engineer using Claude Code in the repository at {repo_path}, with permission to read files, edit code, and run tests.

Context: A multi-agent pipeline for {pipeline_goal} passes data between phases ({phase_list}). Handoffs currently fail silently when an upstream agent emits missing or malformed fields. The decision to support: which phase boundaries need strict contracts, which need warnings only, and what the rollout order should be.

Task: Inventory every phase handoff, define a versioned contract per boundary, implement a validator in {language}, and add contract tests that include malformed and partial payloads.

Inputs (request missing items first; keep assumptions in their own section):
- {phase_list} with producer and consumer for each handoff
- {schema_format}: JSON Schema, Pydantic, Zod, or other
- {strictness_policy}: which boundaries must block on failure
- Sample payloads (sanitized) or permission to infer them from code
- {test_framework}

Workflow:
1. Inventory: search the code for where each phase reads and writes its payload. Produce a table with columns Handoff, Producer, Consumer, Fields observed, Evidence (file and line).
2. Contract design: for each handoff define required fields, optional fields, types, size limits, a version string, and an owner.
3. Classify each boundary as Block, Warn, or Log, with a justification tied to blast radius.
4. Implement: contract definitions, a validate_handoff function returning structured errors, and an integration hook at the boundaries. On Block, the pipeline must halt and record the error in the run log.
5. Test: valid payload, missing required field, wrong type, extra unknown field, oversized payload, and version mismatch. Run tests and report actual outcomes.
6. Document: add a short CONTRACTS section to the existing docs, not a new sprawling file.

Constraints:
- Do not change phase business logic beyond adding the validation hook
- Do not invent fields that have no evidence in code; flag them as proposals
- Keep errors machine-readable with a code, path, and message
- Backward compatibility: support the previous contract version for one release if one exists
- No private data in fixtures

Output format:
1. Handoff inventory table
2. Classification table: Handoff, Policy, Reason, Rollout order
3. Files changed with purpose
4. Validator interface and an example error object
5. Test matrix: Case, Expected, Actual
6. Risks, missing information, and next actions as a checklist

Acceptance criteria:
- Every handoff in the inventory has a contract or an explicit exemption with a reason
- Block-policy violations stop the run before the consumer phase starts
- Error objects identify the failing field path
- Tests cover all six cases above for at least the highest-risk handoff
- Claims in the inventory cite file evidence

Quality checks:
- Re-run the full test suite and confirm no regressions
- Verify no contract references a field absent from both code and samples without being labeled a proposal
- Check that version handling is tested
- List anything you could not verify

Example output

AI-written example
# ===== pipeline/contracts.py =====
# Handoff contracts for ticket-triage pipeline (repo: /srv/work/ticket-pipeline)
#
# Classification (rollout order in brackets):
#   research -> draft    BLOCK  [1] drafts go to customers; bad sources become wrong replies
#   classify -> research BLOCK  [2] wrong category routes the ticket to the wrong knowledge base
#   draft    -> review   WARN   [3] a human reviewer catches issues; schema drift is still worth surfacing
#   intake   -> classify LOG    [4] free-text input; classify already normalizes it
#
# Fields marked PROPOSAL have no ev
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Best used when handoffs are implicit, such as free-form dicts passed between agents. Provide sanitized sample payloads if available. Start with the highest-risk boundary if the pipeline is large and ask for a phased rollout.

Questions about this prompt

Orchestrator System Prompt Builder with Progress Ledger and Stop Conditions

Writes a ready-to-deploy orchestrator system prompt that delegates to your workers, tracks progress in a ledger, merges results and stops on defined conditions.

Parallel Git Worktree Task Split with Interface Contracts and Merge Order

Turns a pasted feature spec into independent coding-agent tasks with file ownership, interface contracts, a merge order and a done command for each task.

Agent Run Post-Mortem: Trace Root Cause and Prompt or Tool Fixes

Analyzes a pasted agent trace to find the first real failure and proposes exact prompt rewrites or tool changes, each with a test.

Checkpoint and Rollback Manager with Compensation Steps and Failure Injection Tests

Guides Claude Code to implement checkpoint snapshots, rollback modes, and compensating actions for side-effecting agent phases, then prove them with failure-injection tests. Helps you decide the rollback strategy per phase.

DAG Scheduler with Fan-Out/Fan-In Barriers and Resumable Run Ledger for Agent Pipelines

Guides Claude Code to build or refactor a dependency-aware DAG scheduler for agent phases, with cycle validation, bounded parallelism, join policies, retries, and an append-only run ledger so interrupted runs resume without redoing finished nodes.

Subagent Fan-Out Plan for a Large Codebase Migration

Plans a big migration so an orchestrating agent can split it into independent chunks for parallel subagents, each with a clear brief, a verification command and merge rules.

Coding Agent Task Brief with Guardrails, Test Plan, and Rollback Steps

Creates a scoped brief for an AI coding agent that limits file changes, defines tests, and includes a rollback plan and review checklist.

Dependency Graph Planner for a Multi-Agent Software Release Workflow

Turns a list of release tasks into a dependency graph with parallel batches, critical path, shared-resource conflicts, and agent assignments. Supports the decision on what to run now versus wait on.

Session Handoff Note for a Fresh Claude Code Session

Writes a verified handoff file covering changes, decisions, open issues and next steps so a new Claude Code session can continue without re-reading the whole history.

Pre-Merge Code Review Checklist Skill (SKILL.md)

A save-ready SKILL.md that has your coding agent review a branch before merge: correctness, security, tests and migrations, with findings ranked by severity and no style nitpicks.

Sequential Agent Handoff Contract Builder for Research-to-Publish Chains

Designs the handoff contracts, stop conditions, and review gates for a sequential chain such as researcher, writer, editor, and fact-checker. Helps you decide whether the chain is ready to run.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.