dot-agents 0.1.0 → 0.1.5

package/README.md

@@ -1,237 +1,269 @@
-# .agents Directory
+# dot-agents
 
-A curated collection of agent capabilities including skills, workflows, and tooling for building agentic projects.
+A framework for building and running agentic workflows with personas and scheduled execution.
 
-## What is the .agents Directory?
+## What is dot-agents?
 
-The `.agents/` directory is a standardized location for agent-related resources in your project. It provides a consistent structure for:
+dot-agents lets you define **personas** (agent configurations) and **workflows** (tasks for agents to execute), then run them on-demand or on a schedule. It's designed to work with any agent CLI (Claude Code, local LLMs, etc.).
 
-- **Skills** - Focused, reusable capabilities (convert markdown to PDF, validate YAML, etc.)
-- **Workflows** - Multi-step orchestrations that compose skills and tools
-- **Meta-tooling** - Tools for creating, testing, and managing agent capabilities
+**Key features:**
 
-Think of it as your project's "agent workspace" - everything your AI agent needs to work effectively on your codebase.
+- **Personas** with cascading inheritance - define base configurations and extend them
+- **Workflows** with triggers - run on-demand, on cron schedules, or via webhooks
+- **Daemon** for background execution - scheduled workflows run automatically
+- **Agent-agnostic** - works with any CLI that accepts prompts via stdin
 
-## Directory Structure
-
-When consumed, this repository installs to your project's `.agents/` directory:
+## Installation
 
-```text
-.agents/
-├── skills/           # Focused, reusable capabilities
-│   ├── meta/         # Tools for skill management
-│   ├── examples/     # Example implementations
-│   └── documents/    # Document processing
-└── workflows/        # Multi-step orchestrations
-    └── examples/     # Example workflows
+```bash
+npm install -g dot-agents
 ```
 
-## Installation
-
-### The Agentic Way (Recommended)
+Requires Node.js 20+.
 
-This repository is designed for **agentic installation** - your AI agent can install resources directly without scripts or package managers.
+## Quick Start
 
-Simply tell your agent:
+### 1. Create a `.agents` directory
 
-```text
-"Install find-local-events skill from tnez/dot-agents"
-"Install skills from tnez/dot-agents"
+```bash
+mkdir -p .agents/personas/claude .agents/workflows/hello
 ```
 
-Your agent will:
+### 2. Define a persona
 
-1. Fetch the files from GitHub
-2. Detect your `.agents/` directory (or ask where to install)
-3. Map repository structure to installation location:
-   - `skills/` → `.agents/skills/`
-   - `workflows/` → `.agents/workflows/`
-4. Verify installation
+Create `.agents/personas/claude/PERSONA.md`:
 
-**No npm, pip, or bash scripts required** - your agent handles everything using its built-in capabilities.
+```markdown
+---
+name: claude
+description: Base Claude persona
+cmd:
+  - "claude --print"
+  - "claude -p"
+env:
+  CLAUDE_MODEL: sonnet
+---
 
-### Discovery & Updates
+You are a helpful assistant. Execute tasks thoroughly and report results clearly.
+```
 
-Browse available resources:
+### 3. Create a workflow
 
-```text
-"Browse skills in tnez/dot-agents"
-"What workflows are available?"
-"Show me document-related skills"
-```
+Create `.agents/workflows/hello/WORKFLOW.md`:
 
