From 02d8d2d12ed1a49a3ac11d6118a1a2a86dc90c0d Mon Sep 17 00:00:00 2001 From: dbpolito Date: Fri, 27 Mar 2026 19:36:17 -0300 Subject: [PATCH] feat: refresh bundled workflow surface docs - document commands, agents, tools, and reusable components across the README, adapter docs, and reference pages - switch command ownership from build to worker and align default agent permissions and config tests - add explicit head branch support to pr_sync for PR creation flows - refresh the docs site landing page and command showcase to present the bundled workflow surface more clearly --- README.md | 17 +- packages/core/commands/index.ts | 26 +- packages/core/lib/config.ts | 8 +- packages/core/test/config.test.ts | 2 + packages/core/tools/pr-sync.ts | 5 + .../opencode/.opencode/agents/navigator.md | 1 + packages/opencode/.opencode/agents/planner.md | 1 + .../opencode/.opencode/agents/reviewer.md | 1 + packages/opencode/.opencode/agents/worker.md | 1 + packages/opencode/.opencode/commands/ask.md | 2 +- .../opencode/.opencode/commands/branch.md | 2 +- .../.opencode/commands/commit-and-push.md | 2 +- .../opencode/.opencode/commands/commit.md | 2 +- packages/opencode/.opencode/commands/dev.md | 2 +- packages/opencode/.opencode/commands/learn.md | 2 +- .../opencode/.opencode/commands/pr/create.md | 2 +- .../opencode/.opencode/commands/pr/fix.md | 2 +- .../opencode/.opencode/commands/rmslop.md | 2 +- .../opencode/.opencode/commands/ticket/ask.md | 2 +- .../.opencode/commands/ticket/create.md | 4 +- .../opencode/.opencode/commands/ticket/dev.md | 2 +- packages/opencode/README.md | 10 +- packages/opencode/test/agents-config.test.ts | 5 + .../opencode/test/commands-config.test.ts | 10 +- packages/web/astro.config.mjs | 1 - .../web/src/components/CommandShowcase.astro | 700 ++++++------------ .../content/docs/docs/adapters/opencode.mdx | 2 +- .../docs/docs/reference/agents/index.mdx | 10 +- .../docs/docs/reference/agents/navigator.mdx | 15 +- .../docs/docs/reference/agents/planner.mdx | 17 +- .../docs/docs/reference/agents/reviewer.mdx | 17 +- .../docs/docs/reference/agents/worker.mdx | 16 +- .../docs/docs/reference/commands/branch.mdx | 16 +- .../reference/commands/commit-and-push.mdx | 17 +- .../docs/docs/reference/commands/commit.mdx | 18 +- .../docs/docs/reference/commands/dev.mdx | 3 +- .../docs/docs/reference/commands/index.mdx | 30 +- .../docs/docs/reference/commands/learn.mdx | 14 +- .../docs/reference/commands/pr-create.mdx | 10 +- .../docs/docs/reference/commands/pr-fix.mdx | 14 +- .../docs/reference/commands/pr-review.mdx | 14 +- .../docs/docs/reference/commands/review.mdx | 13 +- .../docs/docs/reference/commands/rmslop.mdx | 17 +- .../docs/docs/reference/commands/ship.mdx | 18 +- .../docs/reference/commands/ticket-dev.mdx | 18 +- .../docs/reference/commands/ticket-plan.mdx | 17 +- .../docs/docs/reference/commands/todo.mdx | 21 +- .../reference/components/change-summary.mdx | 10 +- .../reference/components/changes-summary.mdx | 10 +- .../docs/docs/reference/components/commit.mdx | 10 +- .../docs/reference/components/dev-flow.mdx | 10 +- .../docs/docs/reference/components/index.mdx | 14 +- .../docs/reference/components/load-pr.mdx | 10 +- .../docs/reference/components/load-ticket.mdx | 10 +- .../components/summarize-changes.mdx | 9 +- .../docs/reference/tools/changes-load.mdx | 13 +- .../docs/docs/reference/tools/index.mdx | 25 +- .../docs/docs/reference/tools/pr-load.mdx | 19 +- .../docs/docs/reference/tools/pr-sync.mdx | 4 +- packages/web/src/pages/index.astro | 23 +- packages/web/src/styles/site.css | 40 + 61 files changed, 639 insertions(+), 699 deletions(-) diff --git a/README.md b/README.md index 3092e59..d91c7c6 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,18 @@ Kompass keeps AI coding agents on course with token-efficient, composable workfl ## Docs -- Main docs: `https://kompassdev.ai/docs/` -- Getting started: `https://kompassdev.ai/docs/getting-started/` -- OpenCode adapter: `https://kompassdev.ai/docs/adapters/opencode/` -- Config reference: `https://kompassdev.ai/docs/config/overview/` -- Command, agent, and tool reference: `https://kompassdev.ai/docs/reference/commands/`, `https://kompassdev.ai/docs/reference/agents/`, `https://kompassdev.ai/docs/reference/tools/` +- Main docs: https://kompassdev.ai/docs/ +- Getting started: https://kompassdev.ai/docs/getting-started/ +- OpenCode adapter: https://kompassdev.ai/docs/adapters/opencode/ +- Config reference: https://kompassdev.ai/docs/config/overview/ +- Command, agent, tool, and component reference: https://kompassdev.ai/docs/reference/commands/, https://kompassdev.ai/docs/reference/agents/, https://kompassdev.ai/docs/reference/tools/, https://kompassdev.ai/docs/reference/components/ + +## Bundled Surface + +- Commands cover direct work (`/ask`, `/commit`), 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`. +- Reusable command-template components live in `packages/core/components/` and are documented in the components reference. ## Installation diff --git a/packages/core/commands/index.ts b/packages/core/commands/index.ts index 60245eb..886f7cd 100644 --- a/packages/core/commands/index.ts +++ b/packages/core/commands/index.ts @@ -13,43 +13,43 @@ interface CommandDefinition { export const commandDefinitions: Record = { ask: { description: "Answer questions about the current project or code", - agent: "build", + agent: "worker", templatePath: "commands/ask.md", }, branch: { description: "Create a feature branch from current changes", - agent: "build", + agent: "worker", templatePath: "commands/branch.md", }, commit: { description: "Commit current changes with a message", - agent: "build", + agent: "worker", templatePath: "commands/commit.md", }, "commit-and-push": { description: "Commit and push current changes", - agent: "build", + agent: "worker", templatePath: "commands/commit-and-push.md", }, dev: { - description: "Implement a request and create a PR", + description: "Implement a request and prepare it for PR creation", agent: "navigator", templatePath: "commands/dev.md", }, learn: { description: "Extract learnings from session to AGENTS.md files", - agent: "build", + agent: "worker", templatePath: "commands/learn.md", subtask: false, }, "pr/create": { description: "Summarize branch work and create a PR", - agent: "build", + agent: "worker", templatePath: "commands/pr/create.md", }, "pr/fix": { description: "Fix PR feedback, push updates, and reply", - agent: "build", + agent: "worker", templatePath: "commands/pr/fix.md", }, "pr/review": { @@ -69,7 +69,7 @@ export const commandDefinitions: Record = { }, rmslop: { description: "Remove AI code slop from current branch", - agent: "build", + agent: "worker", templatePath: "commands/rmslop.md", }, todo: { @@ -79,17 +79,17 @@ export const commandDefinitions: Record = { }, "ticket/ask": { description: "Answer a question on a ticket and post the response", - agent: "build", + agent: "worker", templatePath: "commands/ticket/ask.md", }, "ticket/dev": { description: "Implement a ticket and create a PR", - agent: "build", + agent: "worker", templatePath: "commands/ticket/dev.md", }, "ticket/create": { - description: "Summarize completed work and create a ticket", - agent: "build", + description: "Summarize current change comparison and create a ticket", + agent: "worker", templatePath: "commands/ticket/create.md", }, "ticket/plan": { diff --git a/packages/core/lib/config.ts b/packages/core/lib/config.ts index ebced8b..9074724 100644 --- a/packages/core/lib/config.ts +++ b/packages/core/lib/config.ts @@ -410,25 +410,25 @@ function removeTrailingCommas(input: string): string { const defaultAgentWorker: AgentDefinition = { description: "Generic worker agent.", - permission: { question: "allow" }, + permission: { question: "allow", todowrite: "allow" }, }; const defaultAgentReviewer: AgentDefinition = { description: "Review diffs, PRs, and existing feedback without editing files.", promptPath: "agents/reviewer.md", - permission: { edit: "deny", question: "allow" }, + permission: { edit: "deny", question: "allow", todowrite: "allow" }, }; const defaultAgentNavigator: AgentDefinition = { description: "Coordinate structured multi-step workflows by delegating focused leaf work to subagents.", promptPath: "agents/navigator.md", - permission: { edit: "deny", task: "allow", question: "allow" }, + permission: { edit: "deny", task: "allow", question: "allow", todowrite: "allow" }, }; const defaultAgentPlanner: AgentDefinition = { description: "Turn requests or tickets into scoped implementation plans.", promptPath: "agents/planner.md", - permission: { edit: "deny", question: "allow" }, + permission: { edit: "deny", question: "allow", todowrite: "allow" }, }; const defaultComponentPaths: Record = { diff --git a/packages/core/test/config.test.ts b/packages/core/test/config.test.ts index 599c270..5169df3 100644 --- a/packages/core/test/config.test.ts +++ b/packages/core/test/config.test.ts @@ -276,6 +276,7 @@ describe("command defaults", () => { assert.equal(config.agents.enabled.includes("worker"), true); assert.deepEqual(config.agents.worker.permission, { question: "allow", + todowrite: "allow", }); assert.equal(config.agents.enabled.includes("navigator"), true); assert.deepEqual(config.shared.validation, []); @@ -283,6 +284,7 @@ describe("command defaults", () => { edit: "deny", task: "allow", question: "allow", + todowrite: "allow", }); }); diff --git a/packages/core/tools/pr-sync.ts b/packages/core/tools/pr-sync.ts index 18ec00f..466b2c2 100644 --- a/packages/core/tools/pr-sync.ts +++ b/packages/core/tools/pr-sync.ts @@ -372,6 +372,11 @@ export function createPrSyncTool($: Shell) { optional: true, description: "Base branch to merge into (defaults to repo default branch)", }, + head: { + type: "string", + optional: true, + description: "Head branch to open the PR from when creating a new pull request", + }, assignees: { type: "string[]", optional: true, diff --git a/packages/opencode/.opencode/agents/navigator.md b/packages/opencode/.opencode/agents/navigator.md index de19437..82c798e 100644 --- a/packages/opencode/.opencode/agents/navigator.md +++ b/packages/opencode/.opencode/agents/navigator.md @@ -5,6 +5,7 @@ permission: edit: deny task: allow question: allow + todowrite: allow --- You are a navigation specialist for structured, multi-step workflows. diff --git a/packages/opencode/.opencode/agents/planner.md b/packages/opencode/.opencode/agents/planner.md index e97ecf6..4a0dc7e 100644 --- a/packages/opencode/.opencode/agents/planner.md +++ b/packages/opencode/.opencode/agents/planner.md @@ -3,6 +3,7 @@ description: Turn requests or tickets into scoped implementation plans. permission: edit: deny question: allow + todowrite: allow --- You are a planning specialist. Turn requests, tickets, and gathered context into concise, human-friendly plans that stay grounded in real technical context when needed. diff --git a/packages/opencode/.opencode/agents/reviewer.md b/packages/opencode/.opencode/agents/reviewer.md index 02213b7..2955d8b 100644 --- a/packages/opencode/.opencode/agents/reviewer.md +++ b/packages/opencode/.opencode/agents/reviewer.md @@ -3,6 +3,7 @@ description: Review diffs, PRs, and existing feedback without editing files. permission: edit: deny question: allow + todowrite: allow --- You are a high-signal code review agent. Review whatever material the caller gives you: diffs, files, PR context, tickets, summaries, or related code. diff --git a/packages/opencode/.opencode/agents/worker.md b/packages/opencode/.opencode/agents/worker.md index a283db0..3bf0cac 100644 --- a/packages/opencode/.opencode/agents/worker.md +++ b/packages/opencode/.opencode/agents/worker.md @@ -2,4 +2,5 @@ description: Generic worker agent. permission: question: allow + todowrite: allow --- diff --git a/packages/opencode/.opencode/commands/ask.md b/packages/opencode/.opencode/commands/ask.md index 61c087a..8b5db77 100644 --- a/packages/opencode/.opencode/commands/ask.md +++ b/packages/opencode/.opencode/commands/ask.md @@ -1,6 +1,6 @@ --- description: Answer questions about the current project or code -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/branch.md b/packages/opencode/.opencode/commands/branch.md index 2d9f0ed..239459a 100644 --- a/packages/opencode/.opencode/commands/branch.md +++ b/packages/opencode/.opencode/commands/branch.md @@ -1,6 +1,6 @@ --- description: Create a feature branch from current changes -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/commit-and-push.md b/packages/opencode/.opencode/commands/commit-and-push.md index 42e9737..5d28ef8 100644 --- a/packages/opencode/.opencode/commands/commit-and-push.md +++ b/packages/opencode/.opencode/commands/commit-and-push.md @@ -1,6 +1,6 @@ --- description: Commit and push current changes -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/commit.md b/packages/opencode/.opencode/commands/commit.md index 2b6da67..5b3e49e 100644 --- a/packages/opencode/.opencode/commands/commit.md +++ b/packages/opencode/.opencode/commands/commit.md @@ -1,6 +1,6 @@ --- description: Commit current changes with a message -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/dev.md b/packages/opencode/.opencode/commands/dev.md index d705cb4..b0720e6 100644 --- a/packages/opencode/.opencode/commands/dev.md +++ b/packages/opencode/.opencode/commands/dev.md @@ -1,5 +1,5 @@ --- -description: Implement a request and create a PR +description: Implement a request and prepare it for PR creation agent: navigator --- diff --git a/packages/opencode/.opencode/commands/learn.md b/packages/opencode/.opencode/commands/learn.md index 455151e..95937d9 100644 --- a/packages/opencode/.opencode/commands/learn.md +++ b/packages/opencode/.opencode/commands/learn.md @@ -1,6 +1,6 @@ --- description: Extract learnings from session to AGENTS.md files -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/pr/create.md b/packages/opencode/.opencode/commands/pr/create.md index 02b4d8b..931c111 100644 --- a/packages/opencode/.opencode/commands/pr/create.md +++ b/packages/opencode/.opencode/commands/pr/create.md @@ -1,6 +1,6 @@ --- description: Summarize branch work and create a PR -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/pr/fix.md b/packages/opencode/.opencode/commands/pr/fix.md index e10797c..816f650 100644 --- a/packages/opencode/.opencode/commands/pr/fix.md +++ b/packages/opencode/.opencode/commands/pr/fix.md @@ -1,6 +1,6 @@ --- description: Fix PR feedback, push updates, and reply -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/rmslop.md b/packages/opencode/.opencode/commands/rmslop.md index c22f091..11dd632 100644 --- a/packages/opencode/.opencode/commands/rmslop.md +++ b/packages/opencode/.opencode/commands/rmslop.md @@ -1,6 +1,6 @@ --- description: Remove AI code slop from current branch -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/ticket/ask.md b/packages/opencode/.opencode/commands/ticket/ask.md index 885f103..670829d 100644 --- a/packages/opencode/.opencode/commands/ticket/ask.md +++ b/packages/opencode/.opencode/commands/ticket/ask.md @@ -1,6 +1,6 @@ --- description: Answer a question on a ticket and post the response -agent: build +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/ticket/create.md b/packages/opencode/.opencode/commands/ticket/create.md index 9cd586e..ea27423 100644 --- a/packages/opencode/.opencode/commands/ticket/create.md +++ b/packages/opencode/.opencode/commands/ticket/create.md @@ -1,6 +1,6 @@ --- -description: Summarize completed work and create a ticket -agent: build +description: Summarize current change comparison and create a ticket +agent: worker --- ## Goal diff --git a/packages/opencode/.opencode/commands/ticket/dev.md b/packages/opencode/.opencode/commands/ticket/dev.md index e527657..2556245 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: build +agent: worker --- ## Goal diff --git a/packages/opencode/README.md b/packages/opencode/README.md index 3092e59..b3137d4 100644 --- a/packages/opencode/README.md +++ b/packages/opencode/README.md @@ -10,11 +10,11 @@ Kompass keeps AI coding agents on course with token-efficient, composable workfl ## Docs -- Main docs: `https://kompassdev.ai/docs/` -- Getting started: `https://kompassdev.ai/docs/getting-started/` -- OpenCode adapter: `https://kompassdev.ai/docs/adapters/opencode/` -- Config reference: `https://kompassdev.ai/docs/config/overview/` -- Command, agent, and tool reference: `https://kompassdev.ai/docs/reference/commands/`, `https://kompassdev.ai/docs/reference/agents/`, `https://kompassdev.ai/docs/reference/tools/` +- Main docs: https://kompassdev.ai/docs/ +- Getting started: https://kompassdev.ai/docs/getting-started/ +- OpenCode adapter: https://kompassdev.ai/docs/adapters/opencode/ +- Config reference: https://kompassdev.ai/docs/config/overview/ +- Command, agent, tool, and component reference: https://kompassdev.ai/docs/reference/commands/, https://kompassdev.ai/docs/reference/agents/, https://kompassdev.ai/docs/reference/tools/, https://kompassdev.ai/docs/reference/components/ ## Installation diff --git a/packages/opencode/test/agents-config.test.ts b/packages/opencode/test/agents-config.test.ts index 9b0a60d..0984dcc 100644 --- a/packages/opencode/test/agents-config.test.ts +++ b/packages/opencode/test/agents-config.test.ts @@ -30,6 +30,7 @@ describe("applyAgentsConfig", () => { ); assert.deepEqual(cfg.agent.worker?.permission, { question: "allow", + todowrite: "allow", }); assert.equal(cfg.agent.worker?.mode, undefined); assert.equal( @@ -40,14 +41,17 @@ describe("applyAgentsConfig", () => { edit: "deny", task: "allow", question: "allow", + todowrite: "allow", }); assert.deepEqual(cfg.agent.reviewer?.permission, { edit: "deny", question: "allow", + todowrite: "allow", }); assert.deepEqual(cfg.agent.planner?.permission, { edit: "deny", question: "allow", + todowrite: "allow", }); assert.equal(cfg.agent.worker?.prompt, undefined); assert.match(cfg.agent.navigator?.prompt ?? "", /navigation specialist/i); @@ -83,6 +87,7 @@ describe("applyAgentsConfig", () => { assert.equal(cfg.agent?.worker?.prompt, undefined); assert.deepEqual(cfg.agent?.worker?.permission, { question: "allow", + todowrite: "allow", }); }); }); diff --git a/packages/opencode/test/commands-config.test.ts b/packages/opencode/test/commands-config.test.ts index 17418fa..30d15ac 100644 --- a/packages/opencode/test/commands-config.test.ts +++ b/packages/opencode/test/commands-config.test.ts @@ -59,13 +59,13 @@ describe("applyCommandsConfig", () => { assert.ok(cfg.command); assert.equal(cfg.command!["pr/review"]?.agent, "reviewer"); - assert.equal(cfg.command!["branch"]?.agent, "build"); - assert.equal(cfg.command!["pr/create"]?.agent, "build"); - assert.equal(cfg.command!["ticket/create"]?.agent, "build"); + 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/plan"]?.agent, "planner"); assert.equal(cfg.command!["ticket/plan-and-sync"]?.agent, "planner"); - assert.equal(cfg.command!["ask"]?.agent, "build"); - assert.equal(cfg.command!["ticket/ask"]?.agent, "build"); + assert.equal(cfg.command!["ask"]?.agent, "worker"); + assert.equal(cfg.command!["ticket/ask"]?.agent, "worker"); assert.equal(cfg.command!["dev"]?.agent, "navigator"); assert.equal(cfg.command!["ship"]?.agent, "navigator"); assert.equal(cfg.command!["todo"]?.agent, "navigator"); diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index 2f04a99..55cff69 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -35,7 +35,6 @@ export default defineConfig({ "docs/reference/agents", "docs/reference/tools", "docs/reference/components", - "docs/reference/skills" ] }, { diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro index 5d705cd..d3d8c14 100644 --- a/packages/web/src/components/CommandShowcase.astro +++ b/packages/web/src/components/CommandShowcase.astro @@ -25,102 +25,65 @@ interface CommandScenario { } const scenarios: CommandScenario[] = [ - // Core commands { id: 'ask', label: '/ask', command: '/ask is this project cool?', - agentName: 'Build Agent', + agentName: 'Worker', task: 'Answer questions about the current project or code', group: 'core', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Evaluating project appeal — need to determine if this project is cool by inspecting repository structure, README, and command architecture. Will check relevant files and keep analysis concise.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'glob', args: 'README* in . (5 matches)', status: 'complete' }, - { tool: 'read', args: 'package.json', status: 'complete' }, - { tool: 'read', args: 'README.md [limit=220]', status: 'complete' }, - { tool: 'read', args: 'packages/core/README.md [limit=220]', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'It has a clear point of view: keep AI coding agents "on course" with token-efficient, composable workflows instead of giant ad-hoc prompts.', - 'The repo is structured thoughtfully: shared logic lives in packages/core, adapter-specific wiring in packages/opencode.', - 'The command surface is unusually coherent — /ask, /review, /pr/create, /ticket/plan all fit the same workflow philosophy.' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Need just enough repository context to answer the question directly.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'read', args: 'README.md', status: 'complete' }, + { tool: 'read', args: 'packages/core/README.md', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'It has a clear point of view around structured AI workflows.', + 'The shared-core plus adapter split is thoughtful and consistent.', + 'Yes - it is a pretty cool project.' + ] } ] }, { id: 'branch', label: '/branch', - command: '/branch', + command: '/branch docs cleanup', agentName: 'Worker', - task: 'Create categorized branch names', + task: 'Create a categorized branch from current work', group: 'core', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Creating branch — need to summarize uncommitted work and generate a categorized branch name based on the change themes.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'changes_load', args: 'uncommitted', status: 'complete' }, - { tool: 'bash', args: 'git checkout -b docs/site-refresh', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Created branch: docs/site-refresh', - 'Switched from main to the new work branch' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Summarize uncommitted work, check whether the current branch already looks like a work branch, then generate a short categorized name.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'changes_load', args: 'uncommitted: true', status: 'complete' }, + { tool: 'bash', args: 'git checkout -b docs/reference-cleanup', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Created branch: docs/reference-cleanup', + 'From: main', + 'No additional steps are required.' + ] } ] }, { id: 'commit', label: '/commit', - command: '/commit', + command: '/commit tighten command docs', agentName: 'Worker', - task: 'Generate why-focused commit messages', + task: 'Create a commit from uncommitted work', group: 'core', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Committing — need to inspect staged and unstaged changes, then generate a commit message focused on why the changes were made.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'changes_load', args: 'uncommitted', status: 'complete' }, - { tool: 'bash', args: 'git add packages/web/src/', status: 'complete' }, - { tool: 'bash', args: 'git commit -m "feat: improve command showcase"', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Staged relevant files', - 'Created a new commit with generated message' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Load uncommitted changes, stop if there is nothing to commit, then stage the work and write a conventional message.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'changes_load', args: 'uncommitted: true', status: 'complete' }, + { tool: 'bash', args: 'git add -A', status: 'complete' }, + { tool: 'bash', args: 'git commit', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Created commit `a1b2c3d`:', + 'docs: tighten command reference pages', + 'No additional steps are required.' + ] } ] }, { @@ -128,447 +91,275 @@ const scenarios: CommandScenario[] = [ label: '/commit-and-push', command: '/commit-and-push', agentName: 'Worker', - task: 'Commit and push in one pass', + task: 'Create a commit and push it', group: 'core', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Committing and pushing — need to stage relevant files, generate a commit message, and push the branch upstream in a single operation.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'changes_load', args: 'uncommitted', status: 'complete' }, - { tool: 'bash', args: 'git add packages/web/src/', status: 'complete' }, - { tool: 'bash', args: 'git commit -m "feat: add command showcase"', status: 'complete' }, - { tool: 'bash', args: 'git push origin HEAD', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Staged 3 modified files', - 'Created commit: feat: add command showcase with animations', - 'Pushed to origin/feature/showcase' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Create the commit from current uncommitted work, then push and fall back to upstream setup if needed.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'changes_load', args: 'uncommitted: true', status: 'complete' }, + { tool: 'bash', args: 'git commit', status: 'complete' }, + { tool: 'bash', args: 'git push', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Created commit `d4e5f6g`:', + 'Pushed to origin/docs/reference-cleanup', + 'No additional steps are required.' + ] } ] }, { id: 'learn', label: '/learn', - command: '/learn', + command: '/learn docs', agentName: 'Worker', - task: 'Extract patterns into AGENTS.md', + task: 'Document non-obvious session learnings', group: 'core', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Learning — need to inspect existing patterns in the repo and extract reusable guidance into AGENTS.md targets.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'read', args: 'AGENTS.md', status: 'complete' }, - { tool: 'grep', args: 'function|const|class', status: 'complete' }, - { tool: 'apply_patch', args: 'AGENTS.md', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Summarized established conventions', - 'Updated agent guidance where the pattern belongs' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Review the session for durable, non-obvious learnings and place them in the narrowest useful AGENTS.md scope.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'read', args: 'AGENTS.md', status: 'complete' }, + { tool: 'apply_patch', args: 'update scoped AGENTS guidance', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Documented learnings for docs', + 'Files updated: - AGENTS.md: 2 learnings', + 'No additional steps are required.' + ] } ] }, { id: 'rmslop', label: '/rmslop', - command: '/rmslop', + command: '/rmslop main', agentName: 'Worker', - task: 'Remove unnecessary complexity and duplication', + task: 'Clean AI-style slop from branch changes', group: 'core', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Inspecting for slop — need to examine the branch for unnecessary complexity, duplicate code, and workflow glue that can be simplified or removed.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'changes_load', args: 'HEAD~3...HEAD', status: 'complete' }, - { tool: 'read', args: 'packages/core/commands/*.md', status: 'complete' }, - { tool: 'grep', args: 'TODO|FIXME|XXX', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Removed 47 lines of duplicate validation logic', - 'Simplified 3 overly-abstract helper functions', - 'Consolidated similar command patterns into shared components' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Load the branch diff, identify noisy or inconsistent AI-shaped edits, clean them up, validate, and commit the cleanup.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'changes_load', args: 'base: main', status: 'complete' }, + { tool: 'apply_patch', args: 'clean awkward comments and style drift', status: 'complete' }, + { tool: 'bash', args: 'run validation and commit cleanup', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Cleaned branch changes for main...HEAD', + 'Results: Files updated, validation, and commit recorded', + 'No additional steps are required.' + ] } ] }, - - // Ticket commands { id: 'ticket-ask', label: '/ticket/ask', command: '/ticket/ask #42 how do I test this?', - agentName: 'Build Agent', - task: 'Answer questions about a ticket and post the response', + agentName: 'Worker', + task: 'Answer a ticket question and post the reply', group: 'ticket', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Answering ticket question — loading ticket #42 with discussion to understand the testing requirements, then providing a clear answer.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'ticket_load', args: '#42', status: 'complete' }, - { tool: 'read', args: 'packages/core/package.json', status: 'complete' }, - { tool: 'glob', args: '**/*.test.ts', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Loaded ticket #42 and discussion history', - 'Posted answer with test examples and setup instructions', - 'Answer now visible on the ticket for the team' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Load the ticket discussion, answer the question from ticket and repo context, then post that answer back to the same ticket.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'ticket_load', args: '#42 with comments', status: 'complete' }, + { tool: 'read', args: 'relevant test docs', status: 'complete' }, + { tool: 'ticket_sync', args: 'post ticket comment', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Answered ticket: https://github.com/kompassdev/kompass/issues/42', + 'No additional steps are required.' + ] } ] }, { id: 'ticket-create', label: '/ticket/create', command: '/ticket/create', - agentName: 'Build Agent', - task: 'Create a ticket from current changes', + agentName: 'Worker', + task: 'Create a ticket from current change comparison', group: 'ticket', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Creating ticket — loading branch changes, reading modified files to understand themes, then creating a structured issue.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'changes_load', args: 'HEAD...main', status: 'complete' }, - { tool: 'read', args: 'packages/web/src/components/*.astro', status: 'complete' }, - { tool: 'ticket_sync', args: 'create with checklists', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Analyzed 5 changed files, grouped into 3 themes', - 'Created issue #43: Add workflow documentation', - 'Assigned to @me with implementation checklist' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Summarize the current change comparison into a short title, description, and checklist structure.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'changes_load', args: 'main...HEAD', status: 'complete' }, + { tool: 'ticket_sync', args: 'title, description, checklists, assignees', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Created ticket: Refresh command reference docs', + 'Assigned to @me', + 'Implementation and Validation sections added' + ] } ] }, { id: 'ticket-dev', label: '/ticket/dev', - command: '/ticket/dev #128', - agentName: 'Navigator', - task: 'Implement a ticket end-to-end', + command: '/ticket/dev #42', + agentName: 'Worker', + task: 'Implement a ticket through PR creation', group: 'ticket', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Implementing ticket — loading context and preparing to orchestrate the full workflow: branch creation, development, validation, commit, and PR.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'ticket_load', args: '#128', status: 'complete' }, - { tool: 'dispatch', args: '/branch', status: 'complete' }, - { tool: 'dispatch', args: '/dev', status: 'complete' }, - { tool: 'dispatch', args: '/commit-and-push', status: 'complete' }, - { tool: 'dispatch', args: '/pr/create', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Created branch: feature/ticket-128-workflow', - 'Implemented changes with validation', - 'Published PR #49 linked to ticket #128' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Load the ticket, then orchestrate implementation, branch creation, commit-and-push, and PR creation in order.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'ticket_load', args: '#42', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /dev', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /branch', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /commit-and-push', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /pr/create', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Implemented ticket: refresh command docs', + 'PR: https://github.com/kompassdev/kompass/pull/51', + 'No additional steps are required.' + ] } ] }, { id: 'ticket-plan', label: '/ticket/plan', - command: '/ticket/plan #128', + command: '/ticket/plan #42', agentName: 'Planner', - task: 'Turn a request or ticket into a scoped implementation plan', + task: 'Turn a request or ticket into a scoped plan', group: 'ticket', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Planning the rollout — need to break down the review workflow into actionable steps. Will examine existing patterns and create a scoped plan with clear milestones.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'ticket_load', args: '#128', status: 'complete' }, - { tool: 'read', args: 'packages/core/commands/pr/review.md', status: 'complete' }, - { tool: 'glob', args: 'packages/core/components/*.md', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Phase 1: Extract reusable review components from existing commands', - 'Phase 2: Update navigator agent to coordinate review workflows', - 'Phase 3: Add checklist generation and feedback threading' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Interpret the planning request, inspect only the relevant repo context, then return a scoped plan without syncing ticket state.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'ticket_load', args: '#42 with comments', status: 'complete' }, + { tool: 'grep', args: 'reference docs', status: 'complete' }, + { tool: 'read', args: 'packages/web/src/content/docs/docs/reference/commands/index.mdx', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Title: `Refresh command reference docs`', + 'Plan: short description plus Implementation and Validation checklists', + 'No additional steps are required.' + ] } ] }, { id: 'ticket-plan-and-sync', label: '/ticket/plan-and-sync', - command: '/ticket/plan-and-sync #128', + command: '/ticket/plan-and-sync #42', agentName: 'Planner', - task: 'Load ticket, create plan, sync it back', + task: 'Plan work and sync it back to the ticket', group: 'ticket', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Planning from ticket #128 — loading the ticket context with discussion, inspecting repo patterns, then syncing the scoped plan back to update the ticket.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'ticket_load', args: '#128 (with comments)', status: 'complete' }, - { tool: 'read', args: 'packages/core/commands/pr/review.md', status: 'complete' }, - { tool: 'glob', args: 'packages/core/components/*.md', status: 'complete' }, - { tool: 'ticket_sync', args: 'update #128 with plan', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Loaded ticket #128 and discussion history', - 'Created scoped implementation plan', - 'Synced plan back to ticket #128 with checklists' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Create a grounded plan, then write the title, description, and checklists back into the ticket flow.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'ticket_load', args: '#42 with comments', status: 'complete' }, + { tool: 'read', args: 'relevant docs files', status: 'complete' }, + { tool: 'ticket_sync', args: 'title, description, implementation checklist, validation checklist', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Title: `Refresh command reference docs`', + 'URL: https://github.com/kompassdev/kompass/issues/42', + 'No additional steps are required.' + ] } ] }, - - // PR commands { id: 'pr-create', label: '/pr/create', command: '/pr/create', - agentName: 'Build', - task: 'Summarize branch work and publish a structured PR', + agentName: 'Worker', + task: 'Create a structured PR from current branch work', group: 'pr', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Creating PR — loading branch changes and reading modified files to group themes. Will resolve ticket handling before publishing.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'changes_load', args: 'HEAD...main', status: 'complete' }, - { tool: 'read', args: 'packages/web/src/components/*.astro', status: 'complete' }, - { tool: 'question', args: 'Auto-create ticket, skip, or provide ticket?', status: 'complete' }, - { tool: 'ticket_sync', args: 'auto-create ticket #43', status: 'complete' }, - { tool: 'bash', args: 'git push origin HEAD', status: 'complete' }, - { tool: 'pr_sync', args: 'create PR with checklists', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Analyzed changes and grouped into functional themes', - 'Auto-created ticket #43 for tracking', - 'Created PR #47: Add workflow visualization to homepage' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Load the branch diff, stop on blockers, resolve ticket handling, push if needed, and create the PR with the required body structure.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'changes_load', args: 'main...HEAD', status: 'complete' }, + { tool: 'question', args: 'Provide Ticket', status: 'complete' }, + { tool: 'ticket_sync', args: 'auto-create ticket when selected', status: 'complete' }, + { tool: 'bash', args: 'git push', status: 'complete' }, + { tool: 'pr_sync', args: 'title, body, base, head, assignees', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Created PR: Refresh command reference docs', + 'URL: https://github.com/kompassdev/kompass/pull/51', + 'Ticket: https://github.com/kompassdev/kompass/issues/42' + ] } ] }, { id: 'pr-fix', label: '/pr/fix', command: '/pr/fix', - agentName: 'Build', - task: 'Fix requested PR changes', + agentName: 'Worker', + task: 'Fix review feedback, then push and reply', group: 'pr', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Fixing PR — loading PR #47 with review comments and feedback threads, then proposing fixes for approval before applying.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'pr_load', args: '#47', status: 'complete' }, - { tool: 'question', args: 'Apply these 3 fixes?', status: 'complete' }, - { tool: 'apply_patch', args: 'fix error handling in utils.ts', status: 'complete' }, - { tool: 'bash', args: 'git commit -m "fix: address review feedback"', status: 'complete' }, - { tool: 'bash', args: 'git push origin HEAD', status: 'complete' }, - { tool: 'pr_sync', args: 'reply to review threads', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Proposed 3 fixes for review feedback', - 'Applied fixes after user approval', - 'Pushed commit and replied to inline comments' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Address the feedback, validate the fixes, then in default mode wait for approval before committing, pushing, or replying on the PR.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'pr_load', args: 'current PR', status: 'complete' }, + { tool: 'apply_patch', args: 'implement requested fixes', status: 'complete' }, + { tool: 'question', args: 'Review Fixes', status: 'complete' }, + { tool: 'bash', args: 'git push', status: 'complete' }, + { tool: 'pr_sync', args: 'reply to addressed threads', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'PR fix complete for #51', + 'Threads resolved: 2', + 'Pushed: yes' + ] } ] }, { id: 'pr-review', label: '/pr/review', - command: '/pr/review', + command: '/pr/review 51', agentName: 'Reviewer', - task: 'Review PR with inline comments', + task: 'Review a PR and publish a graded review', group: 'pr', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Reviewing PR — loading PR #47, linked ticket, and diff context. Will analyze changes and publish a formal review with inline comments and grade.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'pr_load', args: '#47', status: 'complete' }, - { tool: 'ticket_load', args: '#42', status: 'complete' }, - { tool: 'changes_load', args: 'HEAD...main', status: 'complete' }, - { tool: 'pr_sync', args: 'publish review with comments', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Grade: ★★★★☆ — solid implementation with minor issues', - 'Line 45: Consider extracting this into a helper function', - 'Line 78: Add null check before accessing property', - 'Line 124: Typo in variable name "recieve" → "receive"' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Load the PR, optional linked ticket, prior review context, and diff, then publish only new eligible findings.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'pr_load', args: 'PR #51', status: 'complete' }, + { tool: 'ticket_load', args: 'linked ticket when one clear ticket exists', status: 'complete' }, + { tool: 'changes_load', args: 'base/head refs', status: 'complete' }, + { tool: 'pr_sync', args: 'submit graded review', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Review submitted for PR #51', + 'Grade: ★★★★☆', + 'No additional steps are required.' + ] } ] }, { id: 'review', label: '/review', - command: '/review', + command: '/review main', agentName: 'Reviewer', - task: 'Review branch changes without editing files', + task: 'Review branch changes locally', group: 'pr', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Reviewing changes — loading diff context and reading modified files to provide inline feedback and risk assessment without making edits.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'changes_load', args: 'uncommitted', status: 'complete' }, - { tool: 'read', args: 'packages/web/src/components/CommandShowcase.astro', status: 'complete' }, - { tool: 'task', args: 'reviewer analysis', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Grade: ★★★★☆ — clean implementation, minor suggestions', - 'Line 45: Consider extracting this into a helper function', - 'Line 78: Add null check before accessing property', - 'Line 124: Typo in variable name "recieve" → "receive"' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Load the diff, inspect the changed files with repo context, and return a local findings summary without publishing comments.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'changes_load', args: 'base: main', status: 'complete' }, + { tool: 'read', args: 'changed files', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Review complete for docs/reference-cleanup -> main', + 'Grade: ★★★★☆', + 'Findings: 2 total (0 critical, 1 high, 1 medium, 0 low)' + ] } ] }, - - // Orchestration commands { id: 'dev', label: '/dev', - command: '/dev implement the approved workflow in packages/core', + command: '/dev update the command docs', agentName: 'Navigator', - task: 'Orchestrate implementation with validation and checkpointing', + task: 'Implement a request and prepare a PR handoff', group: 'orchestration', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Planning implementation — loading ticket context and preparing to delegate tasks to workers. Will coordinate edits and validation checkpoints.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'ticket_load', args: '#128', status: 'complete' }, - { tool: 'dispatch', args: '/ticket/plan', status: 'complete' }, - { tool: 'dispatch', args: '/dev worker', status: 'complete' }, - { tool: 'dispatch', args: '/commit-and-push', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Planned implementation in coordination with ticket', - 'Delegated to worker for file edits and validation', - 'Committed changes and pushed to remote' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Implement the request, validate the result, and stop once the branch is ready for PR creation.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'read', args: 'relevant docs files', status: 'complete' }, + { tool: 'apply_patch', args: 'update docs and demo copy', status: 'complete' }, + { tool: 'bash', args: 'run targeted validation', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Implementation ready: refresh command docs', + 'Validation: docs checks passed', + 'Ready for PR creation on docs/reference-cleanup' + ] } ] }, { @@ -576,32 +367,20 @@ const scenarios: CommandScenario[] = [ label: '/ship', command: '/ship', agentName: 'Navigator', - task: 'Fast path from changes to PR', + task: 'Ship current work through delegated steps', group: 'orchestration', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Shipping — need to create a work branch, commit changes, and publish a PR. Will orchestrate the full workflow from current state to pull request.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'dispatch', args: '/branch feature/new-workflow', status: 'complete' }, - { tool: 'dispatch', args: '/commit', status: 'complete' }, - { tool: 'dispatch', args: '/pr/create', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Created branch: feature/new-workflow', - 'Committed 3 files with generated message', - 'Published PR #48: Add new workflow command' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Ensure a work branch, delegate commit creation, then delegate PR creation and stop on blockers.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'dispatch', args: 'worker · /branch', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /commit', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /pr/create', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Ship flow complete', + 'Branch: Created branch: docs/reference-cleanup', + 'PR: Created PR: Refresh command reference docs' + ] } ] }, { @@ -609,33 +388,22 @@ const scenarios: CommandScenario[] = [ label: '/todo', command: '/todo @TODO.md', agentName: 'Navigator', - task: 'Work through a todo list with checkpoint reviews', + task: 'Work through a todo file one item at a time', group: 'orchestration', steps: [ - { - id: 'thinking', - phase: 'thinking', - content: 'Processing todo — loading the todo list and keeping orchestration local. Will ask for plan approval before implementation starts.' - }, - { - id: 'tools', - phase: 'tool_calls', - toolCalls: [ - { tool: 'read', args: 'TODO.md', status: 'complete' }, - { tool: 'dispatch', args: '/ticket/plan #42', status: 'complete' }, - { tool: 'dispatch', args: '/dev', status: 'complete' }, - { tool: 'dispatch', args: '/commit', status: 'complete' } - ] - }, - { - id: 'output', - phase: 'output', - output: [ - 'Completed: Update command showcase with more examples', - 'Blocked: Waiting for review on PR #47', - 'Next: Add mobile responsive styling' - ] - } + { id: 'thinking', phase: 'thinking', content: 'Take the first unchecked item only, plan it, get approval, implement it, commit it, mark it complete, and loop.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'read', args: '@TODO.md', status: 'complete' }, + { tool: 'dispatch', args: 'planner · /ticket/plan', status: 'complete' }, + { tool: 'question', args: 'Plan Review', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /dev', status: 'complete' }, + { tool: 'dispatch', args: 'worker · /commit', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Todo complete: @TODO.md', + 'Remaining: 0', + 'No additional steps are required.' + ] } ] } ]; diff --git a/packages/web/src/content/docs/docs/adapters/opencode.mdx b/packages/web/src/content/docs/docs/adapters/opencode.mdx index f9ec9c0..c8128d9 100644 --- a/packages/web/src/content/docs/docs/adapters/opencode.mdx +++ b/packages/web/src/content/docs/docs/adapters/opencode.mdx @@ -31,7 +31,7 @@ You can use overrides to: ## Agent model -Most command execution runs on OpenCode's built-in `build` agent. +Most command execution runs on the bundled `worker` agent. Kompass also provides the `worker`, `navigator`, `planner`, and `reviewer` agent roles for structured subagent workflows and review-specific execution. 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 5cf6b0b..3ba6948 100644 --- a/packages/web/src/content/docs/docs/reference/agents/index.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/index.mdx @@ -7,20 +7,20 @@ description: Overview of the bundled Kompass agent roles. Kompass currently defines four bundled agent roles: `worker`, `navigator`, `planner`, and `reviewer`. -These are resolved from the merged config and exposed through the active adapter. +These are resolved from merged config and exposed through the active adapter. ### `worker` -Handles generic implementation work and can ask targeted follow-up questions when execution is blocked. +Generic worker role with minimal built-in behavior. It is the default execution agent when a command just needs focused work. ### `navigator` -Coordinates structured multi-step workflows locally and delegates only focused leaf work to subagents. +Owns structured multi-step workflows locally, preserves state and stop conditions, and forwards literal `` bodies to subagents when commands require delegation. ### `planner` -Turns a request or ticket into a scoped implementation plan. +No-edit planning specialist that turns requests or tickets into concise plans and performs light repo reconnaissance for technical work. ### `reviewer` -Reviews branch or PR changes without editing files. +No-edit review specialist that reviews diffs, PRs, files, tickets, and summaries using repository `AGENTS.md` guidance as binding review criteria. 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 827f321..9c7d0d0 100644 --- a/packages/web/src/content/docs/docs/reference/agents/navigator.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/navigator.mdx @@ -1,14 +1,21 @@ --- title: navigator -description: Orchestrator agent for multi-step workflows. +description: Orchestrator agent for structured multi-step workflows. --- ## Role -Coordinates structured multi-step workflows locally and delegates only focused leaf work to subagents. +`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. ## Best for - pause-and-resume workflows -- todo execution -- commit/PR orchestration +- stepwise orchestration such as `/ship` and `/todo` +- commands that mix local state handling with delegated leaf work + +## Key behavior + +- forwards literal `` bodies exactly after variable substitution +- delegates only explicit focused leaf work +- preserves workflow ownership even when subagents are used +- stops and reports blockers when a delegated step fails or returns incomplete work diff --git a/packages/web/src/content/docs/docs/reference/agents/planner.mdx b/packages/web/src/content/docs/docs/reference/agents/planner.mdx index dc3d2ca..663abac 100644 --- a/packages/web/src/content/docs/docs/reference/agents/planner.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/planner.mdx @@ -1,14 +1,21 @@ --- title: planner -description: Planning agent for turning requests and tickets into scoped implementation plans. +description: No-edit planning specialist for requests and tickets. --- ## Role -Turns a request or ticket into a scoped implementation plan. +`planner` turns requests, tickets, and gathered context into concise human-friendly plans that stay grounded in real repository context when the work is technical. ## Best for -- ticket planning -- acceptance-criteria breakdown -- implementation sequencing +- planning tickets before implementation +- refining technical direction from repo reality +- producing requirement and validation checklists + +## Key behavior + +- does not edit files or make repository changes +- performs light targeted repo inspection for technical work +- validates technical direction from conversation or tickets instead of repeating it blindly +- asks follow-up questions only when a reliable plan cannot be produced otherwise diff --git a/packages/web/src/content/docs/docs/reference/agents/reviewer.mdx b/packages/web/src/content/docs/docs/reference/agents/reviewer.mdx index 927e5a5..58578ba 100644 --- a/packages/web/src/content/docs/docs/reference/agents/reviewer.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/reviewer.mdx @@ -1,14 +1,21 @@ --- title: reviewer -description: Review-focused agent for branch and PR analysis without editing files. +description: No-edit high-signal review specialist. --- ## Role -Reviews branch or PR changes without editing files. +`reviewer` reviews diffs, PRs, files, tickets, summaries, and related code while treating repository `AGENTS.md` guidance as binding review criteria. ## Best for -- branch review -- PR review -- issue finding and feedback drafting +- local branch review +- GitHub PR review +- evaluating diffs and summaries without changing files + +## Key behavior + +- loads changed files and full file context before finalizing review conclusions +- focuses on material issues such as correctness, regressions, contracts, security, and partial updates +- skips style noise unless it hides a real defect or conflicts with `AGENTS.md` +- favors fewer high-confidence findings over speculative comments diff --git a/packages/web/src/content/docs/docs/reference/agents/worker.mdx b/packages/web/src/content/docs/docs/reference/agents/worker.mdx index 745a782..6a7649d 100644 --- a/packages/web/src/content/docs/docs/reference/agents/worker.mdx +++ b/packages/web/src/content/docs/docs/reference/agents/worker.mdx @@ -1,14 +1,20 @@ --- title: worker -description: Generic implementation agent for focused execution work. +description: Generic worker role used for focused execution. --- ## Role -Handles generic implementation work and can ask targeted follow-up questions when execution is blocked. +`worker` is the default generic worker agent. In the bundled config it has no specialized prompt and only minimal built-in policy beyond normal execution rules. ## Best for -- editing files -- implementing tasks from a plan -- making focused changes with validation +- focused implementation or follow-up work +- direct command execution that does not need planner, navigator, or reviewer specialization +- asking a targeted question when a command allows it and execution is blocked + +## Notes + +- bundled description: `Generic worker agent.` +- bundled permission: `question: allow` +- no dedicated bundled prompt file is loaded for this role diff --git a/packages/web/src/content/docs/docs/reference/commands/branch.mdx b/packages/web/src/content/docs/docs/reference/commands/branch.mdx index 0be17c4..2dd868f 100644 --- a/packages/web/src/content/docs/docs/reference/commands/branch.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/branch.mdx @@ -5,7 +5,7 @@ description: Create and switch to a categorized work branch from current uncommi ## Purpose -Use `/branch` to generate a concise feature branch name from the current uncommitted work. +Use `/branch` to create a short categorized branch name from current uncommitted work. ## Usage @@ -15,11 +15,19 @@ Use `/branch` to generate a concise feature branch name from the current uncommi ## Typical flow -- summarize uncommitted changes with `changes_load` -- skip if there is nothing to branch from or you are already on a work branch -- create and checkout a categorized branch such as `feature/...` or `docs/...` +- load uncommitted changes with `changes_load` +- stop with `Nothing to branch from` when there is no work +- skip when the current branch already looks like a work branch +- choose a category such as `feature`, `fix`, `refactor`, `docs`, `test`, or `chore` +- create and checkout `/`, retrying once with a numeric suffix if needed ## Common tools - `changes_load` - `bash(git checkout -b)` + +## Output + +- `Nothing to branch from` +- `Already on work branch: ` +- `Created branch: ` with the prior branch name diff --git a/packages/web/src/content/docs/docs/reference/commands/commit-and-push.mdx b/packages/web/src/content/docs/docs/reference/commands/commit-and-push.mdx index 5218748..9f963c6 100644 --- a/packages/web/src/content/docs/docs/reference/commands/commit-and-push.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/commit-and-push.mdx @@ -1,26 +1,29 @@ --- title: /commit-and-push -description: Commit current changes and push the branch in one workflow. +description: Create a commit from current work and push it immediately. --- ## Purpose -Use `/commit-and-push` when you want to move current work through commit creation and branch push in one pass. +Use `/commit-and-push` when current uncommitted work should become a commit and an updated remote branch in one pass. ## Usage ```text -/commit-and-push [message] +/commit-and-push [message-guidance] ``` ## Typical flow -- inspect the current diff -- create a commit with a provided or generated message -- push the branch upstream +- load uncommitted changes with `changes_load` +- stop with `Nothing to commit or push` when there is no work +- stage the relevant changes and create a commit +- run `git push` +- if no upstream is configured, retry with upstream setup ## Common tools -- `bash(git status)` +- `changes_load` +- `bash(git add)` - `bash(git commit)` - `bash(git push)` diff --git a/packages/web/src/content/docs/docs/reference/commands/commit.mdx b/packages/web/src/content/docs/docs/reference/commands/commit.mdx index 31f0ae9..62a0895 100644 --- a/packages/web/src/content/docs/docs/reference/commands/commit.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/commit.mdx @@ -1,26 +1,28 @@ --- title: /commit -description: Stage and commit current changes with a provided or generated message. +description: Create a commit from current uncommitted changes. --- ## Purpose -Use `/commit` to create a git commit from the current worktree. +Use `/commit` to stage current work, generate a commit message, and create a commit. ## Usage ```text -/commit [message] +/commit [message-guidance] ``` ## Typical flow -- inspect staged and unstaged changes -- generate a concise, why-focused commit message when one is not provided -- create the commit and verify the result +- load uncommitted changes with `changes_load` +- stop with `Nothing to commit` when there are no files +- stage the relevant changes +- generate a conventional commit message, using guidance when provided +- create the commit and return the hash plus rendered message ## Common tools -- `bash(git status)` -- `bash(git diff)` +- `changes_load` +- `bash(git add)` - `bash(git commit)` diff --git a/packages/web/src/content/docs/docs/reference/commands/dev.mdx b/packages/web/src/content/docs/docs/reference/commands/dev.mdx index f202f41..5611df1 100644 --- a/packages/web/src/content/docs/docs/reference/commands/dev.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/dev.mdx @@ -5,7 +5,7 @@ description: Implement a request or ticket, validate the changes, and prepare fo ## Purpose -Use `/dev` for focused implementation work. +Use `/dev` for focused implementation work that stops at a PR handoff. ## Usage @@ -27,4 +27,3 @@ Use `/dev` for focused implementation work. - `read` - `apply_patch` - `bash(...)` -- `task(worker)` 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 51c61ac..7cf6e3b 100644 --- a/packages/web/src/content/docs/docs/reference/commands/index.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/index.mdx @@ -15,9 +15,9 @@ Kompass ships workflow-oriented commands authored as explicit templates in `pack ## What makes them different - 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 -- outputs are written to be deterministic and reviewable +- placeholders like ``, ``, and `` are normalized before execution +- navigator workflows orchestrate locally and delegate focused leaf work with literal `` blocks +- outputs are deterministic, reviewable, and usually terminal ## Core workflows @@ -34,7 +34,7 @@ Answers a project or code question using only the relevant repository context. Creates and switches to a categorized work branch from current uncommitted changes. - usage: `/branch [context]` -- arguments: optional branch naming guidance +- arguments: optional naming guidance that can steer the category and slug - expected tools: `changes_load(uncommitted)`, `git checkout -b` ### `/commit` @@ -51,15 +51,15 @@ Creates a commit and immediately pushes it to the remote repository. - usage: `/commit-and-push [message-guidance]` - arguments: optional commit message guidance -- expected tools: `changes_load(uncommitted)`, git commit, `git push` +- expected tools: `changes_load(uncommitted)`, git commit, `git push` with upstream fallback when needed ### `/learn` -Extracts non-obvious learnings from the current session and documents them appropriately. +Extracts non-obvious learnings from the current session and documents them into the right `AGENTS.md` scope. - usage: `/learn [focus]` -- arguments: optional scope or extra guidance -- expected tools: `read`, `grep`, `apply_patch` +- arguments: optional focus scope or extra guidance +- expected tools: `read`, file edit tools ### `/rmslop` @@ -89,7 +89,7 @@ Creates a ticket summarizing the current change comparison. ### `/ticket/dev` -Implements a ticket by orchestrating development, branching, commit-and-push, and PR creation. +Implements a ticket by orchestrating `/dev`, `/branch`, `/commit-and-push`, and `/pr/create`. - usage: `/ticket/dev ` - arguments: ticket reference, URL, file path, or raw request @@ -115,17 +115,17 @@ Creates a scoped implementation plan from a request or ticket and stores that pl ### `/pr/create` -Creates a pull request for the current branch, including ticket handling when needed. +Creates a pull request for the current branch, including mandatory ticket resolution when the interaction tool is available. -- usage: `/pr/create [context]` -- arguments: optional base branch, ticket directive, ticket reference, or additional context +- usage: `/pr/create [base-or-ticket-context]` +- arguments: optional base branch, ticket directive, ticket reference, skip directive, or additional context - expected tools: `changes_load`, `question` when ticket handling is unresolved, `ticket_sync` when auto-creating a ticket, `git push`, `pr_sync` ### `/pr/fix` Addresses PR feedback by making fixes and responding to review threads. -- usage: `/pr/fix [context]` +- usage: `/pr/fix [pr-or-auto-or-context]` - arguments: optional PR ref, `auto`, or additional fix guidance - expected tools: `pr_load`, file-edit tools, validation commands, `question` unless `auto`, `git push`, `pr_sync` @@ -139,7 +139,7 @@ Reviews a GitHub pull request and publishes findings as a formal review. ### `/review` -Reviews code changes and provides actionable feedback with a grade and risk assessment. +Reviews code changes and returns a grade, verdict, and severity-counted findings summary without publishing comments. - usage: `/review [base-or-uncommitted]` - arguments: optional base branch, `uncommitted`, or review focus guidance @@ -165,7 +165,7 @@ Ships current work by delegating branch creation, commit creation, and PR creati ### `/todo` -Works through a todo file one pending item at a time with planning, approval, implementation, and commit loops. +Works through a todo file one pending item at a time with planning, approval, implementation, commit, checklist update, and repeat loops. - usage: `/todo [@todo-file]` - arguments: optional `@file` reference and execution guidance; defaults to `@TODO.md` diff --git a/packages/web/src/content/docs/docs/reference/commands/learn.mdx b/packages/web/src/content/docs/docs/reference/commands/learn.mdx index 5965e70..30a3913 100644 --- a/packages/web/src/content/docs/docs/reference/commands/learn.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/learn.mdx @@ -1,26 +1,26 @@ --- title: /learn -description: Extract repo conventions and operational guidance into AGENTS.md files. +description: Capture non-obvious learnings from the current session in the right documentation scope. --- ## Purpose -Use `/learn` to study patterns in the repository and encode the useful guidance where agents can reuse it. +Use `/learn` to document durable session discoveries in the most useful `AGENTS.md` scope. ## Usage ```text -/learn +/learn [focus] ``` ## Typical flow -- inspect current conventions in the repo -- summarize reusable rules and practices -- write the guidance into the appropriate `AGENTS.md` surface +- review the current session for non-obvious discoveries and repeated friction +- choose the narrowest useful scope such as root or package-level `AGENTS.md` +- read existing guidance before editing to avoid duplication +- add concise learnings and report which files were updated ## Common tools - `read` -- `grep` - `apply_patch` diff --git a/packages/web/src/content/docs/docs/reference/commands/pr-create.mdx b/packages/web/src/content/docs/docs/reference/commands/pr-create.mdx index 7e39514..6a5a597 100644 --- a/packages/web/src/content/docs/docs/reference/commands/pr-create.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/pr-create.mdx @@ -10,20 +10,22 @@ Use `/pr/create` to move current branch work into a reviewable pull request. ## Usage ```text -/pr/create [title-or-context] +/pr/create [base-or-ticket-context] ``` ## Typical flow - load branch changes against the base branch -- stop if there are uncommitted changes or no branch work to include -- resolve whether to attach or create a ticket +- stop if there are uncommitted changes, no branch work, or you are still on the base branch +- resolve ticket handling explicitly when the interaction tool is available +- auto-create a ticket when requested, otherwise use the provided ticket or literal `SKIPPED` - push the branch if needed -- create the PR with a compact description and checklist structure +- create the PR with `Ticket`, `Description`, and `Checklist` sections in that order ## Common tools - `changes_load` +- `question` - `ticket_sync` - `pr_sync` - `bash(git push)` diff --git a/packages/web/src/content/docs/docs/reference/commands/pr-fix.mdx b/packages/web/src/content/docs/docs/reference/commands/pr-fix.mdx index 72bd799..53c120f 100644 --- a/packages/web/src/content/docs/docs/reference/commands/pr-fix.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/pr-fix.mdx @@ -1,28 +1,30 @@ --- title: /pr/fix -description: Fix issues raised in PR review, push the updates, and reply to review threads. +description: Fix PR feedback with a review-first approval loop by default, then push and reply. --- ## Purpose -Use `/pr/fix` when a PR already exists and review feedback needs to be addressed. +Use `/pr/fix` when a PR already exists and review feedback needs another implementation pass. ## Usage ```text -/pr/fix [context] +/pr/fix [pr-or-auto-or-context] ``` ## Typical flow - load the PR and existing review state - implement the requested fixes on the current branch -- push the updated branch -- reply in the relevant review threads +- run relevant validation +- in default mode, show the fix summary and wait for user approval before commit, push, or replies +- skip that approval loop only with `/pr/fix auto` +- push the updated branch and reply in the relevant review threads after commit succeeds ## Common tools - `pr_load` -- `changes_load` +- `question` - `apply_patch` - `pr_sync` diff --git a/packages/web/src/content/docs/docs/reference/commands/pr-review.mdx b/packages/web/src/content/docs/docs/reference/commands/pr-review.mdx index 3fac8f0..96f0314 100644 --- a/packages/web/src/content/docs/docs/reference/commands/pr-review.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/pr-review.mdx @@ -1,11 +1,11 @@ --- title: /pr/review -description: Review a pull request and publish structured feedback. +description: Review a pull request and publish a formal graded review. --- ## Purpose -Use `/pr/review` to load a PR, inspect its changes, and publish the review result. +Use `/pr/review` to load a PR, inspect its changes, and publish a formal review result. ## Usage @@ -15,15 +15,15 @@ Use `/pr/review` to load a PR, inspect its changes, and publish the review resul ## Typical flow -- load the PR, reviews, comments, files, and diff context with `pr_load` -- if the PR references a ticket, load that ticket and its comments with `ticket_load` -- review the changes against the loaded repository context -- add inline comments and publish a review outcome such as approval or requested changes +- load PR metadata, review history, issue comments, and threads with `pr_load` +- optionally load one linked ticket when the PR body points to one clear ticket +- load the diff for the PR base and head refs +- filter out already-settled or previously-reviewed concerns +- publish a graded review through `pr_sync` ## Common tools - `pr_load` - `ticket_load` - `changes_load` -- `task(reviewer)` - `pr_sync` diff --git a/packages/web/src/content/docs/docs/reference/commands/review.mdx b/packages/web/src/content/docs/docs/reference/commands/review.mdx index 0cf4e73..90c4387 100644 --- a/packages/web/src/content/docs/docs/reference/commands/review.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/review.mdx @@ -1,25 +1,26 @@ --- title: /review -description: Review branch changes without publishing comments to GitHub. +description: Review current branch or uncommitted work and return a graded findings summary. --- ## Purpose -Use `/review` for a local branch review pass. +Use `/review` for a local review pass that does not publish comments. ## Usage ```text -/review [base] +/review [base-or-uncommitted] ``` ## Typical flow -- load the branch delta against the chosen base branch +- load branch or working-tree changes - inspect the changed files with repository-aware context -- return findings without mutating the branch or posting comments +- assign a grade and top-line verdict +- return severity-counted findings without mutating the branch or posting comments ## Common tools - `changes_load` -- `task(reviewer)` +- `read` diff --git a/packages/web/src/content/docs/docs/reference/commands/rmslop.mdx b/packages/web/src/content/docs/docs/reference/commands/rmslop.mdx index f43ff26..84ebacd 100644 --- a/packages/web/src/content/docs/docs/reference/commands/rmslop.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/rmslop.mdx @@ -1,27 +1,28 @@ --- title: /rmslop -description: Remove unnecessary AI-generated slop and simplify the current branch. +description: Clean AI-generated slop and inconsistencies out of branch changes. --- ## Purpose -Use `/rmslop` to simplify noisy or overly complex code and workflow output. +Use `/rmslop` to clean branch work that looks noisy, inconsistent, or overly AI-shaped. ## Usage ```text -/rmslop +/rmslop [base-or-guidance] ``` ## Typical flow -- inspect the branch for unnecessary complexity, duplication, or dead weight -- simplify code and supporting workflow surfaces -- leave the branch smaller and clearer +- load branch changes against an optional base branch +- identify slop such as awkward comments, abnormal defensive code, `any` escapes, emoji, or style drift +- make focused cleanup edits +- run relevant validation +- stage and commit the cleanup ## Common tools - `changes_load` -- `read` - `apply_patch` -- `task(reviewer)` +- `bash(...)` 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 defb327..9729b58 100644 --- a/packages/web/src/content/docs/docs/reference/commands/ship.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/ship.mdx @@ -1,11 +1,11 @@ --- title: /ship -description: Move branch work through summary, commit, and PR creation as a fast shipping path. +description: Move current work through branch, commit, and PR creation as a fast shipping path. --- ## Purpose -Use `/ship` when you want a fast path from current changes to a PR. +Use `/ship` when you want a fast path from current work to a PR through local orchestration. ## Usage @@ -15,13 +15,13 @@ Use `/ship` when you want a fast path from current changes to a PR. ## Typical flow -- summarize current changes -- create a work branch if you are still on the base branch -- delegate commit and PR creation as focused follow-up steps +- ensure there is a suitable work branch +- delegate `/commit` +- delegate `/pr/create` +- stop on blockers and report `Nothing to ship` when PR creation finds no shippable work ## Common tools -- `changes_load` -- `task(navigator)` -- `pr_sync` -- `bash(git checkout -b)` +- `dispatch(/branch)` +- `dispatch(/commit)` +- `dispatch(/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 86d6928..32a822f 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 @@ -1,11 +1,11 @@ --- title: /ticket/dev -description: Load a ticket, create a plan, execute the work, and prepare the result for shipping. +description: Implement a ticket by orchestrating development, branching, commit-and-push, and PR creation. --- ## Purpose -Use `/ticket/dev` when implementation starts from a tracked ticket. +Use `/ticket/dev` when implementation starts from a tracked ticket and should run through shipping. ## Usage @@ -16,13 +16,15 @@ Use `/ticket/dev` when implementation starts from a tracked ticket. ## Typical flow - load the ticket and its surrounding context -- create an implementation plan -- execute the work against that plan -- run relevant validation and return PR-ready 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 ## Common tools - `ticket_load` -- `task(planner)` -- `task(worker)` -- `bash(...)` +- `dispatch(/dev)` +- `dispatch(/branch)` +- `dispatch(/commit-and-push)` +- `dispatch(/pr/create)` diff --git a/packages/web/src/content/docs/docs/reference/commands/ticket-plan.mdx b/packages/web/src/content/docs/docs/reference/commands/ticket-plan.mdx index 53976cc..35324c3 100644 --- a/packages/web/src/content/docs/docs/reference/commands/ticket-plan.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/ticket-plan.mdx @@ -1,26 +1,27 @@ --- title: /ticket/plan -description: Create an implementation plan from a ticket or request before any code changes happen. +description: Create a scoped implementation plan from a request or ticket without syncing ticket state. --- ## Purpose -Use `/ticket/plan` to produce a scoped plan without executing changes. +Use `/ticket/plan` to shape a grounded implementation plan before any code changes happen. ## Usage ```text -/ticket/plan +/ticket/plan ``` ## Typical flow -- load the ticket, comments, and constraints -- inspect the relevant repository context -- draft a detailed implementation plan and handoff +- load ticket comments when planning from a ticket, otherwise use the request and conversation +- derive the planning objective, constraints, technical direction, and open questions +- do light repo reconnaissance for technical work +- return a title, short plan description, implementation checklist, and validation checklist without syncing ticket state ## Common tools - `ticket_load` -- `changes_load` -- `task(planner)` +- `read` +- `grep` 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 56c6658..82884a5 100644 --- a/packages/web/src/content/docs/docs/reference/commands/todo.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/todo.mdx @@ -1,27 +1,30 @@ --- title: /todo -description: Work through a todo file one item at a time with local orchestration. +description: Work through a todo file one item at a time with planning, approval, implementation, and commit loops. --- ## Purpose -Use `/todo` for structured, pause-and-resume work from a todo file. +Use `/todo` for structured pause-and-resume work from a checklist file. ## Usage ```text -/todo [todo-file] +/todo [@todo-file] ``` ## Typical flow -- load the todo file -- keep orchestration local -- delegate one focused task at a time -- report what is done, blocked, or next +- load `@TODO.md` by default or a provided `@file` +- take the first unchecked item only +- delegate `/ticket/plan`, show the plan, and require explicit approval before implementation +- delegate `/dev`, then `/commit`, then mark the checklist item complete +- repeat until there are no pending tasks left ## Common tools - `read` -- `task(navigator)` -- `task(worker)` +- `question` +- `dispatch(/ticket/plan)` +- `dispatch(/dev)` +- `dispatch(/commit)` diff --git a/packages/web/src/content/docs/docs/reference/components/change-summary.mdx b/packages/web/src/content/docs/docs/reference/components/change-summary.mdx index f160a6d..a3a9499 100644 --- a/packages/web/src/content/docs/docs/reference/components/change-summary.mdx +++ b/packages/web/src/content/docs/docs/reference/components/change-summary.mdx @@ -1,6 +1,12 @@ --- title: change-summary -description: Shared partial for loading and summarizing change context. +description: Shared partial for loading changes and summarizing them into themes. --- -Used in workflows that need a compact branch or working-tree summary before taking action. +## Behavior + +- calls `changes_load` +- accepts optional extra rules through `it.rules` +- stores the result as `` +- analyzes paths, statuses, and diffs +- groups related work into concise what/why themes diff --git a/packages/web/src/content/docs/docs/reference/components/changes-summary.mdx b/packages/web/src/content/docs/docs/reference/components/changes-summary.mdx index 8aa0cb9..cde4067 100644 --- a/packages/web/src/content/docs/docs/reference/components/changes-summary.mdx +++ b/packages/web/src/content/docs/docs/reference/components/changes-summary.mdx @@ -1,6 +1,12 @@ --- title: changes-summary -description: Shared partial for rendering grouped change summaries. +description: Shared partial for turning change themes into ticket- or PR-ready summary structure. --- -Used when ticket or PR bodies need a human-readable checklist or grouped summary of delivered work. +## Behavior + +- reuses the current change themes and rationale +- generates a concise title and short description +- produces 2-4 functional checklist sections +- always ends with one `Validation` section +- avoids file-by-file restatement and execution-status filler diff --git a/packages/web/src/content/docs/docs/reference/components/commit.mdx b/packages/web/src/content/docs/docs/reference/components/commit.mdx index cdad5e2..87580ad 100644 --- a/packages/web/src/content/docs/docs/reference/components/commit.mdx +++ b/packages/web/src/content/docs/docs/reference/components/commit.mdx @@ -1,6 +1,12 @@ --- title: commit -description: Shared partial for commit-oriented workflow steps. +description: Shared partial for commit message formatting and commit execution. --- -Used by commit-related command flows to keep staging, message generation, and git safety wording consistent. +## Behavior + +- prefers conventional commit subjects +- uses a subject-plus-bullets format for non-trivial changes +- stages changes with `git add` +- stores `` and `` +- only falls back to `git status` when commit creation fails diff --git a/packages/web/src/content/docs/docs/reference/components/dev-flow.mdx b/packages/web/src/content/docs/docs/reference/components/dev-flow.mdx index a5def9d..7fabe03 100644 --- a/packages/web/src/content/docs/docs/reference/components/dev-flow.mdx +++ b/packages/web/src/content/docs/docs/reference/components/dev-flow.mdx @@ -1,6 +1,12 @@ --- title: dev-flow -description: Shared partial for implementation-oriented execution flow. +description: Shared guidance block for implementation-oriented workflows. --- -Used by development workflows to keep request orientation, implementation, and validation sequencing consistent. +## Behavior + +- orient on the normalized request before editing +- survey the relevant codebase area before implementation +- prefer the smallest complete change +- validate with targeted checks before PR handoff +- surface detours or follow-up work that should stay out of the current change diff --git a/packages/web/src/content/docs/docs/reference/components/index.mdx b/packages/web/src/content/docs/docs/reference/components/index.mdx index c1c2d4a..043fdc1 100644 --- a/packages/web/src/content/docs/docs/reference/components/index.mdx +++ b/packages/web/src/content/docs/docs/reference/components/index.mdx @@ -19,28 +19,28 @@ Bundled components: ### `change-summary` -Shared partial for loading and summarizing change context. +Loads changes with `changes_load`, analyzes file-level diffs, and groups the work into concise what/why themes. ### `changes-summary` -Shared partial for rendering grouped change summaries. +Turns current change themes into a title, short description, grouped checklist sections, and a final validation section. ### `commit` -Shared partial for commit-oriented workflow steps. +Defines commit message formatting plus the stage-and-commit workflow shared by commit-oriented commands. ### `dev-flow` -Shared partial for implementation-oriented execution flow. +Provides a short navigation guide for implementation work from request orientation through targeted validation and handoff notes. ### `load-pr` -Shared partial for loading PR context in review-oriented workflows. +Loads PR context through `pr_load` and treats returned discussion, review history, and relevant attachments as source context. ### `load-ticket` -Shared partial for loading ticket context from GitHub, files, or text. +Loads ticket context through `ticket_load`, with optional comments, and treats returned discussion and relevant attachments as source context. ### `summarize-changes` -Shared partial for PR and ticket summary generation. +Guides commands to inspect comparison metadata, commit history, and changed files before grouping the work into themes. diff --git a/packages/web/src/content/docs/docs/reference/components/load-pr.mdx b/packages/web/src/content/docs/docs/reference/components/load-pr.mdx index ca79cf1..18ee76a 100644 --- a/packages/web/src/content/docs/docs/reference/components/load-pr.mdx +++ b/packages/web/src/content/docs/docs/reference/components/load-pr.mdx @@ -1,6 +1,12 @@ --- title: load-pr -description: Shared partial for loading PR context in review-oriented workflows. +description: Shared partial for loading PR context through `pr_load`. --- -Used in commands that need PR metadata, review history, and associated state before acting. +## Behavior + +- calls `pr_load` with an optional explicit PR ref +- stores the result in the caller-provided placeholder +- treats PR body, discussion, review history, and linked artifacts as source context +- asks commands to review relevant screenshots, PDFs, and other attachments when they matter +- notes inaccessible attachments as a context gap instead of ignoring them silently diff --git a/packages/web/src/content/docs/docs/reference/components/load-ticket.mdx b/packages/web/src/content/docs/docs/reference/components/load-ticket.mdx index 1ab1fee..1f71e06 100644 --- a/packages/web/src/content/docs/docs/reference/components/load-ticket.mdx +++ b/packages/web/src/content/docs/docs/reference/components/load-ticket.mdx @@ -1,6 +1,12 @@ --- title: load-ticket -description: Shared partial for loading ticket context from GitHub, files, or text. +description: Shared partial for loading ticket context through `ticket_load`. --- -Used when workflows start from a ticket reference and need one normalized ticket context object. +## Behavior + +- calls `ticket_load` with the provided source +- can opt into `comments: true` +- stores the result in the caller-provided placeholder +- treats ticket discussion and linked artifacts as source context +- notes inaccessible attachments as a context gap instead of assuming they do not matter diff --git a/packages/web/src/content/docs/docs/reference/components/summarize-changes.mdx b/packages/web/src/content/docs/docs/reference/components/summarize-changes.mdx index ea8f0bf..a3b9df1 100644 --- a/packages/web/src/content/docs/docs/reference/components/summarize-changes.mdx +++ b/packages/web/src/content/docs/docs/reference/components/summarize-changes.mdx @@ -1,6 +1,11 @@ --- title: summarize-changes -description: Shared partial for PR and ticket summary generation. +description: Shared guidance block for reading change context before final summaries. --- -Used when a command needs a concise, directional summary of current branch work before creating downstream artifacts. +## Behavior + +- notes comparison mode, base branch, and current branch +- reviews commit messages when they are available +- reads the most relevant changed files for real context +- groups related work into themes for the final summary diff --git a/packages/web/src/content/docs/docs/reference/tools/changes-load.mdx b/packages/web/src/content/docs/docs/reference/tools/changes-load.mdx index 28a53e6..164a950 100644 --- a/packages/web/src/content/docs/docs/reference/tools/changes-load.mdx +++ b/packages/web/src/content/docs/docs/reference/tools/changes-load.mdx @@ -1,11 +1,11 @@ --- title: changes_load -description: Load branch changes against a base branch. +description: Load uncommitted worktree changes or a branch comparison in structured form. --- ## Purpose -Load committed branch changes or uncommitted work in a structured form. +Use `changes_load` when a workflow needs the changed-file set and structured diffs without inferring git state manually. ## Inputs @@ -14,8 +14,15 @@ Load committed branch changes or uncommitted work in a structured form. - `depthHint` optional - `uncommitted` optional +## Returns + +- `comparison` as either `uncommitted` or `...` +- `branch` when the current branch is known +- `files` with status and diff data +- `commits` for branch comparisons when commit history is available + ## Useful for - branch review - PR creation -- change summaries +- commit and summary workflows diff --git a/packages/web/src/content/docs/docs/reference/tools/index.mdx b/packages/web/src/content/docs/docs/reference/tools/index.mdx index 3276272..d781db8 100644 --- a/packages/web/src/content/docs/docs/reference/tools/index.mdx +++ b/packages/web/src/content/docs/docs/reference/tools/index.mdx @@ -17,35 +17,20 @@ Current built-in tools: ### `changes_load` -Loads committed branch changes or uncommitted work in a structured form. - -- inputs: `base`, `head`, `depthHint`, `uncommitted` -- used by: branch review, PR creation, change summaries, cleanup flows +Loads either uncommitted worktree changes or a base/head git comparison, returning structured file diffs and optional commit metadata. ### `pr_load` -Loads PR metadata, review history, issue comments, and review threads. - -- inputs: `pr` -- used by: `/pr/review`, `/pr/fix` +Loads normalized PR metadata, review history, issue comments, review threads, repo identity, and viewer identity from GitHub. ### `pr_sync` -Creates, updates, comments on, or reviews a GitHub pull request. - -- notable inputs: `title`, `body`, `description`, `base`, `head`, `assignees`, `checklists`, `draft`, `refUrl`, `commitId`, `review`, `replies`, `commentBody` -- used by: `/pr/create`, `/pr/review`, `/pr/fix` +Creates PRs, updates PR metadata, posts comments and replies, and submits formal reviews against an existing PR. ### `ticket_load` -Loads a ticket from GitHub, a file path, or raw text. - -- inputs: `source`, `comments` -- used by: `/ticket/ask`, `/ticket/dev`, `/ticket/plan`, `/ticket/plan-and-sync`, and sometimes `/pr/review` +Loads a ticket from GitHub issue references, local files, or raw text, with optional GitHub comments. ### `ticket_sync` -Creates or updates a GitHub issue with checklist support. - -- notable inputs: `title`, `body`, `description`, `labels`, `assignees`, `checklists`, `refUrl`, `comments` -- used by: `/ticket/create`, `/ticket/ask`, `/ticket/plan-and-sync`, and `/pr/create` when ticket auto-creation is needed +Creates or updates GitHub issues, renders checklist sections, and can append issue comments. diff --git a/packages/web/src/content/docs/docs/reference/tools/pr-load.mdx b/packages/web/src/content/docs/docs/reference/tools/pr-load.mdx index 69af740..feab04b 100644 --- a/packages/web/src/content/docs/docs/reference/tools/pr-load.mdx +++ b/packages/web/src/content/docs/docs/reference/tools/pr-load.mdx @@ -1,17 +1,26 @@ --- title: pr_load -description: Load PR metadata and review history. +description: Load normalized PR metadata, review history, and thread context from GitHub. --- ## Purpose -Load normalized pull request context before reviewing or summarizing a PR. +Use `pr_load` when a workflow needs one grounded PR context payload instead of separate GitHub calls. ## Inputs -- `pr` optional +- `pr` optional; accepts a PR number or URL + +## Returns + +- `repo` +- `viewerLogin` +- `pr` metadata including title, body, URL, refs, commit count, and author +- `reviews` +- `issueComments` +- `threads` ## Useful for -- PR review -- PR fix workflows +- `/pr/review` +- `/pr/fix` diff --git a/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx b/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx index 90670dd..3ea5a95 100644 --- a/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx +++ b/packages/web/src/content/docs/docs/reference/tools/pr-sync.mdx @@ -1,11 +1,11 @@ --- title: pr_sync -description: Create, update, or review a GitHub pull request with structured checklist support. +description: Create, update, comment on, or review a GitHub pull request. --- ## Purpose -Use one tool surface for PR creation, updates, comments, replies, and formal review submission. +Use one tool surface for PR creation, metadata updates, comments, replies, and formal review submission. ## Notable inputs diff --git a/packages/web/src/pages/index.astro b/packages/web/src/pages/index.astro index ba25c73..54cd2ec 100644 --- a/packages/web/src/pages/index.astro +++ b/packages/web/src/pages/index.astro @@ -70,10 +70,27 @@ const heroHighlights = [ Kompass @@ -101,7 +118,7 @@ const heroHighlights = [ -
+
diff --git a/packages/web/src/styles/site.css b/packages/web/src/styles/site.css index 4f11f35..47f68b7 100644 --- a/packages/web/src/styles/site.css +++ b/packages/web/src/styles/site.css @@ -105,6 +105,7 @@ a { flex-wrap: wrap; gap: 1.15rem; color: var(--muted); + align-items: center; } .site-header nav a:hover, @@ -112,6 +113,45 @@ a { color: var(--text); } +.nav-button { + display: inline-flex; + align-items: center; + gap: 0.5rem; + min-height: 2.5rem; + padding: 0.65rem 1rem; + border: 1px solid rgba(125, 166, 196, 0.2); + border-radius: 999px; + background: rgba(9, 20, 31, 0.42); + color: var(--text); + transition: + transform 180ms ease, + border-color 180ms ease, + background-color 180ms ease, + box-shadow 180ms ease; +} + +.nav-button svg { + width: 1rem; + height: 1rem; + flex: 0 0 auto; +} + +.nav-button:hover, +.nav-button:focus-visible { + transform: translateY(-1px); + border-color: rgba(248, 184, 78, 0.34); + background: rgba(248, 184, 78, 0.12); + box-shadow: 0 12px 28px rgba(0, 0, 0, 0.16); +} + +.nav-button--docs { + background: linear-gradient(180deg, rgba(11, 28, 43, 0.86), rgba(9, 20, 31, 0.58)); +} + +.nav-button--github { + border-color: rgba(248, 184, 78, 0.26); +} + .hero__content { display: grid; grid-template-columns: minmax(0, 0.82fr) minmax(480px, 0.88fr);