@cohortapp/agent-sdk 2.3.0

package/docs/company-context/README.md

@@ -0,0 +1,40 @@
+# Company context
+
+Drop documents here that describe **your company**. During `/init-maestro` (and
+whenever you re-run the generators), the agent reads everything in this folder
+and folds it into the generated **operating charter, seeded backlog,
+communication profile**, and the company brief (`config/company.json` +
+`docs/company/overview.md`). This is how the agent's output becomes *role- and
+company-true* instead of generic.
+
+Markdown is ideal — the agent reads it directly. PDFs/decks work too if you also
+add a short `.md` summary alongside. The more concrete and current the material,
+the better the output.
+
+## What to add (add whichever you have)
+
+| File | What to put in it |
+| --- | --- |
+| `company-overview.md` | What the company does, mission, history, business model, stage/size |
+| `strategy.md` | Current strategy, top priorities / OKRs, the next 1–4 quarters |
+| `products.md` | Products / services, positioning, roadmap themes |
+| `org-chart.md` | Leadership, teams, who owns what — and **this agent's principal + key stakeholders** |
+| `market-and-competitors.md` | Market, segments, main competitors, differentiation |
+| `customers.md` | Key customers / segments, ideal-customer profile, notable accounts |
+| `regulatory.md` | Jurisdictions, regulators, licences, compliance obligations |
+| `brand-and-voice.md` | Tone, do's/don'ts, terminology, approved messaging |
+| `key-relationships.md` | Investors, board, advisors, partners, vendors |
+| `systems.md` | Tools / systems (Slack, GitHub, a CRM, Google Workspace, …) the agent should know |
+
+You can also point init at **GitHub repos on the machine** — it will read each
+repo's README, manifest, structure, and recent commits for product/technical
+context. Have the paths ready when the wizard asks.
+
+## Tips
+
+- Be factual and specific — names, numbers, dates, ownership, jurisdictions.
+- Keep it current; stale context produces stale output. Re-run init or the
+  generators (`scripts/setup/generate-company.mjs`, then the charter/backlog/comms
+  generators) after material changes.
+- Treat this as the agent's **private brief** — keep sensitive material to what
+  the agent genuinely needs, and do not commit secrets.

package/docs/guides/agent-persona-setup.md

@@ -0,0 +1,600 @@
+# Agent Persona Setup Guide
+
+How to customise a Maestro agent's identity, operating charter, and behavioural policies when deploying a new autonomous agent on a dedicated Mac mini.
+
+## 1. Overview
+
+A Maestro agent's persona is defined across roughly a dozen files. Each serves a distinct purpose:
+
+| File | Purpose |
+|------|---------|
+| `config/agent.ts` | Structured identity data: name, title, email, phone, archetype, schedule |
+| `CLAUDE.md` | Behavioural charter: who the agent IS, how it thinks, what it can do |
+| `config/contacts.yaml` | Key relationships and communication permissions |
+| `config/priorities.yaml` | Strategic focus areas and milestones |
+| `config/environment.yaml` | System-level settings: paths, scheduling, secrets |
+| `agents/` | Specialist sub-agents the orchestrator can delegate to |
+| `workflows/` | Cadence definitions (daily, weekly, monthly) |
+| `schedules/triggers/` | Prompt templates for each scheduled execution |
+| `memory/profiles/` | Relationship memory for people and channels |
+| `policies/` | Action classification, information barriers, prompt injection defence |
+
+**The relationship between `config/agent.ts` and `CLAUDE.md`**: `agent.ts` holds the structured data (name, email, archetype, schedule). `CLAUDE.md` is the prose charter that tells the LLM who it is and how to behave. They must stay in sync. When the `/init-maestro` command runs, it reads `agent.ts` and generates much of `CLAUDE.md` automatically. Manual fine-tuning of `CLAUDE.md` is where the real persona crafting happens.
+
+## 2. config/agent.ts -- The Identity Source of Truth
+
+This TypeScript file is the single import point for every script, trigger, and workflow that needs the agent's name, email, or operational parameters.
+
+### Field Reference
+
+**Identity fields:**
+
+- `firstName` / `lastName` / `fullName` -- Used in greetings, signatures, Slack profile, and all outbound communications.
+- `title` -- The agent's job title. Appears in email signatures, the CLAUDE.md identity section, and document headers.
+- `archetype` -- Determines default operating principles, communication style, and which Control Towers are most relevant. See the archetype table below.
+- `email` -- The agent's primary email address. Must be a real mailbox the agent can send from.
+- `phone` -- E.164 format. Used for Twilio SMS, voice, and WhatsApp integration.
+- `slackMemberId` -- The agent's Slack user ID (not username). Required for DM routing and mentions.
+
+**Organisation fields:**
+
+- `company` / `companyDomain` / `companyDescription` -- Appear in CLAUDE.md, email signatures, and document branding.
+
+**Reporting line:**
+
+- `principal` -- The person this agent reports to and acts on behalf of. Contains their name, title, email, and Slack ID. This person receives escalations and morning briefs.
+
+**Machine and deployment:**
+
+- `machineName` -- Hostname of the dedicated Mac mini (e.g. `jordan-mini`).
+- `repoSlug` -- The basename of the repo directory. Used to compute `~/maestro` or `~/jordan-ai`.
+- `launchdLabelPrefix` -- Prefix for all launchd daemon labels (e.g. `ai.adaptic.jordan`).
+
+**Operational parameters:**
+
+- `timezone` -- IANA timezone. All scheduled triggers use this.
+- `locale` -- For date/number formatting in documents and messages.
+- `schedule` -- Daily execution times for morning brief, comms triage, evening wrap, and overnight monitoring. Adjust these to the principal's working day.
+
+**Communication style:**
+
+- `communication.defaultTone` -- `'formal'`, `'warm-professional'`, or `'casual'`. Affects Slack messages and internal emails.
+- `communication.externalTone` -- Tone for partners, candidates, regulators. Usually `'formal'`.
+- `communication.voiceModes` -- The voices available to this agent (agent's own voice, principal's voice, internal notes, institutional).
+
+**Responsibilities and principles:**
+
+- `responsibilities` -- 3-7 bullet points describing what this agent does. Injected into CLAUDE.md.
+- `operatingPrinciples` -- Behavioural rules that guide all decision-making.
+
+### Archetype Defaults
+
+The `archetype` field affects which defaults `/init-maestro` selects:
+
+| Archetype | Example Role | Default Tone | Key Control Towers |
+|-----------|-------------|--------------|-------------------|
+| `executive-operator` | Chief of Staff, COO | warm-professional | All 12 |
+| `technical-leader` | CTO, Head of Engineering | casual | 1, 3, 6, 11, 12 |
+| `commercial-leader` | Head of Sales, IR, BD | formal | 1, 7, 8, 9, 12 |
+| `compliance-officer` | Head of Compliance | formal | 1, 5, 10, 12 |
+| `product-leader` | Head of Product | warm-professional | 1, 3, 6, 7, 12 |
+| `operations-leader` | Head of Ops, HR | warm-professional | 1, 2, 4, 5, 12 |
+
+### Derived Values
+
+The file exports computed values that scripts consume:
+
+- `AGENT_UPPER` -- Uppercase first name for shell variable prefixes (e.g. `JORDAN`).
+- `AGENT_LOWER` -- Lowercase first name for file paths (e.g. `jordan`).
+- `REPO_DIR` -- Full repo path (e.g. `~/maestro`).
+- `EMAIL_SIGNATURE` -- Formatted signature line.
+
+### Generating agent.json for Shell Scripts
+
+Shell scripts cannot import TypeScript. Run the following to generate a JSON snapshot:
+
+```bash
+npx tsx -e "import { agent } from './config/agent.ts'; console.log(JSON.stringify(agent, null, 2))" > config/agent.json
+```
+
+Scripts then read values with `jq`:
+
+```bash
+AGENT_NAME=$(jq -r '.firstName' config/agent.json)
+```
+
+## 3. CLAUDE.md -- The Agent's Operating Charter
+
+CLAUDE.md is the most important file in the repo. It is loaded into every Claude session as the system prompt. Every section must be tailored to the agent's role.
+
+### Identity Section
+
+The opening paragraph establishes who the agent is. It must be specific, not generic.
+
+**Executive operator (Chief of Staff):**
+```markdown
+You are **Jordan Lee**, Chief of Staff to Alex Chen, CEO of Northwind.
+You operate as the autonomous executive command layer -- perpetually running on a
+dedicated Mac mini as the institutional executive office for the company.
+```
+
+**Technical leader (Head of Engineering):**
+```markdown
+You are **Jordan Lee**, Head of Engineering at Northwind. You operate as the
+autonomous engineering leadership layer -- perpetually running on a dedicated Mac
+mini, maintaining code quality, delivery velocity, and technical architecture
+across all platform repositories.
+```
+
+**Compliance officer (Head of Compliance):**
+```markdown
+You are **Jordan Lee**, Head of Compliance at Northwind. You operate as the
+autonomous regulatory and compliance layer -- perpetually running on a dedicated
+Mac mini, monitoring regulatory obligations across 7 jurisdictions and ensuring
+the firm meets every licensing condition and filing deadline.
+```
+
+### Company Context Section
+
+This section contains business facts. It does not change between agents unless the agent serves a different entity (e.g. an agent for a subsidiary or sister company would have different company context). Keep the corporate structure, jurisdictions, and key business facts identical across all of your organisation's agents.
+
+### Operating Principles Section
+
+Principles must reflect the agent's domain. A chief of staff prioritises follow-through; an engineer prioritises correctness; a compliance officer prioritises risk avoidance.
+
+**Executive operator:**
+1. Follow-through over brilliance -- Track every commitment until it closes
+2. Concise over comprehensive -- Sharp recommendations, not exhaustive reports
+3. Bias to action -- Act decisively on operational matters
+4. Audit everything -- Every action is logged
+
+**Technical leader:**
+1. Correctness over speed -- Never ship code that has not been tested
+2. Simplicity over cleverness -- Prefer readable, maintainable solutions
+3. Measure before optimising -- Profile first, then act on data
+4. Document decisions -- Every architectural choice gets an ADR
+
+**Commercial leader:**
+1. Relationship first -- Maintain warmth and trust in every interaction
+2. Pipeline over perfection -- Keep deals moving; iterate proposals live
+3. Data-driven positioning -- Back every pitch with evidence
+4. Protect the brand -- Every communication reflects institutional quality
+
+### Communication Rules Section
+
+This section defines voice modes, the autonomy model, and escalation rules. The structure is consistent across agents, but the specifics change significantly.
+
+**Voice modes** -- Most agents have four: their own voice, the principal's voice, internal notes, and institutional. A compliance officer may add a fifth `regulatory` voice for regulator correspondence.
+
+**Autonomy model** -- Define exactly what the agent can send without approval and what must be escalated. A Chief of Staff has broad autonomy. A Head of Engineering has narrower communication scope (mostly internal). A compliance officer may need approval for any external regulatory correspondence.
+
+**Escalation rules** -- Always define these as two lists: what the agent handles autonomously, and what gets escalated to the principal.
+
+### Repository Layout and Key Config Files
+
+These sections are structural references. They stay the same across agents unless the agent has unique config files (e.g. `config/trading-parameters.yaml` for a quant engineer).
+
+### People Section
+
+Update the "That's you" line to reference the new agent:
+
+```markdown
+- **Jordan Lee** -- That's you. Head of Engineering (AI-operated)
+```
+
+Keep all other leadership entries. Every agent needs awareness of the org chart.
+
+### Operational Infrastructure (Control Towers)
+
+The 12 Control Towers are the monitoring and governance framework. Not all are relevant to every agent.
+
+**Universal (keep for all agents):**
+- CT1: Strategy and Decisions
+- CT2: Executive Office and Follow-Through
+- CT3: Operating Cadence and PMO
+- CT11: Systems, Automation, and Institutional Memory
+- CT12: Self-Governance
+
+**Role-specific:**
+- CT4 (People/Hiring) -- Keep for executive-operator, operations-leader
+- CT5 (Culture/Standards) -- Keep for executive-operator, operations-leader
+- CT6 (Product/Engineering) -- Keep for technical-leader, product-leader
+- CT7 (Commercial/Market) -- Keep for commercial-leader
+- CT8 (Board/Advisors) -- Keep for executive-operator, commercial-leader
+- CT9 (Capital/Finance) -- Keep for executive-operator, commercial-leader
+- CT10 (Legal/Compliance) -- Keep for compliance-officer, executive-operator
+
+To remove a Control Tower, delete its section from CLAUDE.md and remove or disable its corresponding dashboard in `state/dashboards/`. To add a custom tower, follow the same format: name, dashboards it reads, metrics it tracks, and cadence.
+
+### Operating Modes Section
+
+The three modes (Reactive, Scheduled, Proactive) are universal. Every agent polls for events, runs scheduled workflows, and executes backlog items. Adjust the specific cadence:
+
+- A Chief of Staff runs morning briefs at 06:00 and evening wraps at 18:00.
+- A Head of Engineering might run a build-health check at 08:00 and a PR review sweep at 14:00.
+- A compliance officer might run a regulatory-calendar check at 07:00 and an obligation-status sweep at 16:00.
+
+## 4. config/contacts.yaml -- Key Relationships
+
+This file defines who the agent communicates with and what approval level each contact requires.
+
+### Contact Structure
+
+Each contact entry includes:
+
+```yaml
+- name: Alex Chen
+  role: CEO / Founder
+  organisation: Northwind
+  classification: internal-ceo
+  channels:
+    slack: true
+    email: true
+    whatsapp: true
+  communication_rules:
+    inbound: always-surface
+    outbound: internal-pre-approved
+  notes: Primary principal. All strategic decisions route through the CEO.
+```
+
+### Classification Types
+
+Classifications determine voice and approval rules:
+
+| Classification | Outbound Approval | Voice | Risk |
+|---------------|-------------------|-------|------|
+| `internal-ceo` | pre-approved | agent | low |
+| `internal-executive` | pre-approved | agent | low |
+| `internal-team` | pre-approved | agent | low |
+| `investor` | explicit | principal-draft | high |
+| `board-member` | explicit | principal-draft | critical |
+| `regulator` | explicit | institutional | critical |
+| `partner` | explicit | agent | medium |
+| `unknown` | blocked | none | critical |
+
+### Adapting for Different Roles
+
+- **Head of Engineering**: Contacts are mostly internal (engineering team, product leads, DevOps). Few external contacts. Most outbound is pre-approved.
+- **Head of Compliance**: Contacts include the regulators in your jurisdictions. All regulator comms require explicit approval. Add specific contacts for each regulatory body.
+- **Head of Sales/BD**: Heavy external contact list (prospects, LPs, advisors). Add classifications for `prospect` and `warm-intro` with appropriate approval levels.
+
+The `principal` defined in `config/agent.ts` should always appear in contacts with `internal-ceo` classification and `always-surface` inbound rules.
+
+## 5. config/priorities.yaml -- Strategic Focus
+
+Priorities define what the agent works on. They drive queue management, backlog execution, and drift detection.
+
+### Priority Structure
+
+```yaml
+- id: P1
+  name: Regulatory Submission
+  status: active
+  urgency: critical
+  owner: alex-chen
+  operational_lead: regulatory-compliance
+  description: >
+    Close 12 critical technical gaps and submit the licence application.
+  milestones:
+    - name: Complete GAP-001 to GAP-005
+      target_date: 2026-04-30
+      status: in_progress
+```
+
+### Examples by Role
+
+**Head of Engineering:**
+```yaml
+- id: P1
+  name: Engine Test Coverage
+  urgency: critical
+  operational_lead: engineering-coordination
+  milestones:
+    - name: Unit test coverage above 80%
+      target_date: 2026-05-31
+```
+
+**Head of Compliance:**
+```yaml
+- id: P1
+  name: Licence Application
+  urgency: critical
+  operational_lead: regulatory-compliance
+  milestones:
+    - name: Complete remediation of 12 technical gaps
+      target_date: 2026-06-30
+```
+
+**Head of Sales:**
+```yaml
+- id: P1
+  name: LP Pipeline Development
+  urgency: high
+  operational_lead: capital-raising
+  milestones:
+    - name: Build qualified pipeline of 20 LP prospects
+      target_date: 2026-05-15
+```
+
+Each priority's `operational_lead` should reference an agent definition in the `agents/` directory.
+
+## 6. config/environment.yaml -- System Configuration
+
+### Fields to Update
+
+```yaml
+system:
+  operator_persona: Jordan Lee              # Agent's full name
+  operator_role: Head of Engineering        # Agent's title
+  company: Northwind                        # Usually unchanged
+  ceo: Alex Chen                            # The principal
+
+paths:
+  agent_home: ~/jordan-ai                    # Repo directory
+
+phone:
+  agent: "+1XXXXXXXXXX"                     # Agent's Twilio number (rename the key)
+
+email:
+  agent: agent@example.com                  # Agent's email (rename the key)
+
+scheduling:
+  timezone: Asia/Dubai                      # Agent's working timezone
+  morning_brief: "08:00"                    # Adjust to role needs
+  comms_triage: ["09:00", "13:00", "17:00"]
+  evening_wrap: "18:00"
+```
+
+### Fields to Leave Alone
+
+- `machine` -- Populated during machine setup.
+- `desktop_control` -- App control profiles are consistent across agents.
+- `rate_limits` -- Global safety limits apply to all agents.
+- `secrets` -- Environment variable names are standard.
+
+## 7. agents/ -- Specialist Agent Definitions
+
+The repo contains 31 specialist agents. Some are universal infrastructure; others are domain-specific.
+
+### Universal Agents (keep for all roles)
+
+These handle core infrastructure every agent needs:
+
+- `inbound-dispatcher` -- Routes incoming messages
+- `session-spawner` -- Manages session lifecycle
+- `workflow-automation` -- Executes workflow steps
+- `desktop-operator` -- macOS desktop interaction
+- `slack-operator` -- Slack API operations
+- `gmail-operator` -- Gmail operations
+- `calendar-ops` -- Calendar management
+- `browser-operator` -- Web browsing
+- `whatsapp-operator` -- WhatsApp messaging
+- `communications` -- Outbound comms governance
+- `decision-log` -- Decision tracking
+- `pmo-execution` -- Project management
+- `ceo-briefing` -- Principal brief production
+- `strategic-planning` -- Strategy analysis
+
+### Role-Specific Agents
+
+Modify, replace, or remove these based on the agent's domain:
+
+- `regulatory-compliance` -- Only for compliance-focused agents
+- `capital-raising` -- Only for commercial or executive agents
+- `corporate-development` -- Only for M&A-focused agents
+- `rollup-target-sourcing` -- Only for corp dev agents
+- `hiring-org-design` -- Only for HR or executive agents
+- `engineering-coordination` -- Only for technical agents
+- `platform-architecture` -- Only for technical agents
+- `fund-ops` -- Only for operations agents
+
+### Creating a New Agent
+
+Each agent lives in `agents/{agent-name}/agent.md` with YAML frontmatter:
+
+```markdown
+---
+name: security-auditor
+description: Reviews code for security vulnerabilities and compliance with security policies.
+model: claude-sonnet-4-20250514
+tools: ["Read", "Grep", "Glob", "Bash"]
+---
+
+# Security Auditor
+
+## Mandate
+Review all code changes for security vulnerabilities...
+
+## Responsibilities
+1. Static analysis of PRs for OWASP Top 10 issues
+2. Dependency vulnerability scanning
+...
+
+## Boundaries
+- Never modify production code directly
+- Escalate critical vulnerabilities to Head of Engineering immediately
+
+## Escalation Rules
+- Critical CVE: immediate escalation
+- High severity: flag in daily brief
+```
+
+Choose the model based on task complexity: `claude-opus-4-6` for complex reasoning, `claude-sonnet-4-20250514` for general tasks, `claude-haiku-4-20250414` for simple/high-volume work.
+
+## 8. workflows/ -- Operational Cadence
+
+Workflows are organised by cadence: `daily/`, `weekly/`, `monthly/`, `quarterly/`, `continuous/`, `event-driven/`.
+
+### Universal Workflows
+
+These apply to all agents:
+
+- `daily/morning-brief.yaml` -- Daily brief to principal
+- `daily/evening-wrap.yaml` -- End-of-day summary and queue cleanup
+- `daily/midday-sweep.yaml` -- SLA check and loop closure
+- `continuous/backlog-executor.yaml` -- The proactive execution loop
+- `continuous/inbox-processor.yaml` -- Inbound message routing
+- `session-protocol.md` -- Start/end session procedures
+
+### Customisable Workflows
+
+Adapt or replace these for the agent's domain:
+
+- `weekly/hiring.yaml` -- Replace with engineering sprint review for a technical agent
+- `weekly/strategic-memo.yaml` -- Keep but adjust focus areas
+- `weekly/engineering-health.yaml` -- Only relevant for technical agents
+- `monthly/board-pack.yaml` -- Only relevant for executive or compliance agents
+
+### Adding a Workflow
+
+Create a YAML file in the appropriate cadence directory:
+
+```yaml
+name: weekly-security-scan
+cadence: weekly
+day: tuesday
+time: "09:00"
+agent: security-auditor
+steps:
+  - name: scan_repos
+    action: run_agent
+    agent: security-auditor
+    depends_on: []
+  - name: report
+    action: send_slack
+    channel: "#security"
+    depends_on: [scan_repos]
+on_failure: escalate_to_principal
+```
+
+## 9. schedules/triggers/ -- Scheduled Prompts
+
+Trigger files are Markdown prompts that launchd executes on a schedule. Each trigger starts with the agent's identity line.
+
+### What to Change
+
+Line 1 of every trigger must match the agent:
+
+```markdown
+You are Jordan Lee, Head of Engineering at Northwind.
+```
+
+The rest of each trigger references queues, dashboards, and workflows. The queue names and dashboard paths are consistent across agents. Adjust the content focus:
+
+- `daily-morning-brief.md` -- Change channel names to scan (e.g. `#engineering` instead of `#exec-office`).
+- `backlog-executor.md` -- The structure stays identical; it reads all queues.
+- `weekly-engineering-health.md` -- Remove or replace for non-technical agents.
+- `meeting-prep.md` -- Universal; only the recipient changes.
+
+### Trigger Files to Review
+
+| Trigger | Universal | Notes |
+|---------|-----------|-------|
+| `daily-morning-brief.md` | Yes | Update identity line and channel list |
+| `daily-midday-sweep.md` | Yes | Update identity line |
+| `daily-evening-wrap.md` | Yes | Update identity line |
+| `backlog-executor.md` | Yes | Update identity line |
+| `inbox-processor.md` | Yes | Update identity line |
+| `meeting-prep.md` | Yes | Update identity line and recipient |
+| `meeting-action-capture.md` | Yes | Update identity line |
+| `weekly-priorities.md` | Yes | Update identity line |
+| `weekly-execution.md` | Yes | Update identity line |
+| `weekly-strategic-memo.md` | Yes | Update identity line and focus areas |
+| `weekly-hiring.md` | Role-specific | Remove for non-HR agents |
+| `weekly-engineering-health.md` | Role-specific | Remove for non-technical agents |
+| `quarterly-self-assessment.md` | Yes | Update identity line |
+
+## 10. memory/profiles/ -- Relationship Memory
+
+### User Profiles
+
+Each person the agent interacts with gets a profile at `memory/profiles/users/{slug}.yaml`:
+
+```yaml
+name: Alex Chen
+preferred_name: Alex
+slug: alex-chen
+role: CEO / Founder
+organisation: Northwind
+privilege_level: ceo
+
+communication_preferences:
+  voice: direct-concise
+  channel_preference: slack
+  timezone: Asia/Dubai
+  notes: Prefers sharp recommendations over long reports.
+
+standing_instructions:
+  - id: si-001
+    instruction: "Always include strategy scorecard in morning brief."
+    source: "slack:DXXXXXXXXXX:1775143273"
+    added: "2026-04-03"
+```
+
+The `privilege_level` field determines what the person can instruct the agent to do. Levels: `ceo` (full override), `executive` (high), `team` (standard), `external` (limited).
+
+### Channel Profiles
+
+Slack channels get profiles at `memory/profiles/channels/{channel}.yaml` defining tone, standing instructions, and response rules.
+
+### Setup for a New Agent
+
+1. Create a profile for the principal with `privilege_level: ceo`.
+2. Create profiles for the agent's direct reports and key stakeholders.
+3. Leave profiles sparse initially -- the agent populates them through interaction.
+4. Copy `memory/profiles/global.yaml` as-is; it contains universal memory rules.
+
+## 11. policies/ -- Behavioural Rules
+
+Three policy files govern agent behaviour:
+
+### policies/action-classification.yaml
+
+Defines five action levels: `observe` (read-only), `draft` (prepare without sending), `execute_autonomous` (agent sends on own authority), `email_autonomy` (email-specific rules), and `escalate_to_ceo` (requires principal approval).
+
+**Adapting for different roles:**
+
+- **Executive operator** -- Broad `execute_autonomous` scope. Can send to almost anyone.
+- **Technical leader** -- Narrow `execute_autonomous` scope. Autonomous for internal engineering channels; explicit approval for external communications.
+- **Compliance officer** -- Very restrictive. All regulatory correspondence requires explicit approval. Internal compliance updates are autonomous.
+
+Update the examples under each action level to reflect the agent's actual authority:
+
+```yaml
+execute_autonomous:
+  examples:
+    - Send Slack messages to engineering channels
+    - Create and merge pull requests
+    - Update CI/CD configuration
+    - Send code review feedback
+```
+
+### policies/information-barriers.yaml
+
+Defines what information can cross which boundaries. Critical for agents that handle confidential data across deal teams, regulatory submissions, or investor conversations. Review and adjust the barrier definitions for each agent's access scope.
+
+### policies/prompt-injection-defence.yaml
+
+The 5-layer defence is universal and should not be weakened. The only customisation needed is updating the agent name in Layer 1 (hard identity lock) to match the new agent.
+
+## 12. Quick Reference Checklist
+
+| File | What to Change | Priority | Notes |
+|------|---------------|----------|-------|
+| `config/agent.ts` | All identity fields, principal, schedule | Required | Run `/init-maestro` to populate interactively |
+| `CLAUDE.md` | Identity, principles, communication rules, people, control towers | Required | The most important file; fine-tune after init |
+| `config/environment.yaml` | Agent name, paths, phone, email, schedule | Required | Leave machine config and rate limits alone |
+| `config/contacts.yaml` | Contacts list, classification rules | Required | Tailor to the agent's communication scope |
+| `config/priorities.yaml` | All priorities and milestones | Required | Define the agent's strategic focus |
+| `agents/<agent-name>-chief-of-staff/agent.md` | Rename directory and rewrite | Required | This is the orchestrator agent definition |
+| `schedules/triggers/*.md` | Identity line in all triggers | Required | Line 1 of every trigger must match agent |
+| `policies/action-classification.yaml` | Autonomous action scope | Required | Adjust authority level for the role |
+| `memory/profiles/users/` | Create principal profile | High | Other profiles build up over time |
+| `agents/` (domain-specific) | Remove/add specialist agents | High | Keep universal agents; swap domain ones |
+| `workflows/` | Add/remove role-specific workflows | Medium | Universal cadence stays; domain workflows change |
+| `policies/information-barriers.yaml` | Barrier definitions | Medium | Critical for multi-deal or regulated roles |
+| `policies/prompt-injection-defence.yaml` | Agent name in Layer 1 | Medium | Do not weaken the defence layers |
+| `memory/profiles/channels/` | Channel tone and rules | Low | Builds up over time through interaction |
+| `config/brand-assets.yaml` | Usually unchanged | Low | Only change if agent serves a different brand |
+| `package.json` | Name and description | Low | Update to reflect new agent identity |
+| `scripts/local-triggers/plists/` | Launchd labels and paths | Low | Handled by `/init-maestro` Phase 3 (generate-plists.sh) |