dex

Files (7)

• SKILL.md
• cli-reference.md
• epic-examples.md
• evals.json · evals/
• examples.md
• hierarchies.md
• verification.md

SKILL.md (first lines)

# Agent Coordination with dex

## Command Invocation

Use `dex` directly via bash for all commands:

```bash
dex <command>
```

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

```bash
dex create "Short name" --description "Full implementation context" --blocked-by <other-id>
```

Description should include: what needs to be done, why, implementation approach, and acceptance criteria. See [examples.md](examples.md) for good/bad examples.

### List and View Tasks

```bash
dex list                  # Pending tasks
dex list --ready          # Unblocked tasks
dex show <id>             # Full details
```

### Complete a Task

```bash
dex complete <id> --result "What was accomplished" --commit <sha>
```

**Always verify before completing.** Results must include evidence: test counts, build status, manual testing outcomes. See [verification.md](verification.md) for the full checklist.

### Edit and Delete

```bash
dex edit <id> --description "Updated description" --blocked-by <other-id>
dex delete <id>
```

For full CLI reference including blockers, see [cli-reference.md](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:

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

From Jeroen-G/skills, MIT.

More from Jeroen-G/skills