Workflow specification writer

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 goes in and out

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)
• Codebase (optional)

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

How the task works

• Find the facts. If you share code, it reads the routes, workers, schema and config for the workflow. It notes where the code differs from your description.
• List the actors. It names every system and person in the workflow, and what each one does.
• Map the happy path. It writes the steps from trigger to finished, with the data passed at each handoff.
• Branch every step. For each step it adds the time limit and every failure, with retry or stop rules and what was already created.
• Show what each party sees. It states what the customer, the operator, the database and the logs show at each step.
• Close out. It adds the cleanup list, the test cases, the assumptions and the open questions, and marks the spec Draft.

Full instructions

• Add the pack as a skill, or paste SKILL.md and then references/source-agent.md into a new chat.
• Name one workflow and say what starts it. Paste or upload any code, routes or notes. Say who the actors are.
• Run it once for one workflow. If the AI spots a related workflow, it will name it and leave it for the next run.
• Read the assumptions and open questions first. Answer them, or send them to the engineer who knows.
• 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.
• 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.

Change the instructions

• Scope. Name one workflow and its trigger. Ask for a registry of all workflows only when you want a system-wide map.
• Detail. Say if you want a short spec for a small feature or the full tree for something that touches money or data.

Improve the result

• After each real failure, paste what happened and ask the AI to add the missing branch.
• Rerun the spec after big code changes and ask it to list where the code no longer matches.

Words used in this task

• Workflow spec: A written list of every step, branch and failure path a system must follow.
• Handoff contract: The agreed data and replies when one system passes work to another.
• Cleanup path: The steps that undo partial work when a workflow fails midway.
• Idempotent: Safe to run twice, because the second run has no extra effect.

Full instruction file

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. Read it if you can. This file is enough to run the job on its own.

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.

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.

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. It takes the document.
• The Recurring task procedure writer. It takes the document.
• The 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.

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, 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.