fix(skill): Update field names to match current CLI (#86)

The skill documentation was using old field names that don't match the
actual CLI, causing agents to execute invalid commands.

Changes:
- `description` → `name` (one-line summary, positional or -n flag)
- `context` → `description` (full details, -d flag)
- Update all command examples to use correct syntax
- Fix task file format example in cli-reference.md

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: kschrader

plugins/dex/skills/dex/SKILL.md

@@ -17,8 +17,8 @@ command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"
 
 Dex tasks are **tickets** - structured artifacts with comprehensive context:
 
-- **Description**: One-line summary (issue title)
-- **Context**: Full background, requirements, approach (issue body)
+- **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?"
@@ -59,10 +59,10 @@ Use **dex** for persistent work. Use built-in task tools for ephemeral in-sessio
 ### Create a Task
 
 ```bash
-dex create -d "Short description" --context "Full implementation context"
+dex create "Short name" --description "Full implementation context"
 ```
 
-Context should include: what needs to be done, why, implementation approach, and acceptance criteria. See [examples.md](examples.md) for good/bad examples.
+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
 
@@ -83,20 +83,20 @@ dex complete <id> --result "What was accomplished" --commit <sha>
 ### Edit and Delete
 
 ```bash
-dex edit <id> --context "Updated context"
+dex edit <id> --description "Updated description"
 dex delete <id>
 ```
 
 For full CLI reference including blockers, see [cli-reference.md](cli-reference.md).
 
-## Understanding Task Context
+## Understanding Task Fields
 
 Tasks have two text fields:
 
-- **Description**: Brief one-line summary (shown in `dex list`)
-- **Context**: Full details - requirements, approach, acceptance criteria (shown with `--full`)
+- **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 context may be truncated. The CLI will hint at `--full` if there's more content.
+When you run `dex show <id>`, the description may be truncated. The CLI will hint at `--full` if there's more content.
 
 ### Gathering Context
 
@@ -138,7 +138,7 @@ Three levels: **Epic** (large initiative) → **Task** (significant work) → **
 
 ```bash
 # Create subtask under parent
-dex create --parent <id> -d "Description" --context "..."
+dex create --parent <id> "Subtask name" --description "..."
 ```
 
 For detailed hierarchy guidance, see [hierarchies.md](hierarchies.md).
@@ -168,7 +168,7 @@ Check `dex show <id>` for GitHub issue info before committing. The "(via parent)
 ## Best Practices
 
 1. **Right-size tasks**: Completable in one focused session
-2. **Clear completion criteria**: Context should define "done"
+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

plugins/dex/skills/dex/cli-reference.md

@@ -5,13 +5,13 @@ Full command reference for dex. For basic usage, see SKILL.md.
 ## Create a Task
 
 ```bash
-dex create -d "Short description" --context "Full implementation context"
+dex create "Task name" --description "Full implementation details"
 ```
 
 Options:
 
-- `-d, --description` (required): One-line summary
-- `--context` (required): Full implementation details
+- `<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)
@@ -24,7 +24,7 @@ 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 description/context
+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).
@@ -56,7 +56,7 @@ This captures commit SHA, message, and branch automatically.
 ## Edit a Task
 
 ```bash
-dex edit <id> -d "Updated description" --context "Updated context"
+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
 ```
@@ -75,7 +75,7 @@ Use blocking dependencies to enforce task ordering:
 
 ```bash
 # Create a task that depends on another
-dex create -d "Deploy to production" --context "..." --blocked-by abc123
+dex create "Deploy to production" --description "..." --blocked-by abc123
 
 # Add a blocker to an existing task
 dex edit xyz789 --add-blocker abc123
@@ -121,14 +121,12 @@ Override with `--storage-path` or `DEX_STORAGE_PATH` env var.
 {
   "id": "abc123",
   "parent_id": null,
-  "description": "One-line summary",
-  "context": "Full implementation details...",
+  "name": "One-line summary",
+  "description": "Full implementation details...",
   "priority": 1,
   "completed": false,
   "result": null,
-  "blockedBy": ["xyz789"],
-  "blocks": ["def456"],
-  "children": [],
+  "blocked_by": ["xyz789"],
   "created_at": "2026-01-01T00:00:00.000Z",
   "updated_at": "2026-01-01T00:00:00.000Z",
   "completed_at": null

plugins/dex/skills/dex/examples.md

@@ -1,19 +1,20 @@
 # Examples
 
-Good and bad examples for writing task context and results.
+Good and bad examples for writing task descriptions and results.
 
-## Writing Context
+## Writing Descriptions
+
+Descriptions should include everything needed to do the work without asking questions:
 
-Context 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 Context Example
+### Good Description Example
 
 ```bash
-dex create -d "Migrate storage to one file per task" \
-  --context "Change storage format for git-friendliness:
+dex create "Migrate storage to one file per task" \
+  --description "Change storage format for git-friendliness:
 
 Structure:
 .dex/
@@ -46,17 +47,18 @@ Benefits:
 
 Notice: States the goal, shows the structure, lists specific implementation steps, and explains benefits. Someone could pick this up without asking questions.
 
-### Bad Context Example
+### Bad Description Example
 
 ```bash
-dex create -d "Add auth" --context "Need to add authentication"
+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)
@@ -95,7 +97,7 @@ dex complete abc123 --result "Fixed the storage issue"
 
 ❌ Missing: What was actually implemented, how, what decisions were made
 
-## Subtask Context Example
+## Subtask Description Example
 
 Link subtasks to their parent and explain what this piece does specifically:
 

plugins/dex/skills/dex/hierarchies.md

@@ -4,26 +4,29 @@ Guidance for organizing work into epics, tasks, and subtasks.
 
 ## Three Levels
 
-| Level | Name | Purpose | Example |
-|-------|------|---------|---------|
-| L0 | **Epic** | Large initiative (5+ tasks) | "Add user authentication system" |
-| L1 | **Task** | Significant work item | "Implement JWT middleware" |
-| L2 | **Subtask** | Atomic implementation step | "Add token verification function" |
+| Level | Name        | Purpose                     | Example                           |
+| ----- | ----------- | --------------------------- | --------------------------------- |
+| L0    | **Epic**    | Large initiative (5+ tasks) | "Add user authentication system"  |
+| L1    | **Task**    | Significant work item       | "Implement JWT middleware"        |
+| L2    | **Subtask** | Atomic implementation step  | "Add token verification function" |
 
 **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
@@ -32,24 +35,25 @@ Guidance for organizing work into epics, tasks, and subtasks.
 
 ```bash
 # Create the epic
-dex create -d "Add user authentication system" \
-  --context "Full auth system with JWT tokens, password reset..."
+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 -d "Implement JWT token generation" \
-  --context "Create token service with signing and verification..."
+dex create --parent abc123 "Implement JWT token generation" \
+  --description "Create token service with signing and verification..."
 
-dex create --parent abc123 -d "Add password reset flow" \
-  --context "Email-based password reset with secure tokens..."
+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 -d "Add token verification function" \
-  --context "Verify JWT signature and expiration..."
+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

plugins/dex/skills/dex/verification.md

@@ -4,7 +4,7 @@ Before marking any task complete, you MUST verify your work. Verification separa
 
 ## The Verification Process
 
-1. **Re-read the task context**: What did you originally commit to do?
+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
@@ -13,32 +13,34 @@ Before marking any task complete, you MUST verify your work. Verification separa
 ## 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
 
-| Task Type | How to Verify |
-|-----------|---------------|
-| Code changes | Run full test suite, document passing count |
-| New features | Run tests + manual testing of functionality |
-| Configuration | Test the config works (run commands, check workflows) |
+| Task Type     | How to Verify                                           |
+| ------------- | ------------------------------------------------------- |
+| Code changes  | Run full test suite, document passing count             |
+| New features  | Run tests + manual testing of functionality             |
+| Configuration | Test the config works (run commands, check workflows)   |
 | Documentation | Verify examples work, links resolve, formatting renders |
-| Refactoring | Confirm tests still pass, no behavior changes |
+| Refactoring   | Confirm tests still pass, no behavior changes           |
 
 ## Cross-Reference Checklist
 
 Before marking complete, verify all applicable items:
 
-- [ ] Task description requirements met
-- [ ] Context "Done when" criteria satisfied
+- [ ] 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)