refactor: rename <dispatch> to <dispatch-command> and restructure navigator orchestration

AGENTS.md

@@ -64,8 +64,8 @@ packages/opencode/.opencode/ # Generated OpenCode output for review
 - Prefer explicit subsection names like `### Load ... Context`, `### Check Blockers`, `### Delegate ...`, and `### Mark Complete And Loop` when the command coordinates multiple phases or subagents
 - Treat loader tools and provided attachments as the source of truth for orchestration inputs; avoid extra exploratory commands when an existing tool result already answers the question
 - Before delegating to a subagent, say what result should be stored and whether the workflow must stop, pause, or continue based on that result
-- Use literal `<dispatch>` tags when the workflow must forward exact text as the next user message to a subagent session; `agent` is required, the block body is the exact rendered message to send, and slash commands belong on the first line of the body when needed
-- Do not use `<task>` blocks in command docs; author navigator delegation with `<dispatch>` blocks only
+- Use literal `<dispatch-command>` tags when the workflow must forward exact text as the next user message to a subagent session; `agent` is required, the block body is the exact rendered message to send, slash commands stay literal, and only placeholders inside the body should be substituted
+- Do not use `<task>` blocks in command docs; author navigator delegation with `<dispatch-command>` blocks only
 - When a command can pause for approval or loop over repeated work, describe the resume condition and the exact cases that must STOP without mutating state
 - Use `## Additional Context` for instructions about how optional guidance, related tickets, focus areas, or other stored context should influence analysis and response formatting
 - Use `### Output` as the final workflow step to define the exact user-facing response shape, including placeholders for generated values
@@ -105,25 +105,25 @@ $ARGUMENTS
 
 ### Delegate Planning
 
-<dispatch agent="planner">
+<dispatch-command agent="planner">
 /ticket/plan
 
 Task: <task>
 Task context: <task-context>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the result as `<plan>`
 - STOP if planning is blocked or unusable
 
 ### Delegate Implementation
 
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /dev
 
 Plan: <plan>
 Constraints: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - STOP if implementation is blocked or incomplete
 
@@ -136,13 +136,13 @@ Constraints: <additional-context>
 Example delegation rule:
 
 ```text
-Before delegating, write the exact `<dispatch ...>...</dispatch>` block, say what result should be stored, and whether the workflow should continue or STOP based on that result.
+Before delegating, write the exact `<dispatch-command ...>...</dispatch-command>` block, say what result should be stored, and whether the workflow should continue or STOP based on that result.
 ```
 
 Example literal dispatch rule:
 
 ```text
-Before literal command forwarding, write the exact `<dispatch ...>...</dispatch>` block, put the slash command on the first line of the body when needed, and say what result should be stored and whether the workflow should continue or STOP based on that result.
+Before literal command forwarding, write the exact `<dispatch-command ...>...</dispatch-command>` block, put the slash command on the first line of the body when needed, substitute placeholders only, and say what result should be stored and whether the workflow should continue or STOP based on that result.
 ```
 
 ## Component Authoring

packages/core/agents/navigator.md

@@ -1,39 +1,51 @@
-You are a navigation specialist for structured, multi-step workflows.
-
-## Operating Boundaries
-
-- Follow the active command and provided context.
-- Own the workflow yourself: decide the next step, load only the local context the command requires, dispatch when the command tells you to, and keep going until the command says to stop.
-- Owning the workflow means managing step order, state, and stop conditions; it does not let you rewrite an explicit `<dispatch>` body.
-- Delegate only explicit leaf tasks when the user explicitly requests a subagent or the command explicitly requires one.
-- Gather only the context needed for the current step.
-- Preserve workflow state, ordering, stop conditions, and approval gates across the whole command.
-- Execute required user-interaction steps exactly as the active command defines them.
-- If a required interaction tool is unavailable, follow the active command's non-interactive fallback instead of pausing or inventing a question.
+You are an orchestrator for structured multi-step workflows.
+
+## Ground Rules
+
+- Follow the active command exactly.
+- Your job is orchestration: load only the context the command needs, handle workflow state, and delegate leaf work.
+- Do not do implementation, planning, or review work yourself unless the command explicitly tells you to.
+- Preserve step order, approvals, stop conditions, and stored results across the workflow.
 - If a delegated step is blocked, incomplete, or fails, stop and report it clearly.
 
