Agister · settings

Agister's settings architecture

Settings define the work; runs and calls are what executed it. Agister reads settings from up to three layers, composes each document field by field, and resolves a request into definitions that core executes as a run, or into a refusal that names the chain at fault. Definitions live in settings, not in code; code adds only a runtime or a kind of input source.

Three axes

Each thing has one name, on one axis. A definition is declared, resolved and planned; it never runs. An execution starts and ends; it is never declared.

DEFINITIONS

in settings

workflow
work defined by inputs, an output contract and children, each a step or a workflow, composed by sequence, parallel, branch or bounded repetition; its bindings carry data into each child, and its conditions choose a branch, accept a result and end a repetition
step
a process bound to an agent, the one leaf; its inputs and output contract are its process's
process
what a step does: its prompt, inputs, environment, output schema, permissions and limits
agent
who does it: a runtime mapping, and the model, effort and skills its runtime takes; a bash agent names only the runtime
runtime mapping
what its runtime grants with no option, and its options with what each grants; bash offers none

EXECUTIONS

in records; each names the definition it executes

run
executes a workflow
call
executes a step
iteration
one execution of a repetition's body; every other child executes once, as a call or a run
turn
one exchange of a call with its runtime
session
the conversation a call held, on a runtime that keeps one

MACHINERY

in code, as settings meet it

runtime
a program Agister drives through its wrapper; a runtime mapping names one
runtime facts
what a runtime can do; resolve refuses a step that needs what its runtime cannot do

What a workflow names

Documents name each other by kind and name, fixed in settings, so they resolve without a run. A workflow composes steps and other workflows. A step binds a process to an agent; nothing but a step chooses an agent. Bash is a runtime, planned like any other: its agent names only the runtime, and its prompt is a script.

child workflow workflow step process agent prompt schema brief form skill runtime mapping
A process names its prompt, guidance, output schema and skills; a workflow's or a process's text inputs may name brief forms; an agent names its runtime mapping and its skills. A child workflow is another workflow: references never form a cycle.

Where settings live

Each kind has its folder in a layer, and a document is the file named after it. Nothing but kind and name joins files across layers.

agentagents/<name>.toml
processprocesses/<name>.yaml
workflowworkflows/<name>.yaml
runtime mappingruntimes/<name>.yaml
brief formbrief-forms/<name>.yaml
schemaschemas/<name>.json
promptprompts/<name>.md
skillskills/<name>/SKILL.md — not read yet
  1. home~/.agister
  2. repository.agister at the worktree root, with blocks.yaml
  3. projectthe nearest .agister from the launch directory up to the root
  • applied home first; the nearer wins
  • maps merge by key
  • lists and scalars replace whole
  • nothing unsets

The launch directory is where the command is launched, or --dir; the layers select settings, not the place of work. Each layer is over its parent alone, and outside a git worktree only home is read. Schemas, prompts and skills are taken whole from the nearest layer. A document may name another of its kind in extends: the extended one is composed first, the extending one over it.

The repository's blocks.yaml names documents it refuses, each with a reason; whatever depends on a blocked document is refused, naming the block.

From files to definitions

Resolve takes a request: a document by kind and name, such as a workflow with its parameters, or a step given as a process and an agent, which resolves as a workflow of that one step. Resolve is the gate before a run: what resolves may run; what does not never reaches core and leaves no run.

runtime facts list names fields, each with its source files layout kind, name → file documents format layering · kinds resolve references · blocks boundaries · bindings each step's plan core check runtime wrappers
An arrow is what flows, and the composition carries every one: no settings package imports another. Resolve plans each step from its process's permissions and its agent's mapping. check is handed resolve and resolves every document, by the names layout lists. Runtime facts and the document source are resolve's ports; the composition answers runtime facts from the wrappers.
a documentA problem in a document refuses only what depends on it, naming the chain to the document at fault.
no documentA problem of no document refuses every request.
a planA plan gives every required permission or refuses; what it grants beyond what the process allows is a warning.
a runtimeA step that needs what its runtime cannot do refuses, with the request that holds it, in branches a run may not take too.

The parts

PackageOwnsPorts
settings/layoutwhere settings live; a kind and name to a file; lists namesfilesystem; worktree root
settings/documentsbytes to typed definitions with each field's source: format, layering, kindsnone: pure
settings/resolvea request to definitions or a refusal naming the chaindocument source; runtime facts
settings/checkcheck, every problem and what it refuses, and inspect, with each field's sourceresolve; list names; a document's fields, each with its source
settings/homeinstall into home and restore: only home's settings, on a broken home too; every write can be undonefilesystem writes; clock

No settings package imports another; the composition connects them. Core takes the resolved workflow and every step's process, agent, runtime mapping and permission plan, and never reads a settings file.

What a run does with them

A workflow's items run in order: a step is one call; a parallel calls its steps and workflows at once; a branch runs the first arm whose condition holds, else its default; a repeat runs its body at least once, binds its next state, and stops when until holds or after max passes; a workflow item runs another workflow as a child run. Home's code_review runs its tests lens as the workflow tests_debate: one model drafts the review, another critiques it, and the writer revises in its own session until the critique converges or two passes have run; only the last review reaches the judge. Whatever this Agister does not run yet, agister check refuses as agister run would, before anything runs. The run architecture follows a run from the command to its record.