@pruddiman/dispatch 0.0.1 → 1.2.1

package/README.md

@@ -1,308 +1,261 @@
-# dispatch
+# Dispatch
 
-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.
+AI agent orchestration CLI — parse work items from GitHub Issues, Azure DevOps, or local markdown files, dispatch each unit of work to a coding agent (OpenCode, GitHub Copilot, Claude Code, or OpenAI Codex), and commit results with conventional commits.
 
-## Why dispatch?
+## What it does
 
-Manual orchestration of AI coding agents is tedious when a project has many small, well-defined units of work. dispatch solves three problems:
+Dispatch closes the gap between issue trackers and AI coding agents. It:
 
-- **Context isolation** — each task runs in a fresh agent session so context from one task does not leak into another.
-- **Precision through planning** — an optional two-phase pipeline lets a read-only planner agent explore the codebase first, producing a focused execution plan that the executor agent follows.
-- **Automated record-keeping** — after each task, the markdown file is updated and a conventional commit is created, giving a clean, reviewable git history tied directly to the original task list.
-
-The tool is backend-agnostic: it supports multiple issue trackers via a datasource abstraction and multiple AI runtimes via a provider abstraction, letting teams use their existing tools without lock-in.
-
-## Key Features
-
-- **Backend-agnostic** provider and datasource abstractions — no vendor lock-in
-- **Two-phase planner-executor pipeline** — optional read-only planner explores the codebase before the executor makes changes (`--no-plan` skips planning)
-- **Markdown as source of truth** — task files use `- [ ]` checkbox syntax with `(P)`arallel, `(S)`erial, and `(I)`solated execution mode prefixes
-- **Automatic conventional commits** — commit type (feat, fix, docs, refactor, etc.) is inferred from task text
-- **Real-time TUI dashboard** — terminal UI with spinner, progress bar, and per-task status tracking
-- **Three-tier configuration** — CLI flags > project-local config file (`.dispatch/config.json`) > defaults
-- **Configurable concurrency** — control parallel task execution per batch
-
-## Supported Backends
-
-### Providers (AI Agent Runtimes)
-
-| Provider | SDK | Prompt Model |
-|----------|-----|-------------|
-| OpenCode | `@opencode-ai/sdk` | Async — fire-and-forget + SSE event stream |
-| GitHub Copilot | `@github/copilot-sdk` | Synchronous — blocking request/response |
-
-### Datasources (Issue Trackers)
-
-| Datasource | Tool | Auth |
-|------------|------|------|
-| GitHub Issues | `gh` CLI | `gh auth login` |
-| Azure DevOps Work Items | `az` CLI | `az login` |
-| Local Markdown | Filesystem | None |
+1. **Fetches work items** from GitHub Issues, Azure DevOps Work Items, or local markdown specs.
+2. **Generates structured specs** via an AI agent that explores the codebase and produces task lists.
+3. **Plans and executes** each task in isolated AI sessions, with an optional two-phase planner-then-executor pipeline.
+4. **Manages the git lifecycle** — branching, committing with conventional commit messages, pushing, and opening pull requests that auto-close the originating issue.
 
 ## Prerequisites
 
-### Node.js and npm
-
-Install [Node.js](https://nodejs.org/) **>= 20.12.0** (npm is included). Verify your installation:
+### Node.js
 
-```sh
-node --version   # must be >= 20.12.0
-```
-
-### AI Agent Runtime
+Node.js **>= 20.12.0** is required.
 
-At least one AI agent runtime must be installed and authenticated with a default model configured. dispatch cannot function without a provider backend.
+### AI provider (choose one)
 
-**OpenCode**
+**OpenCode** (default):
 
 ```sh
-# Install
+# Install OpenCode
 curl -fsSL https://opencode.ai/install | bash
 # or: npm install -g opencode-ai
-```
-
-Launch `opencode` and run the `/connect` command to configure your LLM provider. Then verify:
 
-```sh
-opencode --version
+# Configure an LLM provider (Anthropic, OpenAI, etc.)
+opencode
+# then run: /connect
 ```
 
-See [OpenCode backend docs](./docs/provider-system/opencode-backend.md) for full setup options.
-
-**GitHub Copilot**
-
-Requires an active [GitHub Copilot subscription](https://github.com/features/copilot/plans).
+**GitHub Copilot**:
 
 ```sh
-# Install
-npm install -g @github/copilot
-```
+# Requires an active GitHub Copilot subscription
 
-Launch `copilot` and follow the `/login` prompt to authenticate. Then verify:
+# Install the Copilot CLI
+npm install -g @github/copilot     # requires Node.js 22+
+# or: brew install copilot-cli
+# or: winget install GitHub.Copilot
 
-```sh
-copilot --version
+# Authenticate
+copilot
+# then run: /login
 ```
 
-See [Copilot backend docs](./docs/provider-system/copilot-backend.md) for full setup options.
-
-## Installation
+For CI environments, set one of these environment variables instead of logging in interactively:
+- `COPILOT_GITHUB_TOKEN` — GitHub PAT with **Copilot Requests** permission (highest priority)
+- `GH_TOKEN` — standard GitHub CLI token
+- `GITHUB_TOKEN` — commonly used in CI
 
-```bash
-npm install -g @pruddiman/dispatch
-```
+**Claude Code** (`--provider claude`):
 
-Or run directly without installing:
+```sh
+# Install Claude Code CLI
+npm install -g @anthropic-ai/claude-code
 
-```bash
-npx @pruddiman/dispatch
+# Authenticate
+claude login
+# or set ANTHROPIC_API_KEY in your environment
 ```
 
-## Quick Start
-
-dispatch operates as a three-stage pipeline:
-
-### 1. Generate specs from issues
+Default model: `claude-sonnet-4`. Available models: `claude-sonnet-4`, `claude-sonnet-4-5`, `claude-opus-4-6`, `claude-haiku-3-5`.
 
-Fetch issues from your tracker and generate structured markdown specs with task checkboxes:
+**OpenAI Codex** (`--provider codex`):
 
-```bash
-# From issue numbers
-dispatch --spec 42,43,44
-
-# From local markdown files using a glob pattern
-dispatch --spec "drafts/*.md"
+```sh
+# Install the Codex CLI
+npm install -g @openai/codex
 
-# From an inline text description
-dispatch --spec "add dark mode toggle to settings page"
+# Authenticate via environment variable
+export OPENAI_API_KEY=sk-...
 ```
 
-This creates spec files in `.dispatch/specs/` (e.g., `42-add-auth.md`) with `- [ ]` task items.
+Default model: `o4-mini`. Available models: `o4-mini`, `o3-mini`, `codex-mini-latest`.
 
-To regenerate existing specs, use `--respec`:
+### Issue tracker (choose based on your repo)
 
-```bash
-# Regenerate all existing specs
-dispatch --respec
+**GitHub** (`--source github`):
 
-# Regenerate specs for specific issues
-dispatch --respec 42,43,44
+```sh
+# Install the GitHub CLI
+# https://cli.github.com/
 
-# Regenerate specs matching a glob pattern
-dispatch --respec "specs/*.md"
+gh auth login
 ```
 
-### 2. Execute tasks
+**Azure DevOps** (`--source azdevops`):
 
-Run the generated specs through the plan-and-execute pipeline:
+```sh
+# Install the Azure CLI
+# https://learn.microsoft.com/en-us/cli/azure/install-azure-cli
 
-```bash
-dispatch ".dispatch/specs/*.md"
+az login
+az extension add --name azure-devops
 ```
 
-For each task, dispatch will:
-1. **Plan** — a read-only planner agent explores the codebase and produces a detailed execution plan
-2. **Execute** — an executor agent follows the plan to make code changes
-3. **Commit** — changes are staged and committed with an inferred conventional commit message
-4. **Mark complete** — the `- [ ]` checkbox is updated to `- [x]` in the source file
+**Local markdown** (`--source md`): No external tools or authentication required.
 
-### 3. Fix failing tests
+## Installation
 
-Run tests and automatically fix failures via an AI agent:
+```sh
+# Global install — adds `dispatch` to PATH
+npm install -g @pruddiman/dispatch
 
-```bash
-dispatch --fix-tests
-```
+# Run without installing
+npx @pruddiman/dispatch
 
-### Common options
-
-```bash
-dispatch --no-plan "tasks.md"          # Skip the planning phase
-dispatch --no-branch "tasks.md"        # Skip branch creation, push, and PR lifecycle
-dispatch --provider copilot "tasks.md" # Use GitHub Copilot instead of OpenCode
-dispatch --source github "tasks.md"    # Explicitly set the datasource
-dispatch --concurrency 3 "tasks.md"    # Run up to 3 tasks in parallel
-dispatch --server-url http://localhost:3000 "tasks.md"  # Use a running provider server
-dispatch --plan-timeout 15 "tasks.md"  # Set planning timeout to 15 minutes
-dispatch --plan-retries 2 "tasks.md"   # Retry planning up to 2 times
-dispatch --output-dir ./my-specs --spec 42  # Custom output directory for specs
-dispatch --verbose "tasks.md"          # Show detailed debug output
+# Local project install
+npm install --save-dev @pruddiman/dispatch
+npx dispatch
 ```
 
-> **Concurrency auto-scaling:** When `--concurrency` is not specified, dispatch
-> automatically computes a safe default using `min(cpuCount, freeMemMB / 500)`,
-> with a minimum of 1. Each concurrent agent process is assumed to consume ~500 MB
-> of memory.
-
-## Configuration
-
-dispatch uses a three-tier configuration system: CLI flags > project-local config file (`.dispatch/config.json`) > defaults.
-
-### Interactive configuration
+## Quick start
 
-```bash
+```sh
+# Run interactive configuration wizard (first-time setup)
 dispatch config
-```
-
-Running `dispatch config` launches an interactive wizard that guides you through viewing, setting, and resetting your configuration.
-
-Valid config keys: `provider`, `model`, `concurrency`, `source`, `org`, `project`, `workItemType`, `serverUrl`, `planTimeout`, `planRetries`.
 
-- **`model`** — AI model override in provider-specific format (e.g. `"claude-sonnet-4-5"` for Copilot, `"anthropic/claude-sonnet-4"` for OpenCode). When omitted the provider uses its default.
-- **`workItemType`** — Azure DevOps work item type (e.g. `"User Story"`, `"Bug"`). Only relevant when using the `azdevops` datasource.
+# Dispatch all open issues to AI agents
+dispatch
 
-## Requirements
+# Dispatch specific issues
+dispatch 42 43 44
 
-| Requirement | Version | Notes |
-|-------------|---------|-------|
-| Node.js | >= 20.12.0 | Required — ESM-only runtime |
-| git | Any | Required — auto-detection, conventional commits |
-| `gh` CLI | Any | Optional — required for GitHub datasource |
-| `az` CLI + azure-devops extension | Any | Optional — required for Azure DevOps datasource |
-| OpenCode or GitHub Copilot | Varies | At least one AI agent runtime required |
+# Dry run — list tasks without executing
+dispatch --dry-run
 
-## Development
+# Use GitHub Copilot instead of OpenCode
+dispatch --provider copilot
 
-```bash
-git clone https://github.com/PatrickRuddiman/Dispatch.git
-cd Dispatch
-npm install
-npm run build        # Build with tsup
-npm test             # Run tests with Vitest
-npm run typecheck    # Type-check with tsc --noEmit
+# Generate specs from issues (before dispatching)
+dispatch --spec 42,43
 ```
 
-Additional commands:
+## Pipeline modes
 
-```bash
-npm run dev          # Watch mode build
-npm run test:watch   # Watch mode tests
-```
-
-## Troubleshooting
-
-### "Could not detect datasource from git remote"
+| Mode | Flag | Description |
+|------|------|-------------|
+| **Dispatch** | *(default)* | Plan and execute tasks; manage full git lifecycle |
+| **Spec generation** | `--spec` / `--respec` | Convert issues into structured markdown spec files |
+| **Fix tests** | `--fix-tests` | Detect and auto-fix failing tests via AI |
 
-dispatch auto-detects whether to use GitHub or Azure DevOps by inspecting your git remote URL. If the remote does not match a known pattern (e.g., no remote configured, or a self-hosted URL), detection falls back to local markdown mode.
+## Task files
 
-**Fix:** pass `--source` explicitly:
+Dispatch reads work items from markdown files with `- [ ] ...` checkbox syntax:
 
-```sh
-dispatch --source github "tasks.md"
-dispatch --source azdevops "tasks.md"
-```
+```markdown
+# My Feature
 
-### Provider binary not found
-
-dispatch requires a provider runtime (`opencode` or `copilot`) to be installed and on your `PATH`. If the binary is missing, the provider will fail to start.
-
-**Verify installation:**
-
-```sh
-opencode --version
-copilot --version
+- [ ] (P) Add the login endpoint
+- [ ] (P) Write unit tests for the login endpoint
+- [ ] (S) Update the API documentation
 ```
 
-If not installed, see [OpenCode setup](./docs/provider-system/opencode-backend.md) or [Copilot setup](./docs/provider-system/copilot-backend.md).
+Each unchecked item is dispatched to an AI agent. An optional mode prefix controls execution batching:
 
-### Planning timeout exceeded
+| Prefix | Mode | Behavior |
+|--------|------|----------|
+| `(P)` | Parallel | Tasks run concurrently (up to `--concurrency`) |
+| `(S)` | Serial | Tasks run one at a time |
+| `(I)` | Isolated | Each task runs in a dedicated worktree |
 
-The planner phase has a default timeout of **10 minutes** per attempt. If the planner does not finish in time, dispatch retries up to `maxPlanAttempts` times (default: 1 retry) before failing the task.
+Tasks are marked `[x]` when complete. Rerunning dispatch skips already-completed tasks.
 
-**Fix:** increase the timeout or retries:
-
-```sh
-dispatch --plan-timeout 20 "tasks.md"   # 20-minute timeout
-dispatch --plan-retries 3 "tasks.md"    # Retry planning up to 3 times
-```
-
-Both values can also be set in `.dispatch/config.json` via the `planTimeout` and `planRetries` keys.
-
-### Branch creation failed
-
-dispatch creates a git branch per issue. This can fail if:
-
-- You lack write permissions to the repository.
-- A branch with the computed name already exists locally or on the remote.
+## Configuration
 
-**Fix:** delete the conflicting branch or use `--no-branch` to skip branch creation entirely:
+Dispatch uses three-tier configuration: CLI flags override config file values, which override hardcoded defaults.
 
 ```sh
-dispatch --no-branch "tasks.md"
+# Interactive wizard — guided setup for core AI settings (provider/model/source)
+dispatch config
 ```
 
-### "No unchecked tasks found"
+Config is stored at `.dispatch/config.json` (relative to the working directory where you run `dispatch`):
 
-dispatch looks for unchecked markdown checkboxes in the `## Tasks` section. Tasks must use the exact format `- [ ]` (hyphen, space, open bracket, space, close bracket) with a space inside the brackets.
-
-**Common mistakes:**
-
-```md
-- [] task     # wrong — missing space inside brackets
-- [x] task    # already checked — dispatch skips these
-* [ ] task    # wrong — use - not *
+```json
+{
+  "provider": "copilot",
+  "model": "claude-sonnet-4-5",
+  "source": "github",
+  "testTimeout": 60
+}
 ```
 
-**Correct format:**
+| Key | Description |
+|-----|-------------|
+| `provider` | AI backend: `opencode` (default), `copilot`, `claude`, or `codex` |
+| `model` | Model to use when spawning agents (provider-specific format) |
+| `source` | Issue tracker: `github`, `azdevops`, or `md` |
+| `testTimeout` | Test execution timeout in seconds (default: 60) |
+
+## Options reference
+
+### Dispatch mode
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `<issue-id...>` | *(all open)* | Issue IDs to dispatch |
+| `--provider <name>` | `opencode` | AI backend (`opencode`, `copilot`, `claude`, `codex`) |
+| `--source <name>` | *(auto-detected)* | Datasource (`github`, `azdevops`, `md`) |
+| `--dry-run` | `false` | List tasks without executing |
+| `--no-plan` | `false` | Skip planner phase, execute directly |
+| `--no-branch` | `false` | Skip branch/push/PR lifecycle |
+| `--concurrency <n>` | *(cpu/memory)* | Max parallel dispatches |
+| `--plan-timeout <min>` | `10` | Planning timeout in minutes |
+| `--plan-retries <n>` | `1` | Retries after planning timeout |
+| `--server-url <url>` | *(none)* | Connect to a running provider server |
+| `--cwd <dir>` | `process.cwd()` | Working directory |
+| `--verbose` | `false` | Show detailed debug output |
+
+### Spec mode
+
+| Option | Description |
+|--------|-------------|
+| `--spec <values...>` | Issue numbers, glob pattern, or description. Activates spec mode. |
+| `--respec [values...]` | Regenerate existing specs. Pass no args to regenerate all. |
+| `--source <name>` | Datasource override (auto-detected if omitted) |
+| `--output-dir <dir>` | Output directory for spec files (default: `.dispatch/specs`) |
+| `--org <url>` | Azure DevOps organization URL (required for `azdevops`) |
+| `--project <name>` | Azure DevOps project name (required for `azdevops`) |
+
+## Datasource auto-detection
+
+When `--source` is not provided, Dispatch inspects the git `origin` remote URL:
+
+| Remote URL contains | Detected source |
+|---------------------|----------------|
+| `github.com` | `github` |
+| `dev.azure.com` | `azdevops` |
+| `visualstudio.com` | `azdevops` |
+
+For local-only workflows, pass `--source md` explicitly.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All tasks completed successfully |
+| `1` | One or more tasks failed, or a fatal error occurred |
+| `130` | SIGINT (Ctrl+C) |
+| `143` | SIGTERM |
 
-```md
-- [ ] task description
-- [ ] (P) parallel task description
-```
+## Documentation
 
-## Error Handling & Recovery
+Full documentation is in the [`docs/`](docs/) directory:
 
-- **Batch failure isolation** — when a task fails, other tasks in the same batch continue executing. Failed tasks are tracked and reported in the final summary (e.g., `Done — 5 completed, 1 failed`).
-- **No run resumption** — runs cannot currently be resumed after interruption. Re-running will re-process all unchecked (`- [ ]`) tasks; tasks already marked complete (`- [x]`) in the source file are skipped.
-- **`--dry-run` scope** — `--dry-run` covers task discovery and parsing only. It does not trigger spec generation, planning, or execution.
+- [Architecture Overview](docs/architecture.md)
+- [CLI & Orchestration](docs/cli-orchestration/overview.md)
+- [Datasource System](docs/datasource-system/overview.md)
+- [Provider System](docs/provider-system/provider-overview.md)
+- [Task Parsing](docs/task-parsing/overview.md)
+- [Planning & Dispatch](docs/planning-and-dispatch/overview.md)
+- [Spec Generation](docs/spec-generation/overview.md)
+- [Testing](docs/testing/overview.md)
 
 ## License
 
 MIT
-
-## Documentation
-
-For comprehensive documentation, see the [`docs/`](./docs/) directory:
-
-- **[Documentation Index](./docs/index.md)** — entry point with key concepts and navigation guide
-- **[Architecture Overview](./docs/architecture.md)** — system topology, pipeline flows, design decisions, and component index