vibecodebots
An open operating manual for building software with AI bots in named roles. An orchestrator coordinates the work. A human Owner approves what matters.
Draft Version 0.5. Untested in practice. The Phase 0 trial has not been run yet.
The repository. How to run it.
- Orchestrator
- Project manager
- Developer
- Tester
- Safety
What it is
It is a project-agnostic operating manual and starter kit. You describe the product in a brief. The framework supplies named job roles, an orchestrator, a project manager that critiques the work, approval tiers, decision records, work quotes, and templates.
It is not software. There is no runtime in the repository. You run it with whatever agent tool you already use. It is not a guarantee of quality.
Honest limits
A persona is a prompt, not a qualification. A bot told it is a security engineer does not become one. It becomes a model that is more likely to apply the rules it is given.
Same-model reviewers share blind spots. In a small setup several personas share one bot, so reviews are not fully independent. The Owner's approval is the real check early on.
Why it is different
These are design aims. The Phase 0 trial that would test them has not been run yet. They are not proven results.
Second player
The builder does not mark its own work. A self-check is required and never counts as a review. For riskier work, class R2 and above, at least one reviewer runs on a different model family from the author. The manual cites research on self-enhancement bias, where a model rates its own style of output more highly (Zheng and others, NeurIPS 2023; Panickssery, Bowman and Feng, NeurIPS 2024), and research that models often fail to fix their own reasoning without external feedback (Huang and others, ICLR 2024).
Pay first
Before work above the trivial tier starts, the project manager issues costed options: local only, commercial only, a blend, or a mix the user defines. The orchestrator checks the credit ledger. The person commissioning the work chooses, and that choice is written down.
Risk picks the boss
Tiers decide who may approve. Everyday changes can merge after the project manager and one peer, and the Owner can still revert them. Risky work, and every release, waits for the human Owner.
Save and rewind
Every decision is logged. An unrecorded decision is invalid. Changes are meant to record who made them, when, why, and the diff, and a bad merge can be reverted.
Boss gate
Before a release or a publication, the orchestrator shows three checks, in this order. First the unreviewed-change gate. Then a release risk assessment, shown to the Owner. Then recommended reviews. The building bot's own check never counts as a review.
Show the evidence
Domain safety cannot be handed to bots. Bots screen. Humans decide. "Done" means the definition of done is met and evidenced, not merely said. Legal, licence and safety checks ask for the link or the test.
Party of seven
The catalogue is large. Phase 0 starts with seven bots. The other roles stay dormant until a named trigger, and the Owner approves waking them.
Open cartridge
The manual is not tied to one product. Documents and templates are CC BY 4.0. Scripts are Apache-2.0.
How it works
Every task passes the same stages. The orchestrator records the stage.
- Intake
- Quote and choose
- Persona assignment
- Model routing
- Work
- Self-check
- Peer or dual review
- Project manager critique
- Score
- Artefacts
- Merge by approval tier, then release
The Phase 0 roster is seven bots: Orchestrator, Project Manager, Product Owner, Architect, Developer, Tester, and Safety and Compliance. No bot reviews its own work.
Before notes, tags or publishing, the orchestrator runs the release gates and tells the Owner the result directly. The order is fixed: the unreviewed-change result, then the risk assessment, then the recommended reviews.
Licence and status
Documentation and templates are Creative Commons Attribution 4.0. Scripts are Apache License 2.0. The code of conduct is under CC BY-SA 4.0, as that text requires.
Status in the repository: version 0.5 draft, untested in practice. The Phase 0 trial described in the manual has not been run yet.