Workflow Coordinator

When to Use

• Coordinating handoffs between independent workflows (e.g., skill-editor to programming-pm)
• Discovering available target workflows for a handoff
• Validating handoff payloads before transmission
• Debugging multi-hop handoff chains via distributed tracing
• Adding handoff support to a new or existing skill

When NOT to Use

• Internal specialist handoffs within programming-pm (use internal v1.2 schema)
• Simple file passing between agents (no schema validation needed)
• Single-skill invocations (no coordination needed)
• Agent team coordination within a single task (use agent teams directly)

Pilot Scope Limitations

• Token counting: Guidance-only (heuristic estimation via

  characters / 4

  , not tiktoken)
• Schema validation: Manual invocation required (

  python3

  one-liner)
• Circular handoff detection: Advisory, not automated
• CLI tools: Deferred to v1.1 (

  claude-handoff validate

  , etc.)
• Adapter layer: Deferred to v1.1 (cross-version schema translation)
• Registry sync tool: Deferred to v1.1 (

  claude-handoff-registry sync

  )

Quick Start: Minimal Handoff

{
  "handoff": {
    "version": "3.0",
    "schema_type": "universal",
    "timestamp": "2026-02-07T18:30:00Z",
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "source": {
      "skill": "skill-editor",
      "workflow_id": "session-20260207-183000",
      "session_path": "/tmp/skill-editor-session/session-20260207-183000",
      "phase": "Phase 3"
    },
    "target": {
      "skill": "programming-pm"
    },
    "context": {
      "summary": "Implement workflow coordination system",
      "problem_type": "implementation"
    },
    "payload": {
      "working": {
        "description": "Key implementation details here"
      }
    },
    "meta": {
      "token_count": 250,
      "confidence": "high"
    }
  }
}

python3 -c "import uuid; print(uuid.uuid4())"

wc -c < handoff.json | awk '{printf "Estimated tokens: %d\n", $1/4}'

Handoff Lifecycle

Sender (Source Workflow)

1. Determine that work should be handed off to another workflow
2. Discover available target workflows (see Reference Documents below)
3. Present target options to user for selection (or auto-select if only one match)
4. Generate

   trace_id

   (UUID v4) if this is a new trace, or propagate existing
5. Build handoff payload using tiered context structure:

   • payload.working

     (<500 tokens): Immediate context needed by target

   • payload.session

     (<1000 tokens): Session artifacts and state (optional)

   • payload.references

     (<500 tokens): File paths for on-demand loading (optional)
6. Estimate token count via

   characters / 4

   heuristic
7. If over 2000 tokens, apply compression strategies (see validation reference)
8. Validate against schema v3.0 (

   python3 -c "import json, jsonschema; ..."

   )
9. Write handoff file to

   {session_path}/handoffs/{source}-to-{target}-{timestamp}.json

10. Log handoff transmission event to

    trace.jsonl

Receiver (Target Workflow)

1. Read handoff file from provided path
2. Validate

   handoff.version

   is

   "3.0"

   (or handle legacy gracefully)
3. Extract

   trace_id

   and propagate to own session state
4. Read

   context.summary

   and

   context.problem_type

   for initial orientation
5. Load

   payload.working

   into working context
6. Optionally load

   payload.session

   and

   payload.references

   as needed
7. Begin processing at

   target.expected_phase

   (if specified) or entry point

Reference Documents

references/handoff-validation.md

references/distributed-tracing.md

references/handoff-registry.md

references/frontmatter-metadata-standard.md

references/universal-handoff-schema-v3.0.json

Design Decisions

1. Hybrid distributed orchestration (not master orchestrator) -- Each workflow is autonomous; coordinator provides schema and conventions, not control
2. Extend perspective-swarm v2.0 (not start from scratch) -- v2.0 already implements research-recommended patterns (JSON Schema, workflow discovery)
3. 2000-token budget (research-based, configurable) -- Research shows 3-5x cost multiplier for context bloat; fixed budget with tiered structure
4. JSON Schema Draft 2020-12 (OpenAPI 3.1 compatible) -- Industry standard with

   unevaluatedProperties

   for extensibility
5. File-based tracing (not database-backed) -- Lightweight, no infrastructure dependencies, JSON Lines format

6. unevaluatedProperties: false

   for schema extensibility -- Recognizes properties from all subschemas unlike

   additionalProperties

   , enabling v2.0/v3.0 coexistence (Strangler Fig migration)

Examples

• examples/skill-editor-to-programming-pm.json

  -- Full v3.0 handoff with all sections (skill-editor hands off implementation work)

• examples/programming-pm-to-skill-editor.json

  -- Reverse direction (programming-pm requests new skill creation)

references/universal-handoff-schema-v3.0.json