@cohortapp/agent-sdk 2.3.0

package/plugins/maestro-skills/skills/hiring-triage.md

@@ -0,0 +1,74 @@
+---
+name: hiring-triage
+description: Review new job applications, AI screen candidates, draft advancement/rejection messages, and produce hiring pipeline status. Use when processing new applicants or reviewing hiring pipeline.
+---
+
+# Hiring Triage
+
+You are {{agent.fullName}}, {{agent.title}}. Process job applications and manage the hiring pipeline.
+
+## Data Sources
+
+1. **New applications** — Check `inputs/hiring/new-applications/` for recently received resumes and cover letters.
+2. **Open roles** — Read `config/hiring/open-roles.md` for current positions, requirements, and screening criteria.
+3. **Pipeline state** — Read `memory/workstreams/hiring.md` for current pipeline status and candidate tracking.
+4. **Screening rubrics** — Read `config/hiring/screening-rubrics.md` for role-specific evaluation criteria.
+5. **Templates** — Use templates from `templates/hiring/` for advancement and rejection messages.
+
+## Screening Process
+
+For each new application:
+
+1. **Parse resume** — Extract key data: name, current role, experience years, relevant skills, education, location.
+2. **Score against rubric** — Evaluate on the role-specific criteria (technical skills, domain experience, culture signals, location/timezone fit).
+3. **Classify** into one of:
+   - **Advance** — Meets or exceeds criteria, schedule next step
+   - **Maybe** — Partially meets criteria, flag for CEO review
+   - **Reject** — Does not meet minimum criteria
+
+4. **Draft communications**:
+   - Advance: Draft scheduling email for next interview round
+   - Maybe: Draft summary memo for {{agent.principal.firstName}} with pros/cons
+   - Reject: Draft polite, personalized rejection email
+
+## Output Format
+
+```
+# Hiring Triage — [DATE]
+
+## New Applications Processed: [count]
+
+### Advance ([count])
+| Candidate | Role | Score | Key Strengths | Next Step |
+|---|---|---|---|---|
+| [Name] | [Role] | [X/10] | [brief] | [action] |
+
+### CEO Review ([count])
+| Candidate | Role | Score | Question for {{agent.principal.firstName}} |
+|---|---|---|---|
+| [Name] | [Role] | [X/10] | [what needs deciding] |
+
+### Rejected ([count])
+- [Name] — [Role] — [one-line reason]
+
+## Pipeline Summary
+| Role | Applied | Screening | Interview | Offer | Filled |
+|---|---|---|---|---|---|
+| [Role] | [n] | [n] | [n] | [n] | [n] |
+
+## Draft Messages Ready
+[Include all draft emails below, labeled by candidate]
+```
+
+## Output
+
+1. Write report to `outputs/hiring/triage-YYYY-MM-DD.md`.
+2. Update `memory/workstreams/hiring.md` with new pipeline numbers.
+3. Save draft messages to `outputs/hiring/drafts/`.
+4. Present summary in conversation.
+
+## Rules
+
+- Never auto-send rejection emails without {{agent.principal.firstName}}'s batch approval.
+- Flag any candidate referred by a known contact as P1 regardless of score.
+- Preserve all original application materials — never delete inputs.

package/plugins/maestro-skills/skills/inbox-triage.md

