Omd Setup

OMD Setup

This skill is a setup wizard. Ignore unrelated context (open files, pending code changes, git/commits, etc.).

When you need to ask the user anything, use the AskUser tool and ONLY ask the wizard questions below.

This is the only command you need to learn. After running this, everything else is automatic.

Graceful Interrupt Handling

IMPORTANT: This setup process saves progress after each step. If interrupted (Ctrl+C or connection loss), the setup can resume from where it left off.

State File Location

• .omd/state/setup-state.json - Tracks completed steps

Resume Detection (Step 0)

Before starting any step, check for existing state:

# Check for existing setup state
STATE_FILE=".omd/state/setup-state.json"

# Cross-platform ISO date to epoch conversion
iso_to_epoch() {
  local iso_date="$1"
  local epoch=""
  # Try GNU date first (Linux)
  epoch=$(date -d "$iso_date" +%s 2>/dev/null)
  if [ $? -eq 0 ] && [ -n "$epoch" ]; then
    echo "$epoch"
    return 0
  fi
  # Try BSD/macOS date
  local clean_date=$(echo "$iso_date" | sed 's/[+-][0-9][0-9]:[0-9][0-9]$//' | sed 's/Z$//' | sed 's/T/ /')
  epoch=$(date -j -f "%Y-%m-%d %H:%M:%S" "$clean_date" +%s 2>/dev/null)
  if [ $? -eq 0 ] && [ -n "$epoch" ]; then
    echo "$epoch"
    return 0
  fi
  echo "0"
}

if [ -f "$STATE_FILE" ]; then
  # Check if state is stale (older than 24 hours)
  TIMESTAMP_RAW=$(jq -r '.timestamp // empty' "$STATE_FILE" 2>/dev/null)
  if [ -n "$TIMESTAMP_RAW" ]; then
    TIMESTAMP_EPOCH=$(iso_to_epoch "$TIMESTAMP_RAW")
    NOW_EPOCH=$(date +%s)
    STATE_AGE=$((NOW_EPOCH - TIMESTAMP_EPOCH))
  else
    STATE_AGE=999999  # Force fresh start if no timestamp
  fi
  if [ "$STATE_AGE" -gt 86400 ]; then
    echo "Previous setup state is more than 24 hours old. Starting fresh."
    rm -f "$STATE_FILE"
  else
    LAST_STEP=$(jq -r ".lastCompletedStep // 0" "$STATE_FILE" 2>/dev/null || echo "0")
    TIMESTAMP=$(jq -r .timestamp "$STATE_FILE" 2>/dev/null || echo "unknown")
    echo "Found previous setup session (Step $LAST_STEP completed at $TIMESTAMP)"
  fi
fi

If state exists, use AskUser to prompt exactly:

1. [question] Found a previous setup session. What should I do?

[topic] Resume [option] Resume from last step [option] Start fresh (clear saved state)

If user chooses "Start fresh":

rm -f ".omd/state/setup-state.json"
echo "Previous state cleared. Starting fresh setup."

Step 0.5: Always Ask Parallelism (Required)

MANDATORY: Regardless of whether the user resumes or starts fresh, you MUST ask for maxBackgroundTasks in this run.

If resuming, try to infer the scope from the state file:

# Optional: infer scope from state file
CONFIG_TYPE=$(jq -r '.configType // empty' ".omd/state/setup-state.json" 2>/dev/null || true)

Interpretation:

• If CONFIG_TYPE starts with local → scope = Local (this project)
• If CONFIG_TYPE starts with global → scope = Global (all projects)
• Otherwise, ask Step 1 (scope) again.

Save Progress Helper

After completing each major step, save progress:

# Save setup progress (call after each step)
# Usage: save_setup_progress STEP_NUMBER
save_setup_progress() {
  mkdir -p .omd/state
  cat > ".omd/state/setup-state.json" = 1, skip to the appropriate step based on configType.

Immediately use `AskUser` to prompt **exactly**:

1. [question] Where should I configure oh-my-droid?
[topic] Scope
[option] Local (this project)
[option] Global (all projects)

## Step 1.1: Configure Parallelism (maxBackgroundTasks)

**IMPORTANT:** Always run this step (even if `maxBackgroundTasks` is already set, and even when resuming).

Use `AskUser` to prompt:

1. [question] How many background tasks should I allow in parallel?
[topic] Parallelism
[option] Keep current
[option] 2
[option] 5
[option] 10
[option] 20

If the user chooses **Keep current**, skip updating settings.

Otherwise, update BOTH:

1) **Factory Droid global settings**: `~/.factory/settings.json` → top-level `maxBackgroundTasks`
2) **oh-my-droid config** (so OMD can read it):
   - If scope is **Local** → `./.factory/droid.jsonc` → `permissions.maxBackgroundTasks`
   - If scope is **Global** → `${XDG_CONFIG_HOME:-~/.config}/oh-my-droid/config.jsonc` → `permissions.maxBackgroundTasks`

