Sequences: agent automation that runs itself · crystl

Crystl Sequences

The work that never gets done is the work you have to remember to do. Filing the call. Turning the notes into tasks. Keeping the client record current. Each one is ten minutes, none of them is hard, and all of them slide.

A sequence takes one of those jobs and writes it down as a set of stages an agent runs start to finish. Then it stops being your job. A schedule can start it, a file landing in a watched folder can start it, or a URL changing can start it. You find the work already done.

The definition is a file at .crystl/sequences/<name>/sequence.json in your own project folder, so it is reviewable, diffable, and shared with everyone who clones the repo. Each stage names an agent, a size, and a brief, then declares what it reads from earlier stages and what it writes. crystl passes exactly those files between them and nothing else, so a stage cannot quietly depend on something the definition never mentions.

Automation you cannot trust is worse than none, so every stage has its own accept gate: the files it promised have to exist, be non-empty, or match a JSON schema. A stage that produced nothing fails there. The run stops instead of handing the next stage an empty file, so the mistake never reaches the later stages.

Cost is the other reason a daily job doesn't last. Sizes are yours to map, so the heavy parsing stage can run on a standard model while the tidy-up stages run on a small one, and any size can point at an open model on your own hardware.

Writing and validating a definition is free on every tier, since it is a file in your project folder. Running one, and any trigger that runs one for you, needs a Guild membership.

Sequences are an early preview. A definition you write today may need adjusting as the format settles.

Why it matters

It starts without you

A calendar recurrence, a file landing in a watched folder, or a change at a polled URL. The job you would have remembered to do on Monday is done before you open your laptop.

The same job every time

Asking an agent to redo a five-step job next week gets you a slightly different job. A sequence is the job written down, so this month's run matches last month's.

A bad stage stops there

Every stage has an accept gate that checks what it produced. A stage that promised a file and wrote nothing fails, rather than passing an empty file down the line for you to find later.

Cheap enough to run daily

Parsing is usually the expensive part and the rest is not. Give the first stage a standard model and the later stages a small one, or your own open model, and a daily job costs what it should.

Unattended, and still fenced in

Anything that runs while you are away declares what it is allowed to do. The sequence sets the outer envelope and every stage is limited to what it allows. A stage can narrow that list. It can never widen it.

Try it before it costs anything

crystl sequence validate resolves the whole thing, every stage, agent, size, and trigger, and reports what would happen without starting an agent. A draft cannot fire until you publish it.

Frequently asked questions

What is a sequence?

A recurring job written down once and automated end to end. It runs as a set of agent stages, each handed what the last one produced, and it can start itself. The definition lives at .crystl/sequences//sequence.json in your own project folder.

What sort of work is worth automating this way?

Anything you redo on a rhythm and keep putting off. Filing a call transcript as a memory, turning it into tasks and a client record, triaging the overnight test failures, or sweeping a feed for what changed and writing it up. The job has to be describable in steps; it does not have to be code.

How is a sequence different from fanout or a scheduled agent?

Fanout spreads one task across many agents working at once. A schedule runs one payload on a timer, a prompt or a command, with no stages and no gates. A sequence automates a whole job: stages in order, each one handed the last one's output, each one checked before the next starts.

What can start a sequence?

Four triggers are implemented today: manual, a calendar schedule at a wall-clock time, a change to a watched file path, and a polled URL whose content changed. Watched paths are literal prefixes rather than globs, and a poll response has to validate against a JSON Schema you declare before the run starts.

What stops a stage from producing garbage for the next one?

Its accept gate. A stage can require that files exist, that they are non-empty, or that they match a JSON schema. If a stage promised a file and did not write it, the stage fails and the run stops rather than handing the next stage an empty input.

What happens when a stage finds nothing to do?

It reports crystl stage nothing, which is a success: the run keeps going. That is different from crystl stage blocked, which means the stage needs a person, so the run parks until you deal with it.

Can different stages use different models?

Yes. Each stage picks its own agent and size, so the expensive parsing stage can run on a standard model while the later stages run on a small one. Sizes map to whatever you taught crystl, including an open model on your own hardware.

Are sequences free?

Writing and validating a definition is free on every tier, since it is a file in your own project folder, and so is reading the catalog and the record of past runs. Running a sequence, and any schedule, file, or poll trigger that runs one for you, needs a Guild membership.

Are sequences finished?

They are an early preview. The shape of a definition file may still change between releases, so treat one you write today as something you may need to adjust later.

More features