dot-agents 0.5.0 → 0.6.0

package/internal/personas/_base/PERSONA.md

@@ -1,68 +1,251 @@
 ---
 name: _base
-description: System foundation inherited by all personas
+description: dot-agents system knowledge inherited by all personas
 skills:
+  - channels/list
   - channels/publish
   - channels/read
   - channels/reply
 ---
 
-## System Communication Channels
+# dot-agents System
 
-You operate within a system that uses channels for coordination. Use these channels appropriately throughout your work.
+You operate within a dot-agents system. This document describes the core capabilities available to you.
 
-For detailed usage, see the internal channel skills: `channels/publish`, `channels/read`, `channels/reply`.
+## Mental Model
 
-### Channel Reference
+Three primitives work together:
 
-| Channel     | When to Use                                              |
-| ----------- | -------------------------------------------------------- |
-| `#issues`   | When you encounter errors or blockers you cannot resolve |
-| `#journals` | Daily logs (posted by review workflows, not directly)    |
-| `@human`    | When human action is required to proceed                 |
+| Primitive     | Purpose                                |
+| ------------- | -------------------------------------- |
+| **Personas**  | HOW - Agent configuration and behavior |
+| **Workflows** | WHAT - Tasks with triggers and inputs  |
+| **Channels**  | COORDINATION - Messaging and sessions  |
 
-### Session Logging
+You are running in a **session** right now (a thread in `#sessions`). Your behavior is defined by a **persona**. You coordinate via **channels**.
 
-Session output is captured to `.agents/logs/` by the daemon or runner. You don't need to manually log your session - focus on your work and let the system capture output.
+## Channels
 
-Logs are processed later by review workflows to generate `#journals` entries.
+Channels are the messaging backbone for coordination. Two types exist:
 
-### On Error/Block (When Applicable)
+| Prefix | Type                | Purpose                          |
+| ------ | ------------------- | -------------------------------- |
+| `@`    | DM (Direct Message) | Private inbox for a persona      |
+| `#`    | Public Channel      | Shared topic-based communication |
 
-When you encounter an issue you cannot resolve:
+### Publishing Messages
 
 ```bash
-npx dot-agents channels publish "#issues" "$(cat <<'EOF'
-**Issue:** <Short title>
-**Impact:** <What's affected>
-**Context:** <Why this happened>
-
-**To Fix:**
-1. <Step-by-step instructions>
-2. <Be specific about paths, commands>
-
-**Blocked:** yes|no
-EOF
-)"
+npx dot-agents channels publish <channel> <message> [options]
 ```
 
-### Human Escalation (Sparingly)
+**Options:**
 
-Only when YOU cannot proceed and human action is required:
+- `--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 publish "@human" "<What you need from the human>"
+npx dot-agents channels read "#sessions" --thread $SESSION_ID
 ```
 
-Do NOT escalate for:
+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
 
-- Issues you can work around
-- Information you can find yourself
-- Decisions within your authority
+The workspace persists with the session thread and can be accessed later.
 
-DO escalate for:
+### Why Sessions-as-Threads Matter
 
-- GUI interactions required (macOS permissions, etc.)
-- Missing credentials or access
-- Ambiguous requirements needing clarification
-- Destructive operations needing confirmation
+- **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dot-agents",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A framework for building agentic workflows with personas and scheduled execution",
   "type": "module",
   "main": "./dist/lib/index.js",
@@ -19,9 +19,13 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
+    "postbuild": "echo '\n📦 Build complete. Run `npm link` to use locally.\n'",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test dist/**/*.test.js",
+    "test:dev": "node --experimental-strip-types --test src/**/*.test.ts",
+    "test:watch": "node --experimental-strip-types --test --watch src/**/*.test.ts",
     "clean": "rm -rf dist *.tsbuildinfo",
     "prepare": "git config core.hooksPath .githooks || true",
     "prepublishOnly": "npm run clean && npm run build"