Rules:
- Default to **5** if the user provides an invalid value
- Clamp to **1..20**

```bash
python3 -  str:
  out: list[str] = []
  i = 0
  in_str = False
  str_ch = ''
  while i  dict:
  if not path.exists():
    return {}
  raw = path.read_text('utf-8')
  cleaned = strip_jsonc(raw)
  cleaned = re.sub(r',\s*([}\]])', r'\1', cleaned)
  cleaned_s = cleaned.strip()
  if not cleaned_s:
    return {}
  return json.loads(cleaned_s)

factory_settings_path = Path.home() / '.factory' / 'settings.json'
factory_settings_path.parent.mkdir(parents=True, exist_ok=True)

try:
  factory_data = json.loads(factory_settings_path.read_text('utf-8')) if factory_settings_path.exists() else {}
except Exception:
  factory_data = {}

current = int(factory_data.get('maxBackgroundTasks', DEFAULT_V) or DEFAULT_V)

raw = "USER_CHOICE"  # replace with chosen value (or user's custom answer)
scope = "SCOPE_CHOICE"  # replace with: "Local (this project)" | "Global (all projects)" (or flags)
raw_s = str(raw).strip().lower()
if raw_s.startswith('keep'):
  v = current
else:
  try:
    v = int(raw_s)
  except Exception:
    v = current

if v  MAX_V:
  v = MAX_V

# 1) Factory Droid settings (global)
factory_data['maxBackgroundTasks'] = v
factory_settings_path.write_text(json.dumps(factory_data, indent=2) + '\n', encoding='utf-8')
print('Set Factory maxBackgroundTasks to', v, 'in', factory_settings_path)

# 2) OMD config (local or global)
scope_s = str(scope).strip().lower()
if scope_s.startswith('local'):
  omd_config_path = Path.cwd() / '.factory' / 'droid.jsonc'
else:
  xdg = Path(os.environ.get('XDG_CONFIG_HOME') or (Path.home() / '.config'))
  omd_config_path = xdg / 'oh-my-droid' / 'config.jsonc'

omd_config_path.parent.mkdir(parents=True, exist_ok=True)

try:
  omd_data = parse_jsonc_file(omd_config_path)
except Exception as e:
  print('Warning: could not parse OMD config; skipping update:', omd_config_path, '-', e)
  omd_data = None

if isinstance(omd_data, dict):
  perms = omd_data.get('permissions')
  if not isinstance(perms, dict):
    perms = {}
  perms['maxBackgroundTasks'] = v
  omd_data['permissions'] = perms
  omd_config_path.write_text(json.dumps(omd_data, indent=2) + '\n', encoding='utf-8')
  print('Set OMD permissions.maxBackgroundTasks to', v, 'in', omd_config_path)
PY

Step 2A: Local Configuration (--local flag or user chose LOCAL)

CRITICAL: This ALWAYS downloads fresh FACTORY.md from GitHub to the local project. DO NOT use the Write tool - use bash curl exclusively.

Create Local .factory Directory

# Create .factory directory in current project
mkdir -p .factory && echo ".factory directory ready"

Download Fresh FACTORY.md

# Extract old version before download
OLD_VERSION=$(grep -m1 "^# oh-my-droid" .factory/FACTORY.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")

# Backup existing FACTORY.md before overwriting (if it exists)
if [ -f ".factory/FACTORY.md" ]; then
  BACKUP_DATE=$(date +%Y-%m-%d)
  BACKUP_PATH=".factory/FACTORY.md.backup.${BACKUP_DATE}"
  cp .factory/FACTORY.md "$BACKUP_PATH"
  echo "Backed up existing FACTORY.md to $BACKUP_PATH"
fi

# Download fresh FACTORY.md from GitHub
curl -fsSL "https://raw.githubusercontent.com/MeroZemory/oh-my-droid/main/docs/FACTORY.md" -o .factory/FACTORY.md && \
echo "Downloaded FACTORY.md to .factory/FACTORY.md"

# Extract new version and report
NEW_VERSION=$(grep -m1 "^# oh-my-droid" .factory/FACTORY.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
if [ "$OLD_VERSION" = "none" ]; then
  echo "Installed FACTORY.md: $NEW_VERSION"
elif [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
  echo "FACTORY.md unchanged: $NEW_VERSION"
else
  echo "Updated FACTORY.md: $OLD_VERSION -> $NEW_VERSION"
fi

Note: The downloaded FACTORY.md includes Context Persistence instructions with `` tags for surviving conversation compaction.

Note: If an existing FACTORY.md is found, it will be backed up to .factory/FACTORY.md.backup.YYYY-MM-DD before downloading the new version.

MANDATORY: Always run this command. Do NOT skip. Do NOT use Write tool.

FALLBACK if curl fails: Tell user to manually download from: https://raw.githubusercontent.com/MeroZemory/oh-my-droid/main/docs/FACTORY.md

Verify Plugin Installation

grep -q "oh-my-droid" ~/.factory/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: droid /plugin install oh-my-droid@oh-my-droid"

Confirm Local Configuration Success

After completing local configuration, save progress and report:

# Save progress - Step 2 complete (Local config)
mkdir -p .omd/state
cat > ".omd/state/setup-state.json" /dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")

# Backup existing FACTORY.md before overwriting (if it exists)
if [ -f "$HOME/.factory/FACTORY.md" ]; then
  BACKUP_DATE=$(date +%Y-%m-%d)
  BACKUP_PATH="$HOME/.factory/FACTORY.md.backup.${BACKUP_DATE}"
  cp "$HOME/.factory/FACTORY.md" "$BACKUP_PATH"
  echo "Backed up existing FACTORY.md to $BACKUP_PATH"
fi

# Download fresh FACTORY.md to global config
curl -fsSL "https://raw.githubusercontent.com/MeroZemory/oh-my-droid/main/docs/FACTORY.md" -o ~/.factory/FACTORY.md && \
echo "Downloaded FACTORY.md to ~/.factory/FACTORY.md"

# Extract new version and report
NEW_VERSION=$(grep -m1 "^# oh-my-droid" ~/.factory/FACTORY.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
if [ "$OLD_VERSION" = "none" ]; then
  echo "Installed FACTORY.md: $NEW_VERSION"
elif [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
  echo "FACTORY.md unchanged: $NEW_VERSION"
else
  echo "Updated FACTORY.md: $OLD_VERSION -> $NEW_VERSION"
fi

Note: If an existing FACTORY.md is found, it will be backed up to ~/.factory/FACTORY.md.backup.YYYY-MM-DD before downloading the new version.

Clean Up Legacy Hooks (if present)

Check if old manual hooks exist and remove them to prevent duplicates:

# Remove legacy bash hook scripts (now handled by plugin system)
rm -f ~/.factory/hooks/keyword-detector.sh
rm -f ~/.factory/hooks/stop-continuation.sh
rm -f ~/.factory/hooks/persistent-mode.sh
rm -f ~/.factory/hooks/session-start.sh
echo "Legacy hooks cleaned"

Check ~/.factory/settings.json for manual hook entries. If the "hooks" key exists with UserPromptSubmit, Stop, or SessionStart entries pointing to bash scripts, inform the user:

> Note: Found legacy hooks in settings.json. These should be removed since the plugin now provides hooks automatically. Remove the "hooks" section from ~/.factory/settings.json to prevent duplicate hook execution.

Verify Plugin Installation

grep -q "oh-my-droid" ~/.factory/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: droid /plugin install oh-my-droid@oh-my-droid"

Confirm Global Configuration Success

After completing global configuration, save progress and report:

# Save progress - Step 2 complete (Global config)
mkdir -p .omd/state
cat > ".omd/state/setup-state.json" = 3, skip to Step 3.5.

The HUD shows real-time status in Factory Droid's status bar. **Invoke the hud skill** to set up and configure:

Use the Skill tool to invoke: `hud` with args: `setup`

This will:
1. Install the HUD wrapper script to `~/.factory/hud/omd-hud.mjs`
2. Configure `statusLine` in `~/.factory/settings.json`
3. Report status and prompt to restart if needed

After HUD setup completes, save progress:
```bash
# Save progress - Step 3 complete (HUD setup)
mkdir -p .omd/state
CONFIG_TYPE=$(cat ".omd/state/setup-state.json" 2>/dev/null | grep -oE '"configType":\s*"[^"]+"' | cut -d'"' -f4 || echo "unknown")
cat > ".omd/state/setup-state.json" /dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | sed 's/^v//')
  elif [ -f "$HOME/.factory/FACTORY.md" ]; then
    INSTALLED_VERSION=$(grep -m1 "^# oh-my-droid" "$HOME/.factory/FACTORY.md" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | sed 's/^v//')
  fi
