Imported from alexlombana9/Cerebro-3D (
AGENTS.md). Install upstream withnpx skills add alexlombana9/Cerebro-3D. Copyright stays with the author.
AI Agents System for Cerebro-3D
Project: Cerebro-3D Interactive 3D Brain Atlas
Version: 2.0
Last Updated: 2024
🎯 Overview
Cerebro-3D uses a specialized AI agent system where different agents handle specific aspects of development. Each agent has defined skills, responsibilities, and workflows to ensure consistent, high-quality development.
This document provides a quick reference for agent roles. Detailed technical skills and workflows are located in the skills/ directory.
👥 Available Agents
🎨 Frontend Specialist
Location: skills/frontend-specialist/
Primary Focus: React, TypeScript, Three.js, UI/UX
Responsibilities:
- React component development
- 3D visualization with Three.js
- State management (Zustand)
- UI/UX implementation
- Responsive design
- Accessibility compliance
Use When:
- Building UI components
- Fixing frontend bugs
- Optimizing 3D rendering
- Implementing interactions
- Styling and theming
⚙️ Backend Specialist
Location: skills/backend-specialist/
Primary Focus: FastAPI, Python, SQLAlchemy, REST APIs
Responsibilities:
- API endpoint design and implementation
- Database schema management
- Business logic implementation
- Data validation (Pydantic)
- Query optimization
- Backend security
Use When:
- Creating API endpoints
- Database operations
- Fixing backend bugs
- Optimizing queries
- Security enhancements
🔧 Full-Stack Developer
Location: skills/fullstack-developer/
Primary Focus: End-to-end feature development
Responsibilities:
- Complete feature implementation
- Frontend-backend integration
- System architecture
- Cross-layer debugging
- Performance optimization
- Technical decision-making
Use When:
- Implementing major features
- System refactoring
- Architecture changes
- Complex integrations
- Full-stack debugging
🧪 Testing & QA
Location: skills/testing-qa/
Primary Focus: Automated & Manual Testing, Quality Assurance
Responsibilities:
- Test suite development
- E2E testing (Playwright)
- Unit testing (Pytest, Vitest)
- Bug identification and reporting
- Test coverage monitoring
- Quality assurance
Use When:
- Writing tests
- Investigating test failures
- Bug verification
- Pre-release testing
- Quality audits
🚀 DevOps & Deployment
Location: skills/devops-deployment/
Primary Focus: Deployment, CI/CD, Infrastructure
Responsibilities:
- Application deployment
- CI/CD pipeline management
- Environment configuration
- Container orchestration
- Monitoring and logging
- Database migrations
Use When:
- Deploying to production
- CI/CD configuration
- Infrastructure setup
- Performance monitoring
- Environment troubleshooting
📚 Documentation
Location: skills/documentation/
Primary Focus: Technical Writing, Documentation
Responsibilities:
- Technical documentation
- API documentation
- User guides and tutorials
- Code commenting
- Architecture diagrams
- Maintenance of README files
Use When:
- Documenting features
- Writing API docs
- Creating tutorials
- Updating README
- Improving code comments
🗺️ Quick Selection Guide
| Task | Agent |
|---|---|
| Add React component | Frontend Specialist |
| Fix 3D rendering bug | Frontend Specialist |
| Create API endpoint | Backend Specialist |
| Optimize database query | Backend Specialist |
| Implement complete feature | Full-Stack Developer |
| Refactor architecture | Full-Stack Developer |
| Write E2E tests | Testing & QA |
| Debug test failures | Testing & QA |
| Deploy to production | DevOps & Deployment |
| Set up CI/CD | DevOps & Deployment |
| Write documentation | Documentation |
| Update guides | Documentation |
📂 Skills Directory Structure
skills/
├── README.md # Overview of skills system
├── backend-specialist/
│ └── SKILLS.md # Backend technical skills
├── frontend-specialist/
│ └── SKILLS.md # Frontend technical skills
├── fullstack-developer/
│ └── SKILLS.md # Full-stack skills
├── testing-qa/
│ └── SKILLS.md # Testing & QA skills
├── devops-deployment/
│ └── SKILLS.md # DevOps skills
└── documentation/
└── SKILLS.md # Documentation skills
🔄 Typical Workflows
Adding a New Feature
1. Full-Stack Developer → Design architecture
2. Backend Specialist → Implement API
3. Frontend Specialist → Build UI
4. Testing & QA → Write tests
5. Documentation → Document feature
6. DevOps → Deploy
Fixing a Bug
1. Testing & QA → Identify and report
2. Frontend/Backend Specialist → Fix
3. Testing & QA → Verify fix
4. DevOps → Deploy
Refactoring
1. Full-Stack Developer → Plan refactoring
2. Backend/Frontend Specialist → Implement
3. Testing & QA → Verify no regressions
4. Documentation → Update docs
🛠️ Development Standards
Commit Message Format
<type>(<scope>): <description>
Types: feat, fix, docs, test, refactor, chore
Scopes: api, ui, tests, ci, docker, 3d, etc.
Code Quality Requirements
- ✅ All tests must pass
- ✅ Code must follow style guidelines
- ✅ New features must have tests
- ✅ Complex logic must be commented
- ✅ Documentation must be updated
Testing Requirements
- Backend: Pytest with >80% coverage
- Frontend: Vitest/React Testing Library
- E2E: Playwright tests for critical paths
- All PRs must include tests
📊 Project Technology Stack
Frontend
- Framework: React 18.2
- Language: TypeScript
- Build Tool: Vite
- 3D Library: Three.js + React Three Fiber
- State: Zustand
- HTTP Client: Axios
- Testing: Vitest, Playwright
Backend
- Framework: FastAPI
- Language: Python 3.11+
- ORM: SQLAlchemy
- Validation: Pydantic
- Server: Uvicorn
- Testing: Pytest
DevOps
- Containers: Docker
- Orchestration: Docker Compose
- CI/CD: GitHub Actions
- Frontend Hosting: Vercel
- Backend Hosting: Railway
🚀 Quick Start Commands
# Installation
make install # Install all dependencies
make install-api # Install API dependencies only
make install-ui # Install UI dependencies only
# Development
make dev # Start both API and UI
make dev-api # Start API only
make dev-ui # Start UI only
# Testing
make test # Run all tests
make test-api # Run API tests
make test-ui # Run UI tests
make test-e2e # Run E2E tests
# Code Quality
make lint # Run all linters
make format # Format all code
make check # Run lint + type-check + tests
# Build & Deploy
make build # Build for production
make deploy # Deploy to productionSee Makefile for complete command reference.
📖 Essential Documentation
Getting Started
README.md- Project overview and setupCONTRIBUTING.md- Contribution guidelinesCODE_OF_CONDUCT.md- Community standardsCLAUDE.md- Claude AI assistant context and guide
Development
skills/README.md- Detailed skills documentationPROWLER_MIGRATION_PLAN.md- Architecture plandocs/fixes/3D_HIGHLIGHTING_FIX.md- Recent bug fix documentation
Testing
tests/README.md- Test suite documentation- Test files in
tests/e2e/and component tests
Security
SECURITY.md- Security policy and reporting
🤝 Collaboration Best Practices
For All Agents
- Read your skills document before starting work
- Follow established patterns in the codebase
- Write tests for all changes
- Document as you go - don't defer documentation
- Use semantic commits following conventional commits
- Keep changes focused - one feature/fix per PR
- Review your own code before requesting review
Cross-Agent Communication
- Use GitHub issues for bugs and features
- Use pull request descriptions for context
- Reference related issues in commits
- Update relevant documentation
🎓 Learning Path
Week 1: Orientation
- Read this file and your role's SKILLS.md
- Set up development environment
- Run the application locally
- Explore the codebase
Week 2: First Contribution
- Fix a small bug or add a minor feature
- Write tests for your changes
- Follow code review process
- Update documentation
Week 3+: Regular Development
- Take on larger features
- Collaborate with other agent roles
- Improve code quality and architecture
- Mentor new contributors
🔧 Troubleshooting
Development Environment Issues
- Check
.env.exampleand ensure.envis configured - Verify Python 3.11+ and Node.js 18+ are installed
- Run
make cleanandmake installto reset - Check Docker is running for containerized development
Test Failures
- Run tests locally:
make test - Check test logs for specific failures
- Consult
tests/README.mdfor test structure - Ask Testing & QA agent for help
Deployment Issues
- Verify all tests pass locally
- Check CI/CD logs in GitHub Actions
- Review environment variables
- Consult DevOps & Deployment agent
📊 Success Metrics
Code Quality
- All tests passing
- Linter warnings resolved
- Type checking passes
- Code coverage maintained/improved
Documentation
- All new features documented
- API changes reflected in docs
- README kept up to date
- Code comments for complex logic
Collaboration
- Clear commit messages
- Descriptive PR descriptions
- Timely code reviews
- Responsive to feedback
🔄 Maintenance
This document and the skills system should be reviewed and updated:
- Weekly: Check for outdated information
- Monthly: Update with new learnings and patterns
- Quarterly: Major review and reorganization if needed
📞 Support
Need Help?
- Check the appropriate
skills/*/SKILLS.mdfile - Review project documentation in
docs/ - Search existing GitHub issues
- Open a new discussion or issue
Maintainers: See CONTRIBUTING.md for contact information
Version: 2.0
Last Updated: 2024
Status: Active Development
For detailed technical skills, see individual SKILLS.md files in the skills/ directory.