# 🗺️ What's In This Repository (Plain English Edition)

This is a **toolbox** for developers who work with AI assistants like Claude. Think of it as a recipe book + power tools for coding with AI help.

---

## 📂 The Main Folders Explained

### 📁 [.claude/](./../.claude/)
**What it is:** The brain of the automation system

**In plain English:** This folder contains all the smart stuff that makes AI assistants work better in your projects. It has:
- Settings that tell Claude what it can and can't do
- Scripts that automate boring tasks
- Commands you can run with a simple `/command-name`
- Knowledge that helps Claude give better answers

**Why it matters:** When you sync this to your other projects, they instantly get all these superpowers.

---

### 📁 [docs/](./../docs/)
**What it is:** The instruction manuals

**In plain English:** Detailed guides for:
- [Installing Claude Code](./../docs/installing-claude-code.md) - How to get the AI coding tool on your computer
- [Prompt Engineering Guide](./../docs/prompt-engineering-guide.md) - How to ask AI better questions to get better answers
- [Claude Code Best Practices](./../docs/claude-code-best-practices.md) - Tips for using Claude effectively
- [Syncing Automation](./../docs/syncing-automation.md) - How to copy the magic to other projects

---

### 📁 [methodologies/](./../methodologies/)
**What it is:** The "how to think about it" guides

**In plain English:** Explains the approach for working with AI:
- [AI Pair Programming](./../methodologies/ai-pair-programming.md) - Treating AI like a coding partner who helps you build things

---

### 📁 [playbooks/](./../playbooks/)
**What it is:** Step-by-step recipes

**In plain English:** Like a cookbook but for coding tasks:
- [Implementing New Feature](./../playbooks/implementing-new-feature.md) - Step 1, Step 2, Step 3... to build something new

---

### 📁 [prompts/](./../prompts/)
**What it is:** Copy-paste templates for asking AI

**In plain English:** Ready-made questions you can copy and use:
- Code generation prompts - "Write me code that does X"
- Review prompts - "Check this code for problems"
- Testing prompts - "Create tests for this"

---

### 📁 [tips-and-tricks/](./../tips-and-tricks/)
**What it is:** Quick helpful hints

**In plain English:** Bite-sized advice organized by topic:
- [Prompting tips](./../tips-and-tricks/prompting/) - Better ways to ask AI for help
- [Debugging tips](./../tips-and-tricks/debugging/) - How to fix broken things
- [Testing tips](./../tips-and-tricks/testing/) - How to make sure things work
- [Workflow tips](./../tips-and-tricks/workflow/) - How to work faster

---

### 📁 [model-nuances/](./../model-nuances/)
**What it is:** AI personality profiles

**In plain English:** Different AI tools have different strengths:
- [Claude 3.5 Sonnet](./../model-nuances/claude-3-5-sonnet.md) - What Claude is good at, what to watch out for

---

### 📁 [templates/](./../templates/)
**What it is:** Fill-in-the-blank documents

**In plain English:** Start here when you want to:
- Write a quick note
- Document a tip
- Save a useful prompt
- Record something you learned about an AI

---

### 📁 [specs/](./../specs/)
**What it is:** The rule books

**In plain English:** Standards and requirements for:
- Code quality
- Testing
- Security
- Best practices

---

## 📄 Important Files in the Root

| File | What It Does |
|------|--------------|
| [README.md](./../README.md) | The main intro to everything |
| [QUICKSTART.md](./../QUICKSTART.md) | Get started in 5 minutes |
| [CONTRIBUTING.md](./../CONTRIBUTING.md) | How to add your own stuff |
| [CLAUDE.md](./../CLAUDE.md) | Critical rules AI must follow |

---

## 🎯 The Big Picture

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   THIS REPOSITORY                                           │
│   ================                                          │
│                                                             │
│   📚 Knowledge          → docs/, methodologies/             │
│      (How to think)                                         │
│                                                             │
│   📋 Templates          → prompts/, templates/              │
│      (Copy and use)                                         │
│                                                             │
│   🔧 Automation         → .claude/                          │
│      (Does work for you)                                    │
│                                                             │
│   💡 Tips               → tips-and-tricks/                  │
│      (Quick wins)                                           │
│                                                             │
│   📖 Playbooks          → playbooks/                        │
│      (Step-by-step)                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## ❓ Common Questions

**Q: Do I need to understand all of this?**
A: No! Start with what you need. Browse by problem, not by folder.

**Q: What's the most useful thing here?**
A: The `persuade` CLI (`pip install persuade`) - it copies all the good stuff to any project with one command.

**Q: Where do I start?**
A: Read [QUICKSTART.md](./../QUICKSTART.md) - it takes 5 minutes.

**Q: Can I add my own notes?**
A: Yes! Just drop them in the right folder. See [CONTRIBUTING.md](./../CONTRIBUTING.md).

---

*Plain English explanations for everyone.*
