seo-orchestrator

seo-orchestrator (Layer 2)

Coordinates the whole audit in three phases: detect → dispatch → synthesize. The scripts are the acquisition layer; the model only judges. Read the compact stdout summaries and the JSON files they name — never paste HTML into the conversation. Nothing is written to the user's project; every artifact lives under ${CLAUDE_PLUGIN_DATA}/runs/<host>/<run-id>/.

1. Detect — one call

1. Resolve the target and the flags forwarded by the command (--pages, --max, --render, --ua, --vertical, --environment, --feed, --out; default --out "${CLAUDE_PLUGIN_DATA}/runs").
2. Run the whole deterministic pipeline in one command. audit.mjs acquires the target (it calls crawl.mjs for a URL, snapshot.mjs for --pages 1 or a local path, and skips acquisition entirely when handed a run directory), writes profile.json (platform / framework / cms plugins / hosting / environment / capabilities / write_targets / vertical_hints, plus a vertical guess), runs the checks registry, and calls report.mjs for a first deterministic-only report:

node "${CLAUDE_PLUGIN_ROOT}/scripts/audit.mjs" <url|path> \
  --out "${CLAUDE_PLUGIN_DATA}/runs" --checks deterministic --format json \
  [--pages N] [--max N] [--render static|auto|js] [--ua <preset>] \
  [--vertical <ids>] [--environment production|preview|staging|local] [--feed <path>]

Read only the JSON summary it prints: run_dir, mode, platform, vertical, coverage, tier, scores, findings, checks, report_json, report_md, findings_json, warnings. --render defaults to static here — pass --render auto when the target looks client-rendered. Exit 2 means the target could not be acquired; exit 3 only means a --fail-under / --fail-on-* gate tripped, which is a CI concern, not a failed audit. 3. Read <run_dir>/crawl.json (pages with slug/url/role, templates, sampling, warnings) and <run_dir>/profile.json. 4. Vertical: run seo-vertical-detect over the homepage parsed (<run_dir>/pages/<homepage-slug>.json) plus profile.vertical_hints. The script only guesses — profile.vertical.source is "inferred" unless --vertical was passed. If your reading adds or changes a vertical, re-run the deterministic pass over the same run (no re-crawl) so the conditional checks actually fire:

node "${CLAUDE_PLUGIN_ROOT}/scripts/audit.mjs" <run_dir> --checks deterministic --format json --vertical <ids>

references/routing.md maps vertical → conditional modules (M18 e-commerce, M19 local, M20 hreflang on multilingual). 5. The run now holds <run_dir>/findings.deterministic.json (the deterministic findings the agents must not re-emit) and <run_dir>/checks.json (checks run, errors, needs_api, manual_review, dropped).