Chief-of-Staff Knowledge

Chief-of-Staff is an uber-orchestrator plugin that consolidates multiple email and productivity capabilities into one unified system.

Persona System

Configurable persona with custom identity and dynamic summon command (e.g., /friday, /jarvis). Set up via /chief-of-staff:setup. See references/persona-system.md for configuration details, greeting styles, and sub-commands.

Architecture

Chief-of-Staff contains these sub-agents:

Email Action Routes

Action routes extend the triage system to route emails to specialized agents for active processing. While filing rules route emails to folders, action routes route emails to agents.

How It Works

Email arrives in inbox
    ↓
Triage (batch or interactive)
    ↓
Route matcher checks email-action-routes.yaml
    ↓
Match found? → Suggest "Process: [label]" as action
    ↓ (user confirms)
Invoke agent via Task tool
    ↓
Post-action (archive/delete/keep)

Route Matching

Routes are checked in priority order (same as filing rules):

1. •sender_email — Exact sender email match (highest priority)
2. •sender_domain — Domain-level match
3. •subject_pattern — Subject line regex match
4. •combined — Domain + subject combination

Each route specifies:

• •Match criteria: email/domain/pattern + optional refinements (subject_pattern, attachment_required)
• •Target: route.plugin + route.agent (resolves to Task subagent_type)
• •Label: Human-readable name shown in triage ("Process LF Invoice")
• •Post-action: What to do with email after processing (archive/delete/keep/none)

Integration Points

• •Batch HTML Generator: Emails matching routes appear in the "Actionable" category (priority 0, before all other categories)
• •Batch Processor: Route decisions invoke the target agent via Task tool, then execute the post-action
• •Inbox Interviewer: Route matches surface as "Process: [label]" in the interactive interview options
• •Decision Learner: Route decisions update confidence scores and detect new route-worthy patterns

Route Configuration

Routes are configured in email-action-routes.yaml (mirrors filing-rules.yaml structure):

routes:
  sender_email:
    - email: "accounting@example.com"
      attachment_required: true
      route:
        plugin: "my-plugin"
        agent: "invoice-processor"
        label: "Process Vendor Invoice"
        pass_attachments: true
        post_action: "archive"
        post_action_folder: "Invoices"
      confidence: 0.95
      source: "manual"
      enabled: true

Managing Routes

Use /chief-of-staff:routes to list, add, remove, and toggle routes.

Commands

Data Files

All data is stored in the plugin's data/ directory:

Pattern Files

Pattern files for email classification in assets/:

Workflow: Questions-First Triage

The core workflow is questions-first:

COLLECT → EXECUTE → LEARN

1. •COLLECT: Ask questions for each email, store decisions (no API calls)
2. •EXECUTE: Run all actions in bulk (efficient API usage)
3. •LEARN: Record decisions, update confidence scores, detect patterns

Integration Dependencies

Chief-of-Staff integrates with:

• •Email MCP - Email provider (required, user-configured separately)
• •Parcel API MCP - Package tracking (loaded via ToolSearch "+parcel")
• •Playwright - Browser automation for web forms and tracking extraction
  • •MCP plugin (default): playwright@claude-plugins-official or bundled in chief-of-staff (loaded via ToolSearch "+playwright browser")
  • •CLI alternative: brew install nicholasgriffintn/tap/playwright-cli
  • •Configure in settings.yaml providers.playwright.active: mcp | cli
• •Apple PIM MCP - Reminders and calendar (optional, separate plugin). v2.4.0+ supports profiles for filtered PIM access -- configure at ~/.config/apple-pim/profiles/. Set APPLE_PIM_PROFILE env var to select a profile.
• •imsg CLI - iMessage access (required for imessage-assistant, brew install steipete/tap/imsg)

Email Provider Setup (Required)

Chief-of-Staff does NOT bundle an email MCP server. Run /chief-of-staff:setup to configure. Supports Fastmail, Gmail, and Outlook. See references/email-provider-setup.md for setup instructions, Cowork configuration, and troubleshooting.

Private Extensions

Users can extend Chief-of-Staff with private capabilities by:

1. •Creating a separate private plugin (e.g., chief-of-staff-private)
2. •Adding a skill that teaches COS about the private agents
3. •Private agents can call COS sub-agents via Task tool

Example private extension skill:

# skills/private-capabilities/SKILL.md
---
description: |
  Private agents available to Chief-of-Staff:
  - filing-cabinet-organizer: Manage Filing Cabinet documents
  - inbox-action-vendor: Download vendor invoices
---

# Private Chief-of-Staff Capabilities
[Documentation of private agents]

Key Design Principles

1. •INBOX-ONLY: Never process already-archived emails
2. •DEDUPLICATION: Always check before adding (Parcel rate limits)
3. •USER CONFIRMATION: Never auto-file without explicit approval
4. •LEARNING: Record decisions to improve future suggestions
5. •BULK OPERATIONS: Group API calls for efficiency
6. •VOICE-FRIENDLY: Simple numbered options for voice input

Output Formatting Guidelines

When displaying information to the user:

1. •

   NO EMOJIS IN TABLE CELLS: Emojis have inconsistent display widths and break markdown table column alignment in terminal rendering. Use plain text in tables.

   Bad:

   code

   | Folder | Unread |
   |--------|--------|
   | 📦 Orders | 222 |
   | 🛩️ Flights | 29 |
   

   Good:

   code

   | Folder | Unread |
   |--------|--------|
   | Orders | 222 |
   | Flights | 29 |
   

2. •

   EMOJIS IN HEADERS ARE OK: Section headers like ## 📬 Inbox Overview render fine.

3. •

   EMOJIS IN LISTS ARE OK: Bullet points with emojis work correctly.

4. •

   KEEP TABLES SIMPLE: Avoid complex formatting, long text, or special characters in table cells.