Start a new project
Create the GitHub repository, then shape it so a ticket can land on develop. These steps follow Using Bleeps and the primitives. The commands that run a ticket are still planned. The pattern files are in the Bleeps and Bloops repo.
Shape the repository
Do this now
Create the repository
Create a GitHub repository you administer. GitHub Issues are the ticket source. Linear and Discord can feed the same
ticket.mdlater. They are not the front door today.Do this now
Add develop, and protect main
Create a
developbranch. Protectmainso you, the owner, are the person who can merge into it. Agent pull requests targetdevelop. GitHub auto-merge is still an open question. Bloops usesscripts/merge-pr, which does not turn that setting on.Do this now
Add a short AGENTS.md
Put a router at the root. A few lines and links. Name Bleeps as the doer that runs the crew, and point at 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. Detail lives on the linked page.
Do this now
Add the pull request template
Copy the pull request template. The recap classifies the change as
composes,extends, oradds. Roll up to the highest class. The risk tier is separate.highmeans the diff touches a guardrail and waits for you.Do this now
Add a friction label
Papercuts are GitHub issues labeled
friction, in the format in the friction log. They are not files in the tree. Search openfrictionissues before you file a duplicate.Do this now
Treat five areas as sign-off
Auth, billing, payments, data deletion, and migrations wait for you before they change and before they merge. The list is decided.
scripts/guardrailsreports a touch. It does not block a merge by itself.
Point the project at Orca
Bleeps is built for Orca, the MIT-licensed harness. Orca runs an agent in an isolated worktree per ticket. The shared orca.yaml is the factory config. Symlink it, and commit orca.project.yaml copied from the example.
ln -s /path/to/bleeps-and-bloops/orca.yaml orca.yaml
cp /path/to/bleeps-and-bloops/examples/orca.project.yaml orca.project.yamlSet install, test, and typecheck. proactive defaults to on, so Chip files issues. Set proactive: off to keep this project out of the patrol. Commit orca.project.yaml. Do not commit secrets.
Installing Orca on a machine is still open. The steps that are written are in the home-server notes: clone, approve the setup script, then orca worktree create --run-hooks. 8 GB of RAM is the floor. 16 GB is comfortable. Registering Chip's daily run is python3 scripts/bleeps-scout schedule, then the same command with --install, after scout_provider is set.
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
Filing issues, the line to a merge on develop, guardrails, the friction log, and Chip's patrol are the same from here. Blip keeps the tests that gate the merge. Bloops is who merges, through the script.