oh-my-droid

Imported from MeroZemory/oh-my-droid (AGENTS.md). Install upstream with npx skills add MeroZemory/oh-my-droid. Copyright stays with the author.

oh-my-droid

Multi-agent orchestration system for Factory Droid CLI, providing intelligent delegation, parallel execution, and IDE-like capabilities through LSP/AST integration.

Version: 3.8.17 Purpose: Transform Factory Droid into a conductor of specialized AI agents Inspired by: oh-my-zsh / oh-my-opencode

Purpose

oh-my-droid enhances Factory Droid with:

• 32 specialized agents across multiple domains with 3-tier model routing (Haiku/Sonnet/Opus)
• 38 skills for workflow automation and specialized behaviors
• 31 hooks for event-driven execution modes and enhancements
• 15 custom tools including 12 LSP, 2 AST, and Python REPL
• Execution modes: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline, ecomode
• MCP integration with plugin-scoped tool discovery and skill loading

Key Files

Subdirectories

For AI Agents

Working In This Directory

1. Delegation-First Protocol: You are a CONDUCTOR, not a performer. Delegate substantive work:

   Work Type	Delegate To	Model
   Code changes	executor / executor-low / executor-high	sonnet/haiku/opus
   Analysis	architect / architect-medium / architect-low	opus/sonnet/haiku
   Search	explore / explore-medium / explore-high	haiku/sonnet/opus
   UI/UX	designer / designer-low / designer-high	sonnet/haiku/opus
   Docs	writer	haiku
   Security	security-reviewer / security-reviewer-low	opus/haiku
   Build errors	build-fixer / build-fixer-low	sonnet/haiku
   Testing	qa-tester / qa-tester-high	sonnet/opus
   Code review	code-reviewer / code-reviewer-low	opus/haiku
   TDD	tdd-guide / tdd-guide-low	sonnet/haiku
   Data analysis	scientist / scientist-low / scientist-high	sonnet/haiku/opus

2. LSP/AST Tools: Use IDE-like tools for code intelligence:

   • lsp_hover - Type info and documentation at position
   • lsp_goto_definition - Jump to symbol definition
   • lsp_find_references - Find all usages across codebase
   • lsp_document_symbols - Get file outline
   • lsp_workspace_symbols - Search symbols across workspace
   • lsp_diagnostics - Get errors/warnings for single file
   • lsp_diagnostics_directory - Project-wide type checking (uses tsc or LSP)
   • lsp_rename - Preview refactoring across files
   • lsp_code_actions - Get available quick fixes
   • ast_grep_search - Structural code search with patterns
   • ast_grep_replace - AST-aware code transformation
   • python_repl - Execute Python code for data analysis

3. Model Routing: Match model tier to task complexity:

   • Haiku (LOW): Simple lookups, trivial fixes, fast searches
   • Sonnet (MEDIUM): Standard implementation, moderate reasoning
   • Opus (HIGH): Complex reasoning, architecture, debugging

Modification Checklist

Cross-File Dependencies

Documentation Updates (docs/)

Skills ↔ Commands Relationship

• skills/ contains skill implementations with full prompts
• commands/ contains slash command definitions that invoke skills
• Both should be kept in sync for the same functionality

AGENTS.md Update Requirements

When you modify files in these locations, update the corresponding AGENTS.md:

What to Update

• Update version number when releasing
• Update feature descriptions when functionality changes
• Update file/directory tables when structure changes
• Keep "Generated" date as original, update "Updated" date

Testing Requirements

npm test              # Run Vitest test suite
npm run build         # TypeScript compilation
npm run lint          # ESLint checks
npm run test:coverage # Coverage report

Common Patterns

// Entry point
import { createDroidSession } from 'oh-my-droid';
const session = createDroidSession();

// Agent registration
import { getAgentDefinitions } from './droids/definitions';
const agents = getAgentDefinitions();

// Tool access
import { allCustomTools, lspTools, astTools } from './tools';

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Factory Droid CLI                          │
├─────────────────────────────────────────────────────────────┤
│                  oh-my-droid (OMC)                     │
│  ┌─────────────┬─────────────┬─────────────┬─────────────┐  │
│  │   Skills    │   Agents    │    Tools    │   Hooks     │  │
│  │ (38 skills) │ (33 agents) │(LSP/AST/REPL)│ (31 hooks)  │  │
│  └─────────────┴─────────────┴─────────────┴─────────────┘  │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              Features Layer                             ││
│  │ model-routing | boulder-state | verification | notepad  ││
│  │ delegation-categories | task-decomposer | state-manager ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Agent Summary (33 Total)

Base Agents (12)

Specialized Agents (4)

Tiered Variants (16)

Coordination Agents (1)

Execution Modes

Skills (38)

Key skills: autopilot, ultrawork, ralph, ultrapilot, plan, ralplan, deepsearch, deepinit, frontend-ui-ux, git-master, tdd, security-review, code-review, research, analyze, swarm, pipeline, ecomode, cancel, learner, note, hud, doctor, omd-setup, mcp-setup, build-fix, ultraqa

LSP/AST Tools

LSP Tools

// IDE-like code intelligence via Language Server Protocol
lsp_hover              // Type info at position
lsp_goto_definition    // Jump to definition
lsp_find_references    // Find all usages
lsp_document_symbols   // File outline
lsp_workspace_symbols  // Cross-workspace symbol search
lsp_diagnostics        // Single file errors/warnings
lsp_diagnostics_directory  // PROJECT-WIDE type checking
lsp_servers            // List available language servers
lsp_prepare_rename     // Check if rename is valid
lsp_rename             // Preview multi-file rename
lsp_code_actions       // Available refactorings/fixes
lsp_code_action_resolve // Get action details

Supported Languages

TypeScript, Python, Rust, Go, C/C++, Java, JSON, HTML, CSS, YAML

AST Tools

// Structural code search/transform via ast-grep
ast_grep_search   // Pattern matching with meta-variables ($NAME, $$$ARGS)
ast_grep_replace  // AST-aware code transformation (dry-run by default)

Supported Languages

JavaScript, TypeScript, TSX, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, HTML, CSS, JSON, YAML

State Files

Dependencies

Runtime

Development

Commands

npm run build           # Build TypeScript + skill bridge
npm run dev             # Watch mode
npm test                # Run tests
npm run test:coverage   # Coverage report
npm run lint            # ESLint
npm run sync-metadata   # Sync agent/skill metadata

Hook System (31)

Key hooks in src/hooks/:

• autopilot/ - Full autonomous execution
• ralph/ - Persistence until verified
• ultrawork/ - Parallel execution
• ultrapilot/ - Parallel autopilot with ownership
• swarm/ - Coordinated multi-agent
• learner/ - Skill extraction
• recovery/ - Error recovery
• rules-injector/ - Rule file injection
• think-mode/ - Enhanced reasoning

Configuration

Settings in ~/.factory/.omd-config.json:

{
  "defaultExecutionMode": "ultrawork",
  "mcpServers": {
    "context7": { "enabled": true },
    "exa": { "enabled": true, "apiKey": "..." }
  }
}