mcpField
T
team-lifecycle

team-lifecycle

github.com/catlog22开发2.1k40 次安装19 周前更新
代码仓库

关于 team-lifecycle

Team Lifecycle Orchestrator 是覆盖需求澄清、规格编写、实现和测试的多 Agent 工作流技能，面向需要团队式交付的开发任务。它通过共享探索缓存、并行任务和按讨论严重程度分流来协调流水线。

主要功能

  1. 01五阶段生命周期编排
  2. 02共享代码探索缓存
  3. 03线性任务快速衔接与并行
  4. 04讨论结论严重程度分流
  5. 05中断会话恢复与任务重试

适用场景

  1. 01从需求澄清推进到实现与测试
  2. 02并行执行实现后的测试和评审
  3. 03恢复中断会话并重新调度任务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/catlog22/claude-code-workflow --skill team-lifecycle

安装后在 Claude Code 中输入/team-lifecycle确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
analyst.md
architect.md
discuss-agent.md
executor.md
explore-agent.md
fe-developer.md
fe-qa.md
planner.md
reviewer.md
tester.md
writer.md
phases/
01-requirement-clarification.md
02-team-initialization.md
03-task-chain-creation.md
04-pipeline-coordination.md
05-completion-report.md
specs/
document-standards.md
quality-gates.md
templates/
architecture-doc.md
epics-template.md
product-brief.md
requirements-prd.md

详细介绍

团队生命周期编排器

为规范、实施和测试工作流提供完整生命周期的团队编排。编排器通过五个阶段驱动多 Agent 流水线：需求澄清、会话初始化、任务链创建、流水线协调（启动/等待/关闭循环）以及完成情况报告。

关键设计原则：

  • 内联讨论子 Agent：负责产出的角色（分析师、撰写者、审查者）会在内部调用讨论子 Agent，而不是启动专门的讨论 Agent。这将规范流水线的轮次从 12 次减半至 6 次。
  • 共享探索缓存：所有 Agent 共用一个集中式 explorations/ 目录，其中包含 cache-index.json，从而避免重复探索代码库。
  • 快速推进式启动：Agent 完成后，编排器会立即在线性链中启动下一个 Agent，无需等待完整的协调周期。
  • 按共识严重程度路由：讨论结论会按 HIGH/MEDIUM/LOW 严重程度分级，并触发编排器各不相同的行为（修订、警告后继续或直接通过）。
  • 节拍模型：每个流水线步骤都是一个节拍——启动 Agent、等待结果、处理输出、启动下一个 Agent。编排器每个周期处理一个节拍，然后让出控制权。

架构

+-------------------------------------------------------------+
|  Team Lifecycle Orchestrator                                  |
|  Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5         |
|  Require    Init       Dispatch   Coordinate   Report         |
+----------+------------------------------------------------+--+
           |
     +-----+------+----------+-----------+-----------+
     v            v          v           v           v
+---------+ +---------+ +---------+ +---------+ +---------+
| Phase 1 | | Phase 2 | | Phase 3 | | Phase 4 | | Phase 5 |
| Require | | Init    | | Dispatch| | Coord   | | Report  |
+---------+ +---------+ +---------+ +---------+ +---------+
     |            |          |          |||          |
  params       session     tasks     agents      summary
                                    /  |  \
                              spawn  wait  close
                              /        |        \
                       +------+   +-------+   +--------+
                       |agent1|   |agent2 |   |agent N |
                       +------+   +-------+   +--------+
                          |           |            |
                     (may call discuss/explore subagents internally)

第 4 阶段节拍周期（单个节拍）：

  event (phase advance / user resume)
      |
      v
  [Orchestrator]
      +-- read state file
      +-- find ready tasks (pending + all blockers completed)
      +-- spawn agent(s) for ready task(s)
      +-- wait(agent_ids, timeout)
      +-- process results (consensus routing, artifacts)
      +-- update state file
      +-- close completed agents
      +-- fast-advance: immediately spawn next if linear successor
      +-- yield (wait for next event or user command)

Agent 注册表

