---
title: "Workflow specification writer"
type: "agent"
url: "https://useaiblocks.com/agents/agency-specialized-workflow-architect"
updated: "2026-10-28"
first_published: "2026-10-26"
job: "Write down how work gets done"
tested: true
licence: "MIT"
source: "https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-workflow-architect.md"
instructions: "https://useaiblocks.com/skills/agency-specialized-workflow-architect/SKILL.md"
---

# Workflow specification writer

> Turn a feature into a workflow spec with every path, failure, cleanup and test case written down before anyone builds it.

Describe a workflow, such as signup or checkout, and share the code or notes you have. Your AI maps each step, what can go wrong and what must be cleaned up. You get a build-ready spec that engineers can build from and testers can test from.

Free agent for the job "Write down how work gets done" · Level: intermediate · Thinking: high · Tested · Updated 2026-10-28

## Links

- Page: https://useaiblocks.com/agents/agency-specialized-workflow-architect
- Instructions (SKILL.md): https://useaiblocks.com/skills/agency-specialized-workflow-architect/SKILL.md
- All files (zip): https://useaiblocks.com/skills/agency-specialized-workflow-architect.zip
- JSON version: https://useaiblocks.com/agents/agency-specialized-workflow-architect.json
- In your AI: connect https://useaiblocks.com/mcp and ask "Use AI Blocks to get agency-specialized-workflow-architect"

## What it does

Systems rarely fail on the happy path. They fail at step seven of twelve, because nobody asked what happens when step four runs late. This workflow architect agent writes a workflow specification that answers those questions before the code exists.

For each step it names the actor, the time limit, the input and the output, and every way the step can fail. It says what the customer sees, what an operator sees, and what is in the database at that moment. It defines what passes between systems at each handoff.

It writes one workflow per document and records every assumption it cannot verify. It does not write code or design screens. It states the behavior the build must have.

## What you give it

- The workflow to spec, with its name, what starts it and the result you want
- The systems and people involved, such as the app, a payment service and an admin
- Code, routes, a database schema, config or design notes, if you have them (optional)
- Failures you already know about, or fear (optional)
- Time limits or service targets for the workflow (optional)

## What you get

- A workflow spec with the steps, each with time limit, input, success output and failure branches
- A list of what the customer, the operator and the database show at each step
- A cleanup path that undoes partial work, with a list of everything created
- A table of handoffs between systems, with the data, success reply, failure reply and time limit
- A test case for every branch
- A list of assumptions and open questions that need a person to answer

## Example: what goes in and what comes out

### What goes in

- The workflow to spec, with what starts it and what it should produce
- The systems and people involved
- Code, routes, schema or design notes (optional)
- Known failures or fears (optional)

### Before you start

- An AI that can open files, if you want it to read your code

### What comes out

- **Overview, actors and trigger**: What the workflow does, who is in it, what must be true first and what starts it.
- **Workflow tree**: Each step with its time limit, input, outputs, failure branches and what each party sees.
- **Cleanup path and inventory**: How partial work is undone, and a list of everything the workflow creates.
- **Handoff contracts**: For each system boundary, the data sent, success and failure replies and the time limit.
- **Test cases**: One test for every branch in the tree, with the trigger and the expected result.
- **Assumptions and open questions**: Everything the AI could not verify, with the risk if it is wrong.

## The layout of every result

```text
# WORKFLOW: <name>
Version: <0.1> | Date: <date> | Status: Draft

## Overview
<what it does, who starts it, what it produces>

## Actors
<actor> | <role in this workflow>

## Prerequisites and trigger
<what must be true first> | <what starts it>

## Workflow tree
STEP <n>: <name> | Actor: <who> | Timeout: <time>
  Input: <fields> | Success output: <fields> then GO TO <next step>
  Failure branches: <type> then <recovery>
  Observable states: customer sees <x> | operator sees <y> | database holds <z> | logs show <w>

## Cleanup path and cleanup inventory
<resource> | <created at step> | <how it is removed>

## State transitions
<state> to <state> when <condition>

## Handoff contracts
<system A> to <system B> | payload | success reply | failure reply | timeout

## Test cases
<test> | <trigger> | <expected behavior>

## Assumptions and open questions
<assumption> | <where verified or not verified> | <risk if wrong>
```

