docs: improve PR template and add agent guidance for descriptive PRs

[AutumnsGrove]

• Update PR template with REQUIRED markers for summary and changes
• Add "Changes" section to explicitly list modifications
• Add AI agent instructions in HTML comment for PR creation
• Add "Pull Request Requirements" section to AGENT.md with examples
• Reference git-workflows skill before commits and PRs
• Simplify template by removing redundant documentation checklist

[claude]

Code Review

Summary

This PR improves the pull request template and agent documentation to ensure more descriptive PRs. The changes are well-executed and align with Grove's documentation practices.

✅ Strengths

1. Clear intent and execution - The template changes effectively address vague PR descriptions
2. Consistency - Uses Grove's voice (warm, direct, helpful) appropriately
3. Practical examples - The dark mode example in AGENT.md is concrete and useful
4. Strategic placement - AI agent instructions in HTML comments won't clutter the PR view
5. Good simplification - Removing the verbose documentation checklist reduces friction

📋 Code Quality

Template structure (.github/PULL_REQUEST_TEMPLATE.md:1-67)

• ✅ Proper use of bold REQUIRED markers
• ✅ HTML comment for AI agents is well-placed
• ✅ Conventional commit examples match project standards
• ✅ Checklist items are actionable and relevant

Documentation (AGENT.md:160-225)

• ✅ Consistent formatting with rest of file
• ✅ Warning callout using existing pattern
• ✅ Good balance of rules and examples
• ✅ Appropriate cross-reference to git-workflows skill

🎯 Best Practices

Follows Grove conventions:

• Uses clear, direct language without corporate jargon
• Provides concrete examples rather than abstract rules
• Balances guidance with flexibility
• No unnecessary emoji or performative language

Template design:

• Reduces cognitive load with clear sections
• Bullet point placeholders guide without overwhelming
• Testing section is pragmatic, not dogmatic

🔍 Minor Observations

1. Inconsistent placeholder style - Mix of bold and non-bold in template:

   • Line 3: REQUIRED: Write 2-4 sentences
   • Line 23: Describe how this was tested: (not marked REQUIRED)

   Consider: Should Testing also be marked REQUIRED? Based on the examples in AGENT.md, testing descriptions seem expected.

2. Documentation section ambiguity - The three checkboxes are mutually exclusive but not formatted as radio buttons. First-time contributors might check multiple. This is acceptable for a markdown template, but worth noting.

3. Template bullet placeholders (lines 7-9) - While this guides the format, some users might leave these empty bullets. Consider adding placeholder text as examples.

🔒 Security Considerations

No security concerns. This is documentation-only.

🧪 Testing

The changes are to documentation templates. Testing would involve:

• Creating test PRs to verify template renders correctly ✅ (implicit)
• Checking that AI agents receive HTML comments ✅ (via Claude Code usage)

💡 Suggestions (Optional)

Consider adding a one-line example comment to the Changes section to guide users without cluttering the rendered PR.

📊 Overall Assessment

Rating: ✅ Approve with minor suggestions

This PR achieves its goal effectively. The template will help maintain PR quality, and the AGENT.md additions reinforce the expectations. The changes are self-consistent, well-documented, and follow project conventions.

Impact:

• Reduces vague PRs from AI agents and human contributors
• Provides concrete examples without being prescriptive
• Maintains Grove's warm, helpful voice

Recommendation: Merge as-is. The minor observations above are enhancements, not blockers.

---

Reviewed with attention to Grove's voice, agent workflows, and documentation standards.