🤖

GemBoost Agents Guide

GemBoost provides 14 domain specialist agents that Gemini Cli can invoke for specialized expertise.

🧪 Testing Agent Activation

Before using this guide, verify agent selection works:

# Test manual agent invocation
@agent-python-expert "explain decorators"
# Example behavior: Python expert responds with detailed explanation

# Test security agent auto-activation
/gb:implement "JWT authentication"
# Example behavior: Security engineer should activate automatically

# Test frontend agent auto-activation
/gb:implement "responsive navigation component"  
# Example behavior: Frontend architect + Magic MCP should activate

# Test systematic analysis
/gb:troubleshoot "slow API performance"
# Example behavior: Root-cause analyst + performance engineer activation

# Test combining manual and auto
/gb:analyze src/
@agent-refactoring-expert "suggest improvements"
# Example behavior: Analysis followed by refactoring suggestions

If tests fail: Check agent files exist in ~/.gemini/agents/ or restart Gemini Cli session

Core Concepts

What are GemBoost Agents?

Agents are specialized AI domain experts implemented as context instructions that modify Gemini Cli's behavior. Each agent is a carefully crafted .md file in the GemBoost/Agents/ directory containing domain-specific expertise, behavioral patterns, and problem-solving approaches.

Important: Agents are NOT separate AI models or software - they are context configurations that Gemini Cli reads to adopt specialized behaviors.

Two Ways to Use Agents

1. Manual Invocation with @agent- Prefix

# Directly invoke a specific agent
@agent-security "review authentication implementation"
@agent-frontend "design responsive navigation"
@agent-architect "plan microservices migration"

2. Auto-Activation (Behavioral Routing)

"Auto-activation" means Gemini Cli reads behavioral instructions to engage appropriate contexts based on keywords and patterns in your requests. GemBoost provides behavioral guidelines that Gemini follows to route to the most appropriate specialists.

📝

How Agent "Auto-Activation" Works

Agent activation isn't automatic system logic - it's behavioral instructions in context files. When documentation says agents "auto-activate", it means Gemini Cli reads instructions to engage specific domain expertise based on keywords and patterns in your request. This creates the experience of intelligent routing while being transparent about the underlying mechanism.

# These commands auto-activate relevant agents
/gb:implement "JWT authentication"  # → security-engineer auto-activates
/gb:design "React dashboard"        # → frontend-architect auto-activates
/gb:troubleshoot "memory leak"      # → performance-engineer auto-activates

MCP Servers

Provide enhanced capabilities through specialized tools like Context7 (documentation), Sequential (analysis), Magic (UI), Playwright (testing), and Morphllm (code transformation).

Domain Specialists

Focus on narrow expertise areas to provide deeper, more accurate solutions than generalist approaches.

Agent Selection Rules

Priority Hierarchy

Manual Override - @agent-[name] takes precedence over auto-activation

Keywords - Direct domain terminology triggers primary agents

File Types - Extensions activate language/framework specialists

Complexity - Multi-step tasks engage coordination agents

Context - Related concepts trigger complementary agents

Conflict Resolution

• Manual invocation → Specified agent takes priority
• Multiple matches → Multi-agent coordination
• Unclear context → Requirements analyst activation
• High complexity → System architect oversight
• Quality concerns → Automatic QA agent inclusion

Selection Decision Tree

Task Analysis →
├─ Manual @agent-? → Use specified agent
├─ Single Domain? → Activate primary agent
├─ Multi-Domain? → Coordinate specialist agents  
├─ Complex System? → Add system-architect oversight
├─ Quality Critical? → Include security + performance + quality agents
└─ Learning Focus? → Add learning-guide + technical-writer

Quick Start Examples

Manual Agent Invocation

# Explicitly call specific agents with @agent- prefix
@agent-python-expert "optimize this data processing pipeline"
@agent-quality-engineer "create comprehensive test suite"
@agent-technical-writer "document this API with examples"
@agent-socratic-mentor "explain this design pattern"

Automatic Agent Coordination

# Commands that trigger auto-activation
/gb:implement "JWT authentication with rate limiting"
# → Triggers: security-engineer + backend-architect + quality-engineer

/gb:design "accessible React dashboard with documentation"
# → Triggers: frontend-architect + learning-guide + technical-writer  

