@cohortapp/agent-sdk 2.11.14 → 2.11.15

package/lib/identity/persona.mjs

@@ -130,6 +130,35 @@ function voiceRules(a) {
   ];
 }
 
+/**
+ * Message-craft doctrine — the "how you shape an outbound message" half of the
+ * voice, injected into BOTH prompt-assembly paths so the two planes write the
+ * same way: the full-session prompt (scripts/daemon/prompt-builder.mjs
+ * #buildPrompt) and the quick-reply system prompt (scripts/daemon/responder.mjs
+ * #realGenerateResponse).
+ *
+ * Deliberately a separately-exported CONSTANT rather than part of voiceRules():
+ * the responder does not render the persona block — it calls neither renderPersona
+ * nor voiceRules — so folding it in would reach only full sessions and leave every
+ * reactive quick reply unshaped. As framework code it also survives per-seat
+ * CLAUDE.md drift, where the same doctrine lives as human-readable scaffold data.
+ *
+ * Phrased "distil by default; structure only when the message must be large" so it
+ * does NOT contradict the scaffold's `No unsolicited structure` rule
+ * (scaffold/CLAUDE.md `## Communication Rules`): headings/bullets are for the
+ * genuinely large message, never decoration on a small one. The attach-don't-dump
+ * bullet leans on mechanisms already sanctioned elsewhere in the prompt (the PDF
+ * builder, Slack upload, email --attachment) and on the standing "never reference a
+ * local file path" rule.
+ */
+export const MESSAGE_CRAFT = [
+  "How you shape a message:",
+  "- Distil to what matters, by default. Lead with the answer, the decision, or the ask; cut throat-clearing, restatement of the question, and background the reader already has. Most replies are a few sentences — send those as a few sentences, and keep them scannable.",
+  "- Offer depth, don't front-load it. Give the sharp version and add \"I can go deeper on X if useful\" rather than dumping every detail pre-emptively.",
+  "- When a message genuinely must be long, FORMAT it for legibility: a short intro line, then short paragraphs, a heading, or a few bullets for the parts that actually are a list. Structure serves a large message; it never decorates a small one, and it is never a wall of text.",
+  "- When the content is genuinely verbose — a full memo or report, a long analysis, a large table or dataset — do NOT dump it into the chat. Attach it as a document and put a two-to-three-line summary plus the attachment in the message: generate a branded PDF (scripts/pdf-generation/build-document.mjs, or `npm run pdf:memo -- --input <file.md>`) or upload the file (Slack: scripts/slack-upload-v2.py; email: send with --attachment). Never reference a local file path in an outbound message.",
+].join("\n");
+
 /**
  * Render the persona block from resolved config. Pure — no I/O, never throws.
  *

package/lib/identity/persona.test.mjs

@@ -4,7 +4,7 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { renderPersona, loadPersonaBlock } from "./persona.mjs";
+import { renderPersona, loadPersonaBlock, MESSAGE_CRAFT } from "./persona.mjs";
 
 const AGENT = {
   firstName: "Jamie",
@@ -100,6 +100,31 @@ test("junk values in list fields are dropped, not rendered", () => {
   assert.doesNotMatch(out, /\[object Object\]/);
 });
 
+// The message-craft doctrine is a separately-exported constant (NOT part of the
+// persona block) precisely so the responder — which never renders the persona —
+// can inject the identical string. These pin the substance both planes rely on.
+test("MESSAGE_CRAFT carries the distil-by-default / format-when-large / attach-when-verbose doctrine", () => {
+  // Distil by default; most replies are short.
+  assert.match(MESSAGE_CRAFT, /Distil to what matters, by default/);
+  assert.match(MESSAGE_CRAFT, /Lead with the answer, the decision, or the ask/);
+  // Offer depth on request rather than front-loading.
+  assert.match(MESSAGE_CRAFT, /Offer depth, don't front-load it/);
+  // Format only when the message must be large — never a wall of text.
+  assert.match(MESSAGE_CRAFT, /when a message genuinely must be long, FORMAT it/i);
+  assert.match(MESSAGE_CRAFT, /never a wall of text/);
+  // Attach verbose content with a short summary rather than dumping it.
+  assert.match(MESSAGE_CRAFT, /do NOT dump it into the chat/);
+  assert.match(MESSAGE_CRAFT, /two-to-three-line summary/);
+});
+
+test("MESSAGE_CRAFT names the REAL attach mechanisms and forbids local paths", () => {
+  assert.match(MESSAGE_CRAFT, /scripts\/pdf-generation\/build-document\.mjs/);
+  assert.match(MESSAGE_CRAFT, /npm run pdf:memo/);
+  assert.match(MESSAGE_CRAFT, /scripts\/slack-upload-v2\.py/);
+  assert.match(MESSAGE_CRAFT, /--attachment/);
+  assert.match(MESSAGE_CRAFT, /Never reference a local file path/);
+});
+
 test("loadPersonaBlock reads an agent repo, and fails open on a broken config", () => {
   const dir = mkdtempSync(join(tmpdir(), "persona-"));
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.11.14",
+  "version": "2.11.15",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scaffold/CLAUDE.md

@@ -103,6 +103,16 @@ message (Slack, email, WhatsApp, SMS, voice, drafted artefacts):
 - **Disagree when warranted.** Don't soften real concerns into politeness.
 - **Brevity is a feature.** If the answer is one sentence, send one
   sentence. Do not pad to look thorough.
+- **Distil by default; format only when large.** Lead with the answer,
+  the decision, or the ask; offer more detail on request rather than
+  front-loading it. When a message genuinely must be long, format it for
+  legibility (a short intro line, then short paragraphs or a few bullets)
+  — never a wall of text. When the content is genuinely verbose (a full
+  report, a long analysis, a large table), do NOT dump it in the chat:
+  attach it as a document and give a two-to-three-line summary. Generate a
+  branded PDF (`npm run pdf:memo -- --input <file.md>`) or upload the file
+  (Slack: `scripts/slack-upload-v2.py`; email: send with `--attachment`).
+  See Document Sharing below.
 
 System-style output (status indicators, checklists, formal headers) is
 opt-in — only when the user explicitly requests it or the medium clearly

package/scripts/daemon/prompt-builder.mjs

@@ -7,7 +7,7 @@ import { readFileSync, readdirSync } from "fs";
 import { join } from "path";
 import { createRequire } from "node:module";
 import { compileContext } from "./context-compiler.mjs";
-import { renderPersona } from "../../lib/identity/persona.mjs";
+import { renderPersona, MESSAGE_CRAFT } from "../../lib/identity/persona.mjs";
 import { wrapExternalContent } from "../../lib/security/external-content.mjs";
 import { isEnabled as orgEnabled } from "../../lib/org/client.mjs";
 import { recall as orgRecall } from "../../lib/org/knowledge.mjs";
@@ -876,6 +876,14 @@ export async function buildPrompt(item, classResult, options = {}) {
   parts.push(SKILLS_GUIDANCE);
   parts.push("");
 
+  // 1c. Message-craft doctrine — the shared "how you shape an outbound message"
+  // rule (distil by default; format only when the message must be large; attach
+  // rather than dump genuinely verbose content). Exported from persona.mjs and
+  // injected into the responder's quick-reply prompt too, so reactive replies and
+  // full sessions write outbound prose the same way.
+  parts.push(MESSAGE_CRAFT);
+  parts.push("");
+
   // 1a. Holding message warning — TOP OF PROMPT so Claude sees it before action instructions.
   // This is the most critical instruction in the prompt: prevents double-replies.
   // We repeat it at section 7a as well, immediately before the action block.

package/scripts/daemon/prompt-builder.test.mjs

@@ -212,6 +212,28 @@ test("buildPrompt caps the number of injected org facts (bounded)", async () =>
   });
 });
 
+// ---------------------------------------------------------------------------
+// Message-craft doctrine — the shared "how you shape an outbound message" rule
+// (distil by default; format only when the message must be large; attach
+// genuinely verbose content). The SAME constant leads the responder's quick-reply
+// system prompt, so reactive replies and full sessions write outbound prose the
+// same way.
+// ---------------------------------------------------------------------------
+
+test("buildPrompt injects the message-craft doctrine (distil / format / attach)", async () => {
+  writeOrgConfig(null);
+  const prompt = await buildPrompt(ITEM, CLASS, { type: "inbox" });
+  assert.match(prompt, /How you shape a message:/);
+  assert.match(prompt, /Distil to what matters, by default/);
+  assert.match(prompt, /when a message genuinely must be long, FORMAT it/i);
+  assert.match(prompt, /do NOT dump it into the chat/);
+  // The real attach mechanism, not a vague "share it somewhere".
+  assert.match(prompt, /scripts\/pdf-generation\/build-document\.mjs/);
+  assert.match(prompt, /scripts\/slack-upload-v2\.py/);
+  // The rest of the prompt is unchanged.
+  assert.ok(prompt.includes("--- INCOMING MESSAGE ---"));
+});
+
 test("buildPrompt states the acknowledgement was sent when it actually was", async () => {
   const prompt = await buildPrompt(ITEM, CLASS, {
     type: "inbox",

package/scripts/daemon/responder.mjs

@@ -60,6 +60,13 @@ import { startTyping, stopTyping } from "./typing-registry.mjs";
 // (in short: a 60s `claude --print` spawn to write "let me look into it" lost
 // its own race 2 times in 3, and lost it silently).
 import { composeAck } from "./assurance.mjs";
+// Shared message-craft doctrine (distil by default; format only when the message
+// must be large; attach genuinely verbose content rather than dumping it). The
+// SAME constant leads the full-session prompt in prompt-builder.mjs, so a reactive
+// quick reply and a full inbox/backlog session shape outbound prose identically.
+// This path never renders the persona block, which is why the doctrine is a
+// separately-exported constant rather than part of voiceRules().
+import { MESSAGE_CRAFT } from "../../lib/identity/persona.mjs";
 
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 const SONNET_MODEL = "claude-sonnet-4-6";
@@ -708,7 +715,9 @@ If it's informational, acknowledge appropriately.
 
 Keep responses focused — 1-4 sentences for simple items, up to a short paragraph for more nuanced ones.
 Match the sender's tone and urgency level.
-${profile ? `\nSender profile:\n${profile}` : ""}`;
+${profile ? `\nSender profile:\n${profile}` : ""}
+
+${MESSAGE_CRAFT}`;
 
   const conversationHistory = await loadConversationHistory(item);