PRACTICE / AGENT LAB

Using an Agent Graph for Software Development Tasks

Using an Agent Graph for Software Development Tasks
Illustrative cover for an article about staged agent execution and durable proof.

Advanced · 20 minutes · 11 November 2026

A coding session can produce a useful patch and still leave a weak trail of evidence. An agent graph turns the task into explicit stages with durable artifacts, checkable transitions, and an independent review step. The result can be resumed after a timeout or context loss without relying on one session’s memory.

The problem: a finished message is not a verified result

A single software agent can inspect a repository, edit files, run commands, and report that the work is complete. That workflow is fast, but its control surface is small. The same session may decide what the requirement means, choose the implementation, run a partial check, and judge its own output.

Several failure modes follow:

  • The task is interrupted after code changes but before verification.
  • The agent remembers an assumption that was never written down.
  • A successful test result belongs to an older version of the working tree.
  • The final response says “done” without preserving the exact commands or scope.
  • A restart begins from a summary instead of from a durable, inspectable state.

The practical answer is to separate execution into stages and make each stage publish an artifact. A later stage should consume those artifacts, not an informal transcript. This does not make an agent infallible. It makes the work auditable enough to detect missing evidence and safe enough to resume deliberately.

What an agent graph adds

An execution graph represents a task as nodes and permitted edges. A node has an input contract, performs a bounded action, and writes an output contract. An edge is allowed only when a predicate over the recorded state is true.

intake
  │
  ▼
spec ──► plan ──► implement ──► verify ──► review ──► done
  │                                      │
  └────────────── retry / blocked ◄──────┘
This is a reference topology, not a claim that every project needs exactly these six nodes.

The graph provides four properties that a long conversational session does not provide by itself:

  1. Separation of concerns. Requirements, implementation, verification, and review are different responsibilities.
  2. Durability. Each meaningful result is stored as a file or another versioned artifact.
  3. Resumption. The next action is derived from persisted state and current repository facts.
  4. Accountability. A transition can be rejected when its evidence is absent, stale, or incomplete.

A concrete case: adding a repository health check

Consider a small development task: add a command that reports whether a repository contains the expected configuration files and whether the configuration parses successfully.

The task sounds simple, but it contains several separate questions:

  • Which files are required?
  • What does “valid” mean: existence, syntax, schema, or runtime behavior?
  • Should missing optional files fail the command?
  • Which test command demonstrates the acceptance criteria?
  • Can a reviewer distinguish a new result from a stale test log?

An agent graph makes those questions explicit. The intake node records the request. The specification node defines the acceptance criteria. The planner identifies the command and test files. The implementation node changes the code. The verification node runs the declared checks. The review node compares the diff and evidence against the specification.

The graph does not require six different models or six separate machines. The stages may run in one process, but their inputs and outputs should still be isolated. Independence is a property of the evidence path, not a claim about how many model instances were used.

Define the durable state before writing code

Start with a state directory inside the working project or in an external store associated with the task. The following layout is an example:

.agent/
├── state.json
├── intake.md
├── spec.md
├── plan.md
├── implementation.md
├── verification.md
├── review.md
└── attempts/
    ├── 001/
    │   ├── files-before.txt
    │   ├── commands.log
    │   └── files-after.txt
    └── 002/

The names are not important. The ownership and meaning are. Each file should answer four questions:

  1. Which task and attempt does this artifact belong to?
  2. What inputs were observed?
  3. What action produced the result?
  4. What decision does the result permit?

A useful verification artifact can be short. It should contain the exact command, the relevant working-tree identity, the exit code, a concise result, and any limitation. A summary such as “tests passed” is weaker than:

task_id: repo-health-001
attempt: 1
commit_before: <recorded commit or "uncommitted">
command: npm test -- --runInBand
exit_code: 0
scope: repository health check unit tests
result: pass
limitations: integration tests not run

The placeholder commit value above is intentionally not a real result. A production implementation should write the actual value observed at runtime.

Model state transitions as predicates