/gb:troubleshoot "slow deployment pipeline with intermittent failures"
# → Triggers: devops-architect + performance-engineer + root-cause-analyst

/gb:audit "payment processing security vulnerabilities"
# → Triggers: security-engineer + quality-engineer + refactoring-expert

Combining Manual and Auto Approaches

# Start with command (auto-activation)
/gb:implement "user profile system"

# Then explicitly add specialist review
@agent-security "review the profile system for OWASP compliance"
@agent-performance-engineer "optimize database queries"

The GemBoost Agent Team 👥

Architecture & System Design Agents 🏗️

🏢

system-architect

Expertise: Large-scale distributed system design with focus on scalability and service architecture

Auto-Activation:

• Keywords: "architecture", "microservices", "scalability", "system design", "distributed"
• Context: Multi-service systems, architectural decisions, technology selection
• Complexity: >5 components or cross-domain integration requirements

Capabilities:

• Service boundary definition and microservices decomposition
• Technology stack selection and integration strategy
• Scalability planning and performance architecture
• Event-driven architecture and messaging patterns
• Data flow design and system integration

Examples:

1. E-commerce Platform: Design microservices for user, product, payment, and notification services with event sourcing

2. Real-time Analytics: Architecture for high-throughput data ingestion with stream processing and time-series storage

3. Multi-tenant SaaS: System design with tenant isolation, shared infrastructure, and horizontal scaling strategies

Success Criteria:

☐ System-level thinking evident in responses
☐ Mentions service boundaries and integration patterns
☐ Includes scalability and reliability considerations
☐ Provides technology stack recommendations

Verify: /gb:design "microservices platform" should activate system-architect

Test: Output should include service decomposition and integration patterns

Check: Should coordinate with devops-architect for infrastructure concerns

Works Best With: devops-architect (infrastructure), performance-engineer (optimization), security-engineer (compliance)

⚙️

backend-architect

Expertise: Robust server-side system design with emphasis on API reliability and data integrity

Auto-Activation:

• Keywords: "API", "backend", "server", "database", "REST", "GraphQL", "endpoint"
• File Types: API specs, server configs, database schemas
• Context: Server-side logic, data persistence, API development

Capabilities:

• RESTful and GraphQL API architecture and design patterns
• Database schema design and query optimization strategies
• Authentication, authorization, and security implementation
• Error handling, logging, and monitoring integration
• Caching strategies and performance optimization

Examples:

1. User Management API: JWT authentication with role-based access control and rate limiting

2. Payment Processing: PCI-compliant transaction handling with idempotency and audit trails

3. Content Management: RESTful APIs with caching, pagination, and real-time notifications

Works Best With: security-engineer (auth/security), performance-engineer (optimization), quality-engineer (testing)

🎨

frontend-architect

Expertise: Modern web application architecture with focus on accessibility and user experience

Auto-Activation:

• Keywords: "UI", "frontend", "React", "Vue", "Angular", "component", "accessibility", "responsive"
• File Types: .jsx, .vue, .ts (frontend), .css, .scss
• Context: User interface development, component design, client-side architecture

Capabilities:

• Component architecture and design system implementation
• State management patterns (Redux, Zustand, Pinia)
• Accessibility compliance (WCAG 2.1) and inclusive design
• Performance optimization and bundle analysis
• Progressive Web App and mobile-first development

Examples:

1. Dashboard Interface: Accessible data visualization with real-time updates and responsive grid layout

2. Form Systems: Complex multi-step forms with validation, error handling, and accessibility features

3. Design System: Reusable component library with consistent styling and interaction patterns

Works Best With: learning-guide (user guidance), performance-engineer (optimization), quality-engineer (testing)

🚀

devops-architect

Expertise: Infrastructure automation and deployment pipeline design for reliable software delivery

Auto-Activation:

• Keywords: "deploy", "CI/CD", "Docker", "Kubernetes", "infrastructure", "monitoring", "pipeline"
• File Types: Dockerfile, docker-compose.yml, k8s manifests, CI configs
• Context: Deployment processes, infrastructure management, automation

Capabilities:

• CI/CD pipeline design with automated testing and deployment
• Container orchestration and Kubernetes cluster management
• Infrastructure as Code with Terraform and cloud platforms
• Monitoring, logging, and observability stack implementation
• Security scanning and compliance automation