Agent角色文件职责模式
analyst~/.codex/agents/analyst.md种子分析、上下文收集、DISCUSS-0012.8 内联子 Agent
writer~/.codex/agents/writer.md文档生成、DISCUSS-002 至 DISCUSS-0052.8 内联子 Agent
planner~/.codex/agents/planner.md多角度探索、计划生成2.9 缓存探索
executor~/.codex/agents/executor.md代码实施2.1 标准
tester~/.codex/agents/tester.md测试修复周期2.3 深度交互
reviewer~/.codex/agents/reviewer.md代码审查 + 规范质量、DISCUSS-0062.8 内联子 Agent
architect~/.codex/agents/architect.md架构咨询（按需）2.1 标准
fe-developer~/.codex/agents/fe-developer.md前端实施2.1 标准
fe-qa~/.codex/agents/fe-qa.md前端 QA、GC 循环2.3 深度交互

使用前必须将所有 Agent 角色文件部署到 ~/.codex/agents/。 模式 2.8 = Agent 在内部启动讨论子 Agent，进行多视角评审。 模式 2.9 = Agent 在开始工作前使用共享探索缓存。 模式 2.3 = 编排器可使用 send_input 进行迭代式纠错循环。

子 Agent 注册表

子 AgentAgent 文件可由哪些 Agent 调用用途
discuss~/.codex/agents/discuss-agent.mdanalyst、writer、reviewer通过 CLI 工具进行多视角评审
explore~/.codex/agents/explore-agent.mdanalyst、planner、任何 Agent使用共享缓存探索代码库

子 Agent 由各 Agent 自行启动（而不是由编排器启动）。Agent 会读取子 Agent 规范，通过 spawn_agent 内联启动它，等待结果，然后将其关闭。编排器从不直接管理子 Agent 的生命周期。

快速推进生成 Agent

wait() 返回已完成的 Agent 结果后，编排器会检查下一个流水线步骤是否为简单的线性后继步骤（恰好有一个任务就绪、没有并行窗口、没有检查点）。

决策表：

条件操作
1 个任务就绪、属于简单线性后继步骤、无检查点立即为下一个任务调用 spawn_agent（快速推进）
多个任务就绪（并行窗口）批量生成所有就绪任务，然后对所有任务调用 wait
没有任务就绪，但仍有其他 Agent 在运行暂停推进，等待这些 Agent 完成
没有任务就绪，且没有任务在运行流水线完成，进入阶段 5
检查点任务已完成（例如 QUALITY-001）暂停，输出检查点消息，并等待用户

快速推进失败恢复： 当编排器检测到快速推进的 Agent 失败时（wait 返回错误或超时且没有结果）：

  1. 在状态文件中记录失败
  2. 在状态中将该任务重新标记为“待处理”
  3. 为同一任务生成一个新的 Agent
  4. 如果同一任务失败 3 次或以上，则暂停流水线并向用户报告

共识严重程度路由

当产出 Agent（分析员、写作者、审查员）报告讨论结果时，编排器会从 Agent 输出中解析判定结果。

Agent 的输出格式（写入其产物，也包含在 wait() 结果中）：

DISCUSS_RESULT:
- verdict: <consensus_reached | consensus_blocked>
- severity: <HIGH | MEDIUM | LOW>
- average_rating: <N>/5
- divergences: <summary>
- action_items: <list>
- recommendation: <revise | proceed-with-caution | escalate>
- discussion_path: <path-to-discussion-record>

路由表：

判定结果严重程度编排器操作
consensus_reached-正常继续，快速推进至下一个任务
consensus_blockedLOW附带备注视为已达成，正常继续
consensus_blockedMEDIUM将警告记录到 wisdom/issues.md，在下一个任务的上下文中加入分歧，然后继续
consensus_blockedHIGH创建修订任务（见下文）或暂停并等待用户
consensus_blockedHIGH (DISCUSS-006)始终暂停并等待用户决策（最终签核关卡）

创建修订任务（严重程度为 HIGH，且不是 DISCUSS-006）：

// Add revision entry to state file
const revisionTask = {
  id: "<original-task-id>-R1",
  owner: "<same-agent-role>",
  blocked_by: [],
  description: "Revision of <original-task-id>: address consensus-blocked divergences.\n"
    + "Session: <session-dir>\n"
    + "Original artifact: <artifact-path>\n"
    + "Divergences: <divergence-details>\n"
    + "Action items: <action-items-from-discuss>\n"
    + "InlineDiscuss: <same-round-id>",
  status: "pending",
  is_revision: true
}

