@pruddiman/dispatch 1.4.4 → 1.5.0-beta.07e10a8

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@pruddiman/dispatch",
-  "version": "1.4.4",
+  "version": "1.5.0-beta.07e10a8",
   "description": "AI agent orchestration CLI — parse markdown task files, dispatch each unit of work to code agents (OpenCode, GitHub Copilot, etc.), and commit results with conventional commits",
   "type": "module",
   "bin": {
     "dispatch": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsup",
@@ -27,7 +28,8 @@
     "orchestration",
     "dispatch",
     "tasks",
-    "markdown"
+    "markdown",
+    "beta"
   ],
   "license": "MIT",
   "repository": {
@@ -43,23 +45,33 @@
     "node": ">=20.12.0"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.63",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.98",
     "@azure/identity": "^4.13.0",
-    "@inquirer/prompts": "^8.3.0",
+    "@github/copilot-sdk": "^0.2.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@octokit/auth-oauth-device": "^7.1.5",
     "@octokit/rest": "^21.1.1",
-    "@openai/codex": "^0.1.0",
-    "@opencode-ai/sdk": "^1.2.10",
+    "@openai/codex-sdk": "^0.118.0",
+    "@opencode-ai/sdk": "^1.4.2",
     "azure-devops-node-api": "^14.1.0",
+    "better-sqlite3": "^12.8.0",
     "chalk": "^5.4.1",
     "commander": "^14.0.3",
     "glob": "^11.0.1",
-    "open": "^10.2.0"
+    "ink": "^6.0.0",
+    "ink-select-input": "^6.0.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "open": "^10.2.0",
+    "react": "^19.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@github/copilot-sdk": "^0.1.32",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.13.4",
+    "@types/react": "^19.0.0",
     "@vitest/coverage-v8": "^4.0.18",
+    "ink-testing-library": "^4.0.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.4.0",
     "typescript": "^5.7.3",

package/skills/dispatch/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: dispatch
+description: >
+  Orchestrate work using the Dispatch MCP server (@pruddiman/dispatch). Use when the
+  user wants to spec issues, dispatch tasks, plan execution order, manage
+  dependencies between issues, or run any dispatch operation. Covers correct
+  spec ordering, dependency analysis, and the spec-plan-execute pipeline.
+metadata:
+  author: pruddiman
+  version: "2.1.0"
+license: MIT
+---
+
+# Dispatch Orchestration
+
+Dispatch turns issues into working code: fetch work items → generate structured specs → plan and execute tasks in isolated AI sessions → commit and open PRs.
+
+**Pipeline:** Issues → `spec_generate` → Spec files → `dispatch_run` → Plan → Execute → Commit/PR
+
+Use MCP tools directly. Do not shell out to the `dispatch` CLI.
+
+## MCP Tool Reference
+
+| Category | Tool | What it does |
+|---|---|---|
+| **Spec** | `spec_generate` | Generate spec files from issue IDs, glob pattern, or inline text |
+| | `spec_list` | List spec files in `.dispatch/specs/` |
+| | `spec_read` | Read a spec file's contents |
+| | `spec_runs_list` | List recent spec generation runs |
+| | `spec_run_status` | Get status of a specific spec run by runId |
+| **Dispatch** | `dispatch_run` | Execute dispatch pipeline for one or more issues |
+| | `dispatch_dry_run` | Preview tasks without executing (synchronous) |
+| **Monitor** | `status_get` | Get run status and per-task details by runId |
+| | `runs_list` | List recent dispatch runs (filter by status) |
+| | `issues_list` | List open issues from the configured datasource |
+| | `issues_fetch` | Fetch full details for specific issues |
+| **Recovery** | `run_retry` | Re-run all failed tasks from a previous run |
+| | `task_retry` | Retry a single failed task by taskId |
+| **Config** | `config_get` | Read the current Dispatch configuration |
+
+## Async Pattern — runId + Polling
+
+`spec_generate` and `dispatch_run` are **fire-and-forget**: they return a `runId` immediately; progress arrives as logging notifications.
+
+**Always poll for completion before moving to the next step:**
+
+```
+# After spec_generate
+loop: status = spec_run_status({ runId }); break if status.status in ["completed","failed"]
+
+# After dispatch_run
+loop: status = status_get({ runId }); break if status.run.status in ["completed","failed"]
+```
+
+`dispatch_dry_run` is synchronous — returns results directly, no runId.
+
+## Pipeline Phases
+
+| Phase | When to use |
+|---|---|
+| `spec_generate` | Issue is vague/complex, needs task breakdown, or involves multiple agents. Skip if a good spec already exists. |
+| Planning (default) | Complex tasks, unfamiliar code, refactors. Skip with `noPlan: true` for mechanical/obvious changes. |
+| `dispatch_dry_run` | Always dry-run before dispatching an unfamiliar spec to verify task count and ordering. |
+
+## Spec Ordering — The Core Discipline
+
+**This is the most critical part of using Dispatch correctly.**
+
+### The Rule
+
+**Never spec an issue whose prerequisites have not been fully implemented and merged.**
+
+The spec agent explores the *current* codebase. If issue B depends on code that issue A creates, and A hasn't been executed yet, B's spec will be wrong — written against a codebase missing B's foundations. A spec that exists for A is not enough; A must be fully executed and its code present on disk.
+
+### Dependency Analysis
+
+Before speccing anything:
+
+1. `issues_list` → `issues_fetch` to read all issue descriptions.
+2. Map dependencies: if B imports or calls something A creates, B depends on A.
+3. Group into layers: Layer 0 = no deps. Layer 1 = depends on layer 0. Etc.
+4. Independent issues within a layer can be specced and executed concurrently.
+
+### Execution Pattern
+
+```
+Layer 0 (no deps):   spec_generate → poll → dispatch_run → poll
+                                                  ↓
+Layer 1 (needs 0):   spec_generate → poll → dispatch_run → poll
+                                                  ↓
+Layer 2 (needs 1):   spec_generate → poll → dispatch_run → poll
+```
+
+Spec layer N only after layer N-1 is **executed and complete** — not just specced.
+
+### Concrete Example
+
+```
+Issues: #10 user model, #11 user API (needs #10), #12 admin dashboard (needs #11)
+        #20 logging (independent),  #21 request tracing (needs #20)
+
+Layer 0: #10, #20  →  spec + dispatch together (concurrent, no prerequisites)
+Layer 1: #11, #21  →  spec + dispatch after layer 0 done (concurrent within layer)
+Layer 2: #12       →  spec + dispatch after layer 1 done
+```
+
+### Anti-Patterns
+
+```
+# BAD: speccing everything at once — #11's spec references code that doesn't exist yet
+spec_generate({ issues: "10,11,12,20,21" })
+
+# BAD: not waiting for spec before dispatch — spec may still be running
+rid = spec_generate({ issues: "42" }); dispatch_run({ issueIds: ["42"] })
+
+# BAD: speccing layer 1 before layer 0 is executed — spec alone is not enough
+spec_generate({ issues: "10" })
+spec_generate({ issues: "11" })   # WRONG: #10's code doesn't exist yet
+```
+
+### Pre-Spec Checklist
+
+Before calling `spec_generate` on any issue:
+
+1. What code does it depend on? (imports, APIs, schemas, utilities)
+2. Does that code exist in the codebase *right now*? (verify with grep/glob)
+3. If not — which issue creates it? Execute that issue first, fully.
+4. Are there other issues at the same dependency layer? Spec them together.
+
+## Task Ordering Inside Specs
+
+`spec_generate` tags tasks automatically. You do not write P/S/I tags — understand them to read generated specs:
+
+- `(P)` **Parallel-safe** — runs concurrently with adjacent `(P)` tasks
+- `(S)` **Serial/dependent** — waits for all prior tasks, then runs alone (caps the current group)
+- `(I)` **Isolated/barrier** — runs completely alone; used for validation steps (tests, lint, build)
+
+See [references/ordering-reference.md](references/ordering-reference.md) for the full grouping algorithm and edge cases.
+
+## References
+
+- [references/workflow-recipes.md](references/workflow-recipes.md) — single issue, multi-issue, retry, and feature-branch recipes
+- [references/ordering-reference.md](references/ordering-reference.md) — P/S/I grouping algorithm with walkthrough examples
+- [references/troubleshooting.md](references/troubleshooting.md) — symptom/cause/fix for common failures

package/skills/dispatch/references/ordering-reference.md

@@ -0,0 +1,215 @@
+# P/S/I Ordering Reference
+
+Detailed reference for Dispatch's task grouping algorithm and execution ordering.
+
+## The `groupTasksByMode()` Algorithm
+
+The algorithm in `src/parser.ts` converts a flat list of tagged tasks into ordered execution groups:
+
+```
+Input:  flat list of tasks, each with mode: "parallel" | "serial" | "isolated"
+Output: array of groups (Task[][]), executed sequentially
+```
+
+**Rules:**
+
+1. **Parallel `(P)`** — accumulate into the current group
+2. **Serial `(S)`** — append to the current group, then start a new empty group (acts as a "cap")
+3. **Isolated `(I)`** — flush any accumulated tasks as their own group, then create a solo group for the isolated task
+
+After processing all tasks, any remaining accumulated parallel tasks form a final group.
+
+## Walkthrough Examples
+
+### Example 1: Mixed modes
+
+```markdown
+- [ ] (P) Task A
+- [ ] (P) Task B
+- [ ] (S) Task C
+- [ ] (P) Task D
+- [ ] (P) Task E
+- [ ] (I) Task F
+- [ ] (P) Task G
+```
+
+**Step-by-step:**
+
+| Task | Mode | Action | Current group | Groups so far |
+|------|------|--------|--------------|---------------|
+| A | P | accumulate | [A] | [] |
+| B | P | accumulate | [A, B] | [] |
+| C | S | cap group | [] | [[A, B, C]] |
+| D | P | accumulate | [D] | [[A, B, C]] |
+| E | P | accumulate | [D, E] | [[A, B, C]] |
+| F | I | flush + solo | [] | [[A, B, C], [D, E], [F]] |
+| G | P | accumulate | [G] | [[A, B, C], [D, E], [F]] |
+| end | — | flush remaining | [] | [[A, B, C], [D, E], [F], [G]] |
+
+**Result:** `[[A, B, C], [D, E], [F], [G]]`
+
+**Execution:**
+1. A, B run concurrently → C runs (S caps the group, so C waits for A and B)
+2. D, E run concurrently
+3. F runs alone (isolated)
+4. G runs alone (only task in its group)
+
+### Example 2: All parallel
+
+```markdown
+- [ ] (P) Task A
+- [ ] (P) Task B
+- [ ] (P) Task C
+```
+
+**Result:** `[[A, B, C]]` — all three run concurrently in one group.
+
+### Example 3: All serial
+
+```markdown
+- [ ] (S) Task A
+- [ ] (S) Task B
+- [ ] (S) Task C
+```
+
+**Result:** `[[A], [B], [C]]` — each runs alone, sequentially.
+
+### Example 4: Parallel then isolated validation
+
+```markdown
+- [ ] (P) Implement feature module
+- [ ] (P) Write unit tests for feature
+- [ ] (P) Update documentation
+- [ ] (I) Run full test suite
+- [ ] (I) Run linter
+```
+
+**Result:** `[[module, tests, docs], [test suite], [linter]]`
+
+**Execution:**
+1. Module, tests, and docs all run concurrently
+2. Full test suite runs alone
+3. Linter runs alone
+
+### Example 5: Serial dependency chain
+
+```markdown
+- [ ] (P) Create database schema migration
+- [ ] (P) Add seed data script
+- [ ] (S) Run migration and seed the database
+- [ ] (P) Implement API endpoints using new schema
+- [ ] (P) Write API integration tests
+- [ ] (I) Run all tests
+```
+
+**Result:** `[[schema, seed, run migration], [endpoints, tests], [run all tests]]`
+
+**Execution:**
+1. Schema and seed created concurrently, then migration runs (S caps)
+2. Endpoints and tests written concurrently (safe — schema exists now)
+3. Full test suite runs alone
+
+### Example 6: Isolated as a phase gate
+
+```markdown
+- [ ] (P) Refactor module A
+- [ ] (P) Refactor module B
+- [ ] (I) Run tests to verify refactors
+- [ ] (P) Update module C (imports from A and B)
+- [ ] (P) Update module D (imports from A and B)
+- [ ] (I) Run final test suite
+```
+
+**Result:** `[[A, B], [verify], [C, D], [final tests]]`
+
+The first `(I)` acts as a phase gate — it verifies the refactors before dependent work begins.
+
+## Edge Cases
+
+### Single task
+
+```markdown
+- [ ] (P) Only task
+```
+
+**Result:** `[[Only task]]` — works fine regardless of mode prefix.
+
+### Serial followed immediately by parallel
+
+```markdown
+- [ ] (S) Setup step
+- [ ] (P) Task A
+- [ ] (P) Task B
+```
+
+**Result:** `[[Setup step], [A, B]]` — serial creates its own group, then parallel tasks accumulate.
+
+### Isolated at the very start
+
+```markdown
+- [ ] (I) Clean build artifacts
+- [ ] (P) Task A
+- [ ] (P) Task B
+```
+
+**Result:** `[[Clean], [A, B]]` — isolated runs first (no prior tasks to flush), then parallel group.
+
+### No mode prefix (defaults to serial)
+
+```markdown
+- [ ] Task without prefix
+- [ ] (P) Parallel task
+```
+
+**Result:** `[[no-prefix, parallel]]` — the untagged task is treated as serial, which caps the group after it. But since the parallel task follows, it starts a new group... Actually: the untagged task (serial) starts accumulating, the `(P)` task accumulates into the same group. Then `(S)` caps — but there's no `(S)`. The untagged task is serial, so it caps immediately: `[[no-prefix], [parallel]]`.
+
+**Takeaway:** Always tag explicitly. Untagged = serial = immediate group cap.
+
+## Common Patterns
+
+### The "implement then validate" pattern
+```markdown
+- [ ] (P) Implement feature X
+- [ ] (P) Implement feature Y
+- [ ] (I) Run tests
+```
+Best for: independent features that need a shared validation gate.
+
+### The "foundation then consumers" pattern
+```markdown
+- [ ] (S) Create shared utility/interface
+- [ ] (P) Consumer A uses the utility
+- [ ] (P) Consumer B uses the utility
+- [ ] (I) Run tests
+```
+Best for: creating something that multiple subsequent tasks depend on.
+
+### The "phased rollout" pattern
+```markdown
+- [ ] (P) Phase 1 task A
+- [ ] (P) Phase 1 task B
+- [ ] (I) Verify phase 1
+- [ ] (P) Phase 2 task A (depends on phase 1)
+- [ ] (P) Phase 2 task B (depends on phase 1)
+- [ ] (I) Verify phase 2
+```
+Best for: large changes that need intermediate verification.
+
+### The "all parallel" pattern
+```markdown
+- [ ] (P) Independent change A
+- [ ] (P) Independent change B
+- [ ] (P) Independent change C
+- [ ] (I) Run tests
+```
+Best for: maximum throughput when all tasks are truly independent.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Diagnostic | Fix |
+|---|---|---|---|
+| Task reads a file that doesn't exist | Task should be `(S)` not `(P)` — it ran before the task that creates the file | Check which prior task creates the file | Move the dependent task after its prerequisite with `(S)` |
+| File has conflicts or garbled content | Two `(P)` tasks in the same group wrote to the same file | Check task descriptions for shared file targets | Make one task `(S)` after the other |
+| Tasks run slower than expected | Too many `(S)` tags killing parallelism | Count `(P)` vs `(S)` tags — most tasks should be `(P)` | Audit each `(S)` for genuine dependency |
+| Isolated task fails | Prior parallel tasks didn't complete correctly | Check logs for failures in the preceding group | Fix the failing task; `(I)` correctly waited for it |
+| Wrong execution order | Misunderstanding of how `(S)` caps groups | Use `--dry-run` to preview grouping | Reorder tasks and re-tag |

package/skills/dispatch/references/troubleshooting.md

@@ -0,0 +1,34 @@
+# Troubleshooting
+
+## Dispatch / Spec Failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Spec references code that doesn't exist | Prerequisite issue hasn't been executed | Execute the prerequisite first, then call `spec_generate` again |
+| `dispatch_run` tasks fail — "file not found" or "symbol not found" | Task depends on code from a prior issue that isn't done | Execute issues in dependency order; re-spec if needed |
+| Spec quality is poor / tasks seem wrong | Spec was generated before prerequisite code existed | Execute prerequisites, then `spec_generate` the issue again |
+| Planner times out | Complex task or slow codebase exploration | Pass `planTimeout` (minutes) to `dispatch_run`, or `noPlan: true` for simpler tasks |
+| Too slow — everything sequential | Independent issues dispatched one at a time | Identify independent issues and spec/execute with `concurrency` > 1 |
+| `spec_run_status` shows `failed` | Spec pipeline error | Check `error` field in status response; re-run `spec_generate` |
+| `status_get` shows tasks stuck in `running` | Agent hung | Use `run_retry` to re-run; check logs via logging notifications |
+| Dispatched before spec finished | Polling skipped between `spec_generate` and `dispatch_run` | Always poll `spec_run_status` to `completed` before calling `dispatch_run` |
+
+## Task Ordering Issues (Inside Specs)
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Task reads a file that doesn't exist | Task ran in parallel before the task that creates the file | The task should be `(S)` not `(P)` — report to spec author or regenerate |
+| File has conflicts or garbled content | Two `(P)` tasks wrote to the same file concurrently | One task needs to be `(S)` after the other |
+| Tasks run slower than expected | Too many `(S)` tags killing parallelism | Audit each `(S)` — most tasks should be `(P)` |
+| Isolated task fails | Prior parallel tasks didn't complete correctly | Fix the failing task; `(I)` correctly waited for it |
+| Wrong execution order | Misunderstanding of how `(S)` caps groups | Use `dispatch_dry_run` to preview grouping before executing |
+
+## Dependency Order Violations
+
+These produce subtle, hard-to-debug failures. When in doubt, verify with `issues_fetch` and grep/glob the codebase before speccing.
+
+| Scenario | What goes wrong | Correct action |
+|---|---|---|
+| Specced B before A is executed | B's spec is written against missing code; tasks will fail or be wrong | Execute A fully, then `spec_generate` B |
+| Specced A and B together (B depends on A) | B's spec has no A code to reference | Spec them in separate layers |
+| Re-specced an issue after its dependency changed | Spec may now be stale | Re-spec again after verifying dependencies exist |

package/skills/dispatch/references/workflow-recipes.md

@@ -0,0 +1,105 @@
+# Workflow Recipes
+
+Common dispatch workflows. All async tools require polling — see SKILL.md for the polling pattern.
+
+## Single Issue — Full Pipeline
+
+```
+# 1. Generate spec
+rid_spec = spec_generate({ issues: "42" })
+poll spec_run_status({ runId: rid_spec }) until completed
+
+# 2. Review the spec (optional but recommended)
+spec_list({})
+spec_read({ file: "42-my-issue.md" })
+
+# 3. Preview tasks (optional but recommended for unfamiliar specs)
+dispatch_dry_run({ issueIds: ["42"] })
+
+# 4. Execute
+rid_run = dispatch_run({ issueIds: ["42"] })
+poll status_get({ runId: rid_run }) until completed
+```
+
+## Multiple Independent Issues
+
+```
+# Spec all at once (safe — no dependencies between them)
+rid_spec = spec_generate({ issues: "42,43,44" })
+poll spec_run_status({ runId: rid_spec }) until completed
+
+# Execute concurrently
+rid_run = dispatch_run({ issueIds: ["42", "43", "44"], concurrency: 3 })
+poll status_get({ runId: rid_run }) until completed
+```
+
+## Dependent Issue Chain
+
+```
+# Layer 0 — no dependencies
+rid_s0 = spec_generate({ issues: "42" })
+poll spec_run_status({ runId: rid_s0 }) until completed
+rid_r0 = dispatch_run({ issueIds: ["42"] })
+poll status_get({ runId: rid_r0 }) until completed
+
+# Layer 1 — safe now that #42 is implemented and its code exists
+rid_s1 = spec_generate({ issues: "43" })
+poll spec_run_status({ runId: rid_s1 }) until completed
+rid_r1 = dispatch_run({ issueIds: ["43"] })
+poll status_get({ runId: rid_r1 }) until completed
+```
+
+## Regenerate a Spec (Respec)
+
+```
+# Call spec_generate again — it overwrites the existing spec file
+rid = spec_generate({ issues: "42" })
+poll spec_run_status({ runId: rid }) until completed
+```
+
+Use this when prerequisite code has changed or the original spec was generated too early.
+
+## Skip Planning (Simple Tasks)
+
+```
+rid = dispatch_run({ issueIds: ["42"], noPlan: true })
+poll status_get({ runId: rid }) until completed
+```
+
+Good for: typo fixes, config changes, adding a single obvious field.
+
+## From Inline Description (No Issue)
+
+```
+rid = spec_generate({ issues: "add dark mode toggle to settings page" })
+poll spec_run_status({ runId: rid }) until completed
+# then dispatch as normal
+```
+
+## Retry Failed Tasks
+
+```
+# Inspect the failure
+status = status_get({ runId: "abc-123" })
+
+# Retry all failures in the run
+rid_retry = run_retry({ runId: "abc-123" })
+poll status_get({ runId: rid_retry }) until completed
+
+# Or retry a single specific task
+rid_task = task_retry({ runId: "abc-123", taskId: "42:3" })
+poll status_get({ runId: rid_task }) until completed
+```
+
+## Check Recent Activity
+
+```
+runs_list({})                        # all recent dispatch runs
+runs_list({ status: "failed" })      # only failures
+runs_list({ status: "running" })     # currently in-progress
+spec_runs_list({})                   # recent spec generation runs
+```
+
+## Feature Branch (Group Multiple Issues into One PR)
+
+Run dispatch with `--feature` via the CLI, or dispatch issues sequentially and they'll be grouped if you use a shared branch. Consult the Dispatch README for the `--feature` flag usage.