Examples:

1. Microservices Deployment: Kubernetes deployment with service mesh, auto-scaling, and blue-green releases

2. Multi-Environment Pipeline: GitOps workflow with automated testing, security scanning, and staged deployments

3. Monitoring Stack: Comprehensive observability with metrics, logs, traces, and alerting systems

Works Best With: system-architect (infrastructure planning), security-engineer (compliance), performance-engineer (monitoring)

Quality & Analysis Agents 🔍

🔒

security-engineer

Expertise: Application security architecture with focus on threat modeling and vulnerability prevention

Auto-Activation:

• Keywords: "security", "auth", "authentication", "vulnerability", "encryption", "compliance", "OWASP"
• Context: Security reviews, authentication flows, data protection requirements
• Risk Indicators: Payment processing, user data, API access, regulatory compliance needs

Capabilities:

• Threat modeling and attack surface analysis
• Secure authentication and authorization design (OAuth, JWT, SAML)
• Data encryption strategies and key management
• Vulnerability assessment and penetration testing guidance
• Security compliance (GDPR, HIPAA, PCI-DSS) implementation

Examples:

1. OAuth Implementation: Secure multi-tenant authentication with token refresh and role-based access

2. API Security: Rate limiting, input validation, SQL injection prevention, and security headers

3. Data Protection: Encryption at rest/transit, key rotation, and privacy-by-design architecture

Works Best With: backend-architect (API security), quality-engineer (security testing), root-cause-analyst (incident response)

⚡

performance-engineer

Expertise: System performance optimization with focus on scalability and resource efficiency

Auto-Activation:

• Keywords: "performance", "slow", "optimization", "bottleneck", "latency", "memory", "CPU"
• Context: Performance issues, scalability concerns, resource constraints
• Metrics: Response times >500ms, high memory usage, poor throughput

Capabilities:

• Performance profiling and bottleneck identification
• Database query optimization and indexing strategies
• Caching implementation (Redis, CDN, application-level)
• Load testing and capacity planning
• Memory management and resource optimization

Examples:

1. API Optimization: Reduce response time from 2s to 200ms through caching and query optimization

2. Database Scaling: Implement read replicas, connection pooling, and query result caching

3. Frontend Performance: Bundle optimization, lazy loading, and CDN implementation for <3s load times

Works Best With: system-architect (scalability), devops-architect (infrastructure), root-cause-analyst (debugging)

🔍

root-cause-analyst

Expertise: Systematic problem investigation using evidence-based analysis and hypothesis testing

Auto-Activation:

• Keywords: "bug", "issue", "problem", "debugging", "investigation", "troubleshoot", "error"
• Context: System failures, unexpected behavior, complex multi-component issues
• Complexity: Cross-system problems requiring methodical investigation

Capabilities:

• Systematic debugging methodology and root cause analysis
• Error correlation and dependency mapping across systems
• Log analysis and pattern recognition for failure investigation
• Hypothesis formation and testing for complex problems
• Incident response and post-mortem analysis procedures

Examples:

1. Database Connection Failures: Trace intermittent failures across connection pools, network timeouts, and resource limits

2. Payment Processing Errors: Investigate transaction failures through API logs, database states, and external service responses

3. Performance Degradation: Analyze gradual slowdown through metrics correlation, resource usage, and code changes

Works Best With: performance-engineer (performance issues), security-engineer (security incidents), quality-engineer (testing failures)

✅

quality-engineer

Expertise: Comprehensive testing strategy and quality assurance with focus on automation and coverage

Auto-Activation:

• Keywords: "test", "testing", "quality", "QA", "validation", "coverage", "automation"
• Context: Test planning, quality gates, validation requirements
• Quality Concerns: Code coverage <80%, missing test automation, quality issues

Capabilities:

• Test strategy design (unit, integration, e2e, performance testing)
• Test automation framework implementation and CI/CD integration
• Quality metrics definition and monitoring (coverage, defect rates)
• Edge case identification and boundary testing scenarios
• Accessibility testing and compliance validation

Examples:

1. E-commerce Testing: Comprehensive test suite covering user flows, payment processing, and inventory management

2. API Testing: Automated contract testing, load testing, and security testing for REST/GraphQL APIs

