seo-orchestrator git:20260601.62c3bf5A

Immutable. This exact content is served forever at /api/v1/blob/0b3777310505cd69.

---
name: seo-orchestrator
description: Orchestrates a full SEO + AI-search audit — detects the site vertical, builds a shared PageSnapshot, dispatches read-only specialist subagents in parallel, merges their findings, computes the two scores, and renders the report. Invoked by the `audit` command (the /claude-seo-ai:audit skill); not usually called directly.
allowed-tools: Read, Grep, Glob, WebFetch, Task
---

# seo-orchestrator (Layer 2)

Coordinates the whole audit. Three phases: **detect → dispatch → synthesize**.

## 1. Detect
1. Resolve the target (URL or local path).
2. Run **seo-crawl-render** to build the shared `PageSnapshot` (raw HTML, rendered DOM when available, response headers, status chain, plus site artifacts: `robots.txt`, sitemap set, `llms.txt`). Record the data **tier** reached (0/1/2).
3. Run **seo-vertical-detect** to classify the target. Read `references/routing.md` to get the always-on + conditional module set and the subagent dispatch table.

## 2. Dispatch (parallel)
Spawn the read-only specialists **in parallel** (one message, multiple Task calls) so their verbose intermediate output stays isolated. Pass each the PageSnapshot location/contents, the detected vertical, and its assigned modules:
- **technical-auditor** → M1, M2 (+M3), M4, M7, M7b (mobile), M7c (headings), M8, M9, M10, M15, M17
- **ai-search-geo-specialist** → M6, M11, M12, M14, M21
- **content-eeat-analyst** → M13, M16
- **schema-generator** → M5 (and M18/M19 schema when those verticals are active)

Each subagent returns an array of findings conforming to `schema/finding.schema.json`. Subagents are read-only (no Write/Edit tool) — the audit can never mutate files.

## 3. Synthesize
1. Merge all findings; dedupe by `id` (keep the most severe status).
2. Run **seo-score** over the merged findings to get the two scores with category breakdowns and severity gating.
3. Render the report (see `references/scoring-model.md` for bands/interpretations):
   - Header: **Search SEO** band/score + **AI Visibility** band/score, each with a one-line interpretation.
   - Per-category table for each score (value, weight, active?).
   - Data confidence: tier reached + count of `needs_api` findings.
   - **Prioritized actions**: top findings sorted by `severity × magnitude ÷ effort`, each showing status, evidence, recommendation, fixability (auto/proposed/advisory), and `expected_impact` (axis + confidence + magnitude).
   - Footer: how to run `/claude-seo-ai:fix`.

## Notes
- Keep this skill's own output tight — the value is the merged report, not narration.
- If the target is a multi-page crawl, analyze the homepage + one instance of each detected template first, then sample additional pages; **log what was sampled** (never silently cap coverage).
- Degrade gracefully: if a render/PSI/GSC tier is unavailable, proceed at the lower tier and mark affected findings `needs_api`.