Workflows

Workflows sit one layer above recipes. A workflow is a playbook the calling agent reads to learn how to iterate items in a domain (one control, all pending scope questions, the entire campaign). Recipes describe what to do per item; workflows describe how to walk the items.

Three-layer routing model:

engagement (deterministic Python rules)
  → workflow (markdown playbook the calling agent reads)
    → recipe (calling agent picks per item from the menu)

The engagement layer (start_task) lands later — see the roadmap. v1 ships the workflow registry and the per-workflow playbook markdown so the agent can navigate manually.

What Ships in v1

Four built-in workflows:

Browse them:

pretorin recipe list  # for recipes (CLI)

There’s no pretorin workflow list CLI yet — workflows are discovered through MCP only:

• list_workflows — summary metadata for every loaded workflow.
• get_workflow(workflow_id) — full manifest plus the markdown body.

How a Workflow’s Body Looks

Every workflow body has the same shape: a brief intent statement, a description of the iteration shape, a step-by-step block, and a “what to avoid” closing section. Read one of the built-ins as a template:

cat src/pretorin/workflows_lib/_workflows/single-control/workflow.md

The frontmatter declares:

Why Workflows Matter

Without workflows, the calling agent would freelance the iteration pattern for every task. That’s drift-prone — different agents hit the same questionnaire and follow different orders, producing inconsistent audit trails. The workflow body fixes the pattern: load pending items, filter, iterate, pick a recipe per item, submit through the audit boundary, optionally trigger review.

recipes_commonly_used is a hint, not a binding. The agent reads list_recipes(system_id=...) at runtime and picks per-item by matching use_when strings against recipes whose required sources are connected. When no recipe fits, the workflow surfaces a structured recipe_gap instead of writing directly.

Server-Side vs Calling-Agent Iteration

Three of the four workflows are calling-agent iteration: the agent loops items in its own context window, calling MCP tools per item. Fine for small sets (one control, ~50 questionnaire items).

campaign is server-side iteration: pretorin’s own CodexAgent walks items inside pretorin, calling the same recipe surface. The calling agent kicks off the campaign and observes status — it doesn’t iterate items in its own context. This is what makes thousand-control campaigns tractable without overwhelming the calling agent’s context window.

Authoring a New Workflow

v1 doesn’t ship a workflow scaffolder — workflows are first-party only. If you need a new iteration shape, open an issue describing:

• What domain it iterates (controls? questions? something else?).
• Why the existing four don’t fit.
• The recipes the workflow would commonly use.

Community workflows land in v1.5 once the engagement layer is in place and the routing rules can include community contributions safely.

What’s Already Wired

• Engagement layer (start_task) — picks the workflow from the user’s prompt entities. See Engagement Layer.
• Capture preflight — start_task returns suggested_capture_plan and workflows can refresh it with check_sources. Evidence and narrative writes then proceed through recipe contexts.

Roadmap

• Richer recipe execution — add more first-party and community recipes for operational systems such as GitHub, Kubernetes, and eMASS.
• Community workflows — third loader path, scaffolder, validator. v1.5.