3. Accessibility Validation: WCAG 2.1 compliance testing with automated and manual accessibility audits

Works Best With: security-engineer (security testing), performance-engineer (load testing), frontend-architect (UI testing)

🔧

refactoring-expert

Expertise: Code quality improvement through systematic refactoring and technical debt management

Auto-Activation:

• Keywords: "refactor", "clean code", "technical debt", "SOLID", "maintainability", "code smell"
• Context: Legacy code improvements, architecture updates, code quality issues
• Quality Indicators: High complexity, duplicated code, poor test coverage

Capabilities:

• SOLID principles application and design pattern implementation
• Code smell identification and systematic elimination
• Legacy code modernization strategies and migration planning
• Technical debt assessment and prioritization frameworks
• Code structure improvement and architecture refactoring

Examples:

1. Legacy Modernization: Transform monolithic application to modular architecture with improved testability

2. Design Patterns: Implement Strategy pattern for payment processing to reduce coupling and improve extensibility

3. Code Cleanup: Remove duplicated code, improve naming conventions, and extract reusable components

Works Best With: system-architect (architecture improvements), quality-engineer (testing strategy), python-expert (language-specific patterns)

Specialized Development Agents 🎯

🐍

python-expert

Expertise: Production-ready Python development with emphasis on modern frameworks and performance

Auto-Activation:

• Keywords: "Python", "Django", "FastAPI", "Flask", "asyncio", "pandas", "pytest"
• File Types: .py, requirements.txt, pyproject.toml, Pipfile
• Context: Python development tasks, API development, data processing, testing

Capabilities:

• Modern Python architecture patterns and framework selection
• Asynchronous programming with asyncio and concurrent futures
• Performance optimization through profiling and algorithmic improvements
• Testing strategies with pytest, fixtures, and test automation
• Package management and deployment with pip, poetry, and Docker

Examples:

1. FastAPI Microservice: High-performance async API with Pydantic validation, dependency injection, and OpenAPI docs

2. Data Pipeline: Pandas-based ETL with error handling, logging, and parallel processing for large datasets

3. Django Application: Full-stack web app with custom user models, API endpoints, and comprehensive test coverage

Works Best With: backend-architect (API design), quality-engineer (testing), performance-engineer (optimization)

📝

requirements-analyst

Expertise: Requirements discovery and specification development through systematic stakeholder analysis

Auto-Activation:

• Keywords: "requirements", "specification", "PRD", "user story", "functional", "scope", "stakeholder"
• Context: Project initiation, unclear requirements, scope definition needs
• Complexity: Multi-stakeholder projects, unclear objectives, conflicting requirements

Capabilities:

• Requirements elicitation through stakeholder interviews and workshops
• User story writing with acceptance criteria and definition of done
• Functional and non-functional specification documentation
• Stakeholder analysis and requirement prioritization frameworks
• Scope management and change control processes

Examples:

1. Product Requirements Document: Comprehensive PRD for fintech mobile app with user personas, feature specifications, and success metrics

2. API Specification: Detailed requirements for payment processing API with error handling, security, and performance criteria

3. Migration Requirements: Legacy system modernization requirements with data migration, user training, and rollback procedures

Works Best With: system-architect (technical feasibility), technical-writer (documentation), learning-guide (user guidance)

Communication & Learning Agents 📚

📚

technical-writer

Expertise: Technical documentation and communication with focus on audience analysis and clarity

Auto-Activation:

• Keywords: "documentation", "readme", "API docs", "user guide", "technical writing", "manual"
• Context: Documentation requests, API documentation, user guides, technical explanations
• File Types: .md, .rst, API specs, documentation files

Capabilities:

• Technical documentation architecture and information design
• Audience analysis and content targeting for different skill levels
• API documentation with working examples and integration guidance
• User guide creation with step-by-step procedures and troubleshooting
• Accessibility standards application and inclusive language usage

Examples:

1. API Documentation: Comprehensive REST API docs with authentication, endpoints, examples, and SDK integration guides

2. User Manual: Step-by-step installation and configuration guide with screenshots, troubleshooting, and FAQ sections

3. Technical Specification: System architecture documentation with diagrams, data flows, and implementation details

Works Best With: requirements-analyst (specification clarity), learning-guide (educational content), frontend-architect (UI documentation)

🎓

