multi-agent-ai-projects

# Multi-Agent AI Projects Guidelines for working with multi-agent AI learning projects and experimental codebases. ## CRITICAL: First Actions When Starting or Resuming Work **Read STATUS.md FIRST** (usually `.spec/STATUS.md` or project root) - Shows current phase, completed lessons, blockers, and resume instructions. This prevents working on wrong lessons or repeating completed work. Then: 1. Check git status 2. Verify dependencies installed 3. Check lesson-specific .env files **Auto-activate when:** Project has `.spec/` directory, `lessons/` subdirectory, `STATUS.md`, or lesson-numbered directories. ## Project Structure Recognition ### Common Patterns - `.spec/` directory - Learning specifications and experimental code - `lessons/` or similar learning directories - `STATUS.md` - Progress tracking for learning journey - Per-lesson or per-module structure - Self-contained lesson directories ### Typical Lesson Structure ``` lesson-XXX/ ├── <name>_agent/ # Agent (agent.py, tools.py, prompts.py, cli.py) ├── .env # API keys (gitignored) ├── PLAN.md / README.md # Lesson docs ├── COMPLETE.md # Learnings └── test_*.py # Tests ``` ## Workflow Patterns ### Execution - Use `uv run python` from lesson directory - Check lesson README for setup ### API Keys - Per-lesson `.env` files (never commit) - Check `.env.example` or `.env.template` ### Dependencies - `uv sync --group lesson-XXX` for lesson-specific deps - Check `pyproject.toml` for dependency groups ## Progress Tracking ### STATUS.md Pattern - **Read before starting work** (most important!) - Update after completing lessons - Note blockers and next steps - Document learnings and insights - Track which lessons are complete ### Session Management - **Always check STATUS.md at session start** (FIRST action) - Update STATUS.md before ending sessions - Note any experimental findings - Document what worked and what didn't ## Common Project Types ### Learning Spike Projects - Focus on exploration and experimentation - Code may not be production-quality - Documentation of learnings is important - Test different approaches - Iterate quickly ### Multi-Agent Frameworks - Agent coordination patterns - Tool usage and integration - Message passing between agents - State management across agents - Router/coordinator patterns ## Quick Reference **Execution:** - `uv run python` from lesson directory - Check per-lesson dependencies **Documentation:** - Update STATUS.md with progress - Document findings in COMPLETE.md - Note blockers and next steps --- **Note:** These projects are learning-focused - prioritize understanding and documentation over production perfection. STATUS.md is your single source of truth for project state.