workflow:orchestration

Files (4)

• SKILL.md
• integration-checklist.md · templates/
• owner-prompt.md · templates/
• team-plan.md · templates/

SKILL.md (first lines)

# Orchestration

Use this skill after the constitution has classified a task as Change or Initiative, or when the user asks for team, parallel agents, lanes, delegation, or workflow orchestration.

## Goal

Turn a validated task into an execution topology:

- solo lane for simple, tightly coupled work
- team lanes for independent slices with clear ownership
- state file so the next turn knows the current phase
- integration order and verification evidence

## Gate

Before creating lanes, run both gates.

### Concrete Signal Gate

Implementation work needs at least one concrete signal:

- file path, function, component, API route, schema, or module
- issue, error log, repro step, test command, or fixture
- acceptance criteria, impact scope, or explicit non-goals

If concrete signals are missing:

- do not classify as Patch
- use Change when the goal is clear but details need proposal/tasks
- use Initiative when goal, interface, data model, or impact is unclear

### Team Gate

Check:

- Is the contract stable enough for parallel work?
- Can file ownership be made non-overlapping?
- Are dependencies explicit?
- Is the task large enough that parallelism beats coordination cost?
- Are there at least two independently verifiable lanes?

Do not use team orchestration for:

- Patch hotfixes
- root-cause-unknown debugging
- tasks that require multiple agents to edit the same files
- tasks where public interfaces are still unsettled
- tiny tasks where solo execution is cheaper than coordination

Use team orchestration when:

- an Initiative task has independent frontend/backend/test/docs/migration slices
- tasks can be assigned to disjoint file ownership
- the user explicitly requests team, subagents, parallel agents, or lanes
- a plan already has multiple independent workstreams

## Required Output

Create or update:

- `.agent/current-task.json`
- `.agent/team-plan.md` when team execution is used

## Dispatching Lanes

Use `skills/orchestration/templates/owner-prompt.md` for each lane.

Steps:
1. Fill owner prompt from `team-plan.md` fields
2. Dispatch via Agent tool with `mode: plan` for approval, or `mode: auto` for direct execution
3. Worker updates `.agent/current-task.json` as it progresses

## Integration

Use `skills/orchestration/templates/integration-checklist.md` when all lanes complete.

## Lane Rules

Each lane must define:

- owner
- mission
- scope
- files owned
- files explicitly off-limits
- dependencies
- verification command or check
- integration notes

Prefer fewer lanes with crisp ownership over many small lanes.

## Integration Rules

- Freeze shared contracts before parallel work.
- Integrate dependency lanes before dependent lanes.
- The orchestrator owns final integration.
- Workers must not revert or overwrite unrelated changes.
- If a lane discovers a spec gap, return to OpenSpec instead of silently expanding scope.

## Fix Loop

Integration 发现 inconsistency 后的处理路径：

1. **Integration 报告问题**：只记录，不自行修改 lane 产物——避免掩盖问题
2. **Orchestrator 分类**：issue 分为合约级（需要回 OpenSpec）、lane 级（owner 修复）、体例级（可集成后统一修）
3. **Owner 修复**：lane 级 issue 退回对应 owner，修后重新验证
4. **Re-verify**：修复后重跑 integration checklist，直到通过

| Issue 类型 | 处理方式 | 示例 |
|-----------|---------|------|
| 合约级 | 回退 OpenSpec，更新 design.md | 实体定义冲突 |
| Lane 级 | 退回 owner 修复 | 端点遗漏、角色缺覆盖 |
| 体例级 | 集成时统一修正 | 字段命名不一致 |

Fix loop 上限 3 轮。超过后报告用户决策。

## State Rules

Update `.agent/current-task.json` whenever phase changes:

From cxh0312/workflow-kit, MIT.

More from cxh0312/workflow-kit