Dual-Mode Automations: Timer + Skill Pairs

Summary

Architecture

                          DUAL-MODE AUTOMATION PATTERN
    +-------------------------------------------------------------+
    |                                                             |
    |   SCHEDULED (automatic)          ON-DEMAND (manual)         |
    |                                                             |
    |   +------------------+          +------------------+        |
    |   |  systemd timer   |          |  /skill command  |        |
    |   |  (forge-X.timer) |          |  (Claude Code)   |        |
    |   +--------+---------+          +--------+---------+        |
    |            |                              |                  |
    |   +--------v---------+          +--------v---------+        |
    |   | systemd service  |          |  skill wrapper   |        |
    |   | (forge-X.service)|          | (SKILL.md reads  |        |
    |   |  ExecStart=...   |          |  same script)    |        |
    |   +--------+---------+          +--------+---------+        |
    |            |                              |                  |
    |            +----------+------------------+                  |
    |                       |                                      |
    |              +--------v---------+                           |
    |              |  SCRIPT          |                           |
    |              |  /opt/forge/     |                           |
    |              |  scripts/X.sh    |                           |
    |              |                  |                           |
    |              |  +------------+  |  Standard interface:      |
    |              |  | forge-std  |  |  - source forge-std.sh    |
    |              |  | library    |  |  - env loading            |
    |              |  +------------+  |  - logging                |
    |              |                  |  - Telegram output        |
    |              |  +------------+  |  - exit codes             |
    |              |  | lockfile   |  |  - --dry-run / --now      |
    |              |  +------------+  |  - timeout wrapper        |
    |              |                  |  - DND hours check        |
    |              |  +------------+  |                           |
    |              |  | notify.sh  |  |                           |
    |              |  +------------+  |                           |
    |              +------------------+                           |
    |                       |                                      |
    |              +--------v---------+                           |
    |              |  OUTPUT          |                           |
    |              |  - Telegram msg  |                           |
    |              |  - Log file      |                           |
    |              |  - stdout (skill)|                           |
    |              |  - Exit code     |                           |
    |              +------------------+                           |
    +-------------------------------------------------------------+

FILE LAYOUT PER AUTOMATION:

    scripts/<name>.sh                        # The logic
    services/forge-<name>/
        forge-<name>.service                 # systemd service unit
        forge-<name>.timer                   # systemd timer unit
    skills/<name>/SKILL.md                   # Skill wrapper
    .claude/skills/<name> -> ../../skills/<name>/  # Symlink
    config/<name>.yaml                       # Config (if needed)
    logs/<name>/                             # Log directory

Components

1. forge-std.sh — Standard Script Library

• Purpose: Shared preamble sourced by every automation script. Provides env loading, logging, DND check, timeout, and Telegram output in one source call.
• Location: /opt/forge/scripts/lib/forge-std.sh
• Dependencies: notify.sh, lockfile.sh (existing)
• Build time: 15 min

2. Timer+Service Template

• Purpose: Copy-paste systemd unit pair. Replace 3 variables and sudo systemctl enable --now.
• Location: /opt/forge/Templates/timer-service-template/
• Build time: 5 min

3. Skill Wrapper Template

• Purpose: Minimal SKILL.md that wraps any script for on-demand invocation. Reads the script output and presents it to the user.
• Location: Inline in scripts/new-timer-skill.sh
• Build time: 10 min

4. new-timer-skill.sh — Creation Helper

• Purpose: One command creates the full triple: script stub + timer/service pair + skill wrapper + symlink.
• Usage: bash scripts/new-timer-skill.sh <name> "<description>" "<schedule>"
• Build time: 15 min

5. DND Hours Gate

• Purpose: Shared function that checks current time against DND window before sending Telegram notifications. Queues messages for delivery after DND ends.
• Config: /opt/forge/config/dnd.yaml
• Build time: 15 min

Coverage Map: OpenClaw → Forge

Legend

EXISTS Already built and running   PARTIAL Some coverage, needs completion   PLANNED Identified, ready to build   NEW Designed here for coverage parity

OpenClaw Prompt Categories

Forge-Native Automations (No OpenClaw Equivalent)

Full Timer Inventory (Target State)

After build-out, Forge will have 19 systemd timers (7 existing + 12 new):

Build Priority

Ordered by domino value (what unblocks the most downstream work) and effort.

TIER 1 Foundation (Build First)

Everything depends on these. Build once, use forever.

TIER 2 Wrap Existing Scripts

No new logic — just add timer+skill pair to scripts that already exist.

TIER 3 New Automations

New logic required. Each is a self-contained Ralph task.

TIER 4 Skills Only (No Timer Needed)

Templates

Script Template

Every automation script follows this exact pattern. Copy-paste and fill in the marked sections.

