/seo-orchestrator

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`.