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.