Refresh bundled surface docs and showcase

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
 

packages/core/commands/index.ts

@@ -13,43 +13,43 @@ interface CommandDefinition {
 export const commandDefinitions: Record<string, CommandDefinition> = {
   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<string, CommandDefinition> = {
   },
   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<string, CommandDefinition> = {
   },
   "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": {

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<string, string> = {

packages/core/test/config.test.ts

@@ -276,13 +276,15 @@ 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, []);
     assert.deepEqual(config.agents.navigator.permission, {
       edit: "deny",
       task: "allow",
       question: "allow",
+      todowrite: "allow",
     });
   });
 

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,

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.

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.

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.

packages/opencode/.opencode/agents/worker.md

@@ -2,4 +2,5 @@
 description: Generic worker agent.
 permission:
   question: allow
+  todowrite: allow
 ---

packages/opencode/.opencode/commands/ask.md

@@ -1,6 +1,6 @@
 ---
 description: Answer questions about the current project or code
-agent: build
+agent: worker
 ---
 
 ## Goal

packages/opencode/.opencode/commands/branch.md

@@ -1,6 +1,6 @@
 ---
 description: Create a feature branch from current changes
-agent: build
+agent: worker
 ---
 
 ## Goal

packages/opencode/.opencode/commands/commit-and-push.md

@@ -1,6 +1,6 @@
 ---
 description: Commit and push current changes
-agent: build
+agent: worker
 ---
 
 ## Goal

packages/opencode/.opencode/commands/commit.md

@@ -1,6 +1,6 @@
 ---
 description: Commit current changes with a message
-agent: build
+agent: worker
 ---
 
 ## Goal

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
 ---
 

packages/opencode/.opencode/commands/learn.md

@@ -1,6 +1,6 @@
 ---
 description: Extract learnings from session to AGENTS.md files
-agent: build
+agent: worker
 ---
 
 ## Goal

packages/opencode/.opencode/commands/pr/create.md

@@ -1,6 +1,6 @@
 ---
 description: Summarize branch work and create a PR
-agent: build
+agent: worker
 ---
 
 ## Goal

packages/opencode/.opencode/commands/pr/fix.md

@@ -1,6 +1,6 @@
 ---
 description: Fix PR feedback, push updates, and reply
-agent: build
+agent: worker
 ---
 
 ## Goal

packages/opencode/.opencode/commands/rmslop.md

@@ -1,6 +1,6 @@
 ---
 description: Remove AI code slop from current branch
-agent: build
+agent: worker
 ---
 
 ## Goal

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

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

packages/opencode/.opencode/commands/ticket/dev.md

@@ -1,6 +1,6 @@
 ---
 description: Implement a ticket and create a PR
-agent: build
+agent: worker
 ---
 
 ## Goal

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
 

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",
     });
   });
 });

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");

packages/web/astro.config.mjs

@@ -35,7 +35,6 @@ export default defineConfig({
             "docs/reference/agents",
             "docs/reference/tools",
             "docs/reference/components",
-            "docs/reference/skills"
           ]
         },
         {