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.

  1. Intake
  2. Quote and choose
  3. Persona assignment
  4. Model routing
  5. Work
  6. Self-check
  7. Peer or dual review
  8. Project manager critique
  9. Score
  10. Artefacts
  11. 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.

https://github.com/jonmarson-cmd/vibecodebots