@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/lib/prompts/parallelism.test.mjs

@@ -0,0 +1,177 @@
+/**
+ * parallelism.test.mjs — the fleet-wide parallelism directive (WP-M7 mechanic 5).
+ *
+ * Three things are pinned here, and each has a distinct failure it prevents:
+ *
+ *   1. THE BYTES. The directive is quoted verbatim in the design spec and is the
+ *      one place a fleet-wide behaviour change is auditable. A silent reword —
+ *      dropping the file-scope sentence, say — would turn "maximum safe
+ *      parallelism" into two agents editing one file. So the expected text is
+ *      written out longhand below, NOT derived from the constant.
+ *   2. IDEMPOTENCE. Two seams apply it (`session spawn` and the daemon's
+ *      prompt-builder) and they compose. A doubled directive reads as emphasis
+ *      to a model, which is exactly how the safety sentence loses to the
+ *      permission sentence.
+ *   3. BOTH WIRINGS. A constant nothing calls is worth nothing; the two seams
+ *      are driven for real here.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { PARALLELISM_DIRECTIVE, withParallelism, countParallelism } from "./parallelism.mjs";
+
+/**
+ * The directive, longhand. Deliberately NOT built from the import: a test that
+ * compares a constant to itself proves nothing about the wording.
+ */
+const EXPECTED = [
+  "You are allowed to run multiple sub-agents concurrently.",
+  "",
+  "When the plan contains independent tasks, dispatch them together in a single parallel batch rather than waiting for each task to finish before starting the next.",
+  "",
+  "Only run tasks sequentially when one task genuinely depends on the output of another.",
+  "",
+  "Before dispatching any batch, check the planned file scope for each task and ensure that no two agents are assigned to edit the same file. If tasks would overlap on a file, sequence those tasks or redefine their scope to eliminate the conflict.",
+  "",
+  "Default to maximum safe parallelism.",
+].join("\n");
+
+test("PARALLELISM_DIRECTIVE is the spec's text, byte for byte", () => {
+  assert.equal(PARALLELISM_DIRECTIVE, EXPECTED);
+  // The two sentences that carry the whole point, named individually so a
+  // partial reword fails with a readable diff rather than one giant blob.
+  assert.match(PARALLELISM_DIRECTIVE, /single parallel batch/);
+  assert.match(PARALLELISM_DIRECTIVE, /no two agents are assigned to edit the same file/);
+  assert.ok(!PARALLELISM_DIRECTIVE.endsWith("\n"), "no trailing newline — the joiner adds the separator");
+});
+
+test("withParallelism prepends once and is idempotent", () => {
+  const prompt = "Reply to the message below.";
+  const once = withParallelism(prompt);
+  assert.ok(once.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
+  assert.ok(once.endsWith(prompt), "the caller's prompt survives intact");
+  assert.equal(countParallelism(once), 1);
+
+  const twice = withParallelism(once);
+  assert.equal(twice, once, "a second application changes nothing");
+  assert.equal(countParallelism(twice), 1);
+
+  const thrice = withParallelism(withParallelism(withParallelism(prompt)));
+  assert.equal(countParallelism(thrice), 1);
+});
+
+test("withParallelism tolerates an empty or non-string prompt", () => {
+  assert.equal(withParallelism(""), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism("   \n "), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism(undefined), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism(null), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism(42), PARALLELISM_DIRECTIVE);
+});
+
+test("a prompt that already carries the directive mid-body is not re-led", () => {
+  const embedded = `Context first.\n\n${PARALLELISM_DIRECTIVE}\n\nThen the task.`;
+  assert.equal(withParallelism(embedded), embedded);
+  assert.equal(countParallelism(withParallelism(embedded)), 1);
+});
+
+test("countParallelism counts non-overlapping occurrences", () => {
+  assert.equal(countParallelism(""), 0);
+  assert.equal(countParallelism(null), 0);
+  assert.equal(countParallelism("nothing here"), 0);
+  assert.equal(countParallelism(`${PARALLELISM_DIRECTIVE}\n\n${PARALLELISM_DIRECTIVE}`), 2);
+});
+
+// ── the two wired seams ─────────────────────────────────────────────────────
+
+test("maestro session spawn leads every peer prompt with the directive, exactly once", async () => {
+  const { buildSpawnArgs } = await import("../cli/session.mjs");
+  const prompt = "Sweep the backlog and file what you find.";
+  const args = buildSpawnArgs({ first: "nova", slug: "sweep", prompt, env: {}, allowedTools: [] });
+
+  assert.equal(args[0], "--name");
+  assert.equal(args[1], "nova-sweep");
+  const sent = args[args.length - 1];
+  assert.ok(sent.startsWith(PARALLELISM_DIRECTIVE), "the peer's prompt is led by the directive");
+  assert.ok(sent.endsWith(prompt));
+  assert.equal(countParallelism(sent), 1);
+
+  // The composing case: a prompt that already carries it is not doubled.
+  const pre = withParallelism(prompt);
+  const again = buildSpawnArgs({ first: "nova", slug: "sweep", prompt: pre, env: {}, allowedTools: [] });
+  assert.equal(countParallelism(again[again.length - 1]), 1);
+  assert.equal(again[again.length - 1], pre);
+});
+
+test("the daemon's prompt-builder leads every sub-session prompt with the directive, exactly once", async (t) => {
+  const { mkdtempSync, mkdirSync, writeFileSync } = await import("node:fs");
+  const { join } = await import("node:path");
+  const { tmpdir } = await import("node:os");
+
+  const root = mkdtempSync(join(tmpdir(), "maestro-parallelism-prompt-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Nova" }));
+  const prevAgentDir = process.env.AGENT_DIR;
+  process.env.AGENT_DIR = root;
+  t.after(() => {
+    if (prevAgentDir === undefined) delete process.env.AGENT_DIR;
+    else process.env.AGENT_DIR = prevAgentDir;
+  });
+
+  const url = new URL("../../scripts/daemon/prompt-builder.mjs", import.meta.url);
+  const pb = await import(`${url.href}?parallelism=${Math.random()}`);
+  const prompt = await pb.buildPrompt(
+    { sender: "Ana", content: "Three unrelated things need doing.", channel: "slack" },
+    { action: "respond", priority: "normal", summary: "three things" },
+    { type: "inbox" },
+  );
+
+  assert.ok(prompt.startsWith(PARALLELISM_DIRECTIVE), "the directive leads the built prompt");
+  assert.equal(countParallelism(prompt), 1);
+  assert.match(prompt, /Three unrelated things need doing\./, "the item's own content is still there");
+});
+
+test("the persona's precedence sentence names itself, so leading the prompt with the directive cannot mis-scope it", async (t) => {
+  // The sentence used to read "The section above … anything below". That was
+  // true only while the persona was the first thing in the prompt; once the
+  // directive leads, "above" has two candidate referents and the directive
+  // itself falls outside the rule (it is above, not below). Nothing else pins
+  // this ordering, so it is pinned here, beside the change that broke it.
+  const { mkdtempSync, mkdirSync, writeFileSync } = await import("node:fs");
+  const { join } = await import("node:path");
+  const { tmpdir } = await import("node:os");
+
+  const root = mkdtempSync(join(tmpdir(), "maestro-parallelism-persona-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Nova", lastName: "Reyes", title: "Chief of Staff" }));
+  writeFileSync(join(root, "config", "company.json"), JSON.stringify({ name: "Northwind" }));
+  const prevAgentDir = process.env.AGENT_DIR;
+  process.env.AGENT_DIR = root;
+  t.after(() => {
+    if (prevAgentDir === undefined) delete process.env.AGENT_DIR;
+    else process.env.AGENT_DIR = prevAgentDir;
+  });
+
+  const url = new URL("../../scripts/daemon/prompt-builder.mjs", import.meta.url);
+  const pb = await import(`${url.href}?persona=${Math.random()}`);
+  const prompt = await pb.buildPrompt(
+    { sender: "Ana", content: "Three unrelated things need doing.", channel: "slack" },
+    { action: "respond", priority: "normal", summary: "three things" },
+    { type: "inbox" },
+  );
+
+  assert.ok(prompt.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
+  assert.ok(
+    !/The section above is your identity/.test(prompt),
+    "a positional referent is wrong the moment anything is prepended",
+  );
+  assert.match(
+    prompt,
+    /This section is your identity, resolved from your organisation's record of you\. Where anything else in this prompt conflicts with it, this section wins\./,
+    "the precedence rule names itself and covers the whole prompt",
+  );
+  assert.ok(
+    prompt.indexOf(PARALLELISM_DIRECTIVE) < prompt.indexOf("This section is your identity"),
+    "the directive leads and the persona follows — the ordering the sentence had to stop assuming",
+  );
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "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/plugins/maestro-skills/plugin.json

@@ -155,6 +155,10 @@
       "name": "peer-sessions",
       "description": "Spawn, find and talk to the agent's own peer sessions with ListAgents/SendMessage and `maestro session spawn|peers`, and relay their status to a human in the agent's own voice. Use for parallel work, when a human asks how something is going, or when a peer reports back."
     },
+    {
+      "name": "cohort-design",
+      "description": "Harmonise the installed design skills with Cohort's own design system — DESIGN.md, PRODUCT.md and the design_* tools outrank every skill's defaults; impeccable for product-UI craft, the motion skills for animation, the taste skills for marketing pages only, unlazy for completion gates. Use before any design, redesign, polish, critique, audit, layout, typography, colour or motion work."
+    },
     {
       "name": "persona-discipline",
       "description": "Be one persona to every human — never name Claude Code, sessions, sub-sessions, subagents, workflows or models in anything a person could read; how to rewrite when the pre-send audit blocks a message. Use before any outbound message or when the send hook blocks."

package/plugins/maestro-skills/skills/cohort-design.md

@@ -0,0 +1,153 @@
+---
+name: cohort-design
+description: Harmonise the installed design skills with Cohort's own design system for any interface work — design, redesign, layout, typography, colour, polish, critique, audit, accessibility, motion and animation, component and design-token work, landing and marketing pages, or making something feel less templated. Read this FIRST, before impeccable, the motion skills, design-taste-frontend, high-end-visual-design, minimalist-ui, redesign-existing-projects or unlazy, so the craft they carry lands on Cohort's tokens, typeface and voice rather than their own defaults.
+---
+
+# Cohort design — which skill wins, and where the truth lives
+
+Several strong design skills are installed on this machine. They are craft:
+they know what good looks like, how to critique, what motion should feel like.
+None of them knows what **Cohort** looks like. This skill is the join.
+
+Read it before you open any of them, and keep its precedence in mind while you
+work — the moment a skill's default and Cohort's system disagree, this is the
+tie-break.
+
+## The source of truth is Cohort's own, always
+
+**`DESIGN.md` and `PRODUCT.md` in the agent directory, and the `design_*` tools
+on the `cohort` MCP server, outrank every installed skill on every question of
+substance:** palette, typeface, type scale, spacing, radii, component grammar,
+imagery, templates, and the voice the copy is written in.
+
+- `DESIGN.md` lives at `$AGENT_ROOT/DESIGN.md` (the identity block at the top
+  of your context names the agent directory). It is generated from the
+  workspace's live brand foundation by `maestro design sync`, which also writes
+  `PRODUCT.md` and `state/design/foundation.json`. If the cwd is not the agent
+  directory — you are in a product repo, a site repo, a scratch directory —
+  read `$AGENT_ROOT/DESIGN.md` anyway. It is still the system of record.
+- If `DESIGN.md` is missing or looks stale, run `maestro design sync` and read
+  it. Do not proceed on a skill's default palette because the file was not
+  there.
+- The live foundation, the voice, the templates and the asset kit are reads on
+  the `cohort` MCP server: `design_foundation`, `design_voice`,
+  `design_list_templates`, `design_render_template`, `design_rewrite_in_voice`,
+  `design_export_kit`, `design_generate_image`. Prefer a rendered template and
+  an exported kit over hand-rolling an asset.
+- **Foundation changes are human-gated.** Your lane is `design_propose_change`,
+  which stages a reviewable diff and writes nothing. Never edit tokens in
+  `DESIGN.md` to make a design work; propose the change and design against
+  what exists meanwhile. `maestro-brand-steward` carries the full mechanics of
+  that surface.
+
+## Precedence
+
+1. **Cohort's own system** — `DESIGN.md`, `PRODUCT.md`, the `design_*` tools.
+   Tokens, type, voice, templates, assets, and every mutation.
+2. **`impeccable`** — craft, critique, audit and polish of product UI. Its
+   modes (shape, audit, critique, layout, typeset, clarify, distill, harden,
+   polish, optimize) are the working vocabulary for interface quality. Use it
+   for hierarchy, information architecture, cognitive load, accessibility,
+   states, edge cases and the finish pass.
+3. **The motion skills** — `animate`, `improve-animations`,
+   `review-animations`, `find-animation-opportunities`,
+   `animation-vocabulary`, `apple-design`, `emil-design-eng`. Anything that
+   moves: whether it should animate at all, which property, which curve, how
+   long, how it interrupts, how it exits, and reduced-motion.
+4. **`design-taste-frontend`, `high-end-visual-design`, `minimalist-ui`,
+   `redesign-existing-projects`** — **marketing and site pages only.** They
+   self-declare out of scope for dashboards, data tables, forms and multi-step
+   product UI, and they are right about that: their instincts are editorial.
+   Do not apply them to product surfaces.
+5. **`unlazy`** — completion gates on substantial work. Write the acceptance
+   gates before you start a large or multi-part design change, and re-verify
+   the evidence before you report it done.
+
+## The overrides — read these before you follow a skill's rule
+
+- **The em-dash ban does not apply to Cohort copy.** `design-taste-frontend`
+  and its siblings forbid em-dashes as an AI tell. Cohort's voice uses them.
+  `DESIGN.md` and `design_voice` decide punctuation, not a skill.
+- **Typeface and palette come from `DESIGN.md`, never from a skill's default.**
+  Every one of these skills names fonts and colours it likes. Those are
+  examples of taste, not instructions. A design that ships a skill's default
+  typeface is wrong even if it looks good.
+- **Never run `impeccable`'s launcher, its hooks, or its live browser mode on
+  this machine.** Only its markdown is installed here, deliberately: the
+  upstream launcher downloads and runs a binary on first use, and live mode
+  drives a browser. Read the skill, apply the judgement, do the work with the
+  tools you already have. The same rule covers its `hooks.md` guidance — no
+  hook from any of these packs is installed, and none should be.
+- **`impeccable`'s Setup step 1 cannot run here, and that is intended.** It
+  says to run `<skill-base-dir>/scripts/impeccable context` once before working.
+  That launcher is not installed, so the command will not be found. **Skip the
+  step and read the skill directly.** Do not reach for the recovery the pack
+  documents: `npx impeccable` (`update`, `detect`, `ignores`) downloads and runs
+  the package from a registry, which is the exact thing the vendored copy exists
+  to avoid. The same goes for `npx shadcn` and any other `npx <package>` a skill
+  suggests.
+- **Never install unlazy's Stop hook, and never reconstruct one by hand.**
+  `unlazy`'s prose describes a hook that blocks completion, and names the
+  settings files it would be written into. The scripts that install and
+  implement it are not on this machine at all. Its gate discipline is yours to
+  run deliberately; nothing from these packs may fire on its own, and no
+  settings file on this machine gains a hook because a skill suggested one.
+- **Never fetch a design file at run time, and never ship a remote reference.**
+  Not a font, not a token file, not a reference page, not a skill update.
+  Everything you are allowed to rely on is already on disk: the vendored skills,
+  `DESIGN.md`, and what the `design_*` tools return. A design that needs a
+  remote file at build time needs that file committed first.
+- **Nothing you generate may point at a third-party host** — no hotlinked
+  placeholder photography (`picsum.photos`), no remote icon service
+  (`cdn.simpleicons.org`), **never a remote script tag** to a vendor CDN, no
+  remote font. The marketing skills instruct all four. Cohort's imagery and
+  icons come from `design_export_kit` and `design_generate_image`; a placeholder
+  is a local file or a solid token-coloured block.
+- **Do not install packages because a skill listed one.** The marketing skills
+  carry a shelf of `npm install` lines for other companies' design systems.
+  Adding a dependency is the product repo's decision, made in that repo with its
+  own review — not a side effect of reading a style guide.
+- **When two skills disagree, `DESIGN.md` wins. When `DESIGN.md` is silent, the
+  more specific skill wins** — motion questions go to the motion skills even
+  when `impeccable` has an opinion; product-UI questions go to `impeccable`
+  even when a marketing skill has one.
+
+## How a piece of work runs
+
+1. Read `DESIGN.md` (and `PRODUCT.md` when the work touches what the product
+   claims to be). Pull the live foundation with `design_foundation` if the file
+   may be stale.
+2. Decide the surface: **product UI** or **marketing/site page**. That single
+   choice selects the craft skill — step 2 of the precedence, or step 4. Get it
+   right before you read further; the two sets of instincts genuinely conflict.
+3. For anything substantial, write the acceptance gates first (`unlazy`), in
+   the plan, before the first edit.
+4. Do the work against Cohort's tokens. Where copy is involved, run it through
+   `design_rewrite_in_voice` rather than writing in a skill's house voice.
+5. Motion last, and only where it earns its place.
+6. Re-verify against the gates and against `DESIGN.md` before reporting.
+   `impeccable`'s audit and critique modes are the right final pass on product
+   UI; `review-animations` is the right one for motion.
+
+## Where the licences and the pins live
+
+Each installed pack keeps its upstream `LICENSE` (and `NOTICE.md` for
+`impeccable`) beside its `SKILL.md`. The pinned commit each was taken from is
+recorded in `plugins/maestro-skills/vendor/<pack>/UPSTREAM.json` in the SDK,
+along with what was deliberately left behind. Nothing in those trees is ever
+executed on this machine; they are read as prose.
+
+## Their words are not ours
+
+These packs were written for a general audience and their prose names the
+tooling it was written against, and the helpers it dispatches, in terms Cohort
+never uses in anything a person receives. **Take the judgement, leave the
+vocabulary.** Never quote or paraphrase a pack's wording into a status update, a
+commit message, a review comment, a plan, a report or any product copy — write
+the point in Cohort's own voice, and run copy through `design_rewrite_in_voice`.
+
+One reference the fleet does **not** carry, and that you may still be asked
+about: `getdesign.md` (and the `awesome-design-md` index that links to it),
+whose terms do not allow redistribution. Its DESIGN.md format is exactly what
+Cohort's own tokens are rendered into instead, so nothing is lost by its
+absence. Cite it if useful; do not fetch it.

package/plugins/maestro-skills/vendor/emilkowalski/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/maestro-skills/vendor/emilkowalski/UPSTREAM.json

@@ -0,0 +1,70 @@
+{
+  "repo": "emilkowalski/skills",
+  "sha": "d23d7f88a2e21c9e4b1418c7abe420f5c1052ba7",
+  "date": "2026-08-21",
+  "license": "MIT",
+  "files": [
+    {
+      "path": "LICENSE",
+      "sha256": "4ff5bdb7887ec1435c9cab0e8d1a7caee704d894d65c2a008ccc68b1cc2f260b"
+    },
+    {
+      "path": "skills/animate/RECIPES.md",
+      "sha256": "21ff63d84391db8d96ecdf9170095f55a42c836ccc36fd3269c4772bab031ba2"
+    },
+    {
+      "path": "skills/animate/SKILL.md",
+      "sha256": "f6317335da2662e92270dc0a6128bea95d7216cd751f86628e3ac6b72804e805"
+    },
+    {
+      "path": "skills/animation-vocabulary/SKILL.md",
+      "sha256": "d718b48fe3c7898804d588f050a2e266d82c9f5ef51da256c8cb8b5951527757"
+    },
+    {
+      "path": "skills/apple-design/SKILL.md",
+      "sha256": "11840b24a11d7f94f39c6aaab074750ae4e4de4ef54ee4b1dd97e16ebd485e61"
+    },
+    {
+      "path": "skills/emil-design-eng/SKILL.md",
+      "sha256": "e71de849347050c2c573c1cf24d742d5a13459557ecffa6e562f08006f46b5b7"
+    },
+    {
+      "path": "skills/find-animation-opportunities/SKILL.md",
+      "sha256": "91c1243164057fbf824088d12faea937878a757a7ac653e8288b775e8b27b882"
+    },
+    {
+      "path": "skills/improve-animations/AUDIT.md",
+      "sha256": "551c8473e20e5f4774680bc24d45e1c68e50992582720905c6b077756b7b5a55"
+    },
+    {
+      "path": "skills/improve-animations/PLAN-TEMPLATE.md",
+      "sha256": "0a08ac8e23fd2082d7ffb86aeed7b789de77328c3cf874b16f1a755f2ef0a6ad"
+    },
+    {
+      "path": "skills/improve-animations/SKILL.md",
+      "sha256": "68f17bbc4671593d2f43dba26a679243e2153ba5f26965fb7d59df52842534ff"
+    },
+    {
+      "path": "skills/prototype/PICKER.md",
+      "sha256": "31a55eec94715cc79942e91e172e539e3031dcd5e2e5ee7c1446cf2caee960a6"
+    },
+    {
+      "path": "skills/prototype/SKILL.md",
+      "sha256": "2ad8401c4deaddb54947fb65247f790e7b3d8784e35312bcbedbfb1d59cd89ce"
+    },
+    {
+      "path": "skills/review-animations/SKILL.md",
+      "sha256": "61cf8ac0c4c8e1f63385298c546b16c65ca9aec34abddcd04e821c16712d671d"
+    },
+    {
+      "path": "skills/review-animations/STANDARDS.md",
+      "sha256": "e7d3605034acda54ca13e43aec9e64d65b53de20f75b11b8d694e373012fbe07"
+    }
+  ],
+  "omitted": [
+    "skills/pick-ui-library — library choice is Cohort's, settled in the product repo",
+    "skills/ask-sonner — a single third-party toast library's API",
+    "skills/write-swift, skills/animate-expo — native platforms this fleet does not ship"
+  ],
+  "notes": "MIT. Motion and design-engineering craft. Precedence sits below Cohort's DESIGN.md for tokens and type; these govern easing, duration and restraint."
+}