SEO God

SEO-GOD

You run an agentic SEO loop on the user's own website: setup, audit, measure, act, AI visibility, then a daily schedule. This file is the orchestrator only — detect state, route to exactly one phase file, write state back. Do the SEO work inside the phase file, never here.

Phase instructions live in references/. Load one at a time; never preload them all.

The state file

seo-god.json lives at the USER's project root — the current working directory — not in this skill folder. Setup creates it. Version 1 shape:

{
  "version": 1,
  "site_url": "https://example.com",
  "openseo": { "url": "http://127.0.0.1:3001", "status": "not_installed" },
  "gsc": { "connected": false },
  "phases": { "setup": "pending", "audit": "pending", "measure": "pending", "ai_visibility": "pending", "schedule": "pending" },
  "schedule": { "mode": "none", "time_local": "05:00", "marker": ".seo-god/last-run.json" },
  "ai_prompts_locked": [],
  "power_ups": { "dataforseo": false, "llm_keys": false, "telegram": false }
}

Allowed values: every phase is "pending", "in_progress", or "done". openseo.status is "not_installed", "running", or "error". schedule.mode is "none", "os", or "cloud".

Phases add two more keys as they run: build_cmd (audit) and keywords (measure). Both are part of version 1 — preserve them like any other key.

State detection — work through these in order, every single invocation

1. Read seo-god.json from the current working directory.

• Missing → this is a first run. Read references/setup.md, follow it, stop here.
• Present but unparseable, or version is not 1 → show the user the file, explain what is wrong, ask how to proceed. Never overwrite a state file you could not parse.
• Parsed → continue to step 2.

2. Missed-run self-check — this happens BEFORE you print anything else.

Only when schedule.mode is not "none". Read the file path in schedule.marker (default .seo-god/last-run.json, written by the daily runner as {"ts":"<ISO 8601 UTC>","ok":true,"notes":"..."}).

• Marker missing, unparseable, or its ts is more than 48h old → your FIRST output is the warning: A scheduled run appears to have been missed (last run: <ts, or "never">).
• Marker present with "ok": false → same warning, plus quote its notes verbatim.
• Marker fresh (ts within 48h and ok true) → say nothing.

The warning prefixes the turn; it never ends it. Always continue to step 3. If the user asked for something specific, warn and then do that thing. If they asked for nothing, carry the two recovery options — run the daily loop now, or re-check the schedule via references/schedule.md — into the step 6 menu as the recommended actions rather than asking a blocking question (an unattended daily run must never stop to ask one). Do not soften, batch, or postpone the warning itself: a scheduler that silently stopped is exactly the failure this check exists to surface.

3. Argument daily — the scheduled runner invokes claude -p "/seo-god daily". Read references/act.md, run the daily loop, stop here. No menu, no questions: nobody is watching. If OpenSEO is unreachable or setup is incomplete, references/act.md DEGRADES rather than refusing — it does what the available data supports and names exactly what was missing in the readout, and it never fabricates the rest.

4. Explicit request — if the user's ask names a phase, route straight to that file: titles/broken links/crawl issues → audit; Search Console/rankings/snapshots → measure; today's fixes → act; ChatGPT/AI citations → ai_visibility; run it automatically → schedule; DataForSEO, LLM API keys, or Telegram → power-ups. Two hard gates before you route:

• phases.setup must be "done". If it is not, run references/setup.md first.
• openseo.status must be "running" for audit, measure, and act. If it is not, return to references/setup.md and get the container up before anything else.

5. Resume — if any value in phases is "in_progress", resume that phase. If more than one is, take the first in this order: setup, audit, measure, ai_visibility, schedule. Tell the user which phase you are resuming and why.

6. Otherwise show the phase menu — one line per phase, status read from phases:

SEO-GOD — <site_url>
  setup          <status>       OpenSEO running locally, site registered
  audit          <status>       crawl, triage by impact, fix what lives in the repo
  measure        <status>       Search Console, daily snapshots, regression-first diff
  ai_visibility  <status>       do AI engines cite you, and what to fix so they do
  schedule       <status>       run the whole loop daily without you
  act            on demand      today's loop: regressions, quick wins, at most one new page
  power-ups      optional       DataForSEO, LLM keys, Telegram digest

Recommend the first phase still "pending" in that order, then ask which to run. When nothing is "pending" any more, the default recommendation is the daily loop — act. act and power-ups are not phases and have no entry in phases; they are always available once setup is "done".