Artifact Chaining

The problem: agents are stateless

Each agent invocation starts with a blank slate. No shared memory, no session state. No database the agent automatically consults. So how does the Build agent know what the Plan agent decided? How does the Review agent know what tests passed?

Without artifact chaining, you would need to manually copy-paste outputs between phases. Or worse, each phase would independently analyze the codebase from scratch, producing inconsistent interpretations of the same task. The workflow would be a set of disconnected prompts, not a coherent workflow.

Think of a relay race. Each runner starts where the previous one stopped, but only if the baton is passed. The baton is the artifact. Without it, the next runner does not know when to start or which direction to go.

The solution: artifacts and template variables

Each phase produces a structured output called an artifact. The next phase's prompt template contains variables like ${plan_artifact} that get replaced with the prior phase's output before the prompt reaches the agent.

The workflow engine handles the substitution. The developer designs the templates with the right variable slots. Clean separation: the developer defines what context each phase needs, the engine delivers it.

# Build template -- consumes the plan artifact
## The Plan
${plan_artifact}

## Your Task
Implement ONLY what the plan specifies.
Write tests FIRST, then implementation.
Reference specific file:line for all changes.

When the workflow engine encounters ${plan_artifact}, it replaces it with the actual plan output from the Plan phase. The Build agent sees the complete plan as if it had been written directly into its prompt.

The full artifact chain

Every phase consumes artifacts from prior phases and produces its own. Some phases receive just one artifact; others receive several for cross-referencing. Here is the complete chain:

The state object

The workflow engine maintains a manifest that tracks the current phase, which artifacts exist, pass/fail status, loop iteration counts, and timestamps. This is the single source of truth for workflow progress.

// Workflow state object
{
  "workflow_id": "feat-auth-2026-03-10",
  "current_phase": "review",
  "artifacts": {
    "plan":   { "status": "complete", "format": "markdown" },
    "build":  { "status": "complete", "format": "markdown" },
    "test":   { "status": "complete", "format": "json" },
    "review": { "status": "in_progress" }
  },
  "loops": {
    "test_retry":   { "iteration": 2, "max": 3 },
    "review_patch": { "iteration": 0, "max": 3 }
  }
}

Artifact formats

Not all artifacts are the same shape. The format depends on what the next consumer needs:

## Plan Summary
Add token refresh to auth module.
## Files to Modify
- src/auth/tokens.py:112-130
- src/auth/session.py:55
## Out of Scope
- Session persistence changes

{
  "summary": { "total": 14, "passed": 12 },
  "failures": [
    {
      "test": "test_token_refresh",
      "file": "tests/auth:45",
      "expected": "200 OK",
      "actual": "401 Unauthorized"
    }
  ]
}

The rule: if the next consumer is an agent that needs to iterate over items (test failures, review issues), use JSON. If the next consumer needs narrative context (understanding a plan), use Markdown.

Designing good artifacts

Related concepts