feat: add mode subtitles (descriptions) to all 90 pre-loaded custom modes

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Roo+ Changelog
 
+## [3.73.0] — 2026-07-27
+
+### Minor — Mode Subtitles (Descriptions) Completed
+
+#### 🚀 Enhancements
+
+- **Mode Descriptions** — Added `description:` (subtitle) fields to all 90 custom mode entries in [`.roomodes`](.roomodes) that were missing them. All 97 pre-loaded modes now display descriptive subtitles in the mode selector UI. (Closes: #39)
+- **Agent Source Descriptions** — Added `description:` fields to all 233 agent source YAML files in `custom-modes/agents/`, fixing the root cause where the upstream schema omitted descriptions entirely.
+- **Agent Catalog Alignment** — Audit confirmed 233 total agents: 90 pre-loaded in `.roomodes` (all described), 143 available for import via the `agents/` submodule. See [`custom-modes/AGENT_CATALOG.md`](custom-modes/AGENT_CATALOG.md) for the full list.
+
+#### ✅ Quality
+
+- YAML validation passed — all 97 mode entries parse correctly
+- Lint passed — zero warnings
+
+---
+
 ## [3.72.1] — 2026-07-27
 
 ### Patch — Semble Binary Download Fix, Configurable Path, Multi-Source Fallback

scripts/add_descriptions.py

@@ -0,0 +1,171 @@
+"""
+Add description fields to all modes in .roomodes that are missing them.
+"""
+import re
+
+# Curated descriptions from plans/modes-subtitles-plan.md
+CURATED_DESCRIPTIONS = {
+    "ai-engineer": "Expert in AI system design, model implementation, and production deployment",
+    "machine-learning-engineer": "Expert in production model deployment, serving infrastructure, and scalable ML systems",
+    "llm-architect": "Expert in large language model architecture, deployment, and optimization",
+    "prompt-engineer": "Expert in designing, optimizing, and managing prompts for large language models",
+    "rag-evaluator": "Builds evaluation suites for retrieval quality, guardrails, and safety",
+    "business-analyst": "Expert in requirements gathering, process improvement, and data-driven decision making",
+    "customer-success-manager": "Expert in customer retention, growth, and advocacy",
+    "i18n-l10n-reviewer": "Ensures localization readiness, translation quality, and accessibility of content across locales",
+    "technical-writer": "Expert in clear, accurate documentation and content creation",
+    "ux-researcher": "Expert in user insights, usability testing, and data-driven design decisions",
+    "growth-experimentation-lead": "Orchestrates high-velocity tests, growth loops, and measurable revenue impact",
+    "marketing-strategist": "Elite strategist in digital marketing, growth hacking, brand development, and data-driven campaigns",
+    "product-manager": "Expert in product strategy, user-centric development, and business outcomes",
+    "sales-engineer": "Expert in technical pre-sales, solution architecture, and proof of concepts",
+    "architect-reviewer": "Expert in system design validation, architectural patterns, and technical decision assessment",
+    "microservices-architect": "Distributed systems architect designing scalable microservice ecosystems",
+    "backend-developer": "Senior backend engineer specializing in scalable API development and microservices",
+    "frontend-developer": "Expert UI engineer focused on crafting robust, scalable frontend solutions",
+    "fullstack-developer": "End-to-end feature owner with expertise across the entire stack",
+    "algorithmic-problem-solver": "Designs and implements optimal algorithms with focus on correctness and complexity",
+    "api-designer": "API architecture expert designing scalable, developer-friendly interfaces",
+    "ask": "Task-formulation guide that helps users navigate, ask, and delegate tasks",
+    "blockchain-developer": "Elite blockchain developer specializing in 2026 Web3 technologies",
+    "compiler-engineer": "Designs and optimizes compilers and toolchains",
+    "content-strategist": "Expert Content Strategy specialist with research capabilities",
+    "deep-research-protocol": "Systematic research analyst producing publication-ready reports",
+    "functional-programming-expert": "Designs purely functional, composable systems with strong types",
+    "integration": "Merges outputs of all modes into working, tested, production-ready systems",
+    "mcp": "MCP integration specialist for connecting to and managing external services",
+    "mobile-developer": "Cross-platform mobile specialist building performant native experiences",
+    "performance-engineer": "Expert in system optimization, bottleneck identification, and scalability",
+    "post-deployment-monitoring-mode": "Observes system post-launch, collecting performance, logs, and user feedback",
+    "refinement-optimization-mode": "Refactors, modularizes, and improves system performance",
+    "sdk-developer": "Designs developer-friendly SDKs with ergonomic APIs and strong typing",
+    "ui-expert": "Expert UI/UX Designer with mastery over interface design principles",
+    "web-design-specialist": "Expert in modern web development, UI/UX, accessibility, and performance",
+    "cloud-architect": "Expert in multi-cloud strategies, scalable architectures, and cost-effective solutions",
+    "database-administrator": "Expert in high-availability systems, performance optimization, and disaster recovery",
+    "deployment-engineer": "Expert in CI/CD pipelines, release automation, and deployment strategies",
+    "devops-architect": "Elite specialist in cloud-native infrastructure, CI/CD automation, and platform engineering",
+    "devops-engineer": "Expert bridging development and operations with comprehensive automation",
+    "finops-optimizer": "Drives cloud cost efficiency through rightsizing, commitment management, and architecture improvements",
+    "observability-architect": "Defines SLI/SLOs, golden signals, and telemetry standards for reliable systems",
+    "network-engineer": "Expert in cloud and hybrid network architectures, security, and performance optimization",
+    "sql-pro": "Expert in complex query optimization, database design, and performance tuning",
+    "compliance-specialist": "Meticulous specialist in regulatory adherence across multiple jurisdictions",
+    "corporate-law": "Elite specialist in securities law, M&A, corporate governance, and business transactions",
+    "intellectual-property": "Elite specialist in patents, trademarks, copyrights, and trade secrets",
+    "oss-license-auditor": "Enforces license policy via SBOMs, license detection, and remediation guidance",
+    "agent-organizer": "Expert in multi-agent orchestration, team assembly, and workflow optimization",
+    "build-engineer": "Expert in build system optimization, compilation strategies, and productivity",
+    "bullshit-detection-analyst": "Expert in identifying misinformation using evidence-based verification",
+    "competitive-analyst": "Expert in competitor intelligence, strategic analysis, and market positioning",
+    "data-analyst": "Expert in business intelligence, data visualization, and statistical analysis",
+    "data-engineer": "Expert in building scalable data pipelines and data infrastructure",
+    "database-optimizer": "Expert in query optimization, performance tuning, and scalability",
+    "dependency-manager": "Expert in package management, security auditing, and version conflict resolution",
+    "documentation-engineer": "Expert in technical documentation systems and developer-friendly content",
+    "error-coordinator": "Expert in distributed error handling, failure recovery, and system resilience",
+    "feature-flag-orchestrator": "Manages safe rollouts, kill-switches, and debt cleanup",
+    "git-workflow-manager": "Expert in branching strategies, automation, and team collaboration",
+    "knowledge-synthesizer": "Expert in extracting insights from multi-agent interactions",
+    "market-researcher": "Expert in market analysis, consumer insights, and competitive intelligence",
+    "multi-agent-coordinator": "Expert in complex workflow orchestration and inter-agent communication",
+    "refactoring-specialist": "Expert mastering safe code transformation and design pattern application",
+    "release-governance-lead": "Ensures every release meets quality, security, and compliance gates",
+    "task-distributor": "Expert in intelligent work allocation, load balancing, and queue management",
+    "website-foundation-planner": "Plans directory structure and best-practice alignment for new website projects",
+    "workflow-orchestrator": "Expert in complex process design, state machine implementation, and automation",
+    "code-reviewer": "Expert in code quality, security vulnerabilities, and best practices",
+    "code-skeptic": "Skeptical and critical code quality inspector who questions everything",
+    "cybersecurity-expert": "Elite specialist in threat detection, vulnerability assessment, and security architecture",
+    "penetration-tester": "Expert in ethical hacking, vulnerability assessment, and security testing",
+    "secrets-hygiene-auditor": "Eliminates hardcoded secrets, enforces rotation, and ensures secure management",
+    "security-auditor": "Expert in comprehensive security assessments, compliance validation, and risk management",
+    "zero-trust-strategist": "Implements identity-centric access, continuous verification, and micro-segmentation",
+    "qa-expert": "Expert in comprehensive quality assurance, test strategy, and quality metrics",
+    "tdd": "Implements Test-Driven Development, writing tests first",
+    "test-automator": "Expert in building robust test frameworks and CI/CD integration",
+    "agentic-swarm-conductor": "Hive-Mind Orchestrator & Stuck-State Recovery Specialist",
+    "problem-solving-maestro": "Master of All Heuristics and Systemic Intervention",
+    "uiux-vibe-master": "Aesthetic Intelligence and Zero-Accident Layout Enforcer",
+    "anti-fiction-sentinel": "Truth Enforcer and Neuro-Symbolic Verifier",
+    "core-reasoning-architect": "Immutable foundation of all reasoning",
+    "fintech-engineer": "Expert in financial systems, regulatory compliance, and secure transaction processing",
+    "creative-director": "Elite specialist in brand identity, digital experiences, and creative campaign development",
+    "financial-analyst": "Elite specialist in financial modeling, investment analysis, and risk assessment",
+    "payment-integration": "Expert in payment gateway integration, PCI compliance, and financial transactions",
+    "risk-manager": "Expert in comprehensive risk assessment, mitigation strategies, and compliance",
+    "iot-engineer": "Expert in connected device architectures, edge computing, and IoT platforms",
+}
+
+
+def process_roomodes(filepath):
+    with open(filepath, 'r') as f:
+        lines = f.readlines()
+
+    output = []
+    i = 0
+    modified_count = 0
+    already_had_count = 0
+    skipped_count = 0
+
+    while i < len(lines):
+        line = lines[i]
+        slug_match = re.match(r'  - slug: (\S+)', line)
+
+        if slug_match:
+            slug = slug_match.group(1)
+
+            if slug in CURATED_DESCRIPTIONS:
+                desc = CURATED_DESCRIPTIONS[slug]
+
+                # Find the name: line and description within this mode block
+                name_line_idx = None
+                has_desc = False
+                block_end = len(lines)
+
+                for j in range(i + 1, len(lines)):
+                    next_line = lines[j]
+                    # Stop if we hit the next mode entry or end
+                    if next_line.startswith('  - slug:'):
+                        block_end = j
+                        break
+                    if next_line.startswith('    name:'):
+                        name_line_idx = j
+                    if next_line.startswith('    description:'):
+                        has_desc = True
+
+                if name_line_idx is not None and not has_desc:
+                    # Output lines from current position up to and including name
+                    output.extend(lines[i:name_line_idx + 1])
+                    # Insert description
+                    output.append(f'    description: {desc}\n')
+                    modified_count += 1
+                    # Move past the name line
+                    i = name_line_idx + 1
+                elif name_line_idx is not None and has_desc:
+                    already_had_count += 1
+                    # Pass through all lines until block end or next slug
+                    output.extend(lines[i:block_end])
+                    i = block_end
+                else:
+                    skipped_count += 1
+                    output.append(line)
+                    i += 1
+            else:
+                output.append(line)
+                i += 1
+        else:
+            output.append(line)
+            i += 1
+
+    with open(filepath, 'w') as f:
+        f.writelines(output)
+
+    return modified_count, already_had_count, skipped_count
+
+
+if __name__ == '__main__':
+    count, existing, skipped = process_roomodes('.roomodes')
+    print(f"Modified modes (added description): {count}")
+    print(f"Already had description: {existing}")
+    print(f"Skipped (no name line found): {skipped}")

scripts/fix_missing_descriptions.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Add description fields to all agent source YAML files in custom-modes/agents/.
+
+For each .yaml file, derives a description from the roleDefinition field and
+inserts it after the 'name:' line.
+"""
+
+import os
+import re
+import glob
+import sys
+
+AGENTS_DIR = os.path.join(os.path.dirname(__file__), '..', 'custom-modes', 'agents')
+
+
+def derive_description(role_definition: str) -> str:
+    """
+    Derive a concise description from the roleDefinition string.
+
+    Rules:
+    - Take the first sentence
+    - Remove "You are an " or "You are a " prefix
+    - Keep under 120 characters
+    - Sentence case, no trailing period
+    - Make it unique and descriptive
+    """
+    # Get the first sentence
+    # First, handle em-dash cases: "You are the X — the Y."
+    # We want to capture the full description
+    text = role_definition.strip()
+
+    # Split into sentences (handle various sentence endings)
+    # Look for period, exclamation, question mark followed by space or end
+    sentences = re.split(r'(?<=[.!?])\s+', text)
+    first_sentence = sentences[0].strip() if sentences else text
+
+    # Remove trailing punctuation for processing
+    first_sentence = first_sentence.rstrip('.!?')
+
+    # Remove "You are an " or "You are a " or "You are " prefix (case insensitive)
+    prefix_patterns = [
+        r'^You are an\s+',
+        r'^You are a\s+',
+        r'^You are\s+',
+    ]
+    for pattern in prefix_patterns:
+        if re.match(pattern, first_sentence, re.IGNORECASE):
+            first_sentence = re.sub(pattern, '', first_sentence, flags=re.IGNORECASE)
+            break
+
+    # Handle "the X — the Y" pattern after "You are" removal
+    # e.g., "the Hive-Mind Orchestrator and Stuck-State Recovery Specialist."
+    # Already looks good after prefix removal
+
+    # Ensure we start with a capital letter
+    if first_sentence and first_sentence[0].islower():
+        first_sentence = first_sentence[0].upper() + first_sentence[1:]
+
+    # Trim to under 120 characters
+    if len(first_sentence) > 120:
+        # Try to cut at the last space before 120
+        truncated = first_sentence[:117]
+        last_space = truncated.rfind(' ')
+        if last_space > 30:  # Only cut at a word boundary if it's reasonable
+            first_sentence = first_sentence[:last_space]
+        else:
+            first_sentence = truncated
+
+    first_sentence = first_sentence.strip()
+
+    # Remove any trailing period that might remain
+    first_sentence = first_sentence.rstrip('.')
+
+    return first_sentence
+
+
+def process_file(filepath: str) -> bool:
+    """Process a single YAML file. Returns True if modified."""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        lines = f.readlines()
+
+    # Check if description already exists
+    for line in lines:
+        if line.strip().startswith('description:'):
+            print(f"  SKIP (already has description): {filepath}")
+            return False
+
+    # Find name: line and roleDefinition: line
+    name_line_idx = None
+    role_def_line = None
+
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith('name:'):
+            name_line_idx = i
+        elif stripped.startswith('roleDefinition:'):
+            # Get the full roleDefinition, which may span multiple lines
+            role_def_value = stripped[len('roleDefinition:'):].strip()
+            # Remove leading/trailing quotes
+            role_def_value = role_def_value.strip('"\'')
+            role_def_line = role_def_value
+            # If roleDefinition value continues on next lines (quoted multiline),
+            # we need to handle it, but for most files it's a single line
+            if role_def_value == '' or role_def_value.endswith('\\'):
+                # Multiline - collect continuation
+                j = i + 1
+                while j < len(lines):
+                    cont = lines[j].strip()
+                    if cont.startswith('groups:') or cont.startswith('customInstructions:'):
+                        break
+                    if cont and not cont.startswith('#') and not cont.startswith('  '):
+                        break
+                    # Handle continuation lines in quotes
+                    role_def_line += ' ' + cont.strip().strip('"\'')
+                    j += 1
+            break
+
+    if name_line_idx is None:
+        print(f"  ERROR: No 'name:' found in {filepath}")
+        return False
+
+    if role_def_line is None:
+        print(f"  ERROR: No 'roleDefinition:' found in {filepath}")
+        return False
+
+    description = derive_description(role_def_line)
+
+    # Determine where to insert the description line
+    # Insert after the name: line
+    insert_idx = name_line_idx + 1
+
+    # Build indentation for the description line
+    name_line = lines[name_line_idx]
+    indent = ''
+    for ch in name_line:
+        if ch == ' ':
+            indent += ch
+        else:
+            break
+
+    desc_line = f"{indent}description: {description}\n"
+
+    # Insert the description line
+    new_lines = lines[:insert_idx] + [desc_line] + lines[insert_idx:]
+
+    with open(filepath, 'w', encoding='utf-8') as f:
+        f.writelines(new_lines)
+
+    print(f"  OK: {os.path.relpath(filepath, AGENTS_DIR)} -> \"{description}\"")
+    return True
+
+
+def main():
+    yaml_files = []
+    for root, dirs, files in os.walk(AGENTS_DIR):
+        for f in files:
+            if f.endswith('.yaml') or f.endswith('.yml'):
+                yaml_files.append(os.path.join(root, f))
+
+    yaml_files.sort()
+    print(f"Found {len(yaml_files)} YAML files in {AGENTS_DIR}")
+
+    modified = 0
+    skipped = 0
+    errors = 0
+
+    for filepath in yaml_files:
+        try:
+            if process_file(filepath):
+                modified += 1
+            else:
+                skipped += 1
+        except Exception as e:
+            print(f"  ERROR processing {filepath}: {e}")
+            errors += 1
+
+    print(f"\nDone. Modified: {modified}, Skipped: {skipped}, Errors: {errors}")
+    return 0 if errors == 0 else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())