kompassdev · dbpolito · Mar 31, 2026 · Mar 30, 2026 · Mar 31, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -63,9 +63,9 @@ packages/opencode/.opencode/ # Generated OpenCode output for review
 - For navigator-style commands, separate context loading, blocker checks, delegated execution, and final reporting into distinct workflow subsections so the control flow is easy to follow
 - 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
+- Before dispatching a same-session command step, say what result should be stored and whether the workflow must stop, pause, or continue based on that result
+- Use literal `<session_command>` tags when the workflow must queue exact text through `session_command`; `agent` and `command` are required, and the block body is the exact rendered body to send for that command
+- Do not use `<task>` blocks in command docs; author navigator delegation with `<session_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,23 @@ $ARGUMENTS
 
 ### Delegate Planning
 
-<dispatch agent="planner">
-/ticket/plan
+<session_command agent="planner" command="ticket/plan">
 
 Task: <task>
 Task context: <task-context>
 Additional context: <additional-context>
-</dispatch>
+</session_command>
 
 - Store the result as `<plan>`
 - STOP if planning is blocked or unusable
 
 ### Delegate Implementation
 
-<dispatch agent="worker">
-/dev
+<session_command agent="worker" command="dev">
 
 Plan: <plan>
 Constraints: <additional-context>
-</dispatch>
+</session_command>
 
 - STOP if implementation is blocked or incomplete
 
@@ -136,13 +134,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 dispatching, write the exact `<session_command ...>...</session_command>` block, say what queue acknowledgement should be stored, and whether the workflow should continue or STOP based on that acknowledgement.
 ```
 
-Example literal dispatch rule:
+Example literal session command 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 `<session_command ...>...</session_command>` block, then call `session_command` with the rendered body, exact `agent`, and exact `command`, and say what queue acknowledgement should be stored and whether the workflow should continue or STOP based on that acknowledgement.
 ```
 
 ## Component Authoring

diff --git a/README.md b/README.md
@@ -18,9 +18,9 @@ Kompass keeps AI coding agents on course with token-efficient, composable workfl
 
 ## Bundled Surface
 
-- Commands cover direct work (`/ask`, `/commit`), orchestration (`/dev`, `/ship`, `/todo`), ticket planning/sync, and PR review/shipping flows.
+- Commands cover direct work (`/ask`, `/commit`, `/merge`), orchestration (`/dev`, `/ship`, `/todo`), ticket planning/sync, and PR review/shipping flows.
 - Agents are intentionally narrow: `worker` is generic, `planner` is no-edit planning, `navigator` owns multi-step orchestration, and `reviewer` is a no-edit review specialist.
-- Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `pr_load`, `pr_sync`, `ticket_load`, `ticket_sync`.
+- Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `session_command` (resolve a slash command and queue it into the current session), `pr_load`, `pr_sync`, `ticket_load`, `ticket_sync`.
 - Reusable command-template components live in `packages/core/components/` and are documented in the components reference.
 
 ## Installation

diff --git a/kompass.jsonc b/kompass.jsonc
@@ -17,6 +17,7 @@
     "commit-and-push": { "enabled": true },
     "dev": { "enabled": true },
     "learn": { "enabled": true },
+    "merge": { "enabled": true },
     "pr/create": { "enabled": true },
     "pr/fix": { "enabled": true },
     "pr/review": { "enabled": true },
@@ -40,6 +41,7 @@
 
   "tools": {
     "changes_load": { "enabled": true },
+    "session_command": { "enabled": true },
     "pr_load": { "enabled": true },
     "pr_sync": { "enabled": true },
     "ticket_load": { "enabled": true },

diff --git a/kompass.schema.json b/kompass.schema.json
@@ -50,6 +50,9 @@
         "learn": {
           "$ref": "#/$defs/commandConfig"
         },
+        "merge": {
+          "$ref": "#/$defs/commandConfig"
+        },
         "pr/create": {
           "$ref": "#/$defs/commandConfig"
         },
@@ -97,6 +100,7 @@
               "commit-and-push",
               "dev",
               "learn",
+              "merge",
               "pr/create",
               "pr/fix",
               "pr/review",
@@ -124,6 +128,7 @@
               "commit-and-push",
               "dev",
               "learn",
+              "merge",
               "pr/create",
               "pr/fix",
               "pr/review",
@@ -179,6 +184,9 @@
         "changes_load": {
           "$ref": "#/$defs/toolConfig"
         },
+        "session_command": {
+          "$ref": "#/$defs/toolConfig"
+        },
         "pr_load": {
           "$ref": "#/$defs/toolConfig"
         },
@@ -353,6 +361,7 @@
       "type": "string",
       "enum": [
         "changes_load",
+        "session_command",
         "pr_load",
         "pr_sync",
         "ticket_sync",

diff --git a/packages/core/agents/navigator.md b/packages/core/agents/navigator.md
@@ -1,41 +1,25 @@
-You are a navigation specialist for structured, multi-step workflows.
+You coordinate structured, multi-step workflows.
 
-## Operating Boundaries
+## 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 `<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.
-- 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.
+- Manage step order, stored state, approvals, and stop conditions yourself.
+- Load only the context needed for the current step.
+- Execute required user-interaction steps exactly as the command defines them.
+- If a required interaction tool is unavailable, use the command's non-interactive fallback.
+- If a step is blocked, incomplete, or fails, stop and report it clearly.
+
+## Session Commands
+
+- Treat each `<session_command agent="AGENT_NAME" command="COMMAND_NAME">...</session_command>` block as literal input.
+- Render variables, then call `session_command` with `command` set to the tag value, `body` set to the rendered block body, and `agent` set to the tag value.
+- `session_command` queues the next same-session user turn and returns immediately; it does not wait for the queued command result.
+- Do not rewrite, summarize, or interpret the block body.
+- Preserve line breaks and ordering.
+- Run `session_command` blocks sequentially unless the workflow clearly makes them independent.
+- If a `session_command` block is malformed, report it as invalid and continue with remaining valid blocks when safe.
 
 ## Output
 
 - Follow any explicit command output exactly.