-Check for updates:
+```markdown
+---
+name: hello-world
+description: A simple hello world workflow
+persona: claude
+on:
+  manual: true
+---
 
-```text
-"Check for updates to my installed skills"
-"Update skill-installer"
+Say hello and tell me today's date.
 ```
 
-See [CATALOG.md](CATALOG.md) for the complete list.
+### 4. Run it
 
-### How It Works
+```bash
+dot-agents run hello-world
+```
 
-Your agent uses meta-skills from this repository:
+## Core Concepts
 
-- **skill-installer**: Fetches and installs skills from GitHub
-- **skill-browser**: Discovers available skills and workflows
+### Personas
 
-Both are pure agentic - they teach your agent HOW to install, rather than providing scripts to run.
+Personas define **how** an agent behaves. They specify the command to run, environment variables, available skills, and a system prompt.
 
-### Installation Locations
+```yaml
+---
+name: productivity-assistant
+description: Focused assistant for productivity tasks
+cmd: "claude --print"
+env:
+  CLAUDE_MODEL: sonnet
+skills:
+  - "productivity/**"
+  - "!productivity/experimental/*"
+---
+System prompt goes here in the markdown body...
+```
 
-Resources install to these locations (in priority order):
+**Persona inheritance:** Personas cascade through directories. A persona at `personas/claude/autonomous/productivity/` inherits from `personas/claude/autonomous/` which inherits from `personas/claude/`.
 
-1. `.agents/` - Project-level, agent-agnostic (preferred)
-2. `.claude/` - Project-level, Claude-specific
-3. `~/.agents/` - Global, agent-agnostic
-4. `~/.claude/` - Global, Claude-specific
+- Scalar fields (name, description, cmd) - child overrides parent
+- Objects (env) - deep merged
+- Arrays (skills) - merged with `!` prefix for removal
 
-Your agent will auto-detect or ask where to install.
+### Workflows
 
-## Repository Development Structure
+Workflows define **what** an agent should do. They reference a persona and contain the task in the markdown body.
 
-```text
-worktrees/main/
-├── CATALOG.md             # Machine-readable catalog
-├── skills/                # → .agents/skills/ when consumed
-│   ├── meta/              # Skill management tools
-│   │   ├── skill-installer/
-│   │   ├── skill-browser/
-│   │   ├── skill-creator/
-│   │   ├── skill-tester/
-│   │   └── skill-evaluator/
-│   ├── examples/          # Example implementations
-│   │   ├── find-local-events/
-│   │   ├── get-weather/
-│   │   └── simple-task/
-│   └── documents/         # Document processing
-│       ├── image-review-pdf/
-│       └── markdown-to-pdf/
-└── workflows/             # → .agents/workflows/ when consumed
-    ├── README.md
-    └── examples/
+```yaml
+---
+name: daily-standup
+description: Generate standup notes from git activity
+persona: claude/autonomous
+on:
+  schedule:
+    - cron: "0 9 * * 1-5"
+  manual: true
+inputs:
+  - name: days
+    type: number
+    default: 1
+    description: Days of history to analyze
+---
+
+Analyze git commits from the last ${days} day(s) and generate standup notes.
+Focus on: what was accomplished, what's in progress, any blockers.
 ```
 
-## Quick Start
+**Triggers:**
 
-### For Agents
+- `manual: true` - Can be run on-demand
+- `schedule` - Cron-based scheduling (requires daemon)
+- Future: `file_change`, `webhook`, `git`
 
-Resources are loaded automatically when relevant to your task. Each provides:
+### Variable Expansion
 
-- Clear instructions for when and how to use it
-- Templates and examples
-- Validation and testing tools
+Workflows support variable expansion in the task body:
 
-### For Humans
+- `${VAR}` - Environment variables and inputs
+- `${DATE}`, `${TIME}`, `${DATETIME}` - Current date/time
+- `${RUN_ID}` - Unique execution identifier
+- `{{#if var}}...{{/if}}` - Conditional blocks
 
-1. **Browse skills**: Explore `skills/` directory
-2. **Browse workflows**: Explore `workflows/` directory
-3. **Use meta-skills**: Leverage skill-creator, skill-tester, skill-evaluator
-4. **Create custom resources**: Follow specifications in each directory's README
-5. **See development workflows**: Check WORKFLOWS.md for development patterns
+## CLI Reference
 
-## Skills
+```bash
+dot-agents [command]
+
+Commands:
+  run <workflow>           Run a workflow
+  list [workflows|personas] List resources
+  show workflow <name>     Show workflow details
+  show persona <name>      Show resolved persona (with inheritance)
+  schedule list            List scheduled workflows
+  daemon run               Run the scheduler daemon
+  daemon status            Check daemon status
+  daemon jobs              List scheduled jobs
+  daemon trigger <name>    Manually trigger a workflow
 
-Skills are focused, reusable capabilities that agents load dynamically. Each skill is a self-contained directory with:
+Aliases:
+  workflows                List all workflows
+  personas                 List all personas
+```
 
-- `SKILL.md` - Required markdown file with YAML frontmatter and instructions
-- `CONTEXT.md` - Optional user/project-specific context and customizations
-- Optional supporting files (scripts, templates, assets, references)
+### Running Workflows
 
-**Format**:
+```bash
+# Run a workflow
+dot-agents run daily-standup
 
-```markdown
----
-name: skill-name
-description: What the skill does and when to use it
-license: MIT
----
+# With input overrides
+dot-agents run daily-standup -i days=3
 
-# Skill Instructions
+# Dry run (show prompt without executing)
+dot-agents run daily-standup --dry-run
 
-Imperative instructions for the agent...
+# Override persona
+dot-agents run daily-standup -p claude/autonomous
 ```
 
-**CONTEXT.md Pattern**: Co-locate a `CONTEXT.md` file with any `SKILL.md` to inject user or project-specific context. The skill remains general and reusable while `CONTEXT.md` provides customization. This file is preserved during skill updates.
+### Viewing Details
 
-See [Agent Skills Specification](https://github.com/anthropics/skills/blob/main/agent_skills_spec.md) for details.
+```bash
+# Show resolved persona with full inheritance chain
+dot-agents show persona claude/autonomous/productivity
 
