workflow-coordinator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow Coordinator

工作流协调器

Universal cross-workflow handoff coordination using schema v3.0.

基于schema v3.0的通用跨工作流交接协调方案。

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

协调独立工作流之间的交接（例如skill-editor到programming-pm）
发现可用于交接的目标工作流
在传输前验证交接负载
通过分布式追踪调试多跳交接链
为新技能或现有技能添加交接支持

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)

programming-pm内部的专业人员交接（使用内部v1.2 schema）
Agent之间的简单文件传递（无需schema验证）
单技能调用（无需协调）
单个任务内的Agent团队协作（直接使用Agent团队功能）

Pilot Scope Limitations

试点范围限制

This is v3.0 pilot (documentation + schema artifacts only):

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
```
)

当前为v3.0试点版本（仅包含文档和schema工件）：

Token计数：仅作指导（通过
```
字符数 / 4
```
进行启发式估算，不使用tiktoken）
Schema验证：需要手动调用（
```
python3
```
单行命令）
循环交接检测：仅作建议，未实现自动化
CLI工具：推迟至v1.1版本（如
```
claude-handoff validate
```
等）
适配层：推迟至v1.1版本（跨版本schema转换）
注册表同步工具：推迟至v1.1版本（
```
claude-handoff-registry sync
```
）

Quick Start: Minimal Handoff

快速开始：最简交接示例

The absolute minimum v3.0 handoff (5 required top-level fields):

json

{
  "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"
    }
  }
}

Generate a trace_id:

bash

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

Estimate token count:

bash

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

v3.0版本的最简交接结构（包含5个必填顶级字段）：

json

{
  "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"
    }
  }
}

生成trace_id：

bash

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

估算Token数量：

bash

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

Handoff Lifecycle

交接生命周期

Sender (Source Workflow)

发送方（源工作流）

Determine that work should be handed off to another workflow
Discover available target workflows (see Reference Documents below)
Present target options to user for selection (or auto-select if only one match)
Generate
```
trace_id
```
(UUID v4) if this is a new trace, or propagate existing
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)
Estimate token count via
```
characters / 4
```
heuristic
If over 2000 tokens, apply compression strategies (see validation reference)

Validate against schema v3.0 (

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

)

Write handoff file to

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

Log handoff transmission event to
```
trace.jsonl
```

判断工作需要交接至另一个工作流
发现可用的目标工作流（参见下方参考文档）
向用户展示目标选项供选择（若仅有一个匹配项则自动选择）
若为新追踪链路则生成
```
trace_id
```
（UUID v4），否则传播现有
```
trace_id
```
使用分层上下文结构构建交接负载：
- ```
payload.working
```
  （<500 Token）：目标工作流所需的即时上下文
- ```
payload.session
```
  （<1000 Token）：会话工件和状态（可选）
- ```
payload.references
```
  （<500 Token）：用于按需加载的文件路径（可选）
通过
```
字符数 / 4
```
的启发式方法估算Token数量
若超过2000 Token，应用压缩策略（参见验证参考文档）

依据schema v3.0进行验证（

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

）

将交接文件写入

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

将交接传输事件记录至
```
trace.jsonl
```

Receiver (Target Workflow)

接收方（目标工作流）

Read handoff file from provided path
Validate
```
handoff.version
```
is
```
"3.0"
```
(or handle legacy gracefully)
Extract
```
trace_id
```
and propagate to own session state
Read
```
context.summary
```
and
```
context.problem_type
```
for initial orientation
Load
```
payload.working
```
into working context
Optionally load
```
payload.session
```
and
```
payload.references
```
as needed
Begin processing at
```
target.expected_phase
```
(if specified) or entry point

从指定路径读取交接文件
验证
```
handoff.version
```
为
```
"3.0"
```
（或优雅处理旧版本）
提取
```
trace_id
```
并传播至自身会话状态
读取
```
context.summary
```
和
```
context.problem_type
```
进行初始定位
将
```
payload.working
```
加载至工作上下文
按需加载
```
payload.session
```
和
```
payload.references
```
（可选）
从
```
target.expected_phase
```
（若已指定）或入口点开始处理

Reference Documents

参考文档

Load the relevant reference for your task:

Task	Reference
Creating a handoff payload	`references/handoff-validation.md`
Debugging a handoff chain	`references/distributed-tracing.md`
Finding target workflows	`references/handoff-registry.md`
Adding handoff support to a skill	`references/frontmatter-metadata-standard.md`
Schema definition (JSON Schema)	`references/universal-handoff-schema-v3.0.json`

Load only the reference you need -- progressive disclosure keeps context lean.

根据你的任务加载相关参考文档：

任务	参考文档
创建交接负载	`references/handoff-validation.md`
调试交接链	`references/distributed-tracing.md`
查找目标工作流	`references/handoff-registry.md`
为技能添加交接支持	`references/frontmatter-metadata-standard.md`
Schema定义（JSON Schema）	`references/universal-handoff-schema-v3.0.json`

仅加载你需要的参考文档——渐进式披露可保持上下文简洁。

Design Decisions

设计决策

Key architectural decisions (captured from perspective-swarm analysis and synthesis):

Hybrid distributed orchestration (not master orchestrator) -- Each workflow is autonomous; coordinator provides schema and conventions, not control
Extend perspective-swarm v2.0 (not start from scratch) -- v2.0 already implements research-recommended patterns (JSON Schema, workflow discovery)
2000-token budget (research-based, configurable) -- Research shows 3-5x cost multiplier for context bloat; fixed budget with tiered structure
JSON Schema Draft 2020-12 (OpenAPI 3.1 compatible) -- Industry standard with
```
unevaluatedProperties
```
for extensibility
File-based tracing (not database-backed) -- Lightweight, no infrastructure dependencies, JSON Lines format
unevaluatedProperties: false
for schema extensibility -- Recognizes properties from all subschemas unlike
```
additionalProperties
```
, enabling v2.0/v3.0 coexistence (Strangler Fig migration)

关键架构决策（源自视角集群分析与综合）：

混合分布式编排（无主编排器）——每个工作流都是自主的；协调器仅提供schema和规范，不进行控制
扩展perspective-swarm v2.0（而非从零开始）——v2.0已实现研究推荐的模式（JSON Schema、工作流发现）
2000 Token预算（基于研究，可配置）——研究表明上下文冗余会导致3-5倍的成本乘数；采用固定预算与分层结构
JSON Schema Draft 2020-12（兼容OpenAPI 3.1）——行业标准，支持
```
unevaluatedProperties
```
以实现扩展性
基于文件的追踪（非数据库存储）——轻量级、无基础设施依赖，采用JSON Lines格式
unevaluatedProperties: false
用于Schema扩展性——与
```
additionalProperties
```
不同，它能识别所有子Schema的属性，支持v2.0/v3.0共存（绞杀者模式迁移）

Examples

示例

Two complete example handoff files demonstrate the schema:

```
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)

Both examples validate against

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

两个完整的交接文件示例展示了schema的使用：

```
examples/skill-editor-to-programming-pm.json
```
—— 包含所有章节的完整v3.0交接示例（skill-editor交接实现工作）
```
examples/programming-pm-to-skill-editor.json
```
—— 反向交接示例（programming-pm请求创建新技能）

两个示例均通过

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

的验证。