// Max 1 revision per task. If already revised once, pause for user.
if (stateHasRevision(originalTaskId)) {
  // Pause pipeline, ask user
} else {
  // Insert revision task into state, spawn agent
}

阶段执行

阶段文件概要
阶段 1phases/01-requirement-clarification.md解析用户输入、检测模式、自动检测前端、收集参数
阶段 2phases/02-team-initialization.md创建会话目录、初始化状态文件、智慧库和探索缓存
阶段 3phases/03-task-chain-creation.md根据模式构建流水线任务链，并写入状态文件
阶段 4phases/04-pipeline-coordination.md主要的生成／等待／关闭循环、快速推进、共识路由、检查点
阶段 5phases/05-completion-report.md总结结果、列出产物、提供后续步骤
阶段 0：会话恢复检查（阶段 1 之前）

进入阶段 1 之前，编排器会检查是否存在中断的会话：

  1. 扫描 .workflow/.team/TLS-*/team-session.json，查找 status: "active" 或 status: "paused" 的文件
  2. 未找到会话 -> 进入阶段 1
  3. 找到一个会话 -> 恢复该会话（见下文“会话协调”）
  4. 找到多个会话 -> 请用户选择

会话协调（恢复时）：

  1. 读取状态文件 -> 获取流水线状态
  2. 对状态文件中的每个任务：
    • 如果状态为“进行中”，但没有 Agent 正在运行 -> 重置为“待处理”（已中断）
    • 如果状态为“已完成” -> 验证产物是否存在
  3. 根据协调后的状态重新构建任务就绪情况
  4. 使用协调后的状态进入阶段 4（生成就绪任务）

流水线定义

仅规格说明（6 个节拍）
RESEARCH-001(+D1) -> DRAFT-001(+D2) -> DRAFT-002(+D3) -> DRAFT-003(+D4) -> DRAFT-004(+D5) -> QUALITY-001(+D6)

每个任务都包含内联讨论。(+DN) = 由 Agent 在内部执行的第 N 轮内联讨论。

仅实现（3 个节拍，含并行窗口）
PLAN-001 -> IMPL-001 -> TEST-001 || REVIEW-001

IMPL-001 完成后，TEST-001 和 REVIEW-001 会并行运行。

完整生命周期（9 个节拍）
[Spec pipeline: RESEARCH-001 -> DRAFT-001 -> ... -> QUALITY-001]
    |
    CHECKPOINT: pause for user confirmation
    |
PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 || REVIEW-001
仅前端（3 个节拍）
PLAN-001 -> DEV-FE-001 -> QA-FE-001

GC 循环：如果 QA-FE 的判定为 NEEDS_FIX，则动态创建 DEV-FE-002 -> QA-FE-002（最多 2 轮）。

全栈（4 个节拍，包含双并行）
PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001

REVIEW-001 同时受 TEST-001 和 QA-FE-001 阻塞。

全生命周期前端（12 个任务）
[Spec pipeline] -> PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001

PLAN-001 的 blockedBy 为 QUALITY-001。适用从规格到实现的检查点。

任务元数据注册表

任务 IDAgent阶段依赖项描述内联讨论
RESEARCH-001analystspec（无）初始分析和上下文收集DISCUSS-001
DRAFT-001writerspecRESEARCH-001生成产品简介DISCUSS-002
DRAFT-002writerspecDRAFT-001生成需求/PRDDISCUSS-003
DRAFT-003writerspecDRAFT-002生成架构文档DISCUSS-004
DRAFT-004writerspecDRAFT-003生成 Epic 和 StoryDISCUSS-005
QUALITY-001reviewerspecDRAFT-004规格质量五维评审及签核DISCUSS-006
PLAN-001plannerimpl（无或 QUALITY-001）多角度探索和规划-
IMPL-001executorimplPLAN-001代码实现-
TEST-001testerimplIMPL-001测试-修复循环-
REVIEW-001reviewerimplIMPL-001代码四维评审-
DEV-FE-001fe-developerimplPLAN-001前端实现-
QA-FE-001fe-qaimplDEV-FE-001前端五维 QA-

节奏控制

节拍模型

事件驱动型流水线。每个节拍 = 编排器处理一个事件 -> 启动 Agent -> 等待 -> 处理结果 -> 让出控制权。

