Skip to content
bleeps & bloops

Add Bleeps to an existing project

You keep the repository, its history, and the checks you already run. Bleeps adds a develop branch, a short router, and the gates. These steps follow Using Bleeps and the primitives. Pattern files are in the Bleeps and Bloops repo.

Add the line to this repo

  1. Do this now

    Use the repository you administer

    You need admin on the GitHub repository so you can protect main and add labels. GitHub Issues stay the ticket source. Issues already in the tracker stay issues.

  2. Do this now

    Add develop beside the branch you ship

    Create develop from the branch you trust if the repository does not have it. Leave main named main. Agent pull requests target develop. You merge develop into main. The settled names are those two. A mapping for other branch names is not decided.

    Protect main so the owner is the person who can merge into it. Keep the protection you already have, and keep agents off main. GitHub auto-merge is still an open question. scripts/merge-pr does not turn it on. Required checks you already run stay. They are one gate. The verify verdict and the deployed SHA are gates of their own, and those checks are planned.

  3. Do this now

    Point AGENTS.md at Bleeps

    If the file is new, add the short router: Bleeps runs the crew, and links to the flow, the architecture, the decisions, the primitives, ship-pr, the friction log, and the control CLI. This repo's AGENTS.md is the pattern for the links. If you already have agent instructions, keep them and add those links. The shared behavior comes from orca.yaml.

  4. Do this now

    Add the recap to the pull request template

    If you have no template, copy this one. If you have one, add the recap and the risk tier and keep the rest. The class is composes, extends, or adds. high means a guardrail and waits for you.

  5. Do this now

    Add a friction label

    Create the friction label if you do not have it. Use it for papercuts in the friction log format. Leave the rest of the backlog on the labels it already has. Search open friction issues before you file a duplicate.

  6. Do this now

    Keep your checks, and name the guardrails

    Your tests stay your tests. scripts/orca-verify runs the test and typecheck commands from orca.project.yaml and fails when no test command is set. The checks you already run stay until that file points at them. Auth, billing, payments, data deletion, and migrations wait for you before they change and before they merge. scripts/guardrails reports a touch and does not block a merge by itself.

Point this project at Orca

Bleeps is built for Orca. The shared orca.yaml is the factory config. Symlink it, and commit orca.project.yaml copied from the example. Set install, test, and typecheck to the commands this repository already runs.

ln -s /path/to/bleeps-and-bloops/orca.yaml orca.yaml
cp /path/to/bleeps-and-bloops/examples/orca.project.yaml orca.project.yaml

If you set test_unit, test_integration, or test_e2e, bleeps test runs those instead of the single test command. proactive defaults to on. Set proactive: off to keep Chip from filing issues here. Commit orca.project.yaml. Do not commit secrets.

Installing Orca on a machine is still open. The written steps are in the home-server notes. 8 GB of RAM is the floor. 16 GB is comfortable. One worktree per ticket keeps this repository from trampling another.

Blip is the QA lead. Blip sets up and maintains the unit, integration, and end-to-end tests. On a web app, end-to-end defaults to Playwright. Put test, or test_unit, test_integration, and test_e2e, in orca.project.yaml. Green tests are a hard gate before auto-merge. A missing test command fails bleeps test. The role is in the repo.

Once setup is done

The day-to-day line is the same as on a new project: an issue, a merge to develop, and you promoting main. Blip keeps the tests that gate the merge. Bloops is who merges, through the script.

Day to day with Bleeps