@cohortapp/agent-sdk 2.3.0

package/mcp/README.md

@@ -0,0 +1,80 @@
+# MCP Server Configuration
+
+This directory contains Model Context Protocol (MCP) server configurations for the Maestro agent system. MCP servers provide structured tool access for agents.
+
+## Cohort org server (`cohort-mcp`)
+
+The SDK ships its own MCP server: the **curated Cohort org tool surface** (directory, messaging, board/tasks, decisions, approvals, knowledge, artifacts, email once the workspace-email family is live, and the agent desks — the mail app / files drive / calendar / crm / books plus `meetings_recap_file` — once their families are vendored; the `org_rpc` / `org_read` escape hatches cover the long tail). It is a hand-rolled stdio JSON-RPC server (`lib/mcp/server.mjs`, bin `bin/cohort-mcp.mjs`) — no MCP SDK dependency, stdout carries protocol frames only.
+
+**Add to Claude Code:**
+
+```bash
+claude mcp add cohort -- cohort-mcp
+```
+
+or drop into `.mcp.json` (freshly `create`d agent repos ship this via `scaffold/.mcp.json`):
+
+```json
+{ "mcpServers": { "cohort": { "command": "cohort-mcp" } } }
+```
+
+**Auth (env-first, config-fallback):**
+
+| Var | Meaning |
+| --- | --- |
+| `COHORT_API_TOKEN` | the org API key (aliases: `COHORT_TOKEN`, `COHORT_API_KEY`) |
+| `COHORT_ORG_ID` | org slug (sent as the `x-org-id` pin) |
+| `COHORT_BASE` | server origin (alias: `COHORT_API_URL`; default `https://os.cohortapp.com`) |
+| `COHORT_AGENT_ID` / `COHORT_AGENT_EMAIL` | optional member-identity hints for `org_whoami` |
+
+When env is absent the server falls back to `config/org.yaml` (`org.cohort.{base,orgId,token}`) under `COHORT_AGENT_ROOT`/`AGENT_ROOT`/cwd — an enrolled agent repo needs zero extra configuration. A missing token does not kill the server: `org_describe` works offline and every network tool returns a clear `UNAUTHORIZED` frame.
+
+**Governance:** `messaging_send` / `email_send` / `email_draft_send` (and `org_rpc` invocations of `messaging.send`/`email.send`/`email.draftSend`) run the shared outbound send-gate before dispatch, and every `tools/call` writes an audit row to `logs/audit/<date>-actions.jsonl` (`session_id: "mcp:<pid>"`). Desk verbs that trigger server-TEMPLATED sends (`books_invoice_send`, statement runs, calendar invite emails) are not outbound-flagged — their params carry no free text; hq's server-side governance (holds, guardian approvals, chase ladders) owns those sends and a tripped hold comes back as the `{status:"held", …}` / approval-required frame, never a silent send. In agent repos the `.claude/settings.json` PreToolUse matchers (`mcp__cohort__messaging_send`, `mcp__cohort__email_send`, `mcp__cohort__email_draft_send`, `mcp__cohort__org_rpc` → `scripts/hooks/block-mcp-cohort-send.sh`) block session-initiated outbound writes outright — sends go through the sanctioned CLI lane (`scripts/slack-send.sh`, `scripts/org/send-orgmail.mjs`), which carries the full dedup/reply-storm perimeter. **If you hand-add `.mcp.json` to a pre-2.0 repo, add those four matchers too** — `cohort upgrade` does not rewrite `.claude/settings.json` or `.mcp.json`.
+
+## Active MCP Servers
+
+### Filesystem Access
+
+- **Purpose**: Read/write access to the agent repo and source repositories
+- **Scope**: ~/agent-ai and your organisation's source repositories
+
+### Web Fetch
+
+- **Purpose**: HTTP requests for market data, news, API access
+- **Scope**: Approved domains only
+
+### GitHub
+
+- **Purpose**: Repository management, PR monitoring, issue tracking
+- **Scope**: Your organisation's repositories
+
+### Sequential Thinking
+
+- **Purpose**: Extended reasoning for complex strategic analysis
+- **Scope**: Available to strategic-planning and corporate-development agents
+
+### Memory
+
+- **Purpose**: Persistent memory across sessions
+- **Scope**: CEO Brain knowledge base
+
+## Planned MCP Servers
+
+### Google Calendar (via API)
+
+- **Purpose**: Calendar read/write for scheduling workflows
+- **Status**: Planned — requires OAuth setup
+
+### Slack API (supplementary)
+
+- **Purpose**: Programmatic Slack access in addition to desktop control
+- **Status**: Planned — requires workspace app installation
+
+### Linear / Project Management
+
+- **Purpose**: Task and project tracking integration
+- **Status**: Planned
+
+## Configuration
+
+MCP server configurations are defined in the Claude Code settings and `.mcp.json` files. See `config/mcp-servers.json` for the active configuration.

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@cohortapp/agent-sdk",
+  "version": "2.3.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": {
+    "maestro": "./bin/maestro.mjs",
+    "cohort": "./bin/maestro.mjs",
+    "cohort-mcp": "./bin/cohort-mcp.mjs",
+    "neolith": "./bin/maestro.mjs",
+    "neolith-mcp": "./bin/cohort-mcp.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./tools": "./lib/tool-definitions.js",
+    "./executor": "./lib/action-executor.js",
+    "./singleton": "./lib/singleton.js",
+    "./cadence-bus": "./lib/cadence-bus.mjs",
+    "./fs-atomic": "./lib/fs-atomic.mjs",
+    "./org/protocol": "./lib/org/protocol.mjs",
+    "./org/client": "./lib/org/client.mjs",
+    "./org/ui-parity": "./lib/org/ui-parity.mjs",
+    "./org/tool-surface": "./lib/org/tool-surface.mjs",
+    "./org/doctor": "./lib/org/doctor.mjs",
+    "./mcp/server": "./lib/mcp/server.mjs",
+    "./org/registry": "./lib/org/registry.mjs",
+    "./org/board": "./lib/org/board.mjs",
+    "./org/leases": "./lib/org/leases.mjs",
+    "./org/handoff": "./lib/org/handoff.mjs",
+    "./org/knowledge": "./lib/org/knowledge.mjs",
+    "./org/keys": "./lib/org/keys.mjs",
+    "./org/verify": "./lib/org/verify.mjs",
+    "./org/policy": "./lib/org/policy.mjs",
+    "./org/cost-sync": "./lib/org/cost-sync.mjs",
+    "./org/approvals": "./lib/org/approvals.mjs",
+    "./org/mesh": "./lib/org/mesh.mjs",
+    "./org/cohort-client": "./lib/org/cohort-client.mjs",
+    "./secrets/broker": "./lib/secrets/broker.mjs",
+    "./secrets/providers": "./lib/secrets/providers.mjs",
+    "./diagnostics/trace": "./lib/diagnostics/trace.mjs",
+    "./diagnostics/events": "./lib/diagnostics/events.mjs",
+    "./diagnostics/counters": "./lib/diagnostics/counters.mjs",
+    "./diagnostics/alerts": "./lib/diagnostics/alerts.mjs",
+    "./diagnostics/backup-freshness": "./lib/diagnostics/backup-freshness.mjs",
+    "./diagnostics/otel": "./lib/diagnostics/otel.mjs",
+    "./hooks/bus": "./lib/hooks/bus.mjs",
+    "./scheduling/dynamic-jobs": "./lib/scheduling/dynamic-jobs.mjs",
+    "./scheduling/jitter": "./lib/scheduling/jitter.mjs",
+    "./comms/send-gate": "./lib/comms/send-gate.mjs",
+    "./util/fetch-timeout": "./lib/util/fetch-timeout.mjs",
+    "./util/reconnect": "./lib/util/reconnect.mjs",
+    "./util/unhandled": "./lib/util/unhandled.mjs",
+    "./model-router/spawn": "./lib/model-router/spawn.mjs",
+    "./model-router/llm-task": "./lib/model-router/llm-task.mjs",
+    "./model-router/repair": "./lib/model-router/repair.mjs",
+    "./model-router/health": "./lib/model-router/health.mjs",
+    "./model-router/taxonomy": "./lib/model-router/taxonomy.mjs",
+    "./model-router/failover": "./lib/model-router/failover.mjs",
+    "./model-router/resolve": "./lib/model-router/resolve.mjs",
+    "./feature-init": "./lib/feature-init.mjs",
+    "./tts": "./lib/voice/tts.mjs",
+    "./model-router": "./lib/model-router.mjs",
+    "./model-router/catalog": "./lib/model-router/catalog.mjs",
+    "./model-router/ledger": "./lib/model-router/ledger.mjs",
+    "./model-router/economics": "./lib/model-router/economics.mjs",
+    "./model-router/reconcile": "./lib/model-router/reconcile.mjs",
+    "./model-router/org-credentials": "./lib/model-router/org-credentials.mjs",
+    "./voice": "./lib/voice/index.mjs",
+    "./voice/outbound": "./lib/voice/outbound.mjs",
+    "./voice/tts": "./lib/voice/tts.mjs",
+    "./rag": "./lib/rag/search.mjs",
+    "./rag/indexer": "./lib/rag/indexer.mjs",
+    "./rag/embed": "./lib/rag/embed.mjs",
+    "./channels": "./lib/channels/index.mjs",
+    "./voice/stt": "./lib/voice/stt.mjs",
+    "./security/external-content": "./lib/security/external-content.mjs",
+    "./security/redact": "./lib/security/redact.mjs",
+    "./security/secret-equal": "./lib/security/secret-equal.mjs",
+    "./security/dangerous-tools": "./lib/security/dangerous-tools.mjs",
+    "./security/coerce-args": "./lib/security/coerce-args.mjs",
+    "./archetype": "./lib/archetype.mjs",
+    "./framework-features.json": "./framework-features.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "archetypes/",
+    "scaffold/",
+    "scripts/",
+    "agents/",
+    "workflows/",
+    "policies/",
+    "teams/",
+    "docs/architecture/",
+    "docs/guides/",
+    "docs/prompts/",
+    "docs/research/",
+    "docs/runbooks/",
+    "docs/company-context/",
+    "public/assets/",
+    "plugins/maestro-skills/",
+    "schedules/",
+    "desktop-control/",
+    "ingest/",
+    "mcp/",
+    ".claude/commands/",
+    ".claude/settings.json",
+    ".env.example",
+    "README.md",
+    "framework-features.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node scripts/ci/run-tests.mjs",
+    "test:coverage": "node scripts/ci/run-coverage.mjs",
+    "test:list": "node --test bin/maestro.test.mjs lib/action-executor.test.mjs lib/archetype.test.mjs lib/autonomy.test.mjs lib/backlog.test.mjs lib/budget-guard.test.mjs lib/cadence-bus-schedule.test.mjs lib/cadence-bus.test.mjs lib/cadences.test.mjs lib/capability.test.mjs lib/channels/base-adapter.test.mjs lib/channels/channels.test.mjs lib/channels/contract.test.mjs lib/channels/inbox-item.test.mjs lib/channels/pairing.test.mjs lib/channels/slack-adapter.test.mjs lib/channels/telegram-adapter.test.mjs lib/channels/whatsapp/baileys-typing.test.mjs lib/charter.test.mjs lib/claude-bin.test.mjs lib/collective/capture.test.mjs lib/collective/cards.test.mjs lib/collective/config.test.mjs lib/collective/global-config.test.mjs lib/collective/presence.test.mjs lib/collective/recall.test.mjs lib/comms.test.mjs lib/fs-atomic.test.mjs lib/fs-ownership.test.mjs lib/learning/config.test.mjs lib/learning/counters.test.mjs lib/learning/curator-consolidate.test.mjs lib/learning/curator.test.mjs lib/learning/reflect.test.mjs lib/learning/session-index.test.mjs lib/learning/skill-writer.test.mjs lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs lib/org/approvals.test.mjs lib/org/board.test.mjs lib/org/client.test.mjs lib/org/cost-sync.test.mjs lib/org/handoff.test.mjs lib/org/keys.test.mjs lib/org/knowledge.test.mjs lib/org/activity.test.mjs lib/org/leases.test.mjs lib/org/mesh.test.mjs lib/org/messaging.test.mjs lib/org/cohort-client.test.mjs lib/org/policy.test.mjs lib/org/registry.test.mjs lib/org/tool-surface.test.mjs lib/org/ui-parity.test.mjs lib/org/doctor.test.mjs lib/org/verify.test.mjs lib/mcp/server.test.mjs lib/channels/orgmail/adapter.test.mjs lib/rag/rag.test.mjs lib/rate-guard.test.mjs lib/render.test.mjs lib/resource-governor.test.mjs lib/security/coerce-args.test.mjs lib/security/dangerous-tools.test.mjs lib/security/external-content.test.mjs lib/security/redact.test.mjs lib/security/secret-equal.test.mjs lib/session-permissions.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/enroll-from-cohort.test.mjs lib/setup/integration.test.mjs lib/setup/io.test.mjs lib/setup/runner.test.mjs lib/setup/sections/identity.test.mjs lib/setup/sections/learning.test.mjs lib/setup/sections/messaging.test.mjs lib/setup/sections/org.test.mjs lib/setup/sections/orgmail.test.mjs lib/setup/sections/recovery.test.mjs lib/setup/sot.test.mjs lib/setup/state.test.mjs lib/singleton.test.mjs lib/telemetry/alerts.test.mjs lib/telemetry/collect.test.mjs lib/tool-definitions.test.mjs lib/voice/outbound.test.mjs lib/voice/stt.test.mjs lib/voice/voice.test.mjs scripts/cadence/enqueue-cadence-tick.test.mjs scripts/ci/check-no-build-artifacts.test.mjs scripts/ci/check-no-residual-identity.test.mjs scripts/ci/check.test.mjs scripts/collective/hook-runner.test.mjs scripts/cost/fleet-digest.test.mjs scripts/daemon/cadence-consumer-governance.test.mjs scripts/daemon/cadence-consumer.test.mjs scripts/daemon/cadence-handlers.test.mjs scripts/daemon/classify-kind.test.mjs scripts/daemon/dispatcher-cooldown.test.mjs scripts/daemon/dispatcher-governance.test.mjs scripts/daemon/inbox-deferral.test.mjs scripts/daemon/lib/session-router.test.mjs scripts/daemon/prompt-builder.test.mjs scripts/daemon/typing-registry.test.mjs scripts/hooks/pre-send-audit.test.mjs scripts/local-triggers/generate-plists.test.mjs scripts/poller/inbox-scan-poller.test.mjs scripts/poller/lib/cloud-relay-dedup.test.mjs scripts/poller/slack-socket-mode.test.mjs scripts/setup/init-agent.test.mjs services/webhook-relay/server.test.mjs",
+    "test:setup": "node --test lib/setup/io.test.mjs lib/setup/state.test.mjs lib/setup/sot.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/runner.test.mjs lib/setup/integration.test.mjs",
+    "check": "node scripts/ci/check.mjs",
+    "test:router": "node --test lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs scripts/cost/fleet-digest.test.mjs",
+    "test:voice": "node --test lib/voice/voice.test.mjs lib/voice/outbound.test.mjs",
+    "test:channels": "node --test lib/channels/channels.test.mjs",
+    "test:cadence": "node --test lib/cadence-bus.test.mjs scripts/cadence/enqueue-cadence-tick.test.mjs scripts/daemon/cadence-consumer.test.mjs",
+    "test:cli": "node --test bin/maestro.test.mjs",
+    "test:relay": "node --test services/webhook-relay/server.test.mjs",
+    "test:cohort": "node --test $(find services/cohort -name '*.test.mjs' -not -path '*/node_modules/*')",
+    "test:org": "node --test $(find lib/org -name '*.test.mjs')",
+    "test:pack": "node scripts/ci/check-tarball-fidelity.mjs",
+    "test:plists": "node --test scripts/local-triggers/generate-plists.test.mjs",
+    "prepublishOnly": "echo 'Publishing @cohortapp/agent-sdk...'"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adapticai/maestro.git"
+  },
+  "author": "Adaptic.ai <dev@adaptic.ai>",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "js-yaml": "^4.1.1"
+  }
+}

