/dex-plan

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:

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

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

# 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