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 itWhy 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 unboundedlyDistinction from Dynamic Data
| Characteristic | Static Configuration (✅) | Dynamic Data Abuse (❌) |
|---|---|---|
| When created | At workflow design time | During execution |
| Content source | Curated by workflow author | Generated by agent/tools |
| Size | Known and bounded | Potentially unbounded |
| Purpose | Guide agent behavior | Pass data between steps |
| Changes | Only when workflow is edited | Every 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.