-## Dispatch Execution
-
-- Treat each `<dispatch agent="AGENT_NAME">...</dispatch>` block as a literal message dispatch instruction.
-- Dispatch blocks take precedence over generic delegation guidance; the rendered body is opaque.
-- `agent` is required; invoke that exact subagent type.
-- Set `prompt` to the dispatch body exactly after variable substitution.
-- Do not add wrapper text or rewrite, summarize, interpret, expand, normalize, or improve the body.
-- Preserve line breaks and ordering exactly.
-- Send the rendered body as a real user turn to the target subagent session.
-- Never infer what a slash command means when handling a dispatch block. Forward it literally.
-- Process every valid dispatch block you receive.
-- Run independent dispatch blocks in parallel only when the workflow makes that independence clear; otherwise run them sequentially in source order.
-- If a dispatch block is malformed, report it as invalid, explain why briefly, and continue with remaining valid blocks when safe.
-- If no valid dispatch blocks are present, continue with the command workflow.
-
-## Delegation
-
-- Treat delegated work as one step inside a larger workflow, not as a handoff of orchestration responsibility.
-- For an explicit `<dispatch>` step, your job is only to render variables, send the exact body, store the result, and apply the command's continue-or-stop rules.
-- Pass only the context that task needs.
-- Use the agent type named by the command; otherwise match planner to planning, reviewer to review, and worker to implementation.
-- When a command mixes local orchestration with delegated leaf steps, complete the local steps first and delegate only the explicit leaf steps.
+## Dispatch Commands
+
+Each `<dispatch-command agent="AGENT_NAME">...</dispatch-command>` block represents a literal call to a subagent.
+
+### How to forward dispatch commands
+
+1. **Extract the agent**: Use the `agent` attribute value as `subagent_type` in the task call
+2. **Extract the body**: Use the block body (everything between the tags) as the literal `prompt`
+3. **Substitute placeholders**: Replace `<placeholder>` values inside the body with their stored values
+4. **Forward as-is**: Send the rendered text exactly as the subagent's prompt—do not expand, wrap, or modify it
+
+### Critical rules
+
+- **Do NOT look up command documentation**. Text like `/branch` or `/commit` inside the body is the literal command string to send, not a reference for you to resolve.
+- **Do NOT expand slash commands** into full documentation or workflow steps.
+- **Preserve exact formatting**: Keep line breaks, indentation, and structure intact.
+- **Run in source order** unless the workflow explicitly allows parallel execution.
+
+### Example transformation
+
+Given this block:
+```xml
+<dispatch-command agent="worker">
+/branch
+Branch naming guidance: <branch-context>
+</dispatch-command>
+```
+
+Make this task call:
+```javascript
+task({
+  description: "Ensure feature branch",
+  prompt: "/branch\nBranch naming guidance: <substituted-value>",
+  subagent_type: "worker"
+})
+```
+
+Notice: The `/branch` stays literal. You do not fetch branch command docs or expand it into workflow steps.
 
 ## Output
 

packages/core/commands/index.ts

@@ -84,7 +84,7 @@ export const commandDefinitions: Record<string, CommandDefinition> = {
   },
   "ticket/dev": {
     description: "Implement a ticket and create a PR",
-    agent: "worker",
+    agent: "navigator",
     templatePath: "commands/ticket/dev.md",
   },
   "ticket/create": {

packages/core/commands/ship.md

@@ -4,7 +4,7 @@ Ship the current work by delegating branch creation, commit creation, and PR cre
 
 ## Additional Context
 
-Use `<branch-context>` to steer delegated branch naming. Use `<additional-context>` to refine the delegated commit and PR summaries. Pass `<base>` through to PR creation when it was provided. This command is delegation-first: send each `<dispatch>` body literally and use the subagent result as the source of truth for the next step.
+Use `<branch-context>` to steer delegated branch naming. Use `<additional-context>` to refine the delegated commit and PR summaries. Pass `<base>` through to PR creation when it was provided.
 
 ## Workflow
 
@@ -23,10 +23,10 @@ $ARGUMENTS
 
 ### Ensure Feature Branch
 
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /branch
 Branch naming guidance: <branch-context>
-</dispatch>
+</dispatch-command>
 
 - Store the subagent result as `<branch-result>`
 - If `<branch-result>` is blocked or incomplete, STOP and report the branch blocker
@@ -35,10 +35,10 @@ Branch naming guidance: <branch-context>
 
 ### Delegate Commit
 
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /commit
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the subagent result as `<commit-result>`
 
@@ -48,11 +48,11 @@ Additional context: <additional-context>
 
 ### Delegate PR Creation
 
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /pr/create
 Base branch: <base>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the subagent result as `<pr-result>`
 

packages/core/commands/ticket/dev.md

@@ -31,57 +31,49 @@ $ARGUMENTS
 
 ### Delegate Implementation
 
-- Before delegating, send the exact dispatch block below
-
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /dev
 Ticket reference: <ticket-ref>
 Ticket context: <ticket-context>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the result as `<implementation-result>`
 - If `<implementation-result>` is blocked or incomplete, STOP and report the implementation blocker
 
 ### Delegate Branch Creation
 
-- Before delegating, send the exact dispatch block below
-
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /branch
 Branch naming guidance: <ticket-summary>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the result as `<branch-result>`
 - If `<branch-result>` is blocked or incomplete, STOP and report the branch blocker
 - If `<branch-result>` says branching was skipped because the current branch already looks like a work branch, continue
 
 ### Delegate Commit And Push
 
-- Before delegating, send the exact dispatch block below
-
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /commit-and-push
 Ticket reference: <ticket-ref>
 Ticket summary: <ticket-summary>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the result as `<commit-result>`
 - If `<commit-result>` is blocked or incomplete, STOP and report the commit or push blocker
 - If `<commit-result>` says there was nothing to commit or push, continue to PR creation so already-committed branch work can still be shipped
 
 ### Delegate PR Creation
 
-- Before delegating, send the exact dispatch block below
-
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /pr/create
 Ticket reference: <ticket-ref>
 Ticket context: <ticket-context>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the result as `<pr-result>`
 - If `<pr-result>` is blocked or incomplete, STOP and report the PR blocker

packages/core/commands/todo.md

@@ -41,12 +41,12 @@ $ARGUMENTS
 
 ### Delegate Planning
 
-<dispatch agent="planner">
+<dispatch-command agent="planner">
 /ticket/plan
 Task: <task>
 Task context: <task-context>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Ask the planner for a concise implementation plan with clear scope, risks, and validation steps
 - Store the result as `<plan>`
@@ -63,14 +63,14 @@ Additional context: <additional-context>
     - `Revise` - update the plan based on feedback
 - custom answers enabled so the user can provide specific plan changes
 - If the user requests changes, store that feedback as `<user-answer>`
-<dispatch agent="planner">
+<dispatch-command agent="planner">
 /ticket/plan
 Task: <task>
 Task context: <task-context>
 Current plan: <plan>
 Plan feedback: <user-answer>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the revised result as `<plan>` and continue the review loop
 - If the revised planner result is blocked or unusable, store that blocker as `<pause-reason>`, then STOP and report it before continuing the review loop
@@ -79,24 +79,24 @@ Additional context: <additional-context>
 
 ### Delegate Implementation
 
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /dev
 Plan: <plan>
 Task: <task>
 Task context: <task-context>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the subagent result as `<implementation-result>`
 - If `<implementation-result>` is incomplete, blocked, or fails validation, store the issue as `<pause-reason>`, then STOP and report it without marking the task complete
 
 ### Delegate Commit
 
-<dispatch agent="worker">
+<dispatch-command agent="worker">
 /commit
 Task: <task>
 Additional context: <additional-context>
-</dispatch>
+</dispatch-command>
 
 - Store the subagent result as `<commit-result>`
 - If `<commit-result>` does not succeed, store the commit status as `<pause-reason>`, then STOP and report it without marking the task complete