@korso/shepherd 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @korso/shepherd — Shepherd MCP Server
 
-Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) five advisory coordination tools backed by the shared hub: `join`, `work`, `done`, `announce`, and `sync`.
+Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory coordination tools backed by the shared hub: `work`, `done`, `announce`, and `sync`. The agent **joins the workspace automatically** on startup (no `join` tool), and the server ships standing instructions so the agent self-coordinates without the user prompting it.
 
 > **New here?** The [developer quickstart](https://github.com/Korsoai/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y @korso/shepherd` with the env vars below.
 
@@ -10,7 +10,7 @@ Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, et
 
 > **Everyone must set `WORKSPACE` to the identical string, and that string must equal the hub's `ALLOWED_WORKSPACE` env var.**
 
-If `WORKSPACE` does not match, the server's `join` call to the hub returns HTTP 400 immediately. The error is loud on purpose — you will see it in stderr the moment the first tool is called. This is the most common silent onboarding mistake; the guard turns it into a loud, immediate failure.
+If `WORKSPACE` does not match, the server's automatic `join` call to the hub (fired at startup) returns HTTP 400. Coordination then degrades: every tool reports "session not ready … proceeding uncoordinated" instead of a landscape. This is the most common silent onboarding mistake — if your agent never sees teammates, check `WORKSPACE` first.
 
 ---
 
@@ -156,7 +156,7 @@ No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to ex
 
 and the process exits 1 immediately. This is by design.
 
-**Wrong WORKSPACE:** the server starts and connects, but the first tool call (`work`, `sync`, etc.) returns a 400 from the hub. Check that your `WORKSPACE` value exactly matches the hub's `ALLOWED_WORKSPACE`.
+**Wrong WORKSPACE:** the server starts and connects, but the startup auto-join is rejected (400), so every tool call (`work`, `sync`, etc.) reports "session not ready … proceeding uncoordinated". Check that your `WORKSPACE` value exactly matches the hub's `ALLOWED_WORKSPACE`, then restart.
 
 ---
 
@@ -198,6 +198,6 @@ npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatical
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | `Configuration error — missing or invalid env vars` | One or more of the 8 env vars is absent | Add the missing vars to your client's `env` block |
-| Hub returns 400 on first tool call | `WORKSPACE` mismatch between client and hub | Set `WORKSPACE` to exactly match the hub's `ALLOWED_WORKSPACE` |
+| Tools report "session not ready … proceeding uncoordinated" | Startup auto-join rejected — usually `WORKSPACE` mismatch (or stale `TEAM_TOKEN`) | Set `WORKSPACE` to exactly match the hub's `ALLOWED_WORKSPACE`; re-check `TEAM_TOKEN`; restart |
 | `npm error 404 … @korso/shepherd` | Package not published yet, or name typo | `npm view @korso/shepherd version` to confirm it's live |
 | Process exits immediately with no error | Rare; check for node version incompatibility | Requires Node 18+ (ESM support) |

package/dist/index.js

@@ -247,71 +247,60 @@ function degradedResult(err) {
 function registerTools(server, deps) {
   const { hubClient, config } = deps;
   let sessionId = null;
-  let joinInFlight = null;
+  let agentName = null;
+  const joinBody = {
+    workspace: config.WORKSPACE,
+    repo: config.REPO,
+    branch: config.BRANCH,
+    human: config.HUMAN,
+    program: config.PROGRAM,
+    model: config.MODEL
+  };
+  const joinInFlight = hubClient.post("/join", joinBody).then((r) => {
+    sessionId = r.sessionId;
+    agentName = r.agentName;
+  }).catch(() => {
+  });
   async function awaitJoin() {
-    if (joinInFlight) await joinInFlight;
+    await joinInFlight;
   }
-  server.registerTool(
-    "join",
-    {
-      title: "Join coordination hub",
-      description: "Register yourself with the team coordination hub at the start of a session. Call once before any other coordination tool. Returns your assigned agent name and session ID that the other tools use automatically.",
-      inputSchema: JoinAgentInput.shape
-    },
-    async (_args) => {
-      try {
-        const body = {
-          workspace: config.WORKSPACE,
-          repo: config.REPO,
-          branch: config.BRANCH,
-          human: config.HUMAN,
-          program: config.PROGRAM,
-          model: config.MODEL
-        };
-        const pending = hubClient.post("/join", body);
-        joinInFlight = pending.then((r) => {
-          sessionId = r.sessionId;
-        }).catch(() => {
-        });
-        const result = await pending;
-        sessionId = result.sessionId;
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Joined as ${result.agentName}.`
-            }
-          ]
-        };
-      } catch (err) {
-        if (err instanceof HubUnreachable || err instanceof HubRequestError) {
-          return degradedResult(err);
+  function sessionNotReady() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Shepherd coordination session not ready (hub unreachable at startup) \u2014 proceeding uncoordinated."
         }
-        throw err;
-      }
-    }
-  );
+      ]
+    };
+  }
+  function withIdentity(body) {
+    return agentName ? `You are ${agentName}.
+
+${body}` : body;
+  }
   server.registerTool(
     "work",
     {
       title: "Claim a unit of work",
-      description: "Call this BEFORE you start a unit of work. It atomically checks whether any teammate's agent is already touching the same files and claims the work for you, returning any conflicts and what others are working on. Always call this before editing files.",
+      description: 'Claim a unit of work BEFORE you start editing files in an area of the codebase (per unit of work, NOT per edit). Pass a one-line `intent` and the `pathGlobs` covering the files you expect to touch \u2014 scope them as specifically as you reasonably can (e.g. ["src/auth/**"], not ["src/**"] and not a single file). It atomically checks whether a teammate is already in those files and claims them for you, returning any conflicts and what others are working on. Hold one claim across all edits in that area; don\'t re-claim per file.',
       inputSchema: WorkAgentInput.shape
     },
     async (args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        return sessionNotReady();
       }
       try {
         const body = { sessionId, ...args };
         const result = await hubClient.post("/work", body);
-        const text = `Work claimed (workItemId: ${result.workItemId})
+        const text = withIdentity(
+          `Work claimed (workItemId: ${result.workItemId})
+
+` + formatLandscape(result.landscape) + `
 
-` + formatLandscape(result.landscape);
+You hold this claim until you call done (workItemId: ${result.workItemId}) or it expires (~30 min). Calling work or sync renews it.`
+        );
         return { content: [{ type: "text", text }] };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -325,16 +314,13 @@ function registerTools(server, deps) {
     "done",
     {
       title: "Release a work claim",
-      description: "Call when you finish a unit of work to release your claim so teammates know the files are free. Pass the workItemId returned by the work tool.",
+      description: "Call when a unit of work is complete to release your claim so teammates know the files are free. Pass the workItemId returned by the work tool.",
       inputSchema: DoneAgentInput.shape
     },
     async (args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        return sessionNotReady();
       }
       try {
         const body = { sessionId, ...args };
@@ -343,7 +329,7 @@ function registerTools(server, deps) {
           content: [
             {
               type: "text",
-              text: "Work item released."
+              text: "Work item released. Call work again before your next edit in a new area."
             }
           ]
         };
@@ -359,16 +345,13 @@ function registerTools(server, deps) {
     "announce",
     {
       title: "Broadcast a message to teammates",
-      description: "Broadcast a heads-up to the other agents (or hand a specific agent a finding). This is awareness only \u2014 not a task assignment. Omit targetAgentName to broadcast to everyone in the workspace.",
+      description: "Broadcast a heads-up to the other agents, or direct a finding to a specific agent. This is awareness only \u2014 not a task assignment. To direct it, pass that agent's name (exactly as shown in the landscape) as targetAgentName; omit it to broadcast to everyone in the workspace. Delivery is best-effort: the recipient sees it on their next work/sync, once.",
       inputSchema: AnnounceAgentInput.shape
     },
     async (args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        return sessionNotReady();
       }
       try {
         const body = { sessionId, ...args };
@@ -393,21 +376,18 @@ function registerTools(server, deps) {
     "sync",
     {
       title: "Sync team landscape",
-      description: "Optional periodic pull of the latest team landscape (who's working on what, any messages for you). Also keeps your claims alive. Call this if you want to check for teammate activity without starting new work.",
+      description: "Pull the latest team landscape (who's working on what, any messages for you) and renew your active claims. Call when you resume, start a new task, or before large changes \u2014 or any time you want to check for teammate activity without claiming work.",
       inputSchema: SyncAgentInput.shape
     },
     async (_args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        return sessionNotReady();
       }
       try {
         const body = { sessionId };
         const result = await hubClient.post("/sync", body);
-        const text = formatLandscape(result.landscape);
+        const text = withIdentity(formatLandscape(result.landscape));
         return { content: [{ type: "text", text }] };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -417,13 +397,34 @@ function registerTools(server, deps) {
       }
     }
   );
+  return { ready: joinInFlight };
 }
 
+// src/instructions.ts
+var SHEPHERD_INSTRUCTIONS = `You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories. You have ALREADY been joined to the workspace automatically \u2014 there is no setup step, and you must not ask the user how to connect.
+
+Follow this procedure on every session, proactively and without being asked:
+
+1. Before you start working on an AREA of the codebase, call \`work\` ONCE. Pass a one-line \`intent\` and the \`pathGlobs\` covering the files you expect to touch. Scope the globs as specifically as you reasonably can \u2014 tight enough to avoid colliding with unrelated work, broad enough to cover the task (e.g. ["src/auth/**"], not ["src/**"] and not a single file). Hold that one claim across all your edits in that area; do NOT re-claim per file. If it reports a conflict, coordinate or pick different work \u2014 never silently collide.
+
+2. Call \`done\` when that unit of work is complete, using its \`workItemId\`, so teammates see the files freed.
+
+3. Re-call \`work\` only when you move to a DIFFERENT area not covered by a live claim. (\`work\` and \`sync\` also renew your existing claims.)
+
+4. Call \`announce\` whenever you discover something another agent needs \u2014 a shared decision, a gotcha, an API change, a finding. If the landscape shows a specific agent working in the affected area, direct it to them by passing their name as \`targetAgentName\`; otherwise broadcast. Awareness only, not task assignment.
+
+5. Call \`sync\` when you resume, start a new task, or before large changes, to refresh who is doing what.
+
+Skip \`work\` entirely for read-only exploration. These tools are advisory and degrade gracefully if the hub is unreachable \u2014 never block your real work on them.`;
+
 // src/index.ts
 async function main() {
   const config = loadConfig();
   const hubClient = createHubClient({ hubUrl: config.HUB_URL, teamToken: config.TEAM_TOKEN });
-  const server = new McpServer({ name: "shepherd", version: "0.1.0" });
+  const server = new McpServer(
+    { name: "shepherd", version: "0.1.0" },
+    { instructions: SHEPHERD_INSTRUCTIONS }
+  );
   registerTools(server, { hubClient, config });
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.1.0",
-  "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) five advisory cross-session coordination tools (join/work/done/announce/sync) backed by the shared Shepherd hub.",
+  "version": "0.2.0",
+  "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory cross-session coordination tools (work/done/announce/sync) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {