Add stacked PR strategy and Epic-level workflow guidance#5
Merged
Conversation
…ghts 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) <noreply@anthropic.com>
Clarified primary languages used in the project.
- 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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAGENTS.md is significantly expanded and restructured to add Project Context, Git Workflow, Development Environment preflight, CI/Branch Protection & SonarCloud guidance, Multi-Repo Orchestration, relaxed stacked Epic/Feature branching rules, a detailed Stacked PRs workflow, and a required per-repo docs template. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the organization-wide AGENTS.md standards to add Epic-level stacked PR workflow guidance and expand existing multi-agent/worktree operational rules to cover branching, environment preflights, and CI/branch-protection expectations.
Changes:
- Added new sections for Project Context, Git workflow guardrails, and Development Environment preflight checks.
- Expanded CI/branch-protection guidance (SonarCloud, required check name mismatches, admin merge constraints).
- Introduced a comprehensive “Stacked PRs for Epic Development” workflow and updated multi-agent branching rule(s) to reference it.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
AGENTS.md (1)
609-615:⚠️ Potential issue | 🟠 MajorAdd an explicit required template for dev/test/run commands and env vars.
This section only tells repos to document commands/env vars, but does not provide a concrete required structure in this standards file. Please add a mandatory template/checklist block so repo-level docs remain consistent and auditable.
Proposed doc patch
## Agent Operation Guidance @@ - 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. +- 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/README MUST include a section similar to: + + ```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 + - `ANOTHER_VAR`: purpose, allowed values, example + ```As per coding guidelines: "Document project-specific dev/test/run commands and required environment variables in the repo's AGENTS.md or README".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 609 - 615, Add a mandatory template/checklist block under "Agent Operation Guidance" in AGENTS.md that enforces a consistent repo-level section titled "Local Development Commands" and a "Required Environment Variables" subsection; include required fields for Install, Dev run, Test, Lint, and Typecheck commands and for each env var list the variable name, purpose, allowed values, and an example so repo authors must fill them out (use the proposed headings "Local Development Commands" and "Required Environment Variables" as the canonical section titles to locate and standardize the content).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 380-383: The markdown fences in the workflow examples (the block
containing "main ← Epic-1-PR ← Epic-2-PR ← Epic-3-PR ← Epic-4-PR", the bash
examples used inside ordered steps like the gh/git snippets, and the blocks
showing tree and path like "Epic 1 branch (integration) …" and
".worktrees/<epic-id>-<story-id>-<description>") need markdownlint fixes: add a
language identifier (use "text" for ASCII diagrams and "bash" for shell
snippets) on each opening fence and ensure there is a blank line before and
after fenced blocks that are inside ordered list items (e.g., the gh pr edit and
git rebase snippets) so MD040 and MD031 are satisfied; update every occurrence
referenced (the diagram block, the bash command blocks, and the tree/path
blocks) to use the appropriate ```text or ```bash and include the required
surrounding blank lines.
---
Outside diff comments:
In `@AGENTS.md`:
- Around line 609-615: Add a mandatory template/checklist block under "Agent
Operation Guidance" in AGENTS.md that enforces a consistent repo-level section
titled "Local Development Commands" and a "Required Environment Variables"
subsection; include required fields for Install, Dev run, Test, Lint, and
Typecheck commands and for each env var list the variable name, purpose, allowed
values, and an example so repo authors must fill them out (use the proposed
headings "Local Development Commands" and "Required Environment Variables" as
the canonical section titles to locate and standardize the content).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
- 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) <noreply@anthropic.com>
- 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) <noreply@anthropic.com>
Clarified rules for branching and pull requests in multi-agent environments.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 242-245: Update the "Branch Protection & SonarCloud" section to
expand the explanation of enforce_admins: add a concise sentence after the
existing text (under the "Branch Protection & SonarCloud" heading) stating that
with enforce_admins enabled repository administrators cannot bypass required CI
checks or merge without satisfying branch protection rules (e.g., required
SonarCloud checks and approvals), and briefly note any consequences for agent
workflows such as needing PRs to pass checks before merge.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
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) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
main ← Epic-1-PR ← Epic-2-PR ← ...) that merges bottom-upenforce_adminsimpact on CI requirementsAlso includes prior commits: workflow/environment guidance, multi-repo orchestration rules, and review comment fixes.
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit