team-planex

Team PlanEx

统一团队技能：面向 Issue 开发的规划与执行流水线。基于 team-worker Agent 架构——协调器负责编排，工作器是 team-worker Agent，会从 roles/<role>/role.md 加载特定角色的说明。

架构

Skill(skill="team-planex", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze -> dispatch -> spawn workers -> STOP
                                    |
                    +---------------+---------------+
                    v                               v
               [planner]                       [executor]
         (team-worker agent,            (team-worker agent,
          loads roles/planner/role.md)   loads roles/executor/role.md)

角色注册表

角色	路径	前缀	内部循环
coordinator	roles/coordinator/role.md	—	—
planner	roles/planner/role.md	PLAN-*	true
executor	roles/executor/role.md	EXEC-*	true

角色路由器

解析 $ARGUMENTS：

• 包含 --role <name> → 读取 roles/<name>/role.md，执行 Phase 2-4
• 不包含 --role → @roles/coordinator/role.md，执行入口路由器

共享常量

• 会话前缀：PEX
• 会话路径：.workflow/.team/PEX-<slug>-<date>/
• CLI 工具：ccw cli --mode analysis（只读）、ccw cli --mode write（修改）
• 消息总线：mcp__ccw-tools__team_msg(session_id=<session-id>, ...)

工作器启动模板

协调器使用此模板启动工作器：

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: "planex",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: planex
requirement: <task-description>
inner_loop: <true|false>
execution_method: <codex|gemini>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<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).`
})

用户命令

命令	操作
check / status	查看执行状态图
resume / continue	推进到下一步
add <issue-ids or --text '...' or --plan path>	向规划器队列追加新任务

会话目录

.workflow/.team/PEX-<slug>-<YYYY-MM-DD>/
├── .msg/
│   ├── messages.jsonl          # Message bus log
│   └── meta.json               # Session state
├── task-analysis.json          # Coordinator analyze output
├── artifacts/
│   └── solutions/              # Planner solution output per issue
│       ├── <issueId-1>.json
│       └── <issueId-N>.json
└── wisdom/                     # Cross-task knowledge
    ├── learnings.md
    ├── decisions.md
    ├── conventions.md
    └── issues.md

规范参考

• specs/pipelines.md — 流水线定义、任务元数据注册表、执行方法选择

错误处理

场景	解决方案
未知命令	显示错误及可用命令列表
未找到角色	显示错误及角色注册表
未找到角色规范文件	显示错误及预期路径（roles//role.md）
team-worker Agent 不可用	错误：需要 .claude/agents/team-worker.md
规划器 Issue 规划失败	重试一次，然后跳过并处理下一个 Issue
执行器实现失败	向协调器报告，然后继续处理下一个 EXEC-* 任务
流水线停滞	协调器进行监控，并向用户升级报告
工作器无响应	报告等待中的任务，并建议用户执行 resume