update-models

<mission>
Streamline the process of keeping AI model recommendations current by coordinating specialized agents for OpenRouter data collection and intelligent filtering, obtaining user validation, and distributing updates across all plugins.
</mission>

<user_request>
$ARGUMENTS
</user_request>

<instructions>
  <critical_constraints>
    <orchestrator_role mandatory="true">
      **STRICT Orchestrator Pattern Enforcement:**

      You MUST:
      - Use Task tool to delegate ALL data manipulation to agents
      - Use AskUserQuestion for user approval gate
      - Use Bash for running sync script and git commands
      - Use Read for file verification only
      - Use Glob/Grep for finding files

      You MUST NOT:
      - Use Write or Edit tools directly
      - Perform filtering, categorization, or file updates yourself
      - Manipulate data structures
      - Only coordinate workflow and make decisions about delegation

      **Rationale:** Orchestrators coordinate but never manipulate data. All data operations
      must be delegated to specialized agents with appropriate tool permissions.
    </orchestrator_role>

    <todowrite_requirement>
      You MUST use the TodoWrite tool to create and maintain a todo list throughout your orchestration workflow.

      **Before starting**, create a todo list with all 5 phases:
      1. PHASE 0: Initialization
      2. PHASE 1: Scrape and Filter Models
      3. PHASE 2: User Approval
      4. PHASE 3: Update Shared File
      5. PHASE 4: Sync to Plugins

      **Update continuously**:
      - Mark tasks as "in_progress" when starting
      - Mark tasks as "completed" immediately after finishing
      - Keep only ONE task as "in_progress" at a time
    </todowrite_requirement>

    <delegation_contract mandatory="true">
      **Strict Delegation Rules:**

      - ALL scraping → model-scraper agent
      - ALL filtering/deduplication/categorization → model-scraper agent
      - ALL file updates → model-scraper agent
      - Orchestrator only: coordinates, validates, approves, recovers from errors

      **Never violate this contract.** If you find yourself about to use Write/Edit,
      STOP and delegate to model-scraper instead.
    </delegation_contract>

    <user_approval_gate mandatory="true">
      You MUST present filtered model list to user before updating:

      - Show: model IDs, providers, categories, pricing
      - Allow user to: approve, modify, or reject
      - Do NOT proceed without approval
      - Support structured modification input (see knowledge section)
    </user_approval_gate>
  </critical_constraints>

  <core_principles>
    <principle name="Strict Orchestration Pattern" priority="critical">
      - Orchestrator coordinates but never manipulates data
      - All data operations delegated to specialized agents
      - Clear separation of concerns: orchestration vs implementation
      - Tool restrictions enforced: NO Write/Edit in orchestrator
    </principle>

    <principle name="Context-Aware Filtering" priority="high">
      Provide these filtering rules to model-scraper agent:

      1. **Anthropic Filter**: Exclude all Anthropic models (Claude available natively)
      2. **Provider Deduplication**: Max 1 per provider (keep top-ranked)
      3. **Category Balance**: Min 2 models per category (coding, reasoning, vision, budget)
      4. **Target Count**: 9-12 models
      5. **Diversity**: ≥5 different providers

      **Category Balance Override:**
      - If category has <2 models after deduplication, allow 2nd model from that provider
      - Priority: Category diversity > Provider deduplication
    </principle>

    <principle name="Safe Updates" priority="high">
      - Always read existing file first for verification
      - Create backup before sync
      - Rollback on any failure
      - Preserve existing file if update fails
      - User approval required before modifications
    </principle>

    <principle name="Error Recovery with Retry Limits" priority="high">
      - Handle scraping failures gracefully (max 3 attempts)
      - Rollback on sync script errors
      - Partial sync recovery (continue with successful, retry failures)
      - Log all errors for debugging
      - User decision gates for ambiguous failures
    </principle>
  </core_principles>

  <workflow>
    <phase number="0" name="Initialization">
      <objective>Set up workflow tracking and validate prerequisites</objective>

      <steps>
        <step>Create TodoWrite with all 5 phases</step>
        <step>Mark PHASE 0 as in_progress</step>
        <step>Check if model-scraper agent available:
          ```bash
          test -f .claude/agents/model-scraper.md
          ```
        </step>
        <step>Check if sync script exists:
          ```bash
          test -f scripts/sync-shared.ts
          ```
        </step>
        <step>Check if shared models file exists:
          ```bash
          test -f shared/recommended-models.md
          ```
        </step>
        <step>Read existing shared/recommended-models.md to cache current state</step>
        <step>Mark PHASE 0 as completed</step>
        <step>Mark PHASE 1 as in_progress</step>
      </steps>

      <quality_gate>
        All prerequisites validated:
        - model-scraper agent exists
        - sync script exists
        - shared models file exists
      </quality_gate>

      <error_recovery>
        - If model-scraper missing: Report error, suggest creating agent first
        - If sync script missing: Report error, stop workflow
        - If shared file missing: Report error, suggest manual creation
      </error_recovery>
    </phase>

    <phase number="1" name="Scrape and Filter Models">
      <objective>Get latest model rankings from OpenRouter and apply intelligent filtering</objective>

      <steps>
        <step>Launch model-scraper agent via Task tool with filtering rules:
          ```
          Prompt: "Scrape trending programming models from OpenRou