Use cases

End-to-end walkthroughs of what Branchscope is for.

1. An agent ships a feature; a person reviews meaning, not lines#

1. The agent signs in: alice runs bscope agent login --name claude-api and, on the consent page, limits it to acme/billing. bscope agent setup-git --name claude-api in its clone makes its pushes the agent's.
2. The agent works:
   • it writes PLAN.md with a branchscope block: it will touch src/Billing.Api/**, and not the data layer;
   • it works on a branch and pushes. Pushing to main would be refused: agents can't update protected branches.
3. It checks its own work: it opens a change and waits for the review with bscope change review --wait --fail-on deny. A broken rule exits 3; it reads --json, fixes the code and pushes again, and the review re-runs.
4. alice reviews: she opens the change and reads:
   • the findings: one "needs review: table-writes", with a link to the line;
   • the change map: a new InvoicesController.Create(), writing the invoices table;
   • the API diagram: a new POST /invoices, called from the web app's createInvoice().
5. She merges. The push guard allows it (she's a person), the merge is recorded, and main is indexed.

2. Hand a team's agent its work, and follow it#

1. The organization installs an agent app, such as a hosted coding agent, on acme/billing, and limits it to 5 open changes.
2. bob asks it for something: on change #12, Ask an agent → "Address the review findings"; on the repository's Tasks, "Add an export endpoint for invoices", from main.
3. The agent hears of both at once (its webhook and its MCP session), and posts its status as it goes: working, then blocked: "Which date format?".
4. bob answers in the change's discussion; the agent hears of the reply, pushes a fix, and reports done. Its new change for the export is linked to the task.
5. The organization's Agents page shows what it's doing, and what the push guard refused it. If it misbehaves, Pause stops it at once.

3. Keep agents off main, and know what each one did#

• Protect the branches: a branch ruleset (Settings → Branches) targets main and release/*, with Block agent updates: no agent can update them, even with write access. Turn on Require a change before merging so nothing lands without a change, for people too.
• Know who did what: every agent's pushes appear in Activity as "claude-api, agent, for alice". Sign one agent out (or pause a team's agent), and it stops while alice keeps working.
• During an incident: a site admin turns on deny-all (sidebar → Push guard). Every push is refused with the message they set, until it's turned off.

4. Enforce your architecture on every change#

A branchscope.json in the repository says:

• controllers may not reference the data layer (deny);
• new writes to tables need review;
• reads of personal data need review.

From then on:

• New violations show in red and count as rule violations; old ones are counted, not blamed.
• Moving or renaming code doesn't turn existing violations into new ones.
• A change can't remove a rule to pass its own review: the target branch's rules apply.
• CI or an agent can gate on it: bscope change review "$N" --fail-on deny.

5. Find where personal data goes#

Tag the data: EF Core properties marked [PersonalData] are tagged pii, and so are the columns they map to. Then:

• the Graph → Data flow view shows each pii column, the code that reads and writes it, and the endpoints and screens that reach that code;
• a rule on a pii layer makes every new read or write of personal data stand out in reviews.

6. Understand an unfamiliar codebase#

• Architecture shows the projects, how they depend on each other, and which endpoints, tables and screens each one touches. Click a project to see its modules.
• Explorer finds any type, function or endpoint by name, and shows what it uses and what uses it, with links to the code.
• Agents read the same views: bscope graph view architecture --json, or the graph itself with bscope graph download.

7. Refactor without noise#

Rename functions, move files, or rename a C# class. If the code didn't change, the review shows each element once as renamed or moved ("was fetchInvoice()", "moved from src/lib/a.ts"), not as a removal plus an addition. Rule violations follow them, and the edits that matter stay visible.

8. Work entirely from the terminal#

bscope auth login && bscope auth setup-git
bscope repo create notes            # alice/notes
git remote add origin "$(bscope repo view -R alice/notes --json | jq -r .cloneUrl)"
git push -u origin main
git checkout -b idea && …; git push origin idea
bscope change create -t "An idea"
bscope change review 1 --wait
bscope change merge 1