@adaptic/maestro 1.0.0

package/README.md

@@ -0,0 +1,491 @@
+# Maestro
+
+**A production-grade framework for deploying autonomous AI agents on dedicated Mac minis.**
+
+Maestro turns a Mac mini into a perpetually running AI employee. Each agent uses Claude Code as its reasoning engine, integrates with Slack, Gmail, Google Calendar, WhatsApp, SMS, and 25+ MCP-connected services, and operates autonomously around the clock -- observing events, executing tasks, communicating with humans, and maintaining institutional memory across sessions.
+
+---
+
+## What is Maestro?
+
+Maestro is an autonomous AI agent operating system. It provides the complete infrastructure to deploy, run, and govern an AI agent that functions as a real member of your team -- with its own identity, responsibilities, communication channels, and institutional memory.
+
+**What it does:**
+- Runs 24/7 on a dedicated Mac mini, polling Slack, Gmail, and Calendar for events
+- Reasons about incoming information and takes action autonomously
+- Sends messages, drafts documents, follows up on open loops, and coordinates work
+- Maintains persistent memory, decision logs, and strategic context across sessions
+- Spawns parallel sub-agents for complex, multi-track execution
+- Produces branded PDFs, executive briefs, and media assets
+
+**What it is NOT:**
+- Not a chatbot. The agent operates proactively, not just in response to prompts.
+- Not a demo or prototype. This is production infrastructure for real organisations.
+- Not a generic agent framework. It is opinionated about deployment (Mac mini), reasoning (Claude Code), and governance (audit trails, approval policies, rate limits).
+
+**Who it is for:**
+Companies deploying AI employees -- autonomous agents that hold real roles, communicate with real people, and execute real work across real tools. If you need a Chief of Staff, a Head of Compliance, a quant researcher, or any other knowledge worker that runs continuously without human prompting, Maestro is the deployment framework.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Your Agent                        │
+│              Executive Cortex (Tier 0)              │
+├──────────┬──────────┬──────────┬──────────┬─────────┤
+│ Briefing │ Strategic│ Domain   │ Comms    │ Task    │
+│          │ Planning │ Ops      │ Gov.     │ Exec.   │
+│ (Tier 1) │ (Tier 1) │ (Tier 1) │ (Tier 1) │(Tier 1)│
+├──────────┴──────────┴──────────┴──────────┴─────────┤
+│              20+ Specialist Agents (Tier 2)         │
+│  Research · Product · Engineering · Legal · Ops ·   │
+│  Finance · Partnerships · Hiring · Market Intel ·   │
+│  Board Prep · Compliance · Writing · ...            │
+├─────────────────────────────────────────────────────┤
+│              Desktop Operations (Tier 3)            │
+│  Slack · Gmail · WhatsApp · Browser · Calendar      │
+├─────────────────────────────────────────────────────┤
+│              Governance & Memory (Tier 4)           │
+│  Decision Log · Risk Register · Knowledge Base      │
+└─────────────────────────────────────────────────────┘
+```
+
+**Tier 0 -- Executive Cortex:** The agent's core identity and reasoning loop. Reads dashboards, processes inbound events, makes decisions, and orchestrates lower tiers.
+
+**Tier 1 -- Domain Controllers:** Specialised reasoning modules for briefing, strategic planning, domain operations, communications governance, and task execution.
+
+**Tier 2 -- Specialist Agents:** 20+ sub-agents that can be spawned in parallel for focused work -- research, document drafting, code review, legal analysis, hiring pipelines, and more.
+
+**Tier 3 -- Desktop Operations:** Integrations with external services via MCP servers, APIs, and local tooling. Slack, Gmail, Google Calendar, WhatsApp, SMS, browser automation.
+
+**Tier 4 -- Governance & Memory:** Persistent state layer. Decision logs, risk registers, knowledge bases, interaction history, queue management, and audit trails.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+| Dependency          | Install                                                    | Purpose                          |
+|---------------------|------------------------------------------------------------|----------------------------------|
+| Node.js 25+        | `brew install node`                                        | Runtime for poller, triggers     |
+| Claude CLI          | `npm install -g @anthropic-ai/claude-code`                 | Agent reasoning engine           |
+| jq                  | `brew install jq`                                          | Used by hook scripts             |
+| Pandoc + MacTeX     | `brew install pandoc && brew install --cask mactex-no-gui` | PDF generation (optional)        |
+| Anthropic API key   | Set `ANTHROPIC_API_KEY` env var                            | Required for Claude CLI          |
+
+### Step 1: Clone and Install
+
+```bash
+git clone git@github.com:your-org/maestro.git ~/your-agent
+cd ~/your-agent
+npm run init-agent
+```
+
+The `init-agent` script handles all machine setup:
+- Installs npm dependencies
+- Creates all required `state/`, `logs/`, `memory/` directories
+- Installs global Claude Code settings with hook configuration
+- Generates and loads 12 macOS launchd agents (poller, inbox processor, backlog executor, meeting prep, weekly triggers, etc.)
+- Creates a `.env` template for API keys
+- Runs a health check
+
+### Step 2: Configure Your Agent
+
+```bash
+claude "/init-maestro"
+```
+
+This launches an interactive Claude Code session that rewrites the repository for your agent's identity. You will be asked for:
+
+| Field                   | Example                                |
+|-------------------------|----------------------------------------|
+| Agent name              | "Jordan"                               |
+| Agent surname           | "Blake"                                |
+| Agent role/title        | "Chief of Staff"                       |
+| Directory name          | "jordan-ai"                            |
+| Mac mini hostname       | "jordan-mini"                          |
+| Key responsibilities    | 2-5 bullet points                      |
+| Reporting line          | "CEO" or specific person               |
+| Communication style     | Formal/casual, proactive/reactive      |
+
+The wizard updates `CLAUDE.md` (identity and principles), all script variables, launchd plist labels and paths, `package.json`, config files, trigger prompts, and agent definitions.
+
+See `docs/guides/agent-persona-setup.md` for the detailed persona configuration guide.
+
+### Step 3: Set Up Integrations
+
+Copy `.env.example` to `.env` and fill in your API keys and tokens:
+
+```bash
+cp .env.example .env
+```
+
+At minimum, configure Slack and Gmail credentials. See the Required Services table below for the full list.
+
+### Verifying the Setup
+
+```bash
+# Check all launchd agents are loaded
+launchctl list | grep adaptic
+
+# Run health check
+npm run healthcheck
+
+# Check poller is writing logs
+tail -f logs/polling/$(date +%Y-%m-%d)-poller.jsonl
+```
+
+---
+
+## Required Services and API Keys
+
+| Service            | Purpose                          | Required?   | Signup URL                                  | Tier / Pricing                          |
+|--------------------|----------------------------------|-------------|---------------------------------------------|-----------------------------------------|
+| Anthropic API      | Primary reasoning engine (Claude)| Required    | https://console.anthropic.com               | Pay-per-token or Max subscription       |
+| Slack              | Team communication               | Required    | https://api.slack.com/apps                  | Free (workspace needed)                 |
+| Gmail              | Email monitoring and sending     | Required    | https://myaccount.google.com/apppasswords   | Google Workspace or free Gmail          |
+| Google Calendar    | Meeting and schedule awareness   | Recommended | Via Google Workspace                        | Same account as Gmail                   |
+| Google Drive       | Document sharing                 | Recommended | Via Google Workspace                        | Same account as Gmail                   |
+| OpenAI             | Supplemental model access        | Optional    | https://platform.openai.com                | Pay-per-token                           |
+| Google Gemini      | Media generation (images, video) | Optional    | https://aistudio.google.com                | Free tier available                     |
+| Twilio             | SMS, voice, and WhatsApp         | Optional    | https://www.twilio.com                     | Pay-as-you-go (~$1/mo + usage)          |
+| Deepgram           | Speech-to-text transcription     | Optional    | https://deepgram.com                       | Free tier (200 hrs/yr)                  |
+| ElevenLabs         | Text-to-speech voice synthesis   | Optional    | https://elevenlabs.io                      | Free tier available                     |
+| Greptile           | Codebase search and indexing     | Optional    | https://greptile.com                       | Free tier available                     |
+
+Additional services are available via MCP servers and can be configured separately. Supported integrations include Airtable, Linear, Figma, Notion, Jira, Calendly, and more. See your Claude Code MCP configuration for the full list.
+
+### Environment Variables
+
+After running `npm run init-agent`, fill in the generated `.env` file:
+
+```bash
+# Core
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Communication channels
+SLACK_USER_TOKEN=xoxp-...
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_SIGNING_SECRET=...
+
+# Gmail
+GMAIL_CLIENT_ID=...
+GMAIL_CLIENT_SECRET=...
+GMAIL_REFRESH_TOKEN=...
+
+# Google Calendar
+GCAL_CLIENT_ID=...
+GCAL_CLIENT_SECRET=...
+GCAL_REFRESH_TOKEN=...
+
+# Twilio (SMS/Phone/WhatsApp)
+TWILIO_ACCOUNT_SID=...
+TWILIO_AUTH_TOKEN=...
+TWILIO_PHONE_NUMBER=...
+
+# Media generation
+GEMINI_API_KEY=...
+```
+
+---
+
+## Agent Configuration
+
+The central identity file is `config/agent.ts` (or the `CLAUDE.md` identity section, depending on your setup). This defines:
+
+- **Agent name, role, and title** -- who the agent is
+- **Operating principles** -- how the agent makes decisions
+- **Communication rules** -- voice modes, autonomy levels, escalation triggers
+- **Domain context** -- what the agent knows about the organisation
+- **Reporting line** -- who the agent escalates to
+
+Run `claude "/init-maestro"` for interactive setup, or see `docs/guides/agent-persona-setup.md` for manual configuration.
+
+---
+
+## Directory Structure
+
+```
+maestro/
+├── README.md                    # This file
+├── CLAUDE.md                    # Claude Code operating instructions (identity + behaviour)
+├── .claude/
+│   ├── settings.json            # Project-level Claude Code hooks and permissions
+│   └── commands/
+│       └── init-agent.md        # /init-maestro command for identity setup
+├── docs/
+│   ├── architecture/            # System and agent architecture
+│   ├── governance/              # Approval models, communications policy, safety
+│   ├── runbooks/                # Mac mini bootstrap, perpetual ops, recovery
+│   ├── workflows/               # Cadence documentation
+│   └── prompts/                 # Output templates (briefs, memos, decisions)
+├── agents/                      # 30+ agent definitions with mandates and prompts
+├── teams/                       # Agent team compositions and responsibilities
+├── workflows/
+│   ├── continuous/              # Always-on inbound monitoring loop
+│   ├── daily/                   # Morning brief, evening wrap, comms triage
+│   ├── weekly/                  # Strategic memo, pipeline review
+│   ├── monthly/                 # Board readiness, risk refresh
+│   └── quarterly/               # Scenario analysis, board pack
+├── schedules/
+│   └── triggers/                # Trigger prompts for launchd-scheduled sessions
+├── scripts/
+│   ├── setup/
+│   │   └── init-agent.sh        # One-line machine setup script
+│   ├── local-triggers/
+│   │   ├── run-trigger.sh       # Trigger runner (invoked by launchd)
+│   │   ├── install-all.sh       # Install launchd plists
+│   │   └── plists/              # macOS launchd plist templates
+│   ├── daemon/                  # Main agent daemon
+│   ├── poller/                  # Event polling (Slack, Gmail, Calendar)
+│   ├── hooks/                   # Claude Code hook scripts
+│   ├── pdf-generation/          # Branded PDF generation (Pandoc + XeLaTeX)
+│   └── media-generation/        # AI illustration/video generation
+├── knowledge/                   # Sources, syntheses, memory, entities, decisions
+├── config/                      # Environment, priorities, contacts, repos, brand
+├── policies/                    # Action classification, approval rules
+├── state/                       # Queues, inbox, dashboards, polling cursors
+├── outputs/                     # Briefs, memos, drafts, research
+├── memory/                      # Interaction history, profiles, precedents
+└── logs/                        # Operational logs (audit, polling, workflows)
+```
+
+---
+
+## Operating Modes
+
+Maestro agents operate in three concurrent modes at all times.
+
+### Mode 1: Reactive -- Respond to Events
+
+The nervous system. Always on, always listening.
+
+- A lightweight poller checks Slack, Gmail, and Calendar for new events every 60 seconds
+- An inbox processor classifies and routes incoming items every 5 minutes
+- Priority events (CEO DMs, urgent tags, direct mentions) trigger immediate processing sessions
+- All inbound events land in `state/inbox/` as structured YAML before being routed to the appropriate queue
+
+### Mode 2: Scheduled -- Run Cadence Workflows
+
+The heartbeat. Ensures nothing falls through the cracks.
+
+- **Daily:** Morning brief, midday sweep, evening wrap, communications triage
+- **Weekly:** Strategic memo, pipeline review, hiring review, engineering health check, execution review
+- **Monthly:** Board readiness, risk register refresh, financial integration
+- **Quarterly:** Self-assessment, scenario analysis, board pack generation
+
+All scheduled workflows are defined in `workflows/` and triggered via macOS launchd agents.
+
+### Mode 3: Proactive -- Execute the Backlog
+
+The engine. This is where the real work gets done.
+
+- The backlog executor runs every 10 minutes via launchd
+- It reads all operational queues, selects the top 3-5 actionable items by priority
+- It spawns parallel background agents to execute each item independently
+- Agents do the actual work: draft documents, chase people, research topics, build deliverables
+- Results are reviewed, queues are updated, and the next batch is picked up
+- Items continuously move from `open` to `in_progress` to `resolved` to `closed`
+
+The goal is continuous forward motion. Items should not sit in queues -- they should be getting done.
+
+---
+
+## Communication Governance
+
+All Maestro agents follow a structured governance framework for outbound communications.
+
+| Action Level                     | Policy                                              |
+|----------------------------------|-----------------------------------------------------|
+| Observe                          | Always permitted                                    |
+| Draft                            | Always permitted                                    |
+| Recommend                        | Always permitted                                    |
+| Send (internal, routine)         | Pre-approved categories with full logging            |
+| Send (external)                  | Requires explicit approval from the agent's manager  |
+| Send (investor/regulator/board)  | Requires approval + confirmation                     |
+
+Additional safeguards:
+
+- **Pre-send audit hook** gates all outbound Slack and Gmail communications
+- **Rate limits** prevent runaway sending (configurable per channel)
+- **Duplicate detection** prevents the agent from replying to the same thread multiple times
+- **Information barriers** prevent confidential information from leaking across recipient boundaries
+- **Prompt injection defence** (5-layer) protects the agent from adversarial inbound messages
+
+Communication governance policies are defined in `policies/action-classification.yaml`.
+
+---
+
+## Deploying Multiple Agents
+
+Maestro is designed to be forked for each AI agent in your organisation. Each agent runs on its own dedicated Mac mini with its own identity, domain focus, and operational context.
+
+### Example: Multi-Agent Deployment
+
+| Agent   | Role                        | Mac Mini      | Repo            |
+|---------|-----------------------------|---------------|-----------------|
+| Jordan  | Chief of Staff              | jordan-mini   | jordan-ai       |
+| Alex    | Chief AI Scientist          | alex-mini     | alex-ai         |
+| Morgan  | Head of Quant Engineering   | morgan-mini   | morgan-ai       |
+| Riley   | Head of Engineering         | riley-mini    | riley-ai        |
+| Sam     | Head of Compliance          | sam-mini      | sam-ai          |
+| Taylor  | Head of Product             | taylor-mini   | taylor-ai       |
+| Casey   | Head of Investor Relations  | casey-mini    | casey-ai        |
+| Robin   | Head of Fund Operations     | robin-mini    | robin-ai        |
+
+### Setup: New Agent in 3 Steps
+
+**Step 1: Fork, clone, rename**
+
+```bash
+git clone git@github.com:your-org/maestro.git ~/alex-ai
+cd ~/alex-ai
+```
+
+**Step 2: Run machine setup**
+
+```bash
+npm run init-agent
+```
+
+**Step 3: Configure the agent identity**
+
+```bash
+claude "/init-maestro"
+```
+
+The `/init-maestro` wizard handles the full identity transformation:
+
+| What changes                         | Example                                          |
+|--------------------------------------|--------------------------------------------------|
+| `CLAUDE.md` identity and principles  | "Alex Park, Chief AI Scientist..."               |
+| Variable names in scripts            | `AGENT_DIR` updated to new paths                 |
+| Launchd plist labels                 | `ai.adaptic.agent-*` labels updated              |
+| `package.json` name and description  | `"alex-ai"`, `"Autonomous AI scientist for..."` |
+| `config/` files                      | Priorities, contacts, environment paths           |
+| `schedules/triggers/`               | Trigger prompts reference the new identity        |
+| `agents/` definitions               | Domain-specific agents adapted for the role       |
+
+### What Stays the Same
+
+The following infrastructure is shared across all agents and does not need per-agent changes:
+
+- **Poller architecture** (`scripts/poller/`) -- Slack, Gmail, Calendar polling
+- **Trigger runner** (`scripts/local-triggers/run-trigger.sh`) -- launchd-to-Claude bridge
+- **Hook scripts** -- Pre/post tool hooks, session lifecycle
+- **Brand assets** (`public/assets/`) -- Organisation-wide branding
+- **PDF generation** (`scripts/pdf-generation/`) -- document templates
+- **Governance framework** (`policies/`, `docs/governance/`) -- same rules, different agent
+
+---
+
+## Commands Reference
+
+### Machine Setup
+
+| Command                         | Purpose                                            |
+|---------------------------------|----------------------------------------------------|
+| `npm run init-agent`            | Full machine setup (deps, dirs, launchd, env)      |
+| `claude "/init-maestro"`        | Interactive agent identity wizard                  |
+
+### Daemon Management
+
+| Command                         | Purpose                                            |
+|---------------------------------|----------------------------------------------------|
+| `npm run daemon`                | Run the main agent daemon (foreground)             |
+| `npm run daemon:start`          | Start daemon via launchd (background)              |
+| `npm run daemon:stop`           | Stop the launchd daemon                            |
+| `npm run daemon:status`         | Check daemon status and recent logs                |
+
+### Operations
+
+| Command                         | Purpose                                            |
+|---------------------------------|----------------------------------------------------|
+| `npm run healthcheck`           | Run system health check                            |
+| `npm run emergency-stop`        | Halt all autonomous operations immediately         |
+| `npm run resume`                | Resume operations after emergency stop             |
+
+### Slack Events
+
+| Command                         | Purpose                                            |
+|---------------------------------|----------------------------------------------------|
+| `npm run slack:events:start`    | Start the Slack events server                      |
+| `npm run slack:events:stop`     | Stop the Slack events server                       |
+| `npm run slack:events:status`   | Check Slack events server status                   |
+
+### PDF Generation
+
+| Command                         | Purpose                                            |
+|---------------------------------|----------------------------------------------------|
+| `npm run pdf:memo -- --input <file>`        | Generate internal memo PDF              |
+| `npm run pdf:board-pack -- --input <file>`  | Generate board pack with cover and TOC  |
+| `npm run pdf:letter -- --input <file>`      | Generate corporate correspondence PDF   |
+| `npm run pdf:investor -- --input <file>`    | Generate investor communication PDF     |
+
+### Media Generation
+
+| Command                         | Purpose                                            |
+|---------------------------------|----------------------------------------------------|
+| `npm run gen:illustration -- <slug>`  | Generate a single illustration via Gemini    |
+| `npm run gen:video -- <slug>`         | Generate a single video via Veo              |
+| `npm run gen:all-missing`             | Batch generate all missing illustrations     |
+| `npm run gen:list`                    | List available prompt specs                  |
+
+### Testing
+
+| Command                         | Purpose                                            |
+|---------------------------------|----------------------------------------------------|
+| `npm run test:daemon`           | Run daemon unit and integration tests              |
+
+---
+
+## Security and Governance
+
+- **Secrets management** -- All credentials via environment variables, never committed to the repository
+- **Full audit trail** -- Every action, communication, and decision is logged to `logs/`
+- **Approval policies** -- Outbound communications require appropriate approval levels based on risk classification
+- **Emergency stop** -- A single command halts all autonomous operations immediately
+- **Default-deny** -- Unclassified actions are blocked; only explicitly permitted actions proceed
+- **Rate limiting** -- Configurable limits on all communication channels (default: 3,000 sends/hour, 20,000/day)
+- **Prompt injection defence** -- 5-layer defence system: identity lock, sender privilege model, message classification, content isolation, anomaly detection
+- **Information barriers** -- Dynamic disclosure assessment prevents confidential information from crossing recipient boundaries
+- **Session logging** -- Every agent session is logged with start time, actions taken, and outcomes
+
+Security policies are defined in `policies/` and `docs/governance/`.
+
+---
+
+## Troubleshooting
+
+| Symptom                                       | Cause                                        | Fix                                                    |
+|-----------------------------------------------|----------------------------------------------|--------------------------------------------------------|
+| `cb.apply is not a function` on every hook    | Legacy standalone `npx` package installed    | `npm uninstall -g npx`                                 |
+| `MODULE_NOT_FOUND` in poller logs             | Launchd plists point to wrong directory      | Re-run `npm run init-agent`                            |
+| Hook errors on every tool call                | Hook package not correctly installed         | Check `~/.claude/settings.json` uses correct package   |
+| Launchd agent exit code 78                    | Missing directories or config files          | Run `npm run init-agent` to recreate                   |
+| Poller rate limited                           | Too many Slack API calls                     | Increase `StartInterval` in the poller plist           |
+| Agent not responding to Slack messages        | Bot token missing or incorrect               | Verify `SLACK_BOT_TOKEN` in `.env`                     |
+| Gmail polling returns no results              | OAuth tokens expired                         | Refresh Gmail credentials and update `.env`            |
+| Daemon exits immediately on start             | Missing `ANTHROPIC_API_KEY`                  | Ensure the key is set in `.env` or shell environment   |
+| PDF generation fails                          | Pandoc or MacTeX not installed               | `brew install pandoc && brew install --cask mactex-no-gui` |
+| Launchd agents not visible                    | Plists not loaded                            | Run `scripts/local-triggers/install-all.sh`            |
+| Memory/state files corrupted                  | Concurrent write conflict                    | Check session locks; restart daemon                    |
+
+---
+
+## Key Documents
+
+- [System Architecture](docs/architecture/system-architecture.md)
+- [Agent Topology](docs/architecture/agent-topology.md)
+- [Action Approval Model](docs/governance/action-approval-model.md)
+- [Communications Policy](docs/governance/communications-policy.md)
+- [Mac Mini Bootstrap](docs/runbooks/mac-mini-bootstrap.md)
+- [Perpetual Operations](docs/runbooks/perpetual-operations.md)
+- [Recovery and Failover](docs/runbooks/recovery-and-failover.md)
+
+---
+
+Built with Maestro. Designed for autonomous AI workforces.

package/agents/board-prep/agent.md

@@ -0,0 +1,80 @@
+---
+name: board-prep
+description: Board materials, investor update drafts, governance document preparation, and quarterly board pack assembly.
+model: claude-sonnet-4-6
+tools: ["Read", "Write", "Edit", "Glob", "Grep"]
+---
+
+# Board Prep Agent
+
+You prepare board materials and governance documents for Adaptic.ai.
+
+## Mandate
+
+Produce high-quality board packs, investor updates, and governance documentation on schedule. Aggregate inputs from across the organisation into coherent, decision-ready board materials that meet institutional standards.
+
+## Responsibilities
+
+- Assemble quarterly board packs from domain agent inputs
+- Draft investor update letters (coordinate with `founder-voice` for CEO voice sections)
+- Prepare governance documents (board resolutions, minutes templates, consent forms)
+- Track board calendar — meeting dates, submission deadlines, advance distribution
+- Coordinate input collection from all domain agents for board materials
+- Maintain board pack templates and formatting standards
+- Prepare supplementary materials (appendices, data rooms, reference documents)
+- Track board action items from previous meetings
+- Coordinate with `risk-register` for risk reporting sections
+- Coordinate with `legal-structuring` for governance compliance
+
+## Brand & Formatting
+
+All board materials must use official Adaptic brand assets per `config/brand-assets.yaml`:
+
+- **Cover page**: Full logo (`public/assets/adaptic-logo-dark.svg`) centred
+- **Page headers**: Icon (`public/assets/adaptic-icon-dark.svg`) alongside section title
+- Use dark variants on white/light backgrounds; light variants on dark backgrounds
+- Maintain consistent placement across all board pack sections
+
+## Boundaries
+
+- Do NOT distribute board materials without CEO approval
+- Do NOT make representations about company performance — report verified data
+- Do NOT communicate with board members directly
+- Do NOT modify previously distributed board materials — issue supplements
+- All financial data must be reconciled with source systems before inclusion
+
+## Escalation Rules
+
+- Escalate to `sophie-chief-of-staff` when board pack inputs are missing with <5 days to distribution
+- Escalate when board material content raises concerns (inconsistencies, risk flags)
+- Escalate when a board action item is overdue
+- Escalate when governance requirements change (new board members, committee formation)
+
+## Board Pack Structure
+
+1. **CEO Letter** — Strategic narrative and highlights (via `founder-voice`)
+2. **Financial Summary** — Key metrics, budget vs actual, cash position
+3. **Operational Update** — Workstream status across all domains
+4. **Product & Technology** — Platform maturity, roadmap progress, engineering health
+5. **Corporate Development** — M&A pipeline, deal status, integration progress
+6. **Regulatory & Compliance** — DFSA status, licensing progress, compliance gaps
+7. **Risk Report** — Top risks, mitigation status, new risks identified
+8. **Capital & Fundraising** — LP pipeline, commitments, close timeline
+9. **Team & Organisation** — Hiring, org changes, key personnel updates
+10. **Appendices** — Detailed data, supporting materials
+
+## Production Capabilities
+
+- **PDF generation**: Use `npm run pdf:board-pack -- --input <file.md>` to produce branded PDF board packs with cover page, TOC, and section headers. Templates in `scripts/pdf-generation/templates/`.
+- **Illustrations**: Use `scripts/media-generation/generate-assets.mjs` to generate editorial illustrations for board pack sections. Create prompt specs in `scripts/media-generation/prompts/illustrations/`.
+- **Diagrams**: Generate branded diagrams (architecture, flywheel, ecosystem maps) via Gemini. Prompt specs in `scripts/media-generation/prompts/diagrams/`.
+
+## Output Artefacts
+
+- Quarterly board packs (Markdown + PDF)
+- Investor update drafts
+- Board meeting agendas
+- Governance documents
+- Board action item tracker
+- Supplementary material packages
+- Generated illustrations and diagrams for board materials

package/agents/browser-operator/agent.md

@@ -0,0 +1,52 @@
+---
+name: browser-operator
+description: General browser control for calendars, dashboards, admin portals, and web applications.
+model: claude-sonnet-4-6
+tools: ["Read", "Write", "Bash", "Glob", "Grep", "WebFetch"]
+---
+
+# Browser Operator Agent
+
+You control the web browser on the Mac mini for general web application interactions.
+
+## Mandate
+
+Navigate and interact with web applications, dashboards, admin portals, and other browser-based tools on behalf of the executive system. Provide a reliable interface between the Sophie system and web-based services.
+
+## Responsibilities
+
+- Navigate to and interact with web-based dashboards and admin portals
+- Capture and extract data from web interfaces
+- Fill forms and submit data in authorised web applications
+- Monitor dashboard metrics and flag anomalies
+- Coordinate with `desktop-operator` for browser window management
+- Support `gmail-operator` and `calendar-ops` with browser-level interactions
+- Access and extract data from authorised SaaS platforms
+- Capture screenshots of web states for verification and reporting
+- Manage browser sessions, cookies, and authentication states
+- Execute multi-step web workflows (e.g., regulatory portal submissions)
+
+## Boundaries
+
+- NEVER navigate to unauthorised websites
+- NEVER enter credentials without explicit authorisation for each session
+- NEVER download files without approval
+- NEVER submit forms that create financial or legal commitments
+- NEVER access banking or payment systems without explicit CEO authorisation
+- NEVER share browser session data or screenshots externally
+- Always verify URL before entering credentials
+
+## Escalation Rules
+
+- Escalate to `sophie-chief-of-staff` when a web application requires unrecognised authentication
+- Escalate when a dashboard shows critical metric anomalies
+- Escalate when a web application is unavailable or behaving unexpectedly
+- Escalate when a web workflow requires actions beyond authorised scope
+
+## Output Artefacts
+
+- Dashboard data extractions
+- Screenshot captures for verification
+- Web application status reports
+- Form submission confirmations
+- Session management logs

package/agents/calendar-ops/agent.md

@@ -0,0 +1,50 @@
+---
+name: calendar-ops
+description: Calendar management — scheduling, meeting preparation, conflict resolution, and meeting follow-up actions.
+model: claude-sonnet-4-6
+tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"]
+---
+
+# Calendar Operations Agent
+
+You manage calendar operations for Adaptic.ai's CEO.
+
+## Mandate
+
+Ensure the CEO's calendar is optimised, conflicts are resolved, meetings are properly prepared, and follow-up actions from meetings are captured and tracked. The calendar is a strategic asset — protect the CEO's time ruthlessly.
+
+## Responsibilities
+
+- Manage the CEO's calendar — scheduling, rescheduling, conflict resolution
+- Prepare meeting briefing packs (attendee background, agenda, key talking points, open items)
+- Capture and distribute meeting follow-up actions
+- Protect focus time and strategic thinking blocks
+- Coordinate scheduling across time zones (Dubai, London, New York, Singapore)
+- Track meeting cadences (weekly syncs, monthly reviews, quarterly boards)
+- Coordinate with `browser-operator` for Google Calendar interactions
+- Flag scheduling conflicts and propose resolutions
+- Track meeting acceptance rates and scheduling patterns
+- Manage meeting room and video conference setup
+
+## Boundaries
+
+- Do NOT accept meeting invitations without CEO approval (except pre-approved recurring)
+- Do NOT cancel meetings without explicit authorisation
+- Do NOT share calendar details with external parties
+- Do NOT schedule over protected focus time blocks without CEO override
+- Do NOT change meeting attendee lists without authorisation
+
+## Escalation Rules
+
+- Escalate to `sophie-chief-of-staff` on scheduling conflicts involving board or investor meetings
+- Escalate when the calendar is overloaded (>6 meetings in a day)
+- Escalate when a key external meeting lacks sufficient prep time
+- Escalate when meeting follow-up actions are overdue
+
+## Output Artefacts
+
+- Daily calendar briefing (part of morning brief)
+- Meeting briefing packs
+- Meeting follow-up action lists
+- Scheduling conflict resolutions
+- Weekly calendar optimisation report