{
  "version": "1.0.0",
  "description": "Common tool usage patterns for the Master Orchestrator",
  "patterns": [
    {
      "scenario": "Create a file on user's system",
      "approach": "spawn_worker or delegate_to_worker",
      "example": "spawn_worker('Create a file called example.txt on the desktop with content: Hello World')",
      "notes": "Never use bash echo/cat for file creation - delegate to worker"
    },
    {
      "scenario": "Read a file",
      "approach": "delegate_to_worker for complex, bash for simple",
      "example": "bash('cat ~/Desktop/example.txt') OR delegate_to_worker('Read and summarize the contents of ~/Projects/readme.md')",
      "notes": "Use bash for quick reads, delegate for analysis"
    },
    {
      "scenario": "Run a build or deployment",
      "approach": "spawn_worker (background)",
      "example": "spawn_worker('Run npm build in ~/Projects/my-app and report any errors')",
      "notes": "Non-blocking, check status with check_worker"
    },
    {
      "scenario": "Git operations",
      "approach": "bash for status/log, delegate for commits",
      "example": "bash('git status') then delegate_to_worker('Commit changes with message: Fix bug')",
      "notes": "Simple git commands via bash, complex operations via worker"
    },
    {
      "scenario": "Web research",
      "approach": "web_search + fetch_url",
      "example": "web_search('latest React 19 features') then fetch_url('https://react.dev/blog')",
      "notes": "Search first, then fetch specific pages for details"
    },
    {
      "scenario": "Multiple parallel tasks",
      "approach": "Multiple spawn_worker calls",
      "example": "spawn_worker('Task A'), spawn_worker('Task B'), spawn_worker('Task C')",
      "notes": "Workers run in parallel, use wait_worker to collect results"
    },
    {
      "scenario": "Remember user preferences",
      "approach": "remember with high importance",
      "example": "remember('User prefers dark mode and concise responses', importance=0.8)",
      "notes": "High importance = longer retention"
    },
    {
      "scenario": "Find user's project",
      "approach": "search_memory first",
      "example": "search_memory('connect app project path')",
      "notes": "Always check memory before asking user for paths"
    },
    {
      "scenario": "Preview worker outputs (images, code, files)",
      "approach": "Workers write files, gallery shows them automatically",
      "example": "spawn_worker('Create the image and save to ~/Lia-Hub/shared/outputs/') - gallery displays result",
      "notes": "NEVER use localhost servers for previews. The Connect web UI gallery handles all asset display in-app."
    },
    {
      "scenario": "Debug failing workers",
      "approach": "check_worker for status, list_workers for overview",
      "example": "check_worker('job_xxx') to see error details",
      "notes": "Workers may fail due to permissions, paths, or timeouts"
    }
  ],
  "antipatterns": [
    {
      "wrong": "Using bash to create/edit files directly",
      "right": "Delegate file operations to workers",
      "reason": "Workers have full Claude Code capabilities for safe file ops"
    },
    {
      "wrong": "Doing file operations yourself as orchestrator",
      "right": "Always delegate to workers",
      "reason": "Orchestrator focuses on understanding and coordinating"
    },
    {
      "wrong": "Blocking on spawn_worker completion",
      "right": "Use spawn_worker for background, delegate_to_worker for blocking",
      "reason": "spawn_worker returns immediately with job ID"
    },
    {
      "wrong": "Guessing file paths",
      "right": "Use search_memory or ask user",
      "reason": "Memory stores indexed filesystem, use it"
    },
    {
      "wrong": "Using start_local_server + open_browser for previews",
      "right": "Workers write to ~/Lia-Hub/shared/outputs/, gallery displays automatically",
      "reason": "Connect's web UI has a built-in gallery. localhost servers open random tabs and break UX."
    }
  ]
}