@pruddiman/dispatch 1.4.2 → 1.4.4

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+> **Note:** **Claude Code** (`--provider claude`) and **OpenAI Codex** (`--provider codex`) are largely untested. Expect rough edges and potential failures when using these providers.
+
 ## What it does
 
 Dispatch closes the gap between issue trackers and AI coding agents. It:
@@ -76,26 +78,9 @@ export OPENAI_API_KEY=sk-...
 
 Default model: `o4-mini`. Available models: `o4-mini`, `o3-mini`, `codex-mini-latest`.
 
-### Issue tracker (choose based on your repo)
-
-**GitHub** (`--source github`):
+### Issue tracker
 
-```sh
-# Install the GitHub CLI
-# https://cli.github.com/
-
-gh auth login
-```
-
-**Azure DevOps** (`--source azdevops`):
-
-```sh
-# Install the Azure CLI
-# https://learn.microsoft.com/en-us/cli/azure/install-azure-cli
-
-az login
-az extension add --name azure-devops
-```
+**GitHub** (`--source github`), **Azure DevOps** (`--source azdevops`): No external CLI tools required — Dispatch authenticates directly via browser-based OAuth device flow. See [Authentication](#authentication) below.
 
 **Local markdown** (`--source md`): No external tools or authentication required.
 
@@ -135,15 +120,43 @@ dispatch --provider copilot
 
 # Generate specs from issues (before dispatching)
 dispatch --spec 42,43
+
+# Generate a spec from an inline text description
+dispatch --spec "add dark mode toggle to settings page"
+
+# Regenerate all existing specs
+dispatch --respec
+
+# Group issues into a single feature branch and PR
+dispatch --feature my-feature
+
+# Run tests and fix failures via AI
+dispatch --fix-tests
 ```
 
+## Authentication
+
+Dispatch authenticates with GitHub and Azure DevOps using the **OAuth device flow** — no external CLI tools (`gh`, `az`) are required.
+
+On first use (or when a cached token is missing/expired), Dispatch will:
+
+1. Display a **one-time code** and open your browser to the provider's verification page.
+2. You sign in and authorize Dispatch in the browser.
+3. The token is cached locally at **`~/.dispatch/auth.json`** for future runs.
+
+Authentication happens **early in the CLI lifecycle** — during `dispatch config` (right after datasource selection) or at startup for `dispatch` and `dispatch --spec` runs — before any pipeline work begins. If tokens are already cached the check is instant; otherwise the device-code prompt appears while the terminal is still free, so it is never buried under pipeline output. No separate login step is needed.
+
+**Re-authenticating:** Delete `~/.dispatch/auth.json` (or just the relevant platform key inside it) and run `dispatch` again to re-trigger the device flow.
+
 ## Pipeline modes
 
 | Mode | Flag | Description |
 |------|------|-------------|
 | **Dispatch** | *(default)* | Plan and execute tasks; manage full git lifecycle |
 | **Spec generation** | `--spec` | Convert issues into structured markdown spec files |
+| **Respec** | `--respec` | Regenerate existing specs (all, by ID, or by glob) |
 | **Fix tests** | `--fix-tests` | Detect and auto-fix failing tests via AI |
+| **Feature** | `--feature [name]` | Group issues into a single feature branch and PR |
 
 ## Task files
 
@@ -192,7 +205,14 @@ Config is stored at `.dispatch/config.json` (relative to the working directory w
 | `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) |
+| `testTimeout` | Test execution timeout in minutes (default: 5, range: 1–120) |
+| `planTimeout` | Planning timeout in minutes (default: 30, range: 1–120) |
+| `concurrency` | Max parallel dispatches (range: 1–64) |
+| `org` | Azure DevOps organization URL |
+| `project` | Azure DevOps project name |
+| `workItemType` | Azure DevOps work item type filter |
+| `iteration` | Azure DevOps iteration path filter |
+| `area` | Azure DevOps area path filter |
 
 ## Options reference
 
@@ -206,22 +226,36 @@ Config is stored at `.dispatch/config.json` (relative to the working directory w
 | `--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 |
+| `--no-worktree` | `false` | Skip git worktree isolation for parallel issues |
+| `--feature [name]` | *(off)* | Group issues into a single feature branch and PR |
+| `--force` | `false` | Ignore prior run state and re-run all tasks |
+| `--concurrency <n>` | *(cpu/memory)* | Max parallel dispatches (max: 64) |
+| `--plan-timeout <min>` | `30` | Planning timeout in minutes |
+| `--retries <n>` | `3` | Retry attempts for all agents |
+| `--plan-retries <n>` | *(from --retries)* | Retry attempts for the planner agent (overrides `--retries`) |
+| `--test-timeout <min>` | `5` | Test timeout in minutes |
 | `--server-url <url>` | *(none)* | Connect to a running provider server |
 | `--cwd <dir>` | `process.cwd()` | Working directory |
 | `--verbose` | `false` | Show detailed debug output |
 
+In interactive dispatch runs, exhausted automatic retries pause the failed task in the dispatch UI so you can manually rerun it in place. A rerun re-enters the normal task lifecycle, including planning unless `--no-plan` is set; verbose or non-interactive runs will not wait for input and instead stop predictably with the task left failed.
+
 ### Spec mode
 
 | Option | Description |
 |--------|-------------|
-| `--spec [values...]` | Issue numbers, glob pattern, or description. Activates spec mode. Pass no args to regenerate all existing specs. |
+| `--spec <values...>` | Issue numbers, glob pattern, or inline text description. Activates spec mode. |
+| `--respec [values...]` | Regenerate specs: issue numbers, glob, or omit to regenerate all existing specs. |
 | `--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`) |
+| `--org <url>` | Azure DevOps organization URL |
+| `--project <name>` | Azure DevOps project name |
+
+### Fix tests mode
+
+| Option | Description |
+|--------|-------------|
+| `--fix-tests [issue-ids...]` | Run tests and fix failures via AI. Optionally pass issue IDs to target specific branches in worktrees. |
 
 ## Datasource auto-detection
 
@@ -249,14 +283,21 @@ For local-only workflows, pass `--source md` explicitly.
 Full documentation is in the [`docs/`](docs/) directory:
 
 - [Architecture Overview](docs/architecture.md)
+- [Agent System](docs/agent-system/overview.md)
 - [CLI & Orchestration](docs/cli-orchestration/overview.md)
 - [Datasource System](docs/datasource-system/overview.md)
-- [Provider System](docs/provider-system/provider-overview.md)
+- [Provider System](docs/provider-system/overview.md)
 - [Task Parsing](docs/task-parsing/overview.md)
 - [Planning & Dispatch](docs/planning-and-dispatch/overview.md)
 - [Spec Generation](docs/spec-generation/overview.md)
+- [Issue Fetching](docs/issue-fetching/overview.md)
+- [Git & Worktree](docs/git-and-worktree/overview.md)
+- [Prerequisites & Safety](docs/prereqs-and-safety/overview.md)
+- [Shared Types](docs/shared-types/overview.md)
+- [Shared Utilities](docs/shared-utilities/overview.md)
 - [Testing](docs/testing/overview.md)
 - [Windows](docs/windows.md)
+- [Changelog](docs/changelog.md)
 
 ## License