dot-agents 0.4.1 → 0.5.0

package/internal/skills/channels/publish/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: channels/publish
+description: Publish a message to a channel or DM. Use this to post updates, session summaries, issues, or direct messages to personas.
+license: MIT
+---
+
+# Publish to Channel
+
+Post a message to a public channel (`#channel-name`) or direct message a persona (`@persona-name`).
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Posting a session summary to `#sessions`
+- Reporting an issue or blocker to `#issues`
+- Sending a direct message to another persona
+- Escalating to `@human` for human intervention
+- Broadcasting status updates or notifications
+
+## Process
+
+### Step 1: Determine Channel
+
+Choose the appropriate channel:
+
+| Channel         | Purpose                                  |
+| --------------- | ---------------------------------------- |
+| `#sessions`     | Session summaries and completion reports |
+| `#issues`       | Errors, blockers, and problems           |
+| `@human`        | Human escalation (use sparingly)         |
+| `@persona-name` | Direct message to another persona        |
+| `#custom`       | Any custom channel you've created        |
+
+### Step 2: Compose Message
+
+Format your message appropriately for the channel type.
+
+### Step 3: Publish
+
+```bash
+npx dot-agents channels publish "<channel>" "<message>"
+```
+
+For multi-line messages, use a heredoc:
+
+```bash
+npx dot-agents channels publish "<channel>" "$(cat <<'EOF'
+Your multi-line
+message here
+EOF
+)"
+```
+
+Optional flags:
+
+- `--from <name>` - Set the sender name (defaults to current persona)
+- `--tags <tag1,tag2>` - Add tags to the message
+
+## Examples
+
+### Example 1: Session Summary
+
+```bash
+npx dot-agents channels publish "#sessions" "$(cat <<'EOF'
+**Workflow:** morning-paper
+**Status:** success
+**Duration:** 2m 30s
+
+Generated morning paper PDF with calendar events and weather.
+Delivered to Boox device successfully.
+EOF
+)"
+```
+
+### Example 2: Report an Issue
+
+```bash
+npx dot-agents channels publish "#issues" "$(cat <<'EOF'
+**Issue:** Calendar API returned empty response
+**Impact:** Morning paper missing today's events
+**Context:** Calendar skill executed but returned no events despite events existing
+
+**To Fix:**
+1. Check Calendar permissions in System Settings
+2. Run `dot-agents workflow run test-osx-permissions`
+
+**Blocked:** no
+EOF
+)"
+```
+
+### Example 3: DM to Another Persona
+
+```bash
+npx dot-agents channels publish "@channel-manager" "Please archive inactive channels older than 30 days"
+```
+
+### Example 4: Human Escalation
+
+```bash
+npx dot-agents channels publish "@human" "$(cat <<'EOF'
+Need macOS permission grant for Calendar access.
+
+Please open System Settings > Privacy & Security > Calendars
+and enable access for dot-agents.
+EOF
+)"
+```
+
+### Example 5: Message with Tags
+
+```bash
+npx dot-agents channels publish "#issues" "Build failed: missing dependency" --tags "urgent,build"
+```
+
+## Best Practices
+
+- Keep messages concise but complete
+- Use structured formats for issues (title, impact, context, fix steps)
+- Include relevant context (workflow name, duration, error messages)
+- Use tags to categorize messages for filtering
+- Reserve `@human` for genuine blockers requiring human action
+
+## Error Handling
+
+**Channel doesn't exist**: The channel will be created automatically on first publish.
+
+**Permission denied**: Ensure you're running with appropriate permissions (`--permission-mode bypassPermissions`).

package/internal/skills/channels/read/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: channels/read
+description: Read messages from a channel. Use this to check for new messages, review issue history, or catch up on session logs.
+license: MIT
+---
+
+# Read Channel Messages
+
+Retrieve and display messages from a public channel or DM inbox.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Checking for new issues or blockers in `#issues`
+- Reviewing recent session logs in `#sessions`
+- Reading your DM inbox (`@your-persona-name`)
+- Catching up on channel activity
+- Looking for messages with specific tags
+
+## Process
+
+### Step 1: Identify Channel
+
+Determine which channel to read:
+
+- `#sessions` - Session summaries
+- `#issues` - Reported problems
+- `@persona-name` - DMs sent to a persona
+- Any custom channel
+
+### Step 2: Read Messages
+
+```bash
+npx dot-agents channels read "<channel>"
+```
+
+Optional flags:
+
+- `--since <duration>` - Only messages from last N hours/days (e.g., `24h`, `7d`)
+- `--limit <n>` - Maximum number of messages to return
+- `--tags <tag1,tag2>` - Filter by tags
+
+### Step 3: Process Results
+
+Messages are returned in chronological order with metadata:
+
+- Message ID
+- Timestamp
+- Sender (from)
+- Content
+- Reply count (if any)
+
+## Examples
+
+### Example 1: Read Recent Issues
+
+```bash
+npx dot-agents channels read "#issues" --since 24h
+```
+
+Output:
+
+```text
+#issues (2 messages)
+
+[2025-12-15T10:30:00Z] from: morning-paper
+**Issue:** Calendar API timeout
+**Impact:** No events in morning paper
+...
+(1 reply)
+
+[2025-12-15T14:45:00Z] from: inbox-processor
+**Issue:** Missing attachment in email
+...
+```
+
+### Example 2: Check Your DM Inbox
+
+```bash
+npx dot-agents channels read "@channel-manager"
+```
+
+### Example 3: Filter by Tags
+
+```bash
+npx dot-agents channels read "#issues" --tags "urgent"
+```
+
+### Example 4: Limit Results
+
+```bash
+npx dot-agents channels read "#sessions" --limit 5
+```
+
+### Example 5: Read All Messages from Last Week
+
+```bash
+npx dot-agents channels read "#sessions" --since 7d
+```
+
+## Best Practices
+
+- Use `--since` to avoid processing old, irrelevant messages
+- Check `#issues` regularly for unresolved blockers
+- Look for reply counts to see if issues have been addressed
+- Use tags to filter for specific categories of messages
+
+## Output Format
+
+Messages are displayed with:
+
+- Timestamp in ISO 8601 format
+- Sender name
+- Full message content
+- Reply count indicator
+
+Empty channels return a message indicating no messages found.
+
+## Error Handling
+
+**Channel not found**: Returns empty result (channel may not exist yet).
+
+**No messages in time range**: Returns message indicating no messages match criteria.

