From 3bc775754b0dda11398367265a81d3a3e223d571 Mon Sep 17 00:00:00 2001 From: dbpolito Date: Sat, 28 Mar 2026 11:48:50 -0300 Subject: [PATCH 1/2] refactor(dispatch-command): rename to across all templates and docs - Update agent syntax from to in all command templates - Simplify navigator agent role to focus on orchestration - Change ticket/dev command agent from worker to navigator - Update tests to reflect new navigator behavior expectations - Sync generated opencode output with core template changes - Update documentation to match new dispatch-command syntax --- AGENTS.md | 16 +++---- packages/core/agents/navigator.md | 44 ++++++------------- packages/core/commands/index.ts | 2 +- packages/core/commands/ship.md | 14 +++--- packages/core/commands/ticket/dev.md | 24 ++++------ packages/core/commands/todo.md | 16 +++---- .../opencode/.opencode/agents/navigator.md | 44 ++++++------------- packages/opencode/.opencode/commands/ship.md | 14 +++--- .../opencode/.opencode/commands/ticket/dev.md | 26 ++++------- packages/opencode/.opencode/commands/todo.md | 16 +++---- packages/opencode/test/agents-config.test.ts | 6 +-- .../opencode/test/commands-config.test.ts | 37 ++++++++-------- .../web/src/components/CommandShowcase.astro | 2 +- .../docs/docs/reference/agents/index.mdx | 2 +- .../docs/docs/reference/agents/navigator.mdx | 8 ++-- .../docs/docs/reference/commands/index.mdx | 6 +-- .../docs/docs/reference/commands/ship.mdx | 6 +-- .../docs/reference/commands/ticket-dev.mdx | 17 ++++--- .../docs/docs/reference/commands/todo.mdx | 6 +-- 19 files changed, 129 insertions(+), 177 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e11c909..4a52fd1 100644 --- a/AGENTS.md +++ b/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 `` 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 `` blocks in command docs; author navigator delegation with `` blocks only +- Use literal `` 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 `` blocks in command docs; author navigator delegation with `` 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 - + /ticket/plan Task: Task context: Additional context: - + - Store the result as `` - STOP if planning is blocked or unusable ### Delegate Implementation - + /dev Plan: Constraints: - + - STOP if implementation is blocked or incomplete @@ -136,13 +136,13 @@ Constraints: Example delegation rule: ```text -Before delegating, write the exact `...` block, say what result should be stored, and whether the workflow should continue or STOP based on that result. +Before delegating, write the exact `...` 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 `...` 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 `...` 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 diff --git a/packages/core/agents/navigator.md b/packages/core/agents/navigator.md index 31cd368..90a1977 100644 --- a/packages/core/agents/navigator.md +++ b/packages/core/agents/navigator.md @@ -1,39 +1,23 @@ -You are a navigation specialist for structured, multi-step workflows. +You are an orchestrator for structured multi-step workflows. -## Operating Boundaries +## Ground Rules -- 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 `` 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. +- 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 +## Dispatch Commands -- Treat each `...` block as a literal message dispatch instruction. -- Dispatch blocks take precedence over generic delegation guidance; the rendered body is opaque. +- Treat each `...` block as a literal subagent call. - `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 `` 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. +- Text starting with `/` inside the body is a native subagent command, not a file reference for you to resolve. +- Do not look up or expand slash commands inside a `` block. +- Only substitute placeholders inside the body, then forward the rendered text literally. +- Preserve line breaks and ordering exactly. Do not add wrapper text or rewrite the body. +- Run independent `` blocks in parallel only when the workflow clearly allows it; otherwise run them in source order. +- If a `` block is malformed, report it briefly and continue with remaining valid blocks when safe. ## Output diff --git a/packages/core/commands/index.ts b/packages/core/commands/index.ts index 886f7cd..ab8f1ec 100644 --- a/packages/core/commands/index.ts +++ b/packages/core/commands/index.ts @@ -84,7 +84,7 @@ export const commandDefinitions: Record = { }, "ticket/dev": { description: "Implement a ticket and create a PR", - agent: "worker", + agent: "navigator", templatePath: "commands/ticket/dev.md", }, "ticket/create": { diff --git a/packages/core/commands/ship.md b/packages/core/commands/ship.md index e03f270..7857deb 100644 --- a/packages/core/commands/ship.md +++ b/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 `` to steer delegated branch naming. Use `` to refine the delegated commit and PR summaries. Pass `` through to PR creation when it was provided. This command is delegation-first: send each `` body literally and use the subagent result as the source of truth for the next step. +Use `` to steer delegated branch naming. Use `` to refine the delegated commit and PR summaries. Pass `` through to PR creation when it was provided. ## Workflow @@ -23,10 +23,10 @@ $ARGUMENTS ### Ensure Feature Branch - + /branch Branch naming guidance: - + - Store the subagent result as `` - If `` is blocked or incomplete, STOP and report the branch blocker @@ -35,10 +35,10 @@ Branch naming guidance: ### Delegate Commit - + /commit Additional context: - + - Store the subagent result as `` @@ -48,11 +48,11 @@ Additional context: ### Delegate PR Creation - + /pr/create Base branch: Additional context: - + - Store the subagent result as `` diff --git a/packages/core/commands/ticket/dev.md b/packages/core/commands/ticket/dev.md index d793dde..14172dc 100644 --- a/packages/core/commands/ticket/dev.md +++ b/packages/core/commands/ticket/dev.md @@ -31,27 +31,23 @@ $ARGUMENTS ### Delegate Implementation -- Before delegating, send the exact dispatch block below - - + /dev Ticket reference: Ticket context: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the implementation blocker ### Delegate Branch Creation -- Before delegating, send the exact dispatch block below - - + /branch Branch naming guidance: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the branch blocker @@ -59,14 +55,12 @@ Additional context: ### Delegate Commit And Push -- Before delegating, send the exact dispatch block below - - + /commit-and-push Ticket reference: Ticket summary: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the commit or push blocker @@ -74,14 +68,12 @@ Additional context: ### Delegate PR Creation -- Before delegating, send the exact dispatch block below - - + /pr/create Ticket reference: Ticket context: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the PR blocker diff --git a/packages/core/commands/todo.md b/packages/core/commands/todo.md index de04e65..511daff 100644 --- a/packages/core/commands/todo.md +++ b/packages/core/commands/todo.md @@ -41,12 +41,12 @@ $ARGUMENTS ### Delegate Planning - + /ticket/plan Task: Task context: Additional context: - + - Ask the planner for a concise implementation plan with clear scope, risks, and validation steps - Store the result as `` @@ -63,14 +63,14 @@ 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 `` - + /ticket/plan Task: Task context: Current plan: Plan feedback: Additional context: - + - Store the revised result as `` and continue the review loop - If the revised planner result is blocked or unusable, store that blocker as ``, then STOP and report it before continuing the review loop @@ -79,24 +79,24 @@ Additional context: ### Delegate Implementation - + /dev Plan: Task: Task context: Additional context: - + - Store the subagent result as `` - If `` is incomplete, blocked, or fails validation, store the issue as ``, then STOP and report it without marking the task complete ### Delegate Commit - + /commit Task: Additional context: - + - Store the subagent result as `` - If `` does not succeed, store the commit status as ``, then STOP and report it without marking the task complete diff --git a/packages/opencode/.opencode/agents/navigator.md b/packages/opencode/.opencode/agents/navigator.md index 82c798e..eda4de0 100644 --- a/packages/opencode/.opencode/agents/navigator.md +++ b/packages/opencode/.opencode/agents/navigator.md @@ -8,42 +8,26 @@ permission: todowrite: allow --- -You are a navigation specialist for structured, multi-step workflows. +You are an orchestrator for structured multi-step workflows. -## Operating Boundaries +## Ground Rules -- 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 `` 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. +- 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 +## Dispatch Commands -- Treat each `...` block as a literal message dispatch instruction. -- Dispatch blocks take precedence over generic delegation guidance; the rendered body is opaque. +- Treat each `...` block as a literal subagent call. - `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 `` 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. +- Text starting with `/` inside the body is a native subagent command, not a file reference for you to resolve. +- Do not look up or expand slash commands inside a `` block. +- Only substitute placeholders inside the body, then forward the rendered text literally. +- Preserve line breaks and ordering exactly. Do not add wrapper text or rewrite the body. +- Run independent `` blocks in parallel only when the workflow clearly allows it; otherwise run them in source order. +- If a `` block is malformed, report it briefly and continue with remaining valid blocks when safe. ## Output diff --git a/packages/opencode/.opencode/commands/ship.md b/packages/opencode/.opencode/commands/ship.md index 1aabed0..84b0378 100644 --- a/packages/opencode/.opencode/commands/ship.md +++ b/packages/opencode/.opencode/commands/ship.md @@ -9,7 +9,7 @@ Ship the current work by delegating branch creation, commit creation, and PR cre ## Additional Context -Use `` to steer delegated branch naming. Use `` to refine the delegated commit and PR summaries. Pass `` through to PR creation when it was provided. This command is delegation-first: send each `` body literally and use the subagent result as the source of truth for the next step. +Use `` to steer delegated branch naming. Use `` to refine the delegated commit and PR summaries. Pass `` through to PR creation when it was provided. ## Workflow @@ -28,10 +28,10 @@ $ARGUMENTS ### Ensure Feature Branch - + /branch Branch naming guidance: - + - Store the subagent result as `` - If `` is blocked or incomplete, STOP and report the branch blocker @@ -40,10 +40,10 @@ Branch naming guidance: ### Delegate Commit - + /commit Additional context: - + - Store the subagent result as `` @@ -53,11 +53,11 @@ Additional context: ### Delegate PR Creation - + /pr/create Base branch: Additional context: - + - Store the subagent result as `` diff --git a/packages/opencode/.opencode/commands/ticket/dev.md b/packages/opencode/.opencode/commands/ticket/dev.md index 2556245..0d23ee8 100644 --- a/packages/opencode/.opencode/commands/ticket/dev.md +++ b/packages/opencode/.opencode/commands/ticket/dev.md @@ -1,6 +1,6 @@ --- description: Implement a ticket and create a PR -agent: worker +agent: navigator --- ## Goal @@ -46,27 +46,23 @@ $ARGUMENTS ### Delegate Implementation -- Before delegating, send the exact dispatch block below - - + /dev Ticket reference: Ticket context: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the implementation blocker ### Delegate Branch Creation -- Before delegating, send the exact dispatch block below - - + /branch Branch naming guidance: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the branch blocker @@ -74,14 +70,12 @@ Additional context: ### Delegate Commit And Push -- Before delegating, send the exact dispatch block below - - + /commit-and-push Ticket reference: Ticket summary: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the commit or push blocker @@ -89,14 +83,12 @@ Additional context: ### Delegate PR Creation -- Before delegating, send the exact dispatch block below - - + /pr/create Ticket reference: Ticket context: Additional context: - + - Store the result as `` - If `` is blocked or incomplete, STOP and report the PR blocker diff --git a/packages/opencode/.opencode/commands/todo.md b/packages/opencode/.opencode/commands/todo.md index 6855fae..cb87b86 100644 --- a/packages/opencode/.opencode/commands/todo.md +++ b/packages/opencode/.opencode/commands/todo.md @@ -46,12 +46,12 @@ $ARGUMENTS ### Delegate Planning - + /ticket/plan Task: Task context: Additional context: - + - Ask the planner for a concise implementation plan with clear scope, risks, and validation steps - Store the result as `` @@ -68,14 +68,14 @@ 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 `` - + /ticket/plan Task: Task context: Current plan: Plan feedback: Additional context: - + - Store the revised result as `` and continue the review loop - If the revised planner result is blocked or unusable, store that blocker as ``, then STOP and report it before continuing the review loop @@ -84,24 +84,24 @@ Additional context: ### Delegate Implementation - + /dev Plan: Task: Task context: Additional context: - + - Store the subagent result as `` - If `` is incomplete, blocked, or fails validation, store the issue as ``, then STOP and report it without marking the task complete ### Delegate Commit - + /commit Task: Additional context: - + - Store the subagent result as `` - If `` does not succeed, store the commit status as ``, then STOP and report it without marking the task complete diff --git a/packages/opencode/test/agents-config.test.ts b/packages/opencode/test/agents-config.test.ts index 0984dcc..9a48f8d 100644 --- a/packages/opencode/test/agents-config.test.ts +++ b/packages/opencode/test/agents-config.test.ts @@ -54,9 +54,9 @@ describe("applyAgentsConfig", () => { todowrite: "allow", }); assert.equal(cfg.agent.worker?.prompt, undefined); - assert.match(cfg.agent.navigator?.prompt ?? "", /navigation specialist/i); - assert.match(cfg.agent.navigator?.prompt ?? "", /delegate only explicit leaf tasks/i); - assert.match(cfg.agent.navigator?.prompt ?? "", /complete the local steps first/i); + assert.match(cfg.agent.navigator?.prompt ?? "", /orchestrator/i); + assert.match(cfg.agent.navigator?.prompt ?? "", /do not do implementation, planning, or review work yourself/i); + assert.match(cfg.agent.navigator?.prompt ?? "", /do not look up or expand slash commands/i); assert.match(cfg.agent.reviewer?.prompt ?? "", /Never switch branches/i); }); diff --git a/packages/opencode/test/commands-config.test.ts b/packages/opencode/test/commands-config.test.ts index 30d15ac..6447348 100644 --- a/packages/opencode/test/commands-config.test.ts +++ b/packages/opencode/test/commands-config.test.ts @@ -62,6 +62,7 @@ describe("applyCommandsConfig", () => { assert.equal(cfg.command!["branch"]?.agent, "worker"); assert.equal(cfg.command!["pr/create"]?.agent, "worker"); assert.equal(cfg.command!["ticket/create"]?.agent, "worker"); + assert.equal(cfg.command!["ticket/dev"]?.agent, "navigator"); assert.equal(cfg.command!["ticket/plan"]?.agent, "planner"); assert.equal(cfg.command!["ticket/plan-and-sync"]?.agent, "planner"); assert.equal(cfg.command!["ask"]?.agent, "worker"); @@ -420,7 +421,7 @@ describe("applyCommandsConfig", () => { assert.ok(cfg.command!["review"]?.template); }); - test("embeds literal dispatch blocks in ship command", async () => { + test("embeds literal dispatch-command blocks in ship command", async () => { delete process.env.CI; const cfg: { command?: Record } = {}; @@ -432,13 +433,13 @@ describe("applyCommandsConfig", () => { assert.match(shipTemplate, /## Goal/); assert.match(shipTemplate, /Ship the current work by delegating/); assert.match(shipTemplate, /Ensure Feature Branch/); - assert.match(shipTemplate, //); - assert.match(shipTemplate, /\n\/branch\nBranch naming guidance: \n<\/dispatch>/); + assert.match(shipTemplate, //); + assert.match(shipTemplate, /\n\/branch\nBranch naming guidance: \n<\/dispatch-command>/); assert.match(shipTemplate, /Store the subagent result as ``/); assert.match(shipTemplate, /Store the subagent result as ``/); - assert.match(shipTemplate, /\n\/commit\nAdditional context: \n<\/dispatch>/); + assert.match(shipTemplate, /\n\/commit\nAdditional context: \n<\/dispatch-command>/); assert.match(shipTemplate, /Store the subagent result as ``/); - assert.match(shipTemplate, /\n\/pr\/create\nBase branch: \nAdditional context: \n<\/dispatch>/); + assert.match(shipTemplate, /\n\/pr\/create\nBase branch: \nAdditional context: \n<\/dispatch-command>/); assert.doesNotMatch(shipTemplate, /<%/); }); @@ -451,13 +452,13 @@ describe("applyCommandsConfig", () => { assert.ok(cfg.command); const devTemplate = cfg.command!["dev"].template; - + // Should have replaced components assert.match(devTemplate, /Development Flow Navigation Guide/); // PR Author content is now inline in pr/create, not embedded in dev assert.match(devTemplate, /## Goal/); assert.match(devTemplate, /Implement a feature or fix/); - + assert.doesNotMatch(devTemplate, /<%/); }); @@ -509,17 +510,17 @@ describe("applyCommandsConfig", () => { // PR Author content is now inline in pr/create, not embedded here assert.match(ticketDevTemplate, /## Goal/); assert.match(ticketDevTemplate, /Implement a ticket/); - assert.match(ticketDevTemplate, //); - assert.match(ticketDevTemplate, /\n\/dev\nTicket reference: \nTicket context: \nAdditional context: \n<\/dispatch>/); - assert.match(ticketDevTemplate, /\n\/branch\nBranch naming guidance: \nAdditional context: \n<\/dispatch>/); - assert.match(ticketDevTemplate, /\n\/commit-and-push\nTicket reference: \nTicket summary: \nAdditional context: \n<\/dispatch>/); - assert.match(ticketDevTemplate, /\n\/pr\/create\nTicket reference: \nTicket context: \nAdditional context: \n<\/dispatch>/); + assert.match(ticketDevTemplate, //); + assert.match(ticketDevTemplate, /\n\/dev\nTicket reference: \nTicket context: \nAdditional context: \n<\/dispatch-command>/); + assert.match(ticketDevTemplate, /\n\/branch\nBranch naming guidance: \nAdditional context: \n<\/dispatch-command>/); + assert.match(ticketDevTemplate, /\n\/commit-and-push\nTicket reference: \nTicket summary: \nAdditional context: \n<\/dispatch-command>/); + assert.match(ticketDevTemplate, /\n\/pr\/create\nTicket reference: \nTicket context: \nAdditional context: \n<\/dispatch-command>/); assert.doesNotMatch(ticketDevTemplate, / { + test("embeds literal dispatch-command blocks in todo command", async () => { delete process.env.CI; const cfg: { command?: Record } = {}; @@ -530,12 +531,12 @@ describe("applyCommandsConfig", () => { assert.match(todoTemplate, /## Goal/); assert.match(todoTemplate, /Work through a todo file one pending item at a time/); - assert.match(todoTemplate, //); - assert.match(todoTemplate, /\n\/ticket\/plan\nTask: \nTask context: \nAdditional context: \n<\/dispatch>/); - assert.match(todoTemplate, //); + assert.match(todoTemplate, //); + assert.match(todoTemplate, /\n\/ticket\/plan\nTask: \nTask context: \nAdditional context: \n<\/dispatch-command>/); + assert.match(todoTemplate, //); assert.match(todoTemplate, /Current plan: \nPlan feedback: /); - assert.match(todoTemplate, /\n\/dev\nPlan: \nTask: \nTask context: \nAdditional context: \n<\/dispatch>/); - assert.match(todoTemplate, /\n\/commit\nTask: \nAdditional context: \n<\/dispatch>/); + assert.match(todoTemplate, /\n\/dev\nPlan: \nTask: \nTask context: \nAdditional context: \n<\/dispatch-command>/); + assert.match(todoTemplate, /\n\/commit\nTask: \nAdditional context: \n<\/dispatch-command>/); assert.doesNotMatch(todoTemplate, /` bodies to subagents when commands require delegation. +Orchestrates structured multi-step workflows, preserves state and stop conditions, and forwards literal `` bodies to subagents without expanding slash commands. ### `planner` diff --git a/packages/web/src/content/docs/docs/reference/agents/navigator.mdx b/packages/web/src/content/docs/docs/reference/agents/navigator.mdx index 9c7d0d0..3b47da4 100644 --- a/packages/web/src/content/docs/docs/reference/agents/navigator.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/navigator.mdx @@ -5,17 +5,17 @@ description: Orchestrator agent for structured multi-step workflows. ## Role -`navigator` owns multi-step command workflows locally. It keeps state, ordering, approval gates, and stop conditions in one place instead of handing orchestration off to subagents. +`navigator` is the orchestrator. It keeps state, ordering, approval gates, and stop conditions, while delegating leaf work to subagents. ## Best for - pause-and-resume workflows -- stepwise orchestration such as `/ship` and `/todo` +- stepwise orchestration such as `/ship`, `/todo`, and `/ticket/dev` - commands that mix local state handling with delegated leaf work ## Key behavior -- forwards literal `` bodies exactly after variable substitution +- forwards literal `` bodies after placeholder substitution only - delegates only explicit focused leaf work -- preserves workflow ownership even when subagents are used +- does not expand slash commands inside dispatch bodies - stops and reports blockers when a delegated step fails or returns incomplete work diff --git a/packages/web/src/content/docs/docs/reference/commands/index.mdx b/packages/web/src/content/docs/docs/reference/commands/index.mdx index 7cf6e3b..0f2f611 100644 --- a/packages/web/src/content/docs/docs/reference/commands/index.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/index.mdx @@ -16,7 +16,7 @@ Kompass ships workflow-oriented commands authored as explicit templates in `pack - each command is a documented workflow, not an opaque prompt - placeholders like ``, ``, and `` are normalized before execution -- navigator workflows orchestrate locally and delegate focused leaf work with literal `` blocks +- navigator workflows orchestrate locally and delegate focused leaf work with literal `` blocks - outputs are deterministic, reviewable, and usually terminal ## Core workflows @@ -89,11 +89,11 @@ Creates a ticket summarizing the current change comparison. ### `/ticket/dev` -Implements a ticket by orchestrating `/dev`, `/branch`, `/commit-and-push`, and `/pr/create`. +Implements a ticket with navigator-managed orchestration across `/dev`, `/branch`, `/commit-and-push`, and `/pr/create`. - usage: `/ticket/dev ` - arguments: ticket reference, URL, file path, or raw request -- expected tools: `ticket_load`, delegated `/dev`, delegated `/branch`, delegated `/commit-and-push`, delegated `/pr/create` +- expected tools: `ticket_load`, `` to `/dev`, `` to `/branch`, `` to `/commit-and-push`, `` to `/pr/create` ### `/ticket/plan` diff --git a/packages/web/src/content/docs/docs/reference/commands/ship.mdx b/packages/web/src/content/docs/docs/reference/commands/ship.mdx index 9729b58..781af27 100644 --- a/packages/web/src/content/docs/docs/reference/commands/ship.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/ship.mdx @@ -22,6 +22,6 @@ Use `/ship` when you want a fast path from current work to a PR through local or ## Common tools -- `dispatch(/branch)` -- `dispatch(/commit)` -- `dispatch(/pr/create)` +- `dispatch-command(/branch)` +- `dispatch-command(/commit)` +- `dispatch-command(/pr/create)` diff --git a/packages/web/src/content/docs/docs/reference/commands/ticket-dev.mdx b/packages/web/src/content/docs/docs/reference/commands/ticket-dev.mdx index 32a822f..80fa152 100644 --- a/packages/web/src/content/docs/docs/reference/commands/ticket-dev.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/ticket-dev.mdx @@ -5,7 +5,7 @@ description: Implement a ticket by orchestrating development, branching, commit- ## Purpose -Use `/ticket/dev` when implementation starts from a tracked ticket and should run through shipping. +Use `/ticket/dev` when implementation starts from a tracked ticket and should run through shipping under navigator-managed orchestration. ## Usage @@ -16,15 +16,14 @@ Use `/ticket/dev` when implementation starts from a tracked ticket and should ru ## Typical flow - load the ticket and its surrounding context -- delegate `/dev` for implementation and validation -- delegate `/branch` for branch naming from the ticket summary -- delegate `/commit-and-push` -- delegate `/pr/create` and return the resulting PR URL +- keep orchestration local in `navigator` +- forward literal `` calls to `/dev`, `/branch`, `/commit-and-push`, and `/pr/create` +- stop on blockers at any delegated step and return the resulting PR URL on success ## Common tools - `ticket_load` -- `dispatch(/dev)` -- `dispatch(/branch)` -- `dispatch(/commit-and-push)` -- `dispatch(/pr/create)` +- `dispatch-command(/dev)` +- `dispatch-command(/branch)` +- `dispatch-command(/commit-and-push)` +- `dispatch-command(/pr/create)` diff --git a/packages/web/src/content/docs/docs/reference/commands/todo.mdx b/packages/web/src/content/docs/docs/reference/commands/todo.mdx index 82884a5..82eff3c 100644 --- a/packages/web/src/content/docs/docs/reference/commands/todo.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/todo.mdx @@ -25,6 +25,6 @@ Use `/todo` for structured pause-and-resume work from a checklist file. - `read` - `question` -- `dispatch(/ticket/plan)` -- `dispatch(/dev)` -- `dispatch(/commit)` +- `dispatch-command(/ticket/plan)` +- `dispatch-command(/dev)` +- `dispatch-command(/commit)` From 2750a6249843e6bcf1a59e1236f48ce605c3b110 Mon Sep 17 00:00:00 2001 From: dbpolito Date: Sat, 28 Mar 2026 11:57:45 -0300 Subject: [PATCH 2/2] docs: restructure navigator dispatch command instructions - Reorganize dispatch commands section with clearer subsections - Add explicit "How to forward" step-by-step instructions - Add example transformation showing literal command forwarding - Clarify critical rules about not expanding slash commands - Update test assertion to match new prompt wording --- packages/core/agents/navigator.md | 44 +++++++++++++++---- .../opencode/.opencode/agents/navigator.md | 44 +++++++++++++++---- packages/opencode/test/agents-config.test.ts | 2 +- 3 files changed, 73 insertions(+), 17 deletions(-) diff --git a/packages/core/agents/navigator.md b/packages/core/agents/navigator.md index 90a1977..6558503 100644 --- a/packages/core/agents/navigator.md +++ b/packages/core/agents/navigator.md @@ -10,14 +10,42 @@ You are an orchestrator for structured multi-step workflows. ## Dispatch Commands -- Treat each `...` block as a literal subagent call. -- `agent` is required; invoke that exact subagent type. -- Text starting with `/` inside the body is a native subagent command, not a file reference for you to resolve. -- Do not look up or expand slash commands inside a `` block. -- Only substitute placeholders inside the body, then forward the rendered text literally. -- Preserve line breaks and ordering exactly. Do not add wrapper text or rewrite the body. -- Run independent `` blocks in parallel only when the workflow clearly allows it; otherwise run them in source order. -- If a `` block is malformed, report it briefly and continue with remaining valid blocks when safe. +Each `...` 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 `` 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 + +/branch +Branch naming guidance: + +``` + +Make this task call: +```javascript +task({ + description: "Ensure feature branch", + prompt: "/branch\nBranch naming guidance: ", + subagent_type: "worker" +}) +``` + +Notice: The `/branch` stays literal. You do not fetch branch command docs or expand it into workflow steps. ## Output diff --git a/packages/opencode/.opencode/agents/navigator.md b/packages/opencode/.opencode/agents/navigator.md index eda4de0..ca6629a 100644 --- a/packages/opencode/.opencode/agents/navigator.md +++ b/packages/opencode/.opencode/agents/navigator.md @@ -20,14 +20,42 @@ You are an orchestrator for structured multi-step workflows. ## Dispatch Commands -- Treat each `...` block as a literal subagent call. -- `agent` is required; invoke that exact subagent type. -- Text starting with `/` inside the body is a native subagent command, not a file reference for you to resolve. -- Do not look up or expand slash commands inside a `` block. -- Only substitute placeholders inside the body, then forward the rendered text literally. -- Preserve line breaks and ordering exactly. Do not add wrapper text or rewrite the body. -- Run independent `` blocks in parallel only when the workflow clearly allows it; otherwise run them in source order. -- If a `` block is malformed, report it briefly and continue with remaining valid blocks when safe. +Each `...` 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 `` 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 + +/branch +Branch naming guidance: + +``` + +Make this task call: +```javascript +task({ + description: "Ensure feature branch", + prompt: "/branch\nBranch naming guidance: ", + subagent_type: "worker" +}) +``` + +Notice: The `/branch` stays literal. You do not fetch branch command docs or expand it into workflow steps. ## Output diff --git a/packages/opencode/test/agents-config.test.ts b/packages/opencode/test/agents-config.test.ts index 9a48f8d..5aa0102 100644 --- a/packages/opencode/test/agents-config.test.ts +++ b/packages/opencode/test/agents-config.test.ts @@ -56,7 +56,7 @@ describe("applyAgentsConfig", () => { assert.equal(cfg.agent.worker?.prompt, undefined); assert.match(cfg.agent.navigator?.prompt ?? "", /orchestrator/i); assert.match(cfg.agent.navigator?.prompt ?? "", /do not do implementation, planning, or review work yourself/i); - assert.match(cfg.agent.navigator?.prompt ?? "", /do not look up or expand slash commands/i); + assert.match(cfg.agent.navigator?.prompt ?? "", /do not look up command documentation/i); assert.match(cfg.agent.reviewer?.prompt ?? "", /Never switch branches/i); });