CONTRIBUTING.md

# Contributing Guidelines

Thank you for considering contributing to AI Agents from Scratch!

## Project Philosophy

This repository teaches AI agent fundamentals by building from scratch. Every contribution should support this learning mission.

**Core Principles:**
- **Clarity over cleverness** - Code should be easy to understand
- **Fundamentals first** - No black boxes or magic
- **Progressive learning** - Each example builds on the previous
- **Local-first** - No API dependencies

## Types of Contributions

### Bug Reports
Found something broken? Open an issue with:
- Which example (`intro/`, `react-agent/`, etc.)
- What you expected vs. what happened
- Your environment (Node version, OS, model used)
- Steps to reproduce

### Documentation Improvements
- Typos and grammar fixes
- Clearer explanations
- Better code comments
- Additional examples in documentation
- Diagrams and visualizations

### New Examples
Want to add a new agent pattern? Great! Please:
1. **Open an issue first** - let's discuss if it fits
2. Follow the existing structure:
- `pattern-name/pattern-name.js` - Working code
- `pattern-name/CODE.md` - Detailed code walkthrough
- `pattern-name/CONCEPT.md` - Why it matters, use cases
3. Keep it simple and well-commented
4. Test thoroughly with at least one model

### Code Improvements
- Performance optimizations (with benchmarks)
- Better error handling
- Clearer variable names
- More helpful console output

## What We're Not Looking For

- Framework integrations (LangChain, etc.) - this repo teaches what they do
- Cloud API examples - keep it local
- Production features (monitoring, scaling) - this is educational
- Complex abstractions - keep it beginner-friendly

## Contribution Process

1. **Fork** the repository
2. **Create a branch**: `git checkout -b fix/issue-description`
3. **Make changes** and test thoroughly
4. **Commit** with clear messages: `git commit -m "Fix: clarify ReAct loop explanation"`
5. **Push**: `git push origin fix/issue-description`
6. **Open a Pull Request** with:
- Clear title
- Description of what changed and why
- Which issue it addresses (if any)

## Code Standards

- Use clear, descriptive variable names
- Add comments explaining *why*, not just *what*
- Follow existing code style (no linter, just match the patterns)
- Keep examples self-contained (one file when possible)
- Test with Qwen or Llama models before submitting

## Documentation Standards

- Use clear, simple language
- Explain concepts before code
- Include diagrams where helpful (ASCII art is fine!)
- Provide real-world use cases
- Link to related examples

## Example Structure
```

new-pattern/

├── new-pattern.js # The working code

├── CODE.md # Line-by-line walkthrough

└── CONCEPT.md # High-level explanation

```

**CODE.md should include:**
- Prerequisites
- Step-by-step code breakdown
- How to run it
- Expected output

**CONCEPT.md should include:**
- What problem it solves
- Why this pattern matters
- Real-world applications
- Simple diagrams

## Getting Help

- Not sure if your idea fits? **Open an issue to discuss**
- Stuck on implementation? **Ask in the issue**
- Want to pair on something? **Reach out!**

## License

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT).

## Recognition

All contributors will be recognized in the README. Thank you for helping others learn!

---

**Questions?** Open an issue or reach out. Happy to help guide your contribution!