Workspaces¶

agent_workspaces/<name>/
├── agent/                  # Identity and extensions
│   ├── AGENT.md            # Capabilities, behavior guidelines
│   ├── USER.md             # User context/preferences
│   ├── SOUL.md             # Core personality, values
│   ├── HEARTBEAT.md        # Session state scratchpad (agent-writable)
│   ├── tools/              # Custom LangChain @tool functions
│   │   ├── *.py
│   │   └── requirements.txt
│   └── skills/             # Reusable knowledge and behavior patterns
│       └── <skill-name>/
│           └── SKILL.md
├── config/                 # Configuration (write-protected from agent)
│   ├── agent.yaml          # Per-workspace settings (model, channel, queue)
│   ├── .env                # API keys and secrets
│   └── crons/              # Scheduled task definitions
│       └── *.yaml
├── data/                   # Framework-managed state (write-protected from agent)
│   ├── conversations.db    # AsyncSqliteSaver checkpoint database
│   ├── sessions.json       # Session/conversation thread state
│   ├── token_usage.jsonl   # Token usage metrics (append-only)
│   ├── subagents.yaml      # Sub-agent state
│   ├── TASKS.yaml          # Persistent task tracking
│   ├── dynamic_crons.json  # Agent-scheduled tasks
│   ├── heartbeat_log.jsonl # Heartbeat event log
│   └── uploads/            # User-uploaded files (from FilePersistenceProcessor)
│       └── {YYYY-MM-DD}/   # Date-partitioned storage
│           ├── report.pdf        # Original uploaded file
│           ├── report.md         # Docling-converted markdown (sibling)
│           ├── voice_123.ogg     # Original audio file
│           └── voice_123.txt     # Whisper transcript (sibling)
├── memory/                 # Archived conversations and session logs
│   ├── conversations/      # Conversation exports (markdown + JSON)
│   │   ├── conv_*.md       # Markdown archives (human-readable)
│   │   └── conv_*.json     # JSON sidecars (machine-readable)
│   └── logs/               # Heartbeat, cron, and sub-agent session logs
│       ├── heartbeat/
│       ├── cron/
│       └── subagent/
└── workspace/              # Agent work area (default write target)
    ├── downloads/          # Browser-downloaded files
    └── screenshots/        # Browser screenshots

# Agent Profile

You are Gilfoyle, a senior systems architect and DevOps engineer.

## Capabilities

- AWS infrastructure management (Lambda, S3, DynamoDB)
- Python development (FastAPI, SQLAlchemy, Pydantic)
- Terraform infrastructure-as-code
- CI/CD pipeline design
- System architecture and design patterns

## Communication Style

- Be direct and technically precise
- Avoid unnecessary pleasantries
- Use sarcasm sparingly but effectively
- Cite specific technologies and patterns when relevant

## Constraints

- Do not make AWS changes without confirmation
- Always explain architectural decisions
- Prioritize security and scalability

# User Profile

## Name
John Sosoka

## Role
Engineering Lead

## Preferences
- Prefers concise technical explanations
- Works in Pacific Time (PT)
- Uses AWS us-west-2 region by default

## Context
- Manages multiple client projects
- Values clean, maintainable code
- Follows Clean Code and Clean Architecture principles

# Core Values

## Technical Excellence
Always prioritize correctness, clarity, and maintainability over cleverness.

## Honesty
If you don't know something, say so. Don't speculate or guess about critical systems.

## Efficiency
Value the user's time. Be concise but complete.

## Professionalism
Maintain professional communication standards. You represent the engineering team.

# Current State

## Session Started
2026-02-05

## Active Projects
- OpenPaw: Multi-channel agent framework
- ClientX: AWS Lambda migration

## Pending Tasks
- Review OpenPaw documentation
- Update Terraform modules for ClientX

## Recent Learnings
- Conversation persistence via AsyncSqliteSaver
- APScheduler for cron implementation

name: Gilfoyle
description: Sarcastic systems architect
timezone: America/Denver  # IANA timezone identifier (default: UTC)

model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: ${ANTHROPIC_API_KEY}
  temperature: 0.5
  max_turns: 50

channel:
  type: telegram
  token: ${TELEGRAM_BOT_TOKEN}
  allowed_users: [123456789]
  allowed_groups: []

queue:
  mode: steer
  debounce_ms: 500

builtins:
  allow: []    # Empty = allow all available
  deny:
    - elevenlabs

heartbeat:
  enabled: true
  interval_minutes: 30
  active_hours: "09:00-17:00"  # Interpreted in workspace timezone
  suppress_ok: true
  output:
    channel: telegram
    chat_id: 123456789

# API keys specific to this workspace
CALENDAR_API_KEY=abc123
JIRA_API_TOKEN=xyz789

# Workspace-specific configuration
DEFAULT_PROJECT=ClientX
TEAM_EMAIL=team@example.com

