Mail System

Asynchronous communication system for Product Owner, Lead Developer, and Stakeholder roles, backed by SQLite for message tracking, threading, and read status.

Roles

Role	Description
product-owner	Claude as Product Owner (requirements, issues, documentation)
lead-developer	Claude as Lead Developer (technical review, code quality)
stakeholder	The human user (decisions, approvals, direction)

Setup

First time setup (run from project root):

# Navigate to the plugin's skill directory and install dependencies
cd "${CLAUDE_PLUGIN_ROOT}/skills/mail-system" && npm install && npm run init

This creates:

• Mail directories in your project (mail/product-owner/, mail/lead-developer/, mail/stakeholder/)
• SQLite database (mail.db) in the skill directory

Web UI

Launch the web interface:

cd "${CLAUDE_PLUGIN_ROOT}/skills/mail-system" && npm run ui

Then open http://localhost:3333 in your browser.

Features:

• View all inboxes (Product Owner, Lead Developer, Stakeholder)
• Compose and send messages
• Reply to threads
• Mark messages as read
• Archive messages
• Auto-refresh every 30 seconds

Commands

All commands run from the skill directory (${CLAUDE_PLUGIN_ROOT}/skills/mail-system/):

Check Inbox

# List unread messages
node scripts/list.js product-owner
node scripts/list.js lead-developer

# List all messages (including read)
node scripts/list.js product-owner --all

Send Message

# New message (creates new thread)
node scripts/send.js --from product-owner --to lead-developer --subject "Sprint Review Feedback"

# Reply to existing thread
node scripts/send.js --from lead-developer --to product-owner --subject "Re: Sprint Review" --thread thread-2025-01-20-sprint-review

# Message to stakeholder (for decisions)
node scripts/send.js --from product-owner --to stakeholder --subject "Decision Needed: Auth Approach"

Mark as Read

node scripts/read.js msg-2025-01-20-abc123
node scripts/read.js 2025-01-20-sprint-review.md

Archive Message

node scripts/archive.js msg-2025-01-20-abc123

View Threads

# List all threads
node scripts/thread.js --list

# View specific thread
node scripts/thread.js thread-2025-01-20-sprint-review

Folder Structure

your-project/
└── mail/                        # Created in project root
    ├── product-owner/           # Messages TO Product Owner
    │   └── archive/
    ├── lead-developer/          # Messages TO Lead Developer
    │   └── archive/
    └── stakeholder/             # Messages TO Stakeholder (human)
        └── archive/

${CLAUDE_PLUGIN_ROOT}/skills/mail-system/
├── SKILL.md                     # This file
├── package.json                 # Dependencies
├── schema.sql                   # Database schema
├── mail.db                      # SQLite database (created on init)
└── scripts/
    ├── db.js                    # Database utilities
    ├── init-db.js               # Initialize system
    ├── send.js                  # Send message
    ├── list.js                  # List inbox
    ├── read.js                  # Mark as read
    ├── archive.js               # Archive message
    ├── thread.js                # View threads
    └── server.js                # Web UI server

Message Format

Messages are created with YAML frontmatter for tracking:

---
id: msg-2025-01-20-abc123
thread: thread-2025-01-20-sprint-review
from: lead-developer
to: product-owner
date: 2025-01-20
---

# Subject

## Summary
Brief overview.

## Details
Full content.

## Action Required
- [ ] Actions needed

## Questions
1. Questions for recipient

---
From: lead-developer
Date: 2025-01-20

Threading

Messages are grouped into threads:

• New messages create a new thread
• Replies use --thread <thread-id> to join existing thread
• Use node scripts/thread.js --list to see all threads
• Use node scripts/thread.js <thread-id> to see thread history

Status Indicators

• ● Unread
• ✓ Read
• 📦 Archived

Workflow

As Product Owner

1. Check inbox: node scripts/list.js product-owner
2. Read message file, take action
3. Mark as read: node scripts/read.js <id>
4. Reply: node scripts/send.js --from product-owner --to lead-developer --subject "Re: ..." --thread <thread-id>
5. Escalate to stakeholder if needed: node scripts/send.js --from product-owner --to stakeholder --subject "Decision Needed"
6. Archive when done: node scripts/archive.js <id>

As Lead Developer

1. Check inbox: node scripts/list.js lead-developer
2. Read message file, verify claims
3. Mark as read: node scripts/read.js <id>
4. Reply: node scripts/send.js --from lead-developer --to product-owner --subject "Re: ..." --thread <thread-id>
5. Archive when done: node scripts/archive.js <id>

As Stakeholder (Human)

1. Check inbox: node scripts/list.js stakeholder
2. Read message file in mail/stakeholder/
3. Mark as read: node scripts/read.js <id>
4. Reply: node scripts/send.js --from stakeholder --to product-owner --subject "Re: ..." --thread <thread-id>
5. Archive when done: node scripts/archive.js <id>