From 0d9305334bc2e897f6518ecc15ad37f0f8f766b2 Mon Sep 17 00:00:00 2001 From: DJ Date: Sat, 28 Mar 2026 18:04:19 -0700 Subject: [PATCH 1/3] Add workflow, environment, and orchestration guidance from usage insights Adds four new sections based on recurring friction patterns observed across 80+ agent sessions: Project Context (assume brownfield), Git Workflow (branch creation and switching guardrails), Development Environment (dependency checks before launch), and Branch Protection & SonarCloud (merge retry limits). Also adds Multi-Repo Orchestration rules to the existing multi-agent section. Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 468958f..8e3ac9b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,44 @@ This file defines cross-cutting development standards for all repositories in th --- +## Project Context + +- **Primary languages:** TypeScript, HTML, Markdown. Individual repos may also use Go, Terraform, or other languages as specified in their own AGENTS.md. +- **Assume brownfield.** When exploring a repo, check for existing source code before assuming it is greenfield. Look at all directories, worktrees, and non-main branches before concluding that code does not exist. + +--- + +## Git Workflow + +### Branch Creation + +- **Always base new branches off `main`** (not off other feature or PR branches) unless explicitly told otherwise. +- Before creating a branch, run: + + ```bash + git checkout main && git pull origin main + ``` + +### Branch Switching + +- **Before switching branches, always commit or stash current work.** Uncommitted changes can be lost during branch switches. +- After switching, verify you are on the correct branch with `git branch --show-current` before making any changes. + +--- + +## Development Environment + +When the user asks to run or launch an app, first check the environment for required dependencies and report blockers immediately rather than attempting extensive debugging. At minimum, verify: + +1. **Required runtimes** — Node.js, Go, Python, etc. as specified by `package.json`, `go.mod`, or equivalent +2. **System dependencies** — display server (for Electron/GUI apps), Homebrew, sudo availability +3. **Available ports** — check for conflicts on common dev ports (3000, 5173, 8080) +4. **Package installation** — run `npm install`, `go mod download`, etc. before attempting to build or run + +If a dependency cannot be resolved, report the specific blocker and a workaround immediately — do not spend time debugging environment issues repeatedly. + +--- + ## Test-Driven Development (TDD) - **TDD is mandatory.** Write tests before implementing features or bug fixes. Include tests in the same PR as the implementation. @@ -202,6 +240,12 @@ All repositories MUST configure and enforce the following CI checks. PRs cannot - Never bypass CI gates or weaken thresholds to make a PR pass. - Address CodeRabbit and Copilot review comments the same way you address human reviewer comments — fix or explicitly justify skipping with a reply. +### Branch Protection & SonarCloud + +- This org uses **branch protection with SonarCloud checks** and `enforce_admins` enabled. +- SonarCloud check names may not match exactly across repos — expect check name mismatches. If a merge is blocked by a stale or mismatched check, use `gh pr merge --admin` to override. +- **Do not retry a failing merge more than twice** without telling the user what is blocking it. Surface the specific check name, status, and reason. + --- ## Multi-Agent Isolation — Git Worktrees @@ -307,6 +351,16 @@ Add worktree directories to the project's `.gitignore`: .worktrees/ ``` +### Multi-Repo Orchestration + +When working across multiple repositories, use separate agents to work on each repo in parallel. Each agent MUST: + +1. **Clone or use a separate worktree** — never share a working directory between repos +2. **Work only on its assigned repo** — do not modify files in other repos +3. **Report back status when done** — include PR URL, CI status, and any blockers + +Do NOT share branches or state between agents operating on different repos. + ### Coordination Checklist (for humans orchestrating multiple agents) Before launching parallel agents, verify: From 11204ab292059fee46bb57fcee35798475b55b97 Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Sat, 28 Mar 2026 18:08:06 -0700 Subject: [PATCH 2/3] Update project context in AGENTS.md Clarified primary languages used in the project. --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 8e3ac9b..9e9fce3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,6 @@ This file defines cross-cutting development standards for all repositories in th ## Project Context -- **Primary languages:** TypeScript, HTML, Markdown. Individual repos may also use Go, Terraform, or other languages as specified in their own AGENTS.md. - **Assume brownfield.** When exploring a repo, check for existing source code before assuming it is greenfield. Look at all directories, worktrees, and non-main branches before concluding that code does not exist. --- From 1b9ce04cc4fcf366fa27e6ace444005945db6751 Mon Sep 17 00:00:00 2001 From: DJ Date: Sat, 28 Mar 2026 18:11:38 -0700 Subject: [PATCH 3/3] Address review comments from Copilot and CodeRabbit - Use "default branch" terminology consistent with multi-agent section - Add clean working tree check before branch creation - Clarify branch switching risk (Git prevents most data loss) - Gate admin override behind explicit user approval and verification - Fix worktree/clone wording in multi-repo orchestration Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9e9fce3..bd0e843 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,8 +16,8 @@ This file defines cross-cutting development standards for all repositories in th ### Branch Creation -- **Always base new branches off `main`** (not off other feature or PR branches) unless explicitly told otherwise. -- Before creating a branch, run: +- **Always base new branches off the default branch (`main`)** (not off other feature or PR branches) unless explicitly told otherwise. +- Before creating a branch, ensure your working directory is clean (commit or stash any changes), then run: ```bash git checkout main && git pull origin main @@ -25,7 +25,7 @@ This file defines cross-cutting development standards for all repositories in th ### Branch Switching -- **Before switching branches, always commit or stash current work.** Uncommitted changes can be lost during branch switches. +- **Before switching branches, always commit or stash current work.** Git usually prevents checkouts that would overwrite local changes, but forced operations (e.g., `git checkout -f` or `git reset --hard`) or resolving conflicts incorrectly can cause you to lose or misplace work. - After switching, verify you are on the correct branch with `git branch --show-current` before making any changes. --- @@ -242,8 +242,8 @@ All repositories MUST configure and enforce the following CI checks. PRs cannot ### Branch Protection & SonarCloud - This org uses **branch protection with SonarCloud checks** and `enforce_admins` enabled. -- SonarCloud check names may not match exactly across repos — expect check name mismatches. If a merge is blocked by a stale or mismatched check, use `gh pr merge --admin` to override. -- **Do not retry a failing merge more than twice** without telling the user what is blocking it. Surface the specific check name, status, and reason. +- SonarCloud check names may not match exactly across repos — expect check name mismatches. If a merge is blocked, first identify the exact required check name(s), status, and mismatch source; then fix branch-protection or check configuration. Use `gh pr merge --admin` only with explicit user approval and only after confirming all intended quality gates have passed. +- **Do not retry a failing merge more than twice** without telling the user what is blocking it. Surface the specific check name, status, and reason before any override is considered. --- @@ -354,7 +354,7 @@ Add worktree directories to the project's `.gitignore`: When working across multiple repositories, use separate agents to work on each repo in parallel. Each agent MUST: -1. **Clone or use a separate worktree** — never share a working directory between repos +1. **Use a separate clone or working directory per repo** — never share a working directory between repos; within each repo, use separate worktrees or isolated environments per agent/task 2. **Work only on its assigned repo** — do not modify files in other repos 3. **Report back status when done** — include PR URL, CI status, and any blockers