Working with Directives

Directives are the core unit of automated work in OctoMY. A directive combines a condition (when to act) with a TaskPlan (what to do), and all triggered work flows through the batch system for full visibility.

What is a Directive?

A Directive is a named automation rule managed by the Directorate. Each Directive contains one or more Triggers, where each Trigger has:

• A condition tree that decides when to fire (time interval, calendar schedule, event, or composite logic).
• A TaskPlan that defines what to do (one or more OpalTask invocations in sequence).
• Runtime settings: recurring/one-shot, overlap policy, rate limiting.

When a Trigger's conditions evaluate to true, the Directorate submits the TaskPlan as a batch job. You can inspect all results in the Batch Activity.

Creating a Directive via the UI

1. Open the Directives activity from the Utilities menu.
2. The top pane shows the Directive Editor. Click Add to create a new Directive.
3. Give it a name and description.
4. Add a Trigger with the appropriate condition:
   • IntervalCondition: fires every N seconds/minutes/hours.
   • CronCondition: fires on specific days of the week at a specific time (e.g., every Sunday at 10:33).
   • GitRepoChangedCondition: fires when a git repository changes.
   • AlwaysCondition / ChanceCondition: useful for testing.
5. Set the TaskPlan on the Trigger (the ordered list of OpalTasks to run when the condition fires).
6. Toggle Activate in the toolbar to start the Directive.

The bottom pane shows the Runtime Panel with live status: next fire time, fire count, last result, and per-trigger pause/resume controls.

Creating a Directive via OPAL

You can manage directives conversationally through OPAL tasks:

Create a periodic directive

"Take a screenshot of all widgets every hour"

OPAL translates this to directive.new with an IntervalCondition (3600s) and the appropriate TaskPlan. The fire_immediately flag controls whether the first execution happens immediately or waits for the first interval to elapse.

Create a calendar-scheduled directive

"Every Sunday at 10:33 generate the weekly report"

OPAL creates a CronCondition matching Sunday (day 7) at 10:33. The tolerance window (default 60s) ensures the condition fires reliably even with polling intervals.

Create an event-driven directive

"Whenever the git repo changes, run the lint task"

OPAL creates a GitRepoChangedCondition that polls for repository changes.

Monitoring Directives

The Runtime Panel in the Directives activity shows:

• Status: Active, paused, or inactive per directive/trigger.
• Next fire time: When interval/cron triggers will next evaluate.
• Fire count: Total number of times each trigger has fired.
• Last status: Success/failure of the most recent batch job.

The panel auto-refreshes every second.

Pausing, Resuming, and Deleting

Via UI

Use the toolbar buttons in the Directives activity to pause, resume, or delete individual directives.

Via OPAL

• directive.pause -- pause by ID or name.
• directive.resume -- resume by ID or name.
• directive.delete -- remove entirely.
• directive.list -- list all directives with status and metadata.

Overlap Policy

When a trigger fires while a previous batch job from the same trigger is still running:

• SkipIfRunning (default): The new firing is silently skipped. Prevents runaway job accumulation.
• Queue: The new job is submitted to the batch queue and will execute after the previous one completes.

Set via the overlap_policy parameter when creating a directive.

Rate Limiting

Triggers support rate limiting to prevent excessive firing:

• maxFiresPerWindow: Maximum number of firings allowed within the time window (0 = unlimited, the default).
• rateLimitWindowMs: The sliding time window in milliseconds (default: 60000 = 1 minute).

Example: setting maxFiresPerWindow: 3 and rateLimitWindowMs: 60000 allows at most 3 firings per minute. Additional condition-true evaluations within the window are suppressed.

Viewing Batch Results

All triggered work appears in the Batch Activity:

• Filter by origin: Directive, OPAL, Manual, or System.
• Each job shows its display label, status, timestamps, and result.
• Click Go to source on a batch job detail to navigate back to the originating Directive.

Structured results

Batch job results contain full execution detail:

• Per-step success/failure with messages.
• Output values from each step (used for placeholder binding).
• Failed step index for quick diagnosis.
• Step count and plan description.

Query batch results via OPAL with batch.list and batch.status. Cancel a running or pending job with batch.cancel.

Persistence

Directives are persisted as JSON via the DirectorateBook. On application restart, previously activated directives resume automatically. The persist flag (default: true) controls whether a directive survives restarts.

Conditions Reference