Skip to content
bleeps & bloops

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

  1. 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.md later. They are not the front door today.

  2. Do this now

    Add develop, and protect main

    Create a develop branch. Protect main so you, the owner, are the person who can merge into it. Agent pull requests target develop. GitHub auto-merge is still an open question. Bloops uses scripts/merge-pr, which does not turn that setting on.

  3. 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.

  4. Do this now

    Add the pull request template

    Copy the pull request template. The recap classifies the change as composes, extends, or adds. Roll up to the highest class. The risk tier is separate. high means the diff touches a guardrail and waits for you.

  5. 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 open friction issues before you file a duplicate.

  6. 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/guardrails reports 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.yaml

Set 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.

Day to day with Bleeps