Beat Cycle (single beat)
======================================================================
  Event                 Orchestrator                  Agents
----------------------------------------------------------------------
  advance/resume --> +- read state file ------+
                     |  find ready tasks       |
                     |  spawn agent(s) --------+--> [Agent A] executes
                     |  wait(ids, timeout) ----+--> [Agent B] executes
                     +- process results -------+         |
                     |  update state file      |         |
                     |  close agents           |         |
                     +- yield -----------------+         |
                                                         |
  next beat <--- result from wait() <-------------------+
======================================================================

  Fast-Advance (skips full yield for linear successors)
======================================================================
  [Agent A] completes via wait()
    +- 1 ready task? simple linear successor?
    |   YES -> spawn Agent B immediately, enter wait() again
    |   NO  -> yield, wait for user/event
======================================================================
流水线节拍视图
Spec-only (6 beats, was 12 in v3)
-------------------------------------------------------
Beat  1         2         3         4         5         6
      |         |         |         |         |         |
    R1+D1 --> W1+D2 --> W2+D3 --> W3+D4 --> W4+D5 --> Q1+D6
    ^                                                     ^
  pipeline                                            sign-off
   start                                               pause

R=RESEARCH  W=DRAFT(writer)  Q=QUALITY  D=DISCUSS(inline)

Impl-only (3 beats, with parallel window)
-------------------------------------------------------
Beat  1         2              3
      |         |         +----+----+
      PLAN --> IMPL --> TEST || REVIEW    <-- parallel window
                         +----+----+
                           pipeline
                            done

Full-lifecycle (9 beats)
-------------------------------------------------------
Beat 1-6: [Spec pipeline as above]
                                    |
Beat 6 (Q1+D6 done):      CHECKPOINT -- user confirms then resume
                                    |
Beat 7      8           9
 PLAN --> IMPL --> TEST || REVIEW

Fullstack (with dual parallel windows)
-------------------------------------------------------
Beat  1              2                    3                4
      |         +----+----+         +----+----+           |
      PLAN --> IMPL || DEV-FE --> TEST || QA-FE -->  REVIEW
              ^                ^                   ^
         parallel 1       parallel 2          sync barrier
检查点
触发条件位置行为
从规格到实现的转换QUALITY-001 完成暂停，输出“SPEC PHASE COMPLETE”，等待用户
达到 GC 循环上限QA-FE 最多 2 轮停止迭代，报告当前 QA 状态
流水线停滞无就绪任务 + 无运行中任务检查是否缺少任务，并向用户报告
DISCUSS-006 严重性为 HIGH最终签核始终暂停，等待用户决定
停滞检测
检查项条件解决方法
Agent 无响应活跃 Agent 的 wait() 超时关闭 Agent，将任务重置为待处理，然后重新启动
流水线死锁无就绪任务 + 无运行中任务 + 存在待处理任务检查 blocked_by 链，并向用户报告阻塞情况
超出 GC 循环限制DEV-FE / QA-FE 迭代超过 2 轮终止循环，输出最新 QA 报告
快速推进时出现孤立任务状态中任务为“in_progress”，但 Agent 已关闭重置为待处理，然后重新启动

Agent 启动模板

编排器为流水线任务启动 Agent 时，会使用此模板：

