Dex

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.

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-commit for 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:

1. Check parent task or completed blockers for more details 2. 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

1. Right-size tasks: Completable in one focused session 2. Clear completion criteria: Description should define "done" 3. Don't over-decompose: 3-7 children per parent 4. Action-oriented descriptions: Start with verbs ("Add", "Fix", "Update") 5. 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

CLI Reference

Full command reference for dex. For basic usage, see SKILL.md.

Create a Task

dex create "Task name" --description "Full implementation details"

Options:

• <name> or -n, --name: One-line summary (required)
• -d, --description: Full implementation details (optional but recommended)
• -p, --priority <n>: Lower = higher priority (default: 1)
• -b, --blocked-by <ids>: Comma-separated task IDs that must complete first
• --parent <id>: Parent task ID (creates subtask)

List Tasks

dex list                      # Show pending tasks (default)
dex list --all                # Include completed
dex list --completed          # Only completed
dex list --ready              # Only tasks ready to work on (no blockers)
dex list --blocked            # Only blocked tasks
dex list --query "login"      # Search in name/description

Blocked tasks show an indicator: [B: xyz123] (blocked by task xyz123) or [B: 2] (blocked by 2 tasks).

View Task Details

dex show <id>

Complete a Task

dex complete <id> --result "What was accomplished" --commit <sha>
dex complete <id> --result "No code changes needed" --no-commit

For GitHub/Shortcut-linked tasks, you must specify either:

• --commit <sha> - Links the commit; issue closes when commit is merged to remote
• --no-commit - Completes without a commit; issue stays open (close manually)

Tasks without remote links (no GitHub/Shortcut metadata) don't require either flag.

Linking Commits

When completing a task that involved creating a commit, link it:

dex complete abc123 --result "Implemented feature X" --commit a1b2c3d

This captures commit SHA, message, and branch automatically. The linked GitHub/Shortcut issue will be closed only when the commit is pushed to the remote.

GitHub Issue References: If the task is linked to a GitHub issue (visible in dex show output), include issue references in your commit message. Use Fixes #N for root tasks (closes the issue) or Refs #N for subtasks (links without closing).

Edit a Task

dex edit <id> -n "Updated name" --description "Updated description"
dex edit <id> --add-blocker xyz123      # Add blocking dependency
dex edit <id> --remove-blocker xyz123   # Remove blocking dependency

Delete a Task

dex delete <id>

Note: Deleting a parent task also deletes all its subtasks.

Blocking Dependencies

Use blocking dependencies to enforce task ordering:

# Create a task that depends on another
dex create "Deploy to production" --description "..." --blocked-by abc123

# Add a blocker to an existing task
dex edit xyz789 --add-blocker abc123

# Remove a blocker
dex edit xyz789 --remove-blocker abc123

When to Use Blockers

Use blockers when:

• Task B cannot start until Task A completes
• Multiple tasks depend on a shared prerequisite
• You want to prevent out-of-order completion

Don't use blockers when:

• Tasks can be worked on in parallel
• The dependency is just a logical grouping (use subtasks instead)

Viewing Blocking Relationships

• dex list shows blocked indicator: [B: xyz123] or [B: 2]
• dex list --blocked shows only blocked tasks
• dex list --ready shows only tasks with no blockers
• dex show <id> displays "Blocked by:" and "Blocks:" sections

Blocked tasks can still be completed (soft enforcement), but you'll see a warning.

Storage

Tasks are stored as individual files:

• <git-root>/.dex/tasks/{id}.json (if in a git repo)
• ~/.dex/tasks/{id}.json (fallback)

Override with --storage-path or DEX_STORAGE_PATH env var.

Task File Format

{
  "id": "abc123",
  "parent_id": null,
  "name": "One-line summary",
  "description": "Full implementation details...",
  "priority": 1,
  "completed": false,
  "result": null,
  "blocked_by": ["xyz789"],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "completed_at": null
}

Epic Examples

Real examples of well-structured epics from the dex project.

What Makes a Great Epic

1. Clear problem statement: Why this work is needed 2. Solution overview: High-level approach 3. Key design decisions: Technical choices with rationale 4. Phased subtasks: 3-7 tasks, logically ordered 5. Success criteria: How to know when it's done

Example 1: Migrate to JSONL Storage Format

A completed epic showing a focused technical migration.

Context

# Plan: Migrate to JSONL Storage Format

## Summary

