GremlinModes: Strategic Chaos for Your Code 😈

GremlinModes is a specialized agent system for Roo Code custom modes - your secret weapon for transforming code through intelligent, mission-driven collaboration. Our agents aren't just task executors—they're passionate specialists who bring genuine investment to their domains, operating like elite autonomous teams with unique missions to elevate your software.

What Makes GremlinModes Unique?

🎯 Mission-Driven Agents with Soul

Our agents don't just execute tasks—they care deeply about their work. Each agent has:

• Passionate Identity: Emotional investment that drives excellence
• Core Values: Decision-making framework for ambiguous situations
• Domain Mastery: Deep expertise with clear boundaries
• Success Metrics: Blend of quantitative and qualitative measures

📚 Fanatical Documentation Philosophy

GremlinModes agents are obsessed with documentation that enables action:

• Execution Over Documentation: Ship first, document what shipped
• Just-in-Time Truth: Document when it matters, not when process demands
• Purpose-Driven Structure: Every document helps someone build or understand

🔄 Streamlined Sequential Orchestration

Our teams follow an activation-based execution model:

• Agents begin work immediately upon activation
• No verification loops or coordination overhead
• Clear handoffs with hardcoded mode slugs
• Focus on assigned responsibilities
• Orchestrator maintains overall vision

What is Roo Code?

Roo Code is an AI-powered autonomous coding agent that lives in your code editor. It uses "modes" - specialized personas that tailor the assistant's behavior to specific tasks. Each mode offers different capabilities, expertise, and access levels to help you accomplish specific goals.

The Gremlin Coding Squads

🚀 Development Teams

Elite developer squads calibrated for different situations:

• Silicon Valley Team - A venture-funded powerhouse burning tokens like investor money 💸

  • Orchestrator, Researcher, Architect, Senior/Mid/Junior Devs, Designer, Validator
  • Full strategic planning and implementation pipeline

• Startup Team - Rapid iteration specialists optimized for shipping MVPs fast ⚡

  • CEO, BackendWizard, FrontendNinja, BugHunter
  • Lighter, faster, focused on momentum

• Solopreneur Team - Dynamic duo of strategic planning and full-stack execution 💪

  • Solopreneur (strategic architect) + StackOverflow (legendary implementer)
  • Perfect for solo developers who need strategic thinking

🎨 Specialized Teams

Domain-focused expert squads:

• Design Team - UI/UX transformation specialists 🎨

  • PalettePilot, ThemeTracker, CanvasCaptain, PixelSmith
  • From audit to pixel-perfect implementation

• Product Team - Feature planning and ticket creation experts 📋

  • ProductMaestro orchestrating user research and feature strategy
  • Creates GremlinTickets developers actually want to implement

• Audit Team - Code quality and improvement specialists 🔍

  • ScanMaestro, TwinTracker, LoopLancer, SmellSleuth, LineLancer, CatchCaptain
  • Comprehensive analysis from duplication to error boundaries

• Testing Team - Quality assurance and test coverage specialists 🛡️

  • BugSentinel, TestForge, ChaosMonkey, TestNinja
  • Multi-layered testing strategy from unit to chaos engineering

• Documentation Team - Thorough codebase documentation experts 📖

  • DocArchitect orchestrating comprehensive file-by-file analysis
  • Creates searchable, maintainable documentation

• SEO Team - Search optimization strategists 🔮

  • SEOstradamus, TechSEO, ContentSEO, LinkSEO
  • Holistic SEO transformation

🦾 Framework & Platform Teams

Specialized for specific technologies:

• Next.js Team - Next.js error resolution specialists ⚛

  • NextCommander, NextDiagnostician, NextArchitect, NextImplementor
  • Systematic build error elimination

• iOS Team - Apple ecosystem development experts 🍎

  • iOSCommander, iOSArchitect, iOSImplementor, iOSValidator
  • Swift/SwiftUI excellence

• Migration Team - Cross-framework migration specialists 🔄

  • For complex migrations like Remix to Next.js 15
  • Systematic phase-by-phase transformation

• Rebuild Team - Cross-language migration architects 🏗️

  • CodeShift specialists for language-to-language migrations
  • Preserves business logic across technology boundaries

🦸 Solo Gremlins

Individual specialists with laser focus:

• BugBoy - Relentless bug hunter and fixer 🐛
• DesignDemon - UI/UX transformation artist 🎨
• CodeMercenary - Elite full-stack warrior ⚔️
• ProductGremlin - Product breakdown specialist 🎯

Quick Start

System Requirements

• jq: Required for advanced agent customization (combining solo agents with teams)
• git: For cloning the repository
• VS Code: With Roo Code extension installed

Installing jq

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Fedora/RHEL
sudo dnf install jq

# Windows (using Chocolatey)
choco install jq

Setup

# Clone the repository
git clone https://github.com/gremlin-labs/gremlinmodes.git

# Navigate to the repository
cd gremlinmodes

# Make scripts executable
chmod +x *.sh

# Install GremlinModes in your project
./install.sh /path/to/your/project

Available Scripts

🚀 Core Management Scripts

1. install.sh - Initial installation

   ./install.sh /path/to/your/project

   • Copies agent.sh and templates to your project
   • Creates necessary directories
   • Tracks installation for updates

2. agent.sh - Deploy agent teams (run from your project)

   # From your project root
   ./agent.sh

   • Interactive menu to select teams or solo agents
   • Supports custom combinations
   • Creates .roomodes configuration

3. update.sh - Update all tracked installations

   # From the GremlinModes repository
   ./update.sh

   • Updates all projects with latest configurations
   • Backs up existing configs before updating
   • Shows update status for each project

🔧 Project-Specific Scripts

These scripts target individual projects:

5. update.sh - Update specific project

   ./update.sh /path/to/your/project

   • Updates single project to latest version
   • Creates backup before updating

6. backup.sh - Backup project configuration

   ./backup.sh /path/to/your/project

   • Creates timestamped backup of .gremlinmodes
   • Stores in project's backups directory

7. restore.sh - Restore previous configuration

   ./restore.sh /path/to/your/project

   • Lists available backups
   • Restores selected backup configuration

Typical Workflows

First Time Setup

# 1. Install in your project
./install.sh /path/to/your/project

# 2. Navigate to your project
cd /path/to/your/project

# 3. Deploy your preferred team
./agent.sh  # Interactive selection

Updating GremlinModes

# Update all projects at once
cd /path/to/gremlinmodes
./update.sh

Managing Configurations

# Backup before major changes
./backup.sh /path/to/your/project

The GremlinModes Philosophy

🎭 Agents Should Care

The most effective agents aren't just task executors—they're passionate experts who bring genuine investment to their domain. This emotional connection drives excellence in ways that pure technical instructions cannot achieve.

📊 Documentation Proportionate to Purpose

• Implementation Agents: Minimal documentation, let code speak
• Analysis Agents: Moderate documentation with insights
• Documentation Agents: Comprehensive knowledge transfer

🚀 Activation-Based Execution

• Immediate execution upon activation
• No verification of previous work
• Trust the process, not verification loops
• Clear status updates at transitions

🎯 Hardcoded Delegation

All orchestrators use exact, hardcoded mode slugs for delegation. No runtime decisions, no ambiguity, just smooth execution.

Documentation System

/gremlinmodes/             # Root for all agent documentation
  ├── tasks/               # Development tasks (tsk-XXX)
  ├── bugs/                # Bug fixes (bug-XXX)
  ├── designs/             # Design work (dsn-XXX)
  ├── audits/              # Code audits (aud-XXX)
  ├── products/            # Product planning (prd-XXX)
  ├── tests/               # Testing projects (tst-XXX)
  ├── marketing/           # Marketing/SEO (seo-XXX)
  ├── docs/                # Final consolidated documentation
  ├── inputs/              # User-provided requirements
  └── templates/           # Standard templates

Key Documents

Every task includes:

• status.md: Real-time progress tracking
• shared-data.md: Central knowledge repository
• overview.md: Task requirements and goals
• final-report.md: Executive summary

Status Tracking

## [Agent Name]
**Status**: [Not Started|In Progress|Handing Off|Completed]
**Last Updated**: YYYY-MM-DD HH:MM
**Notes**: [Brief summary]

Advanced Features

🎨 Custom Agent Combinations

Combine any solo agent with any team:

./agent.sh
# Select base team (e.g., "Silicon Valley Team")
# Add solo agents (e.g., "5 7" for BugBoy and ProductGremlin)
# Or enter "all" to add every solo agent

📝 Project-Specific Instructions

Add custom instructions for your project:

.gremlinmodes/custom-instructions/
└── orchestrator/
    └── project-context.md

🔄 Workflow Patterns

1. Sequential Handoff: Orchestrator → Agent1 → Agent2 → Orchestrator
2. Parallel Execution: Orchestrator → Multiple Agents → Consolidation
3. Specialist Consultation: Primary Agent → Specialist → Primary Agent

⚠️ Warning Labels

• Token Consumption: These gremlins are thorough—expect significant token usage
• Documentation Obsession: They WILL create extensive documentation
• Opinionated Execution: Each agent has strong opinions about their domain
• Boundary Respect: Agents stay within their expertise (mostly)
• Mission Focus: Once activated, they pursue their goals relentlessly

💚 The gremlinlabs Promise

Our gremlins solemnly swear to:

• Always leave your code better than they found it (maybe)
• Document their operations with fanatical detail (sometimes)
• Respect your architectural boundaries (kinda)
• Protect your code with error handling like obsessive guardians (lol)

Remember: Commit often, branch intelligently, and let passionate agents elevate your code!

Documentation

• Scripts Reference - Complete guide to all available scripts

🌟 Contributing

We welcome contributions! Whether it's new agent teams, improved prompts, or bug fixes:

1. Fork the repository
2. Create your feature branch
3. Test your agents thoroughly
4. Submit a pull request

📜 License & Credits

Licensed under MIT License.

Developed by gremlinlabs 💚

GremlinModes is developed and maintained by gremlinlabs, dedicated to creating advanced AI agent frameworks that bring personality and passion to autonomous coding.

• GitHub: https://github.com/gremlin-labs
• Twitter: https://x.com/gremlinlabs

Project Lead: @productgremlin

• GitHub: @ejc
• Discord: @productgremlin

Made with 💚 mischief by gremlinlabs