diff --git a/AGENTS.md b/AGENTS.md index de913e3..d627c16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,8 @@ bun run test - runtime definitions in `packages/core` - bundled config in `kompass.jsonc`, `packages/core/kompass.jsonc`, and `packages/opencode/kompass.jsonc` - schema in `kompass.schema.json` - - user-facing docs in `README.md` and adapter/package docs that describe the changed surface + - user-facing docs in `README.md`, adapter/package docs, and the web docs under `packages/web/src/content/docs/` that describe the changed surface + - web marketing and homepage surfaces that showcase commands or agents, especially `packages/web/src/pages/index.astro` and `packages/web/src/components/CommandShowcase.astro` - generated OpenCode output under `packages/opencode/.opencode/` when the source change affects compiled artifacts - If no validation was run in the current session, say that clearly instead of implying the branch was tested. @@ -51,7 +52,7 @@ packages/opencode/.opencode/ # Generated OpenCode output for review ## Command Authoring - Author command definitions in `packages/core/commands/`; treat `packages/opencode/.opencode/commands/` as generated output only -- Treat `packages/core/commands/index.ts`, `packages/core/lib/config.ts`, `kompass.schema.json`, the bundled `kompass.jsonc` files, and the relevant docs as a linked surface area; if one changes, verify the others still describe the same command set and config shape +- Treat `packages/core/commands/index.ts`, `packages/core/lib/config.ts`, `kompass.schema.json`, the bundled `kompass.jsonc` files, the relevant docs, and any web showcase/homepage surfaces as a linked surface area; if one changes, verify the others still describe the same command set, agent ownership, examples, and config shape - Use `packages/core/commands/pr/create.md` as the canonical example for command structure and tone - Keep this section order in command docs unless a command has a strong reason not to: `## Goal`, `## Additional Context`, `## Workflow` - Keep `### Output` as the final subsection inside `## Workflow`; do not use a separate top-level `## Output` section @@ -69,8 +70,9 @@ packages/opencode/.opencode/ # Generated OpenCode output for review - 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 -- Make success, blocked, and no-op outcomes explicit in `### Output` or the surrounding workflow so navigator-led flows report deterministic end states +- Make success, blocked, no-op, waiting, and resume-required outcomes explicit in `### Output` or the surrounding workflow so navigator-led flows report deterministic end states - For terminal command outcomes, prefer an explicit final line inside the output block: `No additional steps are required.` +- Omit that final line for outputs that intentionally wait for approval, pause for resume, loop to the next task, or otherwise continue beyond the current checkpoint - For one-off commands that do not orchestrate follow-up work, make every success, blocked, or no-op output explicitly terminal with that final line - Command-specific extra sections are fine, but they should support this core structure rather than replace it @@ -128,7 +130,7 @@ Constraints: ### Output - Define the exact success, blocked, and no-op response shapes -- For terminal outcomes, end the output block with `No additional steps are required.` +- For terminal outcomes, end the output block with `No additional steps are required.` Omit that line when the command is intentionally waiting, looping, or continuing. ``` Example delegation rule: diff --git a/packages/core/agents/navigator.md b/packages/core/agents/navigator.md index 2aead7d..d8db957 100644 --- a/packages/core/agents/navigator.md +++ b/packages/core/agents/navigator.md @@ -5,8 +5,7 @@ You coordinate structured, multi-step workflows. - Follow the active command and provided context. - 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. +- 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 @@ -14,8 +13,7 @@ You coordinate structured, multi-step workflows. - Treat each `...` 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. +- Do not rewrite 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. diff --git a/packages/core/commands/index.ts b/packages/core/commands/index.ts index 52ac8db..687577e 100644 --- a/packages/core/commands/index.ts +++ b/packages/core/commands/index.ts @@ -89,7 +89,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/opencode/.opencode/agents/navigator.md b/packages/opencode/.opencode/agents/navigator.md index d4ba60e..285c431 100644 --- a/packages/opencode/.opencode/agents/navigator.md +++ b/packages/opencode/.opencode/agents/navigator.md @@ -15,8 +15,7 @@ You coordinate structured, multi-step workflows. - Follow the active command and provided context. - 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. +- 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 @@ -24,8 +23,7 @@ You coordinate structured, multi-step workflows. - Treat each `...` block as literal input. - Render variables, then call `kompass_session_command` with `command` set to the tag value, `body` set to the rendered block body, and `agent` set to the tag value. - `kompass_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. +- Do not rewrite or interpret the block body; preserve line breaks and ordering. - Run `kompass_session_command` blocks sequentially unless the workflow clearly makes them independent. - If a `kompass_session_command` block is malformed, report it as invalid and continue with remaining valid blocks when safe. diff --git a/packages/opencode/.opencode/commands/ticket/dev.md b/packages/opencode/.opencode/commands/ticket/dev.md index c987cd6..ad7d220 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 diff --git a/packages/opencode/test/commands-config.test.ts b/packages/opencode/test/commands-config.test.ts index 5066617..aa2e271 100644 --- a/packages/opencode/test/commands-config.test.ts +++ b/packages/opencode/test/commands-config.test.ts @@ -71,6 +71,7 @@ describe("applyCommandsConfig", () => { assert.equal(cfg.command!["dev"]?.agent, "navigator"); assert.equal(cfg.command!["ship"]?.agent, "navigator"); assert.equal(cfg.command!["todo"]?.agent, "navigator"); + assert.equal(cfg.command!["ticket/dev"]?.agent, "navigator"); assert.ok(cfg.command!["pr/review"]?.description); assert.ok(cfg.command!["dev"]?.template); assert.ok(cfg.command!["branch"]?.template); diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro index 559792c..1a29070 100644 --- a/packages/web/src/components/CommandShowcase.astro +++ b/packages/web/src/components/CommandShowcase.astro @@ -205,7 +205,7 @@ const scenarios: CommandScenario[] = [ id: 'ticket-dev', label: '/ticket/dev', command: '/ticket/dev #42', - agentName: 'Worker', + agentName: 'Navigator', task: 'Implement a ticket through PR creation', group: 'ticket', steps: [ diff --git a/packages/web/src/content/docs/docs/reference/agents/index.mdx b/packages/web/src/content/docs/docs/reference/agents/index.mdx index a081790..4277546 100644 --- a/packages/web/src/content/docs/docs/reference/agents/index.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/index.mdx @@ -15,7 +15,7 @@ Generic worker role with minimal built-in behavior. It is the default execution ### `navigator` -Owns structured multi-step workflows locally, preserves state and stop conditions, and forwards literal `` blocks through the `session_command` tool when commands require queued same-session work. +Owns structured multi-step workflows locally, preserves state and stop conditions, and forwards literal `` blocks through the `session_command` tool when commands such as `/ship`, `/todo`, and `/ticket/dev` require queued same-session work. ### `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 33b6423..71b9563 100644 --- a/packages/web/src/content/docs/docs/reference/agents/navigator.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/navigator.mdx @@ -10,7 +10,7 @@ description: Orchestrator agent for structured multi-step workflows. ## 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 queued `session_command` leaf steps ## Key behavior 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 f5f021b..ae11b17 100644 --- a/packages/web/src/content/docs/docs/reference/commands/index.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/index.mdx @@ -97,7 +97,7 @@ 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 through a navigator-led orchestration of `/dev`, `/branch`, `/commit-and-push`, and `/pr/create`. - usage: `/ticket/dev ` - arguments: ticket reference, URL, file path, or raw request 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 2db2ffd..8160309 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 with queued same-session command steps. +Use `/ticket/dev` when implementation starts from a tracked ticket and should run through a navigator-led shipping flow with queued same-session command steps. ## Usage