A stage completion event is not automatically a valid transition. The state transition should be computed from facts that can be read again.

{
  "task_id": "repo-health-001",
  "stage": "verify",
  "attempt": 1,
  "artifacts": {
    "spec": ".agent/spec.md",
    "plan": ".agent/plan.md",
    "implementation": ".agent/implementation.md",
    "verification": ".agent/verification.md"
  },
  "transition": {
    "from": "verify",
    "to": "review",
    "requires": [
      "verification.exists",
      "verification.exit_code == 0",
      "verification.matches_current_tree",
      "verification.scope_complete == true"
    ]
  }
}

This JSON is an illustrative configuration fragment, not a measured system output. In an implementation, the orchestrator should reject the transition when a required field is missing, has an ambiguous value, or refers to an older tree.

Typical transition rules look like this:

  • intake → spec: goal, constraints, repository scope, and acceptance criteria are present.
  • spec → plan: every requirement has a proposed verification method.
  • plan → implement: the plan identifies change boundaries, risks, and forbidden scope.
  • implement → verify: a diff exists and the implementation report lists changed paths.
  • verify → review: required checks have recorded outcomes and match the current tree.
  • review → done: the reviewer found no blocking issue and cited the acceptance criteria.

Reproducible command sequence

The following commands show a conservative local workflow. They are examples for a Git repository; they do not claim to have been run for this article.

# Inspect the starting point
pwd
git status --short
git rev-parse HEAD

# Create an attempt directory
mkdir -p .agent/attempts/001

# Record the starting file inventory
git ls-files > .agent/attempts/001/files-before.txt

# After implementation, inspect the change
git diff --stat
git diff --check
git status --short

# Run the project-specific checks declared in the specification
npm test -- --runInBand

# Record the ending inventory
git ls-files > .agent/attempts/001/files-after.txt

git diff --check can reveal whitespace errors. git status --short can reveal changed or untracked paths. Neither command proves that the feature is correct. The project’s own tests, type checks, linters, integration checks, or manual acceptance steps must define the actual verification scope.

Do not place secrets in these artifacts. Redact tokens, private URLs, credentials, personal data, and sensitive command arguments before storing logs or sharing them with a reviewer.

How resumption works after interruption

When a worker restarts, it should not ask, “What did the previous conversation intend?” It should evaluate the persisted task state against the current repository.

load state.json
load the latest attempt
verify referenced artifacts exist

if stage == "implement":
    if implementation.md exists and the diff is present:
        enter verify
    else:
        resume implement

if stage == "verify":
    if verification.md is current and complete:
        enter review
    else:
        rerun verification

if stage == "review":
    if review.md is missing:
        run review
    else if review is stale:
        invalidate review and return to verify

This pseudocode is a design example. A real orchestrator needs explicit handling for malformed JSON, missing files, concurrent workers, abandoned attempts, and changes made outside the agent.

Resumption also requires idempotency for repeatable operations. Reading files and rerunning tests are usually safe to repeat. Sending a release notification, opening a ticket, applying a migration, or publishing a package may not be. External side effects need a durable operation identifier, an explicit status, and a rule for determining whether the action already happened.

Independent review without hidden context

The reviewer should receive the smallest complete evidence bundle:

  1. the original intake and specification;
  2. the approved plan;
  3. the current diff or changed-file set;
  4. the verification artifact and relevant logs;
  5. the acceptance and transition rules.

The reviewer should not need the full conversation. This is a useful constraint: a reviewer who can only approve after hearing the author’s explanation is reviewing a narrative, not a reproducible result.

A compact review artifact can use a controlled status vocabulary:

# Review

status: pass | retry | blocked

## Findings
- severity: blocker | major | minor
- requirement: R-001
- evidence: .agent/verification.md
- finding: <concise observation>

## Decision
- accepted_requirements: R-001, R-002
- missing_evidence: none
- next_action: done

The reviewer is independent when the approval decision is based on the published artifacts and current repository facts, not on an unrecorded assurance from the implementation agent. A different model can help, but model diversity alone is not independence if both agents receive the same unverified conclusion and no checkable evidence.

