Team Update

Team Update

Post project updates to team chat, read and triage feedback, and plan next steps. Adapts to whatever communication and project tools are available.

The Playbook Pattern

This skill uses a playbook file at .claude/team-update-playbook.md in the project root.

• First run: Discover available tools, ask the user for preferences, execute, save a playbook
• Subsequent runs: Read the playbook, skip discovery, execute directly
• User edits playbook: Changes take effect immediately (channel, style, triage rules)

The playbook is plain markdown the user can edit. It captures tool configuration, channel preferences, message style, triage rules, and last-run metadata.

---

Phase 0: Playbook Check

Check if .claude/team-update-playbook.md exists in the project root.

If it exists: Read it. All tool configuration, channel info, message style, and triage rules are in there. Jump to Phase 1 with known config.

If it does not exist: Run Phase 0b (Discovery) first.

---

Phase 0b: Discovery (First Run Only)

Detect available capabilities by checking what MCP tools are connected and what local tools exist.

Read references/discovery-patterns.md for detection patterns.

Capability Detection

Check for each capability category:

User Preferences (Ask)

After discovery, ask the user to confirm:

1. Channel: Which chat space/channel to post updates to? (List discovered options) 2. Identity: Post as yourself or a bot identity? (e.g. Anthro Morphic) 3. Repo scope: Which repo(s) to track? (Default: current repo) 4. Message style: Brief standup, detailed changelog, or conversational update? 5. Team context: Any team members to be aware of? (Names, roles) 6. Triage rules: Any custom rules for handling feedback? (Or use defaults)

Save Playbook

After discovery + user preferences, save the playbook to .claude/team-update-playbook.md.

Read references/playbook-format.md for the full template. Fill in all sections with discovered tools and user preferences. If a capability was not found, note it as "Not available" in the playbook.

Ensure .claude/ is in .gitignore (the playbook contains space IDs and preferences that shouldn't be committed).

---

Phase 1: Gather Context

Collect information from all available sources. Use the playbook's "Data Sources" section to know which tools to call.

1a. Determine Time Window

Check the playbook's "Last Run" section for the last update timestamp. If no previous run, ask the user how far back to go (default: 24 hours).

1b. Collect Data

Gather from each available source:

1c. Summarise for Drafting

Group commits by theme (not individual hashes). Note any issues closed, PRs merged, or tasks completed. Flag any team messages that need response.

---

Phase 2: Draft and Post Update

2a. Compose Message

Read references/message-composition.md for message patterns.

Follow the playbook's "Message Style" section. General principles:

• Lead with what shipped or changed, not process
• Group related commits into themes
• Mention specific people only when relevant
• Keep it scannable (short paragraphs, bullet points)
• Write like a teammate, not an AI — no emoji spam, no hedging, no over-explaining context the team already has. See the Communication Style section in references/message-composition.md.

2b. Preview and Approval

Show the draft to the user. Include:

• The composed message
• Which channel it will be posted to
• Whether it's a new message or thread reply

APPROVAL REQUIRED: Never post to external channels without explicit user approval.

2c. Post

Post the approved message using the chat tool from the playbook. If no chat tool is available, output the formatted message for the user to post manually.

2d. Update Playbook

After posting, update the "Last Run" section of the playbook with:

• Current timestamp
• Thread key (if applicable)
• Brief summary of what was posted

---

Phase 3: Read and Triage Feedback

3a. Read Responses

Read messages from the configured channel since the update was posted. Look for:

• Direct replies to the update
• New messages in the channel that reference the project
• Reactions or acknowledgements

3b. Classify Feedback

Read references/feedback-triage.md for classification patterns.

Use the playbook's "Triage Rules" section. Default classification:

3c. Present and Act

Present a summary of feedback with proposed actions:

## Feedback Summary

- Daniel: "Can we add dark mode?" -> Create issue (enhancement)
- Rabin: "Auth is broken on staging" -> Create issue (bug, priority)
- Karen: "Looks good!" -> No action

Proceed with these actions?

APPROVAL REQUIRED: Never create issues, post replies, or take external actions without explicit user approval.

---

Phase 4: Plan Next Steps

4a. Prioritise

From all gathered context (commits, issues, tasks, feedback), identify: 1. Blockers: Things preventing progress 2. High-priority: Bugs, urgent requests, deadlines 3. Next up: Planned work, feature requests 4. Backlog: Nice-to-haves, low-priority items

4b. Present (Not Posted)

Show the prioritised list to the user. This is for the user's planning only -- do NOT post it to any channel.

## Suggested Priorities

1. [BLOCKER] Fix auth on staging (from Rabin's feedback)
2. [HIGH] Complete API endpoint for user profiles (current sprint)
3. [NEXT] Dark mode support (from Daniel's request)
4. [BACKLOG] Refactor database queries

---

Autonomy Rules

---

Graceful Degradation

The skill works at any level of tool availability:

---

Operating Modes

The skill responds to different trigger phrases:

---

Reference Files

Discovery Patterns

How to detect available MCP tools by capability category during first-run discovery.

Detection Strategy

List all available MCP tools by checking what's loaded in the current session. MCP tool names follow the pattern mcp__<server>__<tool>. Match tool names against these patterns to categorise capabilities.

Chat Tools

Look for tools that can send and read messages in team channels.

What to capture: The exact tool name, which server it belongs to, and whether it supports threading.

Fallback: If no chat tools are found, the skill outputs formatted text for the user to copy-paste into their preferred channel.

Git

Not an MCP tool. Detect with:

git rev-parse --is-inside-work-tree 2>/dev/null

If true, git is available. Capture the repo name from the directory or git remote get-url origin.

Issue Trackers

What to capture: Tool name, whether it supports creating issues, available label schemes.

Task Trackers

Knowledge

What to capture: Whether Basalt Cortex vault exists and has relevant data.

Discovery Output

After detection, present a summary to the user:

## Discovered Capabilities

- Chat: Google Chat (via google-chat-anthro)
- Git: Yes (jezweb/my-project on branch main)
- Issues: GitHub (via github MCP)
- Tasks: Brain (via brain MCP)
- Knowledge: Vault (via vault MCP)

Missing:
- (none — all capabilities available)

Which chat space should I post updates to?

If multiple options exist for a category (e.g. two chat servers), ask the user which one to use.

Re-Discovery

If a tool becomes unavailable after the playbook was saved (MCP server disconnected), the skill should:

1. Note the missing tool in its output 2. Fall back gracefully (skip that data source, or output text instead of posting) 3. Suggest updating the playbook if the change is permanent

Feedback Triage

How to classify and act on team responses to project updates.

Classification Table

Signal Detection

Bug Reports

Look for language indicating something is broken or not working:

• "X is broken", "X doesn't work", "X crashes"
• "I'm getting an error when..."
• "This used to work but now..."
• Error screenshots or stack traces
• "Can't login", "page won't load", "data is wrong"

Feature Requests

Look for language suggesting new capability:

• "Can we add...", "It would be nice if..."
• "What about...", "Have you considered..."
• "We need...", "Clients are asking for..."
• Comparisons to other tools ("X does this, can we...")

Blockers

Look for urgency and dependency language:

• "I can't continue until...", "This is blocking..."
• "The client needs this by...", "Deadline is..."
• "Production is down", "Users are affected"
• Explicit escalation ("urgent", "critical", "ASAP")

Questions

Look for inquiry language without urgency:

• "How does X work?", "Where is the setting for..."
• "When will X be ready?", "What's the plan for..."
• "Can you explain...", "I'm not sure how to..."

Action Templates

Creating an Issue (Bug)

Title: [Brief description from feedback]
Body:
  Reported by: [team member name] in [channel name]
  Date: [timestamp]

  ## Description
  [Feedback content, quoted]

  ## Context
  [Any additional context from the conversation]

Labels: bug

Creating an Issue (Feature Request)

Title: [Feature description]
Body:
  Requested by: [team member name] in [channel name]
  Date: [timestamp]

  ## Request
  [Feedback content, quoted]

  ## Notes
  [Any discussion or context]

Labels: enhancement

Drafting a Reply

When drafting a reply to a question, follow the playbook's message style. Keep replies:

• Concise and direct
• In the same thread as the question
• Factual (don't speculate if unsure)

Always show the draft to the user before posting.

Presentation Format

After classifying all feedback, present a summary:

## Feedback Summary (3 items)

1. [Bug] Daniel: "Auth is broken on staging when using Safari"
   -> Create GitHub issue (bug) — "Safari auth failure on staging"

2. [Feature] Karen: "Can we add a CSV export for reports?"
   -> Create GitHub issue (enhancement) — "CSV export for reports"

3. [Ack] Rabin: "Nice work on the API endpoints"
   -> No action

Proceed with actions 1-2?

Approval Flow

Never auto-execute actions from triage. Always present the summary and get explicit approval. The user may want to:

• Reclassify an item (e.g. "that's not a bug, it's expected behaviour")
• Skip an action (e.g. "don't create an issue for that, I'll handle it directly")
• Modify the action (e.g. "create the issue but label it 'priority' too")
• Respond differently (e.g. "reply to Karen's request, don't create an issue")

Handling Ambiguity

If feedback doesn't clearly fit a category:

1. Default to Question — safer than creating unwanted issues 2. Present it to the user with your best guess and reasoning 3. Let the user decide the classification

Message Composition

Patterns for composing team update messages across different channels.

General Principles

1. Lead with outcomes: What shipped, what changed, what's new. Not "I worked on X" but "X is now live". 2. Group by theme: Don't list 12 individual commits. Group them: "Auth rework (5 commits)", "Bug fixes (3)". 3. Scannable format: Short paragraphs, bullet points, bold for key items. People skim chat. 4. Include links: PR links, deployed URLs, issue references. Make it easy to dive deeper. 5. Flag blockers early: If something needs attention, put it at the top, not buried at the bottom.

Message Structure

[Status emoji or label] Project Update — [date or timeframe]

**Shipped**
- [What was completed — outcome, not process]
- [Another completed item with link]

**In Progress**
- [What's being worked on — expected completion]

**Needs Attention** (if any)
- [Blocker or question that needs team input]

**Up Next**
- [What's planned next]

Channel-Specific Formatting

Google Chat

Google Chat uses non-standard markdown. Key differences:

• Bold: *text* (single asterisk, not double)
• Italic: _text_ (underscore)
• Links: <url|text> (pipe separator, not markdown links)
• No headings, tables, or blockquotes
• Strikethrough: ~text~

Example:

*Project Update* — 8 March

*Shipped*
- Auth flow reworked — login/signup now under 2 seconds
- 3 new API endpoints for user profiles (<https://github.com/org/repo/pull/42|PR #42>)
- Fixed: dashboard crash on empty data (<https://github.com/org/repo/issues/15|#15>)

*In Progress*
- Dark mode support (60% complete, targeting Monday)

*Needs Attention*
- Staging DB running low on storage — need to clean up test data or resize

Slack

Standard markdown plus Slack-specific blocks:

• Bold: *text*
• Links: <url|text>
• Code: ` code ` or triple backtick blocks
• Supports block elements for richer formatting

Plain Text (Manual Posting)

When no chat tool is available, output clean text that can be pasted anywhere:

PROJECT UPDATE — 8 March

SHIPPED
- Auth flow reworked — login/signup now under 2 seconds
- 3 new API endpoints for user profiles (PR #42)

IN PROGRESS
- Dark mode support (60% complete)

NEEDS ATTENTION
- Staging DB storage running low

Commit Grouping

Don't list raw commits. Group them by theme:

Input (raw commits)

abc1234 fix: login redirect loop
def5678 fix: signup validation error on mobile
ghi9012 feat: add /api/users/profile endpoint
jkl3456 feat: add /api/users/avatar endpoint
mno7890 feat: add /api/users/settings endpoint
pqr1234 chore: update dependencies
stu5678 fix: dashboard null pointer on empty state

Output (grouped)

- Auth fixes: resolved login redirect loop and mobile signup validation (2 commits)
- User profile API: 3 new endpoints — profile, avatar, settings
- Dashboard: fixed crash when loading with empty data
- Maintenance: dependency updates

Length Guidelines

If the update is unusually large (major release, sprint completion), consider a card format or a separate detailed post with a brief summary in the main channel.

Communication Style

Team updates must read like a human teammate wrote them. Claude's default output voice — over-structured, hedging, emoji-laden, over-explaining — is immediately recognisable and erodes trust. The team should glance at the message and absorb it, not think "the AI posted again."

Voice Rules

Keep it flat and factual. State what changed. Don't narrate the journey.

# BAD — Claude voice
✅ *Great news!* The authentication flow has been successfully reworked! 🎉
We addressed the redirect loop issue that was causing problems for users
attempting to log in. Additionally, we've implemented three new API endpoints
for user profile management, which will enable more granular control over...

# GOOD — teammate voice
*Shipped*
- Auth fixed — was a redirect loop on login
- 3 new user profile endpoints (profile, avatar, settings)

What to Avoid

Assume Context

The team has been reading these updates for weeks or months. They know:

• What the project is
• What stack it uses
• What was being worked on last time
• Who the team members are

Don't re-establish any of this. If the last update said "starting dark mode", this update can just say "dark mode — 60% done, targeting Monday." No need to explain what dark mode is or why it matters.

Length

Shorter is almost always better. A 5-line update that gets read beats a 20-line update that gets skimmed. If in doubt, cut it in half.

Tone

• Factual — state what happened, not how hard it was
• Forward-looking — end with what's next, not just what's done
• Team-aware — mention people when their input is needed, not for credit
• Terse over thorough — chat is not documentation

Playbook Format

Save this file at .claude/team-update-playbook.md in the project root. Fill in all sections based on discovery results and user preferences. Mark unavailable capabilities as "Not available".

Template

# Team Update Playbook

Generated by the team-update skill. Edit this file to change behaviour.

## Channel

- **Type**: [Google Chat | Slack | Discord | Teams | Manual (no chat tool)]
- **MCP tool**: [tool name, e.g. mcp__google-chat-jez__chat_messages | "none"]
- **Space/Channel**: [name] (ID: [space/channel ID])
- **Thread strategy**: [new-message | continue-thread | thread-per-day]
- **Identity**: [Post as self | Post as Anthro Morphic | other]

## Data Sources

### Git
- **Repo**: [repo path or "current directory"]
- **Branch filter**: [all | main only | specific branches]

### Chat (Read)
- **MCP tool**: [tool name for reading messages | "same as Channel"]
- **Read scope**: [same channel as posting | additional channels]

### Issues
- **Type**: [GitHub | Linear | Jira | Brain | none]
- **MCP tool**: [tool name | "none"]
- **Repo/Project**: [owner/repo or project name]
- **Create labels**: [bug, enhancement | custom labels]

### Tasks
- **Type**: [Brain | Asana | Linear | none]
- **MCP tool**: [tool name | "none"]
- **Project filter**: [project name | "all"]

### Knowledge Store
- **Type**: [Vault | Brain | none]
- **MCP tool**: [tool name | "none"]
- **Tags**: [tags for storing/retrieving update history]

## Message Style

- [Lead with what shipped, not process]
- [Group commits by theme, not individual hashes]
- [Keep under N lines for chat, use card format for bigger updates]
- [Address team members by first name]
- [Sign-off: none for chat, name for email]
- [Tone: conversational | formal | brief]

## Triage Rules

| Feedback type | Action | Tool |
|---|---|---|
| Bug report | Create issue (label: bug) | [issue tool] |
| Feature request | Create issue (label: enhancement) | [issue tool] |
| Question | Draft reply for approval | [chat tool] |
| Blocker | Flag immediately | Present to user |
| Acknowledgement | Note, no action | - |
| Off-topic | Ignore | - |

## Team Context

- [Name]: [Role/area — helps with triage and @mentions]
- [Name]: [Role/area]

## Last Run

- **Date**: [ISO 8601 timestamp with timezone]
- **Thread key**: [thread ID or key if applicable]
- **Summary**: [1-2 line summary of what was posted]
- **Feedback processed**: [yes/no, count of items triaged]

Section Notes

Channel

• Thread strategy: new-message posts a fresh top-level message each time. continue-thread replies to the same thread. thread-per-day creates one thread per day.
• Identity: If using a bot identity (like Anthro), include any sign-off or persona rules.

Data Sources

• Mark any unavailable source as "none" so the skill skips it cleanly.
• For Git, all branches is usually correct for dev updates; main only for production-focused updates.

Message Style

• These are freeform guidelines the user can edit. The skill reads them as instructions.
• Common additions: "Include PR links", "Mention blockers first", "Use emoji for status".

Triage Rules

• The table maps feedback types to actions. Users can add custom rows.
• The "Tool" column tells the skill which MCP tool to use for that action.

Last Run

• Updated automatically after each successful post.
• The skill uses the date to determine the time window for gathering context.
• If this section is missing or empty, the skill asks the user how far back to look.