Documentation

Building Your First Workflow

From zero to a repeatable agent workflow that ships value.

A workflow is a multi-step task you've made repeatable: the steps, quality gates, and output format live in a file instead of your head. Run it today, run it next month — same quality.

We'll build a real one: "Take a bug report and turn it into a fixed, tested, reviewed change." It works in Claude Code, Codex CLI, Gemini CLI, or any runner that reads markdown.

Step 1 — Prerequisites

A project with an AGENTS.md (see Getting Started) and two skills from the Skills directory:

Download each as JSON from its page, or copy the prompt into files under skills/.

Step 2 — Write the workflow file

Create workflows/bug-to-fix.md:

# Workflow: Bug → Fixed, tested, reviewed change

Input: a bug report (issue link, error message, or description).

## Phase 1 — Reproduce & diagnose
1. Reproduce the bug. If you cannot, stop and report what you tried.
2. Apply the debug-analyzer skill: hypotheses → smallest experiments → root cause.
3. Write the root cause to scratch/bug-analysis.md before touching any fix.

## Phase 2 — Fix
4. Make the smallest change that fixes the root cause (not the symptom).
5. Add a test that fails without the fix and passes with it.

## Phase 3 — Verify & review
6. Run the full test suite and lint (commands in AGENTS.md).
7. Apply the advanced-code-reviewer skill to your own diff.
8. Fix anything Critical or Important from the review.

## Output
- The diff
- scratch/bug-analysis.md (root cause)
- Test results
- One-paragraph summary: cause, fix, how it's prevented from regressing

Step 3 — Run it

Follow workflows/bug-to-fix.md for this bug:
"Date picker shows wrong month when timezone is west of UTC, see issue #142"

Watch for the two failure modes: skipping Phase 1 (jumping straight to a fix) and skipping step 7 (no self-review). If the agent skips a phase, that's a workflow-file problem — make the gate more explicit ("Do not proceed to Phase 2 until scratch/bug-analysis.md exists").

Step 4 — Improve it after every run

This is the actual secret. After each run, ask: where did quality leak?

  • Agent guessed instead of reproducing → strengthen Phase 1 wording
  • Fix was too broad → add "list every file you intend to touch and why, before editing"
  • Tests were weak → reference the test-writer skill in Phase 2

Each fix compounds. After five runs you'll have a workflow that reliably outperforms ad-hoc prompting — that's the loop: run → observe the leak → patch the file.

Patterns worth stealing for any workflow

  • Phase gates — "do not proceed until X exists" prevents the agent from rushing
  • Scratch files — externalized reasoning survives context loss and enables review (scratchpad discipline)
  • Self-review as a step — the self-critique loop is the single cheapest quality win
  • Defined output — a fixed deliverable list makes runs comparable

Next: split these phases across specialized agents with Multi-Agent Patterns.

← AGENTS.md Best PracticesMulti-Agent Patterns →