docs: add beginner-friendly pull request guide for new contributors

- Create comprehensive PR guide at docs/how-to-contribute-with-pull-requests.md
- Add prominent links in README.md and CONTRIBUTING.md
- Include step-by-step instructions for GitHub newcomers
- Explain what makes good vs bad PRs with examples
- Add Discord community as primary support channel

This addresses issues with inexperienced contributors submitting
poorly formatted PRs or code dumps instead of proper contributions.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

CONTRIBUTING.md

@@ -2,6 +2,8 @@
 
 Thank you for considering contributing to this project! This document outlines the process for contributing and some guidelines to follow.
 
+🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first!
+
 Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
 
 ## Code of Conduct

README.md

@@ -241,7 +241,10 @@ Ask the agent you are using for help with /help (in the web) or \*help in the id
 
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+We welcome contributions!
+
+- 🆕 **New to GitHub?** Start with our [Pull Request Guide](docs/how-to-contribute-with-pull-requests.md)
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines
 
 ### Development Setup
 

docs/how-to-contribute-with-pull-requests.md

@@ -0,0 +1,141 @@
+# How to Contribute with Pull Requests
+
+**New to GitHub and pull requests?** This guide will walk you through the basics step by step.
+
+## What is a Pull Request?
+
+A pull request (PR) is how you propose changes to a project on GitHub. Think of it as saying "Here are some changes I'd like to make - please review and consider adding them to the main project."
+
+## Before You Start
+
+⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change. If you're planning something big, please [open an issue](https://github.com/bmadcode/bmad-method/issues) or start a [discussion](https://github.com/bmadcode/bmad-method/discussions) first.
+
+## Step-by-Step Guide
+
+### 1. Fork the Repository
+
+1. Go to the [BMAD-METHOD repository](https://github.com/bmadcode/bmad-method)
+2. Click the "Fork" button in the top-right corner
+3. This creates your own copy of the project
+
+### 2. Clone Your Fork
+
+```bash
+# Replace YOUR-USERNAME with your actual GitHub username
+git clone https://github.com/YOUR-USERNAME/bmad-method.git
+cd bmad-method
+```text
+
+### 3. Create a New Branch
+
+**Never work directly on the `main` branch!** Always create a new branch for your changes:
+
+```bash
+# Create and switch to a new branch
+git checkout -b fix/typo-in-readme
+# or
+git checkout -b feature/add-new-agent
+```
+
+**Branch naming tips:**
+
+- `fix/description` - for bug fixes
+- `feature/description` - for new features
+- `docs/description` - for documentation changes
+
+### 4. Make Your Changes
+
+- Edit the files you want to change
+- Keep changes small and focused on one thing
+- Test your changes if possible
+
+### 5. Commit Your Changes
+
+```bash
+# Add your changes
+git add .
+
+# Commit with a clear message
+git commit -m "Fix typo in README.md"
+```text
+
+**Good commit messages:**
+
+- "Fix typo in installation instructions"
+- "Add example for new agent usage"
+- "Update broken link in docs"
+
+**Bad commit messages:**
+
+- "stuff"
+- "changes"
+- "update"
+
+### 6. Push to Your Fork
+
+```bash
+# Push your branch to your fork
+git push origin fix/typo-in-readme
+```
+
+### 7. Create the Pull Request
+
+1. Go to your fork on GitHub
+2. You'll see a green "Compare & pull request" button - click it
+3. Fill out the PR template:
+   - **Title**: Clear, descriptive title
+   - **Description**: Explain what you changed and why
+
+### 8. Wait for Review
+
+- A maintainer will review your PR
+- They might ask for changes
+- Be patient and responsive to feedback
+
+## What Makes a Good Pull Request?
+
+✅ **Good PRs:**
+
+- Change one thing at a time
+- Have clear, descriptive titles
+- Explain what and why in the description
+- Include only the files that need to change
+
+❌ **Avoid:**
+
+- Changing formatting of entire files
+- Multiple unrelated changes in one PR
+- Copying your entire project/repo into the PR
+- Changes without explanation
+
+## Common Mistakes to Avoid
+
+1. **Don't reformat entire files** - only change what's necessary
+2. **Don't include unrelated changes** - stick to one fix/feature per PR
+3. **Don't paste code in issues** - create a proper PR instead
+4. **Don't submit your whole project** - contribute specific improvements
+
+## Need Help?
+
+- 💬 Join our [Discord Community](https://discord.gg/g6ypHytrCB) for real-time help
+- 💬 Ask questions in [Discussions](https://github.com/bmadcode/bmad-method/discussions)
+- 🐛 Report bugs in [Issues](https://github.com/bmadcode/bmad-method/issues)
+- 📖 Read the full [Contributing Guidelines](../CONTRIBUTING.md)
+
+## Example: Good vs Bad PRs
+
+### 😀 Good PR Example
+
+**Title**: "Fix broken link to installation guide"
+**Changes**: One file, one line changed
+**Description**: "The link in README.md was pointing to the wrong file. Updated to point to correct installation guide."
+
+### 😞 Bad PR Example
+
+**Title**: "Updates"
+**Changes**: 50 files, entire codebase reformatted
+**Description**: "Made some improvements"
+
+---
+
+**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner.