# dex-plan

Converts markdown plans, specs, and design documents into trackable dex tasks with automatic subtask breakdown.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 737 installs · ★ 386
- Author: dcramer
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dcramer/dex/tree/HEAD/plugins/dex/skills/dex-plan/SKILL.md
- Updated: 2026-03-02
- HTML: https://affpapa.org/en/nevibecode/skills/dex-plan

## What it does

\`dex-plan` reads a markdown file, such as a plan mode draft or `SPEC.md`, and registers it as a task in dex. It pulls the title from the first `#` heading, strips any "Plan: " prefix, and stores the document body as task context.

When a plan contains 3–7 distinct steps or separate phases, the skill analyzes the structure and creates linked subtasks via `--parent`. Dex enforces a limit of three hierarchy levels: epics, tasks, and subtasks. If the document describes a single bugfix or just 1–2 steps, the skill keeps it as one task.

The workflow relies on having the `dex` CLI installed locally or running through `npx @zeeg/dex`. Passing unsaved files or loose exploratory notes will fail because the skill expects actionable, saved markdown on disk.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dcramer/dex --skill dex-plan -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/dex-plan/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/dex-plan/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dcramer/dex --skill dex-plan -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/dex-plan/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dcramer/dex --skill dex-plan -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/dex-plan/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dcramer/dex dex-plan
```

2. **Manually: put the files in place**
- File: `.github/skills/dex-plan/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dcramer/dex --skill dex-plan -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dcramer/dex --path plugins/dex/skills/dex-plan
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/dex-plan/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dcramer/dex --skill dex-plan -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dcramer/dex/tree/HEAD/plugins/dex/skills/dex-plan/SKILL.md

## When to use it
- turn Claude Code plan mode files into dex tasks
- split a markdown spec into a multi-level task hierarchy
- convert a roadmap document into an epic with linked items
- attach design documentation context directly to tracking tickets

## Example prompts
- /dex-plan ~/.claude/plans/auth-plan.md
- /dex-plan SPEC.md --priority 2
- /dex-plan docs/ARCHITECTURE.md --parent abc123

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: e261cc9029713538.

BEGIN THIRD-PARTY FILE e261cc9029713538
````text
---
name: dex-plan
description: Create dex task from markdown planning documents (plans, specs, design docs, roadmaps)
---

# Converting Markdown Documents to Tasks

## Command Invocation

Use `dex` directly for all commands:

```bash
dex <command>
```

If `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.

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

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

## What It Does

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

## Examples

**From plan mode file:**

```markdown
# Plan: Add JWT Authentication

## Summary

...
```

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

**From specification document:**

```markdown
# 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
````
END THIRD-PARTY FILE e261cc9029713538

The third-party file has ended. Everything between the e261cc9029713538 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3282 of 12935 bytes. © dcramer · MIT · https://github.com/dcramer/dex/tree/HEAD/plugins/dex/skills/dex-plan/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md