#!/usr/bin/env bash
# <name>.sh — <one-line description>
# Schedule: <cron expression or interval description>
# Dual-mode: timer (forge-<name>.timer) + skill (/<name>)
#
# Usage:
#   bash /opt/forge/scripts/<name>.sh            # normal run
#   bash /opt/forge/scripts/<name>.sh --dry-run   # log without sending
#   bash /opt/forge/scripts/<name>.sh --now        # skip schedule/DND checks

set -euo pipefail

# ============================================================
# STANDARD PREAMBLE
# ============================================================
FORGE_ROOT="/opt/forge"
SCRIPT_NAME="$(basename "$0" .sh)"
source "${FORGE_ROOT}/scripts/lib/forge-std.sh"

forge_init "$SCRIPT_NAME" "$@"

# ============================================================
# CONFIG (optional YAML config)
# ============================================================
# CONFIG_FILE="${FORGE_ROOT}/config/<name>.yaml"
# MY_SETTING=$(yq '.some.setting // "default"' "$CONFIG_FILE")

# ============================================================
# MAIN LOGIC — replace this section
# ============================================================

log "Starting ${SCRIPT_NAME}..."

# ... your automation logic here ...

RESULT="Your output message here"

# ============================================================
# OUTPUT — Telegram + log + stdout
# ============================================================
if [ "$DRY_RUN" = true ]; then
  log "DRY RUN — would send:"
  echo "$RESULT"
else
  notify "$RESULT"
  log "Sent notification (${#RESULT} chars)"
fi

log "Done"

forge-std.sh Library

Standard preamble for all Forge automation scripts. Provides env loading, logging, DND check, timeout, and Telegram output.

#!/usr/bin/env bash
# forge-std.sh — Standard preamble for all Forge automation scripts
# Source this at the top of every timer+skill script.
#
# Usage: source /opt/forge/scripts/lib/forge-std.sh
#        forge_init "script-name" "$@"

# --- Standard Variables ---
DATE=$(date +%Y-%m-%d)
TIMESTAMP=$(date -Iseconds)
NOW_HOUR=$(date +%H)
NOW_MIN=$(date +%M)

# --- Flags (set by forge_init) ---
DRY_RUN=false
SKIP_CHECKS=false
QUIET=false

# --- Paths ---
LOG_DIR=""
LOG_FILE=""

# --- Source dependencies ---
source "${FORGE_ROOT}/scripts/lib/lockfile.sh"

forge_init() {
  local name="${1:?Usage: forge_init <name> [args...]}"
  shift

  SCRIPT_NAME="$name"
  LOG_DIR="${FORGE_ROOT}/logs/${name}"
  LOG_FILE="${LOG_DIR}/${DATE}.log"
  mkdir -p "$LOG_DIR"

  # Parse flags
  for arg in "$@"; do
    case "$arg" in
      --dry-run)  DRY_RUN=true ;;
      --now)      SKIP_CHECKS=true ;;
      --quiet)    QUIET=true ;;
    esac
  done

  # Overall timeout (5 min default, override with SCRIPT_TIMEOUT)
  local timeout="${SCRIPT_TIMEOUT:-300}"
  if [ "${_FORGE_TIMEOUT_ACTIVE:-}" != "1" ]; then
    export _FORGE_TIMEOUT_ACTIVE=1
    exec timeout --kill-after=15 "$timeout" "$0" "$@"
  fi

  # Cleanup trap
  trap '_forge_cleanup' EXIT
}

log() {
  local msg="[${TIMESTAMP}] [${SCRIPT_NAME}] $1"
  echo "$msg" >> "$LOG_FILE" 2>/dev/null || true
  if [ "$QUIET" != true ]; then
    echo "$msg" >&2
  fi
}

load_env() {
  local env_file="${FORGE_ROOT}/.env.system"
  if [ ! -f "$env_file" ]; then
    log "WARNING: .env.system not found"
    return 1
  fi
  TELEGRAM_BOT_TOKEN=$(grep '^TELEGRAM_BOT_TOKEN=' "$env_file" | cut -d= -f2- | tr -d '[:space:]')
  TELEGRAM_USER_ID=$(grep '^TELEGRAM_USER_ID=' "$env_file" | cut -d= -f2- | tr -d '[:space:]')
}

check_dnd() {
  # Returns 0 if NOT in DND (safe to notify), 1 if in DND (suppress)
  local dnd_config="${FORGE_ROOT}/config/dnd.yaml"
  if [ ! -f "$dnd_config" ]; then return 0; fi

  local dnd_enabled dnd_start dnd_end
  dnd_enabled=$(yq '.dnd.enabled // false' "$dnd_config" 2>/dev/null || echo "false")
  [ "$dnd_enabled" != "true" ] && return 0

  dnd_start=$(yq '.dnd.start_hour // 22' "$dnd_config" 2>/dev/null || echo "22")
  dnd_end=$(yq '.dnd.end_hour // 7' "$dnd_config" 2>/dev/null || echo "7")

  local hour
  hour=$(date +%-H)

  if [ "$dnd_start" -gt "$dnd_end" ]; then
    if [ "$hour" -ge "$dnd_start" ] || [ "$hour" -lt "$dnd_end" ]; then
      return 1
    fi
  else
    if [ "$hour" -ge "$dnd_start" ] && [ "$hour" -lt "$dnd_end" ]; then
      return 1
    fi
  fi
  return 0
}