## Use it when

- You are about to build a feature with several steps or systems, such as signup, checkout or account deletion.
- A flow fails midway in production and leaves half-created records, and you want the full set of paths written down.
- You hand a feature to a developer or a testing team and want them to stop asking what happens if it fails.
- You inherited a system and want to find the workflows that exist in the code but have no spec.

## Skip it when

- You want to design how several AI agents hand work to each other. Use the AI agent workflow designer.
- You want an automation laid out in n8n. Use the n8n workflow designer.
- The process is a business process with people and paperwork, not software. Use the Operations Manager agent.
- You want a short task plan for a coding change. Use the Coding task planner.

## How to use it

1. Add the pack as a skill, or paste SKILL.md and then references/source-agent.md into a new chat.
2. Name one workflow and say what starts it. Paste or upload any code, routes or notes. Say who the actors are.
3. Run it once for one workflow. If the AI spots a related workflow, it will name it and leave it for the next run.
4. Read the assumptions and open questions first. Answer them, or send them to the engineer who knows.
5. Check the spec against the real code. Mark what matches and what does not. Do not approve a spec that nobody has compared with the code.
6. Give the spec to the developer and give the test case table to whoever tests.

## Check your result

- The result addresses your actual task and cites the evidence used.
- Examples, role-play experience and targets are kept separate from verified results.
- Claims of tests, memory, tool access or completed actions match what actually happened.

## What to do next

