From 2a7ac66379f31522bfffe929add04cac6e16efcc Mon Sep 17 00:00:00 2001 From: Ben Schellenberger Date: Sun, 19 Apr 2026 02:41:46 -0400 Subject: [PATCH] docs(agents): autonomy-first guardrails and Bugbot policy - Autonomous work first; multi-repo changes encouraged - Fresh tip (ff-only preferred); pull --rebase ideal but optional - No automatic force-push; require explicit human approval with reasoning and effects - Worktrees optional at operator discretion - Bugbot: autonomy, cross-repo PRs, safer history guidance --- .cursor/BUGBOT.md | 6 ++++++ AGENTS.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 .cursor/BUGBOT.md create mode 100644 AGENTS.md diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md new file mode 100644 index 0000000..6c5e51e --- /dev/null +++ b/.cursor/BUGBOT.md @@ -0,0 +1,6 @@ +# Bugbot review guidance +## Autonomy, cross-repo, and history (reviewers) + +- **Autonomy first:** Prefer review feedback that keeps agents unblocked. Ask for repository splits or extra ceremony only when risk truly warrants it. +- **Multi-repo efforts:** A change may be intentionally split across repositories; read the PR body for links to sibling PRs before calling the work incomplete for only touching one repo. +- **Force-push:** Never suggest force-push as a silent or automatic fix. If history rewrite is raised, require clear **user-visible** justification: **why** it is proposed, **blast radius** and effects on others and CI, and why non-destructive options are insufficient—default to safer paths. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a25444f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,30 @@ +# AGENTS.md + + +## Agentic guardrails + +These notes apply to humans and to automated agents (including Cloud Agents). + +1. **Autonomous work comes first** + The default posture is to **finish useful work without unnecessary human gates**. Prefer actions that keep momentum (fetch, build, test, open PRs) over asking for permission for routine steps—while still honoring the hard safety rules below. + +2. **Multi-repository work is encouraged** + When a task genuinely spans more than one codebase (services, libraries, docs, sibling CLIs), work across **multiple repositories or local clones** as needed. Open **one PR per repository**, keep each PR scoped, and **link related PRs** in every description so reviewers see the coordinated change. + +3. **Stay on a fresh enough tip; rebase is optional** + Before substantive work: `git fetch origin`, check out your branch, then prefer **`git merge --ff-only origin/`** (or `git pull --ff-only` when upstream exists). If you cannot fast-forward, pause and use the repository’s normal merge or rebase workflow—**do not** silently work on a stale checkout. **`git pull --rebase`** is *ideal* when updating an active feature branch, but it is **not required**; a merge commit or team-standard flow is fine when it avoids needless churn. + +4. **Force-push is never automatic and needs explicit human buy-in** + Do **not** run `git push --force`, `git push --force-with-lease`, or rewrite published history on your own. If you believe it might be warranted, **stop** and give the **human** explicit **reasoning**, **effects** on collaborators, CI, and open PRs, and **why** a force-push would be needed versus safer alternatives (new branch, revert, merge). Proceed **only** after they **explicitly approve** that exact repository and branch. + +5. **Focused changes and verification** + Keep pull requests focused; run this repository’s standard build, test, and lint commands (see `README`, `Makefile`, or `CLAUDE.md`) before requesting review. + +6. **Workflow shape is yours** + Using **git worktree** versus a single working directory is an **operator choice**; these docs do **not** require worktrees. + + + +--- + +