🚀 Level Up Your Python Skills (Building Games)!

GUIDERA is an AI coding assistant template that teaches you some professional development practices through hands-on game development.

"Learn by doing. Build by playing. Code like a pro."

---

🎮 Start Your Adventure →

You're not just learning to code - you're building something real. GUIDERA walks you through building text-based games using battle-tested methodologies used by professional developers worldwide.

---

💡 The Secret Sauce: SBE + EDD + BDD + TDD

Methodology	What It Means	Why It Matters
🔍 SBE (Specification By Example)	Real examples capture true intent	You build what users actually want
🎯 EDD (Example-Driven Development)	Specific scenarios guide design decisions	Edge cases surface early
📋 BDD (Behavior-Driven Development)	Given-When-Then scenarios as specs	Everyone speaks the same language
✅ TDD (Test-Driven Development)	Red-Green-Refactor cycle	Code that works, guaranteed

---

🕹️ Choose Your Game

Pick a game to build and start learning! Each project teaches core Python concepts:

🏰 1. DungeonCrawler

Explore dungeons, fight monsters, collect treasure!

• Learn: Dictionaries, map systems, random encounters
• Inspired by: Zork, Colossal Cave Adventure
• Start Building →

🕵️ 2. Detective Mystery

Solve crimes by interviewing suspects and finding clues!

• Learn: Dialogue trees, JSON data, branching endings
• Inspired by: Sherlock Holmes: Consulting Detective
• Start Building →

🏝️ 3. HorrorSurvival

Stranded on an island—survive by managing resources!

• Learn: Game loops, state management, crafting systems
• Inspired by: The Oregon Trail
• Start Building →

🚀 4. SciFiExploration

Travel planets, trade goods, meet alien species!

• Learn: Procedural generation, diplomacy, random events
• Inspired by: Elite, Star Trader
• Start Building →

🔐 5. PuzzleEscape

Escape locked rooms by solving mind-bending puzzles!

• Learn: Function design, state tracking, puzzle logic
• Inspired by: The Room
• Start Building →

---

🔄 How GUIDERA Works

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  PLAN   │───▶│  CODE   │───▶│  ASK    │───▶│  DEBUG  │
│  Agent  │    │  Agent  │    │  Agent  │    │  Agent  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
  Design the    Implement the   Get help &    Fix issues
  spec & tests  features        guidance      & refactor

Switch agents anytime GUIDERA adapts to what you need!

---

⚡ Get Started in 60 Seconds

# 1️⃣ Clone the template (python for now)
git clone https://github.com/AISidesKicks/guidera.git
cd guidera/python-template

# 2️⃣ Pick your game and start building!
# Open this project with Kilo CLI: 
  - TAB to activate PLAN Agent 
  - "Ask it to GUIDE you and to follow instuctions in AGENTS.md"

---

📚 What You'll Learn

By building games with GUIDERA, you'll master:

• ✅ Python Best Practices — Write clean, maintainable code
• ✅ Test-Driven Development — Write tests first, code with confidence
• ✅ Behavior-Driven Design — Think in user stories and scenarios
• ✅ Project Structure — Organize code like a professional
• ✅ Conda Environments — Manage dependencies properly
• ✅ Textual Framework — Build beautiful terminal UIs
• ✅ Git Workflow — Version control from day one

---

🛠️ Tech Stack

Tool	Purpose
Python 3.12	Core language
Textual	Terminal UI framework
python-bdd	BDD testing framework
Conda	Environment management
Kilo CLI	AI coding assistant
z.AI GLM-5	AI coding model

---

📖 Documentation

• AGENTS.md — Development methodology and agent instructions
• GAMEHINTS.md — Game scenarios and Python tips
• SUMMARY.md — Generated after each project (methodology report)

---

🎯 Who Is This For?

You! If you're:

• 🎓 A teenager who completed beginner Python courses
• 🔥 Ready to level up to intermediate skills
• 🎮 Excited to build real games, not just tutorials
• 💪 Wanting to learn professional practices early

---

🤝 Contributing

Contributions are welcome! Whether it's:

• 🐛 Bug fixes
• 🎮 New game scenarios
• 📝 Documentation improvements
• 💡 Feature ideas

Check out our Contributing Guide to get started.

---

📜 License

MIT License — Build whatever you want with this template!

---

🚀 Ready to Code?

The best way to learn is by building. Pick a game, fire up Kilo CLI, and let GUIDERA guide you through professional development practices while you create something awesome.