Add workflow, environment, and orchestration guidance

[don-petry]

Summary

• Project Context — primary languages, assume-brownfield rule to prevent agents from missing existing code
• Git Workflow — branch creation (always from main) and branch switching (commit/stash first, verify after) guardrails to eliminate recurring branch confusion
• Development Environment — dependency/runtime check-first protocol before attempting to build or launch apps
• Branch Protection & SonarCloud — document enforce_admins, check name mismatch expectations, and merge retry limits
• Multi-Repo Orchestration — rules for parallel agents working across different repositories

Motivation

These additions address the top friction patterns observed across 80+ agent sessions:

• Branch confusion (wrong base branch, lost uncommitted work) — 34 wrong-approach incidents
• Environment blockers (missing Node.js, display server, ports) — 6+ sessions stalled
• SonarCloud check name mismatches blocking merges — 4+ sessions affected
• Agents failing to find existing code in non-main branches or worktrees

Test plan

• Review new sections for consistency with existing AGENTS.md style
• Verify no conflicts with repo-level AGENTS.md overrides
• Confirm guidance is actionable across TypeScript, Go, and Terraform repos

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added project context guidance for exploring existing repositories and onboarding.
  • Defined explicit Git workflow rules: branch from main after sync and safe branch switching practices.
  • Added development environment pre-flight checks with immediate blocker reporting before deep debugging.
  • Clarified CI expectations: branch protection with SonarCloud checks, admin-override guidance, and merge retry limits.
  • Added multi-repo orchestration rules: isolated per-repo workspaces, restrict changes to assigned repos, and forbid sharing branch/state across repos.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 031055a7-62e4-4c0a-9a14-55b39e7ba565

📥 Commits

Reviewing files that changed from the base of the PR and between 11204ab and 1b9ce04.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

Added documentation to AGENTS.md defining project-context guidance, git workflow and safe-branching rules, development-environment pre-flight checks, branch-protection/SonarCloud CI requirements, and multi-repo orchestration rules enforcing isolated per-repo agent workspaces.

Changes

Cohort / File(s)	Summary
Documentation AGENTS.md	Inserted sections: "Project Context"; "Git Workflow" (branch-from-main, safe switching); "Development Environment" (dependency/runtime/system/port pre-flight checks); "Branch Protection & SonarCloud" (required checks, enforce_admins, handling blocked merges); and "Multi-Repo Orchestration" (isolated per-repo clones/working dirs, repo-scoped changes, PR/CI reporting, forbid shared branches/state).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

• Add multi-agent isolation strategy using git worktrees #2: Proposes a git-worktree–based per-agent workspace isolation approach that aligns with the Multi-Repo Orchestration rules added here.
• Addressing PR comments #1: Initial AGENTS.md changes that this PR extends with additional workflow, CI, and orchestration guidance.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: adding three new guidance sections (workflow, environment, and orchestration) to AGENTS.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/enhance-agents-workflow-guidance

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates the org-wide AGENTS.md standards to reduce recurring agent friction around repo discovery, git workflow hygiene, environment readiness checks, CI/branch-protection behavior, and parallel work across repositories.

Changes:

• Add “Project Context” guidance (primary languages, assume-brownfield exploration).
• Add explicit Git workflow and development-environment preflight guidance.
• Add SonarCloud/branch-protection notes and multi-repo orchestration rules.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Around line 18-25: Update the "Branch Creation" instructions to first check
for uncommitted changes before running the existing git commands: explicitly
require running a status check and instruct to either commit or stash local
changes (or abort) when uncommitted changes are present, then proceed with the
existing sequence "git checkout main && git pull origin main"; reference the
"Branch Creation" heading and the existing command string so the doc change adds
the pre-check and the commit/stash guidance consistent with the Branch Switching
guidance.
- Line 20: Update the wording of the sentence "**Always base new branches off
`main`**" to match the "default branch" terminology used elsewhere (e.g., the
Multi-Agent Isolation text that mentions "branch from the repository's
configured default branch (for example, `origin/main`)"); replace the explicit
`main` reference with a phrasing such as "the repository's configured default
branch (for example, `origin/main`)" so the language is consistent across
AGENTS.md and aligns with the worktrees section.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 868bd70b-be05-4c23-86fb-0e2c94ba409a

📥 Commits

Reviewing files that changed from the base of the PR and between b0ff212 and 0d93053.

📒 Files selected for processing (1)

• AGENTS.md

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

AGENTS.md (1)

19-24: ⚠️ Potential issue | 🟠 Major

Require a clean working tree before git checkout main.

Line 20 should explicitly require checking git status and committing/stashing first; otherwise branch creation can fail or cause context loss. Also prefer “default branch” terminology to match Line 261.

🔧 Proposed doc fix

-- **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 repository's configured default branch (for example, `origin/main`)** (not off other feature or PR branches) unless explicitly told otherwise.
+- Before creating a branch, verify the working tree is clean (`git status`), then commit or stash any pending changes. Next run:
 
   ```bash
   git checkout main && git pull origin main

</details>
Based on learnings: “Workspaces MUST branch from the repository's configured default branch…” and “If the worktree has uncommitted changes, the agent MUST commit or discard before exiting.”

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @AGENTS.md around lines 19 - 24, Update the branching guidance to require a
clean working tree before switching to the default branch: replace references to
"main" with "default branch" where applicable (the bullet "Always base new
branches off main" and the command snippet), and add a step instructing users
to run git status and commit or stash/discard uncommitted changes before
running the checkout/pull sequence so branch creation won't fail or lose
context.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @AGENTS.md:

• Around line 245-246: Replace the instruction that recommends using "gh pr
  merge --admin" for stale/mismatched SonarCloud checks with guidance to first
  verify the actual required status checks and branch-protection configuration
  (i.e., inspect check names, statuses and branch protection settings) and prefer
  fixing the check-name or branch-protection configuration rather than bypassing;
  update the text that warns "Do not retry a failing merge more than twice" to
  require surfacing the specific failing check name, status and reason before any
  admin override is considered, and remove or gate any unconditional
  admin-override recommendation (references: the string "gh pr merge --admin" and
  the paragraph about retrying merges).

---

Duplicate comments:
In @AGENTS.md:

• Around line 19-24: Update the branching guidance to require a clean working
  tree before switching to the default branch: replace references to "main" with
  "default branch" where applicable (the bullet "Always base new branches off
  main" and the command snippet), and add a step instructing users to run git status and commit or stash/discard uncommitted changes before running the
  checkout/pull sequence so branch creation won't fail or lose context.

</details>

<details>
<summary>🪄 Autofix (Beta)</summary>

Fix all unresolved CodeRabbit comments on this PR:

- [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended)
- [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Organization UI

**Review profile**: ASSERTIVE

**Plan**: Pro

**Run ID**: `8715f10e-bf04-442e-a4a7-e3b58dc2af2e`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 0d9305334bc2e897f6518ecc15ad37f0f8f766b2 and 11204ab292059fee46bb57fcee35798475b55b97.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `AGENTS.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->