cx-plan

cx-plan: Task planning and contract downflow

Truly turn requirements or design into an executable task graph, rather than writing another layer of description documents.

Read first:

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

Mandatory rules

All file reads and writes must use absolute paths. Do not use ../ relative paths. First use git rev-parse --show-toplevel to get the absolute path.

Worktree detection (mandatory)

Check before execution:

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

If it returns on_main=true：

• Prompt the user to first run /cx:cx-prd to create a worktree, or manually enter an existing worktree
• Use AskUserQuestion to list available worktrees for selection
• Do not continue with the planning phase

How to use

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

Planning principles

• Lightweight by default; for ordinary features, split tasks directly
• Only when the PRD clearly introduces new technology, enter the technical identification and skill preparation branch
• Task directories use Chinese display names; status associations always use a stable slug
• Planning on the Claude Code side is part of the runner cc adapter behavior; when the shared core is held by codex , suggest handoff first
• After the user explicitly confirms "enter the planning phase", the workflow is allowed to automatically connect to this skill

Core steps

Step 0: Locate the feature directory

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: Choose planning input

• Small feature: read directly 需求.md
• Medium/large feature: read 设计.md, and if necessary refer to 需求.md

No longer require manually passing --skip-design to take the lightweight path.

Step 2: New technology assessment

Only when the PRD clearly introduces new technology, additionally perform:

• Tech stack identification
• Existing project compatibility check
• Prepare necessary skills or external documentation

Ordinary features skip this branch and go directly to task splitting.

Step 3: Generate shared contracts (MUST for cross-layer tasks)

When the task graph involves 2 or more layers (frontend + backend, backend + database, etc.), you must (MUST) first generate a shared contract file, then split tasks.

Contract file location:

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

The contract must at least contain:

## API 契约

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

## 数据模型契约

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

## 状态/枚举契约

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

Contract source priority:

1. Existing backend routes/Controllers → read the code to extract the real paths
2. Interfaces defined in the Design document → reference directly
3. Neither exists → define them anew in the contract file, and have frontend and backend tasks reference them jointly

Frontend and backend tasks are forbidden from each guessing API paths.

Step 4: Generate the task DAG

Each task must contain at least:

• number
• title
• phase
• depends_on
• parallel
• Acceptance criteria
• Referenced contract entries(which APIs, which data models)

Cross-layer dependency rules:

• When a frontend task depends on a backend task,depends_on must be explicitly declared
• The frontend task document must clearly state the referenced API paths (from the contract file) and must not define them on its own
• After the backend task is completed, if the actual path is inconsistent with the contract, the contract must be updated first before continuing

Step 5: Write the task document

Task files are unified as:

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

The task document must retain both:

• Visible Chinese title
• Stable slug
• Target file scope
• Referenced contract entries (precise to path and field)
• Acceptance criteria

Step 5: Update feature-level status

Feature-level 状态.json at least includes:

{
  "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: Output execution recommendations

Default recommendations after planning is complete:

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

If there are clear parallel groups in the task graph, then annotate in the status parallel_group, for /cx:cx-exec --all to use.