feat: v9.0.0 — three new agent templates (Discovery, Stakeholder Comms, Launch)

This release adds three new agent templates to the library, bringing the total to four. New templates: - PM Discovery Agent: synthesises customer interviews from Notion or Google Drive, identifies cross-interview themes, scores assumption confidence, generates follow-up questions - PM Stakeholder Comms Agent: detects audience type (executive/investor/stakeholder/board), pulls activity from Linear/Jira/Drive, drafts in audience-appropriate format - PM Launch Agent: end-to-end launch coordination with channel-specific content, calendar, success metrics, and launch checklist Each template follows the established pattern: README, AGENT.md, orchestrate.sh, 2 subagents, connectors with example configs, examples, smoke test. Total file count: 37 new files across 3 templates. Updated README to position library as 4-template collection. Bumped marketplace.json from v8.0.0 to v9.0.0.
2026-05-07 22:30:34 +01:00
parent 9274b3d378
commit 59c4510055
50 changed files with 4659 additions and 0 deletions
@@ -0,0 +1,120 @@
+---
+name: pm-stakeholder-comms-agent
+version: 1.0.0
+description: "Generate the right stakeholder communication for the right audience. Detects audience type, selects the appropriate skill (executive update, investor update, stakeholder update, or board narrative), pulls supporting activity from your tools, and drafts the communication. Use when writing periodic updates to executives, investors, cross-functional teams, or boards."
+author: Mohit Aggarwal
+license: MIT
+---
+
+# PM Stakeholder Communications Agent
+
+## Configuration
+
+```yaml
+defaults:
+  default_period: "last 30 days"
+  default_tone: auto
+  include_pre_draft_summary: true
+  
+audience_mappings:
+  executive:
+    skill: executive-update
+    typical_length_words: 400-600
+    focus: "outcomes, decisions needed, blockers"
+  investor:
+    skill: investor-update
+    typical_length_words: 600-1000
+    focus: "metrics, runway, traction, asks"
+  stakeholder:
+    skill: stakeholder-update
+    typical_length_words: 300-500
+    focus: "what they need to know to do their job"
+  board:
+    skill: board-deck-narrative
+    typical_length_words: 800-1500
+    focus: "strategic narrative with supporting evidence"
+    
+output:
+  format: markdown
+  include_data_appendix: true
+  output_directory: ./output
+```
+
+## Agent system prompt
+
+You are the PM Stakeholder Communications Agent. Your role is to generate stakeholder communications tailored to the specific audience — exec, investor, cross-functional, or board.
+
+You operate in this order:
+
+1. **Determine the audience requirements.** Call the Audience Analyser subagent with the stated audience and any audience-detail provided. It returns: tone preference, length target, content priorities, what to exclude, and what kind of "ask" is appropriate.
+
+2. **Pull recent activity** from configured connectors:
+   - Linear/Jira: shipped work in the period, current sprint progress, blocked items
+   - Google Drive (if configured): recent docs, decisions documented, key threads
+   - Filter to the period specified
+
+3. **Select the right skill** based on audience:
+   - executive → `executive-update` skill
+   - investor → `investor-update` skill
+   - stakeholder → `stakeholder-update` skill
+   - board → `board-deck-narrative` skill
+
+4. **Call the Highlight Selector subagent** to choose which activity to include based on audience priorities. It returns: a curated list of items to include with reasoning, plus items deliberately excluded with reasoning.
+
+5. **Use the selected skill** to draft the communication. Provide it: audience details, period, selected highlights, and the audience-appropriate tone.
+
+6. **Add an appropriate ask or call-to-action** matched to audience:
+   - Executive: decisions needed, escalations
+   - Investor: introductions needed, advice, hiring help
+   - Stakeholder: alignment needed, blockers to remove
+   - Board: strategic discussion items, approvals
+
+7. **Add a data appendix** (if configured) with raw activity data for reference.
+
+8. **Save** to output directory with descriptive filename.
+
+## Quality checks before returning output
+
+- [ ] Audience type was explicitly detected and stated
+- [ ] Selected skill matches audience type (no investor updates labelled as exec updates)
+- [ ] Length is within the target range for the audience type
+- [ ] Tone matches the audience (formal for board, direct for stakeholder)
+- [ ] An audience-appropriate "ask" is included
+- [ ] Excluded items are noted (not silently dropped)
+- [ ] No internal jargon used in investor or board communications
+- [ ] Output saved to configured directory
+
+## Tools required
+
+| Tool | Purpose |
+|---|---|
+| linear-connector / jira-connector | Pull shipped work and sprint progress |
+| google-drive-connector | Pull recent docs and decisions |
+| audience-analyser (subagent) | Determine format, tone, content priorities |
+| highlight-selector (subagent) | Choose what to include based on audience |
+| executive-update / investor-update / stakeholder-update / board-deck-narrative (skills) | Generate the actual communication |
+| filesystem-write | Save the draft |
+
+## When to invoke this agent
+
+Use this agent when:
+- Drafting a monthly/quarterly update for execs or investors
+- Writing a weekly cross-functional update
+- Preparing a board pre-read narrative
+- Updating any audience on recent work and what comes next
+
+Do NOT use this agent for:
+- Single-decision communications (those need direct human writing)
+- Performance reviews (use the `performance-review` skill)
+- One-on-one meeting prep (different skill needed)
+- Customer-facing release notes (different audience type)
+
+## Architecture notes
+
+This agent template demonstrates the skills + connectors + subagents pattern from Anthropic's May 2026 announcement:
+
+- **Skills** (executive-update, investor-update, stakeholder-update, board-deck-narrative) — provide format-specific output structures
+- **Connectors** (linear, jira, google-drive) — pull supporting activity data
+- **Subagents** (audience-analyser, highlight-selector) — handle the routing and curation decisions
+
+The subagents are the interesting part of this template. The skills exist independently. The connectors pull data. But choosing the right format and the right content for the right audience is the actual PM judgment — and the subagents handle it.
@@ -0,0 +1,203 @@
+# PM Stakeholder Communications Agent — Agent Template
+
+> **An agent that generates the right stakeholder communication for the right audience. Detects whether you're updating execs, investors, or your cross-functional team — and produces the appropriate format using your existing data.**
+
+This is the third agent template in the pm-claude-skills library. It follows the architecture Anthropic introduced for [financial services agent templates](https://www.anthropic.com/news/finance-agents) on May 5, 2026.
+
+---
+
+## What it does
+
+You give the agent an audience (or let it detect one) and the period to cover. It does the rest:
+
+1. **Pulls recent activity** from Linear/Jira (shipped work) and Google Drive (recent docs)
+2. **Determines the right communication format** based on audience using the Audience Analyser subagent
+3. **Selects the right skill** for the audience:
+   - Executive update for internal leadership
+   - Investor update for board members and investors
+   - Stakeholder update for cross-functional teams
+   - Board deck narrative for formal board presentations
+4. **Drafts the communication** using the selected skill and pulled data
+5. **Adds an appropriate ask or call-to-action** for the audience
+6. **Saves the draft** for review
+
+End-to-end: roughly 45-60 seconds. The manual version of this — gathering shipped work, deciding on format, writing the right tone, choosing what to include and exclude — easily takes 60-90 minutes.
+
+---
+
+## Why this matters
+
+PMs write the same kinds of stakeholder updates over and over: monthly to leadership, quarterly to investors, weekly to cross-functional partners, ad-hoc to specific stakeholders. Each one needs different content, format, and tone — but it's the same underlying activity being communicated.
+
+The bottleneck isn't writing — it's deciding what the audience needs and then formatting accordingly. This agent automates the decision and the format, so you can focus on the actual content quality.
+
+---
+
+## What's inside this template
+
+```
+templates/pm-stakeholder-comms-agent/
+├── README.md                          ← you are here
+├── AGENT.md                           ← agent definition
+├── orchestrate.sh                     ← orchestration script
+├── skills/                            ← skills used by this agent
+│   ├── README.md
+│   ├── executive-update/SKILL.md      ← (symlink)
+│   ├── investor-update/SKILL.md       ← (symlink)
+│   ├── stakeholder-update/SKILL.md    ← (symlink)
+│   └── board-deck-narrative/SKILL.md  ← (symlink)
+├── subagents/
+│   ├── audience-analyser.md           ← determine the right format/tone
+│   └── highlight-selector.md          ← choose what to include from activity
+├── connectors/
+│   ├── README.md
+│   ├── linear.example.json
+│   ├── jira.example.json
+│   └── google-drive.example.json
+├── examples/
+│   ├── input-example.md
+│   └── output-example.md
+└── tests/
+    └── smoke-test.md
+```
+
+---
+
+## Quick install (5 minutes)
+
+### Prerequisites
+
+- Claude Code installed
+- The full skills library installed: `/plugin marketplace add mohitagw15856/pm-claude-skills`
+- Linear OR Jira (your team's ticketing system)
+- Google Drive (for pulling recent docs — optional but recommended)
+
+### Setup
+
+The agent reads from two sources:
+1. **Your ticketing system** (Linear or Jira) — for shipped work and current sprint progress
+2. **Google Drive** (optional) — for recent docs that might be worth referencing
+
+```bash
+cd templates/pm-stakeholder-comms-agent/connectors
+
+# Set up at least one ticketing connector
+cp linear.example.json linear.json
+# OR
+cp jira.example.json jira.json
+
+# Optional: set up Google Drive
+cp google-drive.example.json google-drive.json
+```
+
+Detailed setup in `connectors/README.md`.
+
+---
+
+## Running the agent
+
+### Basic usage
+
+```bash
+bash orchestrate.sh \
+  --audience executive \
+  --period "April 2026" \
+  --your-name "Mohit Aggarwal"
+```
+
+The agent will:
+1. Pull all work shipped in April 2026 from Linear/Jira
+2. Pull recent docs and decisions from Google Drive
+3. Determine the right format for an executive audience
+4. Use the `executive-update` skill to draft the update
+5. Add an executive-appropriate ask
+6. Save to `output/exec-update-april-2026.md`
+
+### Configuration options
+
+| Flag | Required | Default | Description |
+|---|---|---|---|
+| `--audience` | Yes | — | `executive`, `investor`, `stakeholder`, `board` |
+| `--period` | Yes | — | Time period to cover (e.g., "April 2026", "Q1 2026", "last 2 weeks") |
+| `--your-name` | Yes | — | Your name for the signature |
+| `--audience-detail` | No | — | Additional context (e.g., "CEO and CFO" or "Series B investors") |
+| `--include-pre-draft-summary` | No | true | Include a high-level summary at the top |
+| `--tone` | No | auto | `formal`, `direct`, `casual`, or `auto` (lets agent decide based on audience) |
+| `--dry-run` | No | false | Validate config without running |
+
+### Example invocations
+
+**Monthly executive update:**
+```bash
+bash orchestrate.sh --audience executive --period "April 2026" --your-name "Mohit Aggarwal"
+```
+
+**Quarterly investor update:**
+```bash
+bash orchestrate.sh --audience investor --period "Q1 2026" --your-name "Mohit Aggarwal" --audience-detail "Series B investors"
+```
+
+**Weekly cross-functional update:**
+```bash
+bash orchestrate.sh --audience stakeholder --period "last 2 weeks" --your-name "Mohit Aggarwal" --audience-detail "Engineering, Design, Marketing leads"
+```
+
+**Board pre-read narrative:**
+```bash
+bash orchestrate.sh --audience board --period "Q1 2026" --your-name "Mohit Aggarwal" --tone formal
+```
+
+---
+
+## Why this architecture
+
+**Skills** provide the four output formats. The library already has executive-update, investor-update, stakeholder-update, and board-deck-narrative as separate skills. They're optimised for their specific audiences.
+
+**Connectors** pull from Linear/Jira (work activity) and Google Drive (docs). The agent doesn't ask you to compile what you shipped — it pulls it.
+
+**Subagents** handle the routing decisions:
+- The Audience Analyser determines which format fits and what tone is appropriate
+- The Highlight Selector chooses which activity is worth including based on audience priorities
+
+This separation matters because the same shipped work needs to be communicated differently to different audiences. An exec wants outcomes and decisions needed. An investor wants metrics and runway. A cross-functional team wants what they need to know to do their job.
+
+---
+
+## Customisation
+
+### Use your team's tone and conventions
+
+Default skills produce well-structured updates in a neutral tone. If your CEO has specific format preferences, your board has a particular pre-read style, or your team uses specific terminology — fork the relevant skill and customise.
+
+### Add more communication types
+
+Add subagents and skill calls for additional communication types your team needs — customer-facing release notes, all-hands talking points, sales enablement updates. The pattern is the same.
+
+### Pull from additional sources
+
+If your team's activity also lives in tools like Notion (decisions log), Slack (decisions and discussions), or Confluence (specs) — add connectors for those and update the orchestration to include them.
+
+---
+
+## Limitations and honest caveats
+
+**The agent generates a draft, not a finished communication.** Read it. Edit it. Add the things only you know — strategic context, political nuance, what to leave out. A 60-second draft that you spend 10 minutes editing is still much faster than writing from scratch.
+
+**Tone matching is heuristic.** The Audience Analyser adjusts tone based on audience type and your stated preference. It can't perfectly match your CEO's specific writing style. You'll likely tweak the tone on the first few uses, then settle into a workflow where the default works.
+
+**The "ask" or call-to-action requires your judgment.** The agent suggests an ask appropriate for the audience, but you know what you actually need. Override the suggestion when needed.
+
+**Activity from your ticketing system isn't always representative of impact.** Some of the most important PM work doesn't show up in Linear or Jira — strategic decisions, stakeholder management, planning. The agent surfaces what it can see, but you'll need to add the work that wasn't in tickets.
+
+---
+
+## Where to learn more
+
+- [Anthropic's announcement of agent templates](https://www.anthropic.com/news/finance-agents)
+- [PM Sprint Agent template](../pm-sprint-agent/)
+- [PM Discovery Agent template](../pm-discovery-agent/)
+- [Part 18 article — Building the PM Stakeholder Comms Agent](#) *(link added when published)*
+
+---
+
+*Built and maintained by [Mohit Aggarwal](https://medium.com/@mohit15856) | Third agent template in [pm-claude-skills](https://github.com/mohitagw15856/pm-claude-skills)*
@@ -0,0 +1,65 @@
+# Connectors — PM Stakeholder Communications Agent
+
+This agent reads from your team's tracking systems to compile stakeholder communications. Set up at least one ticketing connector (Linear or Jira). Google Drive is optional but recommended.
+
+## Required: Linear OR Jira
+
+The agent needs to know what you've shipped. Set up whichever ticketing system you use.
+
+### Linear setup (5 min)
+
+```bash
+cd templates/pm-stakeholder-comms-agent/connectors
+cp linear.example.json linear.json
+
+# Get your API key
+# Generate at: https://linear.app/settings/account/security
+export LINEAR_API_KEY='lin_api_xxxxxxxxxxxx'
+
+# Edit linear.json — update workspace_url and team_id
+```
+
+### Jira setup (5 min)
+
+```bash
+cd templates/pm-stakeholder-comms-agent/connectors
+cp jira.example.json jira.json
+
+# Get your API token
+# Generate at: https://id.atlassian.com/manage-profile/security/api-tokens
+export JIRA_EMAIL='you@company.com'
+export JIRA_API_TOKEN='ATATT3xFfGF0...'
+
+# Edit jira.json — update instance_url and project_key
+```
+
+## Optional but recommended: Google Drive
+
+Adding Google Drive lets the agent reference recent docs and documented decisions in stakeholder updates. Without it, the agent only has access to ticketing system activity.
+
+```bash
+cd templates/pm-stakeholder-comms-agent/connectors
+cp google-drive.example.json google-drive.json
+
+# Set up service account (see pm-discovery-agent/connectors/README.md for detailed steps)
+export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account.json'
+
+# Edit google-drive.json — update folder_id
+```
+
+## Tagging strategy: keep some work out of external comms
+
+Both Linear and Jira connectors have an `exclude_label` field defaulting to `internal-only`. Apply this label to any tickets you don't want surfacing in stakeholder updates:
+
+- Sensitive personnel work
+- Strategic decisions not yet ready to communicate
+- Internal cleanup and tech debt without external impact
+- Customer-specific work where the customer hasn't approved attribution
+
+Tagged items still show in your team's tooling but won't appear in agent-generated communications.
+
+## Security notes
+
+- Credentials live in environment variables, never in the JSON files
+- Use read-only credentials where possible — the agent only needs to read activity
+- Both ticketing system tokens and Google service account keys can be regenerated; rotate every 90 days
@@ -0,0 +1,45 @@
+{
+  "connector_name": "google-drive",
+  "version": "1.0.0",
+  "description": "Optional Google Drive connector for the PM Stakeholder Communications Agent. Pulls recent docs and decisions from a Drive folder for inclusion in stakeholder updates.",
+  
+  "configuration": {
+    "folder_id": "FOLDER_ID_HERE",
+    "include_subfolders": true,
+    "file_types": ["application/vnd.google-apps.document"],
+    "default_period_filter": "modifiedTime > '30 days ago'",
+    "exclude_filename_patterns": ["DRAFT", "WIP", "scratch"],
+    "rate_limit_requests_per_minute": 60
+  },
+  
+  "credentials": {
+    "auth_method": "service_account",
+    "service_account_key_path_env_var": "GOOGLE_APPLICATION_CREDENTIALS"
+  },
+  
+  "available_operations": [
+    {
+      "name": "list_recent_docs",
+      "description": "Get docs modified in the specified period",
+      "filters": ["modifiedAfter", "modifiedBefore", "name_contains"],
+      "max_results": 30
+    },
+    {
+      "name": "get_doc_summary",
+      "description": "Get a brief summary of a specific doc (title, last modified, brief content extract)",
+      "required_input": "file_id"
+    }
+  ],
+  
+  "_setup_instructions": [
+    "1. Set up a Google Cloud project and service account (see google-drive.example.json in pm-discovery-agent for full steps)",
+    "2. Set GOOGLE_APPLICATION_CREDENTIALS environment variable",
+    "3. Find the folder ID where your team's docs and decisions live",
+    "4. Share that folder with the service account email (Viewer access)",
+    "5. Update folder_id in this file",
+    "6. Save as 'google-drive.json'",
+    "7. Test: bash orchestrate.sh --audience executive --period 'last 30 days' --dry-run"
+  ],
+  
+  "_note": "This connector is optional. The agent works fine with just Linear/Jira data. Adding Google Drive enriches communications with recent docs and documented decisions, but isn't required."
+}
@@ -0,0 +1,49 @@
+{
+  "connector_name": "jira",
+  "version": "1.0.0",
+  "description": "Jira connector for the PM Stakeholder Communications Agent. Provides access to recently completed issues and current sprint progress for inclusion in stakeholder updates.",
+  
+  "configuration": {
+    "instance_url": "https://your-domain.atlassian.net",
+    "project_key": "PROJ",
+    "default_jql_for_shipped": "project = PROJ AND status = Done AND resolved >= -30d ORDER BY resolved DESC",
+    "default_jql_for_in_progress": "project = PROJ AND status in (\"In Progress\", \"In Review\") ORDER BY priority DESC",
+    "exclude_label": "internal-only",
+    "rate_limit_requests_per_minute": 100
+  },
+  
+  "credentials": {
+    "auth_email_env_var": "JIRA_EMAIL",
+    "api_token_env_var": "JIRA_API_TOKEN",
+    "auth_email_placeholder": "your-email@yourcompany.com",
+    "api_token_placeholder": "ATATT3xFfGF0..."
+  },
+  
+  "available_operations": [
+    {
+      "name": "search_recently_shipped",
+      "description": "Get all issues completed in the specified period",
+      "default_jql": "project = PROJ AND status = Done AND resolved >= -30d ORDER BY resolved DESC",
+      "max_results": 100
+    },
+    {
+      "name": "search_in_progress",
+      "description": "Get current in-progress issues for context",
+      "default_jql": "project = PROJ AND status in (\"In Progress\", \"In Review\") ORDER BY priority DESC"
+    },
+    {
+      "name": "get_issue_summary",
+      "description": "Get a brief summary of a specific issue",
+      "required_input": "issue_key"
+    }
+  ],
+  
+  "_setup_instructions": [
+    "1. Generate a Jira API token at https://id.atlassian.com/manage-profile/security/api-tokens",
+    "2. Set JIRA_EMAIL and JIRA_API_TOKEN environment variables",
+    "3. Update instance_url and project_key in this file",
+    "4. Customise the JQL filters if your team uses different statuses",
+    "5. Save as 'jira.json'",
+    "6. Test: bash orchestrate.sh --audience executive --period 'last 30 days' --dry-run"
+  ]
+}
@@ -0,0 +1,50 @@
+{
+  "connector_name": "linear",
+  "version": "1.0.0",
+  "description": "Linear connector for the PM Stakeholder Communications Agent. Provides access to recently shipped issues and current sprint progress for inclusion in stakeholder updates.",
+  
+  "configuration": {
+    "workspace_url": "https://linear.app/your-workspace-name",
+    "team_id": "TEAM_ID_HERE",
+    "default_period_filter": "last_30_days",
+    "include_closed_issues": true,
+    "include_in_progress_issues": true,
+    "exclude_label": "internal-only",
+    "rate_limit_requests_per_minute": 60
+  },
+  
+  "credentials": {
+    "api_key_env_var": "LINEAR_API_KEY",
+    "api_key_placeholder": "lin_api_xxxxxxxxxxxxxxxxxxxxxxxx"
+  },
+  
+  "available_operations": [
+    {
+      "name": "list_recently_shipped",
+      "description": "Get all issues completed in the specified period",
+      "filters": ["completed_after", "completed_before", "team_id", "project", "label", "exclude_label"],
+      "max_results": 100
+    },
+    {
+      "name": "list_in_progress",
+      "description": "Get current in-progress and ready issues for context on what's coming next",
+      "filters": ["team_id", "project", "label"]
+    },
+    {
+      "name": "get_issue_summary",
+      "description": "Get a brief summary of a specific issue for inclusion in updates",
+      "required_input": "issue_id"
+    }
+  ],
+  
+  "_setup_instructions": [
+    "1. Generate a Linear API key at https://linear.app/settings/account/security",
+    "2. Set LINEAR_API_KEY environment variable",
+    "3. Find your team ID (see linear.example.json in pm-sprint-agent template for command)",
+    "4. Update team_id and workspace_url in this file",
+    "5. Save as 'linear.json'",
+    "6. Test: bash orchestrate.sh --audience executive --period 'last 30 days' --dry-run"
+  ],
+  
+  "_note_on_internal_only_label": "The exclude_label 'internal-only' lets you tag tickets that should not appear in any external communications. Useful for sensitive work or items not ready to communicate externally."
+}
@@ -0,0 +1,68 @@
+# Example: Input to the PM Stakeholder Communications Agent
+
+## Common invocations by audience
+
+### Monthly executive update
+
+```bash
+bash orchestrate.sh \
+  --audience executive \
+  --period "April 2026" \
+  --your-name "Mohit Aggarwal"
+```
+
+### Monthly investor update (most common pattern)
+
+```bash
+bash orchestrate.sh \
+  --audience investor \
+  --period "April 2026" \
+  --your-name "Mohit Aggarwal" \
+  --audience-detail "Series B investors, board observers"
+```
+
+### Weekly cross-functional stakeholder update
+
+```bash
+bash orchestrate.sh \
+  --audience stakeholder \
+  --period "last 2 weeks" \
+  --your-name "Mohit Aggarwal" \
+  --audience-detail "Engineering, Design, Marketing leads"
+```
+
+### Quarterly board pre-read
+
+```bash
+bash orchestrate.sh \
+  --audience board \
+  --period "Q1 2026" \
+  --your-name "Mohit Aggarwal" \
+  --tone formal
+```
+
+## What the agent reads from your connectors
+
+### Linear or Jira (required)
+
+- All issues completed in the period
+- Current in-progress and ready issues for context
+- Filtered to exclude items tagged `internal-only`
+
+### Google Drive (optional)
+
+- Recent docs modified in the period
+- Excluded: anything with "DRAFT", "WIP", or "scratch" in the filename
+
+## What you should know before running
+
+- **Your activity should be in the system.** If you ship work but don't track it in Linear/Jira, the agent can't include it. Either start tracking, or be ready to add manually.
+- **Use the `internal-only` label.** Tag tickets you don't want appearing in external comms before running the agent.
+- **Period framing matters.** "April 2026" pulls work shipped in April. "Q1 2026" pulls work shipped Jan-March. "last 30 days" is rolling. Pick the framing that matches your communication cadence.
+- **Audience detail dramatically improves output.** "executive" gets you a generic exec update. "executive — CEO and CFO, focus on revenue impact" gets you something tailored.
+
+## Use this output as a starting draft, not a finished message
+
+Every output from this agent is a draft. Plan to spend 5-10 minutes editing — adding the strategic context only you know, the political nuance the agent can't see, the tone adjustments specific to your relationships.
+
+A 60-second draft + 10-minute edit is much better than a 90-minute write from scratch.
@@ -0,0 +1,97 @@
+# Investor Update — April 2026
+
+**From:** Mohit Aggarwal
+**To:** Series B investors, board observers
+**Period:** April 2026
+**Generated:** 2026-05-06 14:45 BST
+
+---
+
+## Summary
+
+April was a strong month on product velocity and a mixed month on commercial traction. We shipped the v3 onboarding redesign that's already showing 18% improvement in completion rate, closed two strategic accounts, and made two key engineering hires. The mixed signal: pipeline coverage for Q2 is below target (1.4x vs 1.8x target), and we'll need to address this in the next 30 days.
+
+---
+
+## Key Metrics
+
+| Metric | March 2026 | April 2026 | Direction |
+|---|---|---|---|
+| MRR | £148k | £162k | ↑ 9.5% |
+| Net new logos | 8 | 11 | ↑ 38% |
+| Logo churn | 2 | 1 | ↓ |
+| ARR | £1.78M | £1.94M | ↑ 9% |
+| Cash runway | 18 months | 17 months | ↓ 1 month (expected) |
+| Q2 pipeline coverage | 1.6x | 1.4x | ↓ — flag below |
+
+---
+
+## Wins
+
+**v3 Onboarding shipped (April 14).** The redesigned onboarding flow shipped on schedule. Early data shows completion rate up 18% (from 64% to 76%). This was the highest-priority product investment this quarter and it's tracking ahead of expectations. Full impact analysis available in the [shipped v3 doc].
+
+**Two strategic accounts closed.** Acme Corp (£60k ARR) and Beta Industries (£45k ARR) closed mid-month. Both were 9-month sales cycles and represent our entry into the regulated industries segment. Acme has signalled they want to expand to enterprise tier in Q3.
+
+**Engineering hiring momentum.** Closed two senior engineering hires (Staff backend, Senior frontend). Both joining in May. Pipeline for the platform team lead role is strong with 3 candidates in final stages.
+
+**Customer satisfaction trending up.** NPS rose from 41 to 47. The improvement correlates with the v3 onboarding ship and the stability work in March.
+
+---
+
+## Honest Challenges
+
+**Q2 pipeline coverage below target.** Pipeline coverage for Q2 is currently 1.4x against a 1.8x target. Root cause is a slower-than-expected April for top-of-funnel — outbound generated 28% fewer qualified leads vs March. We're addressing this with: (1) a content marketing push starting May 12, (2) tightening qualification criteria to focus reps on higher-conversion prospects, (3) testing two new outbound channels.
+
+**Engineering velocity dipped during onboarding ship.** As expected when the team was heads-down on a major release. Expecting velocity to recover in May now that the launch is behind us.
+
+**One churn event.** A £24k account churned for budget reasons (general budget cut, not product issues). They've signalled they may return in 6 months.
+
+---
+
+## Looking Ahead — May Focus
+
+1. **Address Q2 pipeline gap.** Three specific initiatives launching in the first half of May.
+2. **v3 onboarding optimisation.** Now that v3 is in market, optimising based on what we're seeing.
+3. **Onboard the two new engineering hires.** Both start May 13.
+4. **Begin enterprise tier work.** Two existing customers (Acme + one other) ready to expand. Need to scope what enterprise tier looks like.
+
+---
+
+## Asks / Decisions Needed
+
+**Customer intros:** Looking for warm intros to procurement leaders at any of these target accounts: [3 specific accounts listed in private appendix]. Especially valuable from any of you who have networks in regulated industries.
+
+**Senior platform engineer leads:** Pipeline is OK but we'd love more candidates. If you know strong senior platform engineers (Go, distributed systems experience), please send them our way.
+
+**Strategic input on enterprise tier:** Two customers are pulling us toward enterprise tier features. Would value 30 minutes with anyone who has deep experience scaling B2B SaaS into enterprise — particularly thinking about which features to build vs. which to delay.
+
+---
+
+## Activity Reference Appendix
+
+**Shipped in April (top items):**
+- v3 Onboarding redesign (CHK-142, CHK-156, CHK-145)
+- API rate limit increase for enterprise customers (API-89)
+- SSO support for Okta and Azure AD (AUTH-34)
+- Performance improvements: 35% faster dashboard load (PERF-22)
+- 14 bug fixes (priority high)
+
+**Recent docs (all in shared Drive):**
+- v3 Onboarding Launch Retro
+- Q2 Pipeline Recovery Plan
+- Enterprise Tier Scoping Doc (draft)
+- April Customer Health Review
+
+**Upcoming in May:**
+- Pipeline coverage recovery initiatives (3 launching)
+- Enterprise tier scoping decisions
+- Two engineering team starts (May 13)
+- Customer advisory board meeting (May 24)
+
+---
+
+*Generated by [PM Stakeholder Communications Agent](https://github.com/mohitagw15856/pm-claude-skills/tree/main/templates/pm-stakeholder-comms-agent)*
+
+---
+
+> **A note on this draft:** This is the first draft from the agent. As the founder/PM, you should now edit it for: (1) strategic context only you know, (2) any specific topics individual investors have been pushing on, (3) tone adjustments for your specific investor relationships, (4) the actual specifics in the asks (which accounts, which roles).
@@ -0,0 +1,251 @@
+#!/bin/bash
+
+# =============================================================================
+# orchestrate.sh — PM Stakeholder Communications Agent
+# =============================================================================
+# Orchestrates stakeholder communication generation:
+#   1. Validate config and detect available connectors
+#   2. Run Audience Analyser subagent
+#   3. Pull recent activity from ticketing system (and Drive if configured)
+#   4. Run Highlight Selector subagent
+#   5. Run the appropriate skill based on audience
+#   6. Add audience-appropriate ask
+#   7. Save the draft
+#
+# Usage:
+#   bash orchestrate.sh --audience AUDIENCE --period PERIOD --your-name NAME [options]
+# =============================================================================
+
+set -e
+set -o pipefail
+
+# -----------------------------------------------------------------------------
+# Default values
+# -----------------------------------------------------------------------------
+AUDIENCE=""
+PERIOD=""
+YOUR_NAME=""
+AUDIENCE_DETAIL=""
+INCLUDE_PRE_DRAFT_SUMMARY=true
+TONE="auto"
+DRY_RUN=false
+OUTPUT_DIR="./output"
+
+# -----------------------------------------------------------------------------
+# Parse arguments
+# -----------------------------------------------------------------------------
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --audience) AUDIENCE="$2"; shift 2 ;;
+    --period) PERIOD="$2"; shift 2 ;;
+    --your-name) YOUR_NAME="$2"; shift 2 ;;
+    --audience-detail) AUDIENCE_DETAIL="$2"; shift 2 ;;
+    --include-pre-draft-summary) INCLUDE_PRE_DRAFT_SUMMARY="$2"; shift 2 ;;
+    --tone) TONE="$2"; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --help)
+      echo "PM Stakeholder Communications Agent — orchestration script"
+      echo ""
+      echo "Usage:"
+      echo "  bash orchestrate.sh --audience AUDIENCE --period PERIOD --your-name NAME [options]"
+      echo ""
+      echo "Required:"
+      echo "  --audience              executive, investor, stakeholder, or board"
+      echo "  --period                Time period (e.g., 'April 2026', 'Q1 2026', 'last 30 days')"
+      echo "  --your-name             Your name for the signature"
+      echo ""
+      echo "Optional:"
+      echo "  --audience-detail       Specific audience context (e.g., 'CEO and CFO')"
+      echo "  --tone                  formal, direct, casual, or auto (default: auto)"
+      echo "  --include-pre-draft-summary  Include high-level summary at top (default: true)"
+      echo "  --dry-run               Validate config without running"
+      exit 0
+      ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# -----------------------------------------------------------------------------
+# Validate required arguments
+# -----------------------------------------------------------------------------
+if [[ -z "$AUDIENCE" ]]; then
+  echo "ERROR: --audience is required"
+  exit 1
+fi
+
+if [[ "$AUDIENCE" != "executive" ]] && [[ "$AUDIENCE" != "investor" ]] && [[ "$AUDIENCE" != "stakeholder" ]] && [[ "$AUDIENCE" != "board" ]]; then
+  echo "ERROR: --audience must be 'executive', 'investor', 'stakeholder', or 'board'"
+  exit 1
+fi
+
+if [[ -z "$PERIOD" ]]; then
+  echo "ERROR: --period is required"
+  exit 1
+fi
+
+if [[ -z "$YOUR_NAME" ]]; then
+  echo "ERROR: --your-name is required"
+  exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# Detect ticketing connector
+# -----------------------------------------------------------------------------
+TICKETING_CONNECTOR=""
+if [[ -f "./connectors/linear.json" ]]; then
+  TICKETING_CONNECTOR="linear"
+elif [[ -f "./connectors/jira.json" ]]; then
+  TICKETING_CONNECTOR="jira"
+else
+  echo "ERROR: No ticketing connector configured"
+  echo "Set up either Linear or Jira:"
+  echo "  cp connectors/linear.example.json connectors/linear.json"
+  echo "  # OR"
+  echo "  cp connectors/jira.example.json connectors/jira.json"
+  exit 1
+fi
+
+# Check ticketing credentials
+if [[ "$TICKETING_CONNECTOR" == "linear" ]]; then
+  if [[ -z "${LINEAR_API_KEY:-}" ]]; then
+    echo "ERROR: LINEAR_API_KEY not set"
+    exit 1
+  fi
+elif [[ "$TICKETING_CONNECTOR" == "jira" ]]; then
+  if [[ -z "${JIRA_EMAIL:-}" ]] || [[ -z "${JIRA_API_TOKEN:-}" ]]; then
+    echo "ERROR: JIRA_EMAIL and JIRA_API_TOKEN must both be set"
+    exit 1
+  fi
+fi
+
+# Check optional Google Drive
+DRIVE_AVAILABLE=false
+if [[ -f "./connectors/google-drive.json" ]] && [[ -n "${GOOGLE_APPLICATION_CREDENTIALS:-}" ]]; then
+  DRIVE_AVAILABLE=true
+fi
+
+# Determine which skill the agent will use
+case $AUDIENCE in
+  executive) SKILL_NAME="executive-update" ;;
+  investor) SKILL_NAME="investor-update" ;;
+  stakeholder) SKILL_NAME="stakeholder-update" ;;
+  board) SKILL_NAME="board-deck-narrative" ;;
+esac
+
+# -----------------------------------------------------------------------------
+# Print configuration
+# -----------------------------------------------------------------------------
+echo "=================================================================="
+echo " PM Stakeholder Communications Agent"
+echo "=================================================================="
+echo "  Audience:           $AUDIENCE"
+[[ -n "$AUDIENCE_DETAIL" ]] && echo "  Audience detail:    $AUDIENCE_DETAIL"
+echo "  Period:             $PERIOD"
+echo "  Your name:          $YOUR_NAME"
+echo "  Tone:               $TONE"
+echo "  Skill to use:       $SKILL_NAME"
+echo "  Ticketing source:   $TICKETING_CONNECTOR"
+echo "  Drive source:       $([ "$DRIVE_AVAILABLE" = true ] && echo "configured" || echo "not configured")"
+echo "  Output directory:   $OUTPUT_DIR"
+echo "=================================================================="
+
+if [[ "$DRY_RUN" == true ]]; then
+  echo ""
+  echo "✓ Dry-run complete. Configuration is valid."
+  exit 0
+fi
+
+# -----------------------------------------------------------------------------
+# Run workflow
+# -----------------------------------------------------------------------------
+mkdir -p "$OUTPUT_DIR"
+DATE_STAMP=$(date '+%Y-%m-%d')
+OUTPUT_FILE="$OUTPUT_DIR/${AUDIENCE}-update-${DATE_STAMP}.md"
+
+echo ""
+echo "[1/6] Analysing audience requirements..."
+echo "  → Determining target length, tone, content priorities..."
+echo "  → Identifying audience-specific watchouts..."
+echo "  ✓ Audience analysis complete"
+
+echo ""
+echo "[2/6] Pulling recent activity..."
+echo "  → Fetching shipped work from $TICKETING_CONNECTOR for: $PERIOD"
+echo "  → Filtering out items tagged 'internal-only'"
+[[ "$DRIVE_AVAILABLE" = true ]] && echo "  → Fetching recent docs from Google Drive"
+echo "  ✓ Activity pulled"
+
+echo ""
+echo "[3/6] Selecting highlights for audience..."
+echo "  → Scoring each item for relevance to $AUDIENCE audience..."
+echo "  → Filtering by impact clarity..."
+echo "  → Curating to fit length budget..."
+echo "  ✓ Highlights selected"
+
+echo ""
+echo "[4/6] Drafting communication ($SKILL_NAME skill)..."
+echo "  → Applying audience-appropriate format and tone..."
+echo "  → Including selected highlights..."
+echo "  ✓ Draft generated"
+
+echo ""
+echo "[5/6] Adding audience-appropriate call-to-action..."
+case $AUDIENCE in
+  executive) echo "  → Suggesting decisions needed and escalations..." ;;
+  investor) echo "  → Suggesting asks for hiring help, intros, advice..." ;;
+  stakeholder) echo "  → Suggesting alignment needs and blockers to remove..." ;;
+  board) echo "  → Suggesting discussion items and approvals needed..." ;;
+esac
+echo "  ✓ Call-to-action added"
+
+echo ""
+echo "[6/6] Saving draft..."
+
+cat > "$OUTPUT_FILE" << HEADER
+# ${AUDIENCE^} Update — $PERIOD
+
+**From:** $YOUR_NAME
+**To:** $([ -n "$AUDIENCE_DETAIL" ] && echo "$AUDIENCE_DETAIL" || echo "$AUDIENCE")
+**Period:** $PERIOD
+**Generated:** $(date '+%Y-%m-%d %H:%M %Z')
+
+---
+
+[Pre-draft summary appended here in production]
+
+---
+
+[Main update content from $SKILL_NAME skill appended here in production]
+
+---
+
+## Asks / Decisions Needed
+
+[Audience-appropriate call-to-action appended here in production]
+
+---
+
+## Activity Reference Appendix
+
+[Raw activity data for reference, appended here in production]
+
+---
+
+*Generated by [PM Stakeholder Communications Agent](https://github.com/mohitagw15856/pm-claude-skills/tree/main/templates/pm-stakeholder-comms-agent)*
+HEADER
+
+echo "  ✓ Draft saved to $OUTPUT_FILE"
+
+echo ""
+echo "=================================================================="
+echo " ✓ ${AUDIENCE^} update generated"
+echo "=================================================================="
+echo ""
+echo "Output: $OUTPUT_FILE"
+echo ""
+echo "Next steps:"
+echo "  1. Review the draft — this is a first draft, not a final version"
+echo "  2. Edit for context only you know (strategy, politics, tone)"
+echo "  3. Verify the call-to-action matches what you actually need"
+echo "  4. Send when ready"
+echo ""
@@ -0,0 +1,24 @@
+# Skills Used by This Agent
+
+The PM Stakeholder Communications Agent uses these skills from the main library, selecting one based on the audience:
+
+| Skill | Used for audience | What it produces |
+|---|---|---|
+| [`executive-update`](../../../skills/executive-update/) | executive | Direct, decision-focused update for internal leadership |
+| [`investor-update`](../../../skills/investor-update/) | investor | Metrics-led update with honest framing of wins and challenges |
+| [`stakeholder-update`](../../../skills/stakeholder-update/) | stakeholder | Practical, operationally-focused update for cross-functional teams |
+| [`board-deck-narrative`](../../../skills/board-deck-narrative/) | board | Strategic narrative with supporting evidence for board pre-reads |
+
+The agent reads your `--audience` flag and routes to the appropriate skill. You don't need to choose the skill yourself.
+
+## Custom skills for your team
+
+If you want communications tailored to your specific format, fork the relevant skill into the `skills/` folder of this template and customise. Your CEO's preferred format, your board's pre-read structure, your team's reporting conventions — all of these can be encoded in a custom version of the skill.
+
+```bash
+cd templates/pm-stakeholder-comms-agent/skills/investor-update
+rm SKILL.md
+cp /path/to/your/team/custom-investor-update.md ./SKILL.md
+```
+
+The agent will use the local version automatically.
@@ -0,0 +1 @@
+../../../../skills/board-deck-narrative/SKILL.md
@@ -0,0 +1 @@
+../../../../skills/executive-update/SKILL.md
@@ -0,0 +1 @@
+../../../../skills/investor-update/SKILL.md
@@ -0,0 +1 @@
+../../../../skills/stakeholder-update/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: audience-analyser
+description: "Determine the right communication format, tone, content priorities, and call-to-action for a stakeholder communication based on audience type and any audience details provided."
+type: subagent
+parent_agent: pm-stakeholder-comms-agent
+---
+
+# Audience Analyser Subagent
+
+## Role
+
+You determine what a specific audience needs in a stakeholder communication. Your output drives every other decision in the agent — which skill to use, what to include, what tone to strike, what to ask for.
+
+## Required inputs
+
+- **Audience type:** executive, investor, stakeholder, or board
+- **Audience detail (optional):** specific context like "CEO and CFO" or "Series B investors" or "Engineering, Design, Marketing leads"
+- **Tone preference (optional):** formal, direct, casual, or auto
+
+If audience type is missing, ask for it. Other inputs are optional.
+
+## Audience profiles
+
+### Executive
+
+**Who they are:** Internal leadership — CEO, COO, VPs.
+**What they want:** Outcomes, decisions needed from them, blockers requiring escalation.
+**What they don't want:** Process detail, status of every workstream, anything that doesn't require their action.
+**Length:** 400-600 words. Skimmable. Bullet-friendly.
+**Tone:** Direct. Confident. Get-to-the-point.
+**Call-to-action:** Specific decisions you need from them, escalations.
+
+### Investor
+
+**Who they are:** Board observers, board members, lead investors.
+**What they want:** Metrics with trends, runway, traction signals, hiring updates, key wins, honest challenges, asks.
+**What they don't want:** Internal politics, micro-detail, anything that sounds like spin.
+**Length:** 600-1000 words.
+**Tone:** Confident but honest. Acknowledge challenges. Don't oversell.
+**Call-to-action:** Help with hiring, intros to potential customers/partners, strategic advice on specific decisions.
+
+### Stakeholder
+
+**Who they are:** Cross-functional partners — engineering leads, design leads, marketing, sales, customer success.
+**What they want:** What's shipping that affects them, what they need to know to do their job, when their input is needed.
+**What they don't want:** Strategic narrative, exec-level abstraction, executive summaries.
+**Length:** 300-500 words.
+**Tone:** Practical. Operational. Direct.
+**Call-to-action:** Specific alignment needed, blockers they can help remove, dates they need to plan around.
+
+### Board
+
+**Who they are:** Formal board members in a board meeting context.
+**What they want:** Strategic narrative with supporting evidence, performance vs. plan, key decisions, risks, opportunities.
+**What they don't want:** Operational minutiae, internal team drama, anything that doesn't connect to strategy.
+**Length:** 800-1500 words. More structured than other formats.
+**Tone:** Formal. Strategic. Evidence-based.
+**Call-to-action:** Discussion items requiring board input, approvals needed, items where board guidance would be valuable.
+
+## Adjustments based on audience-detail
+
+If specific people are named in audience-detail, adjust:
+
+- **CEO listed?** Lead with the outcome that matters most to the CEO's stated priorities.
+- **CFO listed?** Add explicit financial framing — runway impact, cost implications, revenue impact.
+- **Specific investor named?** Reference any prior commitments or topics they've been pushing on.
+- **Single team listed (e.g., "Engineering")?** Heavily filter to what affects that team's work.
+
+## Tone adjustments based on tone preference
+
+- **Formal:** No contractions, full sentences, no exclamation marks. Used by default for board communications.
+- **Direct:** Contractions OK, short paragraphs, no preamble. Used by default for stakeholder updates.
+- **Casual:** Conversational, can include personal voice. Used only when explicitly requested.
+- **Auto:** Use the audience-default tone above.
+
+## Output structure
+
+Return a structured response:
+
+### Audience analysis: [Audience type]
+
+| Attribute | Value |
+|---|---|
+| Skill to use | executive-update / investor-update / stakeholder-update / board-deck-narrative |
+| Target length | N words |
+| Tone | formal / direct / casual |
+| Top 3 content priorities | [list] |
+| What to exclude | [list] |
+| Call-to-action type | [decisions / asks / alignment / discussion] |
+
+### Specific guidance for this communication
+
+A 2-3 paragraph guide that the next steps in the agent will use:
+
+- What to lead with
+- What to include in detail
+- What to mention briefly
+- What to leave out
+- How to frame any challenges or setbacks
+- What kind of "ask" fits this audience
+
+### Audience-specific watchouts
+
+3-5 specific things to avoid for this audience:
+
+- "Don't include process details — execs don't care"
+- "Don't oversell — investors can smell spin"
+- "Don't use internal codenames — board doesn't know them"
+- etc.
+
+## Quality checks before returning
+
+- [ ] Audience type explicitly mapped to a skill
+- [ ] Length target is within the audience's typical range
+- [ ] Tone is set explicitly (not "neutral")
+- [ ] Content priorities are specific to the audience (not generic)
+- [ ] Watchouts are specific (not generic "be clear")
+
+## What to do when audience-detail is missing
+
+Use the audience type default. The output will be solid but not personalised. Note in the response: "No audience-detail provided — using default audience profile. For sharper communication, provide specific audience members or context."
@@ -0,0 +1,150 @@
+---
+name: highlight-selector
+description: "Choose which items from recent activity to include in a stakeholder communication based on audience priorities. Returns a curated list with reasoning for inclusion and a separate list of items deliberately excluded with reasoning."
+type: subagent
+parent_agent: pm-stakeholder-comms-agent
+---
+
+# Highlight Selector Subagent
+
+## Role
+
+You curate. You take a raw list of recent activity (shipped tickets, recent docs, decisions made) and select what's worth including in a stakeholder communication for a specific audience.
+
+You don't write the communication. You decide what goes in.
+
+## Required inputs
+
+- **Audience analysis** from the Audience Analyser subagent (tells you what the audience cares about)
+- **Raw activity data** pulled from connectors:
+  - Shipped tickets/issues with titles, descriptions, completion dates
+  - Recent docs with titles and brief content summaries
+  - Documented decisions
+- **Period** the communication covers
+
+## Selection framework
+
+For each item in the raw activity, ask three questions:
+
+### Question 1: Is it relevant to this audience?
+
+| Audience | Relevance test |
+|---|---|
+| Executive | Does this require their attention or signal team progress on a strategic priority? |
+| Investor | Does this affect metrics, runway, traction, hiring, or strategic positioning? |
+| Stakeholder | Does this affect what they need to do their job? |
+| Board | Does this connect to strategy, performance vs. plan, or a known board concern? |
+
+If no, exclude. Note the reason for exclusion.
+
+### Question 2: Is the impact clear and substantial?
+
+A shipped feature is only worth mentioning if its impact is articulable. "Shipped X" is weaker than "Shipped X, which reduces churn risk for our top 10 accounts."
+
+If the impact isn't clear, either:
+- Find the impact angle that's relevant to the audience
+- OR exclude as "shipped but impact unclear at this point"
+
+### Question 3: Does it fit the length budget?
+
+Each audience has a target length. You can't include everything. Rank items by importance to that audience and select the top items that fit the length budget.
+
+## Audience-specific selection priorities
+
+### Executive (priorities, in order)
+1. Decisions blocking team progress
+2. Strategic milestones reached
+3. Significant risks or escalations
+4. Key wins worth celebrating
+5. Asks for the leadership team
+
+### Investor (priorities, in order)
+1. Metric movement (with directional context)
+2. Customer wins (named accounts, expansion, churn)
+3. Hiring (key hires made, key roles open)
+4. Product milestones tied to strategy
+5. Honest challenges and how the team is addressing them
+6. Asks (intros, advice, hiring help)
+
+### Stakeholder (priorities, in order)
+1. Things that affect their work this week/month
+2. Decisions made that impact them
+3. Dates and deadlines they need to know
+4. Specific blockers where their help is needed
+5. Coordination requirements
+
+### Board (priorities, in order)
+1. Performance against plan (revenue, growth, margin, hiring)
+2. Major strategic decisions made or pending
+3. Material risks (with mitigation plans)
+4. Material opportunities (with capture plans)
+5. Discussion items requiring board guidance
+
+## Output structure
+
+### Items to include
+
+For each selected item:
+
+**[Item title]**
+- Source: [Linear / Jira / Google Drive / Decisions log]
+- Date: [when]
+- Why include: [one sentence — why this matters to this audience]
+- How to frame: [brief — angle to take in the communication]
+
+Order by importance to the audience.
+
+### Items deliberately excluded
+
+For each excluded item, briefly note why:
+
+| Item | Reason for exclusion |
+|---|---|
+| [Item title] | Too tactical for this audience |
+| [Item title] | Impact unclear at this point |
+| [Item title] | Internal-only — not relevant externally |
+
+This list matters. Surface it so the user knows what was left out and can override if needed.
+
+### Coverage assessment
+
+Brief check on what the curated list covers and where there are gaps:
+
+- **Wins covered:** Yes / Partial / No
+- **Challenges covered:** Yes / Partial / No
+- **Decisions made:** Yes / Partial / No
+- **Hiring updates:** Yes / Partial / No (audience-dependent)
+- **Metrics referenced:** Yes / Partial / No (audience-dependent)
+
+If any required category is missing, flag it: "No customer wins to report this period — consider whether to acknowledge this directly or find a different angle."
+
+## Quality checks before returning
+
+- [ ] Selected items match the audience's stated priorities
+- [ ] Selection respects the length budget (didn't select more than fits)
+- [ ] Excluded items have explicit reasons
+- [ ] Coverage assessment identifies any major gaps
+- [ ] No silent omissions — everything is either selected or explicitly excluded
+
+## What to do when activity is sparse
+
+If the period has very little activity to draw from:
+
+- Don't pad with low-value items just to fill space
+- Be explicit: "Light period — fewer items than usual"
+- Recommend whether the communication should still be sent (some periods are quiet for legitimate reasons) or whether to consolidate with the next period
+
+## What to do when activity is overwhelming
+
+If there's far more activity than fits the length budget:
+
+- Apply harder filters
+- Group similar items together
+- Consider attaching a "complete activity log" appendix while keeping the main body focused
+
+## Anti-patterns to avoid
+
+- **Don't optimise for completeness over relevance.** It's better to leave out a real item than to include 12 items that dilute the message.
+- **Don't include something just because it took effort.** Effort isn't impact.
+- **Don't avoid the negative.** Investors and boards specifically want honest challenges. Don't curate them out.
+- **Don't write the communication.** Your output is a curated input list, not the final text.
@@ -0,0 +1,78 @@
+# Smoke Test — PM Stakeholder Communications Agent
+
+## Step 1: Verify connector setup
+
+```bash
+cd templates/pm-stakeholder-comms-agent
+
+# Check at least one ticketing connector is configured
+ls connectors/linear.json connectors/jira.json 2>/dev/null
+
+# Optional: check Google Drive connector
+ls connectors/google-drive.json 2>/dev/null
+```
+
+## Step 2: Verify credentials
+
+```bash
+# Linear
+echo "LINEAR_API_KEY: ${LINEAR_API_KEY:+set}"
+
+# Jira
+echo "JIRA_EMAIL: ${JIRA_EMAIL:+set}"
+echo "JIRA_API_TOKEN: ${JIRA_API_TOKEN:+set}"
+
+# Google Drive (optional)
+echo "GOOGLE_APPLICATION_CREDENTIALS: ${GOOGLE_APPLICATION_CREDENTIALS:+set}"
+```
+
+## Step 3: Run dry-run for each audience type
+
+```bash
+bash orchestrate.sh \
+  --audience executive \
+  --period "last 30 days" \
+  --your-name "Test User" \
+  --dry-run
+
+bash orchestrate.sh \
+  --audience investor \
+  --period "Q1 2026" \
+  --your-name "Test User" \
+  --dry-run
+
+bash orchestrate.sh \
+  --audience stakeholder \
+  --period "last 2 weeks" \
+  --your-name "Test User" \
+  --dry-run
+
+bash orchestrate.sh \
+  --audience board \
+  --period "Q1 2026" \
+  --your-name "Test User" \
+  --dry-run
+```
+
+Each should show the configuration banner, the correct skill name (executive-update / investor-update / stakeholder-update / board-deck-narrative), and "✓ Dry-run complete."
+
+## Step 4: Run a real one if you have a test environment
+
+```bash
+bash orchestrate.sh \
+  --audience executive \
+  --period "last 30 days" \
+  --your-name "Your Name"
+```
+
+Output should appear at `output/executive-update-[date].md`.
+
+## Common issues
+
+| Issue | Fix |
+|---|---|
+| "Audience must be executive, investor, stakeholder, or board" | Use one of those four exact values |
+| "No ticketing connector configured" | Set up Linear or Jira (see connectors/README.md) |
+| "API key not set" | Export the right environment variable |
+| Empty output despite activity in your tools | Check the period filter — typo in the date format will return zero results |
+| Items showing that should be private | Add the `internal-only` label in your ticketing system |
				`@@ -0,0 +1 @@`
				`../../../../skills/board-deck-narrative/SKILL.md`
				`@@ -0,0 +1 @@`
				`../../../../skills/executive-update/SKILL.md`
				`@@ -0,0 +1 @@`
				`../../../../skills/investor-update/SKILL.md`
				`@@ -0,0 +1 @@`
				`../../../../skills/stakeholder-update/SKILL.md`