dex

Files (6)

• SKILL.md
• cli-reference.md
• epic-examples.md
• examples.md
• hierarchies.md
• verification.md

SKILL.md (first lines)

# Agent Coordination with dex

## Command Invocation

Use `dex` directly for all commands. If not on PATH, use `npx @zeeg/dex` instead.

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

```bash
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](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>
```

**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](verification.md) for the full checklist.

### Edit and Delete

```bash
dex edit <id> --description "Updated description"
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:

From andrepontesmelo/dsh-suite, MIT.

More from andrepontesmelo/dsh-suite