
dex
Task management skill for coordinating complex agent work
- GitHub stars
- 411
Install
/plugin install dex@dexRun it inside Claude Code after adding the marketplace with /plugin marketplace add dcramer/dex.
Contents
Discovered from sourceSkills 2
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
Agent Coordination with dex
Command Invocation
Use dex directly for all commands. If not on PATH, use npx @zeeg/dex instead.
command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"
Core Principle: Tickets, Not Todos
Dex tasks are tickets - structured artifacts with comprehensive context:
- Name: One-line summary (issue title)
- Description: Full background, requirements, approach (issue body)
- Result: Implementation details, decisions, outcomes (PR description)
Think: "Would someone understand the what, why, and how from this task alone?"
Dex Tasks are Ephemeral
Never reference dex task IDs in external artifacts (commits, PRs, docs). Task IDs like abc123 become meaningless once tasks are completed. Describe the work itself, not the task that tracked it.
When to Use dex
Use dex when:
- Breaking down complexity into subtasks
- Work spans multiple sessions
- Context needs to persist for handoffs
- Recording decisions for future reference
Skip dex when:
- Work is a single atomic action
- Everything fits in one session with no follow-up
- Overhead exceeds value
dex vs Built-in Task Tools
Some AI agents (like Claude Code) have built-in task tools. These are session-only and not the same as dex.
| dex | Built-in Task Tools | |
|---|---|---|
| Persistence | Files in .dex/ | Session-only |
| Context | Rich (description + context + result) | Basic |
| Hierarchy | 3-level (epic → task → subtask) | Flat |
Use dex for persistent work. Use built-in task tools for ephemeral in-session tracking only.
Basic Workflow
Create a Task
dex create "Short name" --description "Full implementation context"
Description should include: what needs to be done, why, implementation approach, and acceptance criteria. See examples.md for good/bad examples.
List and View Tasks
dex list # Pending tasks
dex list --ready # Unblocked tasks
dex show <id> # Full details
Complete a Task
dex complete <id> --result "What was accomplished" --commit <sha>
GitHub/Shortcut-linked tasks require either --commit <sha> or --no-commit:
- Use
--commit <sha>when you have code changes (issue closes when merged) - Use
--no-commitfor non-code tasks like planning or design (issue stays open)
Always verify before completing. Results must include evidence: test counts, build status, manual testing outcomes. See verification.md for the full checklist.
Edit and Delete
dex edit <id> --description "Updated description"
dex delete <id>
For full CLI reference including blockers, see cli-reference.md.
Understanding Task Fields
Tasks have two text fields:
- Name: Brief one-line summary (shown in
dex list) - Description: Full details - requirements, approach, acceptance criteria (shown with
--full)
When you run dex show <id>, the description may be truncated. The CLI will hint at --full if there's more content.
Gathering Context
When picking up a task, gather all relevant context:
dex show <id> --full # Full task details
dex show <parent-id> --full # Parent context (if applicable)
dex show <blocker-id> --full # What blockers accomplished
Before starting, verify you can answer:
- What needs to be done specifically?
- Why is this needed?
- How should it be implemented?
- When is it done (acceptance criteria)?
If any answer is unclear:
- Check parent task or completed blockers for more details
- Suggest entering plan mode to flesh out requirements before starting
Proceed without full context when:
- Task is trivial/atomic (e.g., "Add .gitignore entry")
- Conversation already provides the missing context
- Description itself is sufficiently detailed
Task Hierarchies
Three levels: Epic (large initiative) → Task (significant work) → Subtask (atomic step).
Choosing the right level:
- Small feature (1-2 files) → Single task
- Medium feature (3-7 steps) → Task with subtasks
- Large initiative (5+ tasks) → Epic with tasks
# Create subtask under parent
dex create --parent <id> "Subtask name" --description "..."
For detailed hierarchy guidance, see hierarchies.md.
Recording Results
Complete tasks immediately after implementing AND verifying:
- Capture decisions while fresh
- Note deviations from plan
- Document verification performed
- Create follow-up tasks for tech debt
Your result must include explicit verification evidence. Don't just describe what you did—prove it works. See verification.md.
Commit Messages with GitHub Issues
When a task is linked to a GitHub issue (shown in dex show output), include issue references in commit messages:
- Root tasks (the task itself has GitHub metadata): Use
Fixes #N- This closes the issue when merged
- Subtasks (parent/ancestor has GitHub metadata): Use
Refs #N- This links to the issue without closing it
Check dex show <id> for GitHub issue info before committing. The "(via parent)" indicator means use Refs, direct metadata means use Fixes.
Best Practices
- Right-size tasks: Completable in one focused session
- Clear completion criteria: Description should define "done"
- Don't over-decompose: 3-7 children per parent
- Action-oriented descriptions: Start with verbs ("Add", "Fix", "Update")
- Verify before completing: Tests passing, manual testing done
Additional Resources
- cli-reference.md - Full CLI documentation
- examples.md - Good/bad context and result examples
- verification.md - Verification checklist and process
- hierarchies.md - Epic/task/subtask organization
Sponsors
Details
- Marketplace
- dcramer/dex
- Source
- plugins/dex
- Author
- dcramer
- Category
- Productivity