Add stacked PR strategy and Epic-level workflow guidance

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.
 - 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 +259,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.** 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.
-5. **One PR per workspace.** Each workspace produces exactly one pull request. Do not combine unrelated changes.
+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
@@ -371,12 +372,275 @@ Before launching parallel agents, verify:
 
 ---
 
+## Stacked PRs for Epic/Feature Development
+
+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/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
+```
+
+### How It Works
+
+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 |
+|----|---------------|---------------|
+| 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/Feature PRs
+
+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/Feature 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/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/Feature branch.** The orchestrator (or first agent) creates the 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/Feature 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/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/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
+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/Feature 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 <epic-2-PR-number> --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/Feature PR
+
+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:
+
+   ```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/Features from there.
+
+### 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/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/Feature
+
+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/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/Feature branch before Sprint 2 agents branch from it.
+
+```text
+Epic 1 branch
+├── 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/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/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/Feature prefix):
+
+```text
+.worktrees/<epic-id>-<story-id>-<description>
+```
+
+Branch name: `<epic-id>/<story-id>-<description>`
+
+Examples: `epic-1/S-1.1-data-model`, `epic-2/S-2.3-auth-middleware`
+
+**Merging stories back into the Epic/Feature 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/Feature branch) | Larger team, want per-story review before integration |
+
+Direct merge commands (run from the Epic/Feature 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/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/Feature branch
+git push --force-with-lease
+```
+
+**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/Feature-level PR in the stack is the final gate for review and CI before merging into the parent or `main`.
+
+### 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/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/Feature chains and six agents:
+
+| 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 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/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/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/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/Feature 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.
 - 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: `<install command>`
+  - Dev run: `<dev command>`
+  - Test: `<test command>`
+  - Lint: `<lint command>`
+  - Typecheck (if applicable): `<typecheck command>`
+
+  ## Required Environment Variables
+  - `VAR_NAME`: purpose, allowed values, example
+  ```
 
 ---