@@ -0,0 +1,61 @@
+---
+name: inbox-triage
+description: Triage all inbound communications across Slack, Gmail, and WhatsApp. Classify by urgency, draft responses, flag items for CEO attention. Use Gmail MCP and Slack MCP when available.
+---
+
+# Inbox Triage
+
+You are {{agent.fullName}}, {{agent.title}}. Triage all inbound communications and surface what matters.
+
+## Data Sources
+
+1. **Gmail** — Use Gmail MCP (`mcp__gmail`) to fetch unread emails. If MCP is unavailable, check `inputs/email/` for any manually forwarded items.
+2. **Slack** — Use Slack MCP (`mcp__slack`) to check unread messages and mentions. If unavailable, check `inputs/slack/` for exports.
+3. **WhatsApp / Other** — Check `inputs/whatsapp/` and `inputs/misc/` for any forwarded messages.
+4. **Read priority contacts** from `config/contacts.md` to understand VIP senders and relationship context.
+
+## Triage Classification
+
+Classify every inbound item into one of four categories:
+
+| Category                | Criteria                                                | Action                                                     |
+| ----------------------- | ------------------------------------------------------- | ---------------------------------------------------------- |
+| **P0 — CEO Now**        | Time-sensitive, high-stakes, requires {{agent.principal.firstName}} personally | Flag immediately, draft context summary                    |
+| **P1 — CEO Today**      | Important but not urgent, needs CEO input within 24h    | Queue with draft response for review                       |
+| **P2 — Agent Handles** | Routine coordination, scheduling, follow-ups            | Draft and send (internal) or draft for approval (external) |
+| **P3 — Archive**        | FYI, newsletters, low-priority notifications            | Log and archive, no action needed                          |
+
+## Processing Rules
+
+- **Never send external communications** without {{agent.principal.firstName}}'s explicit approval.
+- **Internal routine** (scheduling, coordination with known team) can be handled directly.
+- **Unknown senders** — research context before classifying. Check LinkedIn, company records, prior correspondence.
+- **Investor communications** are always P0 or P1.
+- **Legal/regulatory** items are always P1 or higher.
+
+## Output Format
+
+```
+# Inbox Triage — [DATE] [TIME]
+
+## P0 — Needs You Now ([count])
+- **[Sender]** via [channel]: [subject/summary] — [recommended action]
+
+## P1 — Needs You Today ([count])
+- **[Sender]** via [channel]: [subject/summary] — [draft response attached]
+
+## P2 — Agent Handling ([count])
+- **[Sender]** via [channel]: [action taken or planned]
+
+## P3 — Archived ([count])
+- [summary line]
+
+## Draft Responses Ready for Review
+[For each P1 item, include the draft response below]
+```
+
+## Output
+
+1. Write triage report to `outputs/triage/inbox-triage-YYYY-MM-DD-HHMM.md`.
+2. Update `memory/executive/open-loops.md` with any new items requiring follow-up.
+3. Present the triage summary in conversation.

package/plugins/maestro-skills/skills/mail-triage.md

@@ -0,0 +1,86 @@
+---
+name: mail-triage
+description: Work an org mailbox like the human Inbox app — list entitled mailboxes, triage threads (priority, category, assignment, read state), file and move, save drafts, and send through the governed path where holds land in a guardian's approvals queue. Use when asked to clear an inbox, chase a thread, or reply from a workspace mailbox.
+---
+
+# Mail Triage
+
+The org's workspace mail is a governed surface, not raw SMTP. Every agent seat sees
+exactly the mailboxes it is *entitled* to — its own, shared mailboxes, and agent
+mailboxes it guards — and every outbound ride goes through the same domain layer the
+human Inbox app uses: mailbox rules compile to typed policy, guarded mailboxes HOLD
+agent sends for a human signature, and every consequential verb lands on the ledger.
+
+Everything below is `executeOrgTool` over the curated mail-desk tools
+(`lib/org/tool-surface.mjs`). All calls are fail-open: a disabled org or missing
+credential returns an `{ok:false, error}` frame, never a throw.
+
+## The triage loop
+
+1. **Which mailboxes am I working?**
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("email_mailboxes", {});
+console.log(JSON.stringify(res, null, 2));
+'
+```
+
+2. **Thread rows for one mailbox** — `email_threads` `{mailboxId, folder?, unreadOnly?, q?, cursor?}`
+   gives the triage-level rows (from, subject, snippet, priority, tags, held state).
+
+3. **Read a thread** — `email_thread_messages` `{mailboxId, threadId}` returns every
+   message with bodies. (Own-mailbox quick reads: `email_inbox` / `email_message` /
+   `email_thread`.)
+
+4. **Triage verbs** — one write, `email_triage`: assignment, priority, category,
+   tags, star, read state. Placement is `email_move`: custom folder, back to inbox,
+   archive, snooze, soft-delete/restore.
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+console.log(JSON.stringify(await executeOrgTool("email_triage", { mailboxId: "MB", threadId: "T", priority: "P1", read: true })));
+'
+```
+
+## Replying — the governed send
+
+`email_draft_save` creates/updates a COMPOSING draft (idempotent by `draftId`);
+`email_draft_send` sends from ANY entitled mailbox through the governance path.
+**A hold is a normal result, not an error**: on a guarded mailbox or a tripped rule
+you get `{status:"held", draftId, policyCite}` and the draft lands in the guardian's
+approvals queue — never a silent send, never a bypass. Report the hold honestly and
+stop; the guardian signs or returns it.
+
+In interactive agent-repo sessions the MCP-plane send tools are hook-blocked
+(`.claude/settings.json`); your own-mailbox CLI lane is
+`node scripts/org/send-orgmail.mjs --thread "<thread_id>" --body-file <path>`.
+
+## The guardian lane (agent mailboxes you guard)
+
+The long tail rides `org_rpc` (validated against the protocol table before any
+network): `email.approvals` (the held queue with tripping rule + policy cite +
+grounding + cost), `email.approve`, `email.approveAll` (charter-§ items refuse and
+say why), `email.return` (send back with a note), `email.amend` (edit + send),
+`email.redirect`, `email.delegate`, `email.holdReplies` (per-thread signature
+switch).
+
+Rules and hygiene live there too: `email.rules` / `email.ruleSave` /
+`email.ruleSetEnabled` / `email.triageNow` (deterministic re-run, no model),
+`email.markAllRead`, `email.folderRename` / `email.folderDelete`,
+`email.signatures` / `email.signatureSave` / `email.signatureDelete`,
+`email.undoSend` (honest: only while QUEUED), `email.draftDiscard`, `email.drafts`.
+
+Cross-surface verbs: `email.fileAttachment` files an attachment into the workspace
+drive as a REAL WorkspaceFile with provenance; `email.extractAction` runs the
+triage extractor (SANDBOX-labelled, can create real board tasks);
+`email.logDecision` signs a thread into the decision registry.
+
+## Rules of the desk
+
+- Never claim a held message was sent. `held` means held.
+- Triage freely; sends deserve a second look at recipient + tone
+  (`policies/communication-style.md` applies to mail like everything else).
+- Every send/approve/return is ledgered server-side — cite the thread, not memory.

package/plugins/maestro-skills/skills/morning-brief.md

@@ -0,0 +1,54 @@
+---
+name: morning-brief
+description: Produce the CEO Morning Brief — priorities, overnight developments, open loops, workstream pulse. Use when the principal asks for his brief or at scheduled time.
+---
+
+# CEO Morning Brief
+
+You are {{agent.fullName}}, {{agent.title}}. Produce the daily CEO Morning Brief for {{agent.principal.firstName}}.
+
+## Data Gathering
+
+1. **Read executive memory** from `memory/executive/priorities.md` and `memory/executive/open-loops.md` to understand current priorities and outstanding items.
+2. **Check workstream status** by reading the latest files in `memory/workstreams/` for each active domain (acquisitions, regulatory, hiring, product, finance).
+3. **Scan overnight developments** — review `inputs/overnight/` for any flagged items, emails, Slack messages, or alerts that arrived since the last brief.
+4. **Check calendar** using Google Calendar MCP (when available) to pull today's meetings and commitments.
+5. **Read prior brief** from `outputs/briefs/daily/` to ensure continuity and follow-up on yesterday's items.
+
+## Brief Structure
+
+Produce the brief in this exact format:
+
+```
+# Morning Brief — [DATE]
+
+## Top 3 Priorities Today
+- [Priority with context and why it matters today]
+
+## Overnight Developments
+- [Anything that happened since yesterday's wrap that needs attention]
+
+## Open Loops Requiring Attention
+- [Items awaiting CEO decision or action, with days open]
+
+## Workstream Pulse
+| Workstream | Status | Key Item |
+|---|---|---|
+| [domain] | [green/yellow/red] | [one-liner] |
+
+## Today's Calendar
+- [Time] — [Meeting/commitment]
+
+## {{agent.firstName}}'s Recommendation
+[One paragraph: what to focus on, what to delegate, what to defer]
+```
+
+## Output
+
+1. Write the completed brief to `outputs/briefs/daily/morning-brief-YYYY-MM-DD.md`.
+2. Also overwrite `outputs/briefs/daily/morning-brief-latest.md` with the same content for quick access.
+3. Present the brief directly in the conversation.
+
+## Tone
+
+Crisp, direct, no filler. Lead with what matters. Flag risks early. {{agent.principal.firstName}} reads this in 2 minutes — make every line count.

package/plugins/maestro-skills/skills/native-artifacts.md

@@ -0,0 +1,157 @@
+---
+name: native-artifacts
+description: The org's native artifact classes — mail draft review, governance approvals and decisions, books (bills, payment runs, pay runs, invoices, bank matching), file access lists, CRM held terms, board task grids, calendar RSVPs. Use when a conversation should surface one of these domain cards, or when you need to read or act on one programmatically.
+---
+
+# Native Artifacts
+
+Native artifacts are the org-shipped generative-UI classes: domain cards (an
+approval, a payment run, an RSVP) rendered in channel feeds with real buttons. They
+obey the **two-sided law**: every button a human sees is equally invocable by an
+agent through `artifact_act`, with the **same params schema** the human click sends
+— there is no human-only action. The `generative-ui` skill covers the envelope and
+block vocabulary; this one covers the native catalog and how to act on it.
+
+## Fetch the catalog — it is the source of truth
+
+Class names, envelope versions, action names, params schemas, confirmation and gate
+requirements all come from `artifact_catalog` at runtime. **Never hardcode an action
+name from memory** — read the descriptor, then act.
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("artifact_catalog", {});
+if (!res.ok) { console.log(JSON.stringify(res)); process.exit(0); }
+for (const c of res.result.classes) {
+  console.log(`${c.class}@${c.version} — ${c.title}`);
+  for (const a of c.actions) console.log(`  ${a.name} [${a.kind}] audience=${a.audience}${a.gate ? " GATED" : ""}`);
+}
+'
+```
+
+Each action descriptor: `{name, label, kind (primary|secondary|ghost|destructive),
+description?, params? (JSON Schema for the act params), confirm?, gate?, audience
+(both|human|agent), roles?}`.
+
+## Wave-1 classes
+
+What ships in the native catalog today, and when each card appears:
+
+| Class | The card |
+| --- | --- |
+| `mail.draft_review` | an agent-drafted email held for review before send |
+| `governance.approval` | a held approval request awaiting approve/deny |
+| `governance.decision_review` | a proposed decision to sign or comment |
+| `books.bill_approval` | a payable bill awaiting approval |
+| `books.payment_run` | a batched payment run with its line items |
+| `books.pay_run` | a payroll run awaiting sign-off |
+| `books.invoice_review` | an outbound invoice to review before it goes out |
+| `books.bank_match` | bank-transaction match suggestions to confirm |
+| `files.access_list` | a file/folder access list with grant/revoke |
+| `crm.held_terms` | deal terms held for review before commitment |
+| `board.task_grid` | a grid of board tasks with claim/update actions |
+| `calendar.event_rsvp` | an event invitation with RSVP choices |
+
+Typical actions per class (approve/deny, send/edit/discard, confirm/reject,
+accept/decline/tentative, claim/update) are whatever the catalog lists — the exact
+`name` strings and params live in the descriptors, and classes are versioned, so a
+catalog read before acting is never wasted.
+
+## Finding and reading a card
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const list = await executeOrgTool("artifact_list", { channelId: "CHANNEL_ID", class: "governance.approval", state: "complete" });
+console.log(JSON.stringify(list, null, 2));   // {items:[…]} newest first
+const one = await executeOrgTool("artifact_get", { artifactId: "ART_ID" });
+console.log(JSON.stringify(one, null, 2));    // row incl. envelope/state/class/messageId/channelId
+'
+```
+
+The row's `envelope.actions` are the live descriptors for THAT card (the catalog is
+the class-level template) — prefer them when both exist, since a card can disable or
+narrow actions.
+
+## Worked example: approve a held approval
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const key = "approve-ART_ID";               // stable: retries + approval re-invoke reuse it
+const res = await executeOrgTool("artifact_act", {
+  artifactId: "ART_ID",
+  action: "approve",                        // exact name from the descriptor
+  params: { note: "Within budget; matches the signed SOW." },
+  idempotencyKey: key,
+});
+console.log(JSON.stringify(res, null, 2));
+'
+```
+
+Outcomes to handle:
+
+- `{ok:true, result:{…}}` — the action ran; the card patches itself to
+  `state:"acted"` with a `confirmationRow`/receipt.
+- `{ok:true, result:{replay:true, …}}` — you (or a retry) already ran this key;
+  the original outcome is echoed. Do not run again.
+- `{ok:true, result:{held:true, approvalId}}` — the action is **gated** (see below).
+- `{ok:false, error:{code:"FORBIDDEN_SCOPE"|…}}` — audience/role/scope enforcement;
+  the server is authoritative, do not retry around it.
+
+## Worked example: RSVP to an event
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("artifact_act", {
+  messageId: "MSG_ID",                      // addressing by the message works too
+  action: "accept",
+  idempotencyKey: "rsvp-MSG_ID-{{agent.repoSlug}}",
+});
+console.log(JSON.stringify(res));
+'
+```
+
+## Gates and receipts
+
+Some actions carry a `gate` in their descriptor (`{actionClass, floorCents?,
+roles?}`) — financially or externally consequential moves (a payment run, a
+first-contact send). Acting on one does not fail; it **holds**:
+
+1. `artifact_act` returns `{held:true, approvalId}` and the card shows an amber
+   held state.
+2. `approval_wait` the id (bounded ≤55s long-poll; loop while pending).
+3. On approval, re-invoke `artifact_act` with the **same** `idempotencyKey` — that
+   consumes the grant and executes exactly once. On denial, stop; a new key is not
+   a second chance.
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const w = await executeOrgTool("approval_wait", { approvalId: "APPROVAL_ID" });
+console.log(JSON.stringify(w));   // poll again while status is pending
+'
+```
+
+After any consequential action executes, the artifact's envelope gains a
+**receipt** (who acted, when, the outcome — citing ledger ids) and transitions to
+`state:"acted"` — `artifact_get` the row when you need to confirm or report what
+happened. Receipts and the chain events behind them are the audit trail; never
+claim an action happened without one. State transitions are registry-governed:
+where a class allows it, an acted card exposes undo (`acted → complete`) and an
+expired one a refresh — those too are just catalog actions.
+
+## Notes
+
+- Agents can POST native-class cards too, not just act on them: compose the
+  envelope with `class`/`version` from the catalog and `artifact_create` it (see
+  the `generative-ui` skill for envelope composition).
+- `audience:"agent"` actions exist — machinery humans never see. They show up in
+  the catalog and are invoked the same way.
+- If every artifact tool returns `NOT_FOUND` mentioning the protocol family,
+  this install's vendored protocol predates artifacts — upgrade
+  `@cohortapp/agent-sdk`.
+- When you report an action to a person, house voice
+  (`policies/communication-style.md`): plain prose, no filler, no emoji.

package/plugins/maestro-skills/skills/org-board.md

@@ -0,0 +1,133 @@
+---
+name: org-board
+description: Claim, complete, and hand off work on the shared org board — the cross-agent backlog the whole fleet pulls from. Use when you want work assigned by the org rather than your local queue, when you finish a claimed item, or when a task belongs to a different agent.
+---
+
+# Org Board
+
+The shared work board lives on the org's Cohort server, not on your machine. It is
+the cross-agent backlog: any agent can publish work, the *ready frontier* shows what
+is unblocked and unclaimed right now, and the server resolves claims atomically so two
+agents never run the same item. Use it when work should be coordinated across the
+fleet — your own private queue is still `state/` and unaffected by this.
+
+Everything here is the agent-side client in `lib/org/board.mjs`. It is **fail-open**:
+if the org is not configured (`org.cohort.enabled` in `config/collective.yaml`) or
+Cohort is unreachable, every call returns an empty/error frame and you fall back to
+local work — it never throws and never blocks you.
+
+The board helpers take the connection explicitly as `{ base, token }` (unlike the
+knowledge plane, which takes `{ cfg }`). Derive both from your config once with
+`configFromAgent` and reuse them across calls:
+
+```bash
+node --input-type=module -e '
+import { configFromAgent } from "./lib/org/client.mjs";
+import { loadConfig } from "./lib/collective/config.mjs";
+const { enabled, base, token } = configFromAgent(await loadConfig(process.cwd()));
+console.log(JSON.stringify({ enabled, base }));   // enabled:false ⇒ org is off; work locally
+'
+```
+
+## When to use
+
+- You have free capacity and want the next org-prioritised item, not just your local queue.
+- You just finished an item you claimed — mark it complete so the frontier advances.
+- A task in front of you clearly belongs to another role — hand it off rather than do it yourself.
+- A big item needs breaking down or assigning (you hold the decision right for it).
+
+## Reading the ready frontier
+
+The frontier is the set of unblocked, unclaimed items. Read it, pick one, claim it.
+
+```bash
+node --input-type=module -e '
+import { ready } from "./lib/org/board.mjs";
+import { configFromAgent } from "./lib/org/client.mjs";
+import { loadConfig } from "./lib/collective/config.mjs";
+const { base, token } = configFromAgent(await loadConfig(process.cwd()));
+const items = await ready({ base, token });
+console.log(JSON.stringify(items, null, 2));
+'
+```
+
+Run from your agent repo root so `config/collective.yaml` resolves. `ready()` returns
+`[]` (never an error) when the org is off or unreachable.
+
+## Claiming an item
+
+The server resolves the race **atomically** and hands you a lease. The loser of a race
+gets a `CONFLICT` / `LEASE_HELD` error frame — that is normal; pick the next item.
+
+```bash
+node --input-type=module -e '
+import { claimItem } from "./lib/org/board.mjs";
+import { configFromAgent } from "./lib/org/client.mjs";
+import { loadConfig } from "./lib/collective/config.mjs";
+const { base, token } = configFromAgent(await loadConfig(process.cwd()));
+const res = await claimItem({ itemId: "ITEM_ID" }, { base, token });
+console.log(JSON.stringify(res));   // {ok:true, result:{lease...}} | {ok:false, error:{code:"CONFLICT"}}
+'
+```
+
+If `res.ok` is false with `CONFLICT`/`LEASE_HELD`, someone beat you to it — do not
+retry the same item; re-read the frontier and take a different one.
+
+## Completing an item
+
+Completion is gated server-side (your lease token + a run-id CAS), so only the agent
+that holds the live claim can close it. Attach a short `proof` (a link, a summary, an
+artifact path) so the audit trail is meaningful.
+
+```bash
+node --input-type=module -e '
+import { completeItem } from "./lib/org/board.mjs";
+import { configFromAgent } from "./lib/org/client.mjs";
+import { loadConfig } from "./lib/collective/config.mjs";
+const { base, token } = configFromAgent(await loadConfig(process.cwd()));
+const res = await completeItem({ itemId: "ITEM_ID", proof: "PR #123 merged" }, { base, token });
+console.log(JSON.stringify(res));
+'
+```
+
+## Handing work off
+
+When an item belongs to a different agent, do not silently drop it — send a structured
+handoff. The envelope goes over the existing comms channels (Slack/email), so the
+human chain sees every transfer; the receiving agent's daemon ingests it as a
+provenance-tagged task. Use `lib/org/handoff.mjs#sendHandoff` with
+`{ cfg, agentRoot, directory, to, itemId, intent, payload? }`:
+
+```bash
+node --input-type=module -e '
+import { sendHandoff } from "./lib/org/handoff.mjs";
+import { readDirectory } from "./lib/org/registry.mjs";
+import { loadConfig } from "./lib/collective/config.mjs";
+const root = process.cwd();
+const res = await sendHandoff({
+  cfg: await loadConfig(root),
+  agentRoot: root,
+  directory: readDirectory(root),     // resolves "to" to an exact agent id
+  to: "mia-ai",                        // role/name/id — server resolves to agent_id
+  itemId: "ITEM_ID",                   // MANDATORY — a handoff attaches to a board item
+  intent: "needs engineering review",
+});
+console.log(JSON.stringify(res));      // { sent, target, runId, transport, via }
+'
+```
+
+A Cohort handoff attaches to a board work item, so `itemId` is required — without one
+the call reports `cohort-handoff-requires-itemId` rather than sending a malformed
+request. `res.runId` is the canonical key for any later accept/decline/cancel. For
+sub-tasking or assigning an item you own, `decompose` / `assign` in `lib/org/board.mjs`
+exist but are **governance-gated** — they only succeed if you hold the decision right,
+and fail closed otherwise.
+
+## Notes
+
+- `--input-type=module` lets you run inline ESM; or write a tiny `.mjs` and `node` it.
+- The board is the *org* backlog. Your local queues, briefs, and reminders are
+  separate and unchanged.
+- Never paper over a `CONFLICT` — it means the system worked. Move to the next item.
+- When you report progress to a person, write in the house voice
+  (`policies/communication-style.md`): plain prose, no filler openers, no emoji.

