docs(claude): add GitHub workflow requirements for issue assignment and PR templates#334
Conversation
…nd PR templates Add MUST requirements to CLAUDE.md for: - Assigning issues to self when starting work - Using PR template for all pull requests These rules are now auto-loaded every session. 🤖 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 adds important GitHub workflow requirements to the CLAUDE.md documentation, specifically for assigning issues and using pull request templates. The changes are well-written and adhere to the repository's markdown style guide.
There was a problem hiding this comment.
Pull request overview
This PR adds mandatory GitHub workflow requirements to CLAUDE.md to ensure consistent process adherence across all sessions. The changes document two critical workflows: assigning GitHub issues to oneself before starting work, and using the complete PR template when creating pull requests.
- Added "GitHub Workflow Requirements (MUST)" section with RFC 2119 MUST keyword
- Documented issue assignment workflow with
gh issue editcommand - Listed all required PR template sections with explicit anti-pattern guidance
📝 WalkthroughWalkthroughDocumentation added to CLAUDE.md establishing GitHub Workflow Requirements for Issue Assignment and Pull Request Template procedures. Includes specific commands, timing details, and rationale. A GitHub Workflow Requirements section is duplicated across two locations, with the second including an exception clause for simple questions. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Flag: The duplicated GitHub Workflow Requirements block creates maintenance risk. If requirements change, both locations need updates. Consider consolidating into a single source of truth. Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used📓 Path-based instructions (16)**/*.md📄 CodeRabbit inference engine (.agents/architecture/ADR-001-markdown-linting.md)
Files:
⚙️ CodeRabbit configuration file
Files:
**/CLAUDE.md📄 CodeRabbit inference engine (.agents/governance/agent-consolidation-process.md)
Files:
CLAUDE.md📄 CodeRabbit inference engine (.agents/governance/steering-committee-charter.md)
Files:
**/*.{md,json,yml,yaml,ps1,sh,bash,toml,ini,cfg,config,txt}📄 CodeRabbit inference engine (.agents/retrospective/phase1-remediation-pr43.md)
Files:
**/*.{md,markdown}📄 CodeRabbit inference engine (.agents/retrospective/2025-12-17-session-failures.md)
Files:
{README*,INSTALL*,*.md}📄 CodeRabbit inference engine (.agents/analysis/002-copilot-cli-limitations-assessment.md)
Files:
**/*.{ps1,yml,yaml,md}📄 CodeRabbit inference engine (.agents/analysis/003-session-protocol-skill-gate.md)
Files:
**/*.{md,js,ts,tsx,jsx,json,yaml,yml,sh,ps1}📄 CodeRabbit inference engine (.agents/retrospective/2025-12-18-serena-memory-reference-migration.md)
Files:
**/*.{md,js,ts,tsx,jsx}📄 CodeRabbit inference engine (.agents/retrospective/2025-12-18-serena-memory-reference-migration.md)
Files:
**/*.{md,ts,tsx,js,jsx,py}📄 CodeRabbit inference engine (.agents/retrospective/2025-12-18-session-17-retrospective.md)
Files:
**/*.{js,ts,ps1,py,json,yaml,yml,md}📄 CodeRabbit inference engine (.agents/retrospective/2025-12-19-skill-extraction-summary.md)
Files:
**/*.{md,txt}📄 CodeRabbit inference engine (.agents/pr-batch-review-session-2025-12-20.md)
Files:
{**/*.md,.serena/**}📄 CodeRabbit inference engine (.agents/qa/002-pr-201-skills-clarity-fixes.md)
Files:
**/{SESSION-PROTOCOL,*-PROTOCOL,*.md}📄 CodeRabbit inference engine (.agents/archive/HANDOFF-2025-12-22.md)
Files:
**/*.{md,yml,yaml}📄 CodeRabbit inference engine (.agents/analysis/156-pr-review-analysis.md)
Files:
**/*.{sh,bash,md}📄 CodeRabbit inference engine (.agents/sessions/2025-12-23-session-84-pr308-review-comments.md)
Files:
🧠 Learnings (5)📚 Learning: 2025-12-16T06:26:21.783ZApplied to files:
📚 Learning: 2025-12-16T06:26:44.230ZApplied to files:
📚 Learning: 2025-12-16T06:26:44.208ZApplied to files:
📚 Learning: 2025-12-16T06:27:04.317ZApplied to files:
📚 Learning: 2025-12-16T08:00:20.752ZApplied to files:
🔍 Remote MCP DeepWikiDeepWiki Wiki Structure for “rjmurillo/ai-agents”DeepWiki indexes this repository under the following high-level topics, which help orient where CLAUDE.md fits in:
Architecture Page HighlightsFrom the Architecture page:
CLAUDE.md Context and Usage
Summary of Additional Context for Review
🔇 Additional comments (3)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
CLAUDE.md (1)
40-42: Language identifier mismatch: PowerShell command in bash code block.Line 40 contains a
pwsh(PowerShell) command but the code fence is marked asbash. This is confusing and breaks syntax highlighting.Fix the language identifier to
powershell:-```bash -pwsh scripts/Validate-SessionEnd.ps1 -SessionLogPath ".agents/sessions/[session-log].md" -``` +```powershell +pwsh scripts/Validate-SessionEnd.ps1 -SessionLogPath ".agents/sessions/[session-log].md" +```
📜 Review details
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CLAUDE.md
🧰 Additional context used
📓 Path-based instructions (16)
**/*.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:
CLAUDE.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:
CLAUDE.md
**/CLAUDE.md
📄 CodeRabbit inference engine (.agents/governance/agent-consolidation-process.md)
Update the agent catalog (CLAUDE.md) to remove deprecated agents and reflect consolidated agent capabilities
Add reference to naming conventions and link to
.agents/governance/naming-conventions.mdin main agent documentation (CLAUDE.md)
Files:
CLAUDE.md
CLAUDE.md
📄 CodeRabbit inference engine (.agents/governance/steering-committee-charter.md)
Agent catalog table must be maintained in CLAUDE.md
Update CLAUDE.md to reference central naming conventions document at .agents/governance/naming-conventions.md for sequenced artifact patterns, type-prefixed patterns, and naming rules.
Files:
CLAUDE.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:
CLAUDE.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:
CLAUDE.md
{README*,INSTALL*,*.md}
📄 CodeRabbit inference engine (.agents/analysis/002-copilot-cli-limitations-assessment.md)
Document platform-specific limitations prominently in README and installation documentation, particularly regarding context window sizes, configuration architecture, and feature parity differences between Claude Code, VS Code, and Copilot CLI
Files:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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)
Use artifact naming conventions: EPIC-NNN-kebab-case for epics, PRD-feature-name.md for product requirements, ADR-NNN-kebab-case-title.md for architectural decisions, TASK-EPIC-NNN-MM for tasks, NNN-feature-plan.md for plans
Files:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.md
🧠 Learnings (5)
📚 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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.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:
CLAUDE.md
🔍 Remote MCP DeepWiki
DeepWiki Wiki Structure for “rjmurillo/ai-agents”
DeepWiki indexes this repository under the following high-level topics, which help orient where CLAUDE.md fits in:
- Overview
- Architecture
- Contributing Guidelines
- CLI Reference
- CLAUDE (agent configuration docs)
Architecture Page Highlights
From the Architecture page:
- Document Loader: At startup, the agent instantiates a DocumentLoader that reads files under
/docs/claude/(including CLAUDE.md) and marshals them into the session context. - Session Manager: Sequences loaded docs into the prompt template before any user interaction.
- GitHub Workflow Integration: A separate “Automation” component watches for
gh issueand PR template compliance; it references the same CLAUDE.md directives to enforce checks at runtime.
Implication for this PR: adding workflow requirements to CLAUDE.md will automatically be picked up by both the pre-session loader and the GitHub integration checks without code changes.
CLAUDE.md Context and Usage
- Location:
/docs/claude/CLAUDE.md - Purpose: Defines “session-level” directives (e.g., commands the bot must always follow) that are prepended to every conversation.
- Existing Sections:
- Agent Behavior (how to answer questions)
- Ticketing & Workspace Guidelines (links to issue templates, branch naming)
- Automation Hooks (references to GitHub checks)
- New Section Impact:
- Introducing “GitHub Workflow Requirements (MUST)” into this file means every session will now carry these directives automatically.
- The duplication of the block in two places could lead to conflicting instructions if one is updated and the other is not; consider consolidating to a single canonical section.
Summary of Additional Context for Review
- CLAUDE.md is central to both prompting and GitHub-check automation; changes here are automatically consumed by the system.
- The PR adds mandatory GitHub workflow steps but duplicates them — consolidation is recommended to avoid drift.
- No runtime code is affected, but reviewers should verify that the GitHub integration component’s search patterns cover the updated section’s exact headings and command syntax.
🔇 Additional comments (3)
CLAUDE.md (3)
86-102: Missing code block for shell command at line 90.Line 90 contains
cat .github/PULL_REQUEST_TEMPLATE.mdas plain text within the numbered list. Wrap this in a code block for consistency with other commands in the document:1. Read the template: `cat .github/PULL_REQUEST_TEMPLATE.md`Actually, this is already in inline backticks, which is acceptable. However, if this were to be a standalone command (not inline), it would need a code block. Current formatting is acceptable.
72-102: Relative paths and RFC 2119 usage are correct.All file paths use repository-relative format (
.agents/,.github/), and RFC 2119 keywords (MUST, SHOULD) are applied consistently per session protocol guidelines. These patterns follow project standards.
72-102: No duplication of GitHub Workflow Requirements section found.The section appears only once in CLAUDE.md (line 72). No consolidation needed.
Likely an incorrect or invalid review comment.
|
This PR is blocked by Issue #341: Required check 'Validate Memory Files' references a workflow that doesn't exist on main. The workflow exists only on the unmerged Root Cause: Branch protection ruleset was updated before the workflow was merged to main, creating a phantom required check. Fix: Merge the See full analysis: |
Adds the missing workflow that creates the "Validate Memory Files" required check. This workflow was on an unmerged feature branch, causing PR #334 to be blocked indefinitely. Fixes #341 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Comprehensive investigation of 20 open PRs to identify those stuck for similar reasons as PR #334. Key Findings: - PR #334 is NOT stuck (all checks pass, approved, mergeable) - 16 of 20 PRs are actually stuck - 10 PRs blocked by Aggregate Results failures (62.5%) - Only 1 PR (#342) shares PR #334's blocker type (missing workflow) - 6 PRs have merge conflicts - 3 PRs ready to merge immediately (#334, #336, #245) Analysis identifies systemic pattern in Aggregate Results failures affecting majority of stuck PRs, distinct from originally described missing workflow issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* ci: add memory validation workflow for ADR-017 enforcement Adds the missing workflow that creates the "Validate Memory Files" required check. This workflow was on an unmerged feature branch, causing PR #334 to be blocked indefinitely. Fixes #341 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * style(ci): add ADR-014 compliance comment for ARM runner selection Address Copilot review comment: Document ARM runner choice per ADR-014 (GitHub Actions Runner Selection) for cost optimization and consistency. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(ci): skip memory validation when no memory files changed Adds conditional check to skip validation when only workflow/script files change. This allows bootstrapping the workflow without failing on pre-existing bundled memory files on main. Validation still runs when .serena/memories/** files are modified. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Comprehensive investigation of 20 open PRs to identify those stuck for similar reasons as PR #334. Key Findings: - PR #334 is NOT stuck (all checks pass, approved, mergeable) - 16 of 20 PRs are actually stuck - 10 PRs blocked by Aggregate Results failures (62.5%) - Only 1 PR (#342) shares PR #334's blocker type (missing workflow) - 6 PRs have merge conflicts - 3 PRs ready to merge immediately (#334, #336, #245) Analysis identifies systemic pattern in Aggregate Results failures affecting majority of stuck PRs, distinct from originally described missing workflow issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Pull Request
Summary
Add MUST requirements to CLAUDE.md for GitHub workflow behaviors that must be followed every session:
These rules are now auto-loaded every session via CLAUDE.md.
Specification References
Spec Requirement Guidelines
docs:)Changes
gh issue editcommandType of Change
Testing
Agent Review
Security Review
Other Agent Reviews
Checklist
Related Issues
N/A - Process improvement based on user feedback
🤖 Generated with Claude Code