-## Workflows
+# Show workflow with resolved prompt
+dot-agents show workflow daily-standup --prompt
+```
 
-Workflows are multi-step orchestrations that compose skills, tools, and agent behaviors. They handle complex tasks requiring:
+## Daemon
 
-- Multiple phases or steps
-- Decision making and conditionals
-- Coordination of multiple skills
-- Standardized procedures
+The daemon runs scheduled workflows in the background.
 
-See `workflows/README.md` for details on creating workflows.
+```bash
+# Start the daemon
+dot-agents daemon run
 
-## Meta-Skills
+# Check status
+dot-agents daemon status
 
-### skill-installer ⭐
+# View scheduled jobs
+dot-agents daemon jobs
 
-Pure agentic skill installation from GitHub repositories. Features:
+# Manually trigger a workflow
+dot-agents daemon trigger daily-standup
 
-- Zero dependencies (uses WebFetch, Bash, Write, Glob)
-- Smart semantic merging for updates
-- CONTEXT.md preservation for user customizations
-- Auto-detects installation location
+# Reload workflows after changes
+dot-agents daemon reload
+```
 
-**New paradigm**: Your agent installs skills, not scripts.
+The daemon provides an HTTP API on port 3141 (configurable with `-p`):
 
-### skill-browser ⭐
+- `GET /health` - Health check
+- `GET /status` - Daemon status and uptime
+- `GET /jobs` - List scheduled jobs
+- `POST /trigger/:workflow` - Trigger a workflow
+- `POST /reload` - Reload workflows from disk
 
-Discover and browse available skills. Features:
+## Directory Structure
 
-- Reads CATALOG.md to show available resources
-- Compares with local installation
-- Identifies updates and new additions
-- Filters by category or relevance
+```text
+.agents/
+├── personas/           # Agent configurations
+│   └── claude/
+│       ├── PERSONA.md  # Base Claude persona
+│       └── autonomous/
+│           ├── PERSONA.md  # Inherits from claude
+│           └── productivity/
+│               └── PERSONA.md  # Inherits from autonomous
+├── workflows/          # Task definitions
+│   └── daily-standup/
+│       └── WORKFLOW.md
+├── skills/             # Reusable capabilities (optional)
+└── sessions/           # Execution logs
+```
 
-**Usage**: "Browse skills in tnez/dot-agents" or "What's new?"
+## Skills
 
-### skill-creator
+dot-agents also supports skills - focused, reusable capabilities that agents can load. Skills follow the [Anthropic Skills Specification](https://github.com/anthropics/skills/blob/main/agent_skills_spec.md).
 
-Scaffold new skills with proper structure and validation. Generates:
+Skills are referenced in personas via glob patterns:
 
-- SKILL.md with valid YAML frontmatter
-- Directory structure (scripts, templates, assets)
-- Validation checks for spec compliance
+```yaml
+skills:
+  - "documents/**"
+  - "productivity/*"
+  - "!experimental/**"
+```
 
-### skill-tester
+See the `skills/` directory for examples.
 
-Validate skills against the specification. Tests:
+## Development
 
-- YAML frontmatter correctness
-- File references and structure
-- Common issues and anti-patterns
+```bash
+# Clone and install
+git clone https://github.com/tnez/dot-agents.git
+cd dot-agents
+npm install
 
-### skill-evaluator
+# Build
+npm run build
 
-Assess skill quality using rubric-based evaluation. Evaluates:
+# Run CLI locally
+just cli list workflows
 
-- Clarity and actionability
-- Completeness and focus
-- Examples and documentation quality
+# Run linters
+just lint
+```
 
 ## Contributing
 
-When creating new skills or workflows:
-
-1. Use `skill-creator` for skills or follow `workflows/README.md` for workflows
-2. Test with `skill-tester` to ensure spec compliance
-3. Evaluate with `skill-evaluator` for quality assurance
-4. Follow the test → evaluate → refine cycle
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
-
-## Resources
-
-- [Agent Skills Specification](https://github.com/anthropics/skills/blob/main/agent_skills_spec.md)
-- [Anthropics Skills Repository](https://github.com/anthropics/skills)
-- [Development Workflows](DEVELOPMENT.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dot-agents",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "A framework for building agentic workflows with personas and scheduled execution",
   "type": "module",
   "main": "./dist/lib/index.js",
@@ -23,6 +23,7 @@
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist *.tsbuildinfo",
+    "prepare": "git config core.hooksPath .githooks || true",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "files": [