Create Custom Routine

Guide the user through creating a new automated routine that runs on schedule via the EvoNexus scheduler.

What You're Building

A routine is a Python script in ADWs/routines/custom/ that runs on a schedule (daily, weekly, monthly, or interval). There are two types:

• AI routines — invoke Claude Code CLI with an agent to perform reasoning tasks (reports, analysis, decisions). Cost tokens and ~30-120s per run.
• Systematic routines — pure Python scripts that perform deterministic operations (API calls, file ops, data transforms). No AI, no tokens, no cost, ~1-5s per run.

Step 1: Understand the Task

Ask the user:

1. What should this routine do? (e.g., "check my GitHub repos every morning", "ping API endpoints every 5 minutes")
2. AI or systematic? Help the user decide:
   • Use AI when: the task needs reasoning, analysis, writing, or decisions (generate a report, analyze sentiment, summarize data, make recommendations)
   • Use systematic when: the task is deterministic and repeatable (HTTP health checks, file cleanup, data snapshots, metric logging, backups, CSV exports)
3. When should it run? (daily at X, every N minutes, weekly on day, monthly on day 1)
4. What output? (HTML report, markdown file, CSV, JSON, Telegram notification, log entry, or just action)

If AI routine, also ask:

• Which agent should run it?
  • clawdia-assistant — ops, daily tasks, email, meetings
  • flux-finance — financial reports, Stripe, ERP
  • atlas-project — GitHub, Linear, project tracking
  • pulse-community — Discord, WhatsApp, community
  • pixel-social-media — social media, content, analytics
  • sage-strategy — OKRs, strategy, competitive analysis
  • nex-sales — pipeline, proposals, leads
  • mentor-courses — courses, learning paths
  • kai-personal-assistant — health, habits, personal

Step 2: Generate the Script

AI routine

Create the routine script at ADWs/routines/custom/{name}.py:

#!/usr/bin/env python3
"""ADW: {Routine Name} — {brief description}. Agent: @{agent-name}"""

import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from runner import run_skill, run_claude, banner, summary

def main():
    banner("{Routine Name}", "{description} | @{agent}")
    results = []
    results.append(run_skill(
        "{skill-name}",
        log_name="{routine-id}",
        timeout=600,
        agent="{agent-name}"
    ))
    summary(results, "{Routine Name}")

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nCancelled.")

Key rules for AI routines:

• Use run_skill() when there's an existing skill, or run_claude() for inline prompts
• Specify the agent name for context loading
• Set a reasonable timeout (300-900s depending on complexity)

Systematic routine

Create the routine script at ADWs/routines/custom/{name}.py:

#!/usr/bin/env python3
"""ADW: {Routine Name} — {brief description}. Type: systematic"""

import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from runner import run_script, banner, summary

def do_task():
    """Pure Python logic — no Claude CLI, no AI, no tokens."""
    # YOUR CODE HERE: API calls, file ops, data transforms
    # ...
    return {
        "ok": True,  # or False on failure
        "summary": "Short description of what happened",
        "data": {}   # optional structured data for logs
    }

def main():
    banner("{Routine Name}", "{description} | systematic")
    results = []
    results.append(run_script(do_task, log_name="{routine-id}", timeout=60))
    summary(results, "{Routine Name}")

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nCancelled.")

Key rules for systematic routines:

• Write the actual Python logic in the do_task() function — this is where YOU (Claude) generate the implementation code
• Use stdlib + requests for HTTP calls (already in pyproject.toml dependencies)
• Return {"ok": bool, "summary": str} so the runner can log success/failure
• Keep timeout short (30-120s) — these should be fast
• No agent parameter — systematic routines don't use agents
• Common patterns: requests.get() for API polling, os.walk() for file ops, csv.writer() for data export, shutil for backups

Step 3: Run It

No Makefile changes needed — routines are discovered dynamically from scripts.

make run R={routine-id}      # Run by ID
make list-routines           # List all available

Step 4: Add to Scheduler (Optional)

If the user wants it automated, add to scheduler.py in the appropriate section:

# Daily
schedule.every().day.at("{HH:MM}").do(run_adw, "{Routine Name}", "custom/{script_name}.py")

# Weekly
schedule.every().{day}.at("{HH:MM}").do(run_adw, "{Routine Name}", "custom/{script_name}.py")

# Monthly (in the monthly block)
run_adw("{Routine Name}", "custom/{script_name}.py")

# Interval
schedule.every({N}).minutes.do(run_adw, "{Routine Name}", "custom/{script_name}.py")

Step 5: Test

Run the routine manually:

make run R={routine-id}

Check the output and adjust the prompt if needed.

Step 6: Create HTML Template (Optional)

If the routine generates an HTML report, create a template at .claude/templates/html/{name}.html following the pattern of existing templates:

• Dark theme (bg #0C111D, green #00FFA7)
• Evolution Foundation logo in header
• Footer: "Automatically generated by EvoNexus — Evolution Foundation"
• Use {{PLACEHOLDER}} for dynamic content

Examples

AI routine: Daily competitor check

Name: competitor-check
Type: AI
Agent: sage-strategy
Schedule: daily at 09:00
Why AI: needs reasoning to analyze competitor changes and compare positioning

AI routine: Weekly content performance

Name: content-performance
Type: AI
Agent: pixel-social-media
Schedule: weekly on friday at 17:00
Why AI: needs analysis to identify trends and make recommendations

Systematic routine: API health check

Name: api-health-check
Type: systematic
Schedule: every 5 minutes
Why systematic: just pings endpoints and checks HTTP status codes — no reasoning needed

Systematic routine: Metric snapshot

Name: metric-snapshot
Type: systematic
Schedule: daily at 23:55
Why systematic: reads metrics.json and appends a row to a CSV — pure data transform

Systematic routine: Log cleanup

Name: log-cleanup
Type: systematic
Schedule: weekly on sunday at 03:00
Why systematic: deletes files older than 30 days — deterministic file operation

Important Notes

• Custom routines go in ADWs/routines/custom/ (gitignored — they're personal to your workspace)
• Core routines in ADWs/routines/ are shipped with the repo and should not be modified
• The runner.py handles logging, metrics, and Telegram notifications automatically for both types
• Systematic routines log with tokens=0 and cost=0 in metrics
• Systematic routines can run at high frequency (every 1-5 minutes) since they cost nothing
• Restart the scheduler after adding new routines: stop and make scheduler