Engineering principles
The short rules Minion is built by, and what each one means for the packages you write.
Minion runs packages, jobs, webhooks and apps for every agent you connect. These are the rules we hold ourselves to while building it. Each page is one rule, one real example from Minion, and what it means when you write a package of your own.
You don't need to read them in order. Open the one that matches what you're doing.
The principles
- Generic platform : you want a provider-specific branch, or a type named after a vendor.
- One source of truth : you're about to add a cache, an index or a second copy of a fact.
- Delete what is off the common path : you're keeping an option, flag or field nobody uses.
- Finish the migration : a new way shipped and the old way is still running beside it.
- Fail loudly at the right layer : an error could be swallowed so a partial result carries on.
- Fix the root bottleneck : something is slow and a longer timeout looks tempting.
- Two-way and one-way doors : you're deciding how careful a change needs to be.
- Examples over prose : you're writing a guide, a skill or a multi-step procedure.
- Keep agent context lean : you're writing instructions an agent will load.
- No test-only code in production : you want a switch that only tests flip.
- Test the workflow : you're adding or reshaping tests.
Why write them down
Agents do a lot of Minion's building and a lot of its use. An agent copies whatever it finds nearby, good or bad. A rule with a working example beside it gets copied correctly. That's also why every page is short.