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
Do this now
Use the repository you administer
You need admin on the GitHub repository so you can protect
mainand add labels. GitHub Issues stay the ticket source. Issues already in the tracker stay issues.Do this now
Add develop beside the branch you ship
Create
developfrom the branch you trust if the repository does not have it. Leavemainnamedmain. Agent pull requests targetdevelop. You mergedevelopintomain. The settled names are those two. A mapping for other branch names is not decided.Protect
mainso the owner is the person who can merge into it. Keep the protection you already have, and keep agents offmain. GitHub auto-merge is still an open question.scripts/merge-prdoes 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.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.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, oradds.highmeans a guardrail and waits for you.Do this now
Add a friction label
Create the
frictionlabel 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 openfrictionissues before you file a duplicate.Do this now
Keep your checks, and name the guardrails
Your tests stay your tests.
scripts/orca-verifyruns the test and typecheck commands fromorca.project.yamland 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/guardrailsreports 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.yamlIf 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.