Durable Workflows: Where the Work Should Live
Your agent is not where the work should live. An agent session ends, crashes, runs out of context or gets swapped for a different model; the work has to outlive all of that. This page explains what a durable workflow is, why AIDLC keeps intent, artifacts and approvals in one, and how it handles the hardest case: discovering mid-process that the intent itself needs to change.
Your Agent Is Not Where the Work Should Live
An agent session is a worker's shift, not the project file. When the session ends, everything that lived only in its context is gone: what was decided, why, what was approved, what is half done. Teams that let the work live inside a chat thread or an agent's memory find out the hard way, when a session times out mid-task or a model upgrade changes how the next session reads the same history.
A durable workflow inverts that. The truth about each piece of work - its intent, its artifacts, its approvals and its current state - lives in a store that outlasts any agent. Agents check work out, do one step, write the result back as a versioned artifact, and finish. The next agent, or the next model, or a person, picks up from exactly the same record. The agents are interchangeable; the workflow is not.
This is the same separation the rest of the site builds on: the conductor is a state machine, artifacts are typed records, and every handoff is a document, not a conversation.
What Makes a Workflow Durable
Six properties. A workflow missing any one of them still loses work, just less often.
Persisted state
Where each work item is - which phase, which step, waiting on whom - is stored outside any agent and survives restarts.
Versioned intent and artifacts
The brief, spec and ticket contract carry version numbers, and everything derived from them records which version it was built against.
Idempotent, resumable steps
A step that crashes halfway can run again without opening a second pull request or writing a duplicate record.
Human waits as real states
Waiting days for an approval is a normal state, not a stuck process. No agent session is held open while a person decides.
Explicit transitions
Work moves between states only through transitions the workflow owns, each guarded by a gate - never because an agent decided it was done.
A complete history
Every agent run, artifact version, approval and transition is recorded, so anyone can reconstruct why the work looks the way it does.
Agent Session vs Durable Workflow
The same piece of work, held two ways. The left column is what most teams start with; the right column is what survives contact with real projects.
| Question | Work held in an agent session | Work held in a durable workflow |
|---|---|---|
| Where is the current intent? | Somewhere in a long chat history | A versioned brief and ticket contract with an owner |
| What happens when the session ends? | Someone re-explains the work to a new session | The next agent reads the same records and continues |
| What happens on a crash? | Half-done work, unknown state, possible duplicates | Resume from the last recorded step; retries are idempotent |
| Who approved this? | "Looks good" in a chat, if anyone remembers | A named approval on a specific artifact version |
| What if we switch models? | The new model reads the history differently | The new model reads the same structured records, after its evals pass |
| What if a person needs days to decide? | The session times out or sits idle and billed | The item waits in a named state; no agent is running |
| Can we audit it later? | Only by reading transcripts | Every run, version, approval and transition is recorded |
What Lives Where
Durable does not mean one giant database. It means every kind of information has a home that outlasts the agent, and the agent only borrows what one step needs.
The intent
Requirements briefs and ticket contracts, with their versions, owners and acceptance criteria.
The state
Which step each item is in, what it waits on, its approvals, intent change requests and the run log.
The work product
Code, tests, specs, ADRs and the instruction file, all versioned and reviewed in pull requests.
Only the current step
What one step needs, assembled fresh from the three homes on the left and thrown away when the step ends.
The test: if an agent session vanished right now, could anyone continue the work without asking it a question? If not, something that should be durable is living in the agent.
When the Intent Changes Mid-Flight
Discovering something that changes the intent is not a failure of the process; it is the process working. An agent writing tests finds that the data contract forbids a field the brief asked for. A design agent finds the external system cannot do what the spec assumes. A reviewer realizes two criteria contradict each other. The question is not how to prevent these moments but how to handle them without losing work or letting an agent quietly redefine the goal.
The rule that makes it safe: an agent may discover that the intent needs to change; it may never decide that it has. The intent belongs to a named person, and changing it is a versioned, approved event like any other.
Detect
An agent, a check or a person finds information that contradicts the current intent, and records the evidence.
Pause the affected work
The work items built on that intent move to an intent review state. Nothing new is built against the old version; unaffected work keeps going.
Propose
The agent writes an intent change request: what it found, the evidence, the intent version it was working from, a proposed revision, and which downstream artifacts depend on what would change.
Decide
The owner of that decision answers: the product owner for the brief and its criteria, the tech lead for the design and spec. They approve, reject or split the change into new work.
Version and invalidate
The intent gets a new version. Every artifact built against the old version that the change touches - plans, tests, pull requests - is marked stale. The rest stay valid.
Resume from the earliest affected step
Work restarts at the first step that depends on what changed, not at the beginning. A revised criterion means new tests and a new plan for that slice; a revised goal can mean going back to Analyze.
How Big Is the Change?
Not every discovery needs the full process. Classify it first; the class decides how far back the work goes.
| Class | What it looks like | Who decides | What happens to work in flight |
|---|---|---|---|
| Clarification | The intent was ambiguous, and the answer changes no acceptance criterion | The intent owner, recorded as an answer in the brief | Continues; the answer is added to the context for every later step |
| Scope change | A criterion is added, removed or rewritten | The product owner approves a new brief version | Affected slices go back to tests and plan; their stale tests and plans are regenerated against the new criteria |
| Design change | The criteria hold, but the chosen approach cannot meet them | The tech lead amends the ADR and spec | Affected slices return to Ideate; finished slices that the new design does not touch stay merged |
| Direction change | The goal itself no longer holds | The product owner, back in Analyze | Affected work stops; anything already merged stays behind its flag or is reverted through its rollback plan |
An Example: The Credit Notes Nobody Mentioned
An invented scenario using the worked example's invoice export. No outcomes are claimed; it shows the mechanics.
| Moment | What the workflow does |
|---|---|
| Discovery | While writing tests for the export job, the coding agent finds that the billing service stores credit notes as invoices with a negative total. The brief, at version 2, never mentions them. |
| Pause | The export-job ticket moves to intent review. The schedule-API and settings-screen tickets do not depend on the question, so they continue. |
| Request | The agent files an intent change request: the evidence, "brief version 2", the question "include credit notes, and how are they marked?", and the dependents: the export plan and two tests. |
| Decision | The product owner classes it as a scope change: include credit notes, with a type column. The brief becomes version 3 with a new criterion, AC-4. |
| Invalidate | The export plan and its two tests are marked stale. The cross-account isolation test, which AC-4 does not touch, stays valid. |
| Resume | The ticket resumes at "tests from the criteria": the agent writes a failing test for AC-4, revises the plan, a person re-approves it, and the build continues. Nothing upstream of the change was redone. |
Intent Revision as Configuration
How the same rules look in a workflow engine. Illustrative; the names map to whatever your engine calls states and events. The full engine design is on Building AIDLC Into an AI Engine.
States and events
# intent-revision.yaml - illustrative
events:
intent_change_requested:
raised_by: [agent, check, person]
requires: [evidence, intent_version, proposed_revision, dependents]
effect:
move_dependents_to: intent_review # only work that depends on it
intent_change_decided:
decided_by:
brief: product_owner
spec_or_design: tech_lead
outcomes: [clarification, scope_change, design_change,
direction_change, rejected]
effect:
bump_version: true # except clarification and rejected
mark_stale: artifacts_built_against_previous_version_and_touched
resume_from: earliest_affected_state
rules:
agent_can_decide_intent_change: false
build_against_stale_intent: falseThe intent change request
{
"kind": "intent_change_request",
"work_item": "BILL-413",
"intent": { "artifact": "brief", "version": 2 },
"found_by": "agent:coding-agent",
"evidence": "billing-service stores credit notes as invoices with a negative total",
"question": "Include credit notes in the export, and how are they marked?",
"proposed_revision": "Add AC-4: credit notes appear with type = credit_note",
"proposed_class": "scope_change",
"dependents": ["plan:BILL-413:v1", "test:export-totals", "test:export-rows"],
"decision": null
}Waiting and Failing Safely
People take days; the workflow waits
An intent decision or a Tier 3 review can take days. The work item sits in a waiting state with a named owner and a reminder, not in an agent session burning budget. If no one answers within the agreed window, the workflow escalates to the owner's lead rather than guessing.
A crash loses one step, not the work
If an agent or the engine dies mid-step, the workflow resumes from the last recorded step. Steps carry idempotency keys, so a retry updates the pull request it already opened instead of opening another.
Model changes do not change the work
Because the intent and artifacts live in the workflow, a pinned model can be upgraded, after its evals pass, without re-explaining anything. The new model reads the same records the old one wrote.
Two repair attempts, then a person
A step that keeps failing its gate stops after two repair attempts and becomes a visible escalation, never a silent loop. See the agent hard rules.
Six Durable Patterns
The engineering patterns behind the properties above. They are long established in distributed systems; agents make them necessary for everyday software delivery.
Checkpoint every step
Record the result of each step before starting the next, so a restart begins after the last checkpoint instead of at the beginning.
Idempotency keys
Give each side effect - a pull request, a ticket update, a message - a key, so repeating the step updates what exists instead of creating a duplicate.
Compensation
When a later step fails or the intent changes, undo earlier steps deliberately: close the stale pull request, turn off the flag, revert the merge.
Timers and escalation
Every wait has a deadline and an escalation path, so a forgotten approval becomes a reminder and then a lead's decision, never a silent stall.
An event history
Keep the sequence of events, not just the latest state, so anyone can replay how an item reached where it is and why.
Versioned workflow definitions
When you change the workflow itself, items already in flight finish on the version they started with; new items take the new one.
Signs the Work Lives in the Agent
Each of these is a small symptom of the same design flaw. Two or more means the team is depending on agent memory for things that should be records.
- Starting a new session means pasting a long summary of "where we were".
- Nobody can say which version of the requirements a pull request implements.
- Approvals happen as replies in a chat thread.
- A model upgrade changed how in-flight work was being done.
- An agent changed the scope because it "learned" something, and no one decided it.
- A retried step opened a second pull request.
- Work waiting on a person shows up as an idle, still-running agent.
- Explaining an incident requires reading agent transcripts.
Frequently Asked Questions
Because agent sessions are temporary. They end, crash, run out of context or get replaced by a different model, and anything that lived only in the session goes with them. A durable workflow keeps the intent, artifacts, approvals and state in a store that outlasts every agent, so any agent or person can pick up exactly where the last one stopped.
An agent may discover that the intent needs to change, but never decide it. The affected work pauses, the agent files an intent change request with its evidence and the dependent artifacts, and the owner of that decision approves, rejects or splits it. The intent gets a new version, artifacts built on the old version that the change touches are marked stale, and work resumes from the earliest affected step rather than from the start.
No. The properties matter more than the product: persisted state, versioned intent and artifacts, idempotent steps, human waits as real states, explicit transitions and a complete history. A tracker with required fields, a database table of states and a CI pipeline can provide them; a durable execution engine makes long waits, retries and resumption easier at scale.
Keep the Work Where It Survives
Put the intent in a versioned record, the state in the workflow and the decisions with people. Then let agents be the fast, replaceable workers they are.