opencode-dispatcher 0.2.4 → 0.2.8

package/README.md

@@ -184,15 +184,18 @@ The documentation agent is used when the task needs README updates, project cont
 
 The research agent is used when a decision depends on external facts such as official documentation, vendor behaviour, pricing, APIs, or current best practices.
 
-### Bootstrap and Shipping
+### Bootstrap, Configuration, and Shipping
 
-| Agent   | Role                             | Used When                 |
-| ------- | -------------------------------- | ------------------------- |
-| Init    | Bootstraps `.ai/context.md`      | First use in a project    |
-| Shipper | Handles git commit and push only | When explicitly requested |
+| Agent        | Role                                                | Used When                                      |
+| ------------ | --------------------------------------------------- | ---------------------------------------------- |
+| Init         | Bootstraps `.ai/context.md`                         | First use in a project                         |
+| Model Config | Assigns models to specific agents in project config | When per-agent model overrides are needed      |
+| Shipper      | Handles git commit and push only                    | When explicitly requested                      |
 
 The init agent is used when a project does not yet have `.ai/context.md`.
 
+The model config agent configures per-agent models in `opencode.jsonc`.
+
 The shipper is never used automatically. It only commits or pushes when you explicitly ask for git shipping work.
 
 ## Common Routes
@@ -314,7 +317,7 @@ Stores the approved task scope, including:
 
 * scope
 * non-goals
-* testable acceptance criteria
+* testable acceptance criteria (includes test file path hints)
 * inspectable acceptance criteria
 * relevant files
 * validation plan
@@ -491,6 +494,15 @@ Install it from any project with:
 npx opencode-dispatcher install
 ```
 
+## Security & Permissions
+
+Dispatcher enforces strict boundaries through OpenCode's permission model:
+
+* The orchestrator cannot run arbitrary shell commands, scripts, or write to files. It uses a strict bash whitelist limited to read-only informational tools (`ls`, `git status`, `which`, etc.).
+* Subagents only get the permissions they need (e.g. shipper is strictly gated around specific git operations).
+* To reduce excessive permission prompts during standard development cycles, the `implementer` and `validator` agents are granted broad `bash` execution allowances so they can seamlessly run test, build, and dev commands.
+* The `edit: deny` constraint is properly enforced because the shell escape hatch is sealed by the `bash` permission whitelist.
+
 ## Limitations
 
 * Managed global agent paths are backed up, then overlaid with Dispatcher files.
@@ -511,3 +523,26 @@ Dispatcher is probably unnecessary when you only need:
 * work where formal task artifacts would slow you down
 
 Use Dispatcher when the structure is worth it. Use the fast path or plain OpenCode when it is not.
+
+## Version History
+
+* **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-dispatcher",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "description": "A low-context OpenCode dispatcher workflow with orchestrator agents and task artifacts.",
   "type": "module",
   "bin": {

package/workflow/agents/executor.md

@@ -7,7 +7,6 @@ permission:
     "*": allow
   edit:
     "*": allow
-    ".ai/**": deny
 ---
 
 You are the Executor Agent.

package/workflow/agents/init.md

@@ -21,7 +21,8 @@ Responsibilities:
   - Naming conventions: casing, file and component naming (`## Conventions`).
   - File layout: co-located tests, file-per-component, directory structure (`## Conventions`).
   - Any project-specific rules: import style, hook ordering, error handling (`## Conventions`).
-- Create `.ai/context.md` with `## Test Setup` and `## Conventions` sections using the user's exact answers.
+  - Agy integration: ask if they want to enable Antigravity CLI integration (`agy: enabled` flag in `## Workflow`). When enabled, the implementer agent can offload work through `agy` to split quota usage across models.
+- Create `.ai/context.md` with `## Test Setup`, `## Conventions`, and `## Workflow` sections using the user's exact answers.
 - Do not invent project facts. Do not create any other files.
 
 Default report back:

package/workflow/agents/model-config.md

@@ -19,12 +19,21 @@ Own per-agent model assignment in the project's opencode config. When delegated
 
 Responsibilities:
 
-- Run `opencode models` to list available models on the system.
+- Run `opencode models --verbose` to list available models and their variants on the system.
 - Check for an existing opencode config at `opencode.jsonc` or `.opencode/opencode.jsonc` (in that order of preference).
-- Present the user with the list of installed Dispatcher agents and ask which agents they want to configure.
+- Present the user with the list of installed Dispatcher subagents (excluding the orchestrator, whose model is chosen directly by the user) and ask which agents they want to configure.
 - For each selected agent, ask which model to assign (from the available models list).
-- Write `agent.<name>.model` entries into the project's opencode config, preserving all existing config content exactly as-is.
-- If no opencode config exists, create one with only the `agent.<name>.model` entries.
+- For each assigned model, parse its `variants` field from the verbose output. If the model has variants (non-empty object), present the available variant names and ask the user to pick one or skip. If the model has no variants (empty `{}`), skip silently without prompting. If the user skips, do not write a `variant` field for that agent.
+- Write `agent.<name>.model` and optionally `agent.<name>.variant` entries into the project's opencode config, preserving all existing config content exactly as-is. Use the target format:
+  ```jsonc
+  "agent": {
+    "orchestrator": {
+      "model": "opencode-go/deepseek-v4-pro",
+      "variant": "medium"
+    }
+  }
+  ```
+- If no opencode config exists, create one with only the `agent.<name>.model` (and `agent.<name>.variant` where applicable) entries.
 - Report back to the orchestrator with a summary of what was configured.
 
 Boundaries:
@@ -32,11 +41,13 @@ Boundaries:
 - Do not edit any files other than the project's opencode config (`opencode.jsonc` or `.opencode/opencode.jsonc`).
 - Do not delegate to other agents (no `task` permission).
 - Do not modify code, tests, documentation, `.ai/` artifacts, or other agent definitions.
+- Do not invent variant names — only use variant names shown in `opencode models --verbose` output.
+- Do not write a `variant` field for models that have no variants (empty `{}`).
 
 Default report back:
 
 - Path of the config file edited (or created).
-- List of agents configured and their assigned models.
+- List of agents configured and their assigned models (and variants, when assigned).
 - Any issues encountered (e.g., config conflicts, missing models).
 
 (End of file - total 37 lines)

package/workflow/agents/orchestrator.md

@@ -59,7 +59,7 @@ Hard boundary: do not implement substantial code, UI, docs, or config changes yo
 Artifact source-of-truth rules:
 
 - Do not rely on chat-only artifacts for substantial work.
-- Project `.ai/context.md` captures durable project truth: shared language, architecture facts, conventions, constraints, and stable decisions.
+- Project `.ai/context.md` captures durable project truth: shared language, architecture facts, conventions, constraints, stable decisions, and workflow flags (like `agy: enabled`).
 - `.ai/tasks/<NNN>-<task-id>/task-spec.md` captures task truth: approved scope, acceptance criteria, constraints, relevant files, and validation plan.
 - Task reports live beside the task spec: `implementation-report.md`, `documentation-report.md`, and `validation-report.md`.
 
@@ -110,11 +110,14 @@ Ask one focused question only when the missing answer would change scope, safety
 Choose the smallest safe path:
 
 - Answer directly when no file changes are needed.
-- Use executor when the edit is exact, single-file, low-risk, and unambiguous.
+- Use executor when the edit is exact, low-risk, and unambiguous (file count is irrelevant).
 - Use research when current facts, external docs, pricing, vendor behaviour, or source-backed confidence matter.
-- Use task-planner when the work is multi-file, behaviour-changing, risky, unclear, or needs acceptance criteria.
+- Use task-planner when the work is behaviour-changing, risky, unclear, needs acceptance criteria, or benefits from a written plan before implementation.
 - Use shipper only when the user explicitly asks to commit or push.
 - Use model-config when the user wants to configure per-agent models for this project.
+### Common Requests
+
+- **Enable agy / enable antigravity**: Add `agy: enabled` to `.ai/context.md` under `## Workflow`. This lets the implementer agent offload work through the `agy` CLI to split quota across models. Route to executor.
 
 ### DELEGATE
 
@@ -132,6 +135,14 @@ Delegate to the specialist that owns the next action.
 
 Always return control to yourself after each subagent result.
 
+Execution pipeline for task specs:
+
+- After task-planner returns a task spec, read the `## Execution` section.
+- Spawn agents in the listed order, one at a time, waiting for each to complete before starting the next (sequential pipeline).
+- After the pipeline completes, always spawn `validator` as the final agent.
+- If the `## Execution` section is missing or empty, do not spawn any agents; report the gap to the user.
+- Never assume a default agent sequence — always read the pipeline from the spec.
+
 ### REVIEW
 
 After non-trivial implementation or documentation work, validate against the task spec.

package/workflow/agents/shipper.md

@@ -15,6 +15,12 @@ permission:
     "git add *": allow
     "git commit *": allow
     "git push*": allow
+    "find *": allow
+    "echo *": allow
+    "sort *": allow
+    "git config*": allow
+    "ls": allow
+    "ls *": allow
     "git reset*": deny
     "git rebase*": deny
     "git clean*": deny

package/workflow/agents/task-planner.md

@@ -23,12 +23,17 @@ On every invocation, assess whether the work is a single-unit task or a multi-un
 
 Single-unit workflow:
 
-- Create `.ai/tasks/<NNN>-<task-id>/task-spec.md` with sections: Scope, 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.
+- 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.
 - 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.
 - 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`. Never include `validator` — the orchestrator appends it automatically. Decision logic for choosing the pipeline:
+  - Feature/fix with testable acceptance criteria → `test-writer`, then `implementer`.
+  - Feature/fix with only inspectable acceptance criteria (no tests to write) → `implementer` only.
+  - Documentation task → `documentation` only.
+  - Follow-up documentation (implementation was handled by its own spec's Execution section) → `documentation` only.
 
 Multi-unit decomposition:
 
@@ -48,7 +53,7 @@ Multi-unit decomposition:
 
 - 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, Non-Goals, Testable Acceptance Criteria (with `### Test File Paths`), Inspectable Acceptance Criteria, Relevant Files.
+- 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>/