const agentId = spawn_agent({
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/<agent-role>.md (MUST read first)
2. Read session state: <session-dir>/team-session.json
3. Read wisdom files: <session-dir>/wisdom/*.md (if exists)

---

## Session
Session directory: <session-dir>
Task ID: <task-id>
Pipeline mode: <mode>

## Scope
<scope-description>

## Task
<task-description>

## InlineDiscuss
<discuss-round-id or "none">

## Dependencies
Completed predecessors: <list of completed task IDs and their artifact paths>

## Constraints
- Only process <PREFIX>-* tasks
- All output prefixed with [<agent-role>] tag
- Write artifacts to <session-dir>/<artifact-subdir>/
- Before each major output, read wisdom files for cross-task knowledge
- After task completion, write discoveries to <session-dir>/wisdom/
- If InlineDiscuss is set, call discuss subagent after primary artifact creation

## Completion Protocol
When work is complete, output EXACTLY:

TASK_COMPLETE:
- task_id: <task-id>
- status: <success | failed>
- artifact: <path-to-primary-artifact>
- discuss_verdict: <consensus_reached | consensus_blocked | none>
- discuss_severity: <HIGH | MEDIUM | LOW | none>
- summary: <one-line summary>
`
})

会话目录

.workflow/.team/TLS-<slug>-<date>/
+-- team-session.json           # Pipeline state (replaces TaskCreate/TaskList)
+-- spec/                       # Spec artifacts
|   +-- spec-config.json
|   +-- discovery-context.json
|   +-- product-brief.md
|   +-- requirements/
|   +-- architecture/
|   +-- epics/
|   +-- readiness-report.md
|   +-- spec-summary.md
+-- discussions/                # Discussion records (written by discuss subagent)
+-- plan/                       # Plan artifacts
|   +-- plan.json
|   +-- tasks/                  # Detailed task specs
+-- explorations/               # Shared explore cache
|   +-- cache-index.json        # { angle -> file_path }
|   +-- explore-<angle>.json
+-- architecture/               # Architect assessments + design-tokens.json
+-- analysis/                   # Analyst design-intelligence.json (UI mode)
+-- qa/                         # QA audit reports
+-- wisdom/                     # Cross-task knowledge accumulation
|   +-- learnings.md            # Patterns and insights
|   +-- decisions.md            # Architecture and design decisions
|   +-- conventions.md          # Codebase conventions
|   +-- issues.md               # Known risks and issues
+-- .msg/                       # Message bus (UI integration)
|   +-- meta.json               # Pipeline metadata (stages, roles, team_name)
|   +-- messages.jsonl          # NDJSON event log
+-- shared-memory.json          # Cross-agent state

状态文件架构（team-session.json）

此状态文件取代 Claude 的 TaskCreate/TaskList/TaskGet/TaskUpdate 系统。该文件仅由编排器管理。

{
  "session_id": "TLS-<slug>-<date>",
  "mode": "<spec-only | impl-only | full-lifecycle | fe-only | fullstack | full-lifecycle-fe>",
  "scope": "<project description>",
  "status": "<active | paused | completed>",
  "started_at": "<ISO8601>",
  "updated_at": "<ISO8601>",
  "tasks_total": 0,
  "tasks_completed": 0,
  "pipeline": [
    {
      "id": "RESEARCH-001",
      "owner": "analyst",
      "status": "pending | in_progress | completed | failed",
      "blocked_by": [],
      "description": "...",
      "inline_discuss": "DISCUSS-001",
      "agent_id": null,
      "artifact_path": null,
      "discuss_verdict": null,
      "discuss_severity": null,
      "started_at": null,
      "completed_at": null,
      "revision_of": null,
      "revision_count": 0
    }
  ],
  "active_agents": [],
  "completed_tasks": [],
  "revision_chains": {},
  "wisdom_entries": [],
  "checkpoints_hit": [],
  "gc_loop_count": 0
}

消息总线（.msg/）

.msg/ 目录为前端 UI 提供流水线元数据。它使用的格式与 Claude 版本的 team_msg 工具（type: "state_update"）相同。

meta.json

供 API 读取并用于前端显示的流水线元数据：

{
  "status": "active",
  "pipeline_mode": "<mode>",
  "pipeline_stages": ["role1", "role2", "..."],
  "roles": ["coordinator", "role1", "role2", "..."],
  "team_name": "lifecycle",
  "role_state": {
    "<role>": {
      "status": "completed",
      "task_id": "TASK-ID",
      "_updated_at": "<ISO8601>"
    }
  },
  "updated_at": "<ISO8601>"
}

按模式划分的 pipeline_stages：

模式pipeline_stages
仅规格["analyst", "writer", "reviewer"]
仅实现["planner", "executor", "tester", "reviewer"]
仅前端["planner", "fe-developer", "fe-qa"]
全栈["planner", "executor", "fe-developer", "tester", "fe-qa", "reviewer"]
全生命周期["analyst", "writer", "planner", "executor", "tester", "reviewer"]
全生命周期前端["analyst", "writer", "planner", "executor", "fe-developer", "tester", "fe-qa", "reviewer"]
messages.jsonl

NDJSON 事件日志（每行一个 JSON 对象）：

{"id":"MSG-001","ts":"<ISO8601>","from":"coordinator","to":"coordinator","type":"state_update","summary":"Session initialized","data":{...}}
{"id":"MSG-002","ts":"<ISO8601>","from":"analyst","to":"coordinator","type":"impl_complete","summary":"RESEARCH-001 completed","data":{...}}

消息类型：state_update、impl_complete、impl_progress、test_result、review_result、error、shutdown

会话恢复

当编排器检测到现有的活动/暂停会话时：

  1. 从会话目录读取 team-session.json
  2. 对于状态为 "in_progress" 的每项任务：
    • 没有匹配的活动 Agent -> 任务已中断 -> 重置为 "pending"
    • 有匹配的活动 Agent -> 确认 Agent 仍在运行（尝试以 0 超时进行 wait）
  3. 协调：确保状态中包含该模式的所有预期任务
  4. 创建缺失的任务，并设置正确的 blocked_by 依赖项
  5. 验证依赖链完整性（无循环、无悬空引用）
  6. 使用协调后的状态更新状态文件
  7. 继续进入阶段 4，启动已就绪的任务

用户命令

在流水线执行期间，用户可以发出以下命令：

命令操作
check / status输出执行状态图（只读，不推进流程）
resume / continue检查 Agent 状态，推进流水线
新会话请求阶段 0 检测到请求后，进入正常的阶段 1-5 流程

状态图输出格式：

[orchestrator] Pipeline Status
[orchestrator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)

[orchestrator] Execution Graph:
  Spec Phase: (if applicable)
    [V RESEARCH-001(+D1)] -> [V DRAFT-001(+D2)] -> [>>> DRAFT-002(+D3)]
    -> [o DRAFT-003(+D4)] -> [o DRAFT-004(+D5)] -> [o QUALITY-001(+D6)]
  Impl Phase: (if applicable)
    [o PLAN-001]
      +- BE: [o IMPL-001] -> [o TEST-001] -> [o REVIEW-001]
      +- FE: [o DEV-FE-001] -> [o QA-FE-001]

  V=completed  >>>=running  o=pending  .=not created

[orchestrator] Active Agents:
  > <task-id> (<agent-role>) - running <elapsed>

[orchestrator] Ready to spawn: <task-ids>
[orchestrator] Commands: 'resume' to advance | 'check' to refresh

生命周期管理

超时协议
阶段超时超时时的处理
阶段 1（需求）无（交互式）不适用
阶段 2（初始化）60s失败并报错
阶段 3（分派）60s失败并报错
阶段 4（每个 Agent）15 min（规格 Agent）、30 min（实现 Agent）通过 send_input 发送收敛请求，再等待 2 min，然后关闭
阶段 5（报告）60s输出部分报告

收敛请求（超时时通过 send_input 发送）：

send_input({
  id: <agent-id>,
  message: `
## TIMEOUT NOTIFICATION

Execution timeout reached. Please:
1. Save all current progress to artifact files
2. Output TASK_COMPLETE with status: partial
3. Include summary of completed vs remaining work
`
})
清理协议

流水线完成（或中止）时：

// Close all active agents
for (const agentEntry of state.active_agents) {
  try {
    close_agent({ id: agentEntry.agent_id })
  } catch (e) {
    // Agent already closed, ignore
  }
}

// Update state file
state.status = "completed"  // or "aborted"
state.updated_at = new Date().toISOString()
// Write state file

错误处理

场景检测方式解决方法
Agent 超时wait() 返回 timed_out发送收敛请求 send_input，再等待 2 min，然后关闭并重置任务
Agent 崩溃/意外关闭wait() 返回错误状态将任务重置为 pending，重新启动 Agent（最多重试 3 次）
同一任务失败 3 次或以上状态文件中的重试次数暂停流水线，向用户报告
快速推进导致孤立任务任务处于 in_progress，但没有活动 Agent，且已超过 5 min重置为 pending，重新启动
共识因 HIGH 受阻从 Agent 输出中解析 DISCUSS_RESULT创建修订任务（最多 1 次）或暂停
DISCUSS-006 的共识因 HIGH 受阻同上，但这是最终签核轮次始终暂停并等待用户处理
修订仍受阻修订任务返回 blocked HIGH暂停流水线，升级给用户处理
会话文件损坏JSON 解析错误尝试从上一个已知正常的状态恢复，否则报告错误
流水线停滞没有就绪任务，也没有运行中任务，但存在待处理任务检查 blocked_by，报告阻塞详情
Agent 输出格式未知wait 结果中未找到 TASK_COMPLETE记录警告，尝试提取状态，并标记为部分完成
状态中存在重复任务分派期间任务 ID 已存在跳过创建，记录警告
依赖缺失blocked_by 引用了不存在的任务记录错误，停止流水线

前端自动检测

在阶段 1 期间，编排器会检测是否需要前端工作：

信号检测方式流水线升级
描述中包含 FE 关键词匹配：component、page、UI、React、Vue、CSS、HTML、Tailwind、Svelte、Next.js、Nuxt、shadcn、design systemimpl-only -> fe-only 或 fullstack
也包含 BE 关键词匹配：API、database、server、endpoint、backend、middlewareimpl-only -> fullstack
项目中使用 FE 框架检测 package.json 中的 react/vue/svelte/nextfull-lifecycle -> full-lifecycle-fe

Inline Discuss 协议（供 Agent 使用）

Produce Agent（分析师、撰写者、审查者）完成主要产物后，会调用 discuss 子 Agent。本协议供参考；每个 Agent 的角色文件中都包含具体调用方式。

讨论轮次映射：

Agent任务后讨论轮次视角
analystRESEARCH-001DISCUSS-001产品、风险、覆盖范围
writerDRAFT-001DISCUSS-002产品、技术、质量、覆盖范围
writerDRAFT-002DISCUSS-003质量、产品、覆盖范围
writerDRAFT-003DISCUSS-004技术、风险
writerDRAFT-004DISCUSS-005产品、技术、质量、覆盖范围
reviewerQUALITY-001DISCUSS-006全部 5 项（产品、技术、质量、风险、覆盖范围）

Agent 侧 discuss 调用（在 Agent 内部调用，而非由编排器调用）：

// Agent spawns discuss subagent internally
const discussId = spawn_agent({
  message: `
## MANDATORY FIRST STEPS (Agent Execute)
1. **Read agent definition**: ~/.codex/agents/discuss-agent.md (MUST read first)

---

## Multi-Perspective Critique: <round-id>

### Input
- Artifact: <artifact-path>
- Round: <round-id>
- Perspectives: <perspective-list>
- Session: <session-dir>
- Discovery Context: <session-dir>/spec/discovery-context.json

### Execution
Per-perspective CLI analysis -> divergence detection -> consensus determination -> write record.

### Output
Write discussion record to: <session-dir>/discussions/<round-id>-discussion.md
Return verdict summary with: verdict, severity, average_rating, action_items, recommendation.
`
})

const discussResult = wait({ ids: [discussId], timeout_ms: 300000 })
close_agent({ id: discussId })
// Agent includes discuss result in its TASK_COMPLETE output

共享 Explore 协议（供 Agent 使用）

任何需要代码库上下文的 Agent 都会调用 explore 子 Agent。结果会缓存到 explorations/ 中。

Agent 侧 explore 调用（在 Agent 内部调用，而非由编排器调用）：

// Agent spawns explore subagent internally
const exploreId = spawn_agent({
  message: `
## MANDATORY FIRST STEPS (Agent Execute)
1. **Read agent definition**: ~/.codex/agents/explore-agent.md (MUST read first)

---

## Explore Codebase

Query: <query>
Focus angle: <angle>
Keywords: <keyword-list>
Session folder: <session-dir>

## Cache Check
1. Read <session-dir>/explorations/cache-index.json (if exists)
2. If matching angle found AND file exists -> return cached result
3. If not found -> proceed to exploration

## Output
Write JSON to: <session-dir>/explorations/explore-<angle>.json
Update cache-index.json with new entry.
Return summary: file count, pattern count, top 5 files, output path.
`
})

const exploreResult = wait({ ids: [exploreId], timeout_ms: 300000 })
close_agent({ id: exploreId })

缓存查找规则：

条件操作
cache-index.json 中存在完全匹配的角度返回缓存结果
无匹配项执行探索并缓存结果
缓存文件缺失，但索引中有条目移除过期条目，重新探索

智识积累

跨任务的知识积累。编排器会在会话初始化时创建 wisdom/。

目录：

<session-dir>/wisdom/
+-- learnings.md      # Patterns and insights discovered
+-- decisions.md      # Architecture and design decisions made
+-- conventions.md    # Codebase conventions identified
+-- issues.md         # Known risks and issues flagged

Agent 职责：

  • 开始时：读取所有 wisdom 文件，以获取跨任务上下文
  • 工作期间：将发现追加到相应的 wisdom 文件
  • 完成时：在 TASK_COMPLETE 摘要中包含重要发现

角色隔离规则

允许禁止
Agent 仅处理自身前缀的任务处理其他 Agent 的任务
Agent 通过 TASK_COMPLETE 输出传达结果Agent 之间直接通信
Agent 在内部调用 discuss/explore 子 AgentAgent 修改编排器状态文件
Agent 将产物写入指定目录Agent 向其他 Agent 的目录写入内容
Agent 读取 wisdom 文件和 shared-memory.jsonAgent 删除或覆盖其他 Agent 的产物

编排器还禁止：直接编写/修改代码、调用实现工具、执行分析/测试/审查工作。

GC 循环（前端 QA）

对于 FE 流水线，QA-FE 可以触发修复-重测循环：

Round 1: DEV-FE-001 -> QA-FE-001
  QA-FE verdict: NEEDS_FIX?
    YES -> Round 2: DEV-FE-002(blocked_by: QA-FE-001) -> QA-FE-002(blocked_by: DEV-FE-002)
    QA-FE-002 verdict: NEEDS_FIX?
      YES -> max rounds reached (2), stop loop, report current state
      NO  -> proceed to next pipeline step
    NO -> proceed to next pipeline step

需要进行 GC 循环迭代时，编排器会动态向状态文件添加 DEV-FE-NNN 和 QA-FE-NNN 任务。

模式到流水线快速参考

模式任务总数首个任务检查点
spec-only6RESEARCH-001无（QUALITY-001 为最终任务）
impl-only4PLAN-001无
fe-only3（+GC）PLAN-001无
fullstack6PLAN-001无
full-lifecycle10RESEARCH-001QUALITY-001 之后
full-lifecycle-fe12（+GC）RESEARCH-001QUALITY-001 之后

共享规范资源

资源路径（相对于 skill）用途
文档标准specs/document-standards.mdYAML frontmatter、命名、结构
质量门槛specs/quality-gates.md各阶段的质量门槛
产品简介模板templates/product-brief.mdDRAFT-001
需求模板templates/requirements-prd.mdDRAFT-002
架构模板templates/architecture-doc.mdDRAFT-003
Epic 模板templates/epics-template.mdDRAFT-004

协调者角色约束（主 Agent）

重要：负责执行此技能的协调者（主 Agent）仅负责编排，而非实现。

  1. 协调者不得执行代码：主 Agent 不得直接编写、修改或实现任何代码。所有实现工作都必须委派给已启动的团队 Agent。协调者仅负责：

    • 启动 Agent 并分配任务
    • 等待 Agent 回调
    • 合并结果并协调工作流
    • 管理各阶段之间的工作流转换

  2. 必须耐心等待：Agent 执行需要较长时间（每个阶段通常为 10-30 分钟，有时更久）。协调者必须：

    • 耐心等待 wait() 调用完成
    • 不得因感觉延迟而跳过工作流步骤
    • 不得仅因 Agent 耗时较长就认定其失败
    • 信任技能中定义的超时机制

  3. 使用 send_input 请求澄清：当 Agent 需要指导或似乎陷入停滞时，协调者必须：

    • 使用 send_input() 提问或提供说明
    • 不得跳过该 Agent 或过早进入下一阶段
    • 在升级处理前给 Agent 机会作出回应
    • 示例：send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })

  4. 不得走捷径：协调者不得：

    • 跳过工作流中定义的阶段或步骤
    • 绕过必需的审批或审查步骤
    • 在前置条件完成前执行依赖任务
    • 未收到 Agent 的明确回调就假定任务已完成
    • 捏造或虚构 Agent 的结果

  5. 尊重长时间运行的进程：这是一个复杂的多 Agent 工作流，需要耐心：

    • 总执行时间可能为 30-90 分钟或更久
    • 每个阶段可能因复杂程度而耗时 10-30 分钟
    • 协调者必须在整个过程中保持活跃并专注
    • 不得因时间顾虑而终止或跳过步骤

评论

支持 Markdown