Designing agentic development workflows: principles for a workflow you can trust
Agentic workflows rely on strict architecture and doctrine to ensure each step behaves correctly. Key ideas include a thin orchestrator, a single run directory, artifact‑based phase interfaces, guard scripts, content‑based gates, fresh judgment contexts, script‑controlled loops, and clear rules for…
When building automated systems that let AI agents make decisions, the biggest challenge is keeping the sequence of steps honest. A well‑structured workflow is only half the battle; the other half is ensuring that every phase behaves as intended, even when the underlying models are prone to produce plausible but incorrect outputs. The following principles, grouped into machinery and doctrine, provide a blueprint for creating workflows that are both reliable and auditable.
1. Keep the Orchestrator Thin
The orchestrator should only manage control flow, gates, and dispatch. It runs on whatever model the current session uses, keeping it lightweight. All judgment is pushed into sub‑agents that declare their own tier, ensuring that the model’s power is matched to the complexity of the decision. This separation also makes it easy to upgrade the underlying model without touching the orchestrator logic.
2. Use a Single Run Directory
Every execution gets a durable directory that is the sole channel across dispatch boundaries. Because environment variables and working directories do not survive a sub‑agent call, the run directory’s path is passed as a literal argument to every dispatched step. All run state lives in a single JSON file written atomically, allowing the workflow to be inspected, resumed, or audited by anyone without needing the original transcript.
3. Artifacts as Phase Interfaces
Each phase produces a named file that the next phase consumes. Renaming outputs prevents accidental reuse of stale data and makes it trivial to re‑run, inspect, or replace individual steps. For example, a "plan.json" produced by the planning phase is read by the implementation phase, and a "report.md" generated by the final phase can be reviewed independently.
4. Guard Seams with Simple Checks
Before a phase runs, a tiny guard script verifies that all required artifacts exist and are non‑empty. This turns silent failures—where a model writes nothing or writes to the wrong location—into loud, correctly attributed stops. The most critical guard is for the final report step, which often outputs prose instead of a file.
5. Gates Must Be Checks, Not Promises
A gate records approval by hashing the artifact’s content and appending the hash to an immutable log. On each run, the workflow recomputes the hash and refuses to proceed if it is missing. This ensures that revisions cannot inherit old approvals and that an agent cannot fabricate approval. The same check is applied at every gate, including the final external‑world publish step.
6. Fresh Context for Judgment
Any step that judges earlier work is dispatched as a fresh sub‑agent, preventing it from inheriting the context of the agent that produced the work. This bias control ensures that, for instance, the agent deciding whether a pull‑request comment is valid has not seen the code that generated the comment.
7. Script‑Controlled Build Loops
The build phase consists of an inner implement‑validate loop and an outer re‑plan loop. After each validation, a deterministic referee script reads a verdict and decides whether to continue, retry, re‑plan, or stop. The verdict includes a failure class—tactical, mechanical, strategic, or environmental—allowing the referee to choose the correct action. This prevents endless retries on transient errors and ensures that environmental failures surface immediately.
8. Tests Must Prove Their Relevance
Tests are written before implementation and confirmed failing. After a successful build, a prover reverts the production files, reruns the tests expecting failure, and records a verdict. If the tests still pass after the revert, they did not actually test the change, exposing a vacuous test suite.
9. Adapters Are the Only Network‑Aware Components
Reasoning agents read and write files; only adapters interact with external services. This separation lets the same workflow run against a live pull request or a static artifact without degrading functionality.
10. Enumerate All Terminal States
Every possible exit path—done, done‑but‑unproven, nothing‑to‑do, bad‑input, stuck, not‑approved—must produce a report. This ensures that even “boring” outcomes are logged and auditable.
Doctrine: Rules for Decision Making
Beyond machinery, doctrine governs what steps should refuse to do, how they treat external text, and how they record decisions.
- Restraint as a First‑Class Outcome: When a step receives external input, it can choose to do nothing, answer a question, or raise a ticket. The decision is auditable, and the run is considered successful only if the tree remains unchanged where it should.
- Never Perform Socially Irreversible Actions: Actions like force‑push, resolving review threads, or auto‑merging are forbidden in code. The workflow can only automate reversible actions; irreversible steps require a human.
- Treat Incoming Text as Data, Not Instructions: Steps that ingest external text must classify it and refuse to execute any embedded commands. This protects against malicious payloads.
- Establish Provenance Before Judging: External feedback refers to a specific code version. The workflow must determine that version and its distance from the current state before evaluating the feedback.
By combining these machinery and doctrine principles, developers can build agentic workflows that are transparent, auditable, and resilient to the quirks of large language models.
Why it matters
Reliable agentic workflows are essential for scaling AI automation without sacrificing control or safety. These principles guard against silent failures, unauthorized changes, and irreversible mistakes, ensuring that automated decisions remain trustworthy.
Key points
- Thin orchestrator keeps control flow lightweight
- Single run directory provides durable, auditable state
- Artifact interfaces enable modular, re‑runnable phases
- Guard scripts catch silent failures early
- Content‑based gates enforce genuine approval
- Script‑controlled loops prevent endless retries
- Tests must prove they actually test changes
- Adapters isolate network access
Frequently asked questions
What is an agentic workflow?
An agentic workflow is a sequence of automated steps where each step can be driven by an AI agent that makes decisions based on its own reasoning.
Why must the orchestrator be thin?
Keeping the orchestrator thin ensures it only handles control flow, making the system easier to maintain and allowing heavier reasoning to be delegated to sub‑agents with appropriate models.
How does the run directory improve reliability?
The run directory acts as the sole channel across dispatch boundaries, ensuring all state is persisted atomically and can be inspected or resumed later.
What is a gate in this context?
A gate is a check that records approval by hashing an artifact’s content, ensuring that approvals cannot be forged or inherited by revisions.
