opencode-dispatcher 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [v0.4.0]
+
+- **Stronger Handoff Contract**: Orchestrator now delegates to task-planner with a rich structured handoff (conversation context, user preferences, corrections, rejected options, rationale) instead of a lossy brief summary, preventing context loss and overconfident under-contextualized specs.
+- **Parallel Planning**: Orchestrator now owns high-level decomposition (single-unit vs multi-unit classification, unit boundaries, dependencies, parallelizability) and can spawn multiple task-planner agents in parallel with assigned output paths for faster multi-unit workflows.
+- **Docs-First Routing**: Orchestrator routes to the documentation agent before task-planner when correctness depends on cross-cutting durable context (UX, product, domain, architecture, API, security decisions), ensuring task-planner has an approved source artifact to cite.
+- **Documentation Owns Durable Artifacts**: The documentation agent now explicitly owns durable source artifact types (UX briefs, product briefs, ADRs, API contracts, domain models, etc.) and reports when user approval is needed before task-planning.
+- **Validator Cites Source Artifacts**: The validator now checks cited source artifacts alongside the task spec when the task spec references them, ensuring implementations stay faithful to approved durable context.
+- **Orchestrator Prompt Slimmed**: Orchestrator prompt cleaned up with clearer responsibility split — orchestrator owns routing and coordination while task-planner owns detailed planning mechanics, field-level handoff definitions, path algorithms, and parent/child manifest formatting.
+
+## [v0.3.3]
+
+- **Workflow Fix**: Agents now use direct reads/directory listings for `.ai/` files instead of `glob`, preventing missed `.ai/context.md` checks.
+
+## [v0.3.2]
+
+- **Model-Config Consent Fix**: The `model-config` agent no longer silently accepts default model selections without explicit user consent — it now requires the user to confirm before applying default models.
+
+## [v0.3.1]
+
+- **Shipper Inspection & Release-Boundary Fixes**: Tightened shipper bash permission whitelist to eliminate pre-commit inspection prompts and fixed release-boundary routing so the shipper only commits and pushes explicitly intended changes.
+
+## [v0.3.0]
+
+- **Model-Config Groups**: Replaced per-agent model selection with two-tier group-based workflow (MED/LOW), excluding orchestrator and task-planner.
+
+## [v0.2.11]
+
+- **Routing Clarity**: Clarified executor routing as exact, mechanical, low-risk edits rather than file-count-based; clarified planner auto-proceed behavior when no user-facing decisions are introduced.
+- **Shipper Boundary**: Tightened shipper routing so it only commits and pushes existing intended changes.
+- **CI Update**: Updated publish workflow to Node 24-compatible GitHub Actions (`actions/checkout@v6`, `actions/setup-node@v6`, `node-version: 24`).
+
+## [v0.2.10]
+
+- **Agent Context**: Shipper agent now reads `.ai/context.md` for project-specific conventions (commit format, version bump patterns, auto-publish). Added `read` permission to shipper. Updated `.ai/context.md` with publication and auto-publish conventions. Added CI workflow (`.github/workflows/publish.yml`) to auto-publish on version bump commits.
+
+## [v0.2.8]
+
+- **Agent Clarity**: Updated `init` and `orchestrator` agents to accurately describe `agy` as an Antigravity CLI integration for splitting quota across models. Removed "file count" from the orchestrator's executor and task-planner routing rules — routing decisions now key on risk, complexity, and clarity instead.
+
+## [v0.2.7]
+
+- **Agent Fixes**: Fixed the `model-config` agent so it writes valid JSON(C) (not YAML) into `opencode.jsonc`, added `find`/`echo`/`sort`/`git config`/`ls` bash permissions to the `shipper` agent to eliminate pre-commit inspection permission prompts, and updated `model-config` to skip the orchestrator when presenting agents for model selection (the orchestrator's model is chosen directly by the user).
+
+## [v0.2.6]
+
+- **Agent Improvements**: Added `agy` integration awareness to the `init` and `orchestrator` agents. Documented strict permission boundaries and bash whitelisting patterns. Added common request routing patterns to the orchestrator. Removed unnecessary `.ai` edit denials from the executor agent.
+
+## [v0.2.5]
+
+- **Model Configuration**: Added the `model-config` agent to seamlessly assign specific models to different agents in the project's `opencode.jsonc`.
+- **Workflow Standardization**: Enforced sequential, zero-padded numeric prefixes for all task directories (e.g., `001-feature-name`) across all agents to ensure proper sorting and tracking.
+- **Usability Fixes**: Granted `bash` execution allowances to `implementer` and `validator` agents to reduce excessive permission prompts during test and build cycles.
+- **Artifact Improvements**: Split the task spec template into *Testable Acceptance Criteria* (with explicit test file path hints) and *Inspectable Acceptance Criteria* to better guide the `test-writer` and `validator`.
+
+## [v0.2.4]
+
+- Hardened security boundaries by applying explicit read-only bash whitelists to the `orchestrator` and sealing `edit: deny` escape hatches.
+
+## [v0.2.1]
+
+- Minor permission fixes to allow the orchestrator to cleanly delegate to the `executor` fast-path agent.
+
+## [v0.2.0]
+
+- **Major Overhaul**: Replaced the general conversational agents with a durable, stateful task workflow.
+- Introduced the central `orchestrator` as a user-facing router.
+- Shifted to explicit `.ai/tasks/` artifacts (task specs, implementation reports, validation reports) to make agent work inspectable, resumable, and git-trackable.
+- Consolidated legacy roles into specialized agents (`task-planner`, `implementer`, `validator`, `test-writer`).

package/README.md

@@ -1,9 +1,14 @@
 # OpenCode Dispatcher
 
-OpenCode Dispatcher is a workflow pack for OpenCode that adds specialist development agents coordinated through file-based task artifacts. It is designed for substantial coding work where you want the agent workflow to be easier to inspect, resume, and validate.
+OpenCode Dispatcher is a workflow pack for OpenCode that adds specialist development agents coordinated through file-based task artifacts. It is designed for substantial coding work where you want the agent workflow to be easier to inspect, resume, and validate. This package is for developers using OpenCode who want structured, auditable workflows for complex coding sessions.
 
 Instead of relying on long chat history, Dispatcher keeps durable task state in your project under `.ai/tasks/` (task specs, implementation reports, validation reports, documentation reports). For tiny one-off edits or quick questions, plain OpenCode is often enough.
 
+## Prerequisites
+
+- **OpenCode** — Dispatcher is a workflow add-on for OpenCode. You must have OpenCode installed and configured before using Dispatcher.
+- **Node.js >= 18** — Required for running the installer.
+
 ## Installation
 
 Install from the npm registry:
@@ -19,12 +24,12 @@ npm run check
 npm run install:local
 ```
 
-After installing, restart OpenCode so it reloads your global configuration.
+After installing, restart OpenCode so it reloads your global configuration. For details on what the installer copies, backup behavior, and uninstall, see [Configuration](docs/configuration.md).
 
 ## First Use
 
 1. Install Dispatcher and restart OpenCode.
-2. Open your project and let the orchestrator initialize `.ai/context.md` if it does not exist.
+2. Open your project and ask the orchestrator to initialize `.ai/context.md`. For example: *"Set up my project context."*
 3. For substantial work, ask the orchestrator to create a task spec:
 
    ```text
@@ -53,12 +58,17 @@ After installing, restart OpenCode so it reloads your global configuration.
 
 ## Further Reading
 
-- [CHANGELOG.md](CHANGELOG.md) — version history
-- [docs/workflow.md](docs/workflow.md) — orchestrator/subagent flow and task artifacts
-- [docs/agents.md](docs/agents.md) — subagent reference and permission model
-- [docs/configuration.md](docs/configuration.md) — model config, agy, opencode config, install details
-- [docs/development.md](docs/development.md) — validation, conventions, releases, publishing
+- [CHANGELOG.md](https://github.com/louisemalvin/opencode-dispatcher/blob/master/CHANGELOG.md) — version history
+- [docs/workflow.md](https://github.com/louisemalvin/opencode-dispatcher/blob/master/docs/workflow.md) — orchestrator/subagent flow and task artifacts
+- [docs/agents.md](https://github.com/louisemalvin/opencode-dispatcher/blob/master/docs/agents.md) — subagent reference and permission model
+- [docs/configuration.md](https://github.com/louisemalvin/opencode-dispatcher/blob/master/docs/configuration.md) — model config, agy, opencode config, install details
+- [docs/development.md](https://github.com/louisemalvin/opencode-dispatcher/blob/master/docs/development.md) — validation, conventions, releases, publishing
+
+## Version History
+
+- **v0.4.0** — Workflow improvements: stronger orchestrator-task-planner handoff, parallel planning, docs-first routing, documentation owns durable artifacts, validator checks cited source artifacts.
+- **v0.3.3** — Workflow fix: agents now use direct reads/directory listings for `.ai/` files instead of `glob`, preventing missed `.ai/context.md` checks.
 
 ## License
 
-MIT. See [LICENSE](LICENSE) for details.
+MIT. See [LICENSE](https://github.com/louisemalvin/opencode-dispatcher/blob/master/LICENSE) for details.

package/docs/agents.md

@@ -0,0 +1,107 @@
+# Agents
+
+This document is the agent reference for OpenCode Dispatcher. It lists every installed agent, describes its role and mode, and explains the permission philosophy that governs how agents interact with your project.
+
+For the end-to-end workflow routing and lifecycle, see [`docs/workflow.md`](workflow.md).
+
+---
+
+## Agent Reference
+
+Dispatcher installs 11 agents. The **orchestrator** is the primary, user-facing coordinator. All other agents are **subagents** — they are invoked by the orchestrator for specific scoped work and are typically hidden from agent selection UIs.
+
+| Agent | Mode | Role Summary |
+|---|---|---|
+| Orchestrator | primary | User-facing coordinator and state-machine router; clarifies requests, applies docs-first routing to documentation when durable context is needed, owns high-level task decomposition, provides a structured handoff to task-planner, delegates to subagents, and synthesizes results |
+| Executor | subagent | Performs exact, mechanical, single-file atomic edits that do not need a task spec, tests, or validation |
+| Task Planner | subagent | Creates auditable task specs under `.ai/tasks/` from an orchestrator handoff; owns path allocation, required spec sections, parent/child manifest mechanics, and planning-blocked behavior; formalizes plans without inventing missing strategic decisions; accepts assigned output paths for unit-level planning |
+| Implementer | subagent | Edits source code according to an approved task spec and writes an implementation report |
+| Validator | subagent | Validates completed work against a task spec and any cited durable source artifacts, runs tests from acceptance criteria, audits test quality, and writes a validation report |
+| Test Writer | subagent | Writes tests that encode testable acceptance criteria from an approved task spec; never writes implementation code |
+| Documentation | subagent | Creates durable source artifacts (UX briefs, ADRs, domain models, API contracts, etc.) for cross-cutting context; writes documentation, project context updates, decision notes, and task documentation reports; reports when user approval is needed before task-planning |
+| Research | subagent | Gathers external facts, official documentation, comparisons, and source-backed evidence before planning decisions |
+| Shipper | subagent | Handles git commit and push only when explicitly requested; no edits, deployment, or general development |
+| Init | subagent | Bootstraps `.ai/context.md` for new projects by interviewing the user about conventions and test setup |
+| Model Config | subagent | Assigns models to agents in the project's `opencode.jsonc` configuration |
+
+For optional agy integration (Antigravity CLI for splitting quota across models), see [Configuration > Agy Integration](configuration.md#agy-integration).
+
+---
+
+## Permission Philosophy
+
+Dispatcher enforces strict boundaries through OpenCode's permission model. Every agent's permissions are declared in its YAML frontmatter (in `workflow/agents/*.md`) and are designed so that no agent can silently cross role boundaries.
+
+### Deny-by-Default
+
+Permissions start locked down. Each agent is granted only the specific capabilities its role requires:
+
+- **Orchestrator**: `edit: deny` — the orchestrator cannot write to any file. Its `bash` permission is a strict whitelist limited to read-only informational commands (`ls`, `pwd`, `which`, `env`, `echo`, `uname`, `file`, `wc`, `git status`, `git diff`, `git log`, `git branch`, `git remote`, `git rev-parse`, `git show`, `git config`, `git stash list`, `git ls-files`). All other shell commands (`*`) are denied. Git write commands (`git commit*`, `git push*`) are explicitly denied.
+- **Research**: `edit: deny`, with `webfetch: allow` only. It cannot write files or run arbitrary shell commands.
+- **Shipper**: `edit: deny`, `read: allow`, with a strict `bash` whitelist of specific `git` commands (`git status`, `git diff`, `git log`, `git branch`, `git remote`, `git rev-parse`, `git add *`, `git commit *`, `git push*`) and inspection utilities (`find`, `echo`, `sort`, `ls`, `grep`, `head`, `tail`, `cat`, `wc`, `file`, `node -p`). Destructive operations (`git reset*`, `git rebase*`, `git clean*`, `git tag*`, `git commit -a*`, `git commit --amend*`, `gh pr*`, and any deploy commands) are explicitly denied.
+- **Task Planner**: `edit` is denied everywhere except `.ai/tasks/**` and `.ai/decisions/**`.
+- **Validator**: `edit` is denied everywhere except `.ai/tasks/*/validation-report.md`.
+- **Test Writer**: `edit` is denied everywhere except test file patterns (`**/*.test.*`, `**/test_*`, `**/*_test.*`, `**/__tests__/**`, `**/tests/**`, `**/spec/**`). It has no `task` permission.
+- **Documentation**: `edit` is denied everywhere except `docs/**`, `README.md`, `README.*`, `CHANGELOG.md`, `.ai/tasks/*/documentation-report.md`, and `.ai/decisions/**`. Configuration files (`.opencode/**`, `opencode.json`, `opencode.jsonc`, `package.json`, `package-lock.json`, lock files) are explicitly denied.
+- **Init**: `edit` is denied everywhere except `.ai/context.md`. It has `question: allow` to interview the user.
+- **Model Config**: `edit` is denied everywhere except `opencode.jsonc` or `.opencode/opencode.jsonc`. It has no `task` permission.
+
+### Role Boundaries
+
+Each agent owns a specific layer of the workflow. No agent is allowed to cross roles:
+
+- **Orchestrator** coordinates, routes (including docs-first routing), and decomposes but never implements, documents, or validates.
+- **Task Planner** plans and decomposes, owns path allocation and planning mechanics, but never edits source code or project docs outside `.ai/`.
+- **Implementer** edits source code but cannot write tests (that is the Test Writer's role) or fix validation issues (the Validator reports them; only a new task can fix them).
+- **Validator** reads and reports (against task spec AND cited source artifacts) but never fixes issues or edits code.
+- **Test Writer** writes tests but never writes implementation code.
+- **Documentation** creates durable source artifacts where needed, writes docs and context, but never edits source code or configuration.
+- **Research** gathers evidence but never implements or edits.
+- **Shipper** commits and pushes but never edits files, runs tests, or deploys.
+- **Init** bootstraps context but never edits source code or task artifacts.
+- **Model Config** configures model assignments but never edits code, docs, or `.ai/` artifacts.
+
+### Escape Hatch Sealing
+
+A secure permission model must ensure that restricted capabilities cannot be bypassed through allowed tools. Dispatcher seals the two common escape hatches:
+
+1. **`edit: deny` must not be subverted through shell commands.** The orchestrator has `edit: deny` and a read-only `bash` whitelist. Commands that could write files (e.g., `echo > file`, `cat > file`, `tee`, `redirects` in shell) are not in the whitelist; the `*: deny` fallback catches everything else. No shell-based file write is possible.
+
+2. **`bash` whitelists must not contain write-capable commands.** The orchestrator's whitelist is limited to read-only queries. The shipper's whitelist allows specific `git` operations but denies `git reset`, `git rebase`, `git clean`, `git tag`, `git commit -a`, `git commit --amend`, and force-push variants. The validator has broad `bash: allow` but `edit: deny` (except its own report), so destructive shell commands are blocked by the edit layer.
+
+### Practical Allowances
+
+Some agents have intentionally broad permissions to avoid excessive prompting during normal development cycles:
+
+- **Implementer**: `bash: * allow` so it can seamlessly run test, build, and dev commands without permission prompts. Its `edit` scope prevents it from touching `.ai/tasks/**` (except its own `implementation-report.md`), `.ai/context.md`, and `.ai/decisions/**` — it can edit source code freely but cannot alter task artifacts.
+- **Validator**: `bash: * allow` for the same reason — running test suites and build commands should not require repeated approval. Its `edit` scope is tightly restricted (only `validation-report.md`).
+- **Executor**: Both `bash: * allow` and `edit: * allow` because it handles exact, mechanical, low-risk edits where the overhead of restricted permissions would add friction without safety benefit. If an edit exceeds this scope, the executor escalates back to the orchestrator.
+
+### Task Gating
+
+The orchestrator's `task` permission is explicitly scoped to named agents — no wildcard task permission exists:
+
+```yaml
+task:
+  "*": deny
+  task-planner: allow
+  implementer: allow
+  documentation: allow
+  validator: allow
+  research: allow
+  shipper: allow
+  test-writer: allow
+  init: allow
+  model-config: allow
+  executor: allow
+```
+
+This means the orchestrator can only delegate to the 10 explicitly listed subagents. It cannot delegate to an arbitrary or unknown agent, which prevents privilege escalation through delegation.
+
+---
+
+## Summary
+
+Dispatcher's permission model follows a simple principle: **an agent can do everything its role requires and nothing its role does not**. Permissions are layered — `edit`, `bash`, and `task` are each scoped independently — and the deny-by-default baseline ensures that every allowance is intentional and auditable through the agent's YAML frontmatter.
+
+For workflow-level routing and the execution lifecycle, see [`docs/workflow.md`](workflow.md).

package/docs/configuration.md

@@ -0,0 +1,215 @@
+# Configuration
+
+## Model Configuration
+
+Dispatcher supports per-agent model assignment through a two-tier group system managed by the **model-config** agent.
+
+### Group System
+
+The configurable subagents are divided into two recommendation tiers:
+
+| Group | Agents | Recommended Model Class |
+|-------|--------|------------------------|
+| **MED** | `validator`, `test-writer`, `documentation`, `init` | Medium reasoning model |
+| **LOW** | `implementer`, `research`, `executor`, `shipper`, `model-config` | Cheaper / lower reasoning model |
+
+The **orchestrator** and **task-planner** are excluded from group assignment — their models are chosen directly by the user in OpenCode itself. The task-planner is intended to use the same model as the orchestrator.
+
+These are recommendation tiers, not hardcoded assignments — you choose the actual model for each group through the model-config agent. The `opencode.jsonc` file included in this repository is the maintainer's preset: a ready-to-use starting point that you can override with your own model choices.
+
+### Configuration Flow
+
+1. The orchestrator delegates model configuration to the **model-config** agent.
+2. The model-config agent runs `opencode models --verbose` to discover available models and their variants on the system.
+3. It checks for an existing opencode config at `opencode.jsonc` or `.opencode/opencode.jsonc` (in that order of preference).
+4. It presents both groups to the user with their intended model tiers and asks the user to pick one model (and optionally a variant) for each group — not per-agent.
+5. For the chosen model, if it has variants (non-empty `variants` object in verbose output), the user is prompted to select one or skip. Models with no variants (`{}`) skip the variant prompt silently.
+6. The model-config agent writes `agent.<name>.model` (and optionally `agent.<name>.variant`) entries for every agent in each group into the project's opencode config, preserving all existing content.
+
+### Config File Format
+
+The model assignments are written to `opencode.jsonc` or `.opencode/opencode.jsonc`:
+
+```jsonc
+{
+  "agent": {
+    "orchestrator": {
+      "model": "opencode-go/deepseek-v4-pro",
+      "variant": "medium"
+    },
+    "implementer": {
+      "model": "opencode-go/deepseek-v4-flash"
+    }
+  }
+}
+```
+
+If no opencode config exists, the model-config agent creates one with only the agent entries.
+
+## Agy Integration
+
+**Agy** (Antigravity CLI integration) is an optional mechanism that offloads implementer work to a separate CLI tool called `agy`, allowing quota usage to be split across different models.
+
+### How It Works
+
+- The implementer agent reads `.ai/context.md` and checks for an `agy: enabled` flag under the `## Workflow` section.
+- If `agy` is enabled and available (verified via `which agy`), the implementer constructs a prompt containing:
+  - Its full persona (the agent definition file contents)
+  - The complete task spec
+  - The contents of all relevant files listed in the task spec
+- It runs `agy --dangerously-skip-permissions --print "<prompt>"` which executes the edits directly.
+- After agy finishes, the implementer verifies the changes, runs validation, writes the implementation report, and reports back to the orchestrator.
+
+### Enabling Agy
+
+Add the following flag to `.ai/context.md` under `## Workflow`:
+
+```markdown
+## Workflow
+
+- **agy**: enabled
+```
+
+The flag is **user-owned** — agents never modify it. During project initialization, the **init** agent asks the user whether they want to enable agy integration.
+
+### Fallback
+
+If agy is not enabled (`agy: enabled` missing or set to a falsy value) or the `agy` binary is not available, the implementer proceeds with manual implementation steps.
+
+## OpenCode Config Locations
+
+Dispatcher's configuration spans two levels:
+
+### Project-Level Config
+
+OpenCode reads project configuration from the following locations, in order of preference:
+
+1. **`opencode.jsonc`** (preferred) — in the project root
+2. **`.opencode/opencode.jsonc`** — in the `.opencode/` subdirectory
+
+The model-config agent writes per-agent model assignments to whichever file exists, preferring `opencode.jsonc` if both are present. If neither exists, it creates `opencode.jsonc`.
+
+### Global / User-Level Config
+
+OpenCode's global configuration lives at:
+
+```
+~/.config/opencode/
+```
+
+This directory contains:
+
+| Directory / File | Description |
+|-----------------|-------------|
+| `agents/` | Installed agent definitions (managed by Dispatcher) |
+| `skills/` | OpenCode skills (not managed by Dispatcher) |
+| `templates/` | Prompt templates (not managed by Dispatcher) |
+| `AGENTS.md` | User-owned agent documentation — never touched by Dispatcher |
+
+Dispatcher installs managed payloads into `~/.config/opencode/agents/`. The `skills/`, `templates/`, and `AGENTS.md` under `~/.config/opencode/` are **user-owned** and never modified, backed up, or removed by Dispatcher.
+
+## Install Locations and Payloads
+
+### What the Installer Copies
+
+The installer (`bin/install.js`) copies Dispatcher's managed payloads into:
+
+```
+~/.config/opencode/agents/
+```
+
+Current payloads include agent definitions for:
+- Orchestration
+- Initialization
+- Task planning
+- Test writing
+- Implementation
+- Documentation
+- Validation
+- Research
+- Shipping
+- Exact mechanical edits (executor)
+- Model configuration
+
+### What the Installer Does NOT Manage
+
+The installer does **not** install or manage:
+
+- Provider configuration
+- Model settings
+- Secrets (API keys, tokens)
+- Project dependencies (`node_modules`)
+- Git configuration
+- `opencode.jsonc` (project-level config is user-managed)
+- Global skills under `~/.config/opencode/skills/`
+- Prompt templates under `~/.config/opencode/templates/`
+- `~/.config/opencode/AGENTS.md`
+
+For agent role descriptions, see [docs/agents.md](agents.md). For development and release processes, see [docs/development.md](development.md).
+
+## Install Safety
+
+Before overwriting a managed path, the installer backs up the existing path beside it using a timestamped `.bak-*` suffix.
+
+Example backup:
+
+```
+~/.config/opencode/agents.bak-2026-06-07T12-34-56-789Z
+```
+
+The installer then overlays the Dispatcher payload into the managed path.
+
+### Backup Semantics
+
+- **Same-named files** may be overwritten in the managed path.
+- **Unrelated pre-existing files** in the managed path may remain.
+- **Backups are kept beside the managed path** and are not modified by subsequent installs.
+- **`~/.config/opencode/AGENTS.md`** is never backed up, overwritten, or touched in any way — it is fully user-owned.
+
+This is an overlay, not a merge. The installer does not attempt to diff or merge files.
+
+## Restore and Uninstall
+
+### Restoring a Backup
+
+To restore a previously backed-up managed path:
+
+1. **Stop OpenCode** so global config is reloaded afterward.
+2. Remove or rename the current managed path:
+   ```bash
+   mv ~/.config/opencode/agents ~/.config/opencode/agents.dispatcher
+   ```
+3. Move the matching `.bak-*` path back to its original name:
+   ```bash
+   mv ~/.config/opencode/agents.bak-<timestamp> ~/.config/opencode/agents
+   ```
+4. **Restart OpenCode** so it reloads the global configuration.
+
+### Uninstalling Dispatcher
+
+- **If you had pre-existing global agents** before installing Dispatcher: restore your backups first (see above).
+- **If you do not need any current contents** (including files that may have existed before Dispatcher was installed): remove the managed paths outright:
+  ```bash
+  rm -rf ~/.config/opencode/agents
+  ```
+- **`~/.config/opencode/AGENTS.md`** is never removed or modified — it remains even after uninstall.
+
+After any restore or uninstall, restart OpenCode so it reloads `~/.config/opencode/`.
+
+## Package Commands
+
+The following commands are available from `package.json`:
+
+| Command | Equivalent | Description |
+|---------|-----------|-------------|
+| `npm run check` | `npx opencode-dispatcher check` | Validates agent frontmatter integrity and orchestrator cross-references |
+| `npm run install:local` | `npx opencode-dispatcher install` | Installs Dispatcher payloads into `~/.config/opencode/` |
+| `npx opencode-dispatcher` (no args) | `npx opencode-dispatcher install` | Defaults to install |
+
+Invalid commands print usage and exit with a non-zero status.
+
+The package is published on the npm registry as `opencode-dispatcher`:
+
+```bash
+npx opencode-dispatcher install
+```

package/docs/development.md

@@ -0,0 +1,74 @@
+# Development
+
+This document covers repository maintenance, validation, release conventions, and publishing for the OpenCode Dispatcher package.
+
+## Validation
+
+The project uses a single check command as its validation gate:
+
+```bash
+npm run check
+```
+
+This is equivalent to:
+
+```bash
+node ./bin/install.js check
+```
+
+The check validates the following:
+
+- **Agent frontmatter completeness** — Every agent markdown file in `workflow/agents/` must contain YAML frontmatter (delimited by `---`) with required fields:
+  - `description` — A summary of the agent's role.
+  - `mode` — One of `primary`, `subagent`, or `all`.
+  - `permission` — Permission blocks that define what the agent may read, edit, or execute.
+- **Cross-reference integrity** — Every agent that the orchestrator permits (via its `permission.task` block) must have a corresponding `.md` file in `workflow/agents/`, and every agent file (except the orchestrator itself) must be listed in the orchestrator's permitted set.
+
+The check also verifies that `workflow/skills/` and `workflow/templates/` are empty or absent, since workflow behavior has been consolidated into agent definitions.
+
+`npm run check` must pass before any release.
+
+For a full list of package commands, see [Configuration](configuration.md).
+
+## Repository Structure
+
+| Path | Purpose |
+|------|---------|
+| `bin/install.js` | CLI installer and checker — supports `install` and `check` commands |
+| `workflow/agents/` | Agent markdown definitions with YAML frontmatter |
+| `workflow/skills/` | Skill definitions (currently unused; must remain empty) |
+| `workflow/templates/` | Task artifact templates (currently unused; must remain empty) |
+| `.ai/` | Project-level task artifacts and project context (git-tracked) |
+| `.github/workflows/publish.yml` | CI auto-publish workflow |
+
+## Conventions
+
+The project follows these conventions, defined in `.ai/context.md`:
+
+| Aspect | Convention |
+|--------|------------|
+| **Language** | Node.js (ESM — `"type": "module"` in `package.json`) |
+| **JS style** | StandardJS / Prettier defaults (semicolons, double quotes, trailing commas) |
+| **Naming** | kebab-case for files; camelCase for JavaScript identifiers and functions |
+| **File layout** | Flat structure — CLI scripts live in `bin/`; no `src/` directory |
+| **Commit messages** | [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) format |
+| **Version bumps** | `chore(release): bump to vX.Y.Z` |
+
+## Release Workflow
+
+The end-to-end release process follows these steps:
+
+1. **Prepare metadata** — Bump the version number in `package.json` following semver.
+2. **Prepare documentation** — Update the Version History section in `README.md` with a description of the changes included in the release. Any changelog updates should also be prepared at this stage.
+3. **Invoke the shipper agent** — The shipper handles the git commit and push. All metadata and documentation changes must be ready before the shipper is invoked.
+4. **Commit format** — The shipper uses the commit message `chore(release): bump to vX.Y.Z`, which matches the CI auto-publish trigger pattern.
+
+Per the [project conventions](#conventions), version bump preparation (metadata and README changes) must be completed by the responsible agent (implementer, executor, or documentation) before the shipper is called.
+
+## CI Auto-Publish
+
+Publishing is automated via `.github/workflows/publish.yml`. On push to `master` with `bump to v` in the commit message, the workflow runs the validation gate and publishes to npm. See the workflow file for the exact steps and authentication details.
+
+## Project Context
+
+See [Workflow > Project Context](workflow.md#project-context) for details on `.ai/context.md`.

package/docs/workflow.md

@@ -0,0 +1,100 @@
+# Workflow
+
+This document describes the high-level OpenCode Dispatcher workflow: how the orchestrator routes requests, how task artifacts are laid out, and how agents coordinate.
+
+For a complete agent reference, see [docs/agents.md](agents.md).
+
+## Role Split
+
+Dispatcher uses five core agents with distinct responsibilities:
+
+- **Orchestrator**: Conversation/context router, high-level decomposition coordinator, user-facing owner. Routes to the right agent, owns the state machine, and provides a structured handoff for non-trivial work.
+- **Documentation**: Durable source artifact author for cross-cutting/reusable context (UX briefs, ADRs, domain models, API contracts, etc.). Reports when user approval is needed before task-planning.
+- **Task Planner**: Task artifact author and planning mechanics owner. Owns path allocation, parent/child manifest format, required spec sections, and self-directed fallback decomposition.
+- **Implementer**: Executes approved task specs by editing source code.
+- **Validator**: Checks completed work against the task spec and any cited durable source artifacts.
+
+Docs-first routing: When correctness depends on cross-cutting/reusable context not yet captured in durable form, the orchestrator routes to documentation BEFORE task-planner so task-planner has an approved source artifact to cite.
+
+## Orchestrator State Machine
+
+The orchestrator operates as a six-state state machine. Not every request passes through every state — the orchestrator always chooses the smallest safe workflow for the task.
+
+- **INTAKE**: Classify the incoming request. Determine whether it is a question, idea exploration, simple edit, non-trivial implementation, research-backed decision, documentation task, validation or review, or a commit/push request.
+- **CLARIFY**: Talk with the user until the request is solid enough to route. A request is solid when the desired outcome, affected files, rough scope, important non-goals, risk level, and expected verification are all understood. The orchestrator asks one focused question only when the missing answer would change scope, safety, or routing.
+- **ROUTE**: Choose the smallest safe path. The orchestrator decides which agent or direct answer best fits the request, applying docs-first routing when durable context is needed.
+- **DELEGATE**: Dispatch the work to the appropriate specialist agent. After the subagent completes, control always returns to the orchestrator.
+- **REVIEW**: After non-trivial implementation or documentation work, validate the result against the task spec. If validation fails, allow one fix cycle. If issues remain, escalate to the user.
+- **DONE**: Summarise the outcome, changed files or artifacts, verification results, and any open issues.
+
+## Routing Logic
+
+The orchestrator selects the smallest safe workflow based on the nature of the request:
+
+- **Direct answer** — When no file changes are needed. Used for explanations, reviews, comparisons, and planning advice.
+- **Docs-first routing** — When correctness depends on cross-cutting/reusable context not yet in durable form, route to documentation first, then to task-planner citing that artifact.
+- **Executor (fast path)** — When the requested edit is exact, mechanical, low-risk, and does not need task planning or acceptance criteria.
+- **Task-planner** — When the work is behaviour-changing, risky, unclear, needs acceptance criteria, or benefits from a written plan before implementation. The orchestrator provides a rich structured handoff (see [Rich Handoff Concept](#rich-handoff-concept)).
+- **Research** — When a decision depends on external facts such as official documentation, vendor behaviour, pricing, APIs, or current best practices.
+- **Shipper** — Only for explicit git commit or push requests after the intended file changes already exist.
+- **Documentation** — When the task involves README updates, project context updates, decision notes, changelog entries, or documentation reports.
+- **Model-config** — When the user wants to configure per-agent models for this project.
+
+## Task Artifact Layout
+
+Dispatcher stores durable task state under `.ai/tasks/`. Each task gets a zero-padded numeric prefix and a short slug:
+
+```text
+.ai/tasks/<NNN>-<task-id>/
+    task-spec.md
+    implementation-report.md
+    validation-report.md
+    documentation-report.md
+```
+
+| File | Purpose | Written by |
+|------|---------|-----------|
+| `task-spec.md` | Approved scope, acceptance criteria, constraints, relevant files, and validation plan. Includes an `## Execution` section listing the agent pipeline. | Task-planner |
+| `implementation-report.md` | What files were changed, what approach was taken, and any open questions. | Implementer |
+| `validation-report.md` | Verification results against the task spec's acceptance criteria and cited source artifacts. | Validator |
+| `documentation-report.md` | Outcome, files changed, context or decisions updated, verification, and follow-ups. | Documentation |
+
+The `## Execution` section in `task-spec.md` drives the agent pipeline: test-writer, implementer, and/or documentation, in that order. The orchestrator reads this section, spawns agents sequentially, and always runs the validator last.
+
+## Project Context
+
+`.ai/context.md` captures durable project truth that persists across tasks and sessions. It stores shared language, architecture facts, conventions, test framework, stable decisions, and workflow flags. The orchestrator checks for it on first interaction; if missing, delegates to the init agent. Specialist agents read it using the `read` tool before acting.
+
+## Common Routes
+
+### Ask a Question, Tiny Edit
+
+These are unchanged from the current workflow: direct answer for questions, executor for exact mechanical edits.
+
+### Substantial Feature or Fix
+
+The orchestrator applies docs-first routing: if durable/cross-cutting context is needed, routes to documentation first. Then routes to task-planner for a task spec. After user approval, reads the spec's `## Execution` section, spawns agents sequentially (implementer, validator), and summarises the outcome.
+
+### Research-Backed Change
+
+The orchestrator routes to research first, then applies the substantial feature or fix route with the research findings as source context.
+
+### Documentation Task, Commit/Push
+
+These routes are unchanged.
+
+## Rich Handoff Concept
+
+When delegating non-trivial work to the task-planner, the orchestrator provides a **rich structured handoff** that preserves conversation-derived context. This prevents context loss in the orchestrator→task-planner delegation.
+
+The handoff fields are: User Intent, Conversation-Derived Context, Source Artifacts / Source Context, Proposed Task Shape, Assigned Output Path(s), Scope and Non-Goals, Constraints, Acceptance Signals, Authority Boundary, Open Questions / Stop Conditions. Each field is filled; empty fields use "None."
+
+Detailed field definitions and mechanics live in the orchestrator and task-planner agent prompts. The orchestrator owns filling this handoff for every non-trivial planning invocation.
+
+## Decomposition Ownership
+
+The orchestrator owns single-unit vs multi-unit classification and high-level decomposition. The task-planner formalizes from the orchestrator's handoff. Task-planner performs self-directed decomposition only as a fallback when the orchestrator has not provided a unit split.
+
+## Planning Mechanics (Owned by Task-Planner)
+
+Detailed task artifact mechanics — path allocation (computing the next `<NNN>`), parent/child manifest format, required spec sections, self-directed fallback decomposition, and planning-blocked behavior — are owned by the task-planner agent. See `workflow/agents/task-planner.md` for the full specification.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-dispatcher",
-  "version": "0.3.2",
-  "description": "A low-context OpenCode dispatcher workflow with orchestrator agents and task artifacts.",
+  "version": "0.4.0",
+  "description": "OpenCode add-on providing structured multi-agent workflows, durable task artifacts, and an orchestrator agent for complex AI coding sessions.",
   "type": "module",
   "bin": {
     "opencode-dispatcher": "bin/install.js"
@@ -13,8 +13,14 @@
   "files": [
     "bin/",
     "workflow/",
-    "README.md"
+    "README.md",
+    "docs/",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "keywords": [
     "opencode",
     "ai-agents",

package/workflow/agents/documentation.md

@@ -24,10 +24,12 @@ You are the Documentation Agent.
 
 Own documentation, project context, decision notes, and documentation reports when delegated by orchestrator.
 
+Own durable source artifacts for cross-cutting and reusable context. Types of durable artifacts you create include: UX design brief, product brief, interaction model, feature behavior spec, ADR, domain model, business rules doc, API contract, integration spec, migration plan, runbook, testing strategy, convention guide. If an artifact introduces meaningful decisions, report that user approval is needed before task-planning.
+
 Responsibilities:
 
 - Update `.ai/context.md` when delegated. Do not create `.ai/context.md` from scratch — that is owned by the init agent. Write decision notes and documentation updates from approved task specs or explicit orchestrator delegation.
-- Read existing docs, `.ai/context.md`, task specs, and relevant source files before writing.
+- Read existing docs, `.ai/context.md` (use the `read` tool — `glob` is unreliable for `.ai/` paths), task specs, and relevant source files before writing.
 - Write decision notes under `.ai/decisions/` for stable, non-obvious decisions when delegated.
 - Write `.ai/tasks/<NNN>-<task-id>/documentation-report.md` with sections: Outcome, Files Changed, Context Or Decisions Updated, Verification. Include Follow-Ups only if there are any.
 - Keep docs concise, accurate, and grounded in source files or approved decisions.

package/workflow/agents/implementer.md

@@ -19,14 +19,14 @@ Own implementation only after the task is specified and approved in `.ai/tasks/<
 
 Responsibilities:
 
-- Agy integration (optional): After reading `.ai/context.md`, check if it contains `agy: enabled`. If enabled, check if `agy` is available (`which agy`). If both conditions are true: construct a prompt that includes your full persona (the contents of this agent definition file), the complete task spec, and the contents of all relevant files. Run `agy --dangerously-skip-permissions --print "<the constructed prompt>"`. Agy will make the edits directly. After agy finishes, verify the changes satisfy the task spec, run verification, write the implementation report, and report back to orchestrator. If agy is not enabled or not available, proceed with the manual implementation steps below.
-- Read `.ai/context.md` and the task spec before editing.
+- Agy integration (optional): After reading `.ai/context.md` (use the `read` tool — `glob` is unreliable for `.ai/` paths), check if it contains `agy: enabled`. If enabled, check if `agy` is available (`which agy`). If both conditions are true: construct a prompt that includes your full persona (the contents of this agent definition file), the complete task spec, and the contents of all relevant files. Run `agy --dangerously-skip-permissions --print "<the constructed prompt>"`. Agy will make the edits directly. After agy finishes, verify the changes satisfy the task spec, run verification, write the implementation report, and report back to orchestrator. If agy is not enabled or not available, proceed with the manual implementation steps below.
+- Read `.ai/context.md` (use the `read` tool — `glob` does not match dot-directories reliably) and the task spec before editing.
 - Read the files listed in the task spec's `## Relevant Files` section. If those files import or reference other files you need to understand, read those too — but only as far as needed. Do not explore unrelated parts of the codebase.
 - Make the smallest correct change that satisfies the task spec.
 - Preserve unrelated user changes.
 - Run the smallest relevant verification when practical.
 - Write `.ai/tasks/<NNN>-<task-id>/implementation-report.md` with sections: Outcome, Files Changed, Decisions, Verification. Include Known Issues only if there are any.
-- Run the project's test suite (using the test runner from `.ai/context.md`). Confirm that the task-specific tests pass. If pre-existing baseline tests fail, note them as Known Issues but do not chase them.
+- Run the project's test suite (using the test runner from `.ai/context.md` — read it with the `read` tool, as `glob` is unreliable for `.ai/` paths). Confirm that the task-specific tests pass. If pre-existing baseline tests fail, note them as Known Issues but do not chase them.
 
 Boundaries:
 

package/workflow/agents/orchestrator.md

@@ -65,7 +65,7 @@ Artifact source-of-truth rules:
 
 Project initialization:
 
-- On first interaction with a project, check if `.ai/context.md` exists before routing non-trivial work.
+- On first interaction with a project, check if `.ai/context.md` exists by using the `read` tool on the path directly (an error means it does not exist). Do **not** use `glob` — it does not match dot-directories reliably.
 - If missing, delegate to init agent to interview the user and create it.
 
 ## Stateful Workflow
@@ -107,12 +107,14 @@ Ask one focused question only when the missing answer would change scope, safety
 
 ### ROUTE
 
+**Docs-first routing**: Before routing to task-planner, check whether correctness depends on cross-cutting or reusable context not yet captured in durable form. Triggering contexts include: UX/design intent, product behavior, interaction model, information architecture, domain/business rules, architecture decisions, API/data contracts, security/privacy requirements, integration behavior, operational rules, testing strategy, conventions. If such context is missing, route to documentation FIRST to create a durable source artifact, then route to task-planner citing that artifact.
+
 Choose the smallest safe path:
 
 - Answer directly when no file changes are needed.
 - Use executor when the requested edit is exact, mechanical, low-risk, and does not need task planning or acceptance criteria.
 - Use research when current facts, external docs, pricing, vendor behaviour, or source-backed confidence matter.
-- Use task-planner when the work is behaviour-changing, risky, unclear, needs acceptance criteria, or benefits from a written plan before implementation.
+- Use task-planner only WITH a rich structured handoff (see ### Rich Handoff Contract below) when the work is behaviour-changing, risky, unclear, needs acceptance criteria, or benefits from a written plan before implementation.
 - Use shipper only for explicit git commit or push work after the intended file changes already exist.
 - Use model-config when the user wants to configure per-agent models for this project.
 ### Common Requests
@@ -132,9 +134,35 @@ Delegate to the specialist that owns the next action.
 - documentation: docs/context/decision updates
 - validator: validation against task specs
 - shipper: commit/push only
-
 Always return control to yourself after each subagent result.
 
+### Rich Handoff Contract
+
+For non-trivial work (behaviour-changing, risky, multi-step, or multi-unit), you MUST NOT delegate to task-planner using only a brief summary. A brief summary risks context loss — task-planner lacks conversation-derived nuance and may invent incorrect assumptions.
+
+Instead, provide a structured handoff with these fields (fill each; write "None" for empty fields):
+- User Intent
+- Conversation-Derived Context
+- Source Artifacts / Source Context
+- Proposed Task Shape
+- Assigned Output Path(s)
+- Scope and Non-Goals
+- Constraints
+- Acceptance Signals
+- Authority Boundary
+- Open Questions / Stop Conditions
+
+### Decomposition Ownership
+
+You own the single-unit vs multi-unit classification and the high-level decomposition. Task-planner formalizes from your handoff; it does not re-decompose unless you failed to provide a unit split.
+
+- **Single-unit**: A focused change touching related files. Delegate to task-planner with a single assigned output path.
+- **Multi-unit**: A request spanning multiple independent modules, deliverables, or phases. You must decompose into units (with user approval if needed), determine unit boundaries, dependencies, and parallelizability, then assign child output paths.
+
+### Multi-Unit Coordination
+
+When work spans multiple units, you own the unit breakdown (with user approval). Assign non-conflicting output paths to parallel task-planners. Units with true dependencies wait until the dependency spec exists before planning. After all specs are written, proceed to the execution pipeline.
+
 Execution pipeline for task specs:
 
 - After task-planner returns a task spec, read the `## Execution` section.

package/workflow/agents/shipper.md

@@ -55,7 +55,7 @@ You are the Shipper Agent.
 
 You own git commit and push work only when orchestrator or the user explicitly requests it. Do not deploy, implement code, edit files, or perform general development tasks.
 
-- Read `.ai/context.md` before operating for project-specific conventions: commit message format (Conventional Commits), version bump pattern (`chore(release): bump to vX.Y.Z`), and auto-publish triggers.
+- Read `.ai/context.md` (use the `read` tool — `glob` is unreliable for `.ai/` paths) before operating for project-specific conventions: commit message format (Conventional Commits), version bump pattern (`chore(release): bump to vX.Y.Z`), and auto-publish triggers.
 
 Hard boundaries:
 

package/workflow/agents/task-planner.md

@@ -12,53 +12,95 @@ permission:
 
 You are the Task Planner Agent.
 
-- Mandatory: every task directory MUST use the `<NNN>-<task-id>` naming convention. `<NNN>` is the next available zero-padded number (001, 002, …) found by scanning existing `.ai/tasks/` directories.
+### Assigned Output Path
 
-Own task specification and decomposition, not implementation. Create or update auditable task artifacts under project `.ai/tasks/` after orchestrator has clarified the user request enough to plan safely. For complex multi-part work, decompose into independent units before writing individual task specs.
+If the orchestrator has provided an assigned output path, use it exactly. Do NOT compute the next `<NNN>` yourself. The path computation step (listing existing `.ai/tasks/` directories) only applies when no path is assigned.
 
-On every invocation, assess whether the work is a single-unit task or a multi-unit task:
+### Planning Flow
 
-- **Single-unit**: a focused change that touches a small set of related files. Proceed with the single-unit workflow below.
-- **Multi-unit**: a complex request spanning multiple unrelated modules, independent deliverables, or phases. Decompose into discrete work units first (see Multi-unit decomposition below), then write child task specs.
+On every invocation, first check if the orchestrator has assigned a specific unit scope and output path:
 
-Single-unit workflow:
+- **Orchestrator-assigned unit**: The orchestrator has provided a single unit scope and an exact output path (typically a child path in a multi-unit decomposition). Follow the Assigned-Unit Workflow below. Do NOT present a unit table or decompose further.
+- **Self-directed decomposition (fallback)**: No assigned unit is provided. Assess whether the work is single-unit or multi-unit (see Self-Directed Decomposition below).
 
-- Create `.ai/tasks/<NNN>-<task-id>/task-spec.md` with sections: Scope, Execution, Non-Goals, Testable Acceptance Criteria (with `### Test File Paths` subsection), Inspectable Acceptance Criteria, Relevant Files. `<NNN>` is the next available zero-padded number (001, 002, …) found by scanning existing `.ai/tasks/` directories.
-- Read `.ai/context.md` for project conventions (naming, styling, file layout, test setup) before writing a task spec.
+### Planning-Blocked
+
+If the handoff from the orchestrator is too thin to create an accurate spec without inventing strategic, product, architecture, domain, security, or business decisions, STOP and return a **planning-blocked** report describing what context or decisions are missing. Do NOT fill gaps by guessing.
+
+A planning-blocked report lists:
+- What decisions cannot be made with the provided context.
+- What specific information is needed to proceed.
+- Which sections of the spec would require invention (and therefore cannot be written safely).
+
+### Decision Authority
+
+Your authority is explicitly constrained:
+
+- **Allowed**: Implementation-local decisions (which patterns to use within project conventions, where to place new files within existing layout, naming within conventions, the `## Execution` pipeline agent list).
+- **Must not invent**: Strategic direction, product behaviour, architecture changes, domain logic, security properties, business rules. If these are not provided by the handoff or source artifacts, report them as blockers.
+- **Exception**: When the handoff explicitly delegates a decision to you (e.g., "choose between X and Y"), you may make that decision.
+
+Do NOT silently change user intent or invent missing requirements.
+
+### Relevant Files Discovery
+
+Read any source artifacts cited in the handoff before planning. If the handoff references `.ai/context.md`, existing task specs, ADRs, `.ai/decisions/`, or source files, read those as canonical truth before making decisions. When the handoff notes that some context is chat-only, note this in the spec.
+
+### Single-Unit Workflow (no assigned path)
+
+- Mandatory: every task directory MUST use the `<NNN>-<task-id>` naming convention. `<NNN>` is the next available zero-padded number (001, 002, …) found by listing existing `.ai/tasks/` directories (use the `read` tool on `.ai/tasks/` or `ls .ai/tasks/` — do **not** use `glob`, which is unreliable for dot-directories).
+- Create `.ai/tasks/<NNN>-<task-id>/task-spec.md` with sections: Source Artifacts / Handoff Context, Scope, Execution, Non-Goals, Testable Acceptance Criteria (with `### Test File Paths` subsection), Inspectable Acceptance Criteria, Relevant Files, Validation Plan, Open Questions.
+- Read `.ai/context.md` (use the `read` tool — `glob` is unreliable for `.ai/` paths) for project conventions (naming, styling, file layout, test setup) before writing a task spec.
 - Read the files the orchestrator named as candidate files. Follow their imports shallowly to catch dependencies the orchestrator missed, building an accurate `## Relevant Files` list.
-- Make real architectural decisions based on conventions: which patterns to use, where new files go, what to change in existing files.
+- Make implementation-local decisions based on conventions: which patterns to use, where new files go, what to change in existing files.
 - Add decision notes under `.ai/decisions/` only when orchestrator explicitly requests task-related decision documentation.
 - Do not edit implementation files, project docs outside `.ai/`, or source code.
 - Write an `## Execution` section in every task spec. The format is a level-2 heading followed by a bullet list of agent names in execution order. Valid agent names: `test-writer`, `implementer`, `documentation`. The `## Execution` section must contain only the agent bullet list — no explanatory orchestration notes.
 
-Multi-unit decomposition:
+### Assigned-Unit Workflow
+
+When the orchestrator has provided an assigned unit scope and output path:
+
+1. Use the assigned path exactly. Do NOT compute a new `<NNN>`.
+2. Write only that unit's `task-spec.md` with sections: Source Artifacts / Handoff Context, Scope, Execution, Non-Goals, Testable Acceptance Criteria (with `### Test File Paths`), Inspectable Acceptance Criteria, Relevant Files, Validation Plan, Open Questions.
+3. Do NOT present a unit table or decompose the full request into new units.
+4. If the assigned unit boundary is provably unsafe or impossible (the unit as described cannot be implemented independently, or the boundary conflicts with the file layout or dependencies), report a planning-blocked issue describing the problem instead of silently restructuring.
+5. Read the parent manifest path if provided, plus any shared handoff context, to understand how this unit fits into the larger work.
+
+### Self-Directed Decomposition (fallback)
+
+Only used when the orchestrator did NOT provide a unit split. In this case:
 
 - Read the user's request, conversation context, and relevant source files to understand the full scope.
-- Decompose into discrete, independently describable work units. Assign each unit a short slug.
-- Identify what files each unit touches.
-- Detect file conflicts: two units touching the same file cannot run in parallel.
-- Detect true dependencies: unit Y needs unit X's output before it can start.
-- Present a unit table to the user for approval:
-
-```
-| # | Unit       | Delivers              | Depends on | Parallel with |
-|---|------------|-----------------------|------------|---------------|
-| 1 | slug-name  | one-line deliverable  | —          | 2             |
-| 2 | slug-name  | one-line deliverable  | —          | 1             |
-```
-
-- Wait for user approval before proceeding. Do not continue until the user explicitly approves the unit plan.
-- After approval, create the parent manifest at `.ai/tasks/<NNN>-<task-id>/task-spec.md` containing the unit table and execution order.
-- Create one child `task-spec.md` per unit under numeric-prefixed subdirectories. Each child task spec follows the standard spec format: Scope, Execution, Non-Goals, Testable Acceptance Criteria (with `### Test File Paths`), Inspectable Acceptance Criteria, Relevant Files.
-
-```
-.ai/tasks/<NNN>-<task-id>/
-  task-spec.md              ← parent manifest (unit table + execution order)
-  01-unitslug/
-    task-spec.md
-  02-unitslug/
-    task-spec.md
-```
+- Assess whether the work is single-unit or multi-unit.
+- **Single-unit**: Focused change touching related files. Proceed with the Single-Unit Workflow above.
+- **Multi-unit**: Complex request spanning multiple unrelated modules. Decompose into discrete units:
+
+  1. Identify independently describable work units. Assign each unit a short slug.
+  2. Identify what files each unit touches.
+  3. Detect file conflicts: two units touching the same file cannot run in parallel.
+  4. Detect true dependencies: unit Y needs unit X's output before it can start.
+  5. Present a unit table to the user for approval:
+
+  ```
+  | # | Unit       | Delivers              | Depends on | Parallel with |
+  |---|------------|-----------------------|------------|---------------|
+  | 1 | slug-name  | one-line deliverable  | —          | 2             |
+  | 2 | slug-name  | one-line deliverable  | —          | 1             |
+  ```
+
+  6. Wait for user approval before proceeding. Do not continue until the user explicitly approves the unit plan.
+  7. After approval, create the parent manifest at `.ai/tasks/<NNN>-<task-id>/task-spec.md` containing the unit table and execution order.
+  8. Create one child `task-spec.md` per unit under numeric-prefixed subdirectories. Each child task spec follows the standard spec format.
+
+  ```
+  .ai/tasks/<NNN>-<task-id>/
+    task-spec.md              ← parent manifest (unit table + execution order)
+    01-unitslug/
+      task-spec.md
+    02-unitslug/
+      task-spec.md
+  ```
 
 If scope is ambiguous, stop and report the missing decision to orchestrator instead of inventing requirements.
 

package/workflow/agents/test-writer.md

@@ -22,7 +22,7 @@ You are the Test Writer Agent. Your job is to read an approved task spec and wri
 
 Responsibilities:
 
-- Read the task spec, `.ai/context.md` test setup, existing nearby tests, public interfaces, exported types, route definitions, and test utilities needed to write realistic tests.
+- Read the task spec, `.ai/context.md` test setup (use the `read` tool — `glob` is unreliable for `.ai/` paths), existing nearby tests, public interfaces, exported types, route definitions, and test utilities needed to write realistic tests.
 - Do not read private implementation internals to mirror implementation details.
 - Write test files that encode each testable criterion as one or more test cases.
 - Name test functions descriptively so failures point clearly to the criterion they test.

package/workflow/agents/validator.md

@@ -12,11 +12,11 @@ permission:
 
 You are the Validator Agent.
 
-Own validation against the task spec. Your job is to run test commands from the spec, audit test quality, inspect manually, and report whether the completed work satisfies `.ai/tasks/<NNN>-<task-id>/task-spec.md`.
+Own validation against the task spec and any cited source artifacts. Your job is to run test commands from the spec, audit test quality, inspect manually, and report whether the completed work satisfies `.ai/tasks/<NNN>-<task-id>/task-spec.md` and any durable documentation the spec cites.
 
 Responsibilities:
 
-- Read `.ai/context.md` (only the `## Test Setup` section) for the test runner command. Read the task spec and the files listed in its `## Relevant Files`. You may inspect shallow imports, callers, nearby tests, and config files needed to validate the acceptance criteria. Avoid broad unrelated exploration.
+- Read `.ai/context.md` (use the `read` tool — `glob` is unreliable for `.ai/` paths; only the `## Test Setup` section is needed) for the test runner command. Read the task spec and the files listed in its `## Relevant Files`. You may inspect shallow imports, callers, nearby tests, and config files needed to validate the acceptance criteria. Avoid broad unrelated exploration.
 - Validate each acceptance criterion and non-goal.
 - Run the test commands from the spec's testable acceptance criteria and confirm they pass.
 - Audit test quality — spot-check test files to verify tests actually cover what the criteria ask for. Report hollow or missing tests.