-- Otherwise report what finished, any delegated result, and whether the workflow is continuing, paused, blocked, or complete.
+- Otherwise report what finished and whether the workflow is continuing, paused, blocked, or complete.
diff --git a/packages/core/commands/index.ts b/packages/core/commands/index.ts
@@ -42,6 +42,11 @@ export const commandDefinitions: Record<string, CommandDefinition> = {
     templatePath: "commands/learn.md",
     subtask: false,
   },
+  merge: {
+    description: "Merge a branch and auto-resolve conflicts best-effort",
+    agent: "worker",
+    templatePath: "commands/merge.md",
+  },
   "pr/create": {
     description: "Summarize branch work and create a PR",
     agent: "worker",

diff --git a/packages/core/commands/merge.md b/packages/core/commands/merge.md
@@ -0,0 +1,101 @@
+## Goal
+
+Merge a provided branch into the current branch, defaulting to the repo base branch, and resolve merge conflicts with a best-effort preference for the incoming branch.
+
+## Additional Context
+
+Consider `<additional-context>` when choosing between competing conflict resolutions.
+- Default to preserving both sides when the intent is clear and the merged result remains coherent.
+- When a confident manual merge is not obvious, prefer the incoming `<merge-source>` version to keep the command moving.
+- Do not create a merge commit if any conflicts remain unresolved.
+
+## Workflow
+
+### Arguments
+
+<arguments>
+$ARGUMENTS
+</arguments>
+
+### Interpret Arguments
+
+- If `<arguments>` starts with or contains a clear branch or ref name, store it as `<merge-source>`
+- If `<arguments>` includes additional merge guidance, store it as `<additional-context>`
+- If no branch or ref was provided, leave `<merge-source>` undefined for now
+
+### Resolve Merge Source
+
+- If `<merge-source>` is already defined, keep it
+- Otherwise, resolve the repo base branch and store it as `<merge-source>`
+- Store the current checked out branch as `<current-branch>`
+
+### Check Blockers
+
+- If the working tree has uncommitted or untracked changes, STOP and report that merge automation requires a clean working tree
+- If `<merge-source>` cannot be resolved to an existing local or remote ref, STOP and report that the merge source could not be found
+- If `<current-branch>` equals `<merge-source>`, STOP and report that the current branch is already the merge source
+
+### Run Merge
+
+- Start the merge with `git merge <merge-source>`
+- If git reports a clean merge with no conflicts, store the new merge commit hash as `<merge-commit>`
+- If git reports conflicts, continue to `Resolve Conflicts`
+
+### Resolve Conflicts
+
+- Treat `git status` and the conflicted file markers as the source of truth for unresolved files
+- For each conflicted file, attempt a best-effort merge that preserves the intended behavior of both sides
+- Use `<additional-context>` when it helps disambiguate intent
+- If a conflict can be resolved confidently by combining both sides, do that and stage that file with `git add <file>`
+- If a confident manual merge is not obvious, prefer the incoming `<merge-source>` side for that conflict, then stage that file with `git add <file>`
+- Do not wait until the end to stage everything implicitly; each resolved conflicted file must be explicitly staged before continuing
+- After resolving all conflicts, finish the merge non-interactively with `GIT_EDITOR=true git merge --continue` and store the new merge commit hash as `<merge-commit>`
+- If any conflicts remain unresolved, STOP and report the remaining files without continuing the merge
+
+### Output
+
+If merge automation is blocked by a dirty working tree, display:
+```
+Merge blocked: working tree is not clean
+
+Commit, stash, or discard local changes before running `/merge`.
+
+No additional steps are required.
+```
+
+If the merge source cannot be found, display:
+```
+Merge blocked: source branch not found
+
+Source: <merge-source>
+
+No additional steps are required.
+```
+
+If the current branch already matches the merge source, display:
+```
+Merge skipped: already on <current-branch>
+
+No additional steps are required.
+```
+
+If any conflicts remain unresolved, display:
+```
+Merge blocked: unresolved conflicts remain
+
+Source: <merge-source>
+Branch: <current-branch>
+
+Resolve the remaining conflicted files, then retry.
+
+No additional steps are required.
+```
+
+When the merge succeeds, display:
+```
+Merged <merge-source> into <current-branch>
+
+Commit: <merge-commit>
+
+No additional steps are required.
+```
diff --git a/packages/core/commands/ship.md b/packages/core/commands/ship.md
@@ -1,10 +1,10 @@
 ## Goal
 
-Ship the current work by delegating branch creation, commit creation, and PR creation.
+Ship the current work by dispatching branch creation, commit creation, and PR creation in the current session.
 
 ## 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 dispatched branch naming. Use `<additional-context>` to refine the dispatched commit and PR summaries. Pass `<base>` through to PR creation when it was provided. This command is session-command-first: send each `<session_command>` body literally through `session_command` and use the result as the source of truth for the next step.
 
 ## Workflow
 
@@ -23,38 +23,35 @@ $ARGUMENTS
 
 ### Ensure Feature Branch
 
-<dispatch agent="worker">
-/branch
+<session_command agent="worker" command="branch">
 Branch naming guidance: <branch-context>
-</dispatch>
+</session_command>
 
-- Store the subagent result as `<branch-result>`
+- Store the dispatch result as `<branch-result>`
 - If `<branch-result>` is blocked or incomplete, STOP and report the branch blocker
 - If `<branch-result>` says there was nothing to branch from, continue without changing branches
 - Otherwise, continue with the created branch
 
 ### Delegate Commit
 
-<dispatch agent="worker">
-/commit
+<session_command agent="worker" command="commit">
 Additional context: <additional-context>
-</dispatch>
+</session_command>
 
-- Store the subagent result as `<commit-result>`
+- Store the dispatch result as `<commit-result>`
 
 - If `<commit-result>` says there was nothing to commit, continue without creating a new commit
 - If `<commit-result>` is blocked or incomplete, STOP and report the commit blocker
 - Otherwise, continue with the created commit
 
 ### Delegate PR Creation
 
-<dispatch agent="worker">
-/pr/create
+<session_command agent="worker" command="pr/create">
 Base branch: <base>
 Additional context: <additional-context>
-</dispatch>
+</session_command>
 
-- Store the subagent result as `<pr-result>`
+- Store the dispatch result as `<pr-result>`
 
 - If `<pr-result>` is blocked or incomplete, STOP and report the PR blocker
 - If `<pr-result>` says there is nothing to include in a PR, STOP and report that there is nothing to ship