Skip to content

Static Workflow Configuration

Overview

Static Workflow Configuration is the practice of declaring curated rules, standards, checklists, and instructions as global variables in the workflow variableRegistry with a default value. These are deliberately placed so the agent sees them on every relevant step, making the authored text available where it is referenced. Delivery does not prove understanding or compliance.

This is a correct pattern — do not confuse with Dynamic Data in Workflow Variables. A curated variableRegistry default is fundamentally different from dynamic data flowing between steps.

When to Use

Use static workflow configuration when:

  • Agent must follow specific rules consistently across multiple steps
  • Instructions are curated and stable (not generated during execution)
  • Content is essential for workflow quality (not optional reference data)
  • You need the workflow engine to guarantee delivery of instructions to the agent

How It Works

variableRegistry (with default values):
planning_standards: "1. Each step must have tests... 2. No code in plan..."
code_quality_rules: "1. Fix root cause, not symptoms... 2. Test after changes..."
validation_checklist: "□ Requirements met □ Tests pass □ No regressions"
Step directive: "Create plan following {{planning_standards}}"
→ Workflow engine injects the registry default into the directive
→ Agent receives the referenced text and remains responsible for applying it

Why Not Files?

A short workflow-owned rule can be interpolated directly. A long reference needs a canonical address for selective reading and independent reviewers. Materializing it once is valid; existing project instructions remain owned by their project files. In either case require actual access and application, not an assertion that delivery guarantees correctness.

Examples

Good: Planning Standards in Development Workflow

{
"variableRegistry": {
"planning_standards": {
"type": "string",
"description": "Rules agent must follow when creating plans",
"default": "PLANNING STANDARDS:\n1. Each step implements functionality + tests\n2. No testing-only steps\n3. Verification criteria required..."
}
}
}

Directive references: "Create development plan following {{planning_standards}}"

Good: Validation Checklist

{
"variableRegistry": {
"validation_checklist": {
"type": "string",
"description": "Quality gates for code review",
"default": "CHECKLIST:\n□ All tests pass\n□ No type errors\n□ Coverage maintained\n□ No security issues"
}
}
}

Not This Pattern: Dynamic Extraction Results

// ❌ This is dynamic data in workflow variables, not static configuration
{
"inputSchema": {
"extraction_results": { "type": "object" },
},
}
// Data generated during execution, grows unboundedly

Distinction from Dynamic Data

CharacteristicStatic Configuration (✅)Dynamic Data Abuse (❌)
When createdAt workflow design timeDuring execution
Content sourceCurated by workflow authorGenerated by agent/tools
SizeKnown and boundedPotentially unbounded
PurposeGuide agent behaviorPass data between steps
ChangesOnly when workflow is editedEvery execution

Static Configuration or a Playbook

A registry default holds text that belongs to this workflow and changes with it. A playbook holds named behaviour text that lives on its own: a review standard, a tone of voice, a definition of done. A node names one with {{playbook:review-standard}}, or {{playbook:@owner/name}} for another account’s published one.

Choose a playbook when the same text serves more than one workflow, or when the person who should change it does not edit workflows: editing a playbook changes behaviour without touching the graph, and the reference resolves at every step, so a running execution picks the change up at its next step.

Choose a registry default when the text belongs to this workflow alone, or when it is a template fragment computed from the run’s own variables. A default can itself carry a playbook reference, which is how a declared variable delivers shared text to a node that reads the variable.

A reference to a playbook the author cannot read is refused while editing and before a run starts. If one becomes unreadable mid-run, the step continues with a visible placeholder and the execution records that it ran without that text.

When the Text Needs an Address

For workflow-authored stable text, a registry default can be the canonical source. Project rules and shared playbooks retain their own source owners. Choose whether the run also needs a readable file address.

A short rule that one node applies whole belongs in that node’s directive: giving it a path would add a read and an indirection for nothing. A body of criteria that outlives the step — planning rules, engineering principles, a review contract — is a document: readers navigate it by section, return to it across steps, and independent reviewers must read it themselves. That needs an address.

The workspace owner writes it once, in the turn where it already creates the workspace, and later directives name the path:

{
"directive": "Use the applicable sections of {{workspace_path}}/authoring-reference.md. The path is canonical; reread unchanged content only when it is absent, uncertain, or changed."
}

Without an address the same body is rendered into every directive that obeys it, and a subagent — who never sees the parent’s directive — cannot be given it at all, so the parent starts copying the text into a prompt. That failure is catalogued as A Reference With No Address.

Size Guidance

Respect the active transport and context limits. Prefer a materialized reference when readers need selected sections. Static configuration should be:

  • Deliberately curated (not auto-generated)
  • Stable across executions
  • Essential for agent behavior

The bundled Workflow Management Flow stores thematic authoring references in workflow_reference_* string defaults, including engine, design, artifacts, review/repair, validation, authority, patterns, antipatterns, progress, and requirements-conversation guidance. Its workflow_template_* defaults hold starting JSON workflows. The bootstrap materializes them under reference/ and reference/templates/; each substantive consumer reads its applicable files. See the actual bootstrap declaration. Software Development Flow likewise stores its planning criteria in the planning_standards string default.