Claude-Code-Workflow/.codex/skills/team-lifecycle-v4/MIGRATION-PLAN.md

Team Lifecycle v4 — Codex 迁移计划

目标

将 Claude Code 版 .claude/skills/team-lifecycle-v4 迁移到 Codex 版 .codex/skills/team-lifecycle-v4，采用 通用 worker + role 文档注入 模式（与 Claude Code 设计对齐），去掉 spawn_agents_on_csv，用 spawn_agent + wait_agent + send_input + close_agent 实现同构编排。

设计原则

1. 通用 agent，role 文档区分角色 — 只定义 2 个 TOML（worker + supervisor），角色差异由 roles/<role>/role.md 决定
2. role 文档直接复用 — .claude/skills/ 中的 roles/specs/templates 原样迁移
3. items 结构化传参 — 取代 message 字符串，分段传递角色分配、任务描述、上游上下文
4. JSON 取代 CSV — tasks.json 管理状态，discoveries/{id}.json 分文件写入
5. 两版同构 — Codex 调用原语与 Claude Code 形成 1:1 映射

平台调用映射

编排概念	Claude Code	Codex
Worker spawn	Agent({ subagent_type: "team-worker", prompt })	spawn_agent({ agent_type: "tlv4_worker", items })
Supervisor spawn	Agent({ subagent_type: "team-supervisor", prompt })	spawn_agent({ agent_type: "tlv4_supervisor", items })
Supervisor wake	SendMessage({ recipient: "supervisor", content })	send_input({ id: supervisorId, items })
Supervisor shutdown	SendMessage({ type: "shutdown_request" })	close_agent({ id: supervisorId })
等待完成	后台回调 -> monitor.md	wait_agent({ ids, timeout_ms })
任务状态	TaskCreate / TaskUpdate	tasks.json 文件读写
团队管理	TeamCreate / TeamDelete	session folder init / cleanup
消息总线	mcp__ccw-tools__team_msg	discoveries/{id}.json + session-state.json
用户交互	AskUserQuestion	request_user_input
角色加载	prompt 中 @roles/<role>/role.md	items text 中指示 Read roles/<role>/role.md

目录结构 (迁移后)

.codex/
├── agents/
│   ├── tlv4-worker.toml                 # 通用 worker (NEW)
│   └── tlv4-supervisor.toml             # 驻留 supervisor (NEW)
└── skills/
    └── team-lifecycle-v4/
        ├── SKILL.md                     # 主编排 (REWRITE)
        ├── MIGRATION-PLAN.md            # 本文档
        ├── roles/                       # 从 .claude/ 复制
        │   ├── coordinator/
        │   │   ├── role.md
        │   │   └── commands/
        │   │       ├── analyze.md
        │   │       ├── dispatch.md
        │   │       └── monitor.md
        │   ├── analyst/role.md
        │   ├── writer/role.md
        │   ├── planner/role.md
        │   ├── executor/
        │   │   ├── role.md
        │   │   └── commands/
        │   │       ├── implement.md
        │   │       └── fix.md
        │   ├── tester/role.md
        │   ├── reviewer/
        │   │   ├── role.md
        │   │   └── commands/
        │   │       ├── review-code.md
        │   │       └── review-spec.md
        │   └── supervisor/role.md
        ├── specs/                       # 从 .claude/ 复制
        │   ├── pipelines.md
        │   ├── quality-gates.md
        │   └── knowledge-transfer.md
        ├── templates/                   # 从 .claude/ 复制
        │   ├── product-brief.md
        │   ├── requirements.md
        │   ├── architecture.md
        │   └── epics.md
        └── schemas/
            └── tasks-schema.md          # REWRITE: CSV -> JSON

---

步骤 1: Agent TOML 定义

.codex/agents/tlv4-worker.toml

name = "tlv4_worker"
description = "Generic team-lifecycle-v4 worker. Role-specific behavior loaded from role.md at spawn time."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

developer_instructions = """
You are a team-lifecycle-v4 worker agent.

## Boot Protocol
1. Read role_spec file path from your task assignment (MUST read first)
2. Read session state from session path
3. Execute role-specific Phase 2-4 defined in role.md
4. Write deliverables to session artifacts directory
5. Write findings to discoveries/{task_id}.json
6. Report via report_agent_job_result

## Output Schema
{
  "id": "<task_id>",
  "status": "completed | failed",
  "findings": "<max 500 chars>",
  "quality_score": "<0-100, reviewer only>",
  "supervision_verdict": "",
  "error": ""
}
"""

.codex/agents/tlv4-supervisor.toml

