cx-exec: Task Execution and Contract Validation

5-step streamlined process to implement feature code, automatically verify consistency with API contracts, and trigger summary after all tasks are completed.

Usage

/cx-exec             # 执行下一个待执行任务
/cx-exec #1          # 执行指定任务编号
/cx-exec 1-5         # 批量执行任务 1 到 5
/cx-exec --phase 1   # 执行 Phase 1 的所有任务
/cx-exec --all       # 执行所有待执行任务（并行）

Core Steps

Step 0: Initialize Local Environment

bash

PROJECT_ROOT=$(git rev-parse --show-toplevel)
DEVELOPER_ID=$(jq -r '.developer_id' "$PROJECT_ROOT/.claude/cx/config.json" 2>/dev/null || echo "cx")
CONFIG="$PROJECT_ROOT/.claude/cx/config.json"
FEATURE_DIR="$PROJECT_ROOT/.claude/cx/features/${DEVELOPER_ID}-{feature_slug}"

Step 1: Read Task

bash

# 读取本地状态
STATUS_FILE="$FEATURE_DIR/status.json"
TASK_NUMBER=$(jq -r '.tasks[] | select(.status == "pending") | .number' "$STATUS_FILE" | head -1)

# 读取任务详情
TASK_FILE="$FEATURE_DIR/tasks/task-${TASK_NUMBER}.md"

Dependency Check:

If the task has
```
depends_on
```
field, check if dependent tasks are completed
If dependencies are not completed, prompt user to execute dependent tasks first, no forced execution

Update Task Status: Mark as

in_progress

Step 2: Code Implementation

Implement according to the task description and API contract snippet in the Task file.

Key Principles:

First read the 「📋 API Contract Snippet」 in the Task file
Backend: Controller path, DTO field names, enum values must be consistent with the contract
Frontend: API path, interface field names, enum constants must be consistent with the contract
If blocked (missing dependencies, unclear requirements), stop and inform the user

Tech Stack Auto-Adaptation: Run corresponding tests and checks according to project type

bash

[ -f pyproject.toml ] && uv run pytest
[ -f package.json ] && npm test
[ -f pom.xml ] && mvn test

Step 3: Contract Validation (Core New Feature)

After implementation is completed, automatically verify whether the code is consistent with the API contract in the Task file.

Validation Content:

1. 接口路径一致性
   比对：Controller @RequestMapping vs Task 中的契约路径
   不一致 → 自动修正

2. DTO/VO 字段一致性
   比对：DTO 类字段 vs Task 中的字段映射表
   不一致 → 自动修正

3. 状态枚举一致性
   比对：枚举类/常量 vs Task 中的状态枚举对照表
   不一致 → 自动修正

4. 请求/响应结构一致性
   比对：Controller 方法签名 vs Task 中的 Request/Response JSON
   不一致 → 自动修正

Validation Result Processing:

✅ All Passed:

契约校验通过
  接口路径: 3/3 一致
  字段映射: 12/12 一致
  状态枚举: 4/4 一致
  → 继续提交

⚠️ Inconsistencies Found (Auto-Fixed):

契约校验发现不一致，自动修正中...

  ❌ 接口路径: POST /api/v1/certifications → 实际为 /certification
    → 已修正 @PostMapping 路径

  ❌ 字段名: rejectReason → 实际为 rejectMsg
    → 已修正 DTO 字段名和前端 interface

  ❌ 状态枚举: REJECTED → 实际为 REJECT
    → 已修正前端枚举常量

修正完成，重新运行测试...

❌ Still Issues After Fix (Stop Submission):

契约校验失败，无法自动修正

  问题: {具体问题}
  建议: {修复建议}

需要人工介入

Step 4: Commit Code

bash

git add {相关文件}
git commit -m "{type}({scope}): {description} (task #{task_number})"

Commit message follows the existing project style (or conventional commits).

Step 5: Update Progress & Unlock Dependent Tasks

bash

# 更新任务状态为 completed
jq ".tasks[] |= if .number == $TASK_NUMBER then .status = \"completed\" else . end" "$STATUS_FILE" > "$STATUS_FILE.tmp"
mv "$STATUS_FILE.tmp" "$STATUS_FILE"

# 解锁依赖该任务的 pending 任务
for dependent in $(jq -r ".tasks[] | select(.depends_on[]? == $TASK_NUMBER) | .number" "$STATUS_FILE"); do
  jq ".tasks[] |= if .number == $dependent then .status = \"pending\" else . end" "$STATUS_FILE" > "$STATUS_FILE.tmp"
  mv "$STATUS_FILE.tmp" "$STATUS_FILE"
done

Step 6: Epic Closure Detection

Check if all tasks are completed:

bash

TOTAL=$(jq '.tasks | length' "$STATUS_FILE")
COMPLETED=$(jq '[.tasks[] | select(.status == "completed")] | length' "$STATUS_FILE")

if [ "$COMPLETED" -eq "$TOTAL" ]; then
  # === 所有任务完成，触发闭环 ===
  echo "所有任务已完成，启动汇总..."

  # 自动触发 cx-summary
  # 如果 config.code_review = true，先启动代码审查流程
fi

Batch Execution Mode

Parameter Parsing

bash

case "$ARGUMENTS" in
  *-*)
    # 范围: 1-5
    RANGE=$(echo "$ARGUMENTS" | tr '-' ' ')
    TARGETS=$(jq -r ".execution_order[] | select(. >= $START and . <= $END)" "$STATUS_FILE")
    ;;
  --phase*)
    # Phase: --phase 1
    PHASE=$(echo "$ARGUMENTS" | grep -oE '[0-9]+')
    TARGETS=$(jq -r ".phases[] | select(.number == $PHASE) | .tasks[]" "$STATUS_FILE")
    ;;
  --all)
    # 所有 pending 任务
    TARGETS=$(jq -r '.tasks[] | select(.status == "pending") | .number' "$STATUS_FILE")
    ;;
esac

Parallel Execution

Judge parallelism according to

parallel_group

field:

Tasks in the same
parallel_group
can be executed in parallel, tasks in different groups are executed serially.

bash

# 并行组 p1-a (task 1, 2 可并行)
Task agent: task-1.md → Step 1-5
Task agent: task-2.md → Step 1-5
            ↓ 全部完成后
# 并行组 p2-a (task 3, 4 可并行)
Task agent: task-3.md → Step 1-5
Task agent: task-4.md → Step 1-5
            ↓ 全部完成后
# 并行组 p3-a (task 5 串行)
Task agent: task-5.md → Step 1-5

Subagent Invocation

Each task starts an independent subagent through the Task tool:

Task tool 参数:
  subagent_type: "task-executor"
  prompt: |
    项目根目录: $PROJECT_ROOT
    任务: $FEATURE_DIR/tasks/task-{n}.md

    请按 5 步流程完成:
    1. 读取 task-{n}.md 中的任务描述和 API 契约片段
    2. 按契约实现代码（路径、字段、枚举一致）
    3. 运行项目测试和检查
    4. 执行契约校验（对比实现 vs task-{n}.md 中的契约）
    5. 校验通过后 git add + commit

    commit message 格式: {type}({scope}): {desc} (task #{n})

Parallel: Initiate multiple Task tool calls in one message Serial: Start the next task after the previous one is completed

Error Handling

Implementation Failure

任务执行遇到问题

错误: {具体错误}
已完成: {部分进度}

已恢复任务为 pending 状态，需要人工介入

Task status is reset to

pending

for subsequent retries.

Contract Validation Failed (Cannot Auto-Fix)

契约校验失败

不一致项:
{具体问题}

建议: 检查 Task 中的契约定义是否需要调整
或检查 Design Doc 中的相应章节

Dependency Not Met

任务 #103 依赖未满足

依赖: #101 (状态: pending)

建议: 先执行 /cx-exec #101

Progress Tracking

status.json is updated in real time in Step 5, recording:

Status of each task (pending / in_progress / completed)
Overall progress of Phase
Next executable task

Integration with cx-plan

Input: status.json (task list) + task-{n}.md (task details)
Output: Updated status.json + git commits
cx-exec reads
```
execution_order
```
in status.json to determine execution order

Integration with cx-summary

When all tasks are completed, cx-summary is triggered automatically
cx-summary reads the complete status.json and git log to generate summary documents
Optional code review initiation (if config.code_review = true)

SubagentStop Hook

During batch execution, SubagentStop hook is triggered for validation after each subagent completes:

Does the code conform to the contract?
Did the tests pass?
If there are problems, mark the task as failed, no automatic retry

Context Persistence

SessionStart hook automatically loads the status.json of the current feature, output:

当前进度:
  功能: cx-payment
  Phase 1: 2/2 completed
  Phase 2: 1/3 in_progress (Task #103)
  下一个: Task #104

Allows users to quickly resume interrupted work.

cx-exec

NPX Install

Tags

SKILL.md Content (Chinese)

cx-exec: Task Execution and Contract Validation

Usage

Core Steps

Step 0: Initialize Local Environment

Step 1: Read Task

Step 2: Code Implementation

Step 3: Contract Validation (Core New Feature)

Step 4: Commit Code

Step 5: Update Progress & Unlock Dependent Tasks

Step 6: Epic Closure Detection

Batch Execution Mode

Parameter Parsing

Parallel Execution

Subagent Invocation

Error Handling

Implementation Failure

Contract Validation Failed (Cannot Auto-Fix)

Dependency Not Met

Progress Tracking

Integration with cx-plan

Integration with cx-summary

SubagentStop Hook

Context Persistence