Document deterministic workflows, step contracts, and org-defined artifact kinds

[pdtnelson]

Summary

Updates the customer-facing docs for the ENG-2193 merge train (deterministic workflow
execution, agent frontmatter contracts, and org-defined artifact kinds) — filed as
ENG-2210 ("[docs] Update customer-facing docs for deterministic workflows, step
contracts, and org-defined kinds").

The prior docs described an LLM workflow-runner that executed steps strictly in
sequence, composed each step's briefing from the workflow's description, and had no
authoring surface for step contracts or customer-defined artifact kinds. All three are
gone or changed with the ENG-2193 train, which is now fully merged to main in all four
repos it touches (agent-core #93, sandbox-agent-server #77, cloud-agent-service #160,
console-web #124).

What changed

• agents/writing-an-agent.mdx — new frontmatter surface: produces (a may, never
  a must), consumes (mode: each|all, the group-by vocabulary using
  patch-generator's real shipped frontmatter as the example), mutates-worktree, and
  inline kind registration with the exact-match evolution rule. Removed sequential-spawns
  (deleted outright, never customer-facing to begin with — no migration note).
• workflows/agent-chain.mdx, workflows/overview.mdx, workflows/create-a-workflow.mdx,
  quickstart.mdx — corrected the "steps run strictly in sequence" and
  "the workflow description shapes every step's briefing" claims against the shipped
  step driver: steps run once their actual dependencies settle, independent steps can
  run concurrently, and the description is documentation shown to your team, not an
  instruction.
• workflows/running.mdx — added the Skipped step status, its reason string, and
  the invocation-count badge for fan-out steps.
• workflows/artifacts.mdx — org-defined artifact kinds are documented as real
  (previously described as "where this is heading, not a set of features to build
  against right now").
• agents/library.mdx — removed the workflow-runner section; excluded
  code-reviewer and security-analyzer from the documented fleet (no durable output /
  already designated for retirement, respectively — not real functions for a customer to
  rely on); repositioned patch-generator as its own chainable step with a migration
  note for the removed generatePatches flag.
• agents/tool-reference.mdx — documented emit_artifact, list_artifacts,
  get_artifact (previously undocumented, despite being the entire mechanism behind
  org-defined kinds).
• agents/how-agents-work.mdx, agents/overview.mdx — removed remaining
  orchestrator-as-LLM-decision-maker language.

Verification

Every behavioral claim was checked against the actual merged code (agent-core's
schemas.ts, cloud-agent-service's kind-policy.ts/canonical-form.ts, sandbox-agent-server's
step-driver.ts, console-web's step-row rendering diff) rather than the planning docs'
language. One correction that came out of that: a workflow's description still rides
along as context on every step's composed task — it wasn't removed outright, just no
longer used to compose custom per-step instructions. The docs say that precisely.

A dedicated review pass confirmed no page names an internal service, storage shape,
internal API/event, or mechanism — every behavior is stated as the user-observable
contract.

Full inventory, fleet-audit reasoning, and open items are tracked on the ENG-2210 ticket.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
amplifysecurity	🟢 Ready	View Preview	Sep 4, 2026, 4:46 PM

💡 Tip: Enable Automations to automatically generate PRs for you.