From 0d9305334bc2e897f6518ecc15ad37f0f8f766b2 Mon Sep 17 00:00:00 2001 From: DJ Date: Sat, 28 Mar 2026 18:04:19 -0700 Subject: [PATCH 1/9] 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/9] 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/9] 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 From 46357b186efc0a0e048fa2d1ab54cb6b15c1116c Mon Sep 17 00:00:00 2001 From: DJ Date: Sun, 29 Mar 2026 12:36:11 -0700 Subject: [PATCH 4/9] Add stacked PR strategy for Epic-level development MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduces a comprehensive stacked PR workflow where dependent Epics form a linear chain (main ← Epic-1 ← Epic-2 ← ...) with bottom-up merging. Within each Epic, multiple agents work stories in parallel via worktrees branching from the Epic integration branch. Sprints within an Epic can also overlap when independent. Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 237 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 236 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index bd0e843..3462a9b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -258,7 +258,7 @@ Never have two agents working in the same working directory simultaneously. 1. **One workspace per agent.** Every agent performing code changes MUST operate in its own isolated workspace (git worktree, container, or ephemeral environment). This applies to Claude Code (`isolation: "worktree"` or `--worktree`), Cursor parallel agents, GitHub Copilot coding agent, OpenAI Codex, and any other AI agent tool. 2. **One agent per story/task.** Each workspace maps to exactly one BMAD story, feature, or bug fix. Do not assign the same story to multiple agents. 3. **No overlapping file ownership.** Two agents MUST NOT modify the same file concurrently. If stories touch shared files (e.g., a shared type definition, config, or lockfile), serialize those stories — do not run them in parallel. This is the single most important rule for multi-agent work. -4. **Branch from the default branch.** Workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch. +4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic Development](#stacked-prs-for-epic-development)). Workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when Epics are part of a declared stack and the child Epic branches from its parent Epic's branch. 5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. 6. **3–5 parallel agents max.** Coordination overhead increases non-linearly. Limit concurrent agents to 3–5 per repository. @@ -371,6 +371,241 @@ Before launching parallel agents, verify: --- +## Stacked PRs for Epic Development + +When a project has multiple Epics with **sequential dependencies** — where Epic 2 builds on the foundation laid by Epic 1, Epic 3 extends Epic 2, and so on — the standard "branch from main" model forces each Epic to wait for the previous Epic's PR to fully merge before work can begin. Stacked PRs eliminate this bottleneck by letting each Epic's branch build on the previous Epic's branch, forming a chain that merges bottom-up. + +Each Epic produces a **single PR** containing all of that Epic's stories. The stack is a chain of Epic-level PRs: + +``` +main ← Epic-1-PR ← Epic-2-PR ← Epic-3-PR ← Epic-4-PR +``` + +> **When to use stacked PRs:** Only when Epics have true sequential dependencies — i.e., Epic 2 cannot compile or pass tests without Epic 1's code. If Epics are independent, use the standard parallel workflow (one agent per Epic, all branching from `main`). + +### How It Works + +Each Epic gets one long-lived **integration branch**. Multiple agents work stories concurrently in separate worktrees that branch from the Epic branch, then merge their completed stories back into it. The Epic branch accumulates all story work and becomes one PR in the stack. + +| PR | Source branch | Target branch | +|----|---------------|---------------| +| Epic 1 PR | `epic-1/foundation` | `main` | +| Epic 2 PR | `epic-2/core-features` | `epic-1/foundation` | +| Epic 3 PR | `epic-3/integrations` | `epic-2/core-features` | +| Epic 4 PR | `epic-4/polish` | `epic-3/integrations` | + +When Epic 1's PR merges into `main`, Epic 2's PR is retargeted to `main`, and so on up the stack. + +### Rules for Stacked Epic PRs + +1. **One PR per Epic.** Each Epic produces exactly one PR. All stories within the Epic are merged into the Epic's integration branch. +2. **Stacks are strictly linear.** No branching within a stack (no diamond or tree shapes). One parent Epic, one child Epic. +3. **Maximum stack depth: 4 Epics.** Deeper stacks become fragile and painful to rebase. If a project has more than 4 sequential Epics, look for opportunities to merge intermediate Epics before continuing. +4. **Parallel agents within an Epic.** Multiple agents CAN work on stories within the same Epic concurrently — each in its own worktree branching from the Epic branch. The standard multi-agent isolation rules apply: no two agents modify the same file. Story worktrees merge back into the Epic branch when complete. +5. **Sprints within an Epic may overlap.** If Sprint 2's stories are independent of Sprint 1's stories, agents may work on both sprints concurrently. Only serialize sprints when later stories depend on earlier ones. +6. **Independent Epic stacks CAN run in parallel.** If your project has two separate dependency chains (e.g., Epics A1→A2 and Epics B1→B2), run those stacks concurrently with separate agents. The standard multi-agent isolation rules apply — no overlapping file ownership across stacks. +7. **File ownership within a stack is cumulative.** Files touched by Epic 1 may also be touched by Epic 2 (that's the nature of sequential dependency). Ensure agents in the child Epic coordinate with the parent Epic's completed state. +8. **Bottom-up merge order is mandatory.** Always merge the bottom Epic PR first, then retarget the next Epic PR to `main`, and so on. Never merge out of order. + +### Workflow — Planning the Stack + +Before any agent starts, the orchestrator (human or planning agent) identifies the Epic dependency order and documents the stack plan: + +```markdown +## Project Stack Plan +1. Epic 1 — Foundation: data model, core types, DB schema (base → main) +2. Epic 2 — Core Features: service layer, business logic (base → Epic 1) +3. Epic 3 — Integrations: API endpoints, external services (base → Epic 2) +4. Epic 4 — Polish: UI refinements, error handling, docs (base → Epic 3) +``` + +Each Epic should list its stories, and the plan should call out which files/modules each Epic owns. + +### Workflow — Implementing the Stack + +**Step 1: Create the Epic integration branch.** The orchestrator (or first agent) creates the Epic branch from its parent: + +```bash +# Epic 1 branches from main +git checkout main && git pull origin main +git checkout -b epic-1/foundation +git push -u origin epic-1/foundation + +# Open the Epic PR (initially empty or with scaffolding) +gh pr create --base main --title "Epic 1: Foundation" --body "..." --draft +``` + +**Step 2: Agents work stories in parallel worktrees.** Each agent creates a story worktree branching from the Epic branch: + +```bash +# Agent 1 — Story S-1.1 +git worktree add .worktrees/S-1.1-data-model -b epic-1/S-1.1-data-model origin/epic-1/foundation + +# Agent 2 — Story S-1.2 (concurrent, no file overlap with S-1.1) +git worktree add .worktrees/S-1.2-core-types -b epic-1/S-1.2-core-types origin/epic-1/foundation + +# Agent 3 — Story S-1.3 (concurrent, no file overlap) +git worktree add .worktrees/S-1.3-db-schema -b epic-1/S-1.3-db-schema origin/epic-1/foundation +``` + +Each agent implements its story, runs quality checks, and pushes. + +**Step 3: Merge stories back into the Epic branch.** As stories complete, merge them into the Epic integration branch: + +```bash +# Merge completed story into the Epic branch +git checkout epic-1/foundation +git merge origin/epic-1/S-1.1-data-model +git push origin epic-1/foundation + +# Later stories may need to rebase onto the updated Epic branch before merging +git checkout epic-1/S-1.3-db-schema +git rebase origin/epic-1/foundation +# resolve any conflicts, then merge back +``` + +Alternatively, story branches can be merged via short-lived PRs targeting the Epic branch for lightweight code review within the Epic. + +**Step 4: Create the next Epic branch.** Once the previous Epic branch has enough foundation (stories merged), create the next Epic: + +```bash +# Epic 2 branches from Epic 1 +git checkout epic-1/foundation && git pull origin epic-1/foundation +git checkout -b epic-2/core-features +git push -u origin epic-2/core-features +gh pr create --base epic-1/foundation --title "Epic 2: Core Features" --body "..." --draft +``` + +Agents then work Epic 2's stories in parallel worktrees branching from `epic-2/core-features`, following the same pattern. + +**Step 5: Repeat** for each subsequent Epic in the stack. + +### Workflow — Merging the Stack + +1. **Merge the bottom PR** (Epic 1 → `main`) using the repo's standard merge strategy. +2. **Retarget the next PR** to `main`: + ```bash + gh pr edit --base main + ``` +3. **Rebase the next branch** onto `main` to incorporate the merge and resolve any squash/rebase differences: + ```bash + # In the Epic 2 worktree + git fetch origin main + git rebase origin/main + git push --force-with-lease + ``` +4. **Review and merge Epic 2** → `main`. Repeat for Epic 3, Epic 4, etc. + +### Workflow — Handling Changes to a Lower Epic PR + +If a reviewer requests changes to a lower Epic PR (e.g., Epic 1), the agent making fixes MUST propagate changes upward: + +1. Make the fix on Epic 1's branch and push. +2. For each child branch in order, rebase onto the updated parent: + ```bash + # In Epic 2 worktree + git fetch origin epic-1/foundation + git rebase origin/epic-1/foundation + # Resolve any conflicts + git push --force-with-lease + ``` +3. Repeat for Epic 3 if it exists (rebasing onto Epic 2's updated branch), and so on. + +If conflicts are extensive, consider collapsing the stack — merge what you can into `main` and rebuild the remaining Epics from there. + +### Story and Sprint Organization Within an Epic + +The Epic branch is an **integration branch** — it accumulates completed stories. Agents do not work directly on the Epic branch. Instead, each agent works in its own story worktree that branches from the Epic branch. + +**Sprint-level organization:** + +Epics are typically broken into Sprints, each containing a set of stories. Within a Sprint, all stories with no file overlap can be worked in parallel by separate agents. Across Sprints: + +- **Independent Sprints** (no data/API dependency between them) — run concurrently. +- **Dependent Sprints** (Sprint 2 stories require Sprint 1 output) — run sequentially. Merge all Sprint 1 stories into the Epic branch before Sprint 2 agents branch from it. + +``` +Epic 1 branch (integration) +├── Sprint 1 (parallel agents) +│ ├── Agent 1 → S-1.1 worktree +│ ├── Agent 2 → S-1.2 worktree +│ └── Agent 3 → S-1.3 worktree +│ (all merge back into Epic branch) +├── Sprint 2 (parallel agents, after Sprint 1 merges) +│ ├── Agent 1 → S-1.4 worktree +│ └── Agent 2 → S-1.5 worktree +│ (merge back into Epic branch) +└── Epic PR → targets parent Epic branch or main +``` + +**Story worktree naming convention:** + +``` +.worktrees/-- +``` + +Branch name: `/-` + +Examples: `epic-1/S-1.1-data-model`, `epic-2/S-2.3-auth-middleware` + +**Merging stories back into the Epic branch:** + +Stories can be integrated via direct merge or via short-lived PRs targeting the Epic branch: + +| Method | When to use | +|--------|-------------| +| **Direct merge** (`git merge`) | Small team, high trust, fast iteration | +| **Story PRs** (PR targeting Epic branch) | Larger team, want per-story review before integration | + +Either way, the Epic-level PR in the stack is the final gate for review and CI before merging into the parent Epic or `main`. + +### Combining Stacked Epics with Parallel Agents + +Stacked PRs and parallel agents operate at different levels and are fully complementary: + +| Level | Parallelism | Constraint | +|-------|-------------|------------| +| **Across independent Epic chains** | Full parallel — separate stacks run concurrently | No file overlap between chains | +| **Across Epics in the same stack** | Sequential — child Epic starts after parent Epic branch is stable | Child branches from parent | +| **Within an Epic (across Sprints)** | Parallel if Sprints are independent; sequential if dependent | Dependent Sprints wait for prior Sprint to merge into Epic branch | +| **Within a Sprint** | Full parallel — multiple agents, one story each | No file overlap between stories | + +Example — a project with two Epic chains and six agents: + +| Agent | Chain | Epic | Sprint | Story | Branch base | Status | +|-------|-------|------|--------|-------|-------------|--------| +| Agent 1 | A | Epic 1 | Sprint 1 | S-1.1 (data model) | `epic-1/foundation` | Active | +| Agent 2 | A | Epic 1 | Sprint 1 | S-1.2 (core types) | `epic-1/foundation` | Active (parallel) | +| Agent 3 | A | Epic 1 | Sprint 1 | S-1.3 (db schema) | `epic-1/foundation` | Active (parallel) | +| Agent 4 | B | Epic 3 | Sprint 1 | S-3.1 (auth) | `epic-3/auth` | Active (parallel, different chain) | +| Agent 5 | B | Epic 3 | Sprint 1 | S-3.2 (sessions) | `epic-3/auth` | Active (parallel) | +| Agent 6 | A | Epic 2 | — | — | `epic-1/foundation` | Waiting (parent Epic incomplete) | + +Once Agents 1–3 merge their stories into `epic-1/foundation`, Agent 6 can begin Epic 2's stories. Meanwhile, Agents 4–5 continue independently on Chain B. + +### Stack Coordination Checklist + +Before starting a stacked Epic workflow, verify: +- [ ] Epics have genuine sequential dependencies (not just conceptual ordering) +- [ ] Stack depth is 4 or fewer Epics +- [ ] Stack plan is documented with Epic order, parent relationships, and Sprint breakdown +- [ ] Each Epic's file/module ownership is identified — no overlap across parallel stacks +- [ ] Within each Epic, stories are assigned to Sprints with file overlap analysis complete +- [ ] Stories within each Sprint have no file overlap (safe for parallel agents) +- [ ] Dependent Sprints are clearly marked — they wait for prior Sprint to merge into Epic branch +- [ ] Stories within each Epic are scoped and ready for implementation (BMAD artifacts complete) +- [ ] No more than 3–5 agents are running concurrently across all active Epics in the repository + +### Tooling Notes + +- **GitHub natively supports stacked PRs** — each PR targets a non-default base branch. The PR diff shows only the changes introduced by that Epic, not the full stack. +- **`gh` CLI** supports `--base` for targeting parent branches and `gh pr edit --base` for retargeting after merges. +- **Graphite, git-town, and spr** are dedicated stacked PR tools that automate rebasing and retargeting. Consider adopting one if stacks become a frequent workflow. +- **CI runs on each PR independently.** Ensure CI is configured to run against the PR's base branch, not just `main`. Most CI systems (GitHub Actions, etc.) handle this correctly by default. +- **PR review is incremental.** Reviewers see only the diff between the Epic branch and its parent — not the entire stack. This keeps reviews focused and manageable. + +--- + ## Agent Operation Guidance - Prefer interactive or dev commands when iterating; avoid running production-only commands from an agent session. From 49e1e4378f5cd7bd006872e26c14f10864518fa9 Mon Sep 17 00:00:00 2001 From: DJ Date: Sun, 29 Mar 2026 12:48:25 -0700 Subject: [PATCH 5/9] Address review comments from Copilot and CodeRabbit - Broaden Rule #4 exception to include story worktrees branching from Epic integration branches, not just child Epic branches - Add git fetch before merging story branches into Epic branch - Fix rebase snippet to run from within the story worktree instead of using git checkout (which fails when branch is in another worktree) - Add language identifiers (text/bash) to all unfenced code blocks - Add blank lines around fenced blocks inside ordered lists (MD031) - Add mandatory repo-level template for dev commands and env vars Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3462a9b..c51cd23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -258,7 +258,7 @@ Never have two agents working in the same working directory simultaneously. 1. **One workspace per agent.** Every agent performing code changes MUST operate in its own isolated workspace (git worktree, container, or ephemeral environment). This applies to Claude Code (`isolation: "worktree"` or `--worktree`), Cursor parallel agents, GitHub Copilot coding agent, OpenAI Codex, and any other AI agent tool. 2. **One agent per story/task.** Each workspace maps to exactly one BMAD story, feature, or bug fix. Do not assign the same story to multiple agents. 3. **No overlapping file ownership.** Two agents MUST NOT modify the same file concurrently. If stories touch shared files (e.g., a shared type definition, config, or lockfile), serialize those stories — do not run them in parallel. This is the single most important rule for multi-agent work. -4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic Development](#stacked-prs-for-epic-development)). Workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when Epics are part of a declared stack and the child Epic branches from its parent Epic's branch. +4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic Development](#stacked-prs-for-epic-development)). Outside a stacked-Epic workflow, workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when (a) Epics are part of a declared stack and the child Epic branches from its parent Epic's branch, or (b) story worktrees/branches are created from the Epic integration branch as defined in the stacked-PR workflow. 5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. 6. **3–5 parallel agents max.** Coordination overhead increases non-linearly. Limit concurrent agents to 3–5 per repository. @@ -377,7 +377,7 @@ When a project has multiple Epics with **sequential dependencies** — where Epi Each Epic produces a **single PR** containing all of that Epic's stories. The stack is a chain of Epic-level PRs: -``` +```text main ← Epic-1-PR ← Epic-2-PR ← Epic-3-PR ← Epic-4-PR ``` @@ -453,15 +453,17 @@ Each agent implements its story, runs quality checks, and pushes. **Step 3: Merge stories back into the Epic branch.** As stories complete, merge them into the Epic integration branch: ```bash -# Merge completed story into the Epic branch +# Merge completed story into the Epic branch (run from the Epic integration worktree) git checkout epic-1/foundation +git fetch origin epic-1/S-1.1-data-model git merge origin/epic-1/S-1.1-data-model git push origin epic-1/foundation -# Later stories may need to rebase onto the updated Epic branch before merging -git checkout epic-1/S-1.3-db-schema +# Later stories may need to rebase onto the updated Epic branch before merging. +# Run this from within the S-1.3 story worktree, where epic-1/S-1.3-db-schema is already checked out: +git fetch origin epic-1/foundation git rebase origin/epic-1/foundation -# resolve any conflicts, then merge back +# resolve any conflicts in the story worktree, then merge the updated story branch back into epic-1/foundation ``` Alternatively, story branches can be merged via short-lived PRs targeting the Epic branch for lightweight code review within the Epic. @@ -484,16 +486,20 @@ Agents then work Epic 2's stories in parallel worktrees branching from `epic-2/c 1. **Merge the bottom PR** (Epic 1 → `main`) using the repo's standard merge strategy. 2. **Retarget the next PR** to `main`: + ```bash gh pr edit --base main ``` + 3. **Rebase the next branch** onto `main` to incorporate the merge and resolve any squash/rebase differences: + ```bash # In the Epic 2 worktree git fetch origin main git rebase origin/main git push --force-with-lease ``` + 4. **Review and merge Epic 2** → `main`. Repeat for Epic 3, Epic 4, etc. ### Workflow — Handling Changes to a Lower Epic PR @@ -502,6 +508,7 @@ If a reviewer requests changes to a lower Epic PR (e.g., Epic 1), the agent maki 1. Make the fix on Epic 1's branch and push. 2. For each child branch in order, rebase onto the updated parent: + ```bash # In Epic 2 worktree git fetch origin epic-1/foundation @@ -509,6 +516,7 @@ If a reviewer requests changes to a lower Epic PR (e.g., Epic 1), the agent maki # Resolve any conflicts git push --force-with-lease ``` + 3. Repeat for Epic 3 if it exists (rebasing onto Epic 2's updated branch), and so on. If conflicts are extensive, consider collapsing the stack — merge what you can into `main` and rebuild the remaining Epics from there. @@ -524,7 +532,7 @@ Epics are typically broken into Sprints, each containing a set of stories. Withi - **Independent Sprints** (no data/API dependency between them) — run concurrently. - **Dependent Sprints** (Sprint 2 stories require Sprint 1 output) — run sequentially. Merge all Sprint 1 stories into the Epic branch before Sprint 2 agents branch from it. -``` +```text Epic 1 branch (integration) ├── Sprint 1 (parallel agents) │ ├── Agent 1 → S-1.1 worktree @@ -540,7 +548,7 @@ Epic 1 branch (integration) **Story worktree naming convention:** -``` +```text .worktrees/-- ``` @@ -612,6 +620,19 @@ Before starting a stacked Epic workflow, verify: - Keep dependencies and lockfiles in sync. - Prefer small, focused commands — run specific tests rather than the full suite when iterating (the full suite is still required before committing; see Pre-Commit Quality Checks). - Document project-specific dev/test/run commands and required environment variables in the repo's own AGENTS.md or README. +- Every repository-level AGENTS.md or README MUST include sections following this template: + + ```markdown + ## Local Development Commands + - Install: `` + - Dev run: `` + - Test: `` + - Lint: `` + - Typecheck (if applicable): `` + + ## Required Environment Variables + - `VAR_NAME`: purpose, allowed values, example + ``` --- From d586b295bd34799609d9ddcf0765e7db3c1de69b Mon Sep 17 00:00:00 2001 From: DJ Date: Sun, 29 Mar 2026 12:55:20 -0700 Subject: [PATCH 6/9] Simplify and tighten stacked PR documentation - Clarify Rule #5 re: story PRs targeting Epic branch are internal, not standalone feature PRs - Consolidate Step 3 merge commands into "Story and Sprint Organization" section to eliminate duplication - Replace vague "enough foundation" with explicit dependency criterion - Add "Keeping Epic Branches in Sync with Main" guidance - Standardize terminology on "Epic branch" (define "integration branch" once on first use) - Add story worktree cleanup guidance (remove after merging into Epic) - Add scoping note linking Epic naming convention to general convention - Remove redundant "When to use" callout (already covered in intro) Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 57 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c51cd23..9b56669 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -259,7 +259,7 @@ Never have two agents working in the same working directory simultaneously. 2. **One agent per story/task.** Each workspace maps to exactly one BMAD story, feature, or bug fix. Do not assign the same story to multiple agents. 3. **No overlapping file ownership.** Two agents MUST NOT modify the same file concurrently. If stories touch shared files (e.g., a shared type definition, config, or lockfile), serialize those stories — do not run them in parallel. This is the single most important rule for multi-agent work. 4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic Development](#stacked-prs-for-epic-development)). Outside a stacked-Epic workflow, workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when (a) Epics are part of a declared stack and the child Epic branches from its parent Epic's branch, or (b) story worktrees/branches are created from the Epic integration branch as defined in the stacked-PR workflow. -5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. +5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. (In a stacked-Epic workflow, story worktrees may optionally produce short-lived PRs targeting the Epic branch for review — these are internal integration PRs, not standalone feature PRs.) 6. **3–5 parallel agents max.** Coordination overhead increases non-linearly. Limit concurrent agents to 3–5 per repository. ### Detecting File Overlap @@ -381,11 +381,9 @@ Each Epic produces a **single PR** containing all of that Epic's stories. The st main ← Epic-1-PR ← Epic-2-PR ← Epic-3-PR ← Epic-4-PR ``` -> **When to use stacked PRs:** Only when Epics have true sequential dependencies — i.e., Epic 2 cannot compile or pass tests without Epic 1's code. If Epics are independent, use the standard parallel workflow (one agent per Epic, all branching from `main`). - ### How It Works -Each Epic gets one long-lived **integration branch**. Multiple agents work stories concurrently in separate worktrees that branch from the Epic branch, then merge their completed stories back into it. The Epic branch accumulates all story work and becomes one PR in the stack. +Each Epic gets one long-lived **Epic branch** (also called its integration branch). Multiple agents work stories concurrently in separate worktrees that branch from the Epic branch, then merge their completed stories back into it. The Epic branch accumulates all story work and becomes one PR in the stack. | PR | Source branch | Target branch | |----|---------------|---------------| @@ -450,25 +448,9 @@ git worktree add .worktrees/S-1.3-db-schema -b epic-1/S-1.3-db-schema origin/epi Each agent implements its story, runs quality checks, and pushes. -**Step 3: Merge stories back into the Epic branch.** As stories complete, merge them into the Epic integration branch: +**Step 3: Merge stories back into the Epic branch.** As stories complete, merge them into the Epic branch. See [Story and Sprint Organization Within an Epic](#story-and-sprint-organization-within-an-epic) for merge strategies and commands. -```bash -# Merge completed story into the Epic branch (run from the Epic integration worktree) -git checkout epic-1/foundation -git fetch origin epic-1/S-1.1-data-model -git merge origin/epic-1/S-1.1-data-model -git push origin epic-1/foundation - -# Later stories may need to rebase onto the updated Epic branch before merging. -# Run this from within the S-1.3 story worktree, where epic-1/S-1.3-db-schema is already checked out: -git fetch origin epic-1/foundation -git rebase origin/epic-1/foundation -# resolve any conflicts in the story worktree, then merge the updated story branch back into epic-1/foundation -``` - -Alternatively, story branches can be merged via short-lived PRs targeting the Epic branch for lightweight code review within the Epic. - -**Step 4: Create the next Epic branch.** Once the previous Epic branch has enough foundation (stories merged), create the next Epic: +**Step 4: Create the next Epic branch.** Once all stories that the next Epic depends on have been merged into the previous Epic branch, create the next Epic: ```bash # Epic 2 branches from Epic 1 @@ -521,9 +503,13 @@ If a reviewer requests changes to a lower Epic PR (e.g., Epic 1), the agent maki If conflicts are extensive, consider collapsing the stack — merge what you can into `main` and rebuild the remaining Epics from there. +### Keeping Epic Branches in Sync with Main + +If `main` advances while a stack is in progress (e.g., hotfixes or other PRs merge), periodically rebase the bottom Epic branch onto `main` and propagate upward through the stack. Do this between Sprints or at natural breakpoints — not while story agents are actively working. A long-diverged Epic branch will produce painful conflicts at merge time. + ### Story and Sprint Organization Within an Epic -The Epic branch is an **integration branch** — it accumulates completed stories. Agents do not work directly on the Epic branch. Instead, each agent works in its own story worktree that branches from the Epic branch. +The Epic branch accumulates completed stories. Agents do not work directly on the Epic branch. Instead, each agent works in its own story worktree that branches from the Epic branch. **Sprint-level organization:** @@ -533,7 +519,7 @@ Epics are typically broken into Sprints, each containing a set of stories. Withi - **Dependent Sprints** (Sprint 2 stories require Sprint 1 output) — run sequentially. Merge all Sprint 1 stories into the Epic branch before Sprint 2 agents branch from it. ```text -Epic 1 branch (integration) +Epic 1 branch ├── Sprint 1 (parallel agents) │ ├── Agent 1 → S-1.1 worktree │ ├── Agent 2 → S-1.2 worktree @@ -546,7 +532,7 @@ Epic 1 branch (integration) └── Epic PR → targets parent Epic branch or main ``` -**Story worktree naming convention:** +**Story worktree naming convention** (extends the general convention in [Worktree Naming Convention](#worktree-naming-convention) with an Epic prefix): ```text .worktrees/-- @@ -565,6 +551,27 @@ Stories can be integrated via direct merge or via short-lived PRs targeting the | **Direct merge** (`git merge`) | Small team, high trust, fast iteration | | **Story PRs** (PR targeting Epic branch) | Larger team, want per-story review before integration | +Direct merge commands (run from the Epic branch worktree): + +```bash +# Fetch and merge a completed story +git checkout epic-1/foundation +git fetch origin epic-1/S-1.1-data-model +git merge origin/epic-1/S-1.1-data-model +git push origin epic-1/foundation +``` + +If a story branch has fallen behind the Epic branch (e.g., other stories merged first), rebase it before merging. Run this from within the story worktree: + +```bash +git fetch origin epic-1/foundation +git rebase origin/epic-1/foundation +# resolve any conflicts, push, then merge into the Epic branch +git push --force-with-lease +``` + +**Story worktree cleanup:** Remove story worktrees and branches immediately after they are merged into the Epic branch — do not wait for the Epic PR to merge into `main`. + Either way, the Epic-level PR in the stack is the final gate for review and CI before merging into the parent Epic or `main`. ### Combining Stacked Epics with Parallel Agents From cd39f53e72aa65457552907139e7d96134bddd5e Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Sun, 29 Mar 2026 13:26:20 -0700 Subject: [PATCH 7/9] Revise multi-agent isolation guidelines in AGENTS.md Clarified rules for branching and pull requests in multi-agent environments. --- AGENTS.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9b56669..37fced5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -242,8 +242,6 @@ 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, 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. --- @@ -258,8 +256,8 @@ Never have two agents working in the same working directory simultaneously. 1. **One workspace per agent.** Every agent performing code changes MUST operate in its own isolated workspace (git worktree, container, or ephemeral environment). This applies to Claude Code (`isolation: "worktree"` or `--worktree`), Cursor parallel agents, GitHub Copilot coding agent, OpenAI Codex, and any other AI agent tool. 2. **One agent per story/task.** Each workspace maps to exactly one BMAD story, feature, or bug fix. Do not assign the same story to multiple agents. 3. **No overlapping file ownership.** Two agents MUST NOT modify the same file concurrently. If stories touch shared files (e.g., a shared type definition, config, or lockfile), serialize those stories — do not run them in parallel. This is the single most important rule for multi-agent work. -4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic Development](#stacked-prs-for-epic-development)). Outside a stacked-Epic workflow, workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when (a) Epics are part of a declared stack and the child Epic branches from its parent Epic's branch, or (b) story worktrees/branches are created from the Epic integration branch as defined in the stacked-PR workflow. -5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. (In a stacked-Epic workflow, story worktrees may optionally produce short-lived PRs targeting the Epic branch for review — these are internal integration PRs, not standalone feature PRs.) +4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic Development](#stacked-prs-for-epic-development)). Outside a stacked-Epic/Feature workflow, workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when (a) Epics/Features are part of a declared stack and the child Epic/Feature branches from its parent Epic/Feature's branch, or (b) story worktrees/branches are created from the Epic/Feature integration branch as defined in the stacked-PR workflow. +5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. (In a stacked-Epic/Feature workflow, story worktrees may optionally produce short-lived PRs targeting the Epic branch for review — these are internal integration PRs, not standalone feature PRs.) 6. **3–5 parallel agents max.** Coordination overhead increases non-linearly. Limit concurrent agents to 3–5 per repository. ### Detecting File Overlap From f9b6de310269efd1b2d7f3079edfc49245bb17d7 Mon Sep 17 00:00:00 2001 From: DJ Date: Sun, 29 Mar 2026 13:32:28 -0700 Subject: [PATCH 8/9] Treat Epic and Feature as interchangeable using Epic/Feature label MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates all generic/conceptual references throughout the stacked PR section to use "Epic/Feature" — section headings, rules, workflow steps, checklists, tables, and internal anchor links. Concrete example names (Epic 1, epic-1/foundation) remain unchanged as illustrative instances. Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 122 +++++++++++++++++++++++++++--------------------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 37fced5..959dad5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -256,8 +256,8 @@ Never have two agents working in the same working directory simultaneously. 1. **One workspace per agent.** Every agent performing code changes MUST operate in its own isolated workspace (git worktree, container, or ephemeral environment). This applies to Claude Code (`isolation: "worktree"` or `--worktree`), Cursor parallel agents, GitHub Copilot coding agent, OpenAI Codex, and any other AI agent tool. 2. **One agent per story/task.** Each workspace maps to exactly one BMAD story, feature, or bug fix. Do not assign the same story to multiple agents. 3. **No overlapping file ownership.** Two agents MUST NOT modify the same file concurrently. If stories touch shared files (e.g., a shared type definition, config, or lockfile), serialize those stories — do not run them in parallel. This is the single most important rule for multi-agent work. -4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic Development](#stacked-prs-for-epic-development)). Outside a stacked-Epic/Feature workflow, workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when (a) Epics/Features are part of a declared stack and the child Epic/Feature branches from its parent Epic/Feature's branch, or (b) story worktrees/branches are created from the Epic/Feature integration branch as defined in the stacked-PR workflow. -5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. (In a stacked-Epic/Feature workflow, story worktrees may optionally produce short-lived PRs targeting the Epic branch for review — these are internal integration PRs, not standalone feature PRs.) +4. **Branch from the default branch** — unless using a stacked PR workflow (see [Stacked PRs for Epic/Feature Development](#stacked-prs-for-epicfeature-development)). Outside a stacked-Epic/Feature workflow, workspaces MUST branch from the repository's configured default branch (for example, `origin/main`). You MAY use `origin/HEAD` as a shortcut when it is correctly configured, but MUST NOT rely on it being present. Never branch from another agent's branch **except** when (a) Epics/Features are part of a declared stack and the child Epic/Feature branches from its parent Epic/Feature's branch, or (b) story worktrees/branches are created from the Epic/Feature integration branch as defined in the stacked-PR workflow. +5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes. (In a stacked-Epic/Feature workflow, story worktrees may optionally produce short-lived PRs targeting the Epic/Feature branch for review — these are internal integration PRs, not standalone feature PRs.) 6. **3–5 parallel agents max.** Coordination overhead increases non-linearly. Limit concurrent agents to 3–5 per repository. ### Detecting File Overlap @@ -369,11 +369,11 @@ Before launching parallel agents, verify: --- -## Stacked PRs for Epic Development +## Stacked PRs for Epic/Feature Development -When a project has multiple Epics with **sequential dependencies** — where Epic 2 builds on the foundation laid by Epic 1, Epic 3 extends Epic 2, and so on — the standard "branch from main" model forces each Epic to wait for the previous Epic's PR to fully merge before work can begin. Stacked PRs eliminate this bottleneck by letting each Epic's branch build on the previous Epic's branch, forming a chain that merges bottom-up. +When a project has multiple Epics/Features with **sequential dependencies** — where Epic 2 builds on the foundation laid by Epic 1, Epic 3 extends Epic 2, and so on — the standard "branch from main" model forces each Epic/Feature to wait for the previous one's PR to fully merge before work can begin. Stacked PRs eliminate this bottleneck by letting each Epic/Feature's branch build on the previous one's branch, forming a chain that merges bottom-up. -Each Epic produces a **single PR** containing all of that Epic's stories. The stack is a chain of Epic-level PRs: +Each Epic/Feature produces a **single PR** containing all of its stories. The stack is a chain of Epic/Feature-level PRs: ```text main ← Epic-1-PR ← Epic-2-PR ← Epic-3-PR ← Epic-4-PR @@ -381,7 +381,7 @@ main ← Epic-1-PR ← Epic-2-PR ← Epic-3-PR ← Epic-4-PR ### How It Works -Each Epic gets one long-lived **Epic branch** (also called its integration branch). Multiple agents work stories concurrently in separate worktrees that branch from the Epic branch, then merge their completed stories back into it. The Epic branch accumulates all story work and becomes one PR in the stack. +Each Epic/Feature gets one long-lived **Epic/Feature branch** (also called its integration branch). Multiple agents work stories concurrently in separate worktrees that branch from the Epic/Feature branch, then merge their completed stories back into it. The Epic/Feature branch accumulates all story work and becomes one PR in the stack. | PR | Source branch | Target branch | |----|---------------|---------------| @@ -392,20 +392,20 @@ Each Epic gets one long-lived **Epic branch** (also called its integration branc When Epic 1's PR merges into `main`, Epic 2's PR is retargeted to `main`, and so on up the stack. -### Rules for Stacked Epic PRs +### Rules for Stacked Epic/Feature PRs -1. **One PR per Epic.** Each Epic produces exactly one PR. All stories within the Epic are merged into the Epic's integration branch. -2. **Stacks are strictly linear.** No branching within a stack (no diamond or tree shapes). One parent Epic, one child Epic. -3. **Maximum stack depth: 4 Epics.** Deeper stacks become fragile and painful to rebase. If a project has more than 4 sequential Epics, look for opportunities to merge intermediate Epics before continuing. -4. **Parallel agents within an Epic.** Multiple agents CAN work on stories within the same Epic concurrently — each in its own worktree branching from the Epic branch. The standard multi-agent isolation rules apply: no two agents modify the same file. Story worktrees merge back into the Epic branch when complete. -5. **Sprints within an Epic may overlap.** If Sprint 2's stories are independent of Sprint 1's stories, agents may work on both sprints concurrently. Only serialize sprints when later stories depend on earlier ones. -6. **Independent Epic stacks CAN run in parallel.** If your project has two separate dependency chains (e.g., Epics A1→A2 and Epics B1→B2), run those stacks concurrently with separate agents. The standard multi-agent isolation rules apply — no overlapping file ownership across stacks. -7. **File ownership within a stack is cumulative.** Files touched by Epic 1 may also be touched by Epic 2 (that's the nature of sequential dependency). Ensure agents in the child Epic coordinate with the parent Epic's completed state. -8. **Bottom-up merge order is mandatory.** Always merge the bottom Epic PR first, then retarget the next Epic PR to `main`, and so on. Never merge out of order. +1. **One PR per Epic/Feature.** Each Epic/Feature produces exactly one PR. All stories within it are merged into its branch. +2. **Stacks are strictly linear.** No branching within a stack (no diamond or tree shapes). One parent, one child. +3. **Maximum stack depth: 4.** Deeper stacks become fragile and painful to rebase. If a project has more than 4 sequential Epics/Features, look for opportunities to merge intermediate ones before continuing. +4. **Parallel agents within an Epic/Feature.** Multiple agents CAN work on stories within the same Epic/Feature concurrently — each in its own worktree branching from the Epic/Feature branch. The standard multi-agent isolation rules apply: no two agents modify the same file. Story worktrees merge back into the Epic/Feature branch when complete. +5. **Sprints within an Epic/Feature may overlap.** If Sprint 2's stories are independent of Sprint 1's stories, agents may work on both sprints concurrently. Only serialize sprints when later stories depend on earlier ones. +6. **Independent stacks CAN run in parallel.** If your project has two separate dependency chains (e.g., A1→A2 and B1→B2), run those stacks concurrently with separate agents. The standard multi-agent isolation rules apply — no overlapping file ownership across stacks. +7. **File ownership within a stack is cumulative.** Files touched by Epic 1 may also be touched by Epic 2 (that's the nature of sequential dependency). Ensure agents in the child Epic/Feature coordinate with the parent's completed state. +8. **Bottom-up merge order is mandatory.** Always merge the bottom PR first, then retarget the next PR to `main`, and so on. Never merge out of order. ### Workflow — Planning the Stack -Before any agent starts, the orchestrator (human or planning agent) identifies the Epic dependency order and documents the stack plan: +Before any agent starts, the orchestrator (human or planning agent) identifies the Epic/Feature dependency order and documents the stack plan: ```markdown ## Project Stack Plan @@ -415,11 +415,11 @@ Before any agent starts, the orchestrator (human or planning agent) identifies t 4. Epic 4 — Polish: UI refinements, error handling, docs (base → Epic 3) ``` -Each Epic should list its stories, and the plan should call out which files/modules each Epic owns. +Each Epic/Feature should list its stories, and the plan should call out which files/modules each one owns. ### Workflow — Implementing the Stack -**Step 1: Create the Epic integration branch.** The orchestrator (or first agent) creates the Epic branch from its parent: +**Step 1: Create the Epic/Feature branch.** The orchestrator (or first agent) creates the branch from its parent: ```bash # Epic 1 branches from main @@ -431,7 +431,7 @@ git push -u origin epic-1/foundation gh pr create --base main --title "Epic 1: Foundation" --body "..." --draft ``` -**Step 2: Agents work stories in parallel worktrees.** Each agent creates a story worktree branching from the Epic branch: +**Step 2: Agents work stories in parallel worktrees.** Each agent creates a story worktree branching from the Epic/Feature branch: ```bash # Agent 1 — Story S-1.1 @@ -446,9 +446,9 @@ git worktree add .worktrees/S-1.3-db-schema -b epic-1/S-1.3-db-schema origin/epi Each agent implements its story, runs quality checks, and pushes. -**Step 3: Merge stories back into the Epic branch.** As stories complete, merge them into the Epic branch. See [Story and Sprint Organization Within an Epic](#story-and-sprint-organization-within-an-epic) for merge strategies and commands. +**Step 3: Merge stories back into the Epic/Feature branch.** As stories complete, merge them into the Epic/Feature branch. See [Story and Sprint Organization Within an Epic/Feature](#story-and-sprint-organization-within-an-epicfeature) for merge strategies and commands. -**Step 4: Create the next Epic branch.** Once all stories that the next Epic depends on have been merged into the previous Epic branch, create the next Epic: +**Step 4: Create the next Epic/Feature branch.** Once all stories that the next Epic/Feature depends on have been merged into the previous branch, create the next one: ```bash # Epic 2 branches from Epic 1 @@ -460,7 +460,7 @@ gh pr create --base epic-1/foundation --title "Epic 2: Core Features" --body ".. Agents then work Epic 2's stories in parallel worktrees branching from `epic-2/core-features`, following the same pattern. -**Step 5: Repeat** for each subsequent Epic in the stack. +**Step 5: Repeat** for each subsequent Epic/Feature in the stack. ### Workflow — Merging the Stack @@ -482,9 +482,9 @@ Agents then work Epic 2's stories in parallel worktrees branching from `epic-2/c 4. **Review and merge Epic 2** → `main`. Repeat for Epic 3, Epic 4, etc. -### Workflow — Handling Changes to a Lower Epic PR +### Workflow — Handling Changes to a Lower Epic/Feature PR -If a reviewer requests changes to a lower Epic PR (e.g., Epic 1), the agent making fixes MUST propagate changes upward: +If a reviewer requests changes to a lower Epic/Feature PR (e.g., Epic 1), the agent making fixes MUST propagate changes upward: 1. Make the fix on Epic 1's branch and push. 2. For each child branch in order, rebase onto the updated parent: @@ -499,22 +499,22 @@ If a reviewer requests changes to a lower Epic PR (e.g., Epic 1), the agent maki 3. Repeat for Epic 3 if it exists (rebasing onto Epic 2's updated branch), and so on. -If conflicts are extensive, consider collapsing the stack — merge what you can into `main` and rebuild the remaining Epics from there. +If conflicts are extensive, consider collapsing the stack — merge what you can into `main` and rebuild the remaining Epics/Features from there. -### Keeping Epic Branches in Sync with Main +### Keeping Epic/Feature Branches in Sync with Main -If `main` advances while a stack is in progress (e.g., hotfixes or other PRs merge), periodically rebase the bottom Epic branch onto `main` and propagate upward through the stack. Do this between Sprints or at natural breakpoints — not while story agents are actively working. A long-diverged Epic branch will produce painful conflicts at merge time. +If `main` advances while a stack is in progress (e.g., hotfixes or other PRs merge), periodically rebase the bottom Epic/Feature branch onto `main` and propagate upward through the stack. Do this between Sprints or at natural breakpoints — not while story agents are actively working. A long-diverged Epic/Feature branch will produce painful conflicts at merge time. -### Story and Sprint Organization Within an Epic +### Story and Sprint Organization Within an Epic/Feature -The Epic branch accumulates completed stories. Agents do not work directly on the Epic branch. Instead, each agent works in its own story worktree that branches from the Epic branch. +The Epic/Feature branch accumulates completed stories. Agents do not work directly on the Epic/Feature branch. Instead, each agent works in its own story worktree that branches from it. **Sprint-level organization:** -Epics are typically broken into Sprints, each containing a set of stories. Within a Sprint, all stories with no file overlap can be worked in parallel by separate agents. Across Sprints: +Epics/Features are typically broken into Sprints, each containing a set of stories. Within a Sprint, all stories with no file overlap can be worked in parallel by separate agents. Across Sprints: - **Independent Sprints** (no data/API dependency between them) — run concurrently. -- **Dependent Sprints** (Sprint 2 stories require Sprint 1 output) — run sequentially. Merge all Sprint 1 stories into the Epic branch before Sprint 2 agents branch from it. +- **Dependent Sprints** (Sprint 2 stories require Sprint 1 output) — run sequentially. Merge all Sprint 1 stories into the Epic/Feature branch before Sprint 2 agents branch from it. ```text Epic 1 branch @@ -522,15 +522,15 @@ Epic 1 branch │ ├── Agent 1 → S-1.1 worktree │ ├── Agent 2 → S-1.2 worktree │ └── Agent 3 → S-1.3 worktree -│ (all merge back into Epic branch) +│ (all merge back into Epic/Feature branch) ├── Sprint 2 (parallel agents, after Sprint 1 merges) │ ├── Agent 1 → S-1.4 worktree │ └── Agent 2 → S-1.5 worktree -│ (merge back into Epic branch) -└── Epic PR → targets parent Epic branch or main +│ (merge back into Epic/Feature branch) +└── Epic/Feature PR → targets parent branch or main ``` -**Story worktree naming convention** (extends the general convention in [Worktree Naming Convention](#worktree-naming-convention) with an Epic prefix): +**Story worktree naming convention** (extends the general convention in [Worktree Naming Convention](#worktree-naming-convention) with an Epic/Feature prefix): ```text .worktrees/-- @@ -540,16 +540,16 @@ Branch name: `/-` Examples: `epic-1/S-1.1-data-model`, `epic-2/S-2.3-auth-middleware` -**Merging stories back into the Epic branch:** +**Merging stories back into the Epic/Feature branch:** -Stories can be integrated via direct merge or via short-lived PRs targeting the Epic branch: +Stories can be integrated via direct merge or via short-lived PRs targeting the Epic/Feature branch: | Method | When to use | |--------|-------------| | **Direct merge** (`git merge`) | Small team, high trust, fast iteration | -| **Story PRs** (PR targeting Epic branch) | Larger team, want per-story review before integration | +| **Story PRs** (PR targeting Epic/Feature branch) | Larger team, want per-story review before integration | -Direct merge commands (run from the Epic branch worktree): +Direct merge commands (run from the Epic/Feature branch worktree): ```bash # Fetch and merge a completed story @@ -559,63 +559,63 @@ git merge origin/epic-1/S-1.1-data-model git push origin epic-1/foundation ``` -If a story branch has fallen behind the Epic branch (e.g., other stories merged first), rebase it before merging. Run this from within the story worktree: +If a story branch has fallen behind the Epic/Feature branch (e.g., other stories merged first), rebase it before merging. Run this from within the story worktree: ```bash git fetch origin epic-1/foundation git rebase origin/epic-1/foundation -# resolve any conflicts, push, then merge into the Epic branch +# resolve any conflicts, push, then merge into the Epic/Feature branch git push --force-with-lease ``` -**Story worktree cleanup:** Remove story worktrees and branches immediately after they are merged into the Epic branch — do not wait for the Epic PR to merge into `main`. +**Story worktree cleanup:** Remove story worktrees and branches immediately after they are merged into the Epic/Feature branch — do not wait for the Epic/Feature PR to merge into `main`. -Either way, the Epic-level PR in the stack is the final gate for review and CI before merging into the parent Epic or `main`. +Either way, the Epic/Feature-level PR in the stack is the final gate for review and CI before merging into the parent or `main`. -### Combining Stacked Epics with Parallel Agents +### Combining Stacked Epics/Features with Parallel Agents Stacked PRs and parallel agents operate at different levels and are fully complementary: | Level | Parallelism | Constraint | |-------|-------------|------------| -| **Across independent Epic chains** | Full parallel — separate stacks run concurrently | No file overlap between chains | -| **Across Epics in the same stack** | Sequential — child Epic starts after parent Epic branch is stable | Child branches from parent | -| **Within an Epic (across Sprints)** | Parallel if Sprints are independent; sequential if dependent | Dependent Sprints wait for prior Sprint to merge into Epic branch | +| **Across independent Epic/Feature chains** | Full parallel — separate stacks run concurrently | No file overlap between chains | +| **Across Epics/Features in the same stack** | Sequential — child starts after parent branch is stable | Child branches from parent | +| **Within an Epic/Feature (across Sprints)** | Parallel if Sprints are independent; sequential if dependent | Dependent Sprints wait for prior Sprint to merge into Epic/Feature branch | | **Within a Sprint** | Full parallel — multiple agents, one story each | No file overlap between stories | -Example — a project with two Epic chains and six agents: +Example — a project with two Epic/Feature chains and six agents: -| Agent | Chain | Epic | Sprint | Story | Branch base | Status | +| Agent | Chain | Epic/Feature | Sprint | Story | Branch base | Status | |-------|-------|------|--------|-------|-------------|--------| | Agent 1 | A | Epic 1 | Sprint 1 | S-1.1 (data model) | `epic-1/foundation` | Active | | Agent 2 | A | Epic 1 | Sprint 1 | S-1.2 (core types) | `epic-1/foundation` | Active (parallel) | | Agent 3 | A | Epic 1 | Sprint 1 | S-1.3 (db schema) | `epic-1/foundation` | Active (parallel) | | Agent 4 | B | Epic 3 | Sprint 1 | S-3.1 (auth) | `epic-3/auth` | Active (parallel, different chain) | | Agent 5 | B | Epic 3 | Sprint 1 | S-3.2 (sessions) | `epic-3/auth` | Active (parallel) | -| Agent 6 | A | Epic 2 | — | — | `epic-1/foundation` | Waiting (parent Epic incomplete) | +| Agent 6 | A | Epic 2 | — | — | `epic-1/foundation` | Waiting (parent incomplete) | Once Agents 1–3 merge their stories into `epic-1/foundation`, Agent 6 can begin Epic 2's stories. Meanwhile, Agents 4–5 continue independently on Chain B. ### Stack Coordination Checklist -Before starting a stacked Epic workflow, verify: -- [ ] Epics have genuine sequential dependencies (not just conceptual ordering) -- [ ] Stack depth is 4 or fewer Epics -- [ ] Stack plan is documented with Epic order, parent relationships, and Sprint breakdown -- [ ] Each Epic's file/module ownership is identified — no overlap across parallel stacks -- [ ] Within each Epic, stories are assigned to Sprints with file overlap analysis complete +Before starting a stacked Epic/Feature workflow, verify: +- [ ] Epics/Features have genuine sequential dependencies (not just conceptual ordering) +- [ ] Stack depth is 4 or fewer +- [ ] Stack plan is documented with Epic/Feature order, parent relationships, and Sprint breakdown +- [ ] Each Epic/Feature's file/module ownership is identified — no overlap across parallel stacks +- [ ] Within each Epic/Feature, stories are assigned to Sprints with file overlap analysis complete - [ ] Stories within each Sprint have no file overlap (safe for parallel agents) -- [ ] Dependent Sprints are clearly marked — they wait for prior Sprint to merge into Epic branch -- [ ] Stories within each Epic are scoped and ready for implementation (BMAD artifacts complete) -- [ ] No more than 3–5 agents are running concurrently across all active Epics in the repository +- [ ] Dependent Sprints are clearly marked — they wait for prior Sprint to merge into Epic/Feature branch +- [ ] Stories within each Epic/Feature are scoped and ready for implementation (BMAD artifacts complete) +- [ ] No more than 3–5 agents are running concurrently across all active Epics/Features in the repository ### Tooling Notes -- **GitHub natively supports stacked PRs** — each PR targets a non-default base branch. The PR diff shows only the changes introduced by that Epic, not the full stack. +- **GitHub natively supports stacked PRs** — each PR targets a non-default base branch. The PR diff shows only the changes introduced by that Epic/Feature, not the full stack. - **`gh` CLI** supports `--base` for targeting parent branches and `gh pr edit --base` for retargeting after merges. - **Graphite, git-town, and spr** are dedicated stacked PR tools that automate rebasing and retargeting. Consider adopting one if stacks become a frequent workflow. - **CI runs on each PR independently.** Ensure CI is configured to run against the PR's base branch, not just `main`. Most CI systems (GitHub Actions, etc.) handle this correctly by default. -- **PR review is incremental.** Reviewers see only the diff between the Epic branch and its parent — not the entire stack. This keeps reviews focused and manageable. +- **PR review is incremental.** Reviewers see only the diff between the Epic/Feature branch and its parent — not the entire stack. This keeps reviews focused and manageable. --- From 77220f17d54b89a121235860815689e5ad54f477 Mon Sep 17 00:00:00 2001 From: DJ Date: Sun, 29 Mar 2026 13:34:12 -0700 Subject: [PATCH 9/9] Clarify enforce_admins impact on branch protection Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 959dad5..5bafdfb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -242,6 +242,7 @@ 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. +- With `enforce_admins` enabled, even repository administrators cannot bypass required status checks, including SonarCloud quality gates. All PRs must pass CI before merging. ---