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) deterministically selects the appropriate playbook from prompt entities. Agents can also inspect the registry directly.

What Ships in v1

Nine 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

All workflows except campaign use calling-agent iteration: the agent follows the loaded playbook in its own context window, calling MCP tools per item or lifecycle gate. This is appropriate for bounded sets such as one control, questionnaire items, one STIG rule, the system risk register, or one formal assessment.

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 workflows don’t fit.
• The recipes the workflow would commonly use.

Community workflows remain a future extension because routing rules must include third-party contributions safely and deterministically.

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.