Custom steps
A [step](../glossary.md#step) is a program. Kusaw sends it a request, it reports progress, and it ends with a result. Every step, built-in or [custom](../glossary.md#custom-command-step), speaks the same [step protocol](../glossary.md#step-protocol). The [built-in steps](../glossary.md#built-in-step) are defaults you can replace.
A step is a program. Kusaw sends it a request, it reports progress, and it ends with a result. Every step, built-in or custom, speaks the same step protocol. The built-in steps are defaults you can replace.
When to write a step
Write a custom step when you have something of your own to run:
- a check you already run
- a tool you trust
- your own agent prompt
- a different review
A config change is enough when you only need to adjust a default: its timeout, retries, fail_on, verification commands, or which MCP servers and skills it may use. You do not need a custom step to rename a timeout.
Built-in steps are defaults
builtin: <name> and command: [...] start the same way. Kusaw handshakes the program, sends the request, and reads progress and a result. Replacing the default review step, or the default build step, does not change gates, loops, or feedback as long as you keep the same step id.
In this section
- Write your first step — handshake, request, progress, result, and a Python 3 worked example
- Replace a built-in step — point a pipeline entry at your command and keep the same id
- Use an agent inside your step — print or run the built-in provider argv with
kusaw agent-args - More examples — the Python worked example, a checklist review, and the Go example
- Example pipelines — four complete pipeline shapes (loop, reviewer, planner) that call
kusaw agent-args
Benchmarks
Benchmarks replay a captured task against baseline and variant overlays. A replay is correct when the clean-checkout regrade is pass (`grade_clean`). The in-place grade (`grade_in_place`) is recorded next to it. `kusaw bench run` queues those replays (default `--repeat 3`). `kusaw bench report --tasks a,b --variants baseline,cheap` reads reliability from the latest batches. `kusaw bench report <batch> --markdown` writes the comparison table for you to keep.
Write your first step
This page is a Python 3 worked example that uses only the standard library. Copy `examples/custom-steps/todo-check/` or type the excerpts as you go. The code on this page is that example. A [Go example](examples.md) that speaks the same protocol is linked from More examples.