notify() {
  local message="$1"
  if [ "$DRY_RUN" = true ]; then
    log "DRY RUN — suppressed notification"
    return 0
  fi

  if [ "$SKIP_CHECKS" != true ] && ! check_dnd; then
    log "DND active — queuing notification"
    echo "$message" >> "${FORGE_ROOT}/logs/dnd-queue.txt"
    return 0
  fi

  [ -z "${TELEGRAM_BOT_TOKEN:-}" ] && load_env

  if [ -z "${TELEGRAM_BOT_TOKEN:-}" ] || [ -z "${TELEGRAM_USER_ID:-}" ]; then
    log "WARNING: Telegram not configured"
    return 1
  fi

  curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
    -d "chat_id=${TELEGRAM_USER_ID}" \
    --data-urlencode "text=${message}" \
    -d "parse_mode=Markdown" \
    >/dev/null 2>&1 || {
      log "WARNING: Telegram send failed"
      return 1
    }
}

_forge_cleanup() {
  local exit_code=$?
  if [ "$exit_code" -eq 124 ]; then
    log "ERROR: Script timed out"
    [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && \
      curl -sf -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
        -d "chat_id=${TELEGRAM_USER_ID}" \
        -d "text=${SCRIPT_NAME} timed out. Check logs." \
        >/dev/null 2>&1 || true
  fi
  if [ -n "${_forge_lock_name:-}" ]; then
    release_lock
  fi
}

Timer Template

# File: services/forge-<NAME>/forge-<NAME>.timer
[Unit]
Description=Forge <DESCRIPTION> timer — <SCHEDULE_HUMAN>

[Timer]
# For interval-based (every N seconds/minutes):
# OnBootSec=60
# OnUnitActiveSec=<INTERVAL>

# For calendar-based (specific times):
# OnCalendar=*-*-* HH:MM:SS
# OnCalendar=Mon *-*-* 09:00:00

Persistent=true

[Install]
WantedBy=timers.target

Service Template

# File: services/forge-<NAME>/forge-<NAME>.service
[Unit]
Description=Forge <DESCRIPTION>
After=network.target

[Service]
Type=oneshot
User=forge
Group=forge
WorkingDirectory=/opt/forge
ExecStart=/opt/forge/scripts/<NAME>.sh
KillMode=process
EnvironmentFile=/opt/forge/.env.system
StandardOutput=journal
StandardError=journal

Skill Wrapper Template

---
name: <NAME>
description: <DESCRIPTION>. Runs <NAME>.sh on demand.
  Use when user says "/<NAME>", "run <NAME>", or "check <NAME>".
---

# /<NAME> — <Title>

You are running the /<NAME> skill. This wraps the
scheduled automation for on-demand use.

## What It Does

<1-2 sentences: what this automation checks/does/produces>

## How to Run

Run the script and present its output:

```bash
bash /opt/forge/scripts/<NAME>.sh --now 2>&1
```

### Flags

| Flag       | Effect                                               |
|------------|------------------------------------------------------|
| (none)     | Normal run, respects DND, sends Telegram             |
| --dry-run  | Runs logic but suppresses Telegram                   |
| --now      | Skips DND check and schedule validation              |
| --quiet    | Suppresses stderr logging                            |

## After Running

1. Present the script output to the user
2. If errors occurred, suggest fixes
3. If --dry-run, ask if user wants to run for real

## RULES
- Always use --now flag when running on-demand
- Default to --dry-run if user just wants to see results
- Show full output — don't summarize unless user asks

Cost Estimate

Risks & Mitigations

Open Questions

1. Migrate existing scripts? Should we refactor brief.sh, heartbeat/check.sh, etc. to use forge-std.sh, or leave as-is? Recommendation: leave existing scripts alone. Only new scripts use the standard.
2. DND timezone: Config uses UTC hours. Jason is in CST (UTC-6). Keep UTC or switch to local? Recommendation: keep UTC for consistency. Document CST equivalents in comments.
3. Skill naming: Use timer name (/forge-followup) or short name (/followup)? Recommendation: short names. Skills are for humans; systemd names are for systemd.
4. Evening digest scope: What should it include? Recommendation: start with Task Board changes + Ralph activity summary. Expand later.
5. Contact ingest dependency: Blocked on Google OAuth steps 7-8. Recommendation: build skeleton now with --dry-run default. Unblock activates it.

Service Convention Compliance

• Registered in config/services.json (each timer gets an entry)
• Health visible via systemctl is-active (systemd native)
• Logs in logs/<name>/ (standard location)
• N/A: /health endpoint (timers don't serve HTTP)
• N/A: /docs endpoint (skills serve as docs)