fi

# Check npm for latest version
LATEST_VERSION=$(npm view oh-my-droid version 2>/dev/null)

if [ -n "$INSTALLED_VERSION" ] && [ -n "$LATEST_VERSION" ]; then
  # Simple version comparison (assumes semantic versioning)
  if [ "$INSTALLED_VERSION" != "$LATEST_VERSION" ]; then
    echo ""
    echo "UPDATE AVAILABLE:"
    echo "  Installed: v$INSTALLED_VERSION"
    echo "  Latest:    v$LATEST_VERSION"
    echo ""
    echo "To update, run: droid /plugin install oh-my-droid@oh-my-droid"
  else
    echo "You're on the latest version: v$INSTALLED_VERSION"
  fi
elif [ -n "$LATEST_VERSION" ]; then
  echo "Latest version available: v$LATEST_VERSION"
fi

Step 3.7: Enable Background Processes (Required)

Background processes are required for true parallel shell execution (e.g., running multiple long Execute commands concurrently).

This must be set globally in ~/.factory/settings.json (there is no per-project equivalent).

python3 -  "$CONFIG_FILE"
echo "Default execution mode set to: USER_CHOICE"

Note: This preference ONLY affects generic keywords ("fast", "parallel"). Explicit keywords ("ulw", "eco") always override this preference.