package/plugins/maestro-skills/plugin.json

@@ -0,0 +1,139 @@
+{
+  "name": "maestro-skills",
+  "version": "1.3.0",
+  "description": "Maestro operational skills — executive briefings, communications, hiring, strategy, and domain-specific workflows for autonomous AI agents",
+  "skills": [
+    {
+      "name": "morning-brief",
+      "description": "Produce the Morning Brief — priorities, overnight developments, open loops, workstream pulse. Universal across all agent archetypes."
+    },
+    {
+      "name": "evening-wrap",
+      "description": "Produce the Evening Wrap — what closed today, what didn't, tomorrow's priorities. Universal across all agent archetypes."
+    },
+    {
+      "name": "inbox-triage",
+      "description": "Triage all inbound communications across Slack, Gmail, and WhatsApp. Classify by urgency, draft responses, flag items for principal attention."
+    },
+    {
+      "name": "hiring-triage",
+      "description": "Review new job applications, AI screen candidates, draft advancement/rejection messages, produce hiring pipeline status."
+    },
+    {
+      "name": "slack-followup",
+      "description": "Check all pending Slack follow-ups — messages awaiting reply, commitments overdue, threads needing continuation."
+    },
+    {
+      "name": "weekly-memo",
+      "description": "Produce the Weekly Strategic Memo — synthesis of the week, workstream status, strategic implications, recommendations."
+    },
+    {
+      "name": "draft-comms",
+      "description": "Draft a communication in the appropriate voice (agent, principal draft, institutional). Applies communication governance rules."
+    },
+    {
+      "name": "decision-brief",
+      "description": "Present a decision to the principal with options, pros/cons, and a recommendation using structured decision framework."
+    },
+    {
+      "name": "pipeline-review",
+      "description": "Review the active pipeline — target status, progress, new items, regulatory/filing status."
+    },
+    {
+      "name": "board-deck",
+      "description": "Prepare board deck materials using Gamma for presentations and Mermaid for diagrams. Assembles content from all domain agents."
+    },
+    {
+      "name": "regulatory-status",
+      "description": "Check regulatory status across all relevant jurisdictions — gap progress, incorporation status, licensing timelines."
+    },
+    {
+      "name": "schedule-meeting",
+      "description": "Schedule a meeting using Google Calendar MCP or Calendly. Handle timezone conversion, find availability, send invites."
+    },
+    {
+      "name": "claude-pace",
+      "description": "Check Claude API rate limit quota — 5-hour/7-day usage, reset countdowns, pace delta. Use before heavy backlog cycles or when quota warnings appear."
+    },
+    {
+      "name": "ccxray-diagnostics",
+      "description": "Run token/cost X-ray diagnostics on Claude API sessions — per-turn breakdown, context window heatmaps, system prompt diffs. Use for debugging expensive sessions."
+    },
+    {
+      "name": "code-review-graph",
+      "description": "Structural code analysis via tree-sitter knowledge graph — blast radius, review context, architecture overview, semantic search. Use for PR reviews and refactoring."
+    },
+    {
+      "name": "agents-observe",
+      "description": "Multi-agent observability dashboard — monitor parallel agent teams, tool calls, session state, and performance in real time. Use when debugging agent failures."
+    },
+    {
+      "name": "session-search",
+      "description": "Recall your own past Claude Code sessions verbatim — full-text search across every prior session transcript (discovery / scroll / read / browse). Use when you need the exact wording or full context of something you did before."
+    },
+    {
+      "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 to take org-prioritised work, close a claimed item, or hand a task to another agent."
+    },
+    {
+      "name": "org-credential",
+      "description": "Understand how you get third-party provider keys from the org — leased automatically at spawn, never stored on your machine. Use when a provider key looks missing or a model fails with a credential error."
+    },
+    {
+      "name": "set-reminder",
+      "description": "Create a dynamic scheduled job in natural language — 'remind me Friday 9am', 'every weekday 8am summarize the channel'. Use to set a one-off reminder or recurring task, list scheduled jobs, or cancel one."
+    },
+    {
+      "name": "router-why",
+      "description": "Explain a model-routing decision — which model on which harness the router would pick for a task, and why. Use when a spawn used an unexpected model or to validate a routing-config change."
+    },
+    {
+      "name": "org-recall",
+      "description": "Consult the shared org knowledge plane — facts, contacts, and meetings other agents recorded, ACL-scoped to what you may see. Use to pull org-wide context before answering, or to record a fact for the fleet."
+    },
+    {
+      "name": "team-activity",
+      "description": "See what the team is doing right now — every peer agent's live state, current activity, machine health, and alerts from the org directory. Use to answer 'what is the team doing now' or 'what is <person> doing', find a free agent, or spot a peer that is down or needs re-login."
+    },
+    {
+      "name": "generative-ui",
+      "description": "Return interactive artifact cards in org conversations instead of plain text — catalog discovery, composing genui/v2 envelopes from the block vocabulary, streaming hydration, and acting on cards. Use when a reply benefits from structured, actionable UI (approvals, review grids, comparisons, forms), or to invoke an action on a posted card."
+    },
+    {
+      "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 to surface one of these domain cards in conversation, or to read/act on one programmatically."
+    },
+    {
+      "name": "mail-triage",
+      "description": "Work an org mailbox like the human Inbox app — entitled mailboxes, thread triage (priority/category/assignment/read), filing and moves, drafts, and the governed send path where holds land in a guardian's approvals queue. Use to clear an inbox, chase a thread, or reply from a workspace mailbox."
+    },
+    {
+      "name": "files-find",
+      "description": "Find, read, and write documents in the org's workspace drive — Docs, Sheets, Decks, folders, uploads — under the same VIEW/COMMENT/EDIT shares that govern humans. Use to locate a file, pull a doc into context, draft or revise a workspace document, or share one."
+    },
+    {
+      "name": "calendar-plan",
+      "description": "Plan workspace calendar events — deterministic free-slot scans across attendees, typed events with real invites, RSVP commitments, reschedules with everyone notified, and meeting recap filing. Use to find a time, set up or move a meeting, or answer an invite."
+    },
+    {
+      "name": "crm-pipeline",
+      "description": "Work the CRM desk — pipeline reads, stage moves, attributed interaction logging, next-best-action inside playbook lines, and the escalation lane where humans sign held work. Use for pipeline questions, progressing or handing over a deal, or running a deal's next step."
+    },
+    {
+      "name": "books-close",
+      "description": "Run the Books desk — ledger-grounded reports, AR/AP work, bank matching, payroll and tax preparation — under the signature law: money movement and lodgement never happen without a human signature. Use for finance questions, invoice/bill work, or preparing a period close."
+    },
+    {
+      "name": "directory-hygiene",
+      "description": "Work the org Directory — search external people and organisations, read a record with its provenance, enrich channels from real traffic, and propose captures and duplicate merges into the human review queue. Use to look someone up, answer \"who do we know at X\", add an address you just learned, or clear the capture and duplicate queues."
+    },
+    {
+      "name": "brand-steward",
+      "description": "Work the org's Design section — read the brand foundation and voice, rewrite copy in that voice, render and export templates and the brand kit, regenerate stale imagery within a budget, and propose reviewable foundation changes. Use before writing anything the workspace publishes, to produce a branded asset, or when imagery/templates have gone stale."
+    },
+    {
+      "name": "call-working-sessions",
+      "description": "Turn a Cohort call into a working session — present a doc/sheet/channel/board/charter on the call stage, step through it (scroll/highlight/type), live-edit docs while talking, read what participants see on screen, and watch reactions and raised hands. Use when you are a participant in a live Cohort call and want to show rather than tell, walk people through a document, or ground \"this chart / that number\" talk in what is actually on screen."
+    }
+  ]
+}

package/plugins/maestro-skills/skills/agents-observe.md

@@ -0,0 +1,110 @@
+---
+name: agents-observe
+description: Multi-agent observability dashboard — monitor parallel agent teams, tool calls, session state, and performance in real time. Use when debugging agent failures or profiling backlog execution.
+---
+
+# Multi-Agent Observability (agents-observe)
+
+You are a Maestro agent. Use agents-observe to monitor, debug, and profile Claude Code agent teams in real time.
+
+## When to Invoke
+
+- **Monitoring parallel execution** — watching multiple backlog executor agents running simultaneously
+- **Debugging agent failures** — an agent crashed, hung, or produced unexpected results
+- **Performance profiling** — identifying which agents or tool calls are slow
+- **Post-mortem analysis** — reviewing what happened in a completed session
+- **Orchestrator oversight** — the orchestrator agent needs visibility into sub-agent activity
+
+## Background
+
+agents-observe captures tool calls, agent hierarchy, and session state via background hooks. Data is stored in SQLite and streamed to a WebSocket-powered dashboard with 3-5ms latency. It is NOT always-on due to SQLite write overhead — enable on demand for specific debugging sessions.
+
+## Steps
+
+### Starting Observation
+
+1. **Launch the dashboard**:
+   ```bash
+   agents-observe serve
+   ```
+   Opens the dashboard at `http://localhost:3847`. Active Claude Code sessions appear automatically.
+
+2. **Monitor live sessions** — the dashboard shows:
+   - Agent hierarchy (parent orchestrator and child sub-agents)
+   - Real-time tool call stream with timing
+   - Session state (active, idle, completed, errored)
+   - Per-agent resource usage
+
+### Querying Historical Data
+
+3. **Query by session** — inspect a specific session's full history:
+   ```bash
+   agents-observe query --session <session-id>
+   ```
+
+4. **Query by tool** — find all uses of a specific tool in a time window:
+   ```bash
+   agents-observe query --tool Write --last 1h
+   ```
+
+5. **Query by agent** — filter to a specific agent's activity:
+   ```bash
+   agents-observe query --agent backlog-executor --last 2h
+   ```
+
+### Analysis Workflows
+
+6. **Debugging a failed agent**:
+   - Find the session ID from workflow logs or the dashboard
+   - Query the session to see the full tool call sequence
+   - Identify the last successful tool call before failure
+   - Check for error patterns: timeout, rate limit, permission denied, context overflow
+
+7. **Performance profiling**:
+   - Compare tool call durations across agents
+   - Identify bottleneck tools (slow reads, large writes)
+   - Check for redundant tool calls (same file read multiple times)
+   - Measure time-to-first-action for each sub-agent
+
+8. **Parallel execution monitoring**:
+   - Verify all expected sub-agents launched successfully
+   - Watch for agents blocking on shared resources (file locks, API limits)
+   - Detect agents that completed quickly vs those that are stuck
+   - Identify ordering issues in agent dependencies
+
+## Output
+
+Report findings appropriate to the workflow:
+
+**For debugging:**
+```
+## Agent Failure Analysis: [session-id]
+- Agent: [name]
+- Failed at: [timestamp]
+- Last successful tool: [tool name] at [timestamp]
+- Error: [error message or pattern]
+- Root cause: [analysis]
+- Recommendation: [fix]
+```
+
+**For performance profiling:**
+```
+## Agent Performance Profile
+| Agent | Duration | Tool Calls | Slowest Tool | Outcome |
+|---|---|---|---|---|
+| [name] | [Xs] | [N] | [tool, Xms] | [success/fail] |
+
+### Bottlenecks
+- [Specific finding, e.g., "Agent X read config.yaml 7 times — cache recommended"]
+
+### Recommendations
+- [Actionable optimization]
+```
+
+## Integration Notes
+
+- Do NOT leave agents-observe running permanently — SQLite writes add overhead to every tool call
+- Enable for specific debugging sessions, then shut down
+- Dashboard port is 3847 — ensure no conflicts with other local services
+- Pairs well with ccxray for combined tool-call and token-level analysis
+- Session data persists in SQLite after the dashboard is closed — queryable later

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

