@cohortapp/agent-sdk 2.12.0 → 2.14.0

package/lib/telemetry/collect.test.mjs

@@ -933,3 +933,288 @@ test("collectStatus: machine.upgrade rides the beat when state/autoupdate/last.j
     assert.equal(injected.machine.upgrade.ok, false);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
+
+// ---------------------------------------------------------------------------
+// machine.sessionNote (WP-M8) — WHY the front door is not live
+// ---------------------------------------------------------------------------
+
+const M8_NOW = Date.parse("2026-09-11T12:00:00Z");
+/** The record scripts/session/supervisor.mjs writes via first-run#attentionRecord. */
+const attention = (over = {}) => ({
+  reason: "no-heartbeat",
+  since: "2026-09-11T11:57:00.000Z",
+  runMs: 180_000,
+  attach: "tmux attach -t =maestro-maya",
+  hint: "The session has been up 180 s without a heartbeat — it is probably waiting on a first-run dialog or a permission prompt. Attach with `tmux attach -t =maestro-maya` and answer it.",
+  ...over,
+});
+
+test("sessionNote: a live front door says nothing at all", () => {
+  const { sessionNote } = _internals;
+  assert.equal(sessionNote({ heartbeat: { ts: M8_NOW - 1_000 }, now: M8_NOW }), null);
+  assert.equal(sessionNote({ heartbeat: { ts: M8_NOW - 89_000 }, jobInstalled: false, attention: attention(), now: M8_NOW }), null,
+    "liveness wins over every other input — the note exists only to explain a door that is NOT open");
+  // A shorter staleness bound makes the same beat stale, and then it does speak.
+  assert.equal(sessionNote({ heartbeat: { ts: M8_NOW - 30_000 }, jobInstalled: true, now: M8_NOW, staleMs: 10_000 }).reason, "heartbeat-stale");
+});
+
+test("sessionNote: job-absent — no plist for this seat, and only ever from a hard false", () => {
+  const { sessionNote } = _internals;
+  const n = sessionNote({ jobInstalled: false, label: "ai.maestro.maya-session", now: M8_NOW });
+  assert.equal(n.reason, "job-absent");
+  assert.match(n.detail, /ai\.maestro\.maya-session/);
+  assert.equal(n.since, undefined, "there is no moment to date — the job was never there");
+  // It outranks a stale attention record left behind by a previous install.
+  assert.equal(sessionNote({ jobInstalled: false, attention: attention(), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "job-absent");
+  // UNKNOWN is not absent: a home we could not read must never accuse the seat.
+  assert.equal(sessionNote({ jobInstalled: null, now: M8_NOW }).reason, "never-beaten");
+  assert.equal(sessionNote({ now: M8_NOW }).reason, "never-beaten");
+  // No label still yields a usable line.
+  assert.match(sessionNote({ jobInstalled: false, now: M8_NOW }).detail, /main-session launchd job/);
+  // …and it does not call a deliberate daemon-front-door seat broken: this seat
+  // reports job-absent on EVERY beat forever, so the line states a configuration.
+  assert.match(n.detail, /the daemon --print lane is the front door/);
+  assert.match(n.detail, /by configuration, or the session job was never installed/);
+});
+
+test("sessionNote: awaiting-input passes the supervisor's own reason, since and hint through", () => {
+  const { sessionNote } = _internals;
+  const n = sessionNote({ jobInstalled: true, attention: attention(), now: M8_NOW });
+  assert.equal(n.reason, "awaiting-input", "the beat's vocabulary — the record's own reason rides in detail");
+  assert.equal(n.since, "2026-09-11T11:57:00.000Z", "attentionRecord.since, normalised to canonical ISO");
+  assert.match(n.detail, /^up, never beaten: /, "the record's own reason survives, rendered out of the watchdog's vocabulary");
+  assert.match(n.detail, /tmux attach -t =maestro-maya/, "the attach command is the actionable part");
+  assert.ok(n.detail.length <= 200);
+  // screen seats say screen.
+  assert.match(sessionNote({ attention: attention({ attach: "screen -r maestro-isla", hint: "… Attach with `screen -r maestro-isla` and answer it." }), now: M8_NOW }).detail, /screen -r maestro-isla/);
+  // It outranks a stale heartbeat: "waiting on a human" is the actionable fact.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "awaiting-input");
+});
+
+test("sessionNote: a heartbeat LATER than the attention record supersedes it", () => {
+  const { sessionNote } = _internals;
+  // supervisor.mjs clears attention.json only at the START of the next launch —
+  // never when the human answers the dialog — so the record outlives its truth.
+  // Answered at 11:57, beat until 3 days later, then the session died.
+  const beat = M8_NOW + 3 * 86_400_000;
+  const n = sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { ts: beat }, now: beat + 86_400_000 });
+  assert.equal(n.reason, "heartbeat-stale", "a days-old attach command for a mux session that ended is worse than no note");
+  assert.equal(n.since, new Date(beat).toISOString());
+  // A record with no orderable `since` loses to a heartbeat that has one.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention({ since: "not a date" }), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "heartbeat-stale");
+  // But the record still wins while it is the LATER fact — the ordinary case:
+  // the session came up, never beat, and the watchdog flagged it.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "awaiting-input");
+  // …and with no heartbeat at all there is nothing to supersede it.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { pid: 7 }, now: M8_NOW }).reason, "awaiting-input");
+});
+
+test("sessionNote: `since` is re-formatted from a parsed instant, never passed through", () => {
+  const { sessionNote } = _internals;
+  // V8's legacy date parser accepts trailing prose, so a bare Date.parse check
+  // let a home path and a token-shaped run ride the one field the detail
+  // sanitiser does not cover. `since` is canonical ISO or it is absent.
+  const evil = "Thu, 01 Jan 2026 00:00:00 GMT (token sk-ant-supersecretvalue1234567890 /Users/maya/x)";
+  assert.ok(Number.isFinite(Date.parse(evil)), "the hostile string really does parse — that is the hazard");
+  const n = sessionNote({ jobInstalled: true, attention: attention({ since: evil }), now: M8_NOW });
+  assert.equal(n.since, "2026-01-01T00:00:00.000Z");
+  assert.ok(!/Users|sk-ant/.test(n.since));
+  // Non-ISO spellings are normalised rather than echoed.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention({ since: "2026-09-11T11:57:00+00:00" }), now: M8_NOW }).since, "2026-09-11T11:57:00.000Z");
+});
+
+test("sessionNote: the attention record's own vocabulary is rendered, not collided with", () => {
+  const { sessionNote } = _internals;
+  // first-run#heartbeatSilence's "no-heartbeat" means "up, never beaten" — the
+  // opposite of what a beat reason of nearly that spelling would mean. Rendering
+  // it keeps `{reason, detail}` from reading as a contradiction side by side.
+  assert.match(sessionNote({ jobInstalled: true, attention: attention(), now: M8_NOW }).detail, /^up, never beaten: /);
+  assert.match(sessionNote({ jobInstalled: true, attention: attention({ reason: "stale-heartbeat" }), now: M8_NOW }).detail, /^no beat since this launch: /);
+  // A word we do not know passes through verbatim rather than being invented.
+  assert.match(sessionNote({ jobInstalled: true, attention: attention({ reason: "wedged-mcp" }), now: M8_NOW }).detail, /^wedged-mcp: /);
+  // And no beat reason collides with a watchdog reason any more.
+  const beatReasons = new Set(["job-absent", "awaiting-input", "heartbeat-stale", "heartbeat-unreadable", "never-beaten"]);
+  for (const r of ["no-heartbeat", "stale-heartbeat", "within-grace", "beating"]) assert.ok(!beatReasons.has(r), `${r} is the watchdog's word, not the beat's`);
+});
+
+test("sessionNote: heartbeat-stale carries the last beat and its age", () => {
+  const { sessionNote } = _internals;
+  const n = sessionNote({ jobInstalled: true, heartbeat: { ts: M8_NOW - 600_000, pid: 4242 }, now: M8_NOW });
+  assert.deepEqual(n, { reason: "heartbeat-stale", since: "2026-09-11T11:50:00.000Z", detail: "no beat for 600 s" });
+  // ISO timestamps are the shape the feed actually writes.
+  assert.equal(sessionNote({ jobInstalled: true, heartbeat: { ts: "2026-09-11T11:50:00Z" }, now: M8_NOW }).since, "2026-09-11T11:50:00.000Z");
+  // A beat from the future is clock skew, not a negative age.
+  assert.equal(sessionNote({ jobInstalled: true, heartbeat: { ts: M8_NOW + 600_000 }, now: M8_NOW }).detail, "last beat is in the future (clock skew)");
+});
+
+test("sessionNote: every malformed input degrades to a coarser note or to null, and nothing throws", () => {
+  const { sessionNote } = _internals;
+  // No `now` at all → no note (a note with no clock behind it would be a guess).
+  assert.equal(sessionNote({ heartbeat: { ts: 1 } }), null);
+  assert.equal(sessionNote({ now: NaN, jobInstalled: false }), null);
+  assert.equal(sessionNote(), null);
+  assert.equal(sessionNote(null), null);
+  assert.equal(sessionNote("nonsense"), null);
+  // Absent files (the reader's null) → the installed-but-silent note.
+  assert.deepEqual(sessionNote({ heartbeat: null, attention: null, jobInstalled: true, now: M8_NOW }),
+    { reason: "never-beaten", detail: "the session job is installed but has never written a heartbeat" });
+  // …and when job presence was never established, the note says THAT rather
+  // than affirming an installation nobody checked.
+  assert.deepEqual(sessionNote({ jobInstalled: null, now: M8_NOW }),
+    { reason: "never-beaten", detail: "no heartbeat from the session job, and its presence on this seat could not be checked" });
+  assert.equal(sessionNote({ now: M8_NOW }).detail, "no heartbeat from the session job, and its presence on this seat could not be checked");
+  // A parsed-but-wrong SHAPE must not throw.
+  assert.equal(sessionNote({ heartbeat: "{}", attention: "{}", now: M8_NOW }).reason, "never-beaten");
+  assert.equal(sessionNote({ heartbeat: [], attention: [], jobInstalled: true, now: M8_NOW }).reason, "never-beaten", "arrays are not records");
+  // A heartbeat file that is THERE but says nothing usable is its own fault —
+  // the job may well have beaten, so it is never called "never beaten".
+  assert.deepEqual(sessionNote({ heartbeat: { pid: 7 }, jobInstalled: true, now: M8_NOW }),
+    { reason: "heartbeat-unreadable", detail: "the heartbeat file is present but carries no readable timestamp" });
+  assert.equal(sessionNote({ heartbeat: { ts: "not a date" }, jobInstalled: true, now: M8_NOW }).reason, "heartbeat-unreadable");
+  assert.deepEqual(sessionNote({ heartbeatUnreadable: true, jobInstalled: true, now: M8_NOW }),
+    { reason: "heartbeat-unreadable", detail: "the heartbeat file is present but could not be parsed" });
+  // An attention record missing every field is still the right REASON — it is
+  // the file's existence that says "the supervisor flagged this seat".
+  assert.deepEqual(sessionNote({ attention: {}, jobInstalled: true, now: M8_NOW }), { reason: "awaiting-input" });
+  assert.deepEqual(sessionNote({ attention: { since: 12345, reason: 7, hint: null }, jobInstalled: true, now: M8_NOW }), { reason: "awaiting-input" });
+  assert.equal(sessionNote({ attention: { since: "not a date", reason: "no-heartbeat" }, jobInstalled: true, now: M8_NOW }).since, undefined);
+});
+
+test("sanitizeNoteDetail: no home paths, no ids, no control characters, never past the cap", () => {
+  const { sanitizeNoteDetail } = _internals;
+  assert.equal(sanitizeNoteDetail("attach with `tmux attach -t =maestro-maya`"), "attach with `tmux attach -t =maestro-maya`");
+  // Home directories name a person and leak the seat's layout.
+  assert.equal(sanitizeNoteDetail("blocked in /Users/maya/maya-ai/state"), "blocked in <path>");
+  // A home directory with a space in it is ordinary on macOS, and its tail
+  // carries the person's surname — the match may not stop at the whitespace.
+  assert.equal(sanitizeNoteDetail("blocked in /Users/olivia chen/maya-ai/state/session"), "blocked in <path>");
+  assert.equal(sanitizeNoteDetail("blocked in /Users/Olivia Chen/Library/Application Support/x"), "blocked in <path>");
+  // …but ordinary prose after a path is not swallowed with it.
+  assert.equal(sanitizeNoteDetail("blocked in /Users/maya and then retry"), "blocked in <path> and then retry");
+  assert.equal(sanitizeNoteDetail("attach to /Users/maya/x and answer it"), "attach to <path> and answer it");
+  assert.equal(sanitizeNoteDetail("blocked in ~/maya-ai and /home/maya/x and /private/var/folders/t/x"), "blocked in <path> and <path> and <path>");
+  // Session ids and token-shaped runs.
+  assert.equal(sanitizeNoteDetail("resume 3f2a1c94-7b0e-4a11-9c3d-0b7e2f8a6d51 failed"), "resume <redacted> failed");
+  assert.equal(sanitizeNoteDetail("token sk-ant-0123456789abcdef rejected"), "token <redacted> rejected");
+  // Newlines and control characters collapse; the note is one line.
+  assert.equal(sanitizeNoteDetail("a\nb\tc\r\nd"), "a b c d");
+  // The cap holds, with an ellipsis so a reader knows it was cut.
+  const long = sanitizeNoteDetail("lorem ipsum ".repeat(50));
+  assert.equal(long.length, 200);
+  assert.ok(long.endsWith("…"));
+  assert.ok(sanitizeNoteDetail("ab ".repeat(20), 10).length <= 10, "the cap is a ceiling, never exceeded (a word boundary can land under it)");
+  // Nothing to say → "", and the caller then omits the field entirely.
+  assert.equal(sanitizeNoteDetail(""), "");
+  assert.equal(sanitizeNoteDetail(null), "");
+  assert.equal(sanitizeNoteDetail(undefined), "");
+  assert.equal(sanitizeNoteDetail(42), "");
+  assert.equal(sanitizeNoteDetail("   \n  "), "");
+  // A hint long enough to overflow is truncated, not dropped.
+  const hint = sanitizeNoteDetail(`no-heartbeat: The session has been up 1800 s without a heartbeat — it is probably waiting on a first-run dialog or a permission prompt. Attach with \`tmux attach -t =maestro-maya\` and answer it. ${"tail ".repeat(20)}`);
+  assert.ok(hint.length <= 200 && hint.endsWith("…"), "an over-long hint is truncated, not dropped");
+});
+
+test("sessionJobInstalled: a readdir of ~/Library/LaunchAgents, and 'unknown' whenever it cannot be read", () => {
+  const { sessionJobInstalled, sessionJobLabel } = _internals;
+  const label = "ai.maestro.maya-session";
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya.plist", "ai.maestro.maya-session.plist"] }, label), true);
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya-session"] }, label), true, "bare labels count too");
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya.plist"] }, label), false);
+  assert.equal(sessionJobInstalled({ launchAgents: [] }, label), false);
+  // Unknowns: no label, an unreadable home, a home that is not there.
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya-session.plist"] }, ""), null);
+  assert.equal(sessionJobInstalled({ os: { homedir: () => "" } }, label), null);
+  assert.equal(sessionJobInstalled({ os: { homedir: () => { throw new Error("nope"); } } }, label), null);
+  assert.equal(sessionJobInstalled({ os: { homedir: () => join(tmpdir(), "no-such-home-xyz") } }, label), null);
+  // An explicit override wins (the daemon may already know).
+  assert.equal(sessionJobInstalled({ sessionJobInstalled: true, launchAgents: [] }, label), true);
+  // A case difference is not an absence: agentFirstName leaves its directory
+  // fallback as-is (`~/Maya-ai` -> `Maya`), and the volume is case-insensitive.
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.Maya-session.plist"] }, "ai.maestro.maya-session"), true);
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya-session.plist"] }, "ai.maestro.Maya-session"), true);
+  // The label matches what generate-plists.sh and `maestro session` spell —
+  // including its casing, which the generator does not lower-case either.
+  assert.equal(sessionJobLabel("/x/maya-ai", "maya"), "ai.maestro.maya-session");
+  assert.equal(sessionJobLabel("/x/Maya-ai", "Maya"), "ai.maestro.Maya-session");
+  assert.equal(sessionJobLabel("", ""), "");
+});
+
+test("collectStatus: machine.sessionNote appears ONLY when the front door is down, and rides machine (never session)", async () => {
+  const root = mkdtempSync(join(tmpdir(), "session-note-"));
+  try {
+    const now = Date.parse("2026-09-11T12:00:00Z");
+    const osImpl = fakeOs({});
+    osImpl.hostname = () => "seat.local";
+    const base = {
+      agentRoot: root, now, os: osImpl, execFile: fakeExecFile({}), subAgentsRunning: 0,
+      powermetrics: false, disk: false, spend: false, agentFirst: "maya", launchAgents: [],
+    };
+    const sess = join(root, "state", "session");
+    mkdirSync(sess, { recursive: true });
+
+    // 1. No job on the seat — the case A010/A016 could not tell apart.
+    const absent = await collectStatus(base);
+    assert.equal(absent.machine.sessionLive, false);
+    assert.equal(absent.machine.sessionNote.reason, "job-absent");
+    assert.match(absent.machine.sessionNote.detail, /ai\.maestro\.maya-session/);
+    assert.equal(absent.session, null, "the note NEVER touches session — hq validates that object strictly");
+    assert.ok(!("sessionNote" in (absent.session || {})));
+
+    // 2. Job installed, session up, waiting on a first-run dialog.
+    const installed = { ...base, launchAgents: ["ai.maestro.maya-session.plist"] };
+    writeFileSync(join(sess, "attention.json"), JSON.stringify(attention()));
+    const waiting = await collectStatus(installed);
+    assert.equal(waiting.machine.sessionNote.reason, "awaiting-input");
+    assert.equal(waiting.machine.sessionNote.since, "2026-09-11T11:57:00.000Z");
+    assert.match(waiting.machine.sessionNote.detail, /tmux attach -t =maestro-maya/);
+
+    // 3. The supervisor cleared attention.json and the beat then went stale.
+    rmSync(join(sess, "attention.json"));
+    writeFileSync(join(sess, "heartbeat.json"), JSON.stringify({ pid: 4242, ts: "2026-09-11T11:50:00Z" }));
+    const stale = await collectStatus(installed);
+    assert.equal(stale.machine.frontDoor, "session");
+    assert.deepEqual(stale.machine.sessionNote, { reason: "heartbeat-stale", since: "2026-09-11T11:50:00.000Z", detail: "no beat for 600 s" });
+
+    // 4. A live front door carries NO note — the key is absent, not null.
+    writeFileSync(join(sess, "heartbeat.json"), JSON.stringify({ pid: 4242, ts: "2026-09-11T11:59:50Z" }));
+    const live = await collectStatus(installed);
+    assert.equal(live.machine.sessionLive, true);
+    assert.ok(!("sessionNote" in live.machine), "a healthy seat must not pay for a field it has nothing to say in");
+
+    // 5. Corrupt state files never break the beat — and a heartbeat file that
+    //    is THERE and will not parse is reported as such, not as "never beaten".
+    writeFileSync(join(sess, "heartbeat.json"), "{not json");
+    writeFileSync(join(sess, "attention.json"), "{not json");
+    const corrupt = await collectStatus(installed);
+    assert.equal(corrupt.machine.sessionLive, false);
+    assert.deepEqual(corrupt.machine.sessionNote,
+      { reason: "heartbeat-unreadable", detail: "the heartbeat file is present but could not be parsed" });
+    assert.equal(typeof corrupt.ts, "string", "the snapshot is intact");
+
+    // 5b. No heartbeat file at all, job installed → never-beaten.
+    rmSync(join(sess, "heartbeat.json"));
+    rmSync(join(sess, "attention.json"));
+    const silent = await collectStatus(installed);
+    assert.deepEqual(silent.machine.sessionNote,
+      { reason: "never-beaten", detail: "the session job is installed but has never written a heartbeat" });
+
+    // 6. The whole note is a best-effort extra: a throwing os.homedir drops the
+    //    launchd read, never the beat — and an unknown job presence is reported
+    //    as neither an absence nor a presence.
+    const hostile = await collectStatus({ ...base, launchAgents: undefined, os: { ...osImpl, homedir: () => { throw new Error("no home"); } } });
+    assert.equal(hostile.machine.sessionNote.reason, "never-beaten", "unknown job presence is not an absence");
+    assert.equal(hostile.machine.sessionNote.detail, "no heartbeat from the session job, and its presence on this seat could not be checked",
+      "…and it is not reported as a presence either");
+    assert.equal(hostile.machine.sessionLive, false);
+
+    // 7. The emitted shape is exactly {reason, since?, detail?} — nothing else,
+    //    and nothing unbounded.
+    for (const s of [absent, waiting, stale, corrupt, silent, hostile]) {
+      const note = s.machine.sessionNote;
+      assert.equal(typeof note.reason, "string");
+      for (const k of Object.keys(note)) assert.ok(["reason", "since", "detail"].includes(k), `sessionNote.${k} is not in the contract`);
+      if (note.since !== undefined) assert.ok(Number.isFinite(Date.parse(note.since)), "since is ISO 8601");
+      if (note.detail !== undefined) assert.ok(note.detail.length <= 200 && !/\/Users\//.test(note.detail));
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.12.0",
+  "version": "2.14.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."
+}