package/internal/skills/channels/reply/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: channels/reply
+description: Reply to a specific message in a channel. Use this to respond to issues, answer questions, or continue threaded conversations.
+license: MIT
+---
+
+# Reply to Message
+
+Post a reply to an existing message, creating a threaded conversation.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Responding to a reported issue with a fix or update
+- Answering a question in a DM
+- Providing status updates on an ongoing issue
+- Continuing a conversation thread
+- Acknowledging receipt of a message
+
+## Process
+
+### Step 1: Identify the Message
+
+You need the message ID to reply to. Get this from:
+
+- The output of `channels read`
+- The message path (e.g., `2025-12-15T10:30:00.000Z`)
+
+### Step 2: Compose Reply
+
+Write your response to the original message.
+
+### Step 3: Post Reply
+
+```bash
+npx dot-agents channels reply "<channel>" "<message-id>" "<reply>"
+```
+
+For multi-line replies:
+
+```bash
+npx dot-agents channels reply "<channel>" "<message-id>" "$(cat <<'EOF'
+Your multi-line
+reply here
+EOF
+)"
+```
+
+## Examples
+
+### Example 1: Reply to an Issue
+
+Original message in `#issues`:
+
+```text
+[2025-12-15T10:30:00.000Z] from: morning-paper
+**Issue:** Calendar API timeout
+```
+
+Reply:
+
+```bash
+npx dot-agents channels reply "#issues" "2025-12-15T10:30:00.000Z" "$(cat <<'EOF'
+**Status:** Resolved
+
+Root cause: Network timeout due to VPN disconnection.
+Fix: Added retry logic with exponential backoff.
+
+Verified working in subsequent run.
+EOF
+)"
+```
+
+### Example 2: Quick Acknowledgment
+
+```bash
+npx dot-agents channels reply "@human" "2025-12-15T14:00:00.000Z" "Understood. Will proceed with the archive operation."
+```
+
+### Example 3: Request More Information
+
+```bash
+npx dot-agents channels reply "#issues" "2025-12-15T09:00:00.000Z" "$(cat <<'EOF'
+Need more details to investigate:
+
+1. Which workflow triggered this?
+2. What was the exact error message?
+3. Has this happened before?
+EOF
+)"
+```
+
+### Example 4: Status Update on Ongoing Issue
+
+```bash
+npx dot-agents channels reply "#issues" "2025-12-15T08:00:00.000Z" "$(cat <<'EOF'
+**Update:** Still investigating
+
+Tried:
+- Restarting daemon (no effect)
+- Clearing cache (no effect)
+
+Next steps:
+- Check system logs
+- Test with fresh config
+EOF
+)"
+```
+
+## Best Practices
+
+- Keep replies focused on the original topic
+- Use structured formats for status updates
+- Reference specific actions taken or planned
+- Close the loop on issues when resolved
+- Use replies rather than new messages for ongoing threads
+
+## Thread Structure
+
+Replies create a nested structure:
+
+```text
+channels/#issues/
+  2025-12-15T10:30:00.000Z/
+    message.md          # Original message
+    replies/
+      2025-12-15T11:00:00.000Z/
+        message.md      # First reply
+      2025-12-15T11:30:00.000Z/
+        message.md      # Second reply
+```
+
+## Error Handling
+
+**Message not found**: Verify the channel and message ID are correct.
+
+**Invalid message ID format**: Use the full ISO 8601 timestamp from the original message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dot-agents",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A framework for building agentic workflows with personas and scheduled execution",
   "type": "module",
   "main": "./dist/lib/index.js",
@@ -28,6 +28,7 @@
   },
   "files": [
     "dist",
+    "internal",
     "README.md",
     "LICENSE"
   ],