@@ -0,0 +1,68 @@
+---
+name: board-deck
+description: Prepare board deck materials using Gamma for presentations and Mermaid for diagrams. Assembles content from all domain agents for board meetings.
+---
+
+# Board Deck Preparation
+
+You are {{agent.fullName}}, {{agent.title}}. Assemble and prepare board deck materials.
+
+## Data Sources
+
+1. **Financial data** — Read `memory/workstreams/finance.md` and `inputs/finance/` for latest financial metrics, P&L, cash position.
+2. **Acquisition pipeline** — Read `memory/workstreams/acquisitions.md` for deal pipeline status and completed transactions.
+3. **Regulatory progress** — Read `memory/workstreams/regulatory.md` for licensing status across all jurisdictions.
+4. **Hiring/team** — Read `memory/workstreams/hiring.md` for headcount, open roles, recent hires.
+5. **Product/tech** — Read `memory/workstreams/product.md` for platform development, integration milestones.
+6. **Strategic priorities** — Read `memory/executive/priorities.md` and `config/strategy.md` for the strategic narrative.
+7. **Weekly memos** — Read recent files from `outputs/briefs/weekly/` for trend data and synthesis.
+8. **Prior board deck** — Check `outputs/board/` for the last deck to maintain continuity.
+
+## Deck Structure
+
+Prepare content for the following slides (standard board deck order):
+
+```
+1. TITLE & AGENDA
+2. EXECUTIVE SUMMARY — 3-5 bullets, quarter highlights, key ask (if any)
+3. FINANCIAL OVERVIEW — Revenue, burn, runway, key metrics vs plan
+4. ACQUISITION PIPELINE — Funnel visual, active targets, closed deals
+5. REGULATORY STATUS — Jurisdiction matrix, timeline to licensing
+6. TEAM & HIRING — Org chart changes, key hires, open roles
+7. PRODUCT & TECHNOLOGY — Platform milestones, integration status
+8. STRATEGIC OUTLOOK — Market positioning, next quarter priorities
+9. RISKS & MITIGATIONS — Top 3 risks with mitigation plans
+10. ASK / DISCUSSION ITEMS — Decisions needed from the board
+```
+
+## Diagram Generation
+
+Use Mermaid syntax for the following standard diagrams:
+
+- **Acquisition funnel** — Stages with target counts
+- **Regulatory timeline** — Gantt chart across jurisdictions
+- **Org chart** — Current team structure
+- **Financial trend** — Key metric trajectories
+
+Save Mermaid diagrams to `outputs/board/diagrams/`.
+
+## Presentation Assembly
+
+1. Write each slide's content as a structured markdown section in `outputs/board/board-deck-YYYY-MM-DD.md`.
+2. Include speaker notes for {{agent.principal.firstName}} under each slide.
+3. If Gamma MCP or API is available, generate the presentation directly. Otherwise, prepare content ready for manual Gamma import.
+4. Flag any data gaps — sections where the data is stale or missing.
+
+## Output
+
+1. Full deck content to `outputs/board/board-deck-YYYY-MM-DD.md`.
+2. Mermaid diagrams to `outputs/board/diagrams/`.
+3. Speaker notes included inline.
+4. Present a summary of the deck with any data gaps or decisions needed before the board meeting.
+
+## Quality Checks
+
+- Every metric must have a source reference and a date stamp.
+- Compare current period to prior period and plan/budget.
+- No surprises — anything in the deck should have been in a weekly memo already.
+- Board tone: confident but transparent. Acknowledge challenges directly.

