cx-plan: 任务规划与契约下沉

把需求或设计真正变成能执行的任务图，而不是再写一层描述文档。

先阅读：

• ${CLAUDE_PLUGIN_ROOT}/core/workflow/README.md
• ${CLAUDE_PLUGIN_ROOT}/core/workflow/protocols/plan.md

强制规则

所有文件读写必须使用绝对路径。 禁止使用 ../ 相对路径。先用 git rev-parse --show-toplevel 获取绝对路径。

Worktree 检测（强制）

执行前检测：

check_output=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-worktree.sh check \
  --feature "{feature-slug}" \
  --project-root "$(git rev-parse --show-toplevel)" 2>&1) || true

如果返回 on_main=true：

• 提示用户先运行 /cx:cx-prd 创建 worktree，或手动进入已有 worktree
• 用 AskUserQuestion 列出可用 worktree 供选择
• 不要继续执行规划阶段

使用方法

/cx:cx-plan {功能名}
/cx:cx-plan

规划原则

• 默认轻量，普通功能直接拆任务
• 仅当 PRD 明显引入新技术时，才进入技术识别和 skill 准备支线
• 任务目录使用中文显示名，状态关联始终用稳定 slug
• Claude Code 侧规划属于 runner cc 的 adapter 行为；共享 core 被 codex 持有时先建议 handoff
• 允许在用户明确确认“进入规划阶段”后，由工作流自动衔接到本 skill

核心步骤

Step 0: 定位 feature 目录

PROJECT_ROOT=$(git rev-parse --show-toplevel)
CX_DOCS_DIR="$PROJECT_ROOT/开发文档/CX工作流"
FEATURE_TITLE="{功能标题}"
FEATURE_SLUG="{feature-slug}"
FEATURE_DIR="$CX_DIR/功能/$FEATURE_TITLE"
TASK_DIR="$FEATURE_DIR/任务"

mkdir -p "$TASK_DIR"

Step 1: 选择规划输入

• 小功能：直接读取 需求.md
• 中大功能：读取 设计.md，必要时参考 需求.md

不再要求手工传 --skip-design 才能走轻量路径。

Step 2: 新技术判断

仅当 PRD 明显引入新技术时，额外执行：

• 技术栈识别
• 现有项目兼容性检查
• 必要 skill 或外部文档准备

普通功能跳过这条支线，直接进入任务拆分。

Step 3: 生成共享契约（跨层任务时 MUST）

当任务图涉及 2 个及以上层级（前端+后端、后端+数据库等）时， 必须（MUST）先生成共享契约文件，再拆任务。

契约文件位置：

开发文档/CX工作流/功能/{功能标题}/契约.md

契约至少包含：

## API 契约

| 接口 | 方法 | 路径 | 请求体 | 响应体 |
|------|------|------|--------|--------|
| 分类树 | GET | /api/case-volume-category/tree | - | CategoryTree[] |
| 案例列表 | GET | /api/historical-case/list | QueryParams | PageResult |

## 数据模型契约

| 字段 | 类型 | 说明 |
|------|------|------|
| id | number | 主键 |

## 状态/枚举契约

| 枚举名 | 值 | 说明 |
|--------|-----|------|

契约来源优先级：

1. 后端已有的路由/Controller → 读代码提取真实路径
2. Design 文档中定义的接口 → 直接引用
3. 都没有 → 在契约文件中新定义，前后端任务共同引用

禁止前后端任务各自猜测 API 路径。

Step 4: 生成任务 DAG

每个任务至少包含：

• number
• title
• phase
• depends_on
• parallel
• 验收标准
• 引用的契约条目（哪些 API、哪些数据模型）

跨层依赖规则：

• 前端任务依赖后端任务时，depends_on 必须显式声明
• 前端任务文档中必须写明引用的 API 路径（来自契约文件），不能自行定义
• 后端任务完成后，如果实际路径与契约不一致，必须先更新契约再继续

Step 5: 写入任务文档

任务文件统一为：

开发文档/CX工作流/功能/{功能标题}/任务/任务-1.md
开发文档/CX工作流/功能/{功能标题}/任务/任务-2.md

任务文档里要同时保留：

• 可见中文标题
• 稳定 slug
• 目标文件范围
• 引用的契约条目（精确到路径和字段）
• 验收标准

Step 5: 更新 feature 级状态

feature 级 状态.json 至少包含：

{
  "feature": "功能标题",
  "slug": "feature-slug",
  "status": "planned",
  "tasks": [
    {
      "number": 1,
      "title": "建立接口骨架",
      "status": "pending"
    }
  ],
  "worktree": {
    "preferred_branch": "codex/vector-memory",
    "preferred_worktree_path": "/worktrees/vector-memory",
    "binding_status": "recommended"
  },
  "docs": {
    "prd": "需求.md",
    "design": "设计.md",
    "summary": "总结.md"
  }
}

Step 6: 输出执行建议

规划完成后默认建议：

下一步：/cx:cx-exec
执行开始时会询问：创建独立工作区 or 当前分支直接开始

如果任务图中存在清晰并行组，再在状态中标注 parallel_group，供 /cx:cx-exec --all 使用。