Automations

A factory line is Islo’s automation product: multi-stage work with typed routing, loops, schedules, and event triggers. A line (line.toml) orchestrates stages; each stage runs a job (job.toml); jobs execute in sandboxes. Agents do the judgment work.

Do not author manifests from memory. Scaffold jobs with islo job init, then confirm every field against the installed CLI:

islo schema factory --short
islo schema job --short

Unknown keys 422. Treat every TOML snippet here as a pattern, not a drop-in. Copy a nearby example from islo-labs/islo-agents (examples/) and edit it against the live schema.

For AI agents, install islo-labs/skills. Use the factory-lines skill to build and debug lines; use the platform skill for sandboxes, snapshots, gateway profiles, incoming webhooks, environments, knowledge, and the SDK.

Building blocks

Building block	Role
factory line	The workflow: trigger, stages, transitions, limits.
Job	One stage’s unit of work: params, outputs, sandbox, `run_agent` / `exec` steps.
Trigger	What starts a line run: manual, schedule, line webhook, or a GitHub / Slack / Linear integration.
Snapshot	Prebuilt sandbox image. Put harness code (and bulky supporting briefs) here. Stage briefs belong in the job `run_agent` prompt so a prompt change is a new job version. Do not `git clone` briefs on every run.
Incoming webhook	Separate product: HTTP event → sandbox lifecycle or a single job. Not a substitute for a multi-stage line.

A standalone scheduled or manual job (no line) is the exception. Use it only when there is explicitly one stage and no routing.

factory lines

Standard layout:

line.toml
jobs/<stage>/job.toml

A line declares identity, what starts a run, the stages, and the routing between them. Harness, model, params, and outputs live on each stage’s job — not on the line.

Required sections (confirm names and fields with islo schema factory --short):

Section	Purpose
`[line]`	Name and optional description / category
`[trigger]`	How runs start
`[[stages]]`	Each stage `id` plus the `job` it runs
`[[transitions]]`	Conditional or agentic routing, including an entry from `trigger` and completion to `done`

Reserved stage ids: trigger, done, wait.

Triggers

Trigger	Use when
`manual`	An operator or the API starts runs; also the right first trigger while a line is under test
`schedule`	Recurring cron-based runs
`webhook`	An HTTP POST to a line-owned path starts runs
`integration_trigger`	Provider-native GitHub, Slack, or Linear events start runs

Schedules live in the line [trigger] and nowhere else. A schedule created in the UI or on a job and then overwritten by the next line deploy is that mistake:

[trigger]
type = "schedule"
cron = "0 7 * * *"
timezone = "UTC"

Discover integration events and whether the tenant is connected:

islo factory triggers list --with-status
islo factory triggers get slack message.received
islo factory triggers get github pull_request.opened

triggers get returns payload shape, selector shape, and example filters. Connect the provider first (islo login --tool slack, GitHub, or Linear) if status shows disconnected.

Line webhook vs incoming webhook:

	Line `[trigger]` `webhook`	Incoming webhook
Setup	`line.toml`	`islo webhook incoming create`
Target	Starts a line run	Sandbox lifecycle or a single job
Use when	Multi-stage orchestration	Ensure / resume / delete a sandbox, or fire one job

Deploy order

The line pins each stage’s job_version_id at deploy time. Redeploying a job alone does not update an already-deployed line.

Knowledge items the line or jobs reference
Every stage job
The line last

islo job deploy --path jobs/<stage>/job.toml --dry-run
islo job deploy --path jobs/<stage>/job.toml
islo factory line validate line.toml
islo factory line deploy line.toml --dry-run
islo factory line deploy line.toml

Smoke-test the first agent stage as a job before the full line is live:

islo job run <first-stage> --param KEY=VALUE --watch

Then run the line:

islo factory line run <name> --param KEY=VALUE
islo factory line-run status <run-id>
islo factory line-run events <run-id>

For integration triggers, fire one real event after deploy (open a test PR, post in the selected channel) and confirm a run appears.

Inspect and steer a run

islo factory line-run status <run-id>
islo factory line-run events <run-id>
islo factory line-run stop <run-id> --reason "<why>"
islo factory line-run retry <run-id>
islo factory line-run steer <run-id> <stage> --param KEY=VALUE
islo factory line-run follow-up <run-id> --stage-name <stage> --reason "<what>"
islo factory line-run ask <run-id> --message "<question>"
islo factory line-run agent-turn <run-id> --stage-name <stage> --message "<message>"

Symptom	Do this
Trigger fired but no run appeared	Use `islo factory line runs <name>` and `islo factory triggers list --with-status`
Stage failed	`islo factory line-run events <run-id>`, then `islo job event <command-id>`
Agent did the wrong thing mid-stage	`agent-turn` for that stage; `ask` for the line manager
422 / extra inputs	Unknown key — diff against `islo schema factory --short` / `islo schema job --short`
Line runs a stale job after you redeployed the job	Redeploy the line
Schedule vanished after deploy	Put cron on the line `[trigger]`

stop parks a run so you can steer. retry reruns the latest failed stage. Steering an active run returns 409 — stop first.

Jobs (stages)

A job is what one stage executes. Path:

jobs/<name>/job.toml

islo job init <name>
islo schema job --short
islo job deploy <name> --dry-run
islo job deploy --path path/to/job.toml

islo schema job returns the machine-readable manifest under job_toml. Control-plane OpenAPI JobManifest is the API source of truth for deploy/validate bodies.

Write params and outputs first — they are the line’s contract. Transitions bind job params from trigger outputs, literals, and prior stages’ outputs.

Policy the schema will not say:

Harness and model live on the run_agent step, never in line.toml.
Do not replace run_agent with shell-wrapped claude / cursor / codex CLIs.
Keep provider tokens out of manifests and sandbox env. Connect integrations (islo login --tool <provider>) and inject credentials with a gateway profile.
Put the stage brief in the job’s run_agent prompt so a prompt change is a new job version. If the repo already has skills, check it out with an idempotent exec step and point at that skill. Bake only supporting or fan-out briefs into the snapshot; do not clone prompts every run.
Do not copy procedural runbooks into Knowledge.

Gateway profiles keep GitHub, Slack, and model credentials out of the sandbox environment by default.

Standalone jobs

Only when you explicitly want a single durable unit of work with no line routing:

islo job init <name>
islo job deploy --path jobs/<name>/job.toml --dry-run
islo job deploy --path jobs/<name>/job.toml
islo job run <name> --param KEY=VALUE --watch

A [schedule] block in job.toml is valid for that standalone job. Every param a scheduled run needs must have a default. One active schedule per job; removing it takes effect on the next deploy. If the work grows a second stage, a decision point, or a loop, it is a line — move the schedule to the line [trigger].

Incoming webhooks

Incoming webhooks authenticate an external POST and run sandbox actions (ensure_sandbox, resume_sandbox, trigger_job, deliver to a port, pause, delete). They still need a sandbox target for ingress even when the only action is trigger_job.

Use them for PR preview sandboxes and one-shot job kicks. Use a factory line trigger for anything multi-stage. Auth, targets, rules, and actions: Incoming Webhooks.

Agent guidance

Install islo-labs/skills (npx skills add islo-labs/skills).
Follow the factory-lines skill end to end, including the design-approval gate before deploy.
Clone or browse islo-labs/islo-agents for examples — there is no in-skill copy of those templates.
Always run islo schema factory --short and islo schema job --short before editing manifests. For incoming webhook templates, run islo schema webhook.