Company Messaging — Skill (Branch-Based v3)

Overview

Company Savia enables async messaging between users across a company using orphan Git branches. Messages are plain markdown files with YAML frontmatter, stored in personal inboxes and a pub/sub exchange branch.

Branch Architecture

main (orphan)
  ├── company/identity.md, org-chart.md
  ├── pubkeys/user/{handle}.pem
  └── .savia-index/users.idx

user/{handle} (orphan)
  ├── inbox/unread/        ← Personal messages (unread)
  ├── inbox/read/          ← Personal messages (archive)
  └── outbox/              ← Sent message archive

exchange (orphan)
  └── pub/sub/pending/
      ├── {msg_id}.md      ← Pending delivery (temp)
      └── .index           ← Routing table by recipient

team/{name} (orphan)
  └── (shared team resources)

Message Lifecycle

1. Compose: Create message with YAML frontmatter
2. Encrypt (optional): RSA-4096 + AES-256-CBC via savia-crypto.sh
3. Deliver: Write to exchange:pub/sub/pending/{msg_id}.md
4. Sync: git add + commit + push to exchange branch
5. Pull: Recipient syncs and fetches from exchange:pub/sub/pending/
6. Move: Transfer to user/{handle}/inbox/unread/
7. Read: User moves to user/{handle}/inbox/read/
8. Archive: Old messages can be purged per retention policy

Fetch-Messages Workflow

git show exchange:pub/sub/pending/{msg_id}.md | decrypt | move to user/{handle}/inbox/unread/

No need to checkout exchange branch — just git show.

@Handle Resolution

Handles are resolved from main:company/directory.md (admin-only):

| Handle | Name | Role | Status |
|--------|------|------|--------|
| @admin | Admin Name | Admin | active |

Pubkeys stored at main:pubkeys/user/{handle}.pem.

Encryption Protocol

Hybrid RSA-4096 + AES-256-CBC (openssl only, zero deps):

1. Keygen: openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096
2. Encrypt: Random AES-256 key → encrypt body → encrypt AES key with recipient RSA pubkey
3. Store: Base64-encoded encrypted_key:::encrypted_body in frontmatter
4. Decrypt: RSA-decrypt AES key (private.pem: chmod 600) → AES-decrypt body

Public keys auto-published to main:pubkeys/user/{handle}.pem by admin script.

Privacy Rules

Before any git push:

1. Layer 1: validate_privacy() — PATs, tokens, IPs, connection strings
2. Layer 2: Scan YAML frontmatter and body for secrets
3. Layer 3: Verify subject line has no sensitive data (see messaging-subject-safety.md)

Script: scripts/privacy-check-company.sh

Message Types

Type	Location	Persist	Encrypted
Direct message	exchange:pending → user/{handle}/inbox/unread/	7 days	Optional
Reply	user/{handle}/inbox/	Until archived	Optional
Broadcast	exchange:pending (deliver to each user/{handle})	7 days	Optional
Announcement	main:company/announcements/	Permanent	Never

Threading

Messages form threads via YAML frontmatter:

• thread: ID of first message
• reply_to: ID of message being replied to

Replies auto-inherit thread from parent.

Read Tracking

• Personal messages: moved from unread/ to read/ on user branch
• Announcements: tracked in $HOME/.pm-workspace/company-inbox-read.log

Scripts

Script	Purpose
scripts/savia-branch.sh	Abstraction layer for branch operations
scripts/savia-messaging.sh	Message CRUD (create, fetch, deliver, archive)
scripts/savia-crypto.sh	E2E encryption (RSA+AES)
scripts/privacy-check-company.sh	Privacy validation pre-push

Worktree Pattern

Writes use temporary worktrees to avoid checkout pollution:

git worktree add .claude/worktrees/{temp} user/{handle}
# Write/edit files
git add && git commit && git push
git worktree remove .claude/worktrees/{temp}

Session-Init Integration

Unread count from user/{handle}/inbox/unread/ (local, no network):

📬 3 unread messages · 1 pending broadcast