Migrate from individual `.dex/tasks/{id}.json` files to a single `tasks.jsonl`
file to reduce file system noise while maintaining merge-safety.

## Problem Statement

- Dozens/hundreds of individual task files create noise
- Directory operations slow with many files
- Git conflicts when multiple developers add tasks

## Solution Overview

JSONL format: one task per line, merge-safe (adding = appending a line).

## Implementation Plan

### Phase 1: Create JSONL Storage Implementation

Create `JsonlStorage` class: parse lines as JSON, atomic writes via temp+rename.

### Phase 2: Add Migration from File-per-Task Format

Auto-detect old format, migrate to JSONL, backup old directory.

### Phase 3: Switch Default Storage

Use JsonlStorage by default, keep FileStorage for compatibility.

### Phase 4: Add Tests

Round-trip, migration, and corruption handling tests.

### Phase 5: Documentation Updates

## Success Criteria

- All existing tests pass
- Migration from old formats works automatically
- No data loss during migration

Subtask Breakdown

[x] uv7izxz0: Migrate to JSONL Storage Format (5 subtasks)
├── [x] ocjsepij: Create JSONL Storage Implementation
├── [x] i5or9r1e: Add migration from file-per-task format
├── [x] 0anx9dfc: Switch default storage to JSONL
├── [x] ak51x8dt: Add comprehensive tests for JSONL storage
└── [x] ao7gpv85: Update documentation for JSONL storage format

Why it works: Focused scope, clear rationale, phased approach with 5 right-sized subtasks.

---

Example 2: Archive Strategy

An in-progress epic with clear design decisions.

Context

# Archive Strategy: Compacted Task History

## Problem Statement

Completed tasks accumulate over time, consuming memory, slowing performance,
and creating noise in active task lists.

## Solution Overview

Move old completed tasks to `archive.jsonl` in compacted format (dropping
context field for 50-80% size reduction).

## Key Design Decisions

- **Compacted fields**: Archive drops context, blockedBy, blocks
- **Rolled-up children**: Epic's children stored in archived_children array
- **Criteria**: Archive if completed >90 days AND not in recent 50
- **Query behavior**: `dex list` reads only active; `dex show` checks both

## Implementation Plan

### Phase 1: Storage Layer

Create archive storage with compaction logic.

### Phase 2: Manual Archive Command

`dex archive <task-id>` archives task + descendants.

### Phase 3: Auto-Archive

Time + count based archival of complete lineages.

### Phase 4: CLI Integration

Add --archived flag to list, integrate into show/query.

### Phase 5: Tests

Subtask Breakdown

[ ] t64hfub3: Archive Strategy (7 subtasks)
├── [x] qi9iakzt: Create Archive Storage Layer
├── [x] qzx9knp8: Implement Compaction Logic
├── [ ] 2uvg80ks: Add manual archive command
├── [ ] j8osnde9: Implement auto-archive functionality
├── [ ] kotl63oy: Add CLI flags for archive operations
├── [ ] xe0pfmym: Integrate archive into query operations
└── [ ] v771l2ru: Add comprehensive archive tests

Why it works: Problem-first, concrete data formats, key decisions documented, logical task ordering.

---

Example 3: Dex TUI - Planning Session Interface

A larger epic with three-level hierarchy (Epic -> Phase -> Subtask).

Context (Abbreviated)

# Plan: Dex TUI - Planning Session Interface

## Summary

Terminal UI for managing dex tasks and spawning Claude Code planning sessions.

## Problem Statement

Users need to capture ideas quickly, spawn planning sessions, maintain backlog
visibility, and convert planning outputs into tasks.

## Solution Overview

Ink-based TUI showing task backlog, with keyboard shortcuts for task creation
and planning session management.

## Key Design Decisions

- **UI Framework**: Ink (declarative React patterns for terminal)
- **State**: Zustand (lightweight, persistent)
- **Claude Integration**: claude-agent-sdk

## Implementation Plan

### Phase 1: Core TUI

Task backlog view, keyboard navigation, quick task creation.

### Phase 2: Planning Sessions

Spawn sessions, status sidebar, convert results to tasks.

### Phase 3: Advanced

Templates, batch operations, cost tracking, session resume.

Subtask Breakdown

[ ] 85wau5dl: Dex TUI (3 phases)
├── [ ] zxw01uwg: Phase 1: Foundation (6 subtasks)
│   ├── [ ] dac0b3nh: Set up dex-tui package
│   ├── [ ] kgirg52i: Implement basic Ink app
│   └── ... (4 more)
├── [ ] i8855dwx: Phase 2: Planning Sessions (6 subtasks)
└── [ ] 12azrz12: Phase 3: Polish & Advanced (5 subtasks)

