dex-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Converting Markdown Documents to Tasks

将Markdown文档转换为任务

Command Invocation

命令调用

Use

dex

directly for all commands:

bash

dex <command>

dex

is not on PATH, use

npx @zeeg/dex <command>

instead. Check once at the start:

bash

command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"

Use

/dex-plan

to convert any markdown planning document into a trackable dex task.

直接使用

dex

执行所有命令：

bash

dex <command>

如果

dex

不在PATH中，改用

npx @zeeg/dex <command>

。开始前先检查：

bash

command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"

使用

/dex-plan

将任意Markdown规划文档转换为可跟踪的dex任务。

When to Use

使用场景

After completing a plan in plan mode
Converting specification documents to trackable tasks
Converting design documents to implementation tasks
Creating tasks from roadmap or milestone documents
Tracking any markdown planning or design content

在计划模式下完成计划后
将规格说明文档转换为可跟踪任务
将设计文档转换为实现任务
从路线图或里程碑文档创建任务
跟踪任意Markdown规划或设计内容

Supported Documents

支持的文档类型

Any markdown file containing planning or design content:

Plan files from plan mode (
```
~/.claude/plans/*.md
```
)
Specification documents (
```
SPEC.md
```
,
```
REQUIREMENTS.md
```
)
Design documents (
```
DESIGN.md
```
,
```
ARCHITECTURE.md
```
)
Roadmaps and milestone documents (
```
ROADMAP.md
```
)
Feature proposals and technical RFCs

任何包含规划或设计内容的Markdown文件：

计划模式生成的计划文件（
```
~/.claude/plans/*.md
```
）
规格说明文档（
```
SPEC.md
```
、
```
REQUIREMENTS.md
```
）
设计文档（
```
DESIGN.md
```
、
```
ARCHITECTURE.md
```
）
路线图和里程碑文档（
```
ROADMAP.md
```
）
功能提案和技术RFC

Usage

使用方法

bash

/dex-plan <markdown-file-path>

bash

/dex-plan <markdown-file-path>

Examples

示例

From plan mode:

bash

/dex-plan /home/user/.claude/plans/moonlit-brewing-lynx.md

From specification document:

bash

/dex-plan @SPEC.md

From design document:

bash

/dex-plan docs/AUTHENTICATION_DESIGN.md

From roadmap:

bash

/dex-plan ROADMAP.md

来自计划模式：

bash

/dex-plan /home/user/.claude/plans/moonlit-brewing-lynx.md

来自规格说明文档：

bash

/dex-plan @SPEC.md

来自设计文档：

bash

/dex-plan docs/AUTHENTICATION_DESIGN.md

来自路线图：

bash

/dex-plan ROADMAP.md

What It Does

功能说明

Reads the markdown file
Extracts title from first
```
#
```
heading (or uses filename as fallback)
Strips "Plan: " prefix if present (case-insensitive)
Creates dex task with full markdown content as context
Analyzes plan structure for potential subtask breakdown
Automatically creates subtasks when appropriate
Returns task ID and breakdown summary

读取Markdown文件
从第一个
```
#
```
标题提取任务名称（若不存在则使用文件名作为备选）
移除开头的"Plan: "前缀（不区分大小写）
创建包含完整Markdown内容作为上下文的dex任务
分析计划结构以确定是否需要拆分子任务
在合适的情况下自动创建子任务
返回任务ID和拆分摘要

Examples

示例

From plan mode file:

markdown

undefined

来自计划模式文件：

markdown

undefined

Plan: Add JWT Authentication

Summary

...


→ Task description: "Add JWT Authentication" (note: "Plan: " prefix stripped)

**From specification document:**

```markdown

...


→ 任务描述："Add JWT Authentication"（注意："Plan: "前缀已移除）

**来自规格说明文档：**

```markdown

User Authentication Specification

Requirements

...


→ Task description: "User Authentication Specification"

...


→ 任务描述："User Authentication Specification"

Automatic Subtask Breakdown

自动子任务拆分

After creating the main task, the skill analyzes the plan structure to determine if breaking it into subtasks adds value.

创建主任务后，该工具会分析计划结构，判断拆分子任务是否有价值。

Hierarchy Levels

层级结构

The skill supports up to 3 levels (maximum depth enforced by dex):

Level	Name	Example
L0	Epic	"Add user authentication system"
L1	Task	"Implement JWT middleware"
L2	Subtask	"Add token verification function"

工具支持最多3级（dex强制的最大深度）：

层级	名称	示例
L0	史诗任务	"Add user authentication system"
L1	任务	"Implement JWT middleware"
L2	子任务	"Add token verification function"

When Breakdown Happens

拆分触发条件

The skill creates subtasks when the plan has:

3-7 clearly separable work items (numbered steps, distinct sections, implementation phases)
Implementation across multiple files or components (different modules, layers, or areas)
Clear sequential dependencies (step 1 before step 2)
Independent items that benefit from separate tracking

Epic-level breakdown (creates tasks, not subtasks) when:

Plan has major phases/sections with their own sub-items
5+ distinct areas of work
Plan spans multiple systems or components
Work will require multiple sessions

当计划满足以下条件时，工具会创建子任务：

包含3-7个可明确分离的工作项（编号步骤、不同章节、实现阶段）
需要在多个文件或组件中实现（不同模块、层级或领域）
存在清晰的顺序依赖关系（步骤1需在步骤2之前完成）
独立工作项可从单独跟踪中获益

史诗级拆分（创建任务而非子任务）的触发条件：

计划包含带有子项的主要阶段/章节
有5个以上不同的工作领域
计划涉及多个系统或组件
工作需要多个会话才能完成

When Breakdown Does NOT Happen

不拆分的情况

The skill keeps a single task when:

Plan describes one cohesive task (even if detailed with multiple paragraphs)
Only 1-2 steps present (not enough to warrant breakdown)
Work items are tightly coupled (can't be separated meaningfully)
Plan is exploratory or investigative (research, analysis, discovery)
Breaking down would create artificial boundaries that don't reflect natural work units

当计划满足以下条件时，工具会保留为单个任务：

计划描述的是一个紧密关联的任务（即使包含多个段落的详细说明）
仅包含1-2个步骤（数量不足以支撑拆分）
工作项紧密耦合（无法有意义地分离）
计划是探索性或调查性的（研究、分析、发现）
拆分后会创建不符合自然工作单元的人为边界

What Each Subtask Contains

子任务包含内容

When breakdown occurs, each subtask includes:

Description: Brief summary extracted from list item, heading, or section
Context: Relevant details from that section plus reference to parent task
Parent link: Automatically linked to main task via
```
--parent
```

当进行拆分时，每个子任务包含：

描述：从列表项、标题或章节中提取的简短摘要
上下文：该章节的相关细节以及父任务的引用
父任务链接：通过
```
--parent
```
自动关联到主任务

Example: With Breakdown

示例：拆分情况

Input plan (

auth-plan.md

markdown

undefined

输入计划（

auth-plan.md

）：

markdown

undefined

Plan: Add Authentication System

Implementation

Create database schema for users/tokens
Implement auth controller with endpoints
Add JWT middleware for route protection
Build frontend login/register forms
Add integration tests


**Output**:

Created task abc123 from plan

Analyzed plan structure: Found 5 distinct implementation steps Created 5 subtasks:

abc124: Create database schema for users/tokens
abc125: Implement auth controller with endpoints
abc126: Add JWT middleware for route protection
abc127: Build frontend login/register forms
abc128: Add integration tests

View full structure: dex show abc123

undefined

Create database schema for users/tokens
Implement auth controller with endpoints
Add JWT middleware for route protection
Build frontend login/register forms
Add integration tests


**输出**：

Created task abc123 from plan

Analyzed plan structure: Found 5 distinct implementation steps Created 5 subtasks:

abc124: Create database schema for users/tokens
abc125: Implement auth controller with endpoints
abc126: Add JWT middleware for route protection
abc127: Build frontend login/register forms
abc128: Add integration tests

View full structure: dex show abc123

undefined

Example: Without Breakdown

示例：不拆分情况

Input plan (

bugfix-plan.md

markdown

undefined

输入计划（

bugfix-plan.md

）：

markdown

undefined

Plan: Fix Login Validation Bug

Problem

Solution

Update validation regex in auth.ts line 42 to allow spaces


**Output**:

Created task xyz789 from plan

Plan describes a cohesive single task. No subtask breakdown needed.

View task: dex show xyz789

undefined

Update validation regex in auth.ts line 42 to allow spaces


**输出**：

Created task xyz789 from plan

Plan describes a cohesive single task. No subtask breakdown needed.

View task: dex show xyz789

undefined

Example: Epic-Level Breakdown (Two-Level Hierarchy)

示例：史诗级拆分（两级结构）

Input plan (

full-auth-plan.md

markdown

undefined

输入计划（

full-auth-plan.md

）：

markdown

undefined

Plan: Complete User Authentication System

Phase 1: Backend Infrastructure

Create database schema for users and sessions
Implement password hashing with bcrypt
Add JWT token generation and validation

Create database schema for users and sessions
Implement password hashing with bcrypt
Add JWT token generation and validation

Phase 2: API Endpoints

POST /auth/register - User registration
POST /auth/login - User login
POST /auth/logout - Session invalidation
POST /auth/reset-password - Password reset flow

POST /auth/register - User registration
POST /auth/login - User login
POST /auth/logout - Session invalidation
POST /auth/reset-password - Password reset flow

Phase 3: Frontend Integration

Login/register forms with validation
Protected route components
Session persistence with refresh tokens


**Output**:

Created epic abc123 from plan

Analyzed plan structure: Found 3 major phases with sub-items Created as epic with 3 tasks:

def456: Backend Infrastructure (3 subtasks)
ghi789: API Endpoints (4 subtasks)
jkl012: Frontend Integration (3 subtasks)

View full structure: dex list abc123

undefined

Login/register forms with validation
Protected route components
Session persistence with refresh tokens


**输出**：

Created epic abc123 from plan

Analyzed plan structure: Found 3 major phases with sub-items Created as epic with 3 tasks:

def456: Backend Infrastructure (3 subtasks)
ghi789: API Endpoints (4 subtasks)
jkl012: Frontend Integration (3 subtasks)

View full structure: dex list abc123

undefined

Options

可选参数

bash

/dex-plan <file> --priority 2              # Set priority
/dex-plan <file> --parent abc123           # Create as subtask

bash

/dex-plan <file> --priority 2              # 设置优先级
/dex-plan <file> --parent abc123           # 创建为子任务

After Creating

创建后的操作

Once created, you can:

View the task:
```
dex show <task-id>
```

Create additional subtasks:

dex create "..." --parent <task-id> --description "..."

Track progress through implementation
Complete the task:
```
dex complete <task-id> --result "..."
```

Run

dex show <task-id>

to see the full task structure including any automatically created subtasks.

任务创建完成后，你可以：

查看任务：
```
dex show <task-id>
```

创建额外子任务：

dex create "..." --parent <task-id> --description "..."

跟踪实现进度
完成任务：
```
dex complete <task-id> --result "..."
```

执行

dex show <task-id>

查看完整任务结构，包括自动创建的子任务。

When NOT to Use

不适用场景

Document is incomplete or exploratory (just draft notes)
Content isn't actionable or ready for implementation
File hasn't been saved to disk yet
File doesn't contain meaningful planning/design content

文档不完整或仅为探索性内容（只是草稿笔记）
内容不可执行或未准备好进行实现
文件尚未保存到磁盘
文件不包含有意义的规划/设计内容

Implementation Instructions for Skill

工具执行说明

These instructions are for the skill agent executing
/dex-plan
. Follow this workflow exactly:

以下是技能代理执行
/dex-plan
的说明，请严格遵循此工作流程：

Step 1: Create Main Task

步骤1：创建主任务

Execute the

dex plan

command with the provided markdown file:

bash

dex plan <markdown-file> [options]

This creates the parent task and returns its ID. Capture this ID for subsequent steps.

使用提供的Markdown文件执行

dex plan

命令：

bash

dex plan <markdown-file> [options]

这会创建父任务并返回其ID，需记录该ID用于后续步骤。

Step 2: Read and Analyze the Plan

步骤2：读取并分析计划

After creating the main task, read it back to analyze its structure:

bash

dex show <task-id>

Examine the context field (which contains the full markdown) for breakdown potential.

创建主任务后，重新读取任务以分析其结构：

bash

dex show <task-id>

检查上下文字段（包含完整Markdown内容）以确定是否有拆分潜力。

Step 3: Apply Breakdown Decision Logic

步骤3：应用拆分决策逻辑

Analyze the plan structure and decide: Should this be broken down into subtasks?

分析计划结构并决定：是否需要拆分为子任务？

Look for these breakdown indicators:

拆分识别指标：

Numbered or bulleted implementation lists (3-7 items):

markdown

## Implementation

1. Create database schema → SUBTASK
2. Build API endpoints → SUBTASK
3. Add frontend components → SUBTASK

Clear subsections under implementation/tasks/steps:

markdown

### 1. Backend Changes

- Modify server.ts
- Add authentication
  → SUBTASK: "Backend Changes" with this context

### 2. Frontend Updates

- Update login form
- Add error handling
  → SUBTASK: "Frontend Updates" with this context

File-specific sections:

markdown

### `src/auth.ts` - Add JWT validation

[Details about changes]
→ SUBTASK: "Add JWT validation to auth.ts"

### `src/middleware.ts` - Create auth middleware

[Details about changes]
→ SUBTASK: "Create auth middleware"

Sequential phases:

markdown

## Implementation Sequence

**Phase 1: Database Layer**
[Details] → SUBTASK

**Phase 2: API Layer**
[Details] → SUBTASK

**Phase 3: Frontend Layer**
[Details] → SUBTASK

编号或项目符号形式的实现列表（3-7项）：

markdown

## Implementation

1. Create database schema → 子任务
2. Build API endpoints → 子任务
3. Add frontend components → 子任务

实现/任务/步骤下的清晰子章节：

markdown

### 1. Backend Changes

- Modify server.ts
- Add authentication
  → 子任务："Backend Changes"，包含此上下文

### 2. Frontend Updates

- Update login form
- Add error handling
  → 子任务："Frontend Updates"，包含此上下文

针对特定文件的章节：

markdown

### `src/auth.ts` - Add JWT validation

[变更详情]
→ 子任务："Add JWT validation to auth.ts"

### `src/middleware.ts` - Create auth middleware

[变更详情]
→ 子任务："Create auth middleware"

顺序阶段：

markdown

## Implementation Sequence

**Phase 1: Database Layer**
[详情] → 子任务

**Phase 2: API Layer**
[详情] → 子任务

**Phase 3: Frontend Layer**
[详情] → 子任务

Do NOT break down when:

不拆分的情况：

Only 1-2 steps/items present
Plan is a single cohesive fix or small change
Content is exploratory ("investigate", "research", "explore")
Work items are inseparable (tightly coupled implementation)
Breaking down creates artificial boundaries
Plan is very short (< 10 lines of meaningful content)

仅包含1-2个步骤/项
计划是一个紧密关联的修复或小变更
内容为探索性的（"调查"、"研究"、"探索"）
工作项不可分离（实现紧密耦合）
拆分后会创建人为边界
计划非常简短（有意义内容少于10行）

Step 4: Extract Subtasks (If Breaking Down)

步骤4：提取子任务（若进行拆分）

For each identified subtask:

Extract description: Use the list item text, heading, or section title
- Strip numbering and bullets: "1. Add auth" → "Add auth"
- Keep it concise (1-10 words)
- Use imperative form: "Add", "Create", "Update", "Fix"
Extract context: Include relevant details from that section
- Copy the full section content for that subtask
- Add reference: "This is part of [parent task description]"
- Include code snippets, file paths, specific requirements

Create the subtask:

bash

dex create "<subtask-description>" \
  --parent <parent-task-id> \
  --description "<extracted-context-with-parent-reference>"

对于每个识别出的子任务：

提取描述：使用列表项文本、标题或章节标题
- 移除编号和项目符号："1. Add auth" → "Add auth"
- 保持简洁（1-10个单词）
- 使用祈使语气："Add"、"Create"、"Update"、"Fix"
提取上下文：包含该章节的相关细节
- 复制该章节的完整内容
- 添加引用："这是[父任务描述]的一部分"
- 包含代码片段、文件路径、特定要求

创建子任务：

bash

dex create "<subtask-description>" \
  --parent <parent-task-id> \
  --description "<extracted-context-with-parent-reference>"

Step 5: Report Results

步骤5：返回结果

If subtasks were created:

Created task <id> from plan

Analyzed plan structure: Found <N> distinct implementation steps
Created <N> subtasks:
- <subtask-id-1>: <description-1>
- <subtask-id-2>: <description-2>
- <subtask-id-3>: <description-3>
...

View full structure: dex show <parent-id>

If no breakdown occurred:

Created task <id> from plan

Plan describes a cohesive single task. No subtask breakdown needed.

View task: dex show <id>

若创建了子任务：

Created task <id> from plan

Analyzed plan structure: Found <N> distinct implementation steps
Created <N> subtasks:
- <subtask-id-1>: <description-1>
- <subtask-id-2>: <description-2>
- <subtask-id-3>: <description-3>
...

View full structure: dex show <parent-id>

若未进行拆分：

Created task <id> from plan

Plan describes a cohesive single task. No subtask breakdown needed.

View task: dex show <id>

Examples of Subtask Extraction

子任务提取示例

Example 1: Numbered list

markdown

undefined

示例1：编号列表

markdown

undefined

Implementation Steps

Create User model with email, password fields
Add POST /api/auth/register endpoint
Implement JWT token generation


Extracted subtasks:

```bash
dex create "Create User model with email, password fields" \
  --parent abc123 \
  --description "Create a User model with email and password fields. This is part of 'Add Authentication System'."

dex create "Add POST /api/auth/register endpoint" \
  --parent abc123 \
  --description "Add POST /api/auth/register endpoint to handle user registration. This is part of 'Add Authentication System'."

dex create "Implement JWT token generation" \
  --parent abc123 \
  --description "Implement JWT token generation for authenticated sessions. This is part of 'Add Authentication System'."

Example 2: Subsections with details

markdown

undefined

Create User model with email, password fields
Add POST /api/auth/register endpoint
Implement JWT token generation


提取的子任务：

```bash
dex create "Create User model with email, password fields" \
  --parent abc123 \
  --description "Create a User model with email and password fields. This is part of 'Add Authentication System'."

dex create "Add POST /api/auth/register endpoint" \
  --parent abc123 \
  --description "Add POST /api/auth/register endpoint to handle user registration. This is part of 'Add Authentication System'."

dex create "Implement JWT token generation" \
  --parent abc123 \
  --description "Implement JWT token generation for authenticated sessions. This is part of 'Add Authentication System'."

示例2：带详情的子章节

markdown

undefined

Frontend: Login Form Component

Create a new React component at

src/components/LoginForm.tsx

Email and password inputs
Submit button with loading state
Error message display
Validation on submit

Create a new React component at

src/components/LoginForm.tsx

Email and password inputs
Submit button with loading state
Error message display
Validation on submit

Backend: Auth Routes

Add to

src/routes/auth.ts

POST /login endpoint
Password verification using bcrypt
JWT token generation on success


Extracted subtasks:

```bash
dex create "Frontend: Login Form Component" \
  --parent abc123 \
  --description "Create a new React component at src/components/LoginForm.tsx with email/password inputs, submit button with loading state, error message display, and validation on submit. This is part of 'Add Authentication System'."

dex create "Backend: Auth Routes" \
  --parent abc123 \
  --description "Add to src/routes/auth.ts: POST /login endpoint, password verification using bcrypt, JWT token generation on success. This is part of 'Add Authentication System'."

Example 3: Should NOT break down

markdown

undefined

Add to

src/routes/auth.ts

POST /login endpoint
Password verification using bcrypt
JWT token generation on success


提取的子任务：

```bash
dex create "Frontend: Login Form Component" \
  --parent abc123 \
  --description "Create a new React component at src/components/LoginForm.tsx with email/password inputs, submit button with loading state, error message display, and validation on submit. This is part of 'Add Authentication System'."

dex create "Backend: Auth Routes" \
  --parent abc123 \
  --description "Add to src/routes/auth.ts: POST /login endpoint, password verification using bcrypt, JWT token generation on success. This is part of 'Add Authentication System'."

示例3：不拆分情况

markdown

undefined

Plan: Fix Typo in Error Message

Problem

Error message says 'Sucessful' instead of 'Successful'

Solution

Fix typo in src/messages.ts line 42


Decision: Single cohesive task, only one change. Do NOT create subtasks.

Fix typo in src/messages.ts line 42


决策：单个紧密关联的任务，仅需一处变更，不创建子任务。

Key Principles

核心原则

Agent judgment is critical: Use intelligence to determine if breakdown adds value
Err on the side of NOT breaking down: Only break down when it clearly helps
Each subtask must be meaningful: Not just a single line change
Context is essential: Each subtask should have enough context to be actionable independently
Preserve plan semantics: Don't force a structure that doesn't match the plan's intent

代理判断至关重要：运用智能判断拆分是否有价值
优先选择不拆分：仅在拆分明显有益时才进行
每个子任务必须有意义：不能只是单行变更
上下文必不可少：每个子任务需包含足够独立执行的上下文
保留计划语义：不要强制使用不符合计划意图的结构