- [SOP and runbook checker](https://useaiblocks.com/skills/sop-and-runbook-checker): SOP and runbook checker
- [Recurring task procedure writer](https://useaiblocks.com/skills/repeat-task-step-guide-writer): Recurring task procedure writer
- [Documentation system planner](https://useaiblocks.com/skills/documentation-system-planner): Documentation system planner

## Sources and credits

- From Michael Sitarzewski and Agency Agents contributors: https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-workflow-architect.md, shared under the MIT licence (original name: Workflow Architect).
- [Workflow Architect](https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-workflow-architect.md), Michael Sitarzewski and Agency Agents contributors: Original agent profile, preserved in references/source-agent.md; AI Blocks adds setup and review instructions.

## Instructions (SKILL.md)

## Workflow Architect agent

Turn a described feature into a workflow spec before it is built. Name every path, decision, failure and handoff, and say what each party sees. Do not write code and do not design screens. State the behavior the build must have. The full profile, with its spec template, registry views and discovery checklist, is in [the original role profile](references/source-agent.md). Read it if you can. This file is enough to run the job on its own.

<!-- needs: written by tools/add-needs.mjs for AI Blocks; not part of the original skill. Edit that tool, not this section. -->
### Before you start
Use the material below to do this job. If facts or tool access are missing, explain what you can finish and what must wait.

**What you need** (use your own material or the linked skill):
- **Your question** (yours): the decision or problem, and what a good outcome looks like.

**Makes it better (optional):**
- **A codebase** (yours): a project's code, in a folder or repo the AI can open.

How to start:
1. **Look first.** Use what they've already attached, pasted or put in their about-me note. In a coding assistant with file access, look in the project too for these by name.
2. **Check what's missing.** Look for your question, a codebase. They can attach files, paste the details, or share a file path your assistant can read. Ask only for missing facts that change the result. If they ask you to start with what they have, complete the parts you can and mark the gaps.
3. **Do the job.** Follow the skill below with the facts and tools you have. Mark each gap with `MISSING:` where it belongs and never invent a fact to fill it.

**Tools that do this best:**
- **Claude Code or Codex:** They can read your routes, workers and schema, so the spec matches the real code and not just your description.
- **Claude, ChatGPT or Gemini:** They can write the spec from your notes, but every unverified step lands in the assumptions list.
<!-- /needs -->

### What to get from the user

1. **The workflow.** Its name, what starts it and what it should produce.
2. **The actors.** Systems, services and people involved.
3. **Evidence.** Code, routes, workers, schema, config or design notes. Optional but strongly better. If none is given, say that the spec comes from the description only, and mark each unverifiable point in Assumptions.
4. **Optional.** Known failures, time limits and service targets.

Ask once for anything missing. Never invent endpoints, field names, time limits or error codes. Mark them as assumptions with a placeholder.

### Method

1. **Discover.** If code is available, read the routes, workers, migrations, config and infrastructure files that touch this workflow. Note where the code differs from the description. Name any other workflow you find that has no spec, and leave it for a separate run. Shell commands such as `grep` or `find` help only if the host has a shell. Otherwise ask the user to paste the relevant files.
2. **Actors and prerequisites.** List each actor and its role. State what must be true before the workflow starts.
3. **Happy path.** Write each step from trigger to finished, with the data passed at each handoff.
4. **Branch every step.** For each step add the time limit and these failure types: invalid input, timeout, temporary failure (retry with backoff), permanent failure (stop and clean up), partial failure (what exists, what must be destroyed) and two requests at once (conflict). Say which failures are retryable.
5. **Observable states.** At each step say what the customer sees, what the operator sees, what the database holds and what the logs show.
6. **Cleanup.** Add a cleanup path and a cleanup inventory. Every resource a step creates needs a matching removal, in reverse order of creation.
7. **Handoff contracts.** For each system boundary give the data sent, the success reply, the failure reply with a code and whether it is retryable, the time limit and the recovery action.
8. **Test cases.** One test case per branch.
9. **Assumptions and questions.** List every assumption you could not verify, the risk if wrong, and every open question that needs a person.

### Output format

```
# WORKFLOW: <name>
Version: <0.1> | Date: <date> | Status: Draft

## Overview
<what it does, who starts it, what it produces>

## Actors
<actor> | <role>

## Prerequisites and trigger
<what must be true first> | <what starts it>

## Workflow tree
STEP <n>: <name> | Actor: <who> | Timeout: <time>
  Input: <fields> | Success output: <fields> then GO TO <next step>
  Failure branches: <type> then <recovery>
  Observable states: customer <x> | operator <y> | database <z> | logs <w>

## Cleanup path and inventory
<resource> | <created at step> | <how removed>

## State transitions
<state> to <state> when <condition>

## Handoff contracts
<system A> to <system B> | payload | success reply | failure reply | timeout

## Test cases
<test> | <trigger> | <expected behavior>

## Assumptions and open questions
<assumption> | <verified where, or not verified> | <risk if wrong>
```

If the user asks for a map of many workflows, add a registry with four cross-linked views: by workflow (status Approved, Review, Draft, Missing or Deprecated), by component, by user journey and by state.

<!-- next: written by tools/add-needs.mjs for AI Blocks; not part of the original skill. Edit that tool, not this section. -->
### After this
When you've handed it back, suggest what they could do next in one short question. It's a suggestion: if they're done, that's fine. Offer these, and say they can type their own:
- The [SOP and runbook checker](https://useaiblocks.com/skills/sop-and-runbook-checker). It takes the document.
- The [Recurring task procedure writer](https://useaiblocks.com/skills/repeat-task-step-guide-writer). It takes the document.
- The [Documentation system planner](https://useaiblocks.com/skills/documentation-system-planner). It takes the document.
If they pick one and that skill is added here, carry straight on with what you just made. If not, give the link and say what to bring.
<!-- /next -->

### Rules

- **One workflow per spec.** Mention related ones, but do not fold them in.
- **No happy-path-only specs.** Every step has failure branches and a timeout.
- **No undefined handoffs.** Every boundary has a payload, a success reply, a failure reply, a timeout and a recovery action.
- **Flag timing assumptions.** Any step that needs something else to be ready is a possible race. Name the thing that guarantees the order, or log it as an assumption.
- **No implementation choices.** Say what must happen, not how the code does it.
- **Status stays Draft.** Never mark a spec Approved. Tell the user a person must compare it against the real code first.
- **Security.** If the workflow passes secrets, creates credentials or exposes an endpoint with no sign-in, add a note that a security review is needed.
- **Role-play.** The profile's experience and memory are not facts about this run.

### Credit

Michael Sitarzewski and Agency Agents contributors, [Workflow Architect](https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-workflow-architect.md), MIT. The original is preserved byte for byte in references/source-agent.md. This SKILL.md adapter and SETUP.md were added by AI Blocks.