dex-plan：将Markdown规划文档自动转换为可追踪任务 | 项目管理自动化工具

dex-plan by dcramer/dex

251 周安装量

223 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/dcramer/dex --skill dex-plan

开发项目管理自动化

🇨🇳中文介绍

将 Markdown 文档转换为任务

命令调用

所有命令直接使用 dex：

dex <命令>

如果 dex 不在 PATH 中，请改用 npx @zeeg/dex <命令>。开始时检查一次：

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

使用 /dex-plan 可将任何 Markdown 规划文档转换为可追踪的 dex 任务。

使用时机

在规划模式完成计划后
将规范文档转换为可追踪的任务
将设计文档转换为实现任务
从路线图或里程碑文档创建任务
追踪任何 Markdown 规划或设计内容

支持的文档

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

来自规划模式的计划文件 (~/.claude/plans/*.md)

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

自动子任务分解

创建主任务后，技能会分析计划结构，以确定将其分解为子任务是否能增加价值。

技能支持最多 3 个层级（dex 强制实施的最大深度）：

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

当计划具有以下情况时，技能会创建子任务：

3-7 个清晰可分离的工作项（编号步骤、不同部分、实现阶段）
跨多个文件或组件的实现（不同的模块、层次或领域）
清晰的顺序依赖关系（步骤 1 在步骤 2 之前）
受益于单独追踪的独立项

史诗级分解（创建任务，而非子任务）当：

计划包含具有自身子项的主要阶段/部分
5 个以上不同的工作领域
计划跨越多个系统或组件
工作需要多个会话

何时不进行分解

技能保持单一任务当：

计划描述一个内聚的任务（即使有多个详细段落）
仅存在 1-2 个步骤（不足以证明分解的合理性）
工作项紧密耦合（无法有意义地分离）
计划是探索性或调查性的（研究、分析、发现）
分解会创建不反映自然工作单元的人为边界

每个子任务包含的内容

当发生分解时，每个子任务包括：

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

示例：进行分解

输入计划 (auth-plan.md)：

# Plan: Add Authentication System

## Implementation

1. Create database schema for users/tokens
2. Implement auth controller with endpoints
3. Add JWT middleware for route protection
4. Build frontend login/register forms
5. 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

示例：不进行分解

输入计划 (bugfix-plan.md)：

# Plan: Fix Login Validation Bug

## Problem

Login fails when username has spaces

## Solution

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

示例：史诗级分解（两级层次结构）

输入计划 (full-auth-plan.md)：

# Plan: Complete User Authentication System

## Phase 1: Backend Infrastructure

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

## Phase 2: API Endpoints

1. POST /auth/register - User registration
2. POST /auth/login - User login
3. POST /auth/logout - Session invalidation
4. POST /auth/reset-password - Password reset flow

## Phase 3: Frontend Integration

1. Login/register forms with validation
2. Protected route components
3. 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

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

创建后，您可以：

查看任务：dex show <任务-id>
创建额外的子任务：dex create "..." --parent <任务-id> --description "..."
通过实现追踪进度
完成任务：dex complete <任务-id> --result "..."

运行 dex show <任务-id> 以查看完整的任务结构，包括任何自动创建的子任务。

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

这些说明适用于执行 /dex-plan 的技能代理。 请严格按照此工作流程操作：

步骤 1：创建主任务

使用提供的 Markdown 文件执行 dex plan 命令：

dex plan <markdown-文件> [选项]

这将创建父任务并返回其 ID。捕获此 ID 用于后续步骤。

步骤 2：读取并分析计划

创建主任务后，将其读回以分析其结构：

dex show <任务-id>

检查上下文字段（包含完整的 Markdown）以了解分解潜力。

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

分析计划结构并决定：是否应将其分解为子任务？

寻找以下分解指标：

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

## Implementation

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

实现/任务/步骤下的清晰子部分：

### 1. Backend Changes

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

### 2. Frontend Updates

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

文件特定部分：

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

[Details about changes]
→ 子任务："Add JWT validation to auth.ts"

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

[Details about changes]
→ 子任务："Create auth middleware"

顺序阶段：

## Implementation Sequence

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

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

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

不进行分解当：

仅存在 1-2 个步骤/项
计划是单一内聚的修复或小改动
内容是探索性的（"investigate"、"research"、"explore"）
工作项不可分割（紧密耦合的实现）
分解会创建人为边界
计划非常短（< 10 行有意义的内容）

步骤 4：提取子任务（如果进行分解）

对于每个识别的子任务：

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

创建子任务：

dex create "<子任务-描述>" \
  --parent <父任务-id> \
  --description "<提取的上下文-包含父引用>"

步骤 5：报告结果

如果创建了子任务：

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>

子任务提取示例

示例 1：编号列表

## Implementation Steps

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

提取的子任务：

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：包含细节的子部分

### 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

### Backend: Auth Routes

Add to `src/routes/auth.ts`:

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

提取的子任务：

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：不应分解

# Plan: Fix Typo in Error Message

## Problem

Error message says 'Sucessful' instead of 'Successful'

## Solution

Fix typo in src/messages.ts line 42

决策：单一内聚任务，仅一个更改。不创建子任务。

代理判断至关重要：运用智能判断分解是否能增加价值
倾向于不分解：仅当明显有帮助时才分解
每个子任务必须有意义：不仅仅是单行更改
上下文至关重要：每个子任务应有足够的上下文以独立操作
保留计划语义：不要强制采用与计划意图不符的结构

2026 年 1 月 24 日

🇺🇸English

Converting Markdown Documents to Tasks

Command Invocation

Use dex directly for all commands:

dex <command>

If dex is not on PATH, use npx @zeeg/dex <command> instead. Check once at the start:

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.

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

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

Usage

/dex-plan <markdown-file-path>

Examples

From plan mode:

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

From specification document:

/dex-plan @SPEC.md

From design document:

/dex-plan docs/AUTHENTICATION_DESIGN.md

From roadmap:

/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

Examples

From plan mode file:

# Plan: Add JWT Authentication

## Summary

...

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

From specification document:

# User Authentication Specification

## Requirements

...

→ Task description: "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"

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

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

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

Example: With Breakdown

Input plan (auth-plan.md):

# Plan: Add Authentication System

## Implementation

1. Create database schema for users/tokens
2. Implement auth controller with endpoints
3. Add JWT middleware for route protection
4. Build frontend login/register forms
5. 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

Example: Without Breakdown

Input plan (bugfix-plan.md):

# Plan: Fix Login Validation Bug

## Problem

Login fails when username has spaces

## 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

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

Input plan (full-auth-plan.md):

# Plan: Complete User Authentication System

## Phase 1: Backend Infrastructure

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

## Phase 2: API Endpoints

1. POST /auth/register - User registration
2. POST /auth/login - User login
3. POST /auth/logout - Session invalidation
4. POST /auth/reset-password - Password reset flow

## Phase 3: Frontend Integration

1. Login/register forms with validation
2. Protected route components
3. 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

Options

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

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.

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:

Step 1: Create Main Task

Execute the dex plan command with the provided markdown file:

dex plan <markdown-file> [options]

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

Step 2: Read and Analyze the Plan

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

dex show <task-id>

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

Step 3: Apply Breakdown Decision Logic

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):

## Implementation

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

Clear subsections under implementation/tasks/steps:

### 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:

### `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:

## Implementation Sequence

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

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

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

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)

Step 4: Extract Subtasks (If Breaking Down)

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:

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

Step 5: Report Results

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>

Examples of Subtask Extraction

Example 1: Numbered list

## Implementation Steps

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

Extracted subtasks:

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

### 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

### Backend: Auth Routes

Add to `src/routes/auth.ts`:

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

Extracted subtasks:

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

# 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.

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

Weekly Installs

231

Repository

dcramer/dex

GitHub Stars

217

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykFail

Installed on

opencode184

claude-code174

github-copilot152

codex132

kimi-cli131

gemini-cli109

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

140,500 周安装

dex-plan：将Markdown规划文档自动转换为可追踪任务 | 项目管理自动化工具

🇨🇳中文介绍

将 Markdown 文档转换为任务

命令调用

使用时机

支持的文档

相关 Skills

用法

示例

功能说明

示例

自动子任务分解

层级结构

何时进行分解

何时不进行分解

每个子任务包含的内容

示例：进行分解

示例：不进行分解

示例：史诗级分解（两级层次结构）

选项

创建后

何时不使用

技能实现说明

步骤 1：创建主任务

步骤 2：读取并分析计划

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

寻找以下分解指标：

不 进行分解当：

步骤 4：提取子任务（如果进行分解）

步骤 5：报告结果

子任务提取示例

关键原则

🇺🇸English

Converting Markdown Documents to Tasks

Command Invocation

When to Use

Supported Documents

Usage

Examples

What It Does

Examples

Automatic Subtask Breakdown

Hierarchy Levels

When Breakdown Happens

When Breakdown Does NOT Happen

What Each Subtask Contains

Example: With Breakdown

Example: Without Breakdown

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

Options

After Creating

When NOT to Use

Implementation Instructions for Skill

Step 1: Create Main Task

Step 2: Read and Analyze the Plan

Step 3: Apply Breakdown Decision Logic

Look for these breakdown indicators:

Do NOT break down when:

Step 4: Extract Subtasks (If Breaking Down)

Step 5: Report Results

Examples of Subtask Extraction

Key Principles

最新 Skills

不进行分解当：