name = "tlv4_supervisor"
description = "Resident supervisor for team-lifecycle-v4. Woken via send_input for checkpoint verification."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
You are a team-lifecycle-v4 supervisor agent (resident pattern).

## Boot Protocol
1. Read role_spec file path from your task assignment (MUST read first)
2. Load baseline context from session
3. Report ready, wait for checkpoint requests via send_input

## Per Checkpoint
1. Read artifacts specified in checkpoint request
2. Verify cross-artifact consistency per role.md definitions
3. Issue verdict: pass (>= 0.8), warn (0.5-0.79), block (< 0.5)
4. Write report to artifacts/CHECKPOINT-{id}-report.md
5. Report findings

## Constraints
- Read-only: never modify artifacts
- Never issue pass when critical inconsistencies exist
- Never block for minor style issues
"""

---

步骤 2: SKILL.md 改写

核心变更

区域	现状	改写后
allowed-tools	spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, ...	spawn_agent, wait_agent, send_input, close_agent, report_agent_job_result, Read, Write, Edit, Bash, Glob, Grep, request_user_input
执行模型	hybrid: CSV wave (primary) + spawn_agent (secondary)	统一: spawn_agent + wait_agent (all tasks)
状态管理	tasks.csv (CSV)	tasks.json (JSON)
发现板	discoveries.ndjson (共享追加)	discoveries/{task_id}.json (分文件)
exec_mode 分类	csv-wave / interactive	移除 — 所有任务统一用 spawn_agent
wave CSV 构建	生成 wave-{N}.csv, spawn_agents_on_csv	循环 spawn_agent + 批量 wait_agent

Worker Spawn Template

// 对齐 Claude Code 的 Agent({ subagent_type: "team-worker", prompt }) 模式
spawn_agent({
  agent_type: "tlv4_worker",
  items: [
    // 段 1: 角色分配 (对齐 Claude Code prompt 的 Role Assignment 块)
    { type: "text", text: `## Role Assignment
role: ${task.role}
role_spec: ${skillRoot}/roles/${task.role}/role.md
session: ${sessionFolder}
session_id: ${sessionId}
requirement: ${requirement}
inner_loop: ${hasInnerLoop(task.role)}` },

    // 段 2: 读取指示 (核心 — 保持 role 文档引用模式)
    { type: "text", text: `Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` },

    // 段 3: 任务上下文
    { type: "text", text: `## Task Context
task_id: ${task.id}
title: ${task.title}
description: ${task.description}
pipeline_phase: ${task.pipeline_phase}` },

    // 段 4: 上游发现
    { type: "text", text: `## Upstream Context\n${task.prev_context}` }
  ]
})

Supervisor Spawn Template

// Spawn — 一次 (Phase 2 init, 对齐 Claude Code Agent({ subagent_type: "team-supervisor" }))
const supervisorId = spawn_agent({
  agent_type: "tlv4_supervisor",
  items: [
    { type: "text", text: `## Role Assignment
role: supervisor
role_spec: ${skillRoot}/roles/supervisor/role.md
session: ${sessionFolder}
session_id: ${sessionId}
requirement: ${requirement}

Read role_spec file (${skillRoot}/roles/supervisor/role.md) to load checkpoint definitions.
Init: load baseline context, report ready, go idle.
Wake cycle: orchestrator sends checkpoint requests via send_input.` }
  ]
})

Supervisor Wake Template

// 对齐 Claude Code SendMessage({ recipient: "supervisor", content })
send_input({
  id: supervisorId,
  items: [
    { type: "text", text: `## Checkpoint Request
task_id: ${task.id}
scope: [${task.deps}]
pipeline_progress: ${done}/${total} tasks completed` }
  ]
})
wait_agent({ ids: [supervisorId], timeout_ms: 300000 })

Supervisor Shutdown

// 对齐 Claude Code SendMessage({ type: "shutdown_request" })
close_agent({ id: supervisorId })

Wave 执行引擎

for (let wave = 1; wave <= maxWave; wave++) {
  const state = JSON.parse(Read(`${sessionFolder}/tasks.json`))
  const waveTasks = Object.values(state.tasks).filter(t => t.wave === wave && t.status === 'pending')

  // 跳过依赖失败的任务
  const executableTasks = []
  for (const task of waveTasks) {
    if (task.deps.some(d => ['failed', 'skipped'].includes(state.tasks[d]?.status))) {
      state.tasks[task.id].status = 'skipped'
      state.tasks[task.id].error = 'Dependency failed or skipped'
      continue
    }
    executableTasks.push(task)
  }

  // 构建 prev_context
  for (const task of executableTasks) {
    const contextParts = task.context_from
      .map(id => {
        const prev = state.tasks[id]
        if (prev?.status === 'completed' && prev.findings) {
          return `[Task ${id}: ${prev.title}] ${prev.findings}`
        }
        try {
          const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${id}.json`))
          return `[Task ${id}] ${disc.findings || JSON.stringify(disc.key_findings || '')}`
        } catch { return null }
      })
      .filter(Boolean)
    task.prev_context = contextParts.join('\n') || 'No previous context available'
  }

  // 分离普通任务和 CHECKPOINT 任务
  const regularTasks = executableTasks.filter(t => !t.id.startsWith('CHECKPOINT-'))
  const checkpointTasks = executableTasks.filter(t => t.id.startsWith('CHECKPOINT-'))

  // 1) 并发 spawn 普通任务
  const agentMap = [] // [{ agentId, taskId }]
  for (const task of regularTasks) {
    state.tasks[task.id].status = 'in_progress'
    const agentId = spawn_agent({
      agent_type: "tlv4_worker",
      items: [
        { type: "text", text: `## Role Assignment
role: ${task.role}
role_spec: ${skillRoot}/roles/${task.role}/role.md
session: ${sessionFolder}
session_id: ${sessionId}
requirement: ${requirement}
inner_loop: ${hasInnerLoop(task.role)}` },
        { type: "text", text: `Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` },
        { type: "text", text: `## Task Context
task_id: ${task.id}
title: ${task.title}
description: ${task.description}
pipeline_phase: ${task.pipeline_phase}` },
        { type: "text", text: `## Upstream Context\n${task.prev_context}` }
      ]
    })
    agentMap.push({ agentId, taskId: task.id })
  }

  // 2) 批量等待
  if (agentMap.length > 0) {
    wait_agent({ ids: agentMap.map(a => a.agentId), timeout_ms: 900000 })
  }

  // 3) 收集结果，合并到 tasks.json
  for (const { agentId, taskId } of agentMap) {
    try {
      const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`))
      state.tasks[taskId].status = disc.status || 'completed'
      state.tasks[taskId].findings = disc.findings || ''
      state.tasks[taskId].quality_score = disc.quality_score || null
      state.tasks[taskId].error = disc.error || null
    } catch {
      state.tasks[taskId].status = 'failed'
      state.tasks[taskId].error = 'No discovery file produced'
    }
    close_agent({ id: agentId })
  }

  // 4) 执行 CHECKPOINT 任务 (send_input 唤醒 supervisor)
  for (const task of checkpointTasks) {
    send_input({
      id: supervisorId,
      items: [
        { type: "text", text: `## Checkpoint Request
task_id: ${task.id}
scope: [${task.deps.join(', ')}]
pipeline_progress: ${completedCount}/${totalCount} tasks completed` }
      ]
    })
    wait_agent({ ids: [supervisorId], timeout_ms: 300000 })

    // 读取 checkpoint 报告
    try {
      const report = Read(`${sessionFolder}/artifacts/${task.id}-report.md`)
      const verdict = parseVerdict(report) // pass | warn | block
      state.tasks[task.id].status = 'completed'
      state.tasks[task.id].findings = `Verdict: ${verdict.decision} (score: ${verdict.score})`
      state.tasks[task.id].supervision_verdict = verdict.decision

      if (verdict.decision === 'block') {
        const action = request_user_input({
          questions: [{
            question: `Checkpoint ${task.id} BLOCKED (score: ${verdict.score}). Choose action.`,
            header: "Blocked",
            id: "blocked_action",
            options: [
              { label: "Override", description: "Proceed despite block" },
              { label: "Revise upstream", description: "Go back and fix issues" },
              { label: "Abort", description: "Stop pipeline" }
            ]
          }]
        })
        // Handle user choice...
      }
    } catch {
      state.tasks[task.id].status = 'failed'
      state.tasks[task.id].error = 'Supervisor report not produced'
    }
  }

  // 5) 持久化 tasks.json
  Write(`${sessionFolder}/tasks.json`, JSON.stringify(state, null, 2))
}

---

步骤 3: 复制 Role 文档

从 .claude/skills/team-lifecycle-v4/ 复制以下目录到 .codex/skills/team-lifecycle-v4/：

源	目标	说明
roles/ (全部)	roles/	原样复制，coordinator 中平台相关调用需适配
specs/pipelines.md	specs/pipelines.md	原样复制
specs/quality-gates.md	specs/quality-gates.md	原样复制
specs/knowledge-transfer.md	specs/knowledge-transfer.md	需适配: team_msg -> discoveries/ 文件
templates/ (全部)	templates/	原样复制

Role 文档适配点

roles/coordinator/role.md — 需改写：

• Phase 2: TeamCreate -> session folder init
• Phase 3: TaskCreate -> tasks.json 写入
• Phase 4: Agent(team-worker) -> spawn_agent(tlv4_worker)
• monitor.md 中 callback 处理 -> wait_agent 结果处理

roles/coordinator/commands/monitor.md — 需改写：

• handleCallback -> wait_agent 结果解析
• handleSpawnNext -> spawn_agent 循环
• SendMessage(supervisor) -> send_input(supervisorId)

specs/knowledge-transfer.md — 需适配：

• team_msg(operation="get_state") -> 读 tasks.json
• team_msg(type="state_update") -> 写 discoveries/{id}.json
• 探索缓存协议保持不变

其余 role 文档 (analyst, writer, planner, executor, tester, reviewer, supervisor):

• 核心执行逻辑不变
• ccw cli 调用保持不变 (CLI 工具两侧通用)
• 发现产出改为写 discoveries/{task_id}.json (替代 team_msg)
• report_agent_job_result 替代 team_msg state_update

---

步骤 4: Tasks Schema 改写

现状: tasks.csv

id,title,description,role,pipeline_phase,deps,context_from,exec_mode,wave,status,findings,quality_score,supervision_verdict,error

改写后: tasks.json

{
  "session_id": "tlv4-auth-system-20260324",
  "pipeline": "full-lifecycle",
  "requirement": "Design and implement user authentication system",
  "created_at": "2026-03-24T10:00:00+08:00",
  "supervision": true,
  "completed_waves": [],
  "active_agents": {},
  "tasks": {
    "RESEARCH-001": {
      "title": "Domain research",
      "description": "Explore domain, extract structured context...",
      "role": "analyst",
      "pipeline_phase": "research",
      "deps": [],
      "context_from": [],
      "wave": 1,
      "status": "pending",
      "findings": null,
      "quality_score": null,
      "supervision_verdict": null,
      "error": null
    },
    "DRAFT-001": {
      "title": "Product brief",
      "description": "Generate product brief from research context...",
      "role": "writer",
      "pipeline_phase": "product-brief",
      "deps": ["RESEARCH-001"],
      "context_from": ["RESEARCH-001"],
      "wave": 2,
      "status": "pending",
      "findings": null,
      "quality_score": null,
      "supervision_verdict": null,
      "error": null
    }
  }
}

发现文件: discoveries/{task_id}.json

{
  "task_id": "RESEARCH-001",
  "worker": "RESEARCH-001",
  "timestamp": "2026-03-24T10:15:00+08:00",
  "type": "research",
  "status": "completed",
  "findings": "Explored domain: identified OAuth2+RBAC pattern, 5 integration points.",
  "quality_score": null,
  "supervision_verdict": null,
  "error": null,
  "data": {
    "dimension": "domain",
    "findings": ["Auth system needs OAuth2 + RBAC"],
    "constraints": ["Must support SSO"],
    "integration_points": ["User service API"]
  },
  "artifacts_produced": ["spec/discovery-context.json"]
}

---

步骤 5: 删除旧文件

迁移完成后，删除 Codex 版中不再需要的文件：

文件	原因
agents/agent-instruction.md	角色逻辑在 roles/ 中，通用协议在 TOML developer_instructions 中
agents/requirement-clarifier.md	需求澄清逻辑合并到 coordinator/role.md Phase 1
agents/supervisor.md	迁移到 roles/supervisor/role.md
agents/quality-gate.md	迁移到 roles/reviewer/role.md (QUALITY-* 任务处理)
schemas/tasks-schema.md (旧版)	被 JSON schema 版本替代

---

实施顺序

步骤	内容	依赖	复杂度
1	创建 2 个 TOML agent 定义	无	低
2	复制 roles/specs/templates 从 .claude/	无	低 (纯复制)
3	改写 tasks-schema.md (CSV -> JSON)	无	低
4	改写 SKILL.md 主编排	1, 2, 3	高 (核心工作)
5	适配 coordinator role.md + commands/	4	中
6	适配 knowledge-transfer.md	3	低
7	适配 worker role 文档 (发现产出方式)	3	低
8	删除旧文件，清理	全部	低

步骤 1-3 可并行，步骤 4 是关键路径，步骤 5-7 依赖步骤 4 但可并行。