package/plugins/maestro-skills/skills/books-close.md

@@ -0,0 +1,77 @@
+---
+name: books-close
+description: Run the org's Books desk — ledger-grounded reports, AR/AP work (draft, send, chase, capture, approve), bank-feed matching, payroll and tax preparation — under the signature law: money movement and lodgement NEVER happen without a verified human signature. Use for finance questions, invoice/bill work, close-the-period tasks, or preparing obligations for a human to sign.
+---
+
+# Books — the Finance Desk
+
+Books is double-entry and ledger-current: every report figure carries its
+`journalLineIds`, journals are append-only, and the SIGNATURE LAW is enforced in
+the domain layer — `books.write` scope alone cannot move money. The money verbs
+(`payrollSign`, `billScheduleRun`, `taxSignLodge`, floor/new-payee bill releases)
+require a verified HUMAN signature token; an agent call without one returns
+`SIGNATURE_REQUIRED` or an approval-required frame. That is the product working,
+not an obstacle: PREPARE everything, then put it in front of the human. External
+rails (bank feeds, SBR/ELSTER lodgement, STP) run SANDBOX providers, honestly
+labelled — never claim a real filing happened.
+
+All of it is `executeOrgTool` over the books-desk tools; fail-open frames; money
+is integer cents.
+
+## Grounded reads
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+console.log(JSON.stringify(await executeOrgTool("books_reports", { report: "pl" }), null, 2));
+'
+```
+
+- `books_reports` — ledger-current reporting; every figure carries journalLineIds.
+- `books_invoices` — AR with chase state; `books_bills` — AP with hold reasons +
+  run linkage; `books_tax_obligations` — the lodgement calendar.
+- `books_ask` — grounded ask-the-books via the shared AI gateway (the gateway
+  self-audits its model call; the answer carries grounding + cost).
+- Long-tail reads via `org_rpc`: `books.accounts`, `books.journals`,
+  `books.feedLines` (bank lines + match state), `books.assets`.
+
+## AR — invoice to cash
+
+`books_invoice_draft` → `books_invoice_send` → payments via `org_rpc`
+`books.invoiceRecordPayment`. The chase ladder holds steps for release
+(`books.invoiceChaseStep`); `books.invoicePromise` records a promise-to-pay and
+pauses the ladder; `books.invoiceCreditNote`, `books.invoiceVoid` (reversing
+journal; undo reinstates), `books.statementRun` (honest skip when no open items).
+
+## AP — capture to run
+
+Capture with `org_rpc` `books.billCapture`; release holds with
+`books_bill_approve` (floor/new-payee releases still need the human signature);
+`books.billHold` / `books.billReturn` manage the run;
+**`books.billScheduleRun` = sign & execute — human signature required.**
+
+## Bank, payroll, tax, assets (escape hatch)
+
+- Bank: `books.matchAccept` (already-matched CONFLICTs — that is the idempotency
+  working), `books.matchHoldResolve`, `books.lineRecode`, `books.receiptsRegister`.
+- Payroll: `books.payrollDraft` (idempotent per period) → **`books.payrollSign`
+  (human signature)** → `books.payrollRecall` before cutoff; `books.stpResubmit`
+  only on errored runs.
+- Tax: `books.taxPrepare` assembles workings from the ledger and HOLDS for
+  signature; `books.taxHold` queues; `books.taxReturn` sends held work back for
+  re-work; **`books.taxSignLodge` lodges — never without a human signature
+  (SANDBOX_SBR/ELSTER rails, labelled as such).**
+- Assets: `books.assetDepreciationRun` (idempotent per period),
+  `books.assetDispose`.
+- People: `books.expenseClaim` / `books.expenseApprove`, `books.leaveRequest` /
+  `books.leaveApprove`; onboarding `books.onboardingStart` / `books.onboardingAdvance`.
+- `books.journalPost` — manual journals, append-only.
+
+## Rules of the desk
+
+- Never report a lodgement, payment run, or pay run as done unless the result
+  says a HUMAN signed it. `SIGNATURE_REQUIRED` / approval-required frames are the
+  law working — surface them and hand the human the exact item to sign.
+- Quote figures with their grounding (report + journalLineIds), amounts in cents.
+- Prefer the idempotent verbs' replay behaviour over re-checking state yourself;
+  a CONFLICT on `matchAccept` means someone already matched the line.