@adaptic/maestro 1.1.0 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/commands/init-maestro.md +292 -29
- package/.gitignore +29 -0
- package/README.md +228 -344
- package/bin/maestro.mjs +462 -7
- package/docs/guides/agent-persona-setup.md +1 -1
- package/lib/action-executor.js +225 -0
- package/lib/index.js +16 -0
- package/lib/singleton.js +116 -0
- package/lib/tool-definitions.js +510 -0
- package/package.json +10 -1
- package/scaffold/CLAUDE.md +207 -0
- package/scripts/daemon/maestro-daemon.mjs +37 -0
- package/scripts/local-triggers/generate-plists.sh +235 -0
- package/scripts/local-triggers/install-all.sh +18 -12
- package/scripts/setup/init-agent.sh +58 -27
- package/scripts/slack-events-server.mjs +10 -0
- package/scripts/local-triggers/plists/ai.adaptic.slack-events-server.plist +0 -45
package/README.md
CHANGED
|
@@ -1,166 +1,187 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @adaptic/maestro
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@adaptic/maestro)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A production-grade npm package for deploying autonomous AI agents on dedicated Mac minis.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## What is Maestro?
|
|
10
10
|
|
|
11
|
-
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.
|
|
11
|
+
Maestro is an autonomous AI agent operating system, distributed as an npm package. 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.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
- Runs 24/7 on a dedicated Mac mini, polling Slack, Gmail, and Calendar for events
|
|
15
|
-
- Reasons about incoming information and takes action autonomously
|
|
16
|
-
- Sends messages, drafts documents, follows up on open loops, and coordinates work
|
|
17
|
-
- Maintains persistent memory, decision logs, and strategic context across sessions
|
|
18
|
-
- Spawns parallel sub-agents for complex, multi-track execution
|
|
19
|
-
- Produces branded PDFs, executive briefs, and media assets
|
|
13
|
+
Each agent lives in its own repository. You install `@adaptic/maestro` to scaffold that repo, and the package provides the framework: scripts, agent definitions, workflow templates, governance policies, macOS automation, and Claude Code integration. Your repo holds the agent's identity, configuration, secrets, and runtime data. The framework and the agent's state are cleanly separated, so framework upgrades never overwrite your agent's personality or operational history.
|
|
20
14
|
|
|
21
|
-
|
|
22
|
-
- Not a chatbot. The agent operates proactively, not just in response to prompts.
|
|
23
|
-
- Not a demo or prototype. This is production infrastructure for real organisations.
|
|
24
|
-
- Not a generic agent framework. It is opinionated about deployment (Mac mini), reasoning (Claude Code), and governance (audit trails, approval policies, rate limits).
|
|
15
|
+
Maestro uses Claude Code as its reasoning engine and integrates with Slack, Gmail, Google Calendar, WhatsApp, SMS, and 25+ MCP-connected services. Agents run 24/7 on a dedicated Mac mini, polling for events, reasoning about incoming information, executing tasks autonomously, and maintaining persistent memory across sessions. They send messages, draft documents, follow up on open loops, spawn parallel sub-agents for complex work, and produce branded PDFs and media assets.
|
|
25
16
|
|
|
26
|
-
|
|
27
|
-
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.
|
|
17
|
+
The package provides: framework scripts (poller, daemon, triggers, hooks, PDF and media generation), 31 agent definitions with mandates and prompts, workflow templates across daily/weekly/monthly/quarterly cadences, operational skills as a Claude Code plugin, slash commands for agent setup, macOS launchd configuration, and comprehensive documentation and runbooks.
|
|
28
18
|
|
|
29
19
|
---
|
|
30
20
|
|
|
31
|
-
##
|
|
21
|
+
## Quick Start
|
|
32
22
|
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
├──────────┬──────────┬──────────┬──────────┬─────────┤
|
|
38
|
-
│ Briefing │ Strategic│ Domain │ Comms │ Task │
|
|
39
|
-
│ │ Planning │ Ops │ Gov. │ Exec. │
|
|
40
|
-
│ (Tier 1) │ (Tier 1) │ (Tier 1) │ (Tier 1) │(Tier 1)│
|
|
41
|
-
├──────────┴──────────┴──────────┴──────────┴─────────┤
|
|
42
|
-
│ 20+ Specialist Agents (Tier 2) │
|
|
43
|
-
│ Research · Product · Engineering · Legal · Ops · │
|
|
44
|
-
│ Finance · Partnerships · Hiring · Market Intel · │
|
|
45
|
-
│ Board Prep · Compliance · Writing · ... │
|
|
46
|
-
├─────────────────────────────────────────────────────┤
|
|
47
|
-
│ Desktop Operations (Tier 3) │
|
|
48
|
-
│ Slack · Gmail · WhatsApp · Browser · Calendar │
|
|
49
|
-
├─────────────────────────────────────────────────────┤
|
|
50
|
-
│ Governance & Memory (Tier 4) │
|
|
51
|
-
│ Decision Log · Risk Register · Knowledge Base │
|
|
52
|
-
└─────────────────────────────────────────────────────┘
|
|
23
|
+
```bash
|
|
24
|
+
npx @adaptic/maestro create jacob-ai
|
|
25
|
+
cd jacob-ai
|
|
26
|
+
claude "/init-maestro" # Handles everything: setup, identity, services, launchd
|
|
53
27
|
```
|
|
54
28
|
|
|
55
|
-
|
|
29
|
+
### Prerequisites
|
|
56
30
|
|
|
57
|
-
|
|
31
|
+
| Dependency | Install | Purpose |
|
|
32
|
+
|-------------------|------------------------------------------------------------|--------------------------------|
|
|
33
|
+
| Node.js 20+ | `brew install node` | Runtime for poller, triggers |
|
|
34
|
+
| Claude CLI | `npm install -g @anthropic-ai/claude-code` | Agent reasoning engine |
|
|
35
|
+
| jq | `brew install jq` | Used by hook scripts |
|
|
36
|
+
| Pandoc + MacTeX | `brew install pandoc && brew install --cask mactex-no-gui` | PDF generation (optional) |
|
|
37
|
+
| Anthropic API key | Set `ANTHROPIC_API_KEY` env var | Required for Claude CLI |
|
|
58
38
|
|
|
59
|
-
|
|
39
|
+
---
|
|
60
40
|
|
|
61
|
-
|
|
41
|
+
## What the Package Provides
|
|
42
|
+
|
|
43
|
+
When you run `npx @adaptic/maestro create <name>`, the following framework files are copied into your new agent repo:
|
|
44
|
+
|
|
45
|
+
| Directory | Description |
|
|
46
|
+
|--------------------------|-----------------------------------------------------------------------------|
|
|
47
|
+
| `scripts/` | Poller, daemon, trigger runner, hooks, PDF generation, media generation, setup scripts, healthcheck, emergency stop |
|
|
48
|
+
| `agents/` | 31 specialist agent definitions with mandates, responsibilities, and prompts |
|
|
49
|
+
| `workflows/` | Workflow templates: continuous, daily, weekly, monthly, quarterly cadences |
|
|
50
|
+
| `policies/` | Action classification, information barriers, prompt injection defence |
|
|
51
|
+
| `plugins/maestro-skills/`| Operational skills plugin for Claude Code (memory, comms, queue management) |
|
|
52
|
+
| `.claude/commands/` | Slash commands including `/init-maestro` for identity setup |
|
|
53
|
+
| `.claude/settings.json` | Project-level Claude Code hooks and permissions |
|
|
54
|
+
| `schedules/` | Trigger prompt templates for launchd-scheduled sessions |
|
|
55
|
+
| `teams/` | Agent team compositions and coordination definitions |
|
|
56
|
+
| `docs/` | Architecture docs, governance policies, runbooks, workflow documentation |
|
|
57
|
+
| `public/assets/` | Brand SVG assets (icon and logo, dark and light variants) |
|
|
58
|
+
| `desktop-control/` | macOS app control profiles for desktop automation |
|
|
59
|
+
| `scaffold/` | Template files for agent-specific config (CLAUDE.md, config/agent.ts) |
|
|
62
60
|
|
|
63
|
-
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## What Lives in the Agent Repo (Not in the Package)
|
|
64
|
+
|
|
65
|
+
These files are specific to your agent and are never overwritten by framework upgrades:
|
|
66
|
+
|
|
67
|
+
| File / Directory | Purpose |
|
|
68
|
+
|--------------------------|------------------------------------------------------------------|
|
|
69
|
+
| `CLAUDE.md` | The agent's behavioural charter -- identity, principles, communication rules, operating modes |
|
|
70
|
+
| `config/agent.ts` | Structured identity data: name, title, email, archetype, schedule, communication style |
|
|
71
|
+
| `config/contacts.yaml` | Key relationships and communication permissions |
|
|
72
|
+
| `config/priorities.yaml` | Strategic focus areas and milestones |
|
|
73
|
+
| `config/environment.yaml`| System-level settings: paths, scheduling, secrets references |
|
|
74
|
+
| `.env` | API keys and credentials (never committed to git) |
|
|
75
|
+
| `knowledge/` | Sources, syntheses, entities, decisions, and memory |
|
|
76
|
+
| `memory/` | Interaction history, user and channel profiles, precedents |
|
|
77
|
+
| `state/` | Queues, inbox, dashboards, polling cursors, locks |
|
|
78
|
+
| `logs/` | Audit trails, polling logs, workflow logs, session logs |
|
|
79
|
+
| `outputs/` | Briefs, memos, drafts, research, and generated deliverables |
|
|
64
80
|
|
|
65
81
|
---
|
|
66
82
|
|
|
67
|
-
##
|
|
83
|
+
## CLI Reference
|
|
68
84
|
|
|
69
|
-
###
|
|
85
|
+
### `npx @adaptic/maestro create <name>`
|
|
70
86
|
|
|
71
|
-
|
|
72
|
-
|---------------------|------------------------------------------------------------|----------------------------------|
|
|
73
|
-
| Node.js 25+ | `brew install node` | Runtime for poller, triggers |
|
|
74
|
-
| Claude CLI | `npm install -g @anthropic-ai/claude-code` | Agent reasoning engine |
|
|
75
|
-
| jq | `brew install jq` | Used by hook scripts |
|
|
76
|
-
| Pandoc + MacTeX | `brew install pandoc && brew install --cask mactex-no-gui` | PDF generation (optional) |
|
|
77
|
-
| Anthropic API key | Set `ANTHROPIC_API_KEY` env var | Required for Claude CLI |
|
|
87
|
+
Scaffolds a new agent repository. This command:
|
|
78
88
|
|
|
79
|
-
|
|
89
|
+
1. Creates the target directory
|
|
90
|
+
2. Copies all framework files (scripts, agents, workflows, policies, plugins, docs)
|
|
91
|
+
3. Copies scaffold templates (CLAUDE.md and config/agent.ts stubs)
|
|
92
|
+
4. Copies `.claude/` directory (settings and commands)
|
|
93
|
+
5. Creates 57 agent-specific directories (config, knowledge, memory, state, logs, outputs, self-optimization, tests)
|
|
94
|
+
6. Generates 53 operational template files (16 queues, 10 dashboards, 13 configs, 9 knowledge schemas, 5 self-optimization)
|
|
95
|
+
7. Generates a `package.json` with all required scripts and dependencies
|
|
96
|
+
8. Copies `.env.example` and `.gitignore`
|
|
97
|
+
9. Initializes a git repository
|
|
98
|
+
10. Runs `npm install`
|
|
80
99
|
|
|
81
|
-
|
|
82
|
-
git clone git@github.com:your-org/maestro.git ~/your-agent
|
|
83
|
-
cd ~/your-agent
|
|
84
|
-
npm run init-agent
|
|
85
|
-
```
|
|
100
|
+
After `create`, run `claude "/init-maestro"` to configure the agent's identity and bring it online. The wizard handles system bootstrap, identity configuration, service setup, launchd installation, and verification -- no other setup commands are needed.
|
|
86
101
|
|
|
87
|
-
|
|
88
|
-
- Installs npm dependencies
|
|
89
|
-
- Creates all required `state/`, `logs/`, `memory/` directories
|
|
90
|
-
- Installs global Claude Code settings with hook configuration
|
|
91
|
-
- Generates and loads 12 macOS launchd agents (poller, inbox processor, backlog executor, meeting prep, weekly triggers, etc.)
|
|
92
|
-
- Creates a `.env` template for API keys
|
|
93
|
-
- Runs a health check
|
|
102
|
+
### `npx @adaptic/maestro upgrade`
|
|
94
103
|
|
|
95
|
-
|
|
104
|
+
Updates framework files in an existing agent repo. This command copies the latest versions of:
|
|
96
105
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
106
|
+
- `scripts/` -- poller, daemon, hooks, PDF generation, setup scripts
|
|
107
|
+
- `policies/` -- action classification, information barriers, prompt injection defence
|
|
108
|
+
- `docs/` -- architecture, governance, runbooks
|
|
109
|
+
- `public/assets/` -- brand assets
|
|
110
|
+
- `workflows/`, `schedules/`, `teams/`, `desktop-control/`, `ingest/`, `mcp/`
|
|
111
|
+
- `.claude/commands/` -- slash commands
|
|
112
|
+
- `plugins/maestro-skills/` -- operational skills
|
|
113
|
+
- `agents/` -- new agents are added, existing ones preserved (no deletions)
|
|
114
|
+
|
|
115
|
+
It also creates any missing directories from the expanded directory set.
|
|
100
116
|
|
|
101
|
-
|
|
117
|
+
Agent-specific files (`config/`, `CLAUDE.md`, `knowledge/`, `memory/`, `state/`, `logs/`) are never touched.
|
|
102
118
|
|
|
103
|
-
|
|
104
|
-
|-------------------------|----------------------------------------|
|
|
105
|
-
| Agent name | "Jordan" |
|
|
106
|
-
| Agent surname | "Blake" |
|
|
107
|
-
| Agent role/title | "Chief of Staff" |
|
|
108
|
-
| Directory name | "jordan-ai" |
|
|
109
|
-
| Mac mini hostname | "jordan-mini" |
|
|
110
|
-
| Key responsibilities | 2-5 bullet points |
|
|
111
|
-
| Reporting line | "CEO" or specific person |
|
|
112
|
-
| Communication style | Formal/casual, proactive/reactive |
|
|
119
|
+
### `npx @adaptic/maestro doctor`
|
|
113
120
|
|
|
114
|
-
|
|
121
|
+
Verifies the agent installation. Checks for 16 essential files:
|
|
115
122
|
|
|
116
|
-
|
|
123
|
+
- Core: `config/agent.ts`, `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/init-maestro.md`, `package.json`
|
|
124
|
+
- Setup: `scripts/setup/init-agent.sh`, `scripts/healthcheck.sh`, `scripts/daemon/maestro-daemon.mjs`, `scripts/local-triggers/generate-plists.sh`
|
|
125
|
+
- Config: `config/environment.yaml`, `config/contacts.yaml`, `config/priorities.yaml`, `config/sla-defaults.yaml`
|
|
126
|
+
- State: `state/dashboards/executive-summary.yaml`, `state/queues/action-stack.yaml`, `knowledge/decisions/decision-schema.yaml`
|
|
127
|
+
- Environment: `.env` file with `ANTHROPIC_API_KEY` (required), `SLACK_USER_TOKEN`, `GMAIL_APP_PASSWORD` (optional)
|
|
128
|
+
- Dependencies: `node_modules` installed, Claude CLI available
|
|
117
129
|
|
|
118
|
-
|
|
130
|
+
---
|
|
119
131
|
|
|
120
|
-
|
|
132
|
+
## Updating the Framework
|
|
121
133
|
|
|
122
134
|
```bash
|
|
123
|
-
|
|
135
|
+
npm update @adaptic/maestro # Get the latest version from npm
|
|
136
|
+
npm run upgrade # Copy updated framework files into your repo
|
|
137
|
+
git diff # Review what changed
|
|
138
|
+
git add -A && git commit -m "Upgrade maestro framework"
|
|
124
139
|
```
|
|
125
140
|
|
|
126
|
-
|
|
141
|
+
The `upgrade` command only updates framework infrastructure: scripts, policies, documentation, brand assets, commands, and plugins. It never modifies your agent's identity (`CLAUDE.md`, `config/agent.ts`), configuration (`config/*.yaml`), secrets (`.env`), or runtime data (`knowledge/`, `memory/`, `state/`, `logs/`, `outputs/`). Your agent's personality, relationships, and operational history remain intact.
|
|
127
142
|
|
|
128
|
-
|
|
143
|
+
---
|
|
129
144
|
|
|
130
|
-
|
|
131
|
-
# Check all launchd agents are loaded
|
|
132
|
-
launchctl list | grep adaptic
|
|
145
|
+
## The /init-maestro Wizard
|
|
133
146
|
|
|
134
|
-
|
|
135
|
-
npm run healthcheck
|
|
147
|
+
After scaffolding, run `claude "/init-maestro"` to configure your agent. This is the only command you need -- it handles everything from system setup to identity configuration to bringing the agent online. The wizard runs in eight phases:
|
|
136
148
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
149
|
+
| Phase | What it does |
|
|
150
|
+
|-------|-------------|
|
|
151
|
+
| **0. System Bootstrap** | Checks prerequisites (Node.js, npm, Claude CLI, jq), runs `npm install`, creates directories, installs global Claude Code settings, creates `.env` from template |
|
|
152
|
+
| **1. Identity Gathering** | Prompts for agent name, surname, title, archetype, email, phone, Mac mini hostname, principal (reporting line), responsibilities, communication style, operating principles |
|
|
153
|
+
| **2. Parallel Rewrite** | 8 sub-agents rewrite the repo in parallel: `config/agent.ts`, `CLAUDE.md`, config files, `package.json`, scripts, agent definitions, triggers/workflows, and agent-specific tools/skills |
|
|
154
|
+
| **3. Machine Config** | Generates launchd plists with the correct agent name, installs them, optionally configures macOS for headless 24/7 operation |
|
|
155
|
+
| **4. Service Setup** | Walks through Slack, Gmail, Twilio, Cloudflare, voice integration -- writing credentials to `.env` |
|
|
156
|
+
| **5. README** | Generates an agent-specific README.md |
|
|
157
|
+
| **6. GitHub Repo** | Optionally creates a GitHub repository and pushes the initial commit |
|
|
158
|
+
| **7. Verification** | Greps for stale references, validates `config/agent.ts`, runs healthcheck, prints summary |
|
|
159
|
+
|
|
160
|
+
See [docs/guides/agent-persona-setup.md](docs/guides/agent-persona-setup.md) for the full persona configuration guide, including archetype defaults, Control Tower selection, contact classification, and manual fine-tuning.
|
|
140
161
|
|
|
141
162
|
---
|
|
142
163
|
|
|
143
164
|
## Required Services and API Keys
|
|
144
165
|
|
|
145
|
-
| Service
|
|
146
|
-
|
|
147
|
-
| Anthropic API
|
|
148
|
-
| Slack
|
|
149
|
-
| Gmail
|
|
150
|
-
| Google Calendar
|
|
151
|
-
| Google Drive
|
|
152
|
-
| OpenAI
|
|
153
|
-
| Google Gemini
|
|
154
|
-
| Twilio
|
|
155
|
-
| Deepgram
|
|
156
|
-
| ElevenLabs
|
|
157
|
-
| Greptile
|
|
158
|
-
|
|
159
|
-
Additional services are available via MCP servers and can be configured separately. Supported integrations include Airtable, Linear, Figma, Notion, Jira, Calendly, and more.
|
|
166
|
+
| Service | Purpose | Required? | Signup URL | Tier / Pricing |
|
|
167
|
+
|------------------|------------------------------------|-------------|-------------------------------------------|-----------------------------------|
|
|
168
|
+
| Anthropic API | Primary reasoning engine (Claude) | Required | https://console.anthropic.com | Pay-per-token or Max subscription |
|
|
169
|
+
| Slack | Team communication | Required | https://api.slack.com/apps | Free (workspace needed) |
|
|
170
|
+
| Gmail | Email monitoring and sending | Required | https://myaccount.google.com/apppasswords | Google Workspace or free Gmail |
|
|
171
|
+
| Google Calendar | Meeting and schedule awareness | Recommended | Via Google Workspace | Same account as Gmail |
|
|
172
|
+
| Google Drive | Document sharing | Recommended | Via Google Workspace | Same account as Gmail |
|
|
173
|
+
| OpenAI | Supplemental model access | Optional | https://platform.openai.com | Pay-per-token |
|
|
174
|
+
| Google Gemini | Media generation (images, video) | Optional | https://aistudio.google.com | Free tier available |
|
|
175
|
+
| Twilio | SMS, voice, and WhatsApp | Optional | https://www.twilio.com | Pay-as-you-go (~$1/mo + usage) |
|
|
176
|
+
| Deepgram | Speech-to-text transcription | Optional | https://deepgram.com | Free tier (200 hrs/yr) |
|
|
177
|
+
| ElevenLabs | Text-to-speech voice synthesis | Optional | https://elevenlabs.io | Free tier available |
|
|
178
|
+
| Greptile | Codebase search and indexing | Optional | https://greptile.com | Free tier available |
|
|
179
|
+
|
|
180
|
+
Additional services are available via MCP servers and can be configured separately. Supported integrations include Airtable, Linear, Figma, Notion, Jira, Calendly, and more.
|
|
160
181
|
|
|
161
182
|
### Environment Variables
|
|
162
183
|
|
|
163
|
-
|
|
184
|
+
The `/init-maestro` wizard creates the `.env` file and walks you through filling in credentials. Key variables:
|
|
164
185
|
|
|
165
186
|
```bash
|
|
166
187
|
# Core
|
|
@@ -192,253 +213,132 @@ GEMINI_API_KEY=...
|
|
|
192
213
|
|
|
193
214
|
---
|
|
194
215
|
|
|
195
|
-
##
|
|
196
|
-
|
|
197
|
-
The central identity file is `config/agent.ts` (or the `CLAUDE.md` identity section, depending on your setup). This defines:
|
|
198
|
-
|
|
199
|
-
- **Agent name, role, and title** -- who the agent is
|
|
200
|
-
- **Operating principles** -- how the agent makes decisions
|
|
201
|
-
- **Communication rules** -- voice modes, autonomy levels, escalation triggers
|
|
202
|
-
- **Domain context** -- what the agent knows about the organisation
|
|
203
|
-
- **Reporting line** -- who the agent escalates to
|
|
204
|
-
|
|
205
|
-
Run `claude "/init-maestro"` for interactive setup, or see `docs/guides/agent-persona-setup.md` for manual configuration.
|
|
206
|
-
|
|
207
|
-
---
|
|
208
|
-
|
|
209
|
-
## Directory Structure
|
|
216
|
+
## Architecture
|
|
210
217
|
|
|
211
218
|
```
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
│
|
|
217
|
-
│
|
|
218
|
-
│
|
|
219
|
-
|
|
220
|
-
│
|
|
221
|
-
│
|
|
222
|
-
│
|
|
223
|
-
│
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
│
|
|
229
|
-
│
|
|
230
|
-
|
|
231
|
-
│ ├── monthly/ # Board readiness, risk refresh
|
|
232
|
-
│ └── quarterly/ # Scenario analysis, board pack
|
|
233
|
-
├── schedules/
|
|
234
|
-
│ └── triggers/ # Trigger prompts for launchd-scheduled sessions
|
|
235
|
-
├── scripts/
|
|
236
|
-
│ ├── setup/
|
|
237
|
-
│ │ └── init-agent.sh # One-line machine setup script
|
|
238
|
-
│ ├── local-triggers/
|
|
239
|
-
│ │ ├── run-trigger.sh # Trigger runner (invoked by launchd)
|
|
240
|
-
│ │ ├── install-all.sh # Install launchd plists
|
|
241
|
-
│ │ └── plists/ # macOS launchd plist templates
|
|
242
|
-
│ ├── daemon/ # Main agent daemon
|
|
243
|
-
│ ├── poller/ # Event polling (Slack, Gmail, Calendar)
|
|
244
|
-
│ ├── hooks/ # Claude Code hook scripts
|
|
245
|
-
│ ├── pdf-generation/ # Branded PDF generation (Pandoc + XeLaTeX)
|
|
246
|
-
│ └── media-generation/ # AI illustration/video generation
|
|
247
|
-
├── knowledge/ # Sources, syntheses, memory, entities, decisions
|
|
248
|
-
├── config/ # Environment, priorities, contacts, repos, brand
|
|
249
|
-
├── policies/ # Action classification, approval rules
|
|
250
|
-
├── state/ # Queues, inbox, dashboards, polling cursors
|
|
251
|
-
├── outputs/ # Briefs, memos, drafts, research
|
|
252
|
-
├── memory/ # Interaction history, profiles, precedents
|
|
253
|
-
└── logs/ # Operational logs (audit, polling, workflows)
|
|
219
|
+
┌─────────────────────────────────────────────────────┐
|
|
220
|
+
│ Your Agent │
|
|
221
|
+
│ Executive Cortex (Tier 0) │
|
|
222
|
+
├──────────┬──────────┬──────────┬──────────┬─────────┤
|
|
223
|
+
│ Briefing │ Strategic│ Domain │ Comms │ Task │
|
|
224
|
+
│ │ Planning │ Ops │ Gov. │ Exec. │
|
|
225
|
+
│ (Tier 1) │ (Tier 1) │ (Tier 1) │ (Tier 1) │(Tier 1)│
|
|
226
|
+
├──────────┴──────────┴──────────┴──────────┴─────────┤
|
|
227
|
+
│ 20+ Specialist Agents (Tier 2) │
|
|
228
|
+
│ Research · Product · Engineering · Legal · Ops · │
|
|
229
|
+
│ Finance · Partnerships · Hiring · Market Intel · │
|
|
230
|
+
│ Board Prep · Compliance · Writing · ... │
|
|
231
|
+
├─────────────────────────────────────────────────────┤
|
|
232
|
+
│ Desktop Operations (Tier 3) │
|
|
233
|
+
│ Slack · Gmail · WhatsApp · Browser · Calendar │
|
|
234
|
+
├─────────────────────────────────────────────────────┤
|
|
235
|
+
│ Governance & Memory (Tier 4) │
|
|
236
|
+
│ Decision Log · Risk Register · Knowledge Base │
|
|
237
|
+
└─────────────────────────────────────────────────────┘
|
|
254
238
|
```
|
|
255
239
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
## Operating Modes
|
|
240
|
+
**Tier 0 -- Executive Cortex:** The agent's core identity and reasoning loop. Reads dashboards, processes inbound events, makes decisions, and orchestrates lower tiers.
|
|
259
241
|
|
|
260
|
-
|
|
242
|
+
**Tier 1 -- Domain Controllers:** Specialised reasoning modules for briefing, strategic planning, domain operations, communications governance, and task execution.
|
|
261
243
|
|
|
262
|
-
|
|
244
|
+
**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.
|
|
263
245
|
|
|
264
|
-
|
|
246
|
+
**Tier 3 -- Desktop Operations:** Integrations with external services via MCP servers, APIs, and local tooling. Slack, Gmail, Google Calendar, WhatsApp, SMS, browser automation.
|
|
265
247
|
|
|
266
|
-
|
|
267
|
-
- An inbox processor classifies and routes incoming items every 5 minutes
|
|
268
|
-
- Priority events (CEO DMs, urgent tags, direct mentions) trigger immediate processing sessions
|
|
269
|
-
- All inbound events land in `state/inbox/` as structured YAML before being routed to the appropriate queue
|
|
248
|
+
**Tier 4 -- Governance & Memory:** Persistent state layer. Decision logs, risk registers, knowledge bases, interaction history, queue management, and audit trails.
|
|
270
249
|
|
|
271
|
-
###
|
|
250
|
+
### Operating Modes
|
|
272
251
|
|
|
273
|
-
|
|
252
|
+
All Maestro agents operate in three concurrent modes:
|
|
274
253
|
|
|
275
|
-
|
|
276
|
-
- **Weekly:** Strategic memo, pipeline review, hiring review, engineering health check, execution review
|
|
277
|
-
- **Monthly:** Board readiness, risk register refresh, financial integration
|
|
278
|
-
- **Quarterly:** Self-assessment, scenario analysis, board pack generation
|
|
254
|
+
**Mode 1: Reactive** -- The nervous system. A lightweight poller checks Slack, Gmail, and Calendar every 60 seconds. An inbox processor classifies and routes incoming items every 5 minutes. Priority events trigger immediate processing.
|
|
279
255
|
|
|
280
|
-
|
|
256
|
+
**Mode 2: Scheduled** -- The heartbeat. Daily morning brief, midday sweep, evening wrap. Weekly strategic memo, pipeline review, execution review. Monthly board readiness, risk refresh. Quarterly self-assessment and board pack. All triggered via macOS launchd.
|
|
281
257
|
|
|
282
|
-
|
|
258
|
+
**Mode 3: Proactive** -- The engine. The backlog executor runs every 10 minutes, reads all queues, selects the top actionable items by priority, and spawns parallel agents to execute them. Items move continuously from `open` to `in_progress` to `resolved` to `closed`.
|
|
283
259
|
|
|
284
|
-
|
|
260
|
+
---
|
|
285
261
|
|
|
286
|
-
-
|
|
287
|
-
- It reads all operational queues, selects the top 3-5 actionable items by priority
|
|
288
|
-
- It spawns parallel background agents to execute each item independently
|
|
289
|
-
- Agents do the actual work: draft documents, chase people, research topics, build deliverables
|
|
290
|
-
- Results are reviewed, queues are updated, and the next batch is picked up
|
|
291
|
-
- Items continuously move from `open` to `in_progress` to `resolved` to `closed`
|
|
262
|
+
## Auto-Publishing
|
|
292
263
|
|
|
293
|
-
|
|
264
|
+
Pushes to the `main` branch of the Maestro repository automatically publish to npm via GitHub Actions. Version bumps are handled automatically -- patch versions for fixes and minor changes, minor versions for new features. You do not need to manually publish or manage versions. When a new version is available, agent repos pick it up with `npm update @adaptic/maestro`.
|
|
294
265
|
|
|
295
266
|
---
|
|
296
267
|
|
|
297
|
-
##
|
|
268
|
+
## Agent Roster (Example)
|
|
298
269
|
|
|
299
|
-
|
|
270
|
+
Maestro supports deploying any number of agents, each on its own Mac mini with a distinct role and domain focus:
|
|
300
271
|
|
|
301
|
-
|
|
|
302
|
-
|
|
303
|
-
|
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
|
307
|
-
|
|
|
308
|
-
|
|
|
272
|
+
| Agent | Role | Archetype | Repo |
|
|
273
|
+
|---------|-----------------------------|----------------------|--------------------|
|
|
274
|
+
| Sophie | Chief of Staff | executive-operator | adapticai/sophie-ai |
|
|
275
|
+
| Jacob | Chief AI Scientist | technical-leader | adapticai/jacob-ai |
|
|
276
|
+
| Isla | Head of Engineering | technical-leader | adapticai/isla-ai |
|
|
277
|
+
| Nadia | Head of Compliance | compliance-officer | adapticai/nadia-ai |
|
|
278
|
+
| Luca | Head of Product | product-leader | adapticai/luca-ai |
|
|
279
|
+
| Amara | Head of Investor Relations | commercial-leader | adapticai/amara-ai |
|
|
280
|
+
| Kai | Head of Fund Operations | operations-leader | adapticai/kai-ai |
|
|
281
|
+
| Rowan | Head of Quant Engineering | technical-leader | adapticai/rowan-ai |
|
|
309
282
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
- **Pre-send audit hook** gates all outbound Slack and Gmail communications
|
|
313
|
-
- **Rate limits** prevent runaway sending (configurable per channel)
|
|
314
|
-
- **Duplicate detection** prevents the agent from replying to the same thread multiple times
|
|
315
|
-
- **Information barriers** prevent confidential information from leaking across recipient boundaries
|
|
316
|
-
- **Prompt injection defence** (5-layer) protects the agent from adversarial inbound messages
|
|
317
|
-
|
|
318
|
-
Communication governance policies are defined in `policies/action-classification.yaml`.
|
|
283
|
+
Each agent gets its own identity, operating principles, communication style, contact graph, priority stack, and specialist sub-agents -- all configured through the `/init-maestro` wizard.
|
|
319
284
|
|
|
320
285
|
---
|
|
321
286
|
|
|
322
|
-
##
|
|
287
|
+
## Tool Library (`lib/`)
|
|
323
288
|
|
|
324
|
-
Maestro
|
|
289
|
+
Maestro provides a comprehensive library of 27+ reusable tools that agents can use during voice conversations, huddles, and autonomous operations. Tools are scoped by access level and executed via the Claude API `tool_use` protocol.
|
|
325
290
|
|
|
326
|
-
###
|
|
291
|
+
### Categories
|
|
327
292
|
|
|
328
|
-
|
|
|
329
|
-
|
|
330
|
-
|
|
|
331
|
-
|
|
|
332
|
-
|
|
|
333
|
-
|
|
|
334
|
-
|
|
|
335
|
-
|
|
|
336
|
-
| Casey | Head of Investor Relations | casey-mini | casey-ai |
|
|
337
|
-
| Robin | Head of Fund Operations | robin-mini | robin-ai |
|
|
293
|
+
| Category | Tools | Description |
|
|
294
|
+
|----------|-------|-------------|
|
|
295
|
+
| **Communication** | `slack_send`, `draft_email`, `whatsapp_send`, `sms_send` | Send messages across all channels |
|
|
296
|
+
| **Search / RAG** | `search_email`, `search_calendar`, `search_files`, `search_meetings`, `search_slack`, `search_web`, `search_documents` | Real-time lookup via MCP-backed queries |
|
|
297
|
+
| **Knowledge** | `search_decisions`, `lookup_person`, `search_regulatory`, `search_strategy`, `search_precedents` | Institutional memory and governance |
|
|
298
|
+
| **Operations** | `queue_update`, `create_action_item`, `schedule_meeting`, `create_reminder` | Operational queue and calendar management |
|
|
299
|
+
| **Analysis** | `search_financial`, `search_pipeline`, `search_engineering`, `search_hiring`, `search_risk` | Cross-functional health and pipeline data |
|
|
300
|
+
| **Documents** | `generate_memo`, `generate_report` | Branded document generation |
|
|
338
301
|
|
|
339
|
-
###
|
|
302
|
+
### Usage
|
|
340
303
|
|
|
341
|
-
|
|
304
|
+
```js
|
|
305
|
+
import { getToolsForAccessLevel, executeAction } from "@adaptic/maestro";
|
|
342
306
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
307
|
+
// Get tools for a Claude API call
|
|
308
|
+
const tools = getToolsForAccessLevel("ceo"); // 27 tools
|
|
309
|
+
const tools = getToolsForAccessLevel("leadership"); // 19 tools (no WhatsApp/SMS/memo)
|
|
310
|
+
const tools = getToolsForAccessLevel("default"); // 17 tools (search/lookup only)
|
|
347
311
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
```bash
|
|
351
|
-
npm run init-agent
|
|
312
|
+
// Execute a tool call from Claude's response
|
|
313
|
+
const result = await executeAction("search_email", { query: "DFSA update" }, callerInfo, sessionId);
|
|
352
314
|
```
|
|
353
315
|
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
```bash
|
|
357
|
-
claude "/init-maestro"
|
|
358
|
-
```
|
|
359
|
-
|
|
360
|
-
The `/init-maestro` wizard handles the full identity transformation:
|
|
361
|
-
|
|
362
|
-
| What changes | Example |
|
|
363
|
-
|--------------------------------------|--------------------------------------------------|
|
|
364
|
-
| `CLAUDE.md` identity and principles | "Alex Park, Chief AI Scientist..." |
|
|
365
|
-
| Variable names in scripts | `AGENT_DIR` updated to new paths |
|
|
366
|
-
| Launchd plist labels | `ai.adaptic.agent-*` labels updated |
|
|
367
|
-
| `package.json` name and description | `"alex-ai"`, `"Autonomous AI scientist for..."` |
|
|
368
|
-
| `config/` files | Priorities, contacts, environment paths |
|
|
369
|
-
| `schedules/triggers/` | Trigger prompts reference the new identity |
|
|
370
|
-
| `agents/` definitions | Domain-specific agents adapted for the role |
|
|
371
|
-
|
|
372
|
-
### What Stays the Same
|
|
373
|
-
|
|
374
|
-
The following infrastructure is shared across all agents and does not need per-agent changes:
|
|
316
|
+
### RAG Architecture
|
|
375
317
|
|
|
376
|
-
|
|
377
|
-
- **Trigger runner** (`scripts/local-triggers/run-trigger.sh`) -- launchd-to-Claude bridge
|
|
378
|
-
- **Hook scripts** -- Pre/post tool hooks, session lifecycle
|
|
379
|
-
- **Brand assets** (`public/assets/`) -- Organisation-wide branding
|
|
380
|
-
- **PDF generation** (`scripts/pdf-generation/`) -- document templates
|
|
381
|
-
- **Governance framework** (`policies/`, `docs/governance/`) -- same rules, different agent
|
|
318
|
+
Lookup tools use `claude --print --model haiku` under the hood, which leverages the agent's Max subscription and all configured MCP servers (Gmail, Calendar, Slack, filesystem, Granola, etc.). This means every agent automatically gets search capabilities across all connected services without additional API costs.
|
|
382
319
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
## Commands Reference
|
|
386
|
-
|
|
387
|
-
### Machine Setup
|
|
388
|
-
|
|
389
|
-
| Command | Purpose |
|
|
390
|
-
|---------------------------------|----------------------------------------------------|
|
|
391
|
-
| `npm run init-agent` | Full machine setup (deps, dirs, launchd, env) |
|
|
392
|
-
| `claude "/init-maestro"` | Interactive agent identity wizard |
|
|
393
|
-
|
|
394
|
-
### Daemon Management
|
|
395
|
-
|
|
396
|
-
| Command | Purpose |
|
|
397
|
-
|---------------------------------|----------------------------------------------------|
|
|
398
|
-
| `npm run daemon` | Run the main agent daemon (foreground) |
|
|
399
|
-
| `npm run daemon:start` | Start daemon via launchd (background) |
|
|
400
|
-
| `npm run daemon:stop` | Stop the launchd daemon |
|
|
401
|
-
| `npm run daemon:status` | Check daemon status and recent logs |
|
|
402
|
-
|
|
403
|
-
### Operations
|
|
320
|
+
### Agent-Specific Tools
|
|
404
321
|
|
|
405
|
-
|
|
406
|
-
|---------------------------------|----------------------------------------------------|
|
|
407
|
-
| `npm run healthcheck` | Run system health check |
|
|
408
|
-
| `npm run emergency-stop` | Halt all autonomous operations immediately |
|
|
409
|
-
| `npm run resume` | Resume operations after emergency stop |
|
|
322
|
+
During `/init-maestro`, Sub-agent 8 generates role-specific tools based on the agent's archetype and responsibilities. These extend the base set — e.g., a compliance officer gets `licence_gap_check` and `regulatory_submission_status`, while an engineering leader gets `code_review_trigger` and `deployment_status`.
|
|
410
323
|
|
|
411
|
-
|
|
324
|
+
## Global vs Agent-Specific Features
|
|
412
325
|
|
|
413
|
-
|
|
414
|
-
|---------------------------------|----------------------------------------------------|
|
|
415
|
-
| `npm run slack:events:start` | Start the Slack events server |
|
|
416
|
-
| `npm run slack:events:stop` | Stop the Slack events server |
|
|
417
|
-
| `npm run slack:events:status` | Check Slack events server status |
|
|
326
|
+
When building new capabilities, decide where they belong:
|
|
418
327
|
|
|
419
|
-
|
|
328
|
+
| Push to `~/maestro` (global) | Keep agent-local |
|
|
329
|
+
|-----|-----|
|
|
330
|
+
| Role-agnostic tools any agent could use | Identity-specific configurations |
|
|
331
|
+
| Communication primitives | Domain tools only this role needs |
|
|
332
|
+
| Search/RAG capabilities | Custom MCP integrations for one agent |
|
|
333
|
+
| Operational patterns | Hardcoded contacts, channels, API keys |
|
|
334
|
+
| Infrastructure (audio, CDP, polling) | Agent-specific prompts and style |
|
|
335
|
+
| Document generation templates | Workflow overrides |
|
|
336
|
+
| Claude Code skills/plugins for dev experience | |
|
|
337
|
+
| Governance patterns | |
|
|
420
338
|
|
|
421
|
-
|
|
422
|
-
|---------------------------------|----------------------------------------------------|
|
|
423
|
-
| `npm run pdf:memo -- --input <file>` | Generate internal memo PDF |
|
|
424
|
-
| `npm run pdf:board-pack -- --input <file>` | Generate board pack with cover and TOC |
|
|
425
|
-
| `npm run pdf:letter -- --input <file>` | Generate corporate correspondence PDF |
|
|
426
|
-
| `npm run pdf:investor -- --input <file>` | Generate investor communication PDF |
|
|
339
|
+
**Decision rule:** Would another agent at Adaptic ever need this? **YES** → `~/maestro`. **NO** → agent repo only.
|
|
427
340
|
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
| Command | Purpose |
|
|
431
|
-
|---------------------------------|----------------------------------------------------|
|
|
432
|
-
| `npm run gen:illustration -- <slug>` | Generate a single illustration via Gemini |
|
|
433
|
-
| `npm run gen:video -- <slug>` | Generate a single video via Veo |
|
|
434
|
-
| `npm run gen:all-missing` | Batch generate all missing illustrations |
|
|
435
|
-
| `npm run gen:list` | List available prompt specs |
|
|
436
|
-
|
|
437
|
-
### Testing
|
|
438
|
-
|
|
439
|
-
| Command | Purpose |
|
|
440
|
-
|---------------------------------|----------------------------------------------------|
|
|
441
|
-
| `npm run test:daemon` | Run daemon unit and integration tests |
|
|
341
|
+
After pushing to maestro: bump version → commit → push. Agent repos update via `npm update @adaptic/maestro`.
|
|
442
342
|
|
|
443
343
|
---
|
|
444
344
|
|
|
@@ -447,45 +347,29 @@ The following infrastructure is shared across all agents and does not need per-a
|
|
|
447
347
|
- **Secrets management** -- All credentials via environment variables, never committed to the repository
|
|
448
348
|
- **Full audit trail** -- Every action, communication, and decision is logged to `logs/`
|
|
449
349
|
- **Approval policies** -- Outbound communications require appropriate approval levels based on risk classification
|
|
450
|
-
- **Emergency stop** --
|
|
350
|
+
- **Emergency stop** -- `npm run emergency-stop` halts all autonomous operations immediately
|
|
451
351
|
- **Default-deny** -- Unclassified actions are blocked; only explicitly permitted actions proceed
|
|
452
352
|
- **Rate limiting** -- Configurable limits on all communication channels (default: 3,000 sends/hour, 20,000/day)
|
|
453
353
|
- **Prompt injection defence** -- 5-layer defence system: identity lock, sender privilege model, message classification, content isolation, anomaly detection
|
|
454
354
|
- **Information barriers** -- Dynamic disclosure assessment prevents confidential information from crossing recipient boundaries
|
|
455
355
|
- **Session logging** -- Every agent session is logged with start time, actions taken, and outcomes
|
|
356
|
+
- **Communication governance** -- Pre-send audit hook gates all outbound Slack and Gmail; duplicate detection prevents replying to the same thread multiple times
|
|
456
357
|
|
|
457
358
|
Security policies are defined in `policies/` and `docs/governance/`.
|
|
458
359
|
|
|
459
360
|
---
|
|
460
361
|
|
|
461
|
-
##
|
|
462
|
-
|
|
463
|
-
| Symptom | Cause | Fix |
|
|
464
|
-
|-----------------------------------------------|----------------------------------------------|--------------------------------------------------------|
|
|
465
|
-
| `cb.apply is not a function` on every hook | Legacy standalone `npx` package installed | `npm uninstall -g npx` |
|
|
466
|
-
| `MODULE_NOT_FOUND` in poller logs | Launchd plists point to wrong directory | Re-run `npm run init-agent` |
|
|
467
|
-
| Hook errors on every tool call | Hook package not correctly installed | Check `~/.claude/settings.json` uses correct package |
|
|
468
|
-
| Launchd agent exit code 78 | Missing directories or config files | Run `npm run init-agent` to recreate |
|
|
469
|
-
| Poller rate limited | Too many Slack API calls | Increase `StartInterval` in the poller plist |
|
|
470
|
-
| Agent not responding to Slack messages | Bot token missing or incorrect | Verify `SLACK_BOT_TOKEN` in `.env` |
|
|
471
|
-
| Gmail polling returns no results | OAuth tokens expired | Refresh Gmail credentials and update `.env` |
|
|
472
|
-
| Daemon exits immediately on start | Missing `ANTHROPIC_API_KEY` | Ensure the key is set in `.env` or shell environment |
|
|
473
|
-
| PDF generation fails | Pandoc or MacTeX not installed | `brew install pandoc && brew install --cask mactex-no-gui` |
|
|
474
|
-
| Launchd agents not visible | Plists not loaded | Run `scripts/local-triggers/install-all.sh` |
|
|
475
|
-
| Memory/state files corrupted | Concurrent write conflict | Check session locks; restart daemon |
|
|
476
|
-
|
|
477
|
-
---
|
|
478
|
-
|
|
479
|
-
## Key Documents
|
|
362
|
+
## Key Documentation
|
|
480
363
|
|
|
481
|
-
- [
|
|
482
|
-
- [
|
|
483
|
-
- [
|
|
484
|
-
- [
|
|
485
|
-
- [
|
|
486
|
-
- [
|
|
487
|
-
- [
|
|
364
|
+
- [Agent Persona Setup Guide](docs/guides/agent-persona-setup.md) -- Detailed guide for configuring identity, operating charter, and behavioural policies
|
|
365
|
+
- [System Architecture](docs/architecture/system-architecture.md) -- Full system design and component overview
|
|
366
|
+
- [Agent Topology](docs/architecture/agent-topology.md) -- Sub-agent hierarchy and delegation model
|
|
367
|
+
- [Action Approval Model](docs/governance/action-approval-model.md) -- Communication governance and approval levels
|
|
368
|
+
- [Communications Policy](docs/governance/communications-policy.md) -- Voice modes, autonomy model, escalation rules
|
|
369
|
+
- [Mac Mini Bootstrap](docs/runbooks/mac-mini-bootstrap.md) -- Hardware setup and initial configuration
|
|
370
|
+
- [Perpetual Operations](docs/runbooks/perpetual-operations.md) -- Keeping the agent running 24/7
|
|
371
|
+
- [Recovery and Failover](docs/runbooks/recovery-and-failover.md) -- Disaster recovery procedures
|
|
488
372
|
|
|
489
373
|
---
|
|
490
374
|
|
|
491
|
-
Built
|
|
375
|
+
Built by [Adaptic.ai](https://adaptic.ai)
|