dot-agents 0.4.0 → 0.5.0

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.0",
+  "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"
   ],