Why it works: Three-level hierarchy for large scope, technology decisions explicit, each phase independently valuable.

---

Anti-Patterns to Avoid

---

Template

# Plan: [Epic Name]

## Summary

One paragraph describing what this epic accomplishes.

## Problem Statement

What pain points does this address?

## Solution Overview

High-level approach (2-3 sentences).

## Key Design Decisions

- Decision 1: Choice and rationale
- Decision 2: Choice and rationale

## Implementation Plan

### Phase 1: [Name]

### Phase 2: [Name]

## Success Criteria

- [ ] Measurable outcome 1
- [ ] Measurable outcome 2

Examples

Good and bad examples for writing task descriptions and results.

Writing Descriptions

Descriptions should include everything needed to do the work without asking questions:

• What needs to be done and why
• Implementation approach (steps, files to modify, technical choices)
• Done when (acceptance criteria)

Good Description Example

dex create "Migrate storage to one file per task" \
  --description "Change storage format for git-friendliness:

Structure:
.dex/
└── tasks/
    ├── abc123.json
    └── def456.json

NO INDEX - just scan task files. For typical task counts (<100), this is fast.

Implementation:
1. Update storage.ts:
   - read(): Scan .dex/tasks/*.json, parse each, return TaskStore
   - write(task): Write single task to .dex/tasks/{id}.json
   - delete(id): Remove .dex/tasks/{id}.json
   - Add readTask(id) for single task lookup

2. Task file format: Same as current Task schema (one task per file)

3. Migration: On read, if old tasks.json exists, migrate to new format

4. Update tests

Benefits:
- Create = new file (never conflicts)
- Update = single file change
- Delete = remove file
- No index to maintain or conflict
- git diff shows exactly which tasks changed"

Notice: States the goal, shows the structure, lists specific implementation steps, and explains benefits. Someone could pick this up without asking questions.

Bad Description Example

dex create "Add auth" --description "Need to add authentication"

❌ Missing: How to implement it, what files, what's done when, technical approach

Writing Results

Results should capture what was actually done:

• What changed (implementation summary)
• Key decisions (and why)
• Verification (tests passing, manual testing done)

Good Result Example

dex complete abc123 --result "Migrated storage from single tasks.json to one file per task:

Structure:
- Each task stored as .dex/tasks/{id}.json
- No index file (avoids merge conflicts)
- Directory scanned on read to build task list

Implementation:
- Modified Storage.read() to scan .dex/tasks/ directory
- Modified Storage.write() to write/delete individual task files
- Auto-migration from old single-file format on first read
- Atomic writes using temp file + rename pattern

Trade-offs:
- Slightly slower reads (must scan directory + parse each file)
- Acceptable since task count is typically small (<100)
- Better git history - each task change is isolated

All 60 tests passing, build successful."

Notice: States what changed, lists implementation details, explains trade-offs, confirms verification.

Bad Result Example

dex complete abc123 --result "Fixed the storage issue"

❌ Missing: What was actually implemented, how, what decisions were made

Subtask Description Example

Link subtasks to their parent and explain what this piece does specifically:

Part of auth system (parent: abc123). This subtask: JWT verification middleware.

What it does:
- Verify JWT signature and expiration on protected routes
- Extract user ID from token payload
- Attach user object to request
- Return 401 for invalid/expired tokens

Implementation:
- Create src/middleware/verify-token.ts
- Export verifyToken middleware function
- Use jsonwebtoken library
- Handle expired vs invalid token cases separately

Done when:
- Middleware function complete and working
- Unit tests cover valid/invalid/expired scenarios
- Integrated into auth routes in server.ts
- Parent task can use this to protect endpoints

Task Hierarchies

Guidance for organizing work into epics, tasks, and subtasks.

Three Levels

Maximum depth is 3 levels. Attempting to create a child of a subtask will fail.

When to Use Each Level

Single Task (No Hierarchy)

• Small feature (1-2 files, ~1 session)
• Work is atomic, no natural breakdown

Task with Subtasks

• Medium feature (3-5 files, 3-7 steps)
• Work naturally decomposes into discrete steps
• Subtasks could be worked on independently

Epic with Tasks

• Large initiative (multiple areas, many sessions)
• Work spans 5+ distinct tasks
• You want high-level progress tracking

Creating Hierarchies

# Create the epic
dex create "Add user authentication system" \
  --description "Full auth system with JWT tokens, password reset..."

# Create tasks under it (note the epic ID, e.g., abc123)
dex create --parent abc123 "Implement JWT token generation" \
  --description "Create token service with signing and verification..."

dex create --parent abc123 "Add password reset flow" \
  --description "Email-based password reset with secure tokens..."

# For complex tasks, add subtasks
dex create --parent def456 "Add token verification function" \
  --description "Verify JWT signature and expiration..."

Subtask Best Practices

Each subtask should be:

• Independently understandable: Clear on its own
• Linked to parent: Reference parent, explain how this piece fits
• Specific scope: What this subtask does vs what parent/siblings do
• Clear completion: Define "done" for this piece specifically

Decomposition Strategy

When faced with large tasks:

1. Assess scope: Is this epic-level (5+ tasks) or task-level (3-7 subtasks)? 2. Create parent task/epic with overall goal and context 3. Analyze and identify 3-7 logical children 4. Create children with specific contexts and boundaries 5. Work through systematically, completing with results 6. Complete parent with summary of overall implementation

Don't Over-Decompose

• 3-7 children per parent is usually right
• If you'd only have 1-2 subtasks, just make separate tasks
• If you need L3, restructure your breakdown

Viewing Hierarchies

dex list                    # Full tree view with all levels
dex list abc123             # Show epic abc123 and its subtree
dex show abc123             # Epic details with task/subtask counts
dex show def456             # Task details with breadcrumb path

Completion Rules

• A task cannot be completed while it has pending subtasks
• Complete all children before completing the parent
• Parent result should summarize the overall implementation

Verification Guide

Before marking any task complete, you MUST verify your work. Verification separates "I think it's done" from "it's actually done."

The Verification Process

1. Re-read the task description: What did you originally commit to do? 2. Check acceptance criteria: Does your implementation satisfy the "Done when" conditions? 3. Run relevant tests: Execute the test suite and document results 4. Test manually: Actually try the feature/change yourself 5. Compare with requirements: Does what you built match what was asked?

Strong vs Weak Verification

Strong Verification Examples

• ✅ "All 60 tests passing, build successful"
• ✅ "All 69 tests passing (4 new tests for middleware edge cases)"
• ✅ "Manually tested with valid/invalid/expired tokens - all cases work"

Weak Verification (Avoid)

• ❌ "Should work now" — "should" means not verified
• ❌ "Made the changes" — no evidence it works
• ❌ "Added tests" — did the tests pass? What's the count?
• ❌ "Fixed the bug" — what bug? Did you verify the fix?

Verification by Task Type

Cross-Reference Checklist

Before marking complete, verify all applicable items:

• [ ] Task name requirements met
• [ ] Description "Done when" criteria satisfied
• [ ] Tests passing (document count: "All X tests passing")
• [ ] Build succeeds (if applicable)
• [ ] Manual testing done (describe what you tested)
• [ ] No regressions introduced
• [ ] Edge cases considered (error handling, invalid input)
• [ ] Follow-up work identified (created new tasks if needed)

If you can't check all applicable boxes, the task isn't done yet.

Result Examples with Verification

Code Implementation

dex complete xyz789 --commit a1b2c3d --result "Implemented JWT middleware:

Implementation:
- Created src/middleware/verify-token.ts
- Separated 'expired' vs 'invalid' error codes

Verification:
- All 69 tests passing (4 new tests for edge cases)
- Manually tested with valid token: ✅ Access granted
- Manually tested with expired token: ✅ 401 with 'token_expired'
- Manually tested with invalid signature: ✅ 401 with 'invalid_token'"

Configuration/Infrastructure

dex complete abc456 --result "Added GitHub Actions workflow for CI:

Implementation:
- Created .github/workflows/ci.yml
- Jobs: lint, test, build with pnpm cache

Verification:
- Pushed to test branch, opened PR #123
- Workflow triggered automatically: ✅
- All jobs passed (lint: 0 errors, test: 69/69, build: success)
- Total run time: 2m 34s"

Refactoring

dex complete def123 --result "Refactored storage to one file per task:

Implementation:
- Split tasks.json into .dex/tasks/{id}.json files
- Added auto-migration from old format

Verification:
- All 60 tests passing (including 8 storage tests)
- Build successful
- Manually tested migration: old → new format ✅
- Confirmed git diff shows only changed tasks"