docs: Local Guardrails analysis consolidated into Issue #230#246
Conversation
Add Phase 0 (Memory Initialization) and Phase 9 (Memory Storage) to ensure reviewer signal quality stats are loaded before triage and stored after completion. This prevents stale data and enables cross-session learning. Changes: - Phase 0: Load pr-comment-responder-skills and reviewer-specific memories - Phase 9: Calculate session stats and update memory before completion - Update cumulative stats with PR #89 data: - cursor[bot]: 11/11 (100%) across #32, #47, #52, #89 - Copilot: 7/12 (58%) across #32, #47, #52, #89 - coderabbitai[bot]: 3/6 (50%) across #32, #47, #52 This addresses user feedback that stats should be kept up to date as work progresses, with mandatory memory operations in the workflow protocol. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Zero review comments - workflow executed cleanly
Add Phase 0 (Memory Initialization) as BLOCKING gate: - Load reviewer signal quality statistics from pr-comment-responder-skills memory - Load cursor-bot-review-patterns memory - Load copilot-pr-review-patterns memory - Verification gate before Phase 1 can proceed Add Phase 9 (Memory Storage) as REQUIRED before completion: - Update reviewer statistics after processing - Store session metrics to memory - Add new PR entry to breakdown section - Update protocol statistics table Update cumulative statistics with PR #89 data: - cursor[bot]: 4 PRs, 11/11 actionable (100%) - Copilot: 4 PRs, 7/12 actionable (58%) - coderabbitai[bot]: 2 PRs, 3/6 actionable (50%) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…nder Add mandatory memory initialization (Phase 0) and storage (Phase 9) to pr-comment-responder protocol. These phases were lost in merge conflict resolution (026b29d) but remain strategically valuable per ADR-007. Changes: - Phase 0 (BLOCKING): Load pr-comment-responder-skills before triage - Phase 9 (BLOCKING): Update reviewer stats after session completion - Renumber workflow from 8 phases (1-8) to 10 phases (0-9) - Complete Session 57 log (was awaiting user decision) - Add Session 58 log documenting restoration implementation Context: - Original commit 536ccce added Phase 0/9 with stale stats (through PR #89) - Merge conflict chose main's versions (current through PR #212) - Session 58 restored Phase 0/9 while preserving main's current data Reviewer statistics (via main merge, current through PR #212): - cursor[bot]: 100% actionable (10/10 comments) - Copilot: 50% actionable (5/10 comments) - coderabbitai[bot]: 50% actionable (3/6 comments) Closes Quality Gate CRITICAL_FAIL (Analyst agent PR description mismatch) Closes Session Protocol FAIL (3 MUST requirements in Session 57) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Session 57 evidence was forward-looking ('will be done in Session 58')
which violated Session Protocol requirements. Updated to show actual
completion evidence from Session 58 (commit aeb6284, lint results).
Session Protocol validator correctly identified: 'Protocol requires
these be completed in current session before claiming completion.'
Evidence now shows:
- HANDOFF.md Updated: Session 58 updated this log with decision
- Markdown Lint: Session 58 ran lint: 0 errors on 138 files
- Changes Committed: Session 58 commit aeb6284 includes this completion
Closes Session Protocol MUST failures (3 → 0)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Addresses PR #199 review comments from @Copilot - Fix circular dependency in Phase 0 Step 0.2 - Add deferred execution note clarifying Step 0.2 executes after Step 1.2 - Resolves architectural issue preventing protocol execution - Add verification checklist to Phase 9 Step 9.4 - Implement Copilot's suggested verification steps - Enables proper Phase 9 completion verification - Add regex pattern clarification - Document lookahead pattern with alternative if unsupported - Prevents potential runtime issues with Serena MCP - Fix session log reviewer classification - Correct copilot-pull-request-reviewer from Human to Bot - Ensures factual accuracy in historical records Comment-IDs: 2638131860, 2638131870, 2638131876, 2638131883
…nder-memory-protocol
Addresses PR #199 review comments from @Copilot (post-merge batch) - Fix PR description statistics mismatch - Update table to match pr-comment-responder-skills memory - cursor[bot]: 4 PRs, 11 comments, 100% (was incorrectly 5 PRs, 10 comments) - Copilot: 4 PRs, 12 comments, 58% (was incorrectly 5 PRs, 10 comments, 50%) - coderabbitai: 3 PRs, 6 comments (was incorrectly 4 PRs) - Resolves: Memory file shows PRs #32, #47, #52, #89 not #212 - Fix normalization logic documentation - Replace algorithmic transformation with manual mapping example - Clarify memory names follow project conventions - Resolves: Code example produced wrong names (copilot_pull_request_reviewer vs copilot-pr-review-patterns) - Fix Session 58 commit SHA references - Correct all references from 97c4988 to aeb6284 (actual commit) - Update 3 occurrences in session log - Resolves: Temporal impossibility (Session 57 referencing non-existent future commit) Comment-IDs: 2638147436, 2638147439, 2638147443 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Addresses review comments from @rjmurillo and @Copilot: - Delete .agents/pr-description-updated.md (out of place) - Update Session 58 status to 'Complete - Awaiting CI verification' - Update Session 57 status to 'Complete - Handed off to Session 58' - Fix Copilot historical signal note with accurate context Comment-IDs: 2639072478, 2638177941, 2638177946, 2638177956
Resolved conflicts by taking main's versions: - src/claude/pr-comment-responder.md: Phase 0/9 changes need to go through template - .serena/memories/pr-comment-responder-skills.md: Main has more comprehensive stats
…plate Addresses @rjmurillo comment: changes to src/claude/pr-comment-responder.md need corresponding changes in templates and regeneration. Added to templates/agents/pr-comment-responder.shared.md: - Phase 0: Memory Initialization (BLOCKING) - Step 0.1: Load Core Skills Memory - Step 0.2: Load Reviewer-Specific Memories (deferred after Step 1.2) - Step 0.3: Verify Memory Loaded - Phase 9: Memory Storage (BLOCKING) - Step 9.1: Calculate Session Statistics - Step 9.2: Update pr-comment-responder-skills Memory - Step 9.3: Update Required Fields - Step 9.4: Verify Memory Updated Regenerated via build/Generate-Agents.ps1: - src/copilot-cli/pr-comment-responder.agent.md - src/vs-code-agents/pr-comment-responder.agent.md Comment-ID: 2639082373
Session 58-PR199 log marked HANDOFF.md Updated as complete but evidence said "Will update after CI verification" which is deferred intent, not actual completion. The validator correctly flagged this as a MUST violation. Changes: - Update HANDOFF.md Session History with PR #199 session entries - Fix Session 58-PR199 evidence column to show actual HANDOFF.md update - Add Session 62 log documenting this validation fix Resolves: Session Protocol CRITICAL_FAIL (1 MUST requirement not met) Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Verdict: APPROVED WITH CONCERNS (85% confidence) Key findings: - P1: FR-2 "major changes" threshold needs definition - P1: FR-4 scope boundary and approval gate required - P2: Success metric baseline clarity needed (n=8 sample) - P2: Rollback strategy missing for high false positive rate Strengths: - Evidence-based requirements (8 PR analysis) - Phased implementation with clear dependencies - Proper infrastructure reuse (Validate-SessionEnd.ps1) Blocking items before Phase 2 implementation: 1. Define "major changes" quantifiable threshold 2. Add FR-4 explicit scope boundary 3. Answer validation sequencing question 4. Document ignore file format Artifacts: - .agents/critique/051-local-guardrails-critique.md - .agents/sessions/2025-12-22-session-63-guardrails-critique.md Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated session log with canonical Session End checklist from SESSION-PROTOCOL.md for validation compliance. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Added Starting Commit field for docs-only detection - Marked QA as SKIPPED for docs-only session - Added spec and plan files that were being reviewed Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
14-agent review identified 70-80% overlap between Local Guardrails plan and Issue #230 "[P1] Implement Technical Guardrails for Autonomous Agent Execution". Key findings from multi-agent review: - 8 agents: APPROVED_WITH_CONCERNS - 4 agents: NEEDS_REVISION - 2 agents: SIMPLIFY/CONSOLIDATE Unique elements preserved as Issue #230 sub-tasks: - Test coverage detection (Detect-TestCoverageGaps.ps1) - PR description validation (Validate-PRDescription.ps1) Files: - .agents/specs/SPEC-local-guardrails.md: Status → CONSOLIDATED - .agents/planning/PLAN-local-guardrails.md: Status → CONSOLIDATED - .agents/sessions/2025-12-22-session-67-guardrails-synthesis.md: Synthesis - .agents/HANDOFF.md: Session 67 entry added 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Code Review
This pull request updates the pr-comment-responder agent documentation across three files to include new phases for memory initialization (Phase 0) and storage (Phase 9). The changes are consistent and well-documented. All original feedback comments have been retained as they align with the provided rules, which clarify that duplication of .agent.md files is intentional and that the comments themselves do not contradict any guidelines. My feedback focuses on improving adherence to the repository's style guide, particularly regarding the use of RFC 2119 keywords, and enhancing the clarity and maintainability of a code example.
There was a problem hiding this comment.
Pull request overview
This PR documents a comprehensive 14-agent review process of the Local Guardrails initiative (Sessions 62-67), which ultimately determined 70-80% overlap with existing Issue #230. The work has been consolidated to avoid duplication, with unique elements (test coverage detection, PR description validation) preserved for future implementation. Additionally, it updates pr-comment-responder agent templates to add Phase 0 (Memory Initialization) and Phase 9 (Memory Storage) for improved memory-driven workflows.
Key Changes
- Added Phase 0 and Phase 9 to pr-comment-responder agent templates for mandatory memory operations before and after workflow execution
- Documented 6 sessions (62-67) covering the Local Guardrails analysis, critique, and consolidation process
- Created SPEC and PLAN documents marked as CONSOLIDATED into Issue #230
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
templates/agents/pr-comment-responder.shared.md |
Added Phase 0 (Memory Initialization) and Phase 9 (Memory Storage) sections with detailed memory operation workflows |
src/vs-code-agents/pr-comment-responder.agent.md |
Same Phase 0/9 additions for VS Code agent variant |
src/copilot-cli/pr-comment-responder.agent.md |
Same Phase 0/9 additions for Copilot CLI agent variant |
.agents/specs/SPEC-local-guardrails.md |
Local Guardrails specification marked as CONSOLIDATED into Issue #230 |
.agents/planning/PLAN-local-guardrails.md |
Implementation plan marked as CONSOLIDATED into Issue #230 |
.agents/sessions/2025-12-22-session-67-guardrails-synthesis.md |
Final synthesis session documenting consolidation decision |
.agents/sessions/2025-12-22-session-66-guardrails-explainer-review.md |
Explainer agent review session (incomplete) |
.agents/sessions/2025-12-22-session-65-guardrails-analyst-critique.md |
Analyst critique session (incomplete) |
.agents/sessions/2025-12-22-session-64-guardrails-task-validation.md |
Task validation session (incomplete, duplicate session ID) |
.agents/sessions/2025-12-22-session-64-guardrails-premortem.md |
Pre-mortem analysis session (incomplete, duplicate session ID) |
.agents/sessions/2025-12-22-session-63-guardrails-critique.md |
Critic review session documenting initial APPROVED WITH CONCERNS verdict |
.agents/sessions/2025-12-22-session-62-pr199-validation-fix.md |
CI fix session for PR #199 validation issues |
.agents/sessions/2025-12-21-session-58-pr199-implementation.md |
PR #199 implementation session restoring Phase 0/9 content |
.agents/sessions/2025-12-21-session-57-pr199-quality-gate-response.md |
Quality gate response analysis for PR #199 |
.agents/sessions/2025-12-21-session-56-pr199-review.md |
Initial PR #199 review session |
.agents/qa/001-session-67-guardrails-synthesis.md |
QA validation report confirming documentation-only changes |
.agents/critique/051-local-guardrails-critique.md |
Comprehensive critique with blocking items identified |
.agents/analysis/065-local-guardrails-critical-analysis.md |
Critical analysis identifying duplicate work and evidence quality concerns |
.agents/HANDOFF.md |
Updated with Sessions 56-58, 62-63, and 67 (missing 64-66) |
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughAdds 20+ documentation artifacts for Local Guardrails (spec, plan, multiple session logs, critiques, analyses, QA, handoff) and updates agent templates and responder docs. Replaces "MANDATORY" → "MUST", adds Resolve Conversation Thread flow, memory-storage steps, Phase 4.5 Copilot follow‑up handling, and a pre‑push session-protocol validation gate. No production code changes. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Richard Murillo <6811113+rjmurillo@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
.claude/skills/merge-resolver/SKILL.md (1)
121-173: Keep Step 7 checklist in lockstep with SESSION-PROTOCOL.mdYou now embed a full MUST checklist here while also telling people to copy from
SESSION-PROTOCOL.md; that’s a drift trap. Please verify this table exactly matches the canonical checklist (same rows, wording, and MUST/MUST NOT semantics) and either (a) treatSESSION-PROTOCOL.mdas the only source of truth and reference it, or (b) update both documents together going forward so CI and local guidance never diverge.src/claude/pr-comment-responder.md (1)
798-816: Unify Copilot follow-up PR handling into a single canonical flowPhase 4.5 now defines a BLOCKING Copilot follow-up pipeline (branch pattern + announcement + intent categorization), but the later “Copilot Behavior” section still has a different follow-up PR detection/close pattern. That split will drift and give mixed signals to agents. Recommend making Phase 4.5 the single source of truth (detection + decisions) and collapsing the Bot-Specific snippet into a short pointer back to Phase 4.5 so all three platforms stay aligned.
Also applies to: 1197-1215
templates/agents/pr-comment-responder.shared.md (1)
723-816: Eliminate duplicated Copilot follow-up logic in the shared templateThis template now defines a full Phase 4.5 Copilot follow-up flow (branch pattern + announcement + DUPLICATE/SUPPLEMENTAL/INDEPENDENT decisions) and still keeps an older “Handling unnecessary follow-up PRs” snippet under Bot-Specific Copilot Behavior. Because this file drives both Copilot CLI and VS Code agents, the two flows will drift and confuse implementers. Recommend consolidating on Phase 4.5 as the canonical follow-up process and trimming the Bot-Specific section down to a short pointer to Phase 4.5 so all three agents stay synchronized.
Also applies to: 1197-1215
📜 Review details
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (10)
.agents/analysis/001-merge-resolver-session-protocol-gap.mdis excluded by!.agents/analysis/**.agents/sessions/2025-12-22-session-63-guardrails-critique.mdis excluded by!.agents/sessions/**.agents/sessions/2025-12-22-session-64-guardrails-premortem.mdis excluded by!.agents/sessions/**.agents/sessions/2025-12-22-session-64a-guardrails-task-validation.mdis excluded by!.agents/sessions/**.agents/sessions/2025-12-22-session-65-guardrails-analyst-critique.mdis excluded by!.agents/sessions/**.agents/sessions/2025-12-22-session-66-guardrails-explainer-review.mdis excluded by!.agents/sessions/**.agents/sessions/2025-12-22-session-67-guardrails-synthesis.mdis excluded by!.agents/sessions/**.agents/sessions/2025-12-27-session-68-template-sync-check-analysis.mdis excluded by!.agents/sessions/**.serena/memories/merge-resolver-auto-resolvable-patterns.mdis excluded by!.serena/memories/**.serena/memories/merge-resolver-session-protocol-gap.mdis excluded by!.serena/memories/**
📒 Files selected for processing (6)
.agents/qa/063-session-63-guardrails-critique-qa.md.claude/skills/merge-resolver/SKILL.mdsrc/claude/pr-comment-responder.mdsrc/copilot-cli/pr-comment-responder.agent.mdsrc/vs-code-agents/pr-comment-responder.agent.mdtemplates/agents/pr-comment-responder.shared.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .agents/qa/063-session-63-guardrails-critique-qa.md
🧰 Additional context used
📓 Path-based instructions (67)
**/*.md
📄 CodeRabbit inference engine (.agents/architecture/ADR-001-markdown-linting.md)
**/*.md: Add language identifiers to all fenced code blocks (MD040). Use appropriate language identifiers:csharpfor C#,powershellfor PowerShell,bashfor shell,jsonfor JSON,yamlfor YAML,markdownfor Markdown,textfor plain text or generic/pseudo code
Wrap generic types in backticks to escape angle brackets (e.g.,ArrayPool<T>instead of ArrayPool) to comply with MD033 inline HTML restrictions and ensure proper rendering
Add blank lines around code blocks to comply with MD031 markdown linting requirements
Add blank lines around lists to comply with MD032 markdown linting requirements
Add blank lines around headings to comply with MD022 markdown linting requirements
Use ATX-style headings (# Heading) consistently across all markdown documents (MD003)
Use fenced code block style (triple backticks) consistently, with backtick delimiters rather than tildes (MD046, MD048)
Allow only specific HTML elements in markdown:<br>,<kbd>,<sup>,<sub>. Escape or avoid other inline HTML elements to comply with MD033 restrictions
**/*.md: Always specify language identifiers on fenced code blocks for syntax highlighting in markdown documentation
Add blank lines before and after code blocks, lists, and headings in markdown documents
Detect and repair malformed code fence closings where closing fences have language identifiers (e.g.,text) instead of plain closing fences ()
**/*.md: Runmarkdownlint --fixbefore manual edits to auto-resolve spacing violations (MD031/MD032/MD022)
Usetextfor pseudo-code and tool invocations, and use specific language identifiers (json, csharp, bash, yaml, markdown) for actual code in MD040 code blocks
Wrap .NET generic types likeArrayPool<T>,Span<T>,Vector256in backticks to prevent MD033 inline HTML violations in C# documentationFix malformed markdown code fence closings by ensuring closing fences never include language identifiers (use
instead oflanguage)Use HTML comment...
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
⚙️ CodeRabbit configuration file
**/*.md: Writing Quality: - Grade 9 reading level - Active voice, direct address - Short sentences (under 15 words ideal) - No fluff, filler, or marketing language - Replace adjectives with data where possible - Every sentence must pass the "so what" test
Flag: - Passive voice - Vague language (nearly, some, almost, very) - Jargon without definitions - Broken links and outdated procedures - Inconsistency with code changes in same PR - Missing context for new features or APIs
Ignore (handled by .markdownlint-cli2.yaml): - Markdown formatting and style - Heading level choices - Link formatting variations - Minor punctuation preferencesDocumentation Review Criteria ### P0 (Must Fix) - Absolute paths - Broken internal links ### P1 (Should Fix) - Missing heading hierarchy - Code blocks without language ### Skip - Markdown linting (markdownlint-cli2 handles) Prefix all comments with: [P0], [P1], or [P2]
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
templates/agents/**/*.shared.md
📄 CodeRabbit inference engine (.agents/analysis/drift-analysis-claude-vs-templates.md)
templates/agents/**/*.shared.md: Restore exact Core Identity text from Claude agents - do not rewrite or expand Core Identity sections in template files
Add Claude Code Tools section or equivalent capabilities section listing available tools (Read/Grep/Glob, Write/Edit, WebSearch, cloudmcp-manager) to all agent definitions
Preserve Execution Mindset format as Think/Act/Create or Think/Act/Decide - do not introduce alternative formats like Think/Act/Challenge/Document without Claude source alignment
Preserve Handoff Options targets from Claude source - do not add or remove handoff targets without validation against Claude source of truth
Keep template-specific additions to agent definitions (constraints sections, handoff protocols, expanded frameworks, review criteria tables) - these are valuable enhancements but should be evaluated for back-porting to Claude source
Document 'When to Use' guidance for each agent describing appropriate use cases and scenarios where agent should be invokedUse
.shared.mdnaming convention to distinguish agent template sources from generated platform-specific outputsApply Phase 2 template-first workflow (modify templates/agents/*.shared.md first, run Generate-Agents.ps1, then verify) to all agent documentation changes across platforms
templates/agents/**/*.shared.md: Include required frontmatter fields in shared agent templates:description,tools_vscode, andtools_copilot
Include required sections in shared agent templates:# Agent Name,## Core Identity,## Core Mission,## Key Responsibilities,## Constraints,## Memory protocol,## Output Format, and## Handoff Protocol
Configure platform-specific tools in agent template frontmatter:tools_vscodefor VS Code/GitHub Copilot tools,tools_copilotfor Copilot CLI toolsAfter running build/Generate-Agents.ps1 to regenerate platform-specific agents from templates, verify regeneration with `git diff templates/agents/ src/copilot-cli/ src/vs-code-agents/...
Files:
templates/agents/pr-comment-responder.shared.md
{templates/agents/**/*.shared.md,src/vs-code-agents/**/*.agent.md,src/claude/**/*.md}
📄 CodeRabbit inference engine (.agents/analysis/drift-analysis-claude-vs-templates.md)
Standardize Memory Protocol syntax using platform variables - Claude format: mcp__cloudmcp-manager__memory-, Templates format: cloudmcp-manager/memory-
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.md
{build/Generate-Agents.ps1,templates/agents/*.shared.md,build/scripts/*.ps1}
📄 CodeRabbit inference engine (.agents/architecture/2-variant-consolidation-review.md)
Generate agent files using PowerShell build script (build/Generate-Agents.ps1) from templates in templates/agents/*.shared.md with platform-specific configurations
Files:
templates/agents/pr-comment-responder.shared.md
templates/agents/*.shared.md
📄 CodeRabbit inference engine (.agents/planning/tasks-agent-consolidation.md)
Shared agent source files should be named with
.shared.mdextension and located intemplates/agents/, using placeholder syntax like {{PLATFORM_MODEL}} and {{PLATFORM_TOOLS}} for platform-specific valuesUpdate shared templates before regenerating platform agents to ensure consistency across multiple platforms (copilot-cli, vs-code)
templates/agents/*.shared.md: Store shared agent sources intemplates/agents/[agent-name].shared.mdformat
Shared agent sources MUST include a header comment indicating it is a source file
Shared agent sources MUST use placeholder syntax (e.g.,{{PLATFORM_TOOLS}},{{PLATFORM_MODEL}}) for platform-specific valuesUse
templates/agents/*.shared.mdas the SOURCE OF TRUTH for shared agent definitions
templates/agents/*.shared.md: After any modification to templates/agents/.shared.md or platforms/.yaml files, regenerate all platform files using 'pwsh build/Generate-Agents.ps1' and commit template files and generated files (src/vs-code-agents/, src/copilot-cli/) together atomically
Each shared agent template (agents/*.shared.md) must include frontmatter with: description, argument-hint, tools_vscode array, and tools_copilot array. Required content sections include: Core Identity, Activation Profile, Core Mission, Key Responsibilities, Constraints, Memory protocol, and Handoff Options
Files:
templates/agents/pr-comment-responder.shared.md
**/*.{sh,py,js,ts,bash}*(@(agent|comment|pr|review))*
📄 CodeRabbit inference engine (.agents/retrospective/047-pr-comment-handling.md)
Use
gh api repos/OWNER/REPO/pulls/PR/comments -X POST -F in_reply_to=ID -f body=TEXTfor thread-preserving responses to review comments
Files:
templates/agents/pr-comment-responder.shared.md
**/*pr-comment-responder*.{md,txt,prompt}*
📄 CodeRabbit inference engine (.agents/retrospective/047-pr-comment-handling.md)
Add GitHub API reference section to pr-comment-responder prompt with review comment endpoint patterns and common errors
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
templates/agents/**/*.md
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-16-phase3-consistency-validation.md)
Agent document changes must go through templates then Generate-Agents.ps1 to maintain consistency
Changes to
templates/agents/**/*.mdMUST executepwsh build/Generate-Agents.ps1to regenerate platform-specific agents and port changes to corresponding agents insrc/claude/**/*.md
Files:
templates/agents/pr-comment-responder.shared.md
**/{templates/agents/*.shared.md,**/agents/!(node_modules)/**/*.md,src/claude/*.md}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-16-phase4-handoff-validation.md)
Include 'Validation Failure' subsection in all handoff checklists to prevent incomplete handoffs
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.md
**/{templates/agents/*.shared.md,**/agents/*.md,src/claude/*.md}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-16-phase4-handoff-validation.md)
Handoff validation must cover Pass, Failure, and Special scenarios (e.g., approval/revision/escalation for critic, completion/blocker/security-flagged for implementer, pass/failure/infrastructure for qa, task breakdown/estimate reconciliation/scope concern for task-generator)
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.md
**/*.{md,json,yml,yaml,ps1,sh,bash,toml,ini,cfg,config,txt}
📄 CodeRabbit inference engine (.agents/retrospective/phase1-remediation-pr43.md)
Use relative paths only in documentation and configuration files; avoid absolute paths (e.g., C:\ on Windows) to prevent environment contamination and maintain cross-platform portability
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{md,markdown}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-17-session-failures.md)
Do not include auto-generated headers in generated files
Run markdown lint on session logs and documentation before committing
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{ps1,yml,yaml,md}
📄 CodeRabbit inference engine (.agents/analysis/003-session-protocol-skill-gate.md)
Validate skill availability before implementing GitHub operations - Check if
.claude/skills/github/directory exists and contains the required capability; list available GitHub skill scripts; read theskill-usage-mandatorymemory; document available skills in session log; use existing skills if they exist rather than writing inline code
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{md,js,ts,tsx,jsx,json,yaml,yml,sh,ps1}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-18-serena-memory-reference-migration.md)
Search entire codebase for pattern before migration to identify all references
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{md,js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-18-serena-memory-reference-migration.md)
Include fallback clause when migrating to tool calls for graceful degradation
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{md,ts,tsx,js,jsx,py}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-18-session-17-retrospective.md)
For features, add new sections rather than refactoring existing logic
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{src/claude/**/*.md,templates/agents/**/*.md,src/copilot-cli/**/*.md,src/vs-code-agents/**/*.md}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-self-contained-agents-skills.md)
{src/claude/**/*.md,templates/agents/**/*.md,src/copilot-cli/**/*.md,src/vs-code-agents/**/*.md}: Agent files ship as independent units - embed requirements, documentation, and guidelines directly in agent files rather than referencing external files. Do not reference external style guides or requirement files (e.g., src/STYLE-GUIDE.md) in agent files, as agents are copied to end-user machines (~/.claude/, ~/.copilot/, ~/.vscode/) without source tree access.
Before committing agent file changes, validate that all file references in the agent resolve from deployment locations, not just from the source repository root.
Test agent files in isolation before committing to verify they function without access to the source tree or external dependencies.
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{src/claude/**/*.md,templates/agents/**/*.md,src/copilot-cli/**/*.md,src/vs-code-agents/**/*.md,**/*.config.json,**/*.config.yaml,**/*.config.yml}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-self-contained-agents-skills.md)
Before creating file references in agent files, configs, or scripts, verify that the referenced path exists at the deployment location (~/.claude/, ~/.copilot/, ~/.vscode/), not just in the source tree repository root.
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{src/claude/**,templates/agents/**,src/copilot-cli/**,src/vs-code-agents/**}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-self-contained-agents-skills.md)
When planning agent enhancements, include all four platforms in scope: Claude agents (src/claude/, ~18 files), agent templates (templates/agents/, ~18 files), copilot-cli agents (src/copilot-cli/, ~18 files), and VS Code agents (src/vs-code-agents/, ~18 files). Agent changes typically affect 72 files minimum across all platforms.
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{src/claude/**,templates/agents/**,src/copilot-cli/**,src/vs-code-agents/**,**/*.config.json,**/*.config.yaml,**/*.config.yml}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-self-contained-agents-skills.md)
Apply DRY (Don't Repeat Yourself) principle with an exception for deployment units (agents, configs, etc.): Files that ship to end-user machines must be self-contained. Embed content instead of referencing external files, prioritizing portability over DRY adherence for these files.
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/{src/claude,templates/agents,src/copilot-cli,src/vs-code-agents}/**
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-self-contained-agents.md)
**/{src/claude,templates/agents,src/copilot-cli,src/vs-code-agents}/**: Agent files ship as independent units - embed requirements and documentation, do not reference external files
Before creating file references in agent files, verify the path exists at deployment location (e.g., ~/.claude/, ~/.copilot/, ~/.vscode/), not just in source tree
Agent modifications must be applied consistently across all platforms: Claude agents (src/claude/), templates (templates/agents/), copilot-cli (src/copilot-cli/), and vs-code-agents (src/vs-code-agents/) - minimum scope is 72 files (4 platforms × 18 agents)
Apply DRY (Don't Repeat Yourself) principle except for deployment units - embed requirements directly in agent files and configuration files for portability instead of referencing external files
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/{src/claude,templates/agents,src/copilot-cli,src/vs-code-agents,{*.json,*.yaml,*.yml,*.config}}/**
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-self-contained-agents.md)
Before creating file references in any deployment unit (agents, configs, scripts), validate deployment context by checking path resolution from end-user machine locations, not from repository root
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{js,ts,ps1,py,json,yaml,yml,md}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-skill-extraction-summary.md)
Use identical syntax for all instances when migrating patterns to maintain consistency
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*pr-comment-responder*
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-20-pr-94-acknowledgment-failure.md)
**/*pr-comment-responder*: Phase 3 BLOCKED until eyes reaction count equals comment count (mandatory step verification before phase completion)
Session log tracks 'NEW this session' separately from 'DONE prior sessions' to prevent conflating prior work with current session obligations
Do not use thread RESOLVED status as a completion signal; verify actual step execution via API endpoints instead
GitHub API verification checklist must be executed before generating completion summaries (prevent false success claims)
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{templates/agents/**/*.shared.md,src/vs-code-agents/**/*.agent.md,src/copilot-cli/**/*.agent.md}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Edit shared agent templates in
templates/agents/with.shared.mdextension to define agent behavior; do not edit generated files directly insrc/vs-code-agents/orsrc/copilot-cli/
Files:
templates/agents/pr-comment-responder.shared.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{md,txt}
📄 CodeRabbit inference engine (.agents/pr-batch-review-session-2025-12-20.md)
Use consistent MCP acronym terminology in documentation (Copilot review feedback)
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{src,templates}/**/*.{md,mdx}
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-20-pr-212-comment-response.md)
Exclude internal PR/Issue/Session references (e.g., PR #XX, Issue #XX, Session XX) from user-facing documentation in src/ and templates/ directories
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/{src/claude,agents}/*.md
📄 CodeRabbit inference engine (.agents/architecture/ADR-013-agent-orchestration-mcp.md)
Assign default models per agent according to the model assignment table: orchestrator/implementer/analyst/architect/others use sonnet; high-level-advisor/independent-thinker/security/roadmap use opus
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.md
{**/*.md,.serena/**}
📄 CodeRabbit inference engine (.agents/qa/002-pr-201-skills-clarity-fixes.md)
Provide concrete examples when documenting MCP tool naming conventions - include breakdown of server name and tool-id components
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/{SESSION-PROTOCOL,*-PROTOCOL,*.md}
📄 CodeRabbit inference engine (.agents/archive/HANDOFF-2025-12-22.md)
Use RFC 2119 keywords (MUST, SHOULD, MAY) in protocol documentation and enforcement mechanisms
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/!(node_modules)/**/*.{md,yml,json}
📄 CodeRabbit inference engine (.agents/archive/HANDOFF-2025-12-22.md)
Use
mcp__serena__read_memorytool calls instead of direct file path references in instructional documentation
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{md,yml,yaml}
📄 CodeRabbit inference engine (.agents/analysis/156-pr-review-analysis.md)
Fix GitHub Actions template syntax: Use
${{ }}instead of@{{ }}for template variables (e.g.,${{ github.event.pull_request.user.login }})
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{sh,bash,md}
📄 CodeRabbit inference engine (.agents/sessions/2025-12-23-session-84-pr308-review-comments.md)
**/*.{sh,bash,md}: Bash script arguments containing special characters (e.g.,-f description) must be properly quoted to prevent shell interpretation errors
Bash variables should use lowercase naming conventions to distinguish user variables from shell built-ins
Hardcoded file paths in Bash scripts should use~or$HOMEvariable instead of absolute paths for portability
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*.{md,json,yml,yaml,ps1}
📄 CodeRabbit inference engine (.agents/devops/SHIFT-LEFT.md)
Use forward slashes (/) for path separators in all documentation and configuration files for cross-platform compatibility
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/pr-comment-responder.*
📄 CodeRabbit inference engine (.agents/architecture/dual-path-strategy.md)
For pr-comment-responder and all GitHub operation integrations, use the dual-path skill routing mechanism instead of direct PowerShell or bash calls
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{templates/agents/**,src/copilot-cli/**,src/vscode/**}
📄 CodeRabbit inference engine (.agents/planning/github-actions-failures-remediation-plan.md)
Regenerate platform-specific agent files in
src/copilot-cli/andsrc/vscode/usingGenerate-Agents.ps1after modifying template files intemplates/agents/
Files:
templates/agents/pr-comment-responder.shared.mdsrc/copilot-cli/pr-comment-responder.agent.md
{src/claude/**/*.md,templates/agents/**/*.md,src/copilot-cli/**/*.agent.md,src/vs-code-agents/**/*.agent.md}
📄 CodeRabbit inference engine (.agents/sessions/2025-12-23-session-63-pr199-comment-response.md)
Template changes in src/claude must be synchronized with templates/agents and regenerated for all three platforms (claude, copilot-cli, vs-code-agents)
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
{src/claude/**/*.md,templates/agents/**/*.md}
📄 CodeRabbit inference engine (.agents/devops/PR-235-devops-review.md)
Changes to
src/claude/**/*.md(Claude Code agents) MUST be independently reimplemented intemplates/agents/**/*.mdand maintain separate but synchronized content during the tri-template migration period
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.md
{src/claude/**/*.md,templates/agents/**/*.shared.md}
📄 CodeRabbit inference engine (.agents/devops/PR-235-devops-review.md)
Changes to agent implementation files (
src/claude/*.mdortemplates/agents/*.shared.md) must be documented in agent capabilities with examples of new switch usage and behavior distinctions
Files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.md
.claude/skills/*/SKILL.md
📄 CodeRabbit inference engine (.agents/analysis/004-check-skill-exists-tool.md)
SKILL.md documentation files must include examples of correct skill usage (using skills) vs incorrect patterns (inline gh commands), plus clear taxonomy of operation types and naming conventions
.claude/skills/*/SKILL.md: Add Framework Limitations section to SKILL.md documenting what Claude Code cannot do automatically (e.g., trigger automatically based on file creation, trigger based on tool output parsing, run in background/parallel)
Document actual skill invocation mechanisms in SKILL.md, not aspirational behavior: specify whether skill is invoked via explicit user command, orchestrator routing with detection patterns, or BLOCKING gate enforcement
Files:
.claude/skills/merge-resolver/SKILL.md
.claude/skills/**/SKILL.md
📄 CodeRabbit inference engine (.agents/critique/2025-12-21-mcp-prd-review.md)
.claude/skills/**/SKILL.md: SKILL.md files for executable skills MUST includereplaces_commandmetadata field as a required field, enforced via schema validation and pre-commit hooks
All skill definition SKILL.md files must specify required parameters inreplaces_commandmetadata for exact parameter matching in blocking gatesAll executable skills MUST include
replaces_commandmetadata field in SKILL.md files - enforce via pre-commit hook and schema validationAgent documentation in SKILL.md files must be updated with usage examples reflecting new features and distinguish between different comment types (review vs issue comments)
Files:
.claude/skills/merge-resolver/SKILL.md
.claude/skills/**/*
📄 CodeRabbit inference engine (.agents/specs/skill-catalog-mcp-spec.md)
Executable skills are located in .claude/skills/ directory with naming pattern of subdirectory/SKILL.md and associated scripts in subdirectory/scripts/
Files:
.claude/skills/merge-resolver/SKILL.md
**/.claude/skills/**/*.md
📄 CodeRabbit inference engine (.agents/architecture/ADR-016-addendum-skills-pattern.md)
Document skill capabilities by listing available MCP tools with their parameters and usage patterns in skill documentation
Files:
.claude/skills/merge-resolver/SKILL.md
.claude/**/*.md
📄 CodeRabbit inference engine (.agents/analysis/pr-quality-gate-320c2b3-analysis.md)
Document workflow state transitions (e.g., NEW → ACKNOWLEDGED → REPLIED → RESOLVED) for comment lifecycle models
Files:
.claude/skills/merge-resolver/SKILL.md
**/.claude/skills/**/SKILL.md
📄 CodeRabbit inference engine (.agents/critique/PR-400-refactor-validation.md)
Extracted skill functions should be documented with comprehensive reference documentation in corresponding SKILL.md file including function signatures, parameters, and usage examples
Files:
.claude/skills/merge-resolver/SKILL.md
**/pr-comment-responder.md
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-14-pr-comment-responder-gaps.md)
**/pr-comment-responder.md: In pr-comment-responder.md Phase 1, add explicit reviewer enumeration with paginated comment retrieval and total comment count verification
In pr-comment-responder.md Phase 2, add guidance that each review comment must be analyzed independently and not aggregated by file path
In pr-comment-responder.md Phase 3, add completion verification step to compare addressed_count vs total_comments before claiming done
In pr-comment-responder.md Phase 3, add examples for using review reply endpoint (gh api pulls/comments/{id}/replies) for thread-preserving responses vs issue comments
Files:
src/claude/pr-comment-responder.md
src/**/*.md
📄 CodeRabbit inference engine (.agents/analysis/ideation-agent-templating.md)
Document that generated agent files should have headers indicating they are auto-generated artifacts to prevent accidental manual editing
Use atomic commits (one commit per task) with conventional commit format (type: description) for agent documentation changes
Update all cross-references to skills in agent definitions from numeric skill IDs (Skill-Domain-NNN) to semantic slugs
Files:
src/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
src/claude/**/*.{py,ts,tsx,js,jsx,md}
📄 CodeRabbit inference engine (src/claude/CLAUDE.md)
Use the Task tool with
subagent_typeparameter to invoke specialized agents (analyst, architect, planner, critic, implementer, qa, explainer, task-generator, high-level-advisor, independent-thinker, memory, skillbook, retrospective, devops, roadmap, security, pr-comment-responder, or orchestrator)
Files:
src/claude/pr-comment-responder.md
src/claude/{analyst,critic,devops,explainer,planner,pr-comment-responder,qa,retrospective,task-generator}.md
📄 CodeRabbit inference engine (.agents/architecture/ADR-002-agent-model-selection-optimization.md)
Update the
model:field fromopustosonnetin agent configuration files: analyst, critic, devops, explainer, planner, pr-comment-responder, qa, retrospective, and task-generator
Files:
src/claude/pr-comment-responder.md
src/claude/**/*.{md,ts,tsx}
📄 CodeRabbit inference engine (.agents/retrospective/phase3-p2-learnings.md)
When modifying agent documentation in src/claude/, verify if templates/agents/ need the same updates before committing
Files:
src/claude/pr-comment-responder.md
src/claude/**/*.md
📄 CodeRabbit inference engine (.agents/README.md)
Implement steering injection pattern for agent prompt files in src/claude/ by loading agent-prompts.md steering guidance
Follow existing agent prompt patterns found in
src/claude/when creating new agent specifications
src/claude/**/*.md: Use agent prompt naming convention:[agent-name].md(lowercase, hyphenated) for agent prompt files
Update agent prompts to reference applicable steering guidance in.agents/steering/and note that orchestrator injects relevant steering based on task scopeValidate agent prompts for consistency when making changes to agent implementations
Agent prompt files should reference steering guidance from
.agents/steering/directory based on the context of the file being worked onMaintain
src/claude/**/*.mddocumentation independently from generated sources, with a dual-flow pattern where changes in either location must be ported to the otherClaude agents use Task(subagent_type=...) syntax for handoffs; VS Code/Copilot CLI agents use runSubagent(...) syntax
Files:
src/claude/pr-comment-responder.md
⚙️ CodeRabbit configuration file
src/claude/**/*.md: ## Agent Prompt Review CriteriaP0 (Must Fix)
- Missing required Front Matter
- Model assignment violating ADR-002
- Absolute paths in documentation
P1 (Should Fix)
- Missing Core Identity section
- Drift from VS Code/Copilot CLI versions
Prefix all comments with: [P0] or [P1]Only comment when you have HIGH CONFIDENCE (>80%) that an issue exists.
Be concise: one sentence per comment when possible.
Focus on actionable feedback, not observations.
If uncertain whether something is an issue, do not comment.
Files:
src/claude/pr-comment-responder.md
{src/claude/**/*.md,.github/copilot-instructions.md}
📄 CodeRabbit inference engine (.agents/steering/agent-prompts.md)
{src/claude/**/*.md,.github/copilot-instructions.md}: Maintain prompt structure consistency in agent prompts
Ensure clear role definition in agent prompts
Define explicit responsibilities for agents in prompts
Use memory protocol consistently in agent prompts
Follow handoff format standards in agent prompts
Include front matter metadata in agent prompt files
Organize agent prompt content into consistent sections
Include delegation instructions in agent prompts
Specify output format requirements in agent prompts
Avoid ambiguous instructions in agent prompts
Ensure delegation logic is present and clear in agent prompts
Define clear success criteria for agent tasks in prompts
Use consistent terminology throughout agent prompts
Files:
src/claude/pr-comment-responder.md
**/claude/**/*.md
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-18-session-17-retrospective.md)
When updating agent workflows, modify both producer and consumer prompts to maintain symmetry
Files:
src/claude/pr-comment-responder.md
src/**/*.{md,agent.md}
📄 CodeRabbit inference engine (src/AGENTS.md)
All agents MUST follow STYLE-GUIDE.md for communication standards
Files:
src/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
src/claude/*.md
📄 CodeRabbit inference engine (src/AGENTS.md)
Claude Code CLI agent definitions use markdown format (.md files)
src/claude/*.md: Agent definitions in src/claude/*.md must specify role, specialization, default_model, delegates_to, and called_by metadata
Provide artifact_directory configuration in agent definitions when agents produce persistent artifacts (e.g., .agents/analysis/)
src/claude/*.md: Claude Code agents in src/claude/ are hand-maintained source files. Edit src/claude/{agent}.md for Claude-specific changes; DO NOT directly edit .claude/agents/ which is the installed runtime copy
Claude-specific changes (tool syntax, Claude Code features) should only modify src/claude/*.md without requiring template synchronization
Each Claude agent file must follow the required frontmatter structure: name, description, model (sonnet|opus|haiku), and argument-hint fields
Each Claude agent file must include all required sections: Core Identity, Activation Profile, Claude Code Tools, Core Mission, Key Responsibilities, Constraints, Memory protocol, Handoff Options, and Output Format
Claude agents must use MCP tool prefix syntax (mcp__cloudmcp-manager__memory-search_nodes) instead of path notation used by VS Code/Copilot agents
Claude agents must reference .claude/skills/github/ skill scripts (e.g., pwsh .claude/skills/github/scripts/pr/Get-PRContext.ps1) rather than raw gh commands
Files:
src/claude/pr-comment-responder.md
src/claude/pr-comment-responder.md
📄 CodeRabbit inference engine (.agents/sessions/2025-12-20-session-37-pr-94-retrospective.md)
src/claude/pr-comment-responder.md: Phase 3 BLOCKED until eyes reaction count equals comment count - do not mark Phase 3 complete without verifying that the number of eyes reactions on a PR comment matches the number of comments in the thread
Verify mandatory step completion via API before marking phase complete - do not mark a protocol phase as complete without using API verification (e.g., gh CLI or GitHub API) to confirm that required steps were actually executed
PowerShell script failure requires immediate gh CLI fallback attempt - if Add-CommentReaction.ps1 or any PowerShell script fails, immediately attempt the equivalent operation using gh CLI as a fallback before marking the step as failed
Files:
src/claude/pr-comment-responder.md
**/src/claude/*.md
📄 CodeRabbit inference engine (.agents/planning/PRD-agent-orchestration-mcp.md)
Agent prompt files (src/claude/*.md) MUST be parsed for front matter containing agent name, model, and description; MUST extract role from 'Core Identity' section and specialization from 'Specialization' section
Files:
src/claude/pr-comment-responder.md
**/vs-code-agents/pr-comment-responder.agent.md
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-14-pr-comment-responder-gaps.md)
Sync pr-comment-responder.md changes to vs-code-agents/pr-comment-responder.agent.md
Files:
src/vs-code-agents/pr-comment-responder.agent.md
src/{vs-code-agents,copilot-cli}/**/*.agent.md
📄 CodeRabbit inference engine (.agents/architecture/2-variant-consolidation-review.md)
src/{vs-code-agents,copilot-cli}/**/*.agent.md: Add a header comment to generated files to prevent accidental edits, following the format: '# AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY' with source file reference and generator script name
Ensure generated agent files in src/vs-code-agents/ and src/copilot-cli/ comply with markdown linting rules as defined in ADR-001Generated agent output files should have the
.agent.mdextension and be output to platform-specific directories (src/vs-code-agents/ for VS Code, src/copilot-cli/ for Copilot CLI)Generated agent files in
src/vs-code-agents/andsrc/copilot-cli/MUST be byte-identical to current manually-maintained files during migration phase
Files:
src/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
src/**/**.agent.md
📄 CodeRabbit inference engine (.agents/qa/001-agent-consolidation-test-strategy-review.md)
Verify all agent markdown files contain required sections: '## Core Identity', '## Core Mission', and '## Key Responsibilities'
Files:
src/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/*agent*.md
📄 CodeRabbit inference engine (.agents/planning/phase4-complete-handoff.md)
**/*agent*.md: Include 'Validation Failure' subsection in all handoff validation checklist sections within agent documentation
Handoff validation sections must cover Pass/Approval, Failure/Revision, and Special case scenarios
Files:
src/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
src/vs-code-agents/*.agent.md
📄 CodeRabbit inference engine (src/AGENTS.md)
VS Code / GitHub Copilot agent definitions use .agent.md file format
Files:
src/vs-code-agents/pr-comment-responder.agent.md
**/*.agent.md
📄 CodeRabbit inference engine (.agents/planning/prd-visual-studio-install-support.md)
Visual Studio agents must use the same .agent.md file format as VS Code agents with frontmatter containing name, description, tools, model, and target properties
Files:
src/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
src/vs-code-agents/**
📄 CodeRabbit inference engine (.agents/analysis/001-workflow-validation-shift-left-analysis.md)
Agent files must be generated using
./build/Generate-Agents.ps1 -Validateand cannot be manually edited. Agent drift detection uses./build/scripts/Detect-AgentDrift.ps1to ensure files match templates.
Files:
src/vs-code-agents/pr-comment-responder.agent.md
{src/vs-code-agents/**,src/copilot-cli/**}
📄 CodeRabbit inference engine (.agents/analysis/001-workflow-validation-shift-left-analysis.md)
Generated agent files in
src/vs-code-agents/andsrc/copilot-cli/must be generated from templates using./build/Generate-Agents.ps1 -Validateand must not contain manual edits.
Files:
src/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
**/copilot-cli/pr-comment-responder.agent.md
📄 CodeRabbit inference engine (.agents/retrospective/2025-12-14-pr-comment-responder-gaps.md)
Sync pr-comment-responder.md changes to copilot-cli/pr-comment-responder.agent.md
Files:
src/copilot-cli/pr-comment-responder.agent.md
src/copilot-cli/*.agent.md
📄 CodeRabbit inference engine (src/AGENTS.md)
GitHub Copilot CLI agent definitions use .agent.md file format
Files:
src/copilot-cli/pr-comment-responder.agent.md
🧠 Learnings (7)
📚 Learning: 2025-12-17T21:55:43.359Z
Learnt from: CR
Repo: rjmurillo/ai-agents PR: 0
File: .agents/retrospective/047-pr-comment-handling.md:0-0
Timestamp: 2025-12-17T21:55:43.359Z
Learning: Run QA agent after all implementer work, regardless of perceived fix complexity
Applied to files:
templates/agents/pr-comment-responder.shared.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
📚 Learning: 2025-12-16T06:26:21.783Z
Learnt from: rjmurillo
Repo: rjmurillo/ai-agents PR: 43
File: templates/agents/qa.shared.md:1-311
Timestamp: 2025-12-16T06:26:21.783Z
Learning: In the rjmurillo/ai-agents repository, follow the project's Markdown lint rules defined in .markdownlint-cli2.yaml. Do not flag MD031/MD032 (blank lines around fences) or similar style issues in Markdown files if the repository's markdownlint configuration passes; rely on the config to determine formatting and style decisions.
Applied to files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
📚 Learning: 2025-12-16T06:26:44.230Z
Learnt from: rjmurillo
Repo: rjmurillo/ai-agents PR: 43
File: templates/agents/implementer.shared.md:33-40
Timestamp: 2025-12-16T06:26:44.230Z
Learning: In the rjmurillo/ai-agents repository, markdownlint issues should be governed by the repository's .markdownlint-cli2.yaml configuration. Do not flag or enforce markdown formatting/style violations that are not surfaced by the configured rules. Apply this rule to all Markdown files (e.g., templates/agents/implementer.shared.md and others) and only flag issues that the project's markdownlint config would detect.
Applied to files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
📚 Learning: 2025-12-16T06:26:44.208Z
Learnt from: rjmurillo
Repo: rjmurillo/ai-agents PR: 43
File: templates/agents/planner.shared.md:73-121
Timestamp: 2025-12-16T06:26:44.208Z
Learning: In this repository (rjmurillo/ai-agents), do not flag Markdown formatting or style issues (MD031, MD032, heading levels, link formatting, punctuation) for Markdown files. These are already ignored by the project’s .markdownlint-cli2.yaml; rely on that configuration and the repository's coding guidelines for Markdown handling.
Applied to files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
📚 Learning: 2025-12-16T06:27:04.317Z
Learnt from: rjmurillo
Repo: rjmurillo/ai-agents PR: 43
File: src/copilot-cli/analyst.agent.md:39-44
Timestamp: 2025-12-16T06:27:04.317Z
Learning: In the rjmurillo/ai-agents repository, do not flag MD031 (blank lines around fenced code blocks) or MD032 (blank lines around lists) violations in Markdown files. These formatting rules are configured in the project’s .markdownlint-cli2.yaml, and such style issues do not affect agent instruction functionality. Apply this pattern to all Markdown files (recursively) and focus review attention on issues that affect behavior, correctness, or other lint rules.
Applied to files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
📚 Learning: 2025-12-16T08:00:20.752Z
Learnt from: rjmurillo
Repo: rjmurillo/ai-agents PR: 43
File: templates/agents/roadmap.shared.md:124-174
Timestamp: 2025-12-16T08:00:20.752Z
Learning: Review Markdown files to ensure nested code fences follow the rule: the outer fence uses more backticks than the inner fence (e.g., an outer `````` with four backticks containing an inner ```mermaid``` fence). This follows CommonMark conventions; verify that nesting does not break rendering by using a greater number of backticks for the outer fence than the inner one.
Applied to files:
templates/agents/pr-comment-responder.shared.mdsrc/claude/pr-comment-responder.mdsrc/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
📚 Learning: 2025-12-16T06:16:01.759Z
Learnt from: rjmurillo
Repo: rjmurillo/ai-agents PR: 43
File: build/Generate-Agents.ps1:513-519
Timestamp: 2025-12-16T06:16:01.759Z
Learning: In this repository, generated agent instruction files (e.g., src/vs-code-agents/*.agent.md, src/copilot-cli/*.agent.md) intentionally omit a 'DO NOT EDIT DIRECTLY' header because AI agents consume these files and human-oriented warnings add noise to their context. Do not manually edit these generated files. CI validation (validate-generated-agents.yml) enforces edits to them via the generator. The related generation script is build/Generate-Agents.ps1, which should be used to update these files, not manual edits.
Applied to files:
src/vs-code-agents/pr-comment-responder.agent.mdsrc/copilot-cli/pr-comment-responder.agent.md
🔍 Remote MCP DeepWiki
Here is a concise summary of relevant facts and concrete information to assist in effectively reviewing the given pull request, based on extensive repository context:
1. Pull Request Context & Objectives
- This PR documents and consolidates the Local Guardrails initiative into Issue #230, including the specification, plan, critiques, session logs, QA validation, and updates to agent templates for memory and session protocol.
- Classified as a documentation update with no code changes.
- Extensive multi-agent evaluation (~14 agents) found 70-80% overlap with Issue #230 and recommended consolidation while preserving uniquely valuable elements.
- Impacts session protocol enforcement, memory system usage, and CI/CD workflows.
2. Repository Architecture & Agent Ecosystem
- The AI Agents repository implements a multi-platform system (VS Code, GitHub Copilot CLI, Claude Code CLI) with 17 specialized agents coordinating via an orchestrator.
- Agents apply a strict session protocol with 5 blocking gates to ensure continuity and context preservation across sessions.
- Memory bridge concept: uses
.serena/memories/(file-based memory),.agents/sessions/(per-session logs), and.agents/HANDOFF.md(read-only dashboard) to solve context loss and merge conflict issues. - Agent outputs are organized into
.agents/subdirectories segmented by function (analysis, planning, critique, QA, etc.).
3. Session Protocol & Memory Management
- All agents, including those involved in Local Guardrails, must adhere to the session protocol:
- Block 1: Initialize Serena memory (activate project + load instructions).
- Block 2: Read
.agents/HANDOFF.mdfor prior context. - Block 3: Create session log in
.agents/sessions/. - Block 4: Complete session end checklist; update handoff reference.
- Block 5: Pass
Validate-SessionEnd.ps1validation script.
.agents/HANDOFF.mdis now read-only per ADR-014 (distributed handoff architecture).- Session logs hold session-specific state; memory files hold cross-session knowledge.
- Memory access and updates use MCP tools like
mcp__serena__write_memory,read_memory, and graph-basedmemory-search_nodes.
4. Local Guardrails Specification and Plan
- The Local Guardrails SPEC and PLAN documents included in the PR define guardrails to run local pre-PR validation checks to prevent AI quality gate violations.
- The plan outlines six phases, including pre-PR session validation, PR description validation, integration with session protocol, test coverage detection, and documentation update.
- New PowerShell scripts and hooks added to enforce protocol and validation steps locally.
- Consolidation aims to reduce duplicate efforts and leverage existing infrastructure and scripts, referencing Issue #230.
5. CI/CD & Automation Workflows
- AI-driven workflows automate issue triage, spec validation, PR quality gates (involving security, QA, analyst, architect, devops, roadmap agents), and session protocol validation.
- CI workflows run on ARM runners with path filtering for cost efficiency.
- Validation includes mandatory checks of session protocol adherence, plan completeness, test coverage, and security validation.
- AIReviewCommon PowerShell module provides secure parsing, verdict aggregation, and GitHub comment formatting utilities.
6. Agent Consistency and Template Generation
- Agent source templates in
templates/agents/*.shared.mdgenerate platform-specific files for VS Code and Copilot CLI; Claude agents are manually maintained. .github/copilot-code-review.mdenforces consistency including core identity, responsibilities, handoff protocol, memory protocol, and output directories.- Template regeneration is mandatory on changes and verified by CI.
- The PR updates agent templates regarding Local Guardrails, including memory and session protocol compliance provisions.
7. PR Comment Responder & GitHub Skills Integration
- The pr-comment-responder agent automates triage, adding reactions, analyzing bot signals, and managing response workflows.
- It uses PowerShell GitHub skill scripts (
Get-PRContext.ps1,Get-PRReviewComments.ps1,Post-PRCommentReply.ps1,Resolve-PRReviewThread.ps1,Add-CommentReaction.ps1) that handle pagination, error handling, and security validation. - Thread resolution via GraphQL API is mandatory before merges per branch protection.
- The PR updates pr-comment-responder artifacts and session logs consistent with Local Guardrails changes.
8. Security & Autonomous Execution Guardrails
- The repository uses defense-in-depth techniques to prevent command injection (CWE-20, CWE-78) in workflows and AI parsing.
- Pre-commit hooks and PowerShell modules enforce safe patterns in shell invocation, symlink rejection, path validation, and hardened JSON parsing.
- Autonomous execution guardrails impose stricter controls requiring session log presence, orchestrator routing, critic and QA validation, and substantive replies before thread resolution.
- PR #226 retrospective highlighted catastrophic failure due to protocol bypass; this PR's documentation and plan reinforce enforcement mechanisms.
9. Installation & Directory Structure
- Per-repository agent installation is recommended due to global installation issues for Copilot CLI.
- Agents reside under
.github/agents/(VS Code and Copilot CLI) or.claude/agents/(Claude CLI). - The
.agents/directory contains agent output artifacts and session logs. - Installation scripts (
scripts/install-*.ps1) and shared module (scripts/lib/Install-Common.psm1) manage deployment and directory setup.
10. User Documentation & Quality Assurance
- The PR includes QA reports validating that all documentation files are lint-clean and no code changes occurred.
- Agents use documented style guidelines and communication best practices to maintain consistency.
- The session synthesis and traceability features ensure auditability and reproducibility of agent decisions in the consolidated Local Guardrails framework.
Conclusion
This pull request consolidates Local Guardrails initiative documentation and its integration within the multi-agent AI system, enforcing stringent session protocol and memory management practices to ensure robust, reproducible validations. The extensive repository infrastructure—covering agent coordination, memory bridge, CI/CD workflows, consistency enforcement, and security hardening—supports these improvements to prevent AI Quality Gate violations and maintain project health.
Citations
All summarized details are grounded on repository context sources including:
- DeepWiki: Repository structure and agent ecosystem overview
- AGENTS.md and related agent docs: Agent roles, session protocols, memory system, workflows
- .agents/SESSION-PROTOCOL.md: Session lifecycle and blocking gate requirements
- .agents/HANDOFF.md and ADR-014: Distributed handoff architecture and session logs
- .github/workflows/ai-pr-quality-gate.yml and related workflows: CI/CD pipeline definitions
- .github/copilot-code-review.md: Agent consistency enforcement rules
- pr-comment-responder agent sources & GitHub skills scripts (.claude/skills/github/scripts)
- Autonomous execution guardrail retrospectives and enforcement docs
- Installation scripts in
scripts/install-*.ps1and shared modules,, [::GitHub_Copilot_get_file_contents::], [::GitHub_Copilot_get_file_contents::]
🔇 Additional comments (2)
src/copilot-cli/pr-comment-responder.agent.md (1)
946-967: Copilot CLI resolution flow correctly matches shared protocolThe new Step 6.4 “Resolve Conversation Thread” and its use of
Resolve-PRReviewThread.ps1align with the documented completion gates and the shared template; behavior looks consistent and correct for Copilot CLI.src/vs-code-agents/pr-comment-responder.agent.md (1)
946-967: VS Code agent’s thread-resolution step is aligned and usable as-isThe added Step 6.4 resolution flow (including exceptions for human reviewers and use of
Resolve-PRReviewThread.ps1) cleanly matches the shared protocol and should work for VS Code users without further changes.
Fixed session 68 (analyst background agent) to meet protocol requirements: - Status: ACTIVE -> COMPLETE - Protocol Compliance: all phases marked complete with evidence - Session End Checklist: canonical 9-row format with MUST/MUST NOT 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
4f04432
Pull Request
Summary
Documents the Local Guardrails initiative analysis (Sessions 62-67) and consolidates findings into Issue #230. This PR captures the 14-agent review process that determined 70-80% overlap with existing Issue #230 work, preserving unique elements for implementation.
Specification References
.agents/specs/SPEC-local-guardrails.md.agents/planning/PLAN-local-guardrails.mdChanges
Type of Change
Testing
Agent Review
Security Review
Other Agent Reviews
Checklist
Related Issues
Contributes to #230
14-Agent Review Summary
Decision: CONSOLIDATE into Issue #230 to avoid duplicate effort.
Unique elements preserved for Issue #230 implementation: