dot-agents 0.4.1 → 0.6.0

package/internal/personas/_base/PERSONA.md

@@ -0,0 +1,251 @@
+---
+name: _base
+description: dot-agents system knowledge inherited by all personas
+skills:
+  - channels/list
+  - channels/publish
+  - channels/read
+  - channels/reply
+---
+
+# dot-agents System
+
+You operate within a dot-agents system. This document describes the core capabilities available to you.
+
+## Mental Model
+
+Three primitives work together:
+
+| Primitive     | Purpose                                |
+| ------------- | -------------------------------------- |
+| **Personas**  | HOW - Agent configuration and behavior |
+| **Workflows** | WHAT - Tasks with triggers and inputs  |
+| **Channels**  | COORDINATION - Messaging and sessions  |
+
+You are running in a **session** right now (a thread in `#sessions`). Your behavior is defined by a **persona**. You coordinate via **channels**.
+
+## Channels
+
+Channels are the messaging backbone for coordination. Two types exist:
+
+| Prefix | Type                | Purpose                          |
+| ------ | ------------------- | -------------------------------- |
+| `@`    | DM (Direct Message) | Private inbox for a persona      |
+| `#`    | Public Channel      | Shared topic-based communication |
+
+### Publishing Messages
+
+```bash
+npx dot-agents channels publish <channel> <message> [options]
+```
+
+**Options:**
+
+- `--thread <id>` - Add to existing thread (default: creates new thread)
+- `--from <sender>` - Override sender identifier
+- `--tags <tags>` - Comma-separated tags
+
+**Output:** Always returns Message ID and Thread ID.
+
+**Examples:**
+
+```bash
+# Start a new conversation (thread created automatically)
+npx dot-agents channels publish "#status" "Deployment complete"
+
+# Continue an existing thread
+npx dot-agents channels publish "#status" "Rollback needed" --thread <thread-id>
+
+# Post to a persona's DM
+npx dot-agents channels publish "@developer" "Please review PR #123"
+```
+
+### Reading Messages
+
+```bash
+npx dot-agents channels read <channel> [options]
+```
+
+**Options:**
+
+- `--thread <id>` - Filter to specific thread
+- `--since <duration>` - Filter by time (e.g., `24h`, `7d`, `1m`)
+- `-l, --limit <n>` - Number of messages (default: 10)
+
+**Examples:**
+
+```bash
+# Read recent messages
+npx dot-agents channels read "#status"
+
+# Read a specific conversation thread
+npx dot-agents channels read "#status" --thread <thread-id>
+
+# Read last 24 hours
+npx dot-agents channels read "@human" --since 24h
+```
+
+### Replying to Messages
+
+```bash
+npx dot-agents channels reply <channel> <messageId> <reply>
+```
+
+Adds a reply to a specific message (creates a sub-thread within the message).
+
+## Personas
+
+Personas are agent configurations with inherited context and capabilities.
+
+### Running Personas
+
+```bash
+npx dot-agents personas run <name> [options]
+```
+
+**Options:**
+
+- `-p, --prompt <text>` - Initial prompt/task
+- `--headless` - Non-interactive mode
+- `--interactive` - Interactive mode (default)
+
+### Inheritance
+
+Personas inherit automatically via directory structure:
+
+1. **Root persona** (`.agents/PERSONA.md`) provides project-wide context
+2. **Child personas** in `.agents/personas/` inherit from root implicitly
+3. **All personas** inherit from the built-in `_base` persona (this document)
+
+No explicit `inherits:` field needed - inheritance is convention-based.
+
+## Workflows
+
+Workflows are multi-step processes defined in `.agents/workflows/`.
+
+```bash
+npx dot-agents run <workflow-name>
+npx dot-agents list workflows
+```
+
+## Projects
+
+Projects are registered dot-agents installations that can communicate with each other.
+
+```bash
+npx dot-agents projects list   # Registered projects
+```
+
+### Cross-Project Communication
+
+Delegate to another project using `@project` syntax:
+
+```bash
+# Delegate to another project's entry point
+npx dot-agents channels publish "@other-project" "Please handle this task"
+
+# Read from another project's channel
+npx dot-agents channels read "@other-project" --since 24h
+```
+
+## Discovery
+
+```bash
+npx dot-agents projects list   # Registered projects
+npx dot-agents channels list   # Available channels
+npx dot-agents list personas   # Available personas
+npx dot-agents list workflows  # Available workflows
+```
+
+**Proactively discover your environment** - Run discovery commands at session start to understand available resources before diving into work.
+
+Note: Skills are implementation details of workflows and personas. Access capabilities through workflows and personas rather than invoking skills directly.
+
+---
+
+## Sessions
+
+Sessions are threads in the `#sessions` channel. When you start running, the system automatically creates a session thread and posts a "Session Started" message. When the session ends, a "Session Ended" message is posted with duration and exit status.
+
+### Environment Variables
+
+- `SESSION_ID` - Your session thread ID (ISO timestamp, e.g., `2025-12-23T15:30:45.000Z`)
+- `SESSION_THREAD_ID` - Same as SESSION_ID (alias for clarity)
+- `SESSION_WORKSPACE` - Path to your session's workspace directory for working files
+
+### Posting Session Updates
+
+For **interactive sessions**, post updates to your session thread to maintain an observable log of your work. This is especially important for:
+
+- Major decisions or milestones
+- Delegating to other personas/projects
+- Receiving updates from delegated work
+- Encountering blockers
+
+**Pattern for updates:**
+
+```bash
+npx dot-agents channels publish "#sessions" "Brief update message" --thread $SESSION_ID
+```
+
+**Examples:**
+
+```bash
+# Log a major action
+npx dot-agents channels publish "#sessions" "Starting implementation of feature X" --thread $SESSION_ID
+
+# Log delegation
+npx dot-agents channels publish "#sessions" "Delegating to @scoutos for backend changes" --thread $SESSION_ID
+
+# Log receiving results
+npx dot-agents channels publish "#sessions" "Received: Backend changes complete, tests passing" --thread $SESSION_ID
+```
+
+### Checking for Updates
+
+When you've delegated work to another persona or project, periodically check your session thread for updates:
+
+```bash
+npx dot-agents channels read "#sessions" --thread $SESSION_ID
+```
+
+Delegates should post their status updates to the upstream session thread, keeping the parent informed of progress.
+
+### Cross-Project Delegation Callbacks
+
+When you receive a delegated task via DM, the system automatically provides callback routing:
+
+**Environment variables (set automatically):**
+
+- `FROM_ADDRESS` - Full callback address (e.g., `#docs/sessions:2026-01-02T21:00:00.000Z`)
+- `FROM_CHANNEL` - Channel portion (e.g., `#docs/sessions`)
+- `FROM_THREAD` - Thread ID portion (e.g., `2026-01-02T21:00:00.000Z`)
+
+**Posting callbacks:**
+
+```bash
+# Reply directly using FROM_ADDRESS (includes channel + thread)
+npx dot-agents channels publish "$FROM_ADDRESS" "Task complete: implemented feature X"
+
+# This is equivalent to:
+# npx dot-agents channels publish "$FROM_CHANNEL" "..." --thread "$FROM_THREAD"
+```
+
+**Your outgoing messages also include callback info automatically.** When you publish, your `FROM_ADDRESS` is included in the `from` field, so receivers can reply back to your session.
+
+### Workspace Directory
+
+Use `$SESSION_WORKSPACE` for any working files needed during the session:
+
+- Scratch notes
+- Temporary artifacts
+- Files to preserve for later reference
+
+The workspace persists with the session thread and can be accessed later.
+
+### Why Sessions-as-Threads Matter
+
+- **Cross-machine coordination** - Channels sync across machines, so you can see session history from anywhere
+- **Observable audit trail** - Anyone can read the session thread to understand what happened
+- **Delegation callbacks** - Delegates post to the parent's thread, no polling required
+- **Natural resumption** - Read the thread to reconstruct context for any session

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

@@ -0,0 +1,76 @@
+---
+name: channels/list
+description: List all available channels. Use when discovering what channels exist or checking channel metadata.
+license: MIT
+---
+
+# List Channels
+
+List all channels to discover available communication streams.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+- Discover what channels exist
+- Check channel metadata (creator, creation date)
+- Find the right channel to publish to
+- Get an overview of communication streams
+
+## Process
+
+### Step 1: List All Channels
+
+```bash
+npx dot-agents channels list
+```
+
+### Step 2: Review Output
+
+The output shows all channels with their metadata:
+
+```text
+Channels (4):
+
+  #status
+    Progress updates and milestone notifications
+    created by system at 2025-12-10T08:00:00.000Z
+
+  #issues
+    Problems, blockers, and errors
+    created by system at 2025-12-10T08:00:00.000Z
+
+  @developer
+    created by human:tnez at 2025-12-12T09:00:00.000Z
+```
+
+## Examples
+
+### Example 1: Check Available Channels
+
+```bash
+npx dot-agents channels list
+```
+
+### Example 2: Filter Public Channels
+
+```bash
+npx dot-agents channels list | grep "^  #"
+```
+
+### Example 3: Filter DM Channels
+
+```bash
+npx dot-agents channels list | grep "^  @"
+```
+
+## Channel Types
+
+- `#channel-name` - Public channels for topic-based communication
+- `@persona-name` - Direct message inboxes for personas
+
+## Notes
+
+- Channels are created automatically when first message is published
+- Empty result means no channels have been created yet
+- Use this before publishing to discover the right channel

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.