poetry run openpaw -c config.yaml -w gilfoyle,assistant,scheduler

Agent reads HEARTBEAT.md → Updates pending tasks → Writes back to file

Agent creates notes/ directory → Saves meeting summaries → Retrieves on demand

Agent uses file_info to check size → Uses grep_files to search content → Reads specific files

User uploads document → FilePersistenceProcessor saves to uploads/ → Agent reads processed markdown

from langchain_core.tools import tool
from datetime import datetime, timedelta
import os

@tool
def get_upcoming_events(days_ahead: int = 7) -> str:
    """Get upcoming calendar events.

    Args:
        days_ahead: Number of days to look ahead

    Returns:
        Formatted list of events.
    """
    api_key = os.getenv("CALENDAR_API_KEY")
    if not api_key:
        return "Error: CALENDAR_API_KEY not configured"

    # Implementation here
    events = fetch_calendar_events(api_key, days_ahead)
    return format_events(events)

@tool
def check_availability(date: str) -> str:
    """Check if a specific date is free.

    Args:
        date: Date in YYYY-MM-DD format

    Returns:
        Availability status with free time blocks.
    """
    # Implementation here
    return check_calendar_availability(date)

# agent/tools/requirements.txt
icalendar>=5.0.0
caldav>=1.0.0
requests>=2.31.0

agent/skills/
├── research-patterns/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── _disabled-skill/     # Skipped (underscore prefix)
    └── SKILL.md

---
name: research-patterns
description: Patterns for conducting technical research across multiple sources
version: "1.0"
---

# Research Patterns

When conducting research, follow these steps:
1. Identify primary sources...
2. Cross-reference findings across at least three independent sources...
3. Summarize findings with citations...

---
name: writing-style
description: House style guide for all written output
---

# Writing Style Guide

## Tone
- Direct and professional — no filler phrases ("Certainly!", "Great question!")
- Use active voice; avoid passive constructions where possible
- Prefer concrete nouns and specific verbs over vague generalities

## Formatting
- Use bullet points for lists of three or more items
- Code examples belong in fenced code blocks with language tags
- Section headers use title case

name: daily-summary
schedule: "0 9 * * *"  # 9 AM daily (workspace timezone)
enabled: true

prompt: |
  Generate a daily summary by reviewing:
  - Active projects in HEARTBEAT.md
  - TASKS.yaml for pending work
  - Recent conversation archives in memory/conversations/

  Provide a concise status update focusing on what requires attention today.

output:
  channel: telegram
  chat_id: 123456789

# Basic scaffold with TODO markers
poetry run openpaw init my_agent

# Pre-configure model and channel
poetry run openpaw init my_agent --model anthropic:claude-sonnet-4-20250514 --channel telegram

# Scaffold in a custom directory
poetry run openpaw init my_agent --path /path/to/workspaces

poetry run openpaw -c config.yaml -w my_agent

poetry run openpaw list

# Technical Support Specialist

You are a technical support specialist for SaaS products.

## Capabilities
- Troubleshooting common issues
- API debugging assistance
- Documentation lookup via brave_search
- Issue escalation when needed

## Communication Style
- Patient and helpful
- Ask clarifying questions
- Provide step-by-step solutions
- Link to relevant documentation

queue:
  mode: followup  # Process support requests sequentially

builtins:
  allow:
    - brave_search  # Enable documentation search
    - send_message  # Progress updates during troubleshooting

# Daily Reporter

You generate daily reports by analyzing system state and recent activity.

## Capabilities
- Reading workspace files (HEARTBEAT.md, TASKS.yaml)
- Summarizing project status
- Identifying pending tasks and blockers
- Analyzing conversation archives for trends

name: daily-report
schedule: "0 9 * * 1-5"  # Weekdays at 9 AM
enabled: true

prompt: |
  Review all workspace files and generate a status report.

  Include:
  - Active projects from HEARTBEAT.md
  - Task status from TASKS.yaml
  - Recent conversation topics from memory/conversations/
  - Any blockers requiring human attention

# Team Assistant

You are a team assistant supporting multiple engineers in a group chat.

## Capabilities
- Task tracking via TASKS.yaml
- Calendar management (custom tools)
- Documentation lookup
- Meeting note summarization

## Communication Style
- Tag users when addressing them directly
- Be concise in group contexts
- Use threads for detailed discussions

channel:
  type: telegram
  allowed_groups: [-1001234567890]  # Team group chat

builtins:
  task_tracker:
    enabled: true
  brave_search:
    enabled: true

from langchain_core.tools import tool

@tool
def check_team_availability(date: str) -> str:
    """Check team calendar for available meeting slots.

    Args:
        date: Date in YYYY-MM-DD format

    Returns:
        Available time slots for team meetings.
    """
    # Implementation using workspace calendar API
    return get_team_availability(date)