diff --git a/AGENTS.md b/AGENTS.md index bd0e843..d5d5f13 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. - 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 --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/-- +``` + +Branch name: `/-` + +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: `` + - Dev run: `` + - Test: `` + - Lint: `` + - Typecheck (if applicable): `` + + ## Required Environment Variables + - `VAR_NAME`: purpose, allowed values, example + ``` ---