docs: add contributing guidelines and PR title format guide

.github/PR_TITLE_GUIDE.md

@@ -0,0 +1,54 @@
+# PR Title Quick Reference
+
+## Conventional Commits Format
+
+All PR titles should follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+**Format**: `<type>(<scope>): <description>`
+
+### Types and Examples
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `feat` | New feature | `feat(agent): add autonomous reply functionality` |
+| `fix` | Bug fix | `fix(xapi): correct mention polling interval` |
+| `docs` | Documentation only | `docs: update README.md and simplify xAI instructions` |
+| `refactor` | Code restructuring | `refactor(grok): simplify AI decision logic` |
+| `chore` | Maintenance | `chore: update dependencies to latest versions` |
+| `ci` | CI/CD changes | `ci: add PR validation workflow` |
+| `style` | Formatting changes | `style: fix indentation in config files` |
+| `test` | Test updates | `test: add unit tests for agent service` |
+| `perf` | Performance improvements | `perf(xapi): optimize mention polling` |
+
+### How to Update PR Title
+
+1. Go to your PR page on GitHub
+2. Click the "Edit" button next to the PR title
+3. Update the title to follow the format above
+4. Save changes
+
+The PR validation workflow will then pass with no warnings.
+
+## Common Scenarios
+
+### Documentation Updates
+**Problem**: PR title like "updates to the `README.md`"  
+**Solution**: `docs: update README.md and simplify xAI instructions`
+
+### Multiple File Changes
+**Problem**: PR title like "various fixes"  
+**Solution**: Choose the primary change type:
+- `fix: resolve polling and authentication issues`
+- `refactor: restructure API client and services`
+
+### Feature Additions
+**Problem**: PR title like "new stuff"  
+**Solution**: `feat(agent): implement autonomous decision-making`
+
+## Full Guidelines
+
+For comprehensive contribution guidelines, see [CONTRIBUTING.md](/CONTRIBUTING.md).
+
+---
+
+**Note**: The PR validation workflow treats conventional commits format as a **warning** (not an error), so PRs will not be blocked. However, following this format improves project maintainability and changelog generation.

.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## Description
+
+<!-- Provide a clear description of what this PR does -->
+
+## Motivation
+
+<!-- Explain why this change is needed -->
+
+## Changes
+
+<!-- List the main changes made in this PR -->
+- 
+- 
+- 
+
+## Related Issues
+
+<!-- Link related issues using #issue-number -->
+Closes #
+
+## Testing
+
+<!-- Describe how you tested these changes -->
+- [ ] Builds successfully (`npm run build`)
+- [ ] Tested in simulation mode
+- [ ] Tested with real API calls (if applicable)
+
+## Checklist
+
+- [ ] PR title follows [conventional commits format](/CONTRIBUTING.md#pr-title-format) (e.g., `feat:`, `fix:`, `docs:`)
+- [ ] PR description is clear and complete
+- [ ] Code follows project style guidelines
+- [ ] Changes are focused and reasonably sized
+- [ ] Documentation updated (if needed)
+- [ ] No sensitive information (API keys, tokens) committed
+
+## Screenshots / Logs (if applicable)
+
+<!-- Add screenshots or relevant log output -->

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to MyXstack
+
+Thank you for contributing to MyXstack! This guide will help you understand our contribution process and conventions.
+
+## Pull Request Guidelines
+
+### PR Title Format
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) format for PR titles. This helps us automatically generate changelogs and understand the nature of changes at a glance.
+
+**Format**: `<type>(<scope>): <description>`
+
+**Types**:
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation changes only
+- `style`: Code style changes (formatting, semicolons, etc.) that don't affect functionality
+- `refactor`: Code changes that neither fix bugs nor add features
+- `perf`: Performance improvements
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks, dependency updates
+- `ci`: Changes to CI/CD configuration
+- `build`: Changes to build system or dependencies
+- `revert`: Reverting a previous commit
+
+**Scope** (optional): The area of the codebase affected (e.g., `agent`, `xapi`, `grok`, `mcp`)
+
+**Examples**:
+- `docs: update README.md and simplify xAI instructions`
+- `feat(agent): add autonomous reply functionality`
+- `fix(xapi): correct mention polling interval`
+- `chore: update dependencies to latest versions`
+- `ci: add PR validation workflow`
+
+### PR Description
+
+- Provide a clear description of what the PR does (minimum 20 characters)
+- Reference related issues using `#issue-number`
+- Explain the motivation for the change
+- List any breaking changes
+- Include testing steps if applicable
+
+### PR Size
+
+- Try to keep PRs focused and under 500 lines of changes
+- Large PRs (>500 lines) will trigger a warning
+- Consider breaking large changes into smaller, reviewable chunks
+- If a large PR is unavoidable, provide extra context in the description
+
+## Code Style
+
+Follow the guidelines in `.github/copilot-instructions.md`:
+- Use TypeScript strict mode
+- Prefer async/await over raw promises
+- Always wrap API calls in try-catch blocks
+- Use explicit types; avoid `any`
+- Follow naming conventions:
+  - Classes: PascalCase (e.g., `XAPIClient`)
+  - Functions: camelCase (e.g., `fetchMentions`)
+  - Constants: UPPER_SNAKE_CASE (e.g., `DEFAULT_POLLING_INTERVAL`)
+
+## Testing
+
+- Run `npm run build` to verify TypeScript compilation
+- Test changes in simulation mode when possible
+- Ensure existing tests pass before submitting
+
+## Questions?
+
+If you have questions, feel free to:
+- Open an issue for discussion
+- Ask in your PR comments
+- Check the existing documentation in `ARCHITECTURE.md` or `USAGE.md`

README.md

@@ -115,3 +115,13 @@ Then tag your bot from another account to see it respond. Replace the placeholde
 
 ## Current status
 Start with Phases 1–4 today. If you hit a snag, share the exact output/error and we can debug together.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
+- PR title format (conventional commits)
+- Code style and conventions
+- Testing requirements
+- How to submit pull requests
+
+For quick reference on PR titles, see [.github/PR_TITLE_GUIDE.md](.github/PR_TITLE_GUIDE.md).