cx-exec

cx-exec: automatic execution and task advancement

By default it advances steadily like a reliable lead engineer; with --all , it upgrades to high-autonomy agent teams.

Mandatory rules

All file reads and writes must use absolute paths. Using ../ relative paths to operate on files is prohibited. When working in a worktree, first use git rev-parse --show-toplevel to get the absolute path of the worktree root directory; all Read/Write/Edit operations are based on that absolute path.

Behaviors that violate this rule:

• ❌ Edit("../../../../.worktrees/xxx/开发文档/CX工作流/状态.json", ...)
• ❌ Using relative paths to operate on files outside the worktree

Correct behavior:

• ✅ PROJECT_ROOT=$(git rev-parse --show-toplevel) then Edit("$PROJECT_ROOT/开发文档/CX工作流/功能/{title}/状态.json", ...)

Skipping workspace selection is prohibited. Before execution, first call worktree detection:

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 in_worktree=false and not on main (possibly on a non-feature branch), use AskUserQuestion to list available worktrees for selection.

Behaviors that violate this rule:

• ❌ --all mode directly starts working on the current branch
• ❌ Skipping the prompt and defaulting to inline
• ❌ Not completing workspace selection before spawning subagents

Correct behavior:

• ✅ Read state → AskUserQuestion to ask about workspace → user answers → record choice → only then start execution/spawning agents

Anti-rationalization

Excuse	Reality
"This change is small and doesn't need a worktree"	Small changes also pollute the main context
"Let me try it on main first"	Losing context when switching to a worktree afterward is more painful
"Only one person uses it, no isolation needed"	You may have multiple windows open at the same time
"Creating a worktree is too slow"	git worktree add is a millisecond-level operation
"I'll switch to a worktree later"	You'll forget later, until a conflict happens
"This feature will be done soon"	Merging it back after it's done is also fast

Read first:

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

How to use

/cx:cx-exec
/cx:cx-exec --all
/cx:cx-exec 任务-3

Operating principles

• Project-level 开发文档/CX工作流/配置.json and feature-level 状态.json are the execution truth
• /cx:cx-exec By default advances automatically until completion, blockage, or a key decision point
• /cx:cx-exec --all only then enters high-autonomy team mode
• GitHub does not participate in execution-state control; closed-loop synchronization is left to /cx:cx-summary
• Claude Code is always registered as a runner in the shared core cc; if the feature is currently held by codex , a handoff must be performed first; silent preemption is not allowed
• After the user explicitly confirms "enter execution phase" or "continue execution", the workflow is allowed to automatically connect to this skill

Core steps

Step 0: Read the current feature and task graph

• From 开发文档/CX工作流/配置.json read current_feature and worktree_isolation
• From project-level 开发文档/CX工作流/状态.json find the corresponding Chinese directory
• From 开发文档/CX工作流/功能/{功能标题}/状态.json read tasks / phases / execution_order

Step 0.3: Workspace selection (ask once the first time each feature is executed)

If the current feature is not yet bound to a worktree (状态.json where worktree.binding_status is not bound）， MUST (MUST) use AskUserQuestion tool to ask the user,listing options in plain text is prohibited：

{
  "questions": [
    {
      "question": "功能「{feature_title}」即将开始执行，选择工作区模式？",
      "header": "工作区",
      "multiSelect": false,
      "options": [
        {
          "label": "独立工作区 (Recommended)",
          "description": "在隔离 worktree 中开发，主分支不受影响，完成后合并回来"
        },
        {
          "label": "当前分支直接开始",
          "description": "在当前分支上直接开发，适合小改动或快速修复"
        }
      ]
    }
  ]
}

If worktree_isolation=true, put "independent workspace" first and mark it (Recommended). If worktree_isolation=false, put "start directly on the current branch" first and mark it (Recommended)。

User selects 1 (create an independent workspace):

Use Claude Code's built-in EnterWorktree tool to create an isolated workspace:

EnterWorktree(name: "{feature-slug}")

This will:

• At <repo>/.claude/worktrees/{feature-slug}/ create an independent directory
• Automatically create worktree-{feature-slug} branch
• Switch the current session to the new workspace

After successful creation, record the worktree information in the feature's 状态.json：

{
  "worktree": {
    "preferred_branch": "worktree-{feature-slug}",
    "preferred_worktree_path": ".claude/worktrees/{feature-slug}",
    "binding_status": "bound",
    "isolation_mode": "worktree"
  }
}

User selects 2 (start directly on the current branch):

Record the user's choice, and do not ask again afterward:

{
  "worktree": {
    "preferred_branch": "{当前分支名}",
    "preferred_worktree_path": "{当前目录}",
    "binding_status": "bound",
    "isolation_mode": "inline"
  }
}

If the feature is already bound to a worktree:

• isolation_mode = "worktree" and it is currently not in that worktree: prompt the user to switch or use EnterWorktree to enter
• isolation_mode = "inline": continue directly
• Do not ask again

Step 0.5: Validate worktree binding

Do a final validation before claim to ensure the runner's current checkout matches the feature binding:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-core-worktree.sh \
  --feature {feature-slug} \
  --runner {runner} \
  --session-id {session-id} \
  --branch {branch} \
  --worktree-path {preferred-worktree-path}

• If the script rejects the current checkout, do handoff first or switch to the correct worktree; you cannot claim directly
• The same feature can hold active execution rights in only one worktree, unless a handoff has already occurred
• When the claim helper registers the current session, the runner always uses cc

Step 1: Select an executable task through the shared dispatch helper

Call the shared dispatch helper first, instead of deciding "where to stop" based on your own feeling:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-workflow-exec-dispatch.sh \
  --feature {feature-slug} \
  --runner cc \
  --session-id {session-id} \
  --mode {auto|all}

The dispatch helper will return a unified decision:

• continue: continue the current in_progress or the next ready task
• ask_parallel: detected 2+ ready tasks under the same parallel_group , allowed to ask the user once whether to switch to team mode
• parallel：--all directly advance multiple tasks under
• blocked: enter blocked explanation or key decision
• completed: all complete, enter /cx:summary

If there are no explicit parameters:

• Prefer to continue the current in_progress task
• When there is no in_progress , the dispatch helper selects the next ready task
• After completing one task, rerun the dispatch helper until blocked / completed / key decision point
• It is not allowed to naturally stop at ordinary task boundaries

Step 2: Implement, verify, update status

Every task follows the same closed loop:

1. Read 任务/任务-{n}.md
2. Read 契约.md, confirm the API path and data model referenced by this task
3. Implement code
4. Contract consistency validation (MUST)：
   • Backend task: whether the actual route matches the path in the contract
   • Frontend task: whether the API call path matches the path in the contract
   • Data model: whether field names and types match the contract
   • If they do not match:Update the contract file first, then continue, cannot be silently ignored
5. Run the most relevant verification
6. Update 状态.json
7. Commit code

If execution fails, prioritize self-recovery; when it truly cannot continue, mark the task or feature as blocked。

Step 2.5: Reschedule immediately after completion

After a task is completed and the shared state is updated:

1. Re-run ${CLAUDE_PLUGIN_ROOT}/scripts/cx-workflow-exec-dispatch.sh
2. If it returns continue, directly proceed to the next task
3. If it returns ask_parallel, you may ask the user once whether to switch to --all
4. If it returns parallel, enter team mode
5. If it returns blocked or completed, then stop

Step 3: Structured blocking

All blocking must be recorded in the state, not just described in natural language.

{
  "status": "blocked",
  "blocked": {
    "reason_type": "needs_decision",
    "message": "需要确认接口返回结构"
  }
}

Task-level recording of reason_typeis also allowed, to facilitate /cx:cx-status and hook recovery.

Step 4: Default execution mode

Ordinary /cx:cx-exec means:

• Automatically and continuously advance executable tasks
• Handle ordinary test failures and local conflicts yourself
• Do not make advisory pauses at ordinary task boundaries or wave boundaries
• Pause only at the following 4 types of key decision points:
  • Multiple behavioral paths with clearly different outcomes
  • Will change architecture, API contracts, database structure, or state model
  • High-risk or irreversible operations
  • Requires external information from the user
• If a clear parallelization opportunity is detected, you may ask the user once whether to upgrade to --all; if the user does not explicitly switch, continue serial advancement by default

Step 5: /cx:cx-exec --all

/cx:cx-exec --all does not simply mean "run everything to completion", but rather:

• Enter high-autonomy agent teams mode
• Adaptively split waves according to the task graph
• Spin up as many as possible 3+ 专业代理
• The main agent is only responsible for scheduling, integration, contract validation, and pausing at key decisions

Team roles are not hardcoded; teams are formed temporarily based only on the task graph, for example:

• backend-agent
• frontend-agent
• database-agent
• integration-agent
• review-agent

Commit conventions

By default, each task is committed independently, and a marker is appended at the end of the commit message:

[cx:<feature-slug>] [task:<n>]

Complete example:

feat(memory): add vector query service [cx:vector-memory] [task:4]
fix(liuyao): guard divine fallback path [cx:liuyao-divine] [task:2]

If it is a fix path, use:

fix(scope): description [cx-fix:<fix-slug>]

Completion conditions

When all tasks are completed:

• Switch feature status to completed
• If code_review=true, first suggest doing a closed-loop review
• Finally, enter /cx:cx-summary