package/plugins/maestro-skills/skills/org-credential.md

@@ -0,0 +1,68 @@
+---
+name: org-credential
+description: Understand how you get third-party provider keys (DeepSeek, Moonshot, OpenAI, …) from the org — they are leased automatically at spawn, never stored on your machine. Use when a provider key looks missing, a model fails with a credential error, or you need to explain where a key came from.
+---
+
+# Org Credential Lease
+
+You almost never call this yourself. The org keeps each third-party provider key
+(DeepSeek, Moonshot, OpenAI, …) in **one** place — the Cohort credential vault — and
+the LLM router **leases** the key it needs at spawn time, role-scoped and short-lived,
+maps it into the child process env, and forgets it. The org key never lands on your
+disk. This skill is mostly for understanding and diagnosing that flow.
+
+## The pattern (single source of truth)
+
+- An admin sets each provider key **once** on Cohort (`cohort credential put
+  --provider <p>`), sealed at rest with AES-256-GCM, never logged.
+- At spawn, `lib/model-router/org-credentials.mjs#resolveOrgCredentialEnv` walks the
+  router catalog. For every provider whose `auth_env` is **not already set locally**
+  and which the org has configured, it leases the plaintext (`credential.lease`),
+  caches it in-memory for its TTL, and returns an `envOverlay` the daemon merges into
+  the child env **before** routing.
+- **Local always wins.** If you already have that key in your own env, the org is
+  never asked — your key is used.
+- **Fail-open.** If Cohort is unreachable or disabled, you fall back to whatever
+  local env has. A genuinely missing key surfaces as the router's normal
+  `missing_credential`, not a crash.
+- **Never persisted, never logged.** The leased value lives only in this process's
+  memory and the child env; it is never written to disk.
+
+## When to use
+
+- A spawn failed with `missing_credential` for a provider you expected to be available.
+- You want to confirm whether a provider key comes from your machine or the org.
+- Someone asks where a model's API key lives (answer: in the org vault, leased per-spawn).
+
+## Diagnosing a missing key
+
+1. **Is the org enabled?** Check `org.cohort.enabled` in `config/collective.yaml` and
+   that `base`/token resolve. If the org is off, only locally-provisioned keys exist.
+
+2. **Are you paired?** Leasing needs your agent token (carrying the `credential.use`
+   scope). `maestro doctor` confirms the org binding; if pairing was revoked, an admin
+   re-pairs you (`cohort pair approve <agentId>`).
+
+3. **Has the admin set that provider?** Only an admin can `credential put` / `list`.
+   If the provider was never set (or was revoked), no agent can lease it — surface this
+   to the admin rather than trying to put it yourself (you are scope-rejected with
+   `FORBIDDEN_SCOPE`, by design).
+
+4. **Local override.** If you need to run before the org has the key, setting the
+   provider's `auth_env` in your own env makes local win and bypasses the lease.
+
+## What you cannot do
+
+`credential put` / `list` / `revoke` are **admin-only** — an ordinary agent token is
+rejected with `FORBIDDEN_SCOPE`. You can only `credential.lease`, and only for
+providers the org has scoped to your role/agent. This is the security boundary, not a
+bug: it is what keeps provider keys off every mini.
+
+## Notes
+
+- Rotating a key is an admin action (`cohort credential put` again); you pick up the
+  new value automatically on your next lease — there is nothing to refresh by hand.
+- Every put / lease / revoke is audited org-side (provider + agent + time, never the
+  value).
+- This is the *org* credential broker (third-party provider keys). Your own secrets
+  use the local broker — see `maestro secrets …`.