Failure cases the graph should make visible

Missing evidence

If verification.md does not exist, the graph should stop at verification. It should not infer success from an assistant message or from a green-looking log fragment.

Stale evidence

If the working tree changed after the test ran, the earlier result should be marked stale. Re-run the relevant checks or explicitly record why the change is outside their scope.

Partial completion

If implementation changed three files and the report lists only two, the transition should fail. The purpose of a proof file is to make omissions detectable.

Contradictory artifacts

If the specification requires an integration test but the verification file says “unit tests only,” the result is not a pass. The graph should route the task to retry or blocked rather than asking the reviewer to silently reinterpret the requirement.

Concurrent writes

Two workers can overwrite state or produce incompatible patches. Use an attempt identifier, compare the observed base revision, and reject writes that no longer match the expected state. A graph does not remove the need for locking or conflict resolution.

External side effects

A retry can duplicate an email, deployment, migration, or ticket update. Separate pure verification from side-effecting actions and give every side effect its own durable confirmation.

Verification checklist for the orchestrator itself

Before trusting an agent graph, test the control logic with deliberately incomplete scenarios. The following checklist is a test design, not a report of completed results.

  • Delete one required artifact and confirm that the next transition is rejected.
  • Change a file after a successful verification and confirm that the proof becomes stale.
  • Write an invalid status value and confirm that the state loader fails closed.
  • Resume from each stage with the worker process stopped between actions.
  • Run the same verification stage twice and compare the recorded scope.
  • Create two attempts and confirm that a later attempt cannot consume an earlier attempt’s proof accidentally.
  • Simulate a reviewer finding and confirm that the graph routes to retry or blocked.
  • Simulate a non-idempotent external action and confirm that the retry policy requires an operation identifier.

For each scenario, record the initial state, injected failure, expected transition, observed transition, and any discrepancy. A control system is only as trustworthy as its failure behavior.

Limitations and design trade-offs

An agent graph adds files, schemas, transition logic, and maintenance work. For a one-file change with a clear test command, the overhead may outweigh the benefit. The approach becomes more useful when a task is long-running, expensive, safety-sensitive, parallelized, or likely to be resumed by another worker.

Durable artifacts also do not guarantee truthful artifacts. A worker can record a misleading summary, omit a command, or run a check against the wrong directory. Mitigations include machine-generated fields, immutable logs, repository identity checks, least-privilege tools, and a reviewer that can rerun critical checks.

Independent review reduces self-confirmation risk, but it does not prove semantic correctness. Tests can be incomplete, acceptance criteria can be wrong, and a reviewer can miss a defect. Keep the article’s boundary clear: the graph improves evidence and control flow; it does not turn uncertain software work into a formal proof.

A practical starting contract

If you are introducing this pattern into an existing project, begin with one narrow contract:

  1. Every task has a stable identifier.
  2. Every stage writes one named artifact.
  3. Every verification artifact records exact commands and exit codes.
  4. Every transition checks artifact existence and freshness.
  5. Review is a separate decision with a controlled status.
  6. Unknown, missing, or contradictory state blocks completion.

Once that contract works, add retries, parallel branches, human approval, external action receipts, and richer observability. The durable state model should come first. More agents do not compensate for an unclear transition contract.

Conclusion

Using an Agent Graph for Software Development Tasks is a way to move from conversational completion to inspectable execution. The central design decision is simple: make the task’s state and evidence durable, then let the orchestrator derive the next step from those records.

Separate intake, specification, planning, implementation, verification, and review. Store proof files with task and attempt identifiers. Reject stale or incomplete evidence. Resume from persisted state rather than from a session summary. Treat side effects as separate, idempotent operations. These measures do not eliminate failure, but they make failure visible, recovery deliberate, and completion independently reviewable.

Browse practical guides · Open the glossary

We publish what works for us—and implement the same solutions for your business. We design AI automation, Telegram bots, chats, and AI agents for real-world processes. Discuss your project →