scheduled-improvement-loops

name	scheduled-improvement-loops
description	Use this whenever an agent wants OpenForage to periodically emit algorithm review or improvement prompts through callbacks. Trigger for scheduled improvement, algorithm improvement loop, periodic prompt, run_due_callbacks, improvement_prompt, search refinement cadence, or automated review loop.

Scheduled Improvement Loops

STOP. If you have not read the OpenForage Library README.md at the repo root §0–§C, read it first. This skill is depth reference for the T-OF-schedule bootstrap task. The README §E.4e shows the recommended cadence for run_due_callbacks() per runtime (Claude CLI ScheduleWakeup / CronCreate, Codex CLI update_plan tick, Hermes runtime tick or /goal loop if configured, OpenClaw Lane Queue), and §F documents the improvement_prompt event schema sinks will receive.

Scheduled improvement callbacks create periodic improvement_prompt events. They do not run an optimizer by themselves; they emit prompts to the registered non-scheduled callbacks for an agent runtime to consume.

Register Outputs First

Use a file callback as the default output sink.

from openforage.callbacks import register_callback

register_callback(
    data_dir=".openforage/data",
    callback_type="file",
    path=".openforage/data/improvement-events.jsonl",
)

Add A Scheduled Prompt

from openforage.callbacks import register_callback

register_callback(
    data_dir=".openforage/data",
    callback_type="scheduled_improvement",
    interval_seconds=3600,
    prompt="Review current OpenForage status, recent_errors, algorithm_state, and events.jsonl. Suggest one conservative next algorithm adjustment.",
)

Run Due Callbacks

Call this from the owning agent runtime's scheduler.

from openforage.callbacks import run_due_callbacks

result = run_due_callbacks(data_dir=".openforage/data")

result["events_emitted"] is the number of due improvement prompts. result["callbacks_dispatched"] is the number of non-scheduled callbacks that received them. There is no hard registry max/rate limit: each due enabled scheduled callback emits one prompt per run_due_callbacks() call, and dispatch is synchronous/serial to all enabled non-scheduled sinks. Effective rate is set by interval_seconds and the owning runtime's call cadence.

Operating Rules

• Keep prompts specific and conservative.
• Include status, recent_errors, algorithm_state, and event-log review in the prompt.
• Avoid promises about earnings or signal discovery.
• Use one state directory for the worker, callback registry, and output events.
• Let the external runtime decide whether and how to act on the prompt.
• Never suggest, recommend, or explore signal compute-graph depth greater than 6. The depth-6 cap is a hard agent-side rule independent of the era's max_depth — see README.md §G Hard Rules.

If no file, webhook, or shell callback is registered, due scheduled prompts have nowhere useful to go.

Review A random_weighted Fork

For a scheduled review of a forked template, make the prompt diagnose and compare instead of promising automatic tuning. Scheduled callbacks do not automatically optimize and do not run an optimizer; the owning runtime decides whether to edit or keep the fork.

register_callback(
    data_dir=".openforage/data",
    callback_type="scheduled_improvement",
    interval_seconds=3600,
    prompt=(
        "Review the random_weighted fork. Inspect analytics such as "
        "openforage.templates.analyze_random_weighted, get_search_stats(), "
        "get_search_patterns(), and get_yield_analysis() to diagnose what "
        "worked, failed, changed yield, or produced passing candidates. "
        "Before recommending action, require a bounded validation loop and "
        "compare baseline versus fork cold/warm distribution and behavior. "
        "Reject any fork or recommendation that produces expressions with "
        "compute-graph depth > 6, regardless of the era's max_depth. "
        "This scheduled_improvement improvement_prompt does not run an optimizer."
    ),
)

Checklist for the receiving agent:

• Open the bundle SKILL.md or skill guidance before changing the custom template.
• Use analytics diagnosis to explain what worked, failed, changed yield, or passed.
• Require bounded local validation before acting on the fork.
• Compare baseline vs fork behavior, including cold and warm distribution.
• State that scheduled callbacks do not automatically optimize.

Adjacent Skills

• callback_hooks — read before T-OF-callbacks-sink (register at least one non-scheduled sink first).
• agent_runtime_integration — read before T-OF-improvement-loop (per-runtime durable outcome + tick patterns for run_due_callbacks()).
• background_search_loops — read before T-OF-start-search-bg (the worker must be running for analytics-driven prompts to be meaningful).