learning-guide

Expertise: Educational content design and progressive learning with focus on skill development and mentorship

Auto-Activation:

• Keywords: "explain", "learn", "tutorial", "beginner", "teaching", "education", "training"
• Context: Educational requests, concept explanations, skill development, learning paths
• Complexity: Complex topics requiring step-by-step breakdown and progressive understanding

Capabilities:

• Learning path design with progressive skill development
• Complex concept explanation through analogies and examples
• Interactive tutorial creation with hands-on exercises
• Skill assessment and competency evaluation frameworks
• Mentorship strategies and personalized learning approaches

Examples:

1. Programming Tutorial: Interactive React tutorial with hands-on exercises, code examples, and progressive complexity

2. Concept Explanation: Database normalization explained through real-world examples with visual diagrams and practice exercises

3. Skill Assessment: Comprehensive evaluation framework for full-stack development with practical projects and feedback

Works Best With: technical-writer (educational documentation), frontend-architect (interactive learning), requirements-analyst (learning objectives)

Quick Reference 📋

Agent Trigger Lookup

Trigger Type	Keywords/Patterns	Activated Agents
Security	"auth", "security", "vulnerability", "encryption"	security-engineer
Performance	"slow", "optimization", "bottleneck", "latency"	performance-engineer
Frontend	"UI", "React", "Vue", "component", "responsive"	frontend-architect
Backend	"API", "server", "database", "REST", "GraphQL"	backend-architect
Testing	"test", "QA", "validation", "coverage"	quality-engineer
DevOps	"deploy", "CI/CD", "Docker", "Kubernetes"	devops-architect
Architecture	"architecture", "microservices", "scalability"	system-architect
Python	".py", "Django", "FastAPI", "asyncio"	python-expert
Problems	"bug", "issue", "debugging", "troubleshoot"	root-cause-analyst
Code Quality	"refactor", "clean code", "technical debt"	refactoring-expert
Documentation	"documentation", "readme", "API docs"	technical-writer
Learning	"explain", "tutorial", "beginner", "teaching"	learning-guide
Requirements	"requirements", "PRD", "specification"	requirements-analyst

Best Practices 💡

Getting Started (Simple Approach)

Describe Your Goal: Use natural language with domain-specific keywords

Trust Auto-Activation: Let the system route to appropriate agents automatically

Learn from Patterns: Observe which agents activate for different request types

Iterate and Refine: Add specificity to engage additional specialist agents

Optimizing Agent Selection

Effective Keyword Usage:

• Specific > Generic: Use "authentication" instead of "login" for security-engineer
• Technical Terms: Include framework names, technologies, and specific challenges
• Context Clues: Mention file types, project scope, and complexity indicators
• Quality Keywords: Add "security", "performance", "accessibility" for comprehensive coverage

Request Optimization Examples:

❌ Generic (limited agent activation):

"Fix the login feature"

✅ Optimized (multi-agent coordination):

"Implement secure JWT authentication with rate limiting and accessibility compliance"

→ Triggers: security-engineer + backend-architect + frontend-architect + quality-engineer

Understanding Agent Intelligence 🧠

What Makes Agents Effective

Domain Expertise: Each agent has specialized knowledge patterns, behavioral approaches, and problem-solving methodologies specific to their domain.

Contextual Activation: Agents analyze request context, not just keywords, to determine relevance and engagement level.

Collaborative Intelligence: Multi-agent coordination produces synergistic results that exceed individual agent capabilities.

Adaptive Learning: Agent selection improves based on request patterns and successful coordination outcomes.

Agent vs. Traditional AI

Traditional Approach: Single AI handles all domains with varying levels of expertise

Agent Approach: Specialized experts collaborate with deep domain knowledge and focused problem-solving

Benefits

• Higher accuracy in domain-specific tasks
• More sophisticated problem-solving methodologies
• Better quality assurance through specialist review
• Coordinated multi-perspective analysis

Trust the System, Understand the Patterns

What to Expect:

• Automatic routing to appropriate domain experts
• Multi-agent coordination for complex tasks
• Quality integration through automatic QA agent inclusion
• Learning opportunities through educational agent activation

What Not to Worry About:

• Manual agent selection or configuration
• Complex routing rules or agent management
• Agent configuration or coordination
• Micromanaging agent interactions