Give Initialization Its Own Phase
Make the agent figure out how to build and run the project while it's also doing the work, and every run starts in a slightly different, half-broken world. Setup deserves its own step.
A kitchen does its prep before the first order: stock made, stations set, knives sharp. Service is no time to discover you are out of onions. Initialization is mise en place for the agent: build the world and prove it is healthy once, up front, so the actual work never stops to fix the environment.
Why setup is not step zero
When environment setup is improvised inside the task, you get silent drift: a dependency that was installed last time but not this time, an env var that happened to be set, a service that was already running. The agent then spends real context diagnosing the environment instead of doing the work, and the results are not reproducible.
Pulling init into its own phase makes the starting world explicit and identical every run. "It worked on my machine" stops being a category of failure.
flowchart LR Start["Run starts"] --> Init["init.sh, build and check the env"] Init -->|exit non-zero| Fail["Run fails before any agent"] Init -->|exit 0| Work["Drive features against a proven world"] linkStyle 1 stroke:#e0493f,stroke-width:2.5px,color:#e0493f linkStyle 2 stroke:#2ea043,stroke-width:2.5px,color:#2ea043
A repeatable init script
Capture setup as a single command that builds the world from scratch: install dependencies, configure, migrate, and start whatever the agent runs against. It should be idempotent and fast to re-run.
# Environment smoke-test, run ONCE before any feature. # A non-zero exit aborts the whole run, the env is not ready. set -euo pipefail command -v git >/dev/null || { echo "FAIL: git"; exit 1; } command -v make >/dev/null || { echo "FAIL: make"; exit 1; } make setup && make check # prove the world is healthy echo "OK, environment is ready"
Keep it fast and cheap, and prove health before work starts: in Agentum a non-zero init.sh exit means no agent is ever spawned.
Init in the Agentum loop
The Harness Engine runs .agentum-harness/init.sh exactly once, before the first feature, the run sits in the init_verifying state while it executes. A non-zero exit moves the whole run to failed before a single agent is spawned, so a broken environment fails loud and early instead of corrupting feature after feature. Every feature that follows starts against the same proven world.
Key takeaways
- Folding setup into the task causes silent, non-reproducible drift.
- Make initialization a dedicated, idempotent phase that builds the world from scratch.
- End init with a health check that proves the environment before work starts.
- Agentum runs init ahead of the loop, so every task starts from a known-good world.
Exercises
- Write init.sh. Capture your project setup as one idempotent script that ends by proving the environment is healthy.
- Break it on purpose. Remove a dependency and confirm init fails loudly instead of mid-task.