Step 3.9: Install CLI Analytics Tools (Optional)

The OMD CLI provides standalone token analytics commands (omd stats, omd agents, omd tui).

Ask user: "Would you like to install the OMD CLI for standalone analytics? (Recommended for tracking token usage and costs)"

Options:

1. Yes (Recommended) - Install CLI tools globally for omd stats, omd agents, etc.
2. No - Skip CLI installation, use only plugin skills

CLI Installation Note

The CLI (omc command) is no longer supported via npm/bun global install.

All functionality is available through the plugin system:

• Use /help for guidance
• Use /doctor for diagnostics

Skip this step - the plugin provides all features.

Step 4: Verify Plugin Installation

grep -q "oh-my-droid" ~/.factory/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: droid /plugin install oh-my-droid@oh-my-droid"

Step 5: Offer MCP Server Configuration

MCP servers extend Factory Droid with additional tools (web search, GitHub, etc.).

Ask user: "Would you like to configure MCP servers for enhanced capabilities? (Context7, Exa search, GitHub, etc.)"

If yes, invoke the mcp-setup skill:

/mcp-setup

If no, skip to next step.

Step 6: Detect Upgrade from 2.x

Check if user has existing configuration:

# Check for existing 2.x artifacts
ls ~/.factory/commands/ralph-loop.md 2>/dev/null || ls ~/.factory/commands/ultrawork.md 2>/dev/null

If found, this is an upgrade from 2.x.

Step 7: Show Welcome Message

For New Users:

OMD Setup Complete!

You don't need to learn any commands. I now have intelligent behaviors that activate automatically.

WHAT HAPPENS AUTOMATICALLY:
- Complex tasks -> I parallelize and delegate to specialists
- "plan this" -> I start a planning interview
- "don't stop until done" -> I persist until verified complete
- "stop" or "cancel" -> I intelligently stop current operation

MAGIC KEYWORDS (optional power-user shortcuts):
Just include these words naturally in your request:

| Keyword | Effect | Example |
|---------|--------|---------|
| ralph | Persistence mode | "ralph: fix the auth bug" |
| ralplan | Iterative planning | "ralplan this feature" |
| ulw | Max parallelism | "ulw refactor the API" |
| eco | Token-efficient mode | "eco refactor the API" |
| plan | Planning interview | "plan the new endpoints" |

**ralph includes ultrawork:** When you activate ralph mode, it automatically includes ultrawork's parallel execution. No need to combine keywords.

MCP S

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MeroZemory](https://github.com/MeroZemory)
- **Source:** [MeroZemory/oh-my-droid](https://github.com/MeroZemory/oh-my-droid)
- **License:** MIT

Install and usage instructions live in the source repository linked above.