@cohortapp/agent-sdk 2.3.0

package/.claude/commands/init-maestro.md

@@ -0,0 +1,1187 @@
+# /init-maestro -- Configure a New Maestro Agent Identity
+
+> **Deprecated (manual fallback).** The primary way to configure an agent is now
+> the deterministic, resumable, self-verifying CLI wizard:
+>
+> ```
+> maestro setup
+> ```
+>
+> `maestro setup` validates and *verifies* itself (a shared completeness gate +
+> a live capability table), survives interruption (resume from a checkpoint),
+> and keeps `config/agent.json` as the single source of truth. Prefer it. This
+> LLM-driven command is kept only as a manual fallback for bespoke / interactive
+> setups; it is no longer advertised as the default path.
+
+You are running the Maestro initialization wizard. This is the single most important command in the system -- it configures this repository as a fully operational autonomous AI agent.
+
+This repo was created by `npx @cohortapp/agent-sdk create` and contains the Maestro framework. Your job is to bootstrap the system, give it an identity (a name, a role, responsibilities, and an operating style), configure external services, and bring it online. The wizard handles everything -- the user should not need to run any other setup commands.
+
+## Important Context
+
+- The central config file is `config/agent.ts` -- this is the single source of truth for all identity values
+- CLAUDE.md defines the agent's system prompt and operating instructions
+- There are 31 agent definitions in `agents/`, 13 trigger prompts in `schedules/triggers/`, and config files throughout the repo
+- The current agent identity must be fully replaced -- no references to the old agent should remain in critical files
+
+## Phase 0: System Bootstrap
+
+Before gathering identity information, ensure the system is ready. Run these checks silently and only report issues:
+
+### Step 1: Prerequisites
+
+Check that required tools are installed. Report any missing ones and offer to install them:
+
+```bash
+# Check each — report OK or missing
+node --version          # Required: >= 20.0.0
+npm --version           # Required
+claude --version        # Required for triggers
+jq --version            # Required for hooks
+```
+
+If Node.js or npm are missing, stop and tell the user to install them. If Claude CLI or jq are missing, warn but continue.
+
+### Step 2: Install dependencies
+
+```bash
+npm install
+```
+
+### Step 3: Create directories
+
+Ensure all operational directories exist (these should already exist from `maestro create`, but init-maestro may be re-run):
+
+```bash
+# Create any missing state/log/memory directories
+for dir in state/inbox/{slack,gmail,calendar,sms,whatsapp,internal,attachments,processed} \
+           state/{queues,dashboards,polling,handoffs,huddle,indexes,rag,sessions} \
+           state/{slack-responded,slack-thread-tracker,tmp} \
+           state/locks/outbound state/triggers/priority \
+           knowledge/{decisions,decisions/archive,entities,memory,sources,syntheses} \
+           memory/{interactions,indexes,templates} \
+           memory/profiles/{users,channels} \
+           memory/precedents/market-signals \
+           outputs/{briefs,drafts,memos,research,tasks,sessions} \
+           logs/{polling,workflows,sessions,audit,security,evolution,huddle,daemon} \
+           logs/{infra,monitor,phone,sms,whatsapp,email} \
+           self-optimization/scenarios tests; do
+  mkdir -p "$dir"
+done
+```
+
+### Step 4: Global Claude Code settings
+
+Install the global Claude Code settings to `~/.claude/settings.json`. Read the current content first — if it already exists and has substantive customisations, ask the user before overwriting. If it doesn't exist or is a default install, write it silently.
+
+The template is in `scripts/setup/init-agent.sh` (the heredoc in Step 4 of that script). Extract and write it.
+
+### Step 5: Environment file
+
+If `.env` doesn't exist, copy from `.env.example`:
+
+```bash
+cp .env.example .env
+```
+
+Tell the user: "I've created a .env file from the template. We'll fill in API keys during service configuration later."
+
+### Step 6: Report
+
+Only print a summary if there were issues. If everything passed silently, just say:
+
+```
+System bootstrap complete. Let's set up your agent.
+```
+
+Then proceed to Phase 1.
+
+## Phase 1: Gather Information
+
+Run a conversational wizard to collect the new agent's identity. Be friendly, encouraging, and clear. Ask questions in small groups (2-3 at a time), not as a wall of text. Confirm values as you go.
+
+### Step 1: Welcome and Name
+
+Start with a warm welcome, then ask for the basics:
+
+```
+Welcome to Maestro -- let's set up your new AI agent.
+
+First, the fundamentals:
+1. What is the agent's first name? (e.g., "Jacob", "Ravi", "Isla")
+2. What is the agent's last name? (e.g., "Chen", "Patel", "Roselli")
+3. What is their job title? (e.g., "Chief AI Scientist", "Head of Engineering")
+4. What is their email address? (e.g., jordan@example.com)
+```
+
+### Step 2: Role Archetype — Function × Altitude
+
+Maestro models an archetype on TWO orthogonal axes, which the archetype library
+(`~/maestro/archetypes/`, resolved by `~/maestro/lib/archetype.mjs`) composes
+into a full operating model. Ask the user to choose ONE of each:
+
+- **Function** — WHAT the agent owns: control towers, tools, skills, templates,
+  KPI categories, backlog streams.
+- **Altitude** — HOW senior / how it operates: autonomy bands, decision-rights
+  authority, escalation thresholds, KPI altitude, backlog granularity, tone.
+
+```
+First, the FUNCTION — what does this agent own?
+
+  1. executive-operator  — Chief of Staff / COO / GM / founder's operator (cross-functional)
+  2. technical-leader    — CTO / VP-Eng / Eng Manager: architecture, delivery, reliability, R&D
+  3. commercial-leader   — Sales / BD / IR / partnerships / revenue
+  4. compliance-officer  — Legal / regulatory / risk / licensing
+  5. product-leader      — product roadmap, UX, product-market fit, metrics
+  6. operations-leader   — ops / fund-ops / HR-ops / vendors / resilience
+
+Then, the ALTITUDE — how senior is this agent?
+
+  a. founder         — owner-level; broadest autonomy; sets direction, answers to the board
+  b. c-suite         — officer; org-wide function; board-facing
+  c. svp             — senior leader / Head-of; high autonomy within the domain
+  d. vp              — owns a sub-function; escalates strategic & cross-functional matters
+  e. senior-manager  — owns a team/workstream; hands-on; escalates more
+
+Which function (1–6) and which altitude (a–e)?
+```
+
+The seniority roles a user may have in mind decompose cleanly into cells:
+**Head of Operations** = `operations-leader × svp`; **Startup Founder** =
+`executive-operator × founder`; **VP of Engineering** = `technical-leader × vp`;
+a **CTO** = `technical-leader × c-suite`; a **Senior Compliance Manager** =
+`compliance-officer × senior-manager`.
+
+Record BOTH `function` and `altitude`. Do NOT hand-author towers, principles,
+autonomy, KPIs, or backlog streams — the library is the single source of truth;
+later phases resolve and render them. To see the available ids, run:
+`node -e "import('${HOME}/maestro/lib/archetype.mjs').then(m=>console.log('functions:',m.listFunctions(),'\naltitudes:',m.listAltitudes()))"`
+
+### Step 3: Responsibilities and Principles
+
+Ask for the agent's key responsibilities:
+
+```
+What are this agent's key responsibilities? List 3-7 bullet points describing
+what they do day-to-day.
+
+(If you'd like, I can generate defaults based on the archetype you chose.)
+```
+
+Operating principles are NO LONGER hand-entered here — they are resolved from the
+archetype library (base ⊕ function ⊕ altitude `operatingPrinciples`) and rendered
+into the charter by `generate-charter.mjs`. Only ask the user for principles if
+they want to ADD to or override the resolved defaults; otherwise proceed.
+
+### Step 4: Company Context
+
+The single most important input for role-true output — the charter, backlog,
+capabilities, cadences, and comms all build on it. Ask in small groups; offer
+the current `config/agent.ts` values as defaults. Populate `config/company.json`
+as you go (it is the company SoT).
+
+```
+Identity
+  1. Company name (trading), and legal name if different?
+  2. Website / primary domain?
+  3. Industry / sector?
+
+What the company does
+  4. One-line description — what does the company do?
+  5. A detailed overview — mission, what you build/sell, business model (a paragraph or more)?
+  6. Main products / services?
+
+Shape
+  7. Stage and size — startup / scaleup / growth / enterprise; approx headcount; funding stage?
+  8. Where do you operate — HQ plus key markets?
+  9. Are you regulated? Which regimes / regulators (if any)?
+
+Strategy & people
+  10. Top 3–5 strategic priorities right now?
+  11. Key people / leadership (names + roles) — especially this agent's principal and key stakeholders?
+  12. Main competitors / market position? (optional)
+```
+
+**Context sources — DO THESE; they are the difference between generic and role-true:**
+
+13. **GitHub repos on this machine.** Ask: "Are there repos on this machine I should analyse for
+    context? Give me the paths." For each, read the README, the package/manifest, the top-level
+    structure, and the recent commit log; extract products, stack, and themes. Record paths in
+    `config/company.json` → `repos`.
+14. **Company docs.** Ask the user to drop strategy/deck/overview/org-chart files into
+    `docs/company-context/` (see README § Company context), then read each and fold it into the
+    overview. Record the filenames in `config/company.json` → `contextDocs`.
+15. **Tools/systems** they use (Slack, GitHub, a CRM, Google Workspace, …) — informs the MCP/plugin
+    and channel configuration in Phase 2.5 / Phase 4.
+
+Write everything gathered to `config/company.json`, then synthesise + enrich the brief:
+
+```bash
+node scripts/setup/generate-company.mjs    # renders docs/company/overview.md from config/company.json
+```
+
+Enrich the `description` / `overview` and the generated overview doc from the repo + docs analysis.
+`config/company.json` is the SoT every downstream generator (charter, backlog, comms, and the CLAUDE.md
+"Company Context" section) reads, and `{{company.*}}` tokens in framework prompts resolve from it.
+
+### Step 5: Principal (Reporting Line)
+
+```
+Who does this agent report to?
+
+1. Principal's full name (e.g., "Alex Chen")
+2. Principal's title (e.g., "CEO")
+3. Principal's email (e.g., alex@example.com)
+```
+
+### Step 6: Machine and Timezone
+
+```
+A few deployment details:
+
+1. Mac mini hostname (e.g., "jacob-mini") -- defaults to {firstname}-mini
+2. Timezone (IANA format, e.g., "America/New_York") -- defaults to current value
+```
+
+### Step 7: Communication Style
+
+```
+How should this agent communicate?
+
+1. Default tone: formal / warm-professional / casual (default: warm-professional)
+2. Any custom voice modes beyond the standard four (agent, principal, internal, institutional)?
+```
+
+### Step 8: Optional Contact Details
+
+```
+Optional -- skip any you don't have yet:
+
+1. Agent phone number (E.164 format, e.g., +16282656712) -- for Twilio SMS/WhatsApp
+2. Agent Slack member ID (e.g., U097N5R0M7U) -- for mentions and DM routing
+```
+
+### Step 9: Confirmation
+
+Before executing, display a full summary of all gathered values and ask for confirmation:
+
+```
+Here is the complete configuration for the new agent:
+
+  Name:           {firstName} {lastName}
+  Title:          {title}
+  Email:          {email}
+  Archetype:      {function} × {altitude}
+  Company:        {company} ({companyDomain})
+  Principal:      {principalName}, {principalTitle}
+  Machine:        {machineName}
+  Timezone:       {timezone}
+  Tone:           {defaultTone}
+  Phone:          {phone || "not set"}
+  Slack ID:       {slackMemberId || "not set"}
+
+  Responsibilities:
+    - {each responsibility}
+
+  Operating Principles:
+    - {each principle}
+
+Does this look correct? (yes to proceed, or tell me what to change)
+```
+
+## Phase 2: Execute Changes
+
+Once the user confirms, deploy SEVEN sub-agents in parallel using the Agent tool with `run_in_background: true` (sub-agent 8 is retired — the operating model + capability surface are generated next, in Phase 2.5). Announce what you are doing:
+
+```
+Deploying 7 parallel agents to rewrite the repository identity. The operating model and capability surface are generated next (Phase 2.5). This will take a minute or two...
+```
+
+### Sub-agent 1: Update config/agent.ts
+
+**Instruction to sub-agent:** Read `config/agent.ts` and rewrite it with all the gathered values. Preserve the file structure, TypeScript types, JSDoc comments, and derived values section exactly. Only change the literal values in the `agent` object. Update:
+
+- firstName, lastName, fullName, title, **function** + **altitude** (the two archetype axes from Step 2; also set the derived legacy `archetype` = the function id for back-compat). Do NOT hand-author towers / principles / autonomy / KPIs / backlog — those resolve from the archetype library in Phase 2.5.
+- email, phone, slackMemberId
+- company, companyDomain, companyDescription
+- principal object (firstName, lastName, fullName, title, email -- keep slackMemberId as empty string unless provided)
+- machineName, launchdLabelPrefix (ai.maestro.{lowercase-firstname})
+- timezone
+- communication.defaultTone, communication.externalTone (set based on archetype -- compliance/institutional roles default to formal)
+- communication.voiceModes (update labels: "Agent's voice" -> "{firstName}'s voice", "Principal's voice" -> "{principalFirstName}'s voice")
+- responsibilities array
+- operatingPrinciples array
+
+### Sub-agent 2: Rewrite CLAUDE.md
+
+**Instruction to sub-agent:** Read `CLAUDE.md` and rewrite ONLY the identity-related sections. Keep all infrastructure sections intact (Repository Layout, Build & Test, Control Towers, Operating Modes, etc.).
+
+Sections to rewrite:
+- **## Identity** -- New agent name, title, role description. Write 2-3 sentences describing who this agent is and what they do.
+- **## Operating Principles** -- Replace with the new principles. Use the same numbered-list format.
+- **## Communication Rules** -- Adapt the autonomy model to the archetype. An executive-operator has broad autonomy; a compliance-officer escalates more. Rewrite the "sends autonomously" and "escalates" sections with the new agent's name and appropriate boundaries. Keep the Immediate Acknowledgement Rule, Document Sharing, and Logging subsections but replace the agent name throughout.
+- **## People (Key Leadership)** -- Update the "That's you" line to the new agent. Keep other people entries unless the user indicated changes.
+- **## Control Towers** -- Replace the 12 generic org-wide control towers with 8-10 towers scoped to the agent's specific role and domain. Each tower should reflect what this agent actually monitors and manages. Generate towers based on archetype:
+  - **executive-operator**: Keep the original 12 org-wide towers (they are appropriate for this archetype).
+  - **technical-leader**: Model/platform architecture, R&D strategy, engineering quality, platform delivery, infrastructure & scalability, security & compliance, performance & benchmarking, team growth, systems & automation, self-governance.
+  - **commercial-leader**: Pipeline management, partnership development, investor relations, market intelligence, revenue operations, competitive analysis, client success, commercial governance, systems & automation, self-governance.
+  - **compliance-officer**: Regulatory submissions, licence management, policy framework, audit readiness, risk register, cross-jurisdiction compliance, legal obligations, reporting & disclosure, systems & automation, self-governance.
+  - **product-leader**: Product roadmap, user research & insights, feature delivery, design system, product-market fit, metrics & analytics, cross-functional alignment, stakeholder communication, systems & automation, self-governance.
+  - **operations-leader**: Process efficiency, fund operations, vendor management, capacity planning, organisational design, SLA compliance, cost management, operational resilience, systems & automation, self-governance.
+  Each tower should have a brief description of what it monitors (same format as the original: `**Name** — description`).
+
+Replace ALL instances of the old agent's first name with the new agent's first name throughout the entire CLAUDE.md file. Be thorough -- check every section header, bullet point, and inline reference.
+
+Do NOT modify these sections (keep them exactly as they are, except for agent name substitution):
+- Repository Layout, Key Config Files, Brand Assets, PDF Generation, Visual Media Generation
+- Source Repositories, Hiring Management (unless archetype is not executive-operator, in which case trim or adapt)
+- Operational Infrastructure
+- Build & Test, Code Standards, Three Operating Modes, Parallel Execution
+- Agent Development, Workflow Development
+
+### Sub-agent 3: Update config files
+
+**Instruction to sub-agent:** Update these configuration files:
+
+1. **config/environment.yaml** -- Replace agent name, email, phone, directory paths, and scheduling references. Update timezone.
+
+2. **config/contacts.yaml** -- Update the principal's entry to match the new principal details. Keep other contacts unless the archetype suggests they are irrelevant. Add the new agent as a contact entry.
+
+3. **config/priorities.yaml** -- Generate 4-6 strategic priorities appropriate for the role archetype:
+   - executive-operator: operational excellence, communication cadence, strategic execution, hiring, institutional memory
+   - technical-leader: platform architecture, engineering quality, technical debt, R&D pipeline, delivery velocity
+   - commercial-leader: pipeline growth, partnership development, investor relations, market positioning, commercial operations
+   - compliance-officer: regulatory submissions, licence maintenance, policy framework, audit readiness, cross-jurisdiction compliance
+   - product-leader: product roadmap, user research, feature delivery, product-market fit, design system
+   - operations-leader: process automation, operational efficiency, fund operations, organisational design, vendor management
+
+### Sub-agent 4: Update package.json, scripts, and identity-baked content
+
+**Instruction to sub-agent:**
+
+1. **package.json** -- Update the `name` field to `maestro` (or keep current if already correct). Update `description` to reflect the new agent's role (e.g., "Autonomous AI Chief Scientist for your company").
+
+2. **Shell scripts** -- Search all files in `scripts/` for references to the old agent name (case-insensitive) and replace with the new agent name. Specifically target:
+   - Variable names like `SOPHIE_AI_DIR` -> `{UPPER_FIRSTNAME}_AI_DIR`
+   - Path references like `/Users/sophie/sophie-ai` -> `/Users/{lowercase-firstname}/{repoSlug}`
+   - LaunchD labels like `ai.maestro.sophie-` -> `ai.maestro.{lowercase-firstname}-`
+   - Pronouns: if the new agent's gender differs from the scaffolding template, update he/she/him/her/his/hers/himself/herself across system prompts, comments, and documentation. Be surgical — do NOT change pronouns inside generic regex patterns or third-party detection logic.
+
+3. **LaunchD plists** in `scripts/local-triggers/plists/` -- Update labels and paths in all `.plist` files.
+
+4. **Identity-baked content rewrites (CRITICAL — full overwrites, not grep-replace).** These files contain the agent's outbound identity (name, title, email, phone, signature) and MUST be fully rewritten with the new agent's values. Do not rely on grep-replace alone — read each file, then OVERWRITE it with content that uses these exact values:
+
+   - `firstName + lastName` (e.g., "Lucas Ferreira")
+   - `title` (e.g., "VP, Regulatory & Licensing")
+   - `email` (from config/agent.json → email)
+   - `phone` (use the spaced pretty form for human-facing display, the E.164 form for code)
+   - `companyName` (from **config/company.json → name** — never hardcode a company)
+   - `companyAddress` (the company's primary office from config/company.json; ask the user if absent)
+
+   **Files to rewrite:**
+
+   a. **`scripts/email-signature.html`** — The HTML signature appended to all outbound emails by `send-email.sh` and the Python send scripts. Must contain: name (bold, 14px), title (grey, 13px), the company logo (from config/company.json / brand assets — omit the logo line if none), email, phone, company address line, full confidentiality disclaimer footer. Pattern matches the template in `~/maestro/scripts/email-signature.html` — use placeholders {{AGENT_NAME}}, {{AGENT_TITLE}}, {{AGENT_EMAIL}}, {{AGENT_PHONE}}, {{COMPANY_ADDRESS}} and substitute them.
+
+   b. **`scripts/email-signature-principal.html`** — Principal's signature block (used by `send-email-as-principal.py` or equivalent send-as-principal scripts). Update with the principal's values: `principal.fullName`, `principal.title`, `principal.email`. If the principal doesn't have a phone in config/agent.ts, omit the phone line.
+
+   c. **`scripts/send-email.sh`** — Hardcoded `From:` header and inline signature fallback. Update both. The From header should be in the form `"{fullName}" <{email}>` (from config/agent.json).
+
+   d. **`scripts/send-email-threaded.py`** — `USER`, `From` header construction, inline signature, argparse description. All must reflect the new agent.
+
+   e. **`scripts/send-email-with-attachment.py`** — Same as above.
+
+   f. **`scripts/pdf-generation/build-document.mjs`** — Default `author` value (used in PDF metadata) and the help text describing the default. Set to the new agent's full name.
+
+   g. **`scripts/pdf-generation/templates/memo.latex`** — Footer line "Prepared by ... Chief of Staff" — replace with "Prepared by {fullName}, {title}".
+
+   h. **`scripts/daemon/responder.mjs` `FALLBACK_PREAMBLE`** — System prompt that introduces the agent to Claude. Identity intro line must reference the new agent. Preserve the operational rules.
+
+   i. **`scripts/daemon/prompt-builder.mjs` `FALLBACK_PREAMBLE`** — Same treatment.
+
+   j. **`scripts/daemon/classifier.mjs` `SYSTEM_PROMPT`** — Identity intro line. Preserve everything else.
+
+   k. **`scripts/huddle/huddle-server.mjs` `HUDDLE_SYSTEM_PROMPT`** — Voice agent identity line.
+
+   l. **`scripts/spawn-session.sh`** — Sub-session bootstrap prompt that names the agent.
+
+   m. **`scripts/continuous-monitor.sh`** — Channel monitor agent prompt.
+
+   n. **`scripts/llm_email_dedup.py`, `scripts/comms-monitor.sh`, `scripts/archive-email.sh`, `scripts/poller/gmail-poller.mjs`, `scripts/poller/imap-client.mjs`** — Hardcoded `LUCAS_EMAIL`/`USER`/`gmail_user` constants. Set to the new agent's email.
+
+   o. **`scripts/{firstname}-inbox-poller.py`** — Rename file from `sophie-inbox-poller.py` (or current scaffolding name) to `{firstname}-inbox-poller.py`. Update internal `LUCAS_EMAIL` constant. Update any plist references to the new filename.
+
+   p. **`scripts/rag-indexer.py`, `scripts/user-context-search.py`** — Author docstring at the top. Set to the new agent's full name.
+
+   q. **`scripts/validate-outbound.py`** — Test/regex references to the placeholder agent name "Robin Hayes" or `lookup_entity("Robin Hayes")`. Replace with the new agent's full name. Leave the generic third-party pronoun regex (around line 1007) UNCHANGED — it's a detector, not an identity reference.
+
+   **Verification step (identity AND company):** After rewrites, run `grep -rniE "robin|alex|jordan|northwind" scripts/ config/ agents/ policies/ 2>&1` and confirm NO placeholder identity remains — neither the placeholder persona (Robin / Alex) NOR the placeholder company ("Northwind"). Everything must be the new agent + the company from `config/company.json`. Report any remaining matches you cannot safely auto-resolve so the main agent can decide.
+
+### Sub-agent 5: Update agent definitions
+
+**Instruction to sub-agent:**
+
+1. **Rename the core agent directory**: `agents/sophie-chief-of-staff` -> `agents/{lowercase-firstname}-{role-slug}` (e.g., `agents/jacob-chief-ai-scientist`). Derive the role slug from the title by lowercasing and hyphenating.
+
+2. **Rewrite the core agent's agent.md**: Update the name, title, mandate, and responsibilities to match the new agent identity.
+
+3. **Review all 31 agent directories** in `agents/`. For each:
+   - If the agent is generic infrastructure (inbound-dispatcher, session-spawner, workflow-automation, browser-operator, desktop-operator, slack-operator, gmail-operator, whatsapp-operator, calendar-ops, decision-log, communications, pmo-execution): Keep it, but replace any references to the old agent name in its agent.md.
+   - If the agent is role-specific to the old identity and relevant to the new role: Adapt it (e.g., ceo-briefing might become cto-briefing for a technical-leader).
+   - If the agent is role-specific and NOT relevant: Leave a note in the file that it needs review, but do not delete it.
+
+### Sub-agent 6: Update triggers and workflows
+
+**Instruction to sub-agent:**
+
+1. **Trigger prompts** in `schedules/triggers/` -- Read each `.md` file and replace all references to the old agent name with the new agent name. Adapt the trigger content where the old agent's role is referenced (e.g., "Robin's morning brief" -> "{firstName}'s morning brief").
+
+2. **Workflow configs** in `workflows/` -- Update any agent name references.
+
+3. Keep the cadence structure intact (morning brief, midday sweep, evening wrap, backlog executor, etc.) -- these are generic patterns that work for any agent.
+
+### Sub-agent 7: Update README and miscellaneous
+
+**Instruction to sub-agent:**
+
+1. **README.md** -- Rewrite the repository README to reflect the new agent's identity. Keep the structure but update the agent name, role description, and any old-agent-specific language.
+
+2. **Any other files** that reference the old agent by name in `docs/`, `teams/`, or root-level markdown files. Do a thorough search and replace.
+
+### Sub-agent 8: (retired)
+
+Capability-surface generation — tools, **Claude Code skills**, **workflows**,
+the **expansive 40–60 role sub-agents**, **MCP servers / plugins**, and the
+**event→capability usage map** — is no longer a shallow parallel sub-agent. It is
+performed comprehensively in **Phase 2.5, Step 5** below, driven by the archetype
+library's capability pack + the gathered context pack. Skip this slot.
+
+## Phase 2.5: Generate the Operating Model & Capability Surface
+
+After the parallel rewrite has written `config/agent.json` with `{ function, altitude }`,
+generate the agent's complete operating model and capability surface FROM THE
+ARCHETYPE LIBRARY (`~/maestro/archetypes/`, resolved by `lib/archetype.mjs`) —
+deterministic skeletons + LLM enrichment for company-specific substance. Run in order;
+everything generated is shown to the user for review before it goes live.
+
+### Step 1 — Resolve & validate the archetype
+```bash
+node scripts/setup/init-archetype.mjs
+```
+Normalises `{ function, altitude }`, resolves + validates the profile. If it fails, stop and fix.
+
+### Step 2 — Gather the strategic context pack (hybrid interview + research)
+Conduct a focused interview (ask only what you cannot infer): the mandate the
+principal is giving this agent; company stage + top 3–5 priorities; key people /
+stakeholders + relationships; any docs/repos to read. THEN research the company /
+market / comparable-role norms (web + available MCP + RAG over provided docs).
+Write the structured result to `state/init/context-pack.json` — every generator below consumes it.
+
+### Step 3 — Operating charter
+```bash
+node scripts/setup/generate-charter.mjs   # renders config/operating-charter.md from the profile
+```
+Then ENRICH the company-specific slots (mandate, named stakeholders, KPI targets, first-90)
+from the context pack, and generate a branded PDF via the pdf pipeline.
+
+### Step 4 — Seeded WBS backlog
+```bash
+node scripts/setup/generate-backlog.mjs   # state/backlog/wbs.yaml + state/queues/backlog.yaml + config/priorities.yaml
+```
+Then ENRICH the WBS epics/tasks with company-specific work from the context pack and
+re-run to re-materialise, so the backlog-executor has real, role-true work on the first tick.
+
+### Step 5 — Capability surface (COMPREHENSIVE — this is what lets the agent ACT)
+```bash
+node scripts/setup/generate-capability.mjs   # renders the full roster + skills + workflows + event-routing + mcp declaration
+```
+This resolves the archetype's **capability pack** from the library and renders skeletons for
+ALL of the below. THEN ENRICH each artifact with company-specific substance — a parallel
+workflow LLM-tailors the 40–60 agent mandates, skill procedures, and workflow steps to the
+context pack. The generator produces (and you enrich):
+
+  a. **Sub-agents (expansive — target 40–60 role-tailored, plus the standard defaults).**
+     Compose the full sub-agent roster:
+     - KEEP the STANDARD default sub-agents that ship from `~/maestro/agents/` (generic
+       infrastructure every agent needs: inbox-processor, session-spawner, dispatcher,
+       channel operators, decision-log, pmo-execution, …);
+     - PLUS generate a LARGE role-tailored set (target **40–60**) from the function's
+       `agentTeams` capability pack — one sub-agent per role across the function's teams,
+       with breadth/depth scaled by altitude (founder/C-suite field more delegated teams;
+       senior-manager fewer, more hands-on). Each sub-agent gets a full `agents/<id>/agent.md`
+       (mandate, tools, model tier, towers served, decision rights), tailored to the company.
+  b. **Skills.** Generate the role's Claude Code skills under `plugins/agent-skills/skills/`
+     (the procedures the agent runs) from the skill pack + responsibilities; write `plugin.json`.
+  c. **Workflows.** Generate the role's workflow definitions under `workflows/`
+     (daily/weekly/monthly/quarterly/continuous/event-driven) from the workflow pack.
+  d. **MCP servers / plugins.** Install + configure the MCP servers and Claude Code plugins
+     the role needs (from the `mcpServers` pack — e.g. technical-leader → GitHub/code MCP;
+     commercial-leader → CRM MCP; compliance-officer → filings/registry MCP). Wire into `.claude`.
+  e. **Usage mapping (event → capability).** Write `config/event-routing.yaml` mapping incoming
+     task/request/event types → the skill, workflow, or sub-agent that handles them, so the
+     daemon routes work to the right capability.
+
+### Step 6 — Acceptance gate
+```bash
+npx @cohortapp/agent-sdk doctor
+```
+Confirm the operating-model gate passes: archetype resolves; charter present & enriched
+(no `TBD` / `{{}}`); priorities populated; backlog seeded (≥5 open items); capability
+surface generated (sub-agents, skills, workflows, MCP, routing). The agent is not "done"
+until it can actually work.
+
+## Phase 3: Machine Configuration
+
+After identity rewriting completes, generate and install the launchd plists (these need the agent name from Phase 1).
+
+The plists generated here use the **cadence bus architecture** (maestro 1.8+): scheduled cadence ticks no longer spawn a fresh Claude Code session per tick. Instead, launchd invokes `scripts/cadence/enqueue-cadence-tick.mjs` (≈10 ms, no Claude) which drops a JSON event onto `state/cadence-bus/inbox/`. The persistent daemon (started by the `*-daemon` plist) drains the bus and decides — per cadence — whether to handle the tick inline or escalate to a managed sub-session.
+
+### Step 1: Generate launchd plists
+
+```bash
+bash scripts/local-triggers/generate-plists.sh
+```
+
+This reads `config/agent.ts` to get the agent's first name and generates all 13 launchd plist files with correct labels and paths. Every plist carries the `maestro-plist-arch: cadence-bus v1` marker.
+
+### Step 2: Install launchd agents
+
+```bash
+LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
+mkdir -p "$LAUNCH_AGENTS_DIR"
+for plist in scripts/local-triggers/plists/*.plist; do
+    PLIST_NAME=$(basename "$plist")
+    LABEL=$(basename "$plist" .plist)
+    DST="$LAUNCH_AGENTS_DIR/$PLIST_NAME"
+    launchctl unload "$DST" 2>/dev/null || true
+    cp "$plist" "$DST"
+    launchctl load "$DST"
+done
+```
+
+Report how many triggers were installed.
+
+### Step 2b: Cadence bus smoke test (verifies end-to-end delivery)
+
+```bash
+# Enqueue a heartbeat tick and confirm the daemon drained it.
+node scripts/cadence/enqueue-cadence-tick.mjs cadence-bus-heartbeat --source=init-maestro
+sleep 4
+node scripts/cadence/cadence-status.mjs
+```
+
+The heartbeat must show `depth.inbox: 0` and a fresh `health.ts` within the last minute. If not, check `logs/cadence-bus/<date>.jsonl` and `logs/daemon/launchd-stderr.log`.
+
+### Step 3: macOS headless configuration (optional)
+
+Offer to configure the Mac mini for headless 24/7 operation:
+
+```
+Would you like to configure the Mac mini for headless operation?
+
+This will (requires sudo):
+  1. Enable auto-login (no password on reboot)
+  2. Disable sleep/standby/screen saver
+  3. Configure Parsec for remote desktop access
+  4. Set up Slack with CDP for huddle automation
+  5. Install virtual audio (BlackHole) for voice
+
+Run macOS configuration? (yes/no)
+```
+
+If yes, run:
+```bash
+sudo ./scripts/setup/configure-macos.sh
+```
+
+### Step 4: External SSD configuration (REQUIRED if /Volumes/{name}-SSD is mounted)
+
+The maestro daemon and its launchd-spawned trigger jobs should write all runtime data — Claude Code per-cwd temp dirs, daemon logs, state, outputs, memory, knowledge — to an external SSD when one is available. This keeps the internal disk free for macOS and avoids wear on the system disk.
+
+**Two macOS hurdles need to be cleared before the SSD redirect actually works for launchd-spawned processes:**
+
+#### 4a. Enable file ownership on the volume
+
+By default, external volumes have Owners disabled, which makes file permissions advisory rather than enforced. The daemon's wrapper writes per-agent log files, and that requires real owners.
+
+Detect the SSD and enable owners:
+
+```bash
+SSD_VOLUME=""
+for v in /Volumes/*-SSD /Volumes/*SSD* /Volumes/maestro-data; do
+  if [ -d "$v" ] && [ "$v" != "/Volumes/Macintosh HD" ]; then SSD_VOLUME="$v"; break; fi
+done
+
+if [ -n "$SSD_VOLUME" ]; then
+  # Tell the user we found an SSD and need sudo to enable owners
+  echo "Found external SSD at $SSD_VOLUME — enabling file ownership."
+  echo "Please run this in your terminal (it needs sudo):"
+  echo "  sudo diskutil enableOwnership \"$SSD_VOLUME\""
+  echo "Reply 'done' when complete."
+fi
+```
+
+Wait for the user to confirm. Then verify:
+
+```bash
+diskutil info "$SSD_VOLUME" | grep "Owners" | grep -q "Enabled" && echo "OK" || echo "FAIL"
+```
+
+#### 4b. Grant Full Disk Access to bash and node (TCC)
+
+Even with owners enabled, **macOS TCC blocks launchd-spawned processes from writing to /Volumes/ unless the binary has Full Disk Access**. This is the single most common cause of "Operation not permitted" errors when you run a daemon under launchd that tries to write to an external volume.
+
+You cannot grant Full Disk Access programmatically without disabling SIP (which is unsafe). The user must do this via System Settings UI:
+
+```
+1. Open System Settings → Privacy & Security → Full Disk Access
+2. Click the + button
+3. Press Cmd+Shift+G to "Go to Folder", then enter:
+     /bin/bash
+   Press Enter, select 'bash', click Open
+4. Click + again, then:
+     /usr/bin/node     OR     ~/.nvm/versions/node/v24.11.1/bin/node
+   (whichever node binary the wrapper uses)
+5. Make sure both toggles are ON
+
+The toggles take effect immediately. No restart needed.
+```
+
+After the user confirms, test that launchd can now write to the SSD:
+
+```bash
+cat > /tmp/ssd-tcc-test.plist <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>ai.maestro.ssd-tcc-test</string>
+    <key>ProgramArguments</key><array>
+        <string>/bin/bash</string><string>-c</string>
+        <string>touch "$SSD_VOLUME/.tcc-test" && echo "ok=$?" > /tmp/ssd-tcc-result.log || echo "fail=$?" > /tmp/ssd-tcc-result.log</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+</dict>
+</plist>
+EOF
+launchctl load /tmp/ssd-tcc-test.plist
+sleep 2
+cat /tmp/ssd-tcc-result.log
+launchctl unload /tmp/ssd-tcc-test.plist
+rm -f "$SSD_VOLUME/.tcc-test"
+```
+
+If you see `ok=0`, TCC is configured correctly and the daemon can use the SSD. If you see `fail=1`, TCC is still blocking — repeat the System Settings step and make sure the toggles are ON.
+
+#### 4c. Set up SSD layout and symlinks
+
+```bash
+AGENT_NAME="$(grep firstName config/agent.ts | head -1 | sed 's/.*[\x27\"]\([a-zA-Z]*\)[\x27\"].*/\1/' | tr A-Z a-z)"
+SSD_AGENT_ROOT="$SSD_VOLUME/maestro/$AGENT_NAME"
+mkdir -p "$SSD_AGENT_ROOT"/{state,outputs,memory,knowledge,claude-tmp,logs,tmp}
+
+# Symlink runtime data dirs from the agent repo to the SSD.
+# IMPORTANT: do NOT symlink logs/ — launchd's StandardErrorPath cannot follow
+# symlinks to external volumes. The daemon's wrapper writes its own log file
+# directly to the SSD via shell redirection (see launchd-wrapper.sh).
+for d in state outputs memory knowledge; do
+  if [ -d "$d" ] && [ ! -L "$d" ]; then
+    rsync -a "$d/" "$SSD_AGENT_ROOT/$d/"
+    rm -rf "$d"
+    ln -sfn "$SSD_AGENT_ROOT/$d" "$d"
+  fi
+done
+
+# Create internal-disk logs/ as a real directory (NOT a symlink)
+mkdir -p logs/{daemon,polling,workflows,sessions,audit,security,evolution,huddle,infra,monitor,phone,sms,whatsapp,email,launchd,cloudflared}
+```
+
+The wrapper scripts (`scripts/daemon/launchd-wrapper.sh` and `launchd-wrapper-generic.sh`) handle the runtime side: they detect the SSD, set `CLAUDE_CODE_TMPDIR`, and redirect daemon stdout/stderr to a log file on the SSD. They gracefully fall back to internal-disk paths if the SSD isn't writable (e.g. if TCC isn't granted yet).
+
+#### 4d. Verify
+
+```bash
+# Daemon should now be writing to the SSD log file
+launchctl unload ~/Library/LaunchAgents/ai.maestro.${AGENT_NAME}-daemon.plist
+launchctl load   ~/Library/LaunchAgents/ai.maestro.${AGENT_NAME}-daemon.plist
+sleep 4
+ls -la "$SSD_AGENT_ROOT/logs/daemon/" | tail -5
+ls -la "$SSD_AGENT_ROOT/state/inbox/" | tail -5
+```
+
+You should see the daemon log file growing and inbox directories populating. If you don't, repeat steps 4a–4b (most often it's TCC).
+
+## Phase 4: Autonomous Service Configuration
+
+This phase sets up all third-party integrations **autonomously**. Use Playwright MCP for web-based setup (Slack API portal, Twilio Console, Google Account, ElevenLabs, Deepgram) and Bash for local scripts. Only ask the user for input when genuinely required (existing credentials, 2FA codes, payment authorisation).
+
+**Tooling:**
+- **Playwright MCP** (`mcp__plugin_playwright_playwright__browser_navigate`, `browser_click`, `browser_fill_form`, `browser_snapshot`, etc.) for all web UI interactions
+- **Bash** for local scripts, CLI tools, file writes, service starts
+- If a web UI requires authentication the agent doesn't have, ask the user to log in via `! open <url>` then resume automation once they confirm they're logged in
+
+**Implementation guides**: Each service has a detailed guide in `docs/guides/`. Follow the guide's steps exactly during setup. Reference the guide's troubleshooting section if something fails.
+
+### Step 0: Ask what services this agent needs
+
+```
+Which services does this agent need? Select all that apply:
+
+  [1] Slack (messaging, events, typing indicators)
+  [2] Gmail (email send/receive via IMAP/SMTP)
+  [3] Twilio SMS (inbound/outbound text messaging)
+  [4] Twilio WhatsApp (inbound/outbound WhatsApp)
+  [5] Voice / Huddle (Deepgram STT + ElevenLabs TTS)
+  [6] Cloudflare Tunnels (public webhook URLs — needed if 3/4/5 selected)
+  [7] Gemini / Veo (AI image + video generation)
+  [8] All of the above
+  [9] Minimal (Slack + Gmail only)
+
+Which? (comma-separated numbers, or "all" / "minimal")
+```
+
+Then execute each selected service. For services with existing credentials, ask the user to paste them. For new accounts, drive the web UI via Playwright.
+
+### Step 1: Slack — per `docs/guides/slack-setup.md`
+
+**If user has existing tokens:** ask for xoxb- and xoxp- tokens, write to `.env`.
+
+**If creating new app — execute via Playwright:**
+
+1. `browser_navigate` to `https://api.slack.com/apps`
+2. `browser_snapshot` to check auth — if not logged in, ask user: `! open https://api.slack.com/apps` and log in, then resume
+3. Click "Create New App" → "From scratch"
+4. `browser_fill_form` with app name "Maestro - {AgentFirstName}", select workspace
+5. Navigate to OAuth & Permissions
+6. Add Bot Token Scopes: `chat:write`, `chat:write.customize`, `channels:read`, `channels:history`, `groups:read`, `groups:history`, `im:read`, `im:history`, `im:write`, `users:read`, `users:read.email`, `reactions:read`, `reactions:write`, `files:read`, `files:write`
+7. Add User Token Scopes: `channels:history`, `groups:history`, `im:history`, `search:read`, `chat:write`
+8. Click "Install to Workspace" → authorize
+9. Extract Bot User OAuth Token (xoxb-...) and User OAuth Token (xoxp-...) from the page
+10. Navigate to Basic Information → extract Signing Secret
+11. Write `SLACK_BOT_TOKEN`, `SLACK_USER_TOKEN`, `SLACK_SIGNING_SECRET` to `.env`
+
+**Verify:**
+```bash
+source .env && curl -s -H "Authorization: Bearer $SLACK_USER_TOKEN" https://slack.com/api/auth.test | python3 -c "import json,sys; d=json.load(sys.stdin); print('Slack OK: ' + d.get('user','') if d.get('ok') else 'FAIL: ' + d.get('error',''))"
+```
+
+### Step 2: Gmail — per `docs/guides/email-setup.md`
+
+Gmail app passwords require 2FA interaction — ask user:
+```
+Gmail setup: Please generate an app password:
+  1. Go to https://myaccount.google.com/apppasswords (or I can open it for you)
+  2. Generate a password for "Mail" on "Mac"
+  3. Paste the 16-character password here:
+```
+
+After receiving the password:
+1. Write `GMAIL_APP_PASSWORD` to `.env`
+2. If monitoring principal's inbox, ask for secondary password → `SECONDARY_GMAIL_APP_PASSWORD`
+3. Install msmtp: `brew install msmtp 2>/dev/null || true`
+4. Write `~/.msmtprc` per guide § 1.4, set `chmod 600 ~/.msmtprc`
+
+**Verify:**
+```bash
+source .env && python3 -c "import imaplib,os; m=imaplib.IMAP4_SSL('imap.gmail.com'); m.login('${AGENT_EMAIL}', os.environ['GMAIL_APP_PASSWORD']); print('IMAP OK'); m.logout()"
+```
+
+### Step 3: Twilio (SMS + WhatsApp) — per `docs/guides/voice-sms-setup.md`, `docs/guides/whatsapp-setup.md`
+
+**If user has credentials:** ask for Account SID, Auth Token, Phone Number → write to `.env`.
+
+**If creating new account — execute via Playwright:**
+
+1. `browser_navigate` to `https://www.twilio.com/console`
+2. `browser_snapshot` — if not logged in, ask user to log in via `! open https://www.twilio.com/login`
+3. Once authenticated, extract Account SID and Auth Token from Console dashboard
+4. Navigate to Phone Numbers → Buy a Number → search for SMS+Voice number in preferred country
+5. **Ask user to confirm the purchase** (payment authorisation)
+6. After purchase, extract phone number (E.164) and Phone SID
+7. Write `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER`, `TWILIO_PHONE_SID` to `.env`
+
+**If SMS selected:** Configure webhook per guide:
+1. Navigate to Twilio Console → Phone Numbers → Active Numbers → select number
+2. Under Messaging → "A message comes in" → Webhook POST → `{tunnel_url}/sms`
+3. Enable geo-permissions: navigate to Messaging → Settings → Geo Permissions → enable needed countries
+
+**If WhatsApp selected:** Configure sandbox per guide:
+1. `browser_navigate` to `https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn`
+2. Under Sandbox Settings → set webhook URL to `{tunnel_url}/whatsapp` POST
+3. Set Status Callback to `{tunnel_url}/whatsapp/status` POST
+4. Note and report the sandbox join keyword to the user
+5. Write `WHATSAPP_MODE=sandbox`, `WHATSAPP_PORT=3002` to `.env`
+
+### Step 4: Webhook Relay (Railway) — per `docs/guides/webhook-relay-setup.md`
+
+**This is the canonical pattern. Do NOT use Cloudflare Tunnels for new agents** — they were a transitional approach. Each agent gets its own Railway-deployed webhook relay. The local Mac mini polls the relay every 5 seconds and never needs an inbound tunnel.
+
+The relay handles:
+- `POST /slack/events` — Slack Events API (HMAC verified via SLACK_SIGNING_SECRET)
+- `POST /sms` — Twilio SMS inbound (HMAC verified via TWILIO_AUTH_TOKEN)
+- `POST /whatsapp` — Twilio WhatsApp inbound
+- `POST /whatsapp/status` — Twilio WhatsApp delivery status
+- `GET /events`, `/sms/messages`, `/whatsapp/messages` — drained by Mac mini poller
+- `GET /health` — service status
+
+**Source code** is already in the repo at `services/webhook-relay/` (copied from the maestro framework). It's a ~250-line Node 20 HTTP server, no dependencies, deployable straight to Railway.
+
+**Prerequisites:**
+- Railway CLI installed: `brew install railway 2>/dev/null || true`
+- User must run `railway login` once (interactive — opens browser)
+- User must have admin rights in the company's Railway workspace (e.g., "Northwind")
+
+**Deploy steps (run from the agent's repo root):**
+
+```bash
+# 1. Create the project in the company's Railway workspace
+cd services/webhook-relay
+railway init --name {firstname-lower}-webhook-relay --workspace {Company}
+
+# 2. Add the service and deploy
+railway up --service {firstname-lower}-webhook-relay --detach
+
+# 3. Generate a public domain
+railway domain --service {firstname-lower}-webhook-relay
+# Captures: https://{firstname-lower}-webhook-relay-production.up.railway.app
+
+# 4. Set env vars (must include the agent's own SLACK_SIGNING_SECRET and TWILIO_AUTH_TOKEN)
+source ../../.env
+railway variables --service {firstname-lower}-webhook-relay \
+  --set "SLACK_SIGNING_SECRET=$SLACK_SIGNING_SECRET" \
+  --set "TWILIO_AUTH_TOKEN=$TWILIO_AUTH_TOKEN" \
+  --set "PUBLIC_HOSTNAME={firstname-lower}-webhook-relay-production.up.railway.app" \
+  --set "BUFFER_TTL_MS=600000" \
+  --set "MAX_BUFFER_SIZE=1000"
+
+# 5. Trigger redeploy so the running container picks up the new env vars
+railway up --service {firstname-lower}-webhook-relay --detach
+
+# 6. Wait until /health returns slack_signature: true and twilio_signature: true
+for i in 1 2 3 4 5 6 7 8 9 10 11 12; do
+  RESP=$(curl -sf -m 5 https://{firstname-lower}-webhook-relay-production.up.railway.app/health)
+  if echo "$RESP" | grep -q '"slack_signature":true' && echo "$RESP" | grep -q '"twilio_signature":true'; then
+    echo "Relay live with signature verification"
+    break
+  fi
+  sleep 10
+done
+```
+
+**Configure external services to point at the relay:**
+
+```bash
+# Twilio SMS webhook (uses Twilio API directly, no UI)
+RELAY_URL="https://{firstname-lower}-webhook-relay-production.up.railway.app"
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$TWILIO_PHONE_SID.json" \
+  --data-urlencode "SmsUrl=$RELAY_URL/sms" --data-urlencode "SmsMethod=POST"
+```
+
+For **Slack Events Subscription**: use Playwright to update via the App Manifest editor (more reliable than the events page). Navigate to `https://app.slack.com/app-settings/{TEAM_ID}/{APP_ID}/app-manifest`, read the JSON via the CodeMirror instance, add this block to `settings`, and click Save Changes:
+
+```json
+"event_subscriptions": {
+  "request_url": "https://{firstname-lower}-webhook-relay-production.up.railway.app/slack/events",
+  "bot_events": [
+    "app_mention",
+    "message.channels",
+    "message.groups",
+    "message.im",
+    "message.mpim"
+  ]
+}
+```
+
+After save, navigate to the Event Subscriptions page and check for the yellow "Click here to verify" button — click it. Then **reinstall the app** at `https://api.slack.com/apps/{APP_ID}/install-on-team` so the new event scopes activate.
+
+For **Twilio WhatsApp sandbox**: this requires a per-agent Twilio sub-account (see Phase 4 Step 3.5). Cannot share with other agents because the sandbox webhook is account-wide.
+
+**Update local poll script:**
+
+```bash
+# Edit scripts/poll-slack-events.sh and scripts/comms-monitor.sh
+# Set EVENTS_URL to https://{firstname-lower}-webhook-relay-production.up.railway.app/events
+```
+
+**Install the launchd job that polls the relay every 5 seconds:**
+
+```bash
+cat > scripts/local-triggers/plists/ai.maestro.{firstname-lower}-poll-relay.plist <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>ai.maestro.{firstname-lower}-poll-relay</string>
+    <key>ProgramArguments</key><array>
+        <string>/bin/bash</string>
+        <string>{REPO_ROOT}/scripts/poll-slack-events.sh</string>
+    </array>
+    <key>WorkingDirectory</key><string>{REPO_ROOT}</string>
+    <key>StartInterval</key><integer>5</integer>
+    <key>RunAtLoad</key><true/>
+    <key>StandardOutPath</key><string>{REPO_ROOT}/logs/polling/poll-relay-stdout.log</string>
+    <key>StandardErrorPath</key><string>{REPO_ROOT}/logs/polling/poll-relay-stderr.log</string>
+</dict>
+</plist>
+EOF
+cp scripts/local-triggers/plists/ai.maestro.{firstname-lower}-poll-relay.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/ai.maestro.{firstname-lower}-poll-relay.plist
+```
+
+**Add the relay URL block to `.env`:**
+
+```bash
+cat >> .env <<EOF
+
+# ─── RAILWAY WEBHOOK RELAY ──────────────────────────────────────────────────
+WEBHOOK_RELAY_URL=https://{firstname-lower}-webhook-relay-production.up.railway.app
+WEBHOOK_RELAY_SLACK_EVENTS=https://{firstname-lower}-webhook-relay-production.up.railway.app/slack/events
+WEBHOOK_RELAY_SMS_INBOUND=https://{firstname-lower}-webhook-relay-production.up.railway.app/sms
+WEBHOOK_RELAY_WHATSAPP_INBOUND=https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp
+WEBHOOK_RELAY_POLL_EVENTS=https://{firstname-lower}-webhook-relay-production.up.railway.app/events
+WEBHOOK_RELAY_POLL_SMS=https://{firstname-lower}-webhook-relay-production.up.railway.app/sms/messages
+WEBHOOK_RELAY_POLL_WHATSAPP=https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp/messages
+EOF
+```
+
+**End-to-end test:**
+
+1. Have Lucas (or any user) send a Slack message to a channel where the bot is a member, OR @-mention the bot in a public channel
+2. Within ~5 seconds, the local Mac mini should fetch the buffered event and write a YAML file to `state/inbox/slack/`
+3. The inbox processor picks it up and routes it
+4. Verify `railway logs --service {firstname-lower}-webhook-relay` shows `[slack] buffered ...`
+
+### Step 5: Voice / Huddle — per `docs/guides/voice-sms-setup.md` § 5
+
+**API keys** — if user has them, paste directly. Otherwise, drive signup via Playwright:
+
+1. **ElevenLabs**: `browser_navigate` to `https://elevenlabs.io/` → sign up or log in → navigate to Profile → API Keys → extract key
+2. **Deepgram**: `browser_navigate` to `https://console.deepgram.com/` → sign up or log in → navigate to API Keys → create and extract key
+3. Write `ELEVENLABS_API_KEY`, `DEEPGRAM_API_KEY` to `.env`
+
+**Local setup:**
+```bash
+bash scripts/huddle/setup-audio.sh          # Install BlackHole, sox, verify
+cd scripts/huddle && npm install && cd ../.. # Install huddle Node.js deps
+bash scripts/huddle/launch-slack.sh          # Launch Slack with CDP
+```
+
+### Step 6: Media Generation — per `docs/guides/media-generation-setup.md`
+
+1. If user has Gemini key, paste directly. Otherwise: `browser_navigate` to `https://aistudio.google.com/apikey` → extract or create key
+2. Write `GEMINI_API_KEY` to `.env`
+
+### Step 7: Additional Keys
+
+Prompt for any remaining optional keys: `OPENAI_API_KEY`, `GREPTILE_API_KEY`. Write to `.env` or skip.
+
+## Phase 5: Subsystem Implementation & Verification
+
+After credentials are configured, this phase **autonomously implements and verifies** every subsystem by following each implementation guide's setup and test steps. This ensures the agent is actually operational — not just configured with API keys.
+
+**Execution:** Spawn parallel background agents for independent subsystems. Report results as a verification matrix. Do NOT proceed to Phase 6 until all selected subsystems pass (or user explicitly accepts failures).
+
+Tell the user:
+```
+Credentials configured. Now I'll set up and verify each subsystem end-to-end.
+This runs autonomously — I'll report results when complete.
+```
+
+### 5.1 Outbound Governance — `docs/guides/outbound-governance-setup.md`
+
+Verify FIRST — all send scripts depend on this.
+
+1. Verify hooks registered in `.claude/settings.json` (PreToolUse for block-mcp-slack-send and pre-send-audit, PostToolUse for post-action-log, Stop for session-end-log)
+2. `chmod +x scripts/hooks/*.sh`
+3. Test dedup: generate key → acquire → verify CLAIMED → cleanup
+4. Test validate-outbound.py runs without crash
+5. Test disclosure_assessment.py runs without crash
+
+### 5.2 Email — `docs/guides/email-setup.md`
+
+1. Test IMAP connectivity (if GMAIL_APP_PASSWORD set)
+2. Verify msmtp config exists: `test -f ~/.msmtprc`
+3. Verify email signature files: `test -f scripts/email-signature.html`
+4. `chmod +x scripts/send-email.sh`
+
+### 5.3 Slack — `docs/guides/slack-setup.md`
+
+1. Test token: `curl -s -H "Authorization: Bearer $SLACK_USER_TOKEN" https://slack.com/api/auth.test`
+2. Verify slack-send.sh uses xoxp- token (not xoxb-)
+3. Verify typing indicator exists: `test -f scripts/slack-typing.mjs`
+4. Verify MCP block hook: `test -f scripts/hooks/block-mcp-slack-send.sh`
+
+### 5.4 SMS & WhatsApp — `docs/guides/voice-sms-setup.md`, `docs/guides/whatsapp-setup.md`
+
+1. Verify `config/caller-id-map.yaml` exists and has principal with `access_level: ceo`
+2. Start SMS handler, verify health: `curl http://localhost:3001/health`
+3. Start WhatsApp handler, verify health: `curl http://localhost:3002/health`
+4. `chmod +x scripts/send-sms.sh scripts/send-whatsapp.sh`
+
+### 5.5 Voice / Huddle — `docs/guides/voice-sms-setup.md` § 5
+
+1. `bash scripts/huddle/setup-audio.sh --check`
+2. Verify huddle deps: `test -d scripts/huddle/node_modules`
+3. Verify Deepgram + ElevenLabs keys are set
+
+### 5.6 Poller & Daemon — `docs/guides/poller-daemon-setup.md`
+
+1. Run poller once: `timeout 30 node scripts/poller/index.mjs`
+2. Verify daemon entry point: `head -5 scripts/daemon/maestro-daemon.mjs`
+3. Verify plists generated: `ls scripts/local-triggers/plists/*.plist | wc -l`
+4. Test emergency stop: `touch .emergency-stop` → run trigger → verify blocked → `rm .emergency-stop`
+5. Verify watchdog: `bash scripts/watchdog/memory-watchdog.sh --check`
+
+### 5.7 RAG & Context — `docs/guides/rag-context-setup.md`
+
+1. Build search index: `python3 scripts/rag-indexer.py --full`
+2. Verify docs indexed: `python3 scripts/rag-indexer.py --stats`
+3. Test search: `python3 scripts/user-context-search.py --user unknown --query "adaptic" --max-results 1`
+4. Run test suite if available: `bash scripts/test-rag-search.sh`
+
+### 5.8 PDF Generation — `docs/guides/pdf-generation-setup.md`
+
+1. `pandoc --version`
+2. Check XeLaTeX: `xelatex --version 2>/dev/null || ~/Library/TinyTeX/bin/universal-darwin/xelatex --version 2>/dev/null`
+3. Generate test PDF:
+   ```bash
+   echo "# Test\nGenerated by init-maestro." > /tmp/init-test.md
+   node scripts/pdf-generation/build-document.mjs --input /tmp/init-test.md --template memo --output /tmp/init-test.pdf
+   test -f /tmp/init-test.pdf && echo "PDF OK"
+   rm -f /tmp/init-test.md /tmp/init-test.pdf
+   ```
+
+### 5.9 Media Generation — `docs/guides/media-generation-setup.md`
+
+1. Verify Gemini key set
+2. List specs: `node scripts/media-generation/generate-assets.mjs --list`
+3. Verify client loads: `node -e "import('./scripts/media-generation/gemini-image-client.mjs').then(() => console.log('OK'))"`
+
+### 5.10 Verification Summary
+
+Print results:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  SUBSYSTEM VERIFICATION RESULTS                              ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Outbound Governance   ✅ PASS    hooks, dedup, validation   ║
+║  Email (Gmail)         ✅ PASS    IMAP, SMTP, signatures     ║
+║  Slack                 ✅ PASS    tokens, send, typing        ║
+║  SMS (Twilio)          ✅ PASS    handler, send, caller-id   ║
+║  WhatsApp              ⏭️ SKIP    not selected                ║
+║  Voice / Huddle        ⏭️ SKIP    not selected                ║
+║  Poller & Daemon       ✅ PASS    poller, plists, watchdog    ║
+║  RAG & Context         ✅ PASS    index built, search works   ║
+║  PDF Generation        ✅ PASS    pandoc + xelatex OK         ║
+║  Media Generation      ⏭️ SKIP    not selected                ║
+║                                                              ║
+║  Overall: 7/7 selected subsystems PASS                       ║
+║                                                              ║
+║  Guides: docs/guides/ (for detailed testing & troubleshoot)  ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+If any subsystem FAILS: diagnose via the guide's troubleshooting section, attempt one fix, re-run check. If still failing, report failure with specific error and ask user whether to continue or abort.
+
+## Phase 6: Generate Agent README
+
+Generate a comprehensive README.md for this agent's repository. This describes THIS specific agent, not the Maestro framework.
+
+Include all of the following sections populated with gathered values:
+
+1. **Title and tagline**: `{fullName} — Autonomous {title} for {company}`
+2. **Who is {firstName}?**: 3-4 sentence description of role, reporting line, autonomy level
+3. **Capabilities**: 8-12 bullet points based on archetype and responsibilities
+4. **Architecture**: 5-tier model with role-specific domain controllers
+5. **Subsystem Status**: Include the Phase 5 verification matrix
+6. **Operating Modes**: Reactive (polling), Scheduled (triggers), Proactive (backlog)
+7. **Commands**: npm run daemon, healthcheck, emergency-stop, resume, upgrade
+8. **Implementation Guides**: Table linking to all 10 guides in `docs/guides/`
+9. **Communication Governance**: Based on archetype autonomy model
+
+Write to repo root as `README.md`.
+
+## Phase 7: Create GitHub Repository
+
+Ask the user whether they want to create a GitHub repo:
+
+```
+Would you like me to create a GitHub repository for this agent? (yes/no)
+```
+
+If yes: ask for org/username (default: adapticai), repo name (default: {repoName}), visibility (default: private). Then:
+
+```bash
+gh repo create {org}/{repoName} --private --description "{fullName} — Autonomous {title} for {company} (powered by Maestro)"
+git remote add origin https://github.com/{org}/{repoName}.git
+git add -A
+git commit -m "Initialize {fullName} as {title} — powered by @cohortapp/agent-sdk"
+git push -u origin main
+```
+
+## Phase 8: Final Verification
+
+### Step 1: Grep for stale agent references
+
+Search critical files for the old agent name AND the placeholder company "Northwind" (case-insensitive): CLAUDE.md, config/agent.ts, config/*.{yaml,json}, package.json, schedules/triggers/*.md, agents/*/agent.md, policies/*. Everything must be the new agent + the company from config/company.json. Fix any stragglers.
+
+### Step 2: Validate config/agent.ts
+
+Read and verify valid TypeScript, all fields populated with new values.
+
+### Step 3: Health check
+
+```bash
+npm run healthcheck
+```
+
+### Step 4: Completion Summary
+
+```
+═══════════════════════════════════════════════════════════════
+  MAESTRO INITIALIZATION COMPLETE
+═══════════════════════════════════════════════════════════════
+
+  Agent:       {fullName}, {title}
+  Archetype:   {archetype}
+  Company:     {company}
+  Principal:   {principalName}
+  Machine:     {machineName}
+
+  Identity (Phase 2):       ✅ 8 parallel agents rewrote repo
+  Infrastructure (Phase 3): ✅ {N} launchd triggers installed
+  Services (Phase 4):       ✅ {list configured services}
+  Subsystems (Phase 5):     {include verification matrix}
+  README (Phase 6):         ✅ Agent-specific README generated
+  GitHub (Phase 7):         {repo URL or "skipped"}
+
+  ─────────────────────────────────────────────────────────
+
+  Next steps:
+    1. Start the daemon:  npm run daemon
+    2. Monitor logs:      tail -f logs/daemon/$(date +%Y-%m-%d)-sessions.jsonl
+    3. Test a message:    Send a Slack DM to {firstName}
+
+  Implementation guides:    docs/guides/
+═══════════════════════════════════════════════════════════════
+```
+
+## Guidelines for the Wizard
+
+- Be warm and professional. This is a setup experience, not an interrogation.
+- Offer sensible defaults wherever possible.
+- Always confirm before executing identity changes (Phase 2). Service configuration (Phase 4) and verification (Phase 5) execute autonomously after the user selects services.
+- Sub-agents MUST run in parallel (`run_in_background: true`).
+- **Autonomous execution is the default.** Only ask for input when you cannot proceed without it (credentials, 2FA, payment). Everything else — web UI navigation, script execution, file writes, verification — you do yourself.
+- **Use Playwright MCP** for web UIs: Slack API portal, Twilio Console, Google Account, ElevenLabs, Deepgram, Gemini.
+- **Use Bash** for local operations: scripts, installs, service starts, tests.
+- If Playwright fails (auth wall, CAPTCHA), fall back to asking user to do that specific step via `! open <url>`, then resume.
+
+## Error Handling
+
+- If a sub-agent fails, report which one and offer to retry.
+- If a Phase 5 subsystem verification fails, diagnose using the guide's troubleshooting section, attempt one fix, re-run. If still failing, report with specific error and ask whether to continue.
+- If user aborts mid-wizard, exit cleanly.
+- If config/agent.ts unreadable, suggest `npx @cohortapp/agent-sdk create` first.