hack/tools/scripts/llm-key-hunter/results/_cache/content/aaronjullger-lgtm_panacea.json

{"repo": "aaronjullger-lgtm/panacea", "files": {".claude/multi-agent/USAGE_GUIDE.md": {"08d103d90b243680f7074d03ff437fb0ca6165f4": {"t": 1786068455.4339416, "n": 11986, "h": "2d4d66f33d47f463", "c": "# Multi-Agent Orchestrator — Step-by-Step Usage Guide\n\nThis guide walks you through setting up and using the PANaCEa multi-agent orchestrator from scratch. It coordinates five AI models — GLM, Gemini, OpenAI, DeepSeek, and Claude — to plan, review, implement, and validate code changes through a single CLI.\n\n\n## Step 1: Initial Setup\n\nNavigate to the orchestrator directory and run the setup script. This creates your `.env` file, installs dependencies, initializes the queue and state files, and sets hook permissions.\n\n```bash\ncd .claude/multi-agent\nbash setup.sh\n```\n\nYou should see output confirming each step. If `httpx` fails to install automatically, install it manually:\n\n```bash\npip3 install httpx --break-system-packages\n```\n\n\n## Step 2: Add Your API Keys\n\nOpen the `.env` file created by setup and replace the placeholder values with your real API keys:\n\n```bash\nnano .env\n```\n\nYou need keys for these providers:\n\n| Provider | Key name | Where to get it |\n|----------|----------|----------------|\n| Zhipu (GLM) | `ZHIPU_API_KEY` | https://open.bigmodel.cn/ |\n| OpenAI | `OPENAI_API_KEY` | https://platform.openai.com/api-keys |\n| Google Gemini | `GEMINI_API_KEY` | https://aistudio.google.com/apikey |\n| DeepSeek | `DEEPSEEK_API_KEY` | https://platform.deepseek.com/ |\n| Anthropic (Claude) | `ANTHROPIC_API_KEY` | https://console.anthropic.com/ |\n\nThe Anthropic key is optional if you're running Claude Code directly (it uses its own auth). All others are required.\n\n\n## Step 3: Verify Provider Connections\n\nRun a health check to confirm all providers can reach their APIs:\n\n```bash\npython3 orchestrator.py health\n```\n\nThis sends a tiny \"Reply with OK\" test to each model. You'll see a pass/fail for each provider. If one fails, double-check that API key in your `.env`.\n\n\n## Step 4: Run Your First Full Pipeline\n\nThe `pipeline` command is the main way to use the orchestrator. It runs all four phases automatically:\n\n```bash\npython3 orchestrator.py pipeline \"Add error boundary component to DrillShell.tsx\"\n```\n\nHere's what happens behind the scenes:\n\n1. **Phase 1 — Planning (Gemini `gemini-3.1-pro`):** Creates a step-by-step execution plan with architecture considerations, dependencies, and risks.\n\n2. **Phase 2 — Review (OpenAI `gpt-4.1`):** Reviews the plan for bugs, edge cases, regressions, and suggests exact fixes.\n\n3. **Phase 3 — Implementation (GLM `glm-5.1`):** Writes the actual code, guided by the plan and the review findings. In safe mode (default), this phase pauses and asks for your approval before running.\n\n4. **Phase 4 — Overseer (Claude `claude-sonnet-4-6`):** Synthesizes all outputs, validates correctness, checks for conflicts, and issues a final APPROVE / REJECT / NEEDS_REVISION verdict. This phase is mandatory — if Claude can't validate, the entire pipeline is marked as failed.\n\nWhen the pipeline finishes, you'll see a summary showing how many characters each phase produced and whether it succeeded.\n\n\n## Step 5: Approve Code Tasks (Safe Mode)\n\nBy default, the orchestrator runs in `safe_automatic` mode. This means planning, reviewing, and oversight run automatically, but code-writing tasks pause for your approval.\n\nWhen a code task is pending, you'll see a message like:\n\n```\n⏳ Code task a1b2c3d4 needs approval.\n   Run: python3 orchestrator.py approve a1b2c3d4\n```\n\nTo approve it:\n\n```bash\npython3 orchestrator.py approve a1b2c3d4\n```\n\nTo reject it instead:\n\n```bash\npython3 orchestrator.py reject a1b2c3d4 --reason \"I want a different approach\"\n```\n\nAfter approving, run the pipeline again or use `run` to dispatch it:\n\n```bash\npython3 orchestrator.py run\n```\n\n\n## Step 6: Skip Pipeline Phases (Optional)\n\nYou don't always need all four phases. Use flags to skip:\n\n```bash\n# Skip the review phase (just plan → code → overseer)\npython3 orchestrator.py pipeline \"Quick typo fix in README\" --no-review\n\n# Skip the planning phase (just review → code → overseer)\npython3 orchestrator.py pipeline \"Implement this from the existing plan\" --no-planning\n\n# Skip both (just code → overseer)\npython3 orchestrator.py pipeline \"Simple one-liner fix\" --no-review --no-planning\n```\n\nThe Claude overseer phase can never be skipped. Every pipeline must pass through Claude validation.\n\n\n## Step 7: Enqueue Tasks to Specific Models\n\nInstead of running a full pipeline, you can send a task directly to a specific model:\n\n```bash\n# Send a code review to OpenAI\npython3 orchestrator.py enqueue code_review \"Review the FSRS pipeline changes in lib/fsrs.ts\"\n\n# Send a planning task to Gemini\npython3 orchestrator.py enqueue planning \"Plan the OSCE simulator refactor\"\n\n# Send a coding task to GLM\npython3 orchestrator.py enqueue code_implementation \"Add loading skeleton to QuizView.tsx\"\n\n# Send a research task to OpenAI (uses gpt-4.1-mini automatically)\npython3 orchestrator.py enqueue research \"What's the best approach for WebSocket reconnection?\"\n\n# Send to a specific model by key\npython3 orchestrator.py enqueue code_implementation \"Write unit tests\" --model deepseek\n```\n\nAfter enqueueing, the task appears in the queue. Use `run` to dispatch it:\n\n```bash\npython3 orchestrator.py run\n```\n\n\n## Step 8: Check Queue and State\n\nSee what's in the queue, what's pending approval, and recent events:\n\n```bash\npython3 orchestrator.py status\n```\n\nThis outputs JSON showing the current state, queue stats, pending messages, approved messages, and the last 10 events.\n\n\n## Step 9: Understand Task-Aware Model Selection\n\nThe orchestrator automatically picks the best model variant for each task type. You don't need to do anything — this happens behind the scenes. Here's what gets selected:\n\n| When you enqueue... | The orchestrator uses... | Why |\n|---------------------|-------------------------|-----|\n| `code_implementation` to GLM | `glm-5.1` | Full model for heavy coding |\n| `test_generation` to GLM | `glm-5-turbo` | Fast model for lighter test writing |\n| `code_review` to OpenAI | `gpt-4.1` | Full model for thorough review |\n| `research` to OpenAI | `gpt-4.1-mini` | Faster, cheaper for lookups |\n| `planning` to Gemini | `gemini-3.1-pro` | Full model for architecture plans |\n| `critique` to Gemini | `gemini-2.5-flash` | Fast model for quick feedback |\n| `architecture_review` to DeepSeek | `deepseek-reasoner` | Deep reasoning for analysis |\n| `code_implementation` to DeepSeek | `deepseek-chat` | Fast chat model for coding |\n| Any overseer task to Claude | `claude-sonnet-4-6` | Always the full model |\n\nTo customize these mappings, edit the `model_variants` section in `config/settings.json`. For example, to make GLM always use the turbo model for refactoring:\n\n```json\n\"refactor\": {\n  \"zhipu\": \"glm-5-turbo\"\n}\n```\n\n\n## Step 10: Use Safety Controls\n\nThe orchestrator has several safety mechanisms:\n\n**Emergency stop** — halts all operations immediately:\n\n```bash\npython3 orchestrator.py stop\n```\n\nThis creates a `state/STOP` file. No messages will be dispatched until you resume:\n\n```bash\npython3 orchestrator.py resume\n```\n\n**Automatic protections** (always active, configurable in `config/settings.json`):\n\n- Loop depth limit (default: 5) prevents infinite prompt chains\n- Auto-turn limit (default: 3) forces human interaction\n- Thread message limit (default: 50) caps thread length\n- Stale message TTL (default: 120 min) rejects old messages\n- Dedup window (default: 30 sec) blocks duplicate submissions\n- Blocked categories: `git_force_push`, `branch_delete_main`, and `env_modification` are never auto-executed\n\n\n## Step 11: Switch Operating Modes\n\nThe orchestrator has two modes. Change by editing `config/settings.json`:\n\n**`safe_automatic` (default):** Planning, reviewing, and oversight run automatically. Code writing, refactoring, and git commits require manual approval.\n\n**`aggressive_automatic`:** Everything runs automatically except git commits, pushes, and file deletes. Use this when you trust the pipeline and want speed.\n\n```json\n\"mode\": \"aggressive_automatic\"\n```\n\nYou can also override the mode via environment variable:\n\n```bash\nORCHESTRATOR_MODE=aggressive_automatic python3 orchestrator.py pipeline \"Your task\"\n```\n\n\n## Step 12: Install Claude Code Hooks (Optional)\n\nHooks integrate the orchestrator into your Claude Code session so tasks are automatically brokered when you use Claude Code:\n\n```bash\npython3 scripts/install_hooks.py\n```\n\nOr manually add to your `.claude/settings.local.json`:\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [{\n      \"matcher\": \"\",\n      \"hooks\": [{\"type\": \"command\", \"command\": \"bash .claude/multi-agent/hooks/session_start_context.sh\", \"timeout\": 5}]\n    }],\n    \"PostToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [{\"type\": \"command\", \"command\": \"bash .claude/multi-agent/hooks/post_task_broker.sh\", \"timeout\": 5, \"async\": true}]\n    }],\n    \"PreToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [{\"type\": \"command\", \"command\": \"bash .claude/multi-agent/hooks/pre_tool_safety.sh\", \"timeout\": 5}]\n    }]\n  }\n}\n```\n\n- **SessionStart:** Generates a repo context snapshot when a Claude Code session begins.\n- **PostToolUse:** After a Bash command, checks if the result should be brokered to another model.\n- **PreToolUse:** Safety gate that can block dangerous operations.\n\n\n## Step 13: Read the Logs\n\nAll events are logged to `logs/events.jsonl` as structured JSON. Each entry includes timestamps, model identity, contract scores, and variant selections.\n\nTo see recent events:\n\n```bash\ntail -20 logs/events.jsonl | python3 -m json.tool\n```\n\nLook for these event types:\n\n- `dispatch` — a message was sent to a provider\n- `response` — a provider returned a result\n- `identity` — flags when `actual_backend` differs from `target_model` (e.g., GLM behind Claude Code slot)\n- `variant_selection` — when a task-specific model variant was chosen (e.g., `glm-5-turbo` instead of `glm-5.1`)\n- `contract` — output contract conformance score (0.0–1.0)\n- `safety` — safety check pass/fail events\n- `error` — something went wrong\n\n\n## Quick Reference: All Commands\n\n```bash\n# ── Full pipeline ──\npython3 orchestrator.py pipeline \"Your task\"\npython3 orchestrator.py pipeline \"Your task\" --no-review\npython3 orchestrator.py pipeline \"Your task\" --no-planning\npython3 orchestrator.py pipeline \"Your task\" --no-review --no-planning\n\n# ── Single-task dispatch ──\npython3 orchestrator.py enqueue <task_type> \"Description\"\npython3 orchestrator.py enqueue <task_type> \"Description\" --model <model_key>\npython3 orchestrator.py run\n\n# ── Queue management ──\npython3 orchestrator.py status\npython3 orchestrator.py approve <msg_id>\npython3 orchestrator.py reject <msg_id> --reason \"explanation\"\n\n# ── Safety ──\npython3 orchestrator.py stop\npython3 orchestrator.py resume\npython3 orchestrator.py health\n```\n\nValid `<task_type>` values: `code_implementation`, `refactor`, `test_generation`, `planning`, `architecture_review`, `risk_analysis`, `code_review`, `research`, `alternate_implementation`, `critique`, `synthesis`, `validation`, `supervisor_review`, `overseer`.\n\nValid `<model_key>` values: `claude_code_glm`, `gemini`, `openai`, `deepseek`, `claude`.\n\n\n## Troubleshooting\n\n**\"No provider found for model: X\"** — The model key doesn't match anything in `config/settings.json`. Check the `models` section for valid keys.\n\n**Pipeline hangs at code phase** — You're in `safe_automatic` mode and the code task needs approval. Run `python3 orchestrator.py status` to find the pending message ID, then `python3 orchestrator.py approve <id>`.\n\n**\"PIPELINE FAILED: mandatory Claude overseer did not complete\"** — The Claude API call failed (key missing, rate limited, or network issue). Check your `ANTHROPIC_API_KEY` in `.env` and run `python3 orchestrator.py health`.\n\n**\"All 3 attempts failed\"** — The provider returned retryable errors (429, 5xx) on all retry attempts. Wait a minute and try again, or check your API quota.\n\n**Provider health check fails** — Confirm the API key is set in `.env` (not still a placeholder value like `your_key_here`). Restart your terminal if you just edited `.env`.\n"}}}}