Platinum SEO Engine

Status: v2.1.0 — production-ready core (production/publishing suites + 4 new tech-SEO skills are wip: contracts + tests locked, runtime deferred) · 49 skills · 29 commands · 6 hooks · 4 MCP servers (3 stdio + 1 HTTP)

Schema-locked, drift-checked SEO automation for Claude Code. Turn manual SEO work into auditable, repeatable workflows — backed by JSON Schemas, append-only state, and a tool that audits itself.

Contents

What is this? · Who it's for · What it does · Quick start · Architecture · Screaming Frog MCP · Skills & commands · Tech stack · Roadmap · Documentation · Contributing · License

What is this?

platinum-seo-engine is a Claude Code plugin that runs your full SEO operation from inside the editor — keyword research, on-page audits, content planning, reporting, indexing — all governed by strict contracts so the system can't silently drift.

Most SEO toolchains are loose: a Google Sheet here, an Ahrefs export there, an LLM that improvises a different format every time. The data spreads across tabs, fields rename themselves, and three months later nobody can reproduce a number. This plugin takes the opposite stance.

The core idea: less code, stricter rules, single authority, machine-readable contracts. Every workflow is a discoverable skill, every input/output is validated against a JSON Schema, every state change is appended to an event log, and a drift-check skill watches the whole thing.

The result: you can re-run any workflow weeks later, hand a project to someone else, or audit a year of activity — and the system tells you exactly what happened.

Who is this for?

• SEO operators who run multiple sites and need reproducible workflows instead of ad-hoc spreadsheets.
• Agencies managing a portfolio — the plugin is project-agnostic, the same install drives any number of sites.
• Technical SEOs who already use Claude Code and want skills/commands wired into a real pipeline (GSC ingestion → discovery → planning → reporting).
• Teams that need an audit trail for SEO decisions (every action is logged in events.jsonl).

You will get the most out of this if you are comfortable with a CLI, JSON, and the idea that "the schema wins."

What it does

Out of the box, 49 skills across 8 categories cover an end-to-end SEO loop:

Plus 29 slash commands (/pseo-init, /pseo-quickwin, /pseo-driftcheck, /pseo-sf-crawl, /pseo-sf-status, …), 6 hooks that fire on session start, prompt submit, and tool use, and 4 MCP servers wired up automatically (GSC, DataForSEO, Scrapling, SF — the last over HTTP http://127.0.0.1:11435/mcp).

A typical workflow looks like:

/pseo-init           →  bootstrap a project (slug, domain, brand)
/pseo-gsc-pull       →  ingest 90 days of Search Console data
/pseo-quickwin       →  find pages stuck at positions 11–20 with high impressions
/pseo-whats-next     →  router skill suggests the next high-impact action
/pseo-monthly        →  generate the month's report
/pseo-driftcheck     →  audit the full state for inconsistencies

Quick start

Requirements

• Claude Code CLI (latest)
• Python 3.10+
• Node.js 18+ (for the MCP servers via npx)
• Git

Install

# 1. Clone the plugin
git clone https://github.com/popiliadam/platinum-seo-engine ~/Documents/platinum-seo-engine

# 2. Register it with Claude Code
claude /plugin add ~/Documents/platinum-seo-engine

# 3. Configure credentials
cp ~/Documents/platinum-seo-engine/.env.example ~/Documents/platinum-seo-engine/.env
# edit .env — see the table below

Restart Claude Code after the /plugin add step.

Required environment variables

Optional:

First run

# inside Claude Code
/pseo-init        # bootstrap your first project
/pseo-status      # verify the plugin loaded
/pseo-quickwin    # smoke test — should finish in under 2 minutes

Full instructions: docs/INSTALL.md · Troubleshooting: same file, bottom section.

Architecture

The plugin enforces a two-repo separation between logic and data:

┌──────────────────────────────────┐        ┌──────────────────────────────────┐
│  platinum-seo-engine  (this)     │  reads │  platinum-seo-workspace          │
│  ─────────────────────────────   │ ─────► │  ─────────────────────────────   │
│  • skills/        (49 SKILL.md)  │        │  • projects/{slug}/              │
│  • commands/      (29 slash cmds)│        │     ├ project.config.json        │
│  • hooks/         (6 hooks)      │ writes │     ├ master.xlsx                │
│  • schemas/       (32 JSON       │ ─────► │     ├ events.jsonl  (append-only)│
│  • scripts/        Schemas)      │        │     └ workflows/{run_id}.json    │
│  • rules/         (10 disciplines│        │  • shared/                       │
│  • templates/     enforced by CI)│        │  • _archive/                     │
│  • docs/                         │        │                                  │
│                                  │        │  No logic. Only data + state.    │
│  Project-agnostic.               │        │  No project names in the engine. │
└──────────────────────────────────┘        └──────────────────────────────────┘

The plugin never stores project data; the workspace never holds logic. They are linked at runtime by PSEO_WORKSPACE_ROOT in .env. You can drop a fresh workspace next to the same engine and run a different portfolio without a single line of code change.

The 10 disciplines (non-negotiable rules)

Every rule below is enforced by either CI, the drift-check skill, or both:

Bonus: Schema Versioning — bumping a schema requires a migration script in scripts/migrations/.

Full architecture: docs/ARCHITECTURE.md

Screaming Frog 24 MCP (Optional)

v1.8 added Screaming Frog 24's native MCP server as the fourth MCP in PSEO (first HTTP-transport MCP; existing 3 use stdio). The MCP-primary ingestion path replaces manual CSV drop as the authoritative workflow — operator triggers /pseo-sf-crawl and the orchestrator runs the full 24-report export atomically. File-drop fallback is preserved as disaster recovery (D-SF-07; never deprecated).

Setup

1. Install Screaming Frog 24+ (screamingfrog.co.uk)
2. Open SF → Configuration → API Access → MCP Server tab → click Start
3. After plugin install, verify with claude mcp list — the sf entry should show connected. SF 24's MCP is Streamable-HTTP with a per-session Mcp-Session-Id; it exposes no plain tool-listing or health HTTP endpoint that a bare curl can hit. The repo's canonical programmatic probe is SfMcpClient.health() in scripts/util/sf_mcp_client.py, which runs the initialize → notifications/initialized → tools/call handshake.

SF Settings (recommended)

.mcp.json snippet (v1.8+)

{
  "mcpServers": {
    "gsc":            { "command": "bash", "args": ["-c", "set -a; [ -f .env ] && source .env; set +a; exec npx -y [email protected]"] },
    "dataforseo":     { "command": "bash", "args": ["-c", "set -a; [ -f .env ] && source .env; set +a; exec npx -y [email protected]"] },
    "ScraplingServer":{ "command": "${SCRAPLING_BIN:-scrapling}", "args": ["mcp"] },
    "sf":             { "type": "http", "url": "http://127.0.0.1:11435/mcp" }
  }
}

First Crawl Walkthrough

/pseo-sf-crawl <slug> https://example.com/

Orchestrator: pre-flight (DURUR-orch-1/2/4/7) → sf_crawl → poll progress → 24-report iteration (Tier 1: 14 mandatory + Tier 2: 10 AMBER-tolerant) → atomic move to projects/{slug}/sf-exports/{date}/raw/ → sf-import handoff.

Mid-loop crash recovery: /pseo-sf-crawl <slug> --resume <run_id> continues from where it stopped (workflow_runner.pause/resume).

Live status table: /pseo-sf-status (4-column: project_slug, last_crawl_date, sf_mcp_connection_status, allowed_directory_path).

Full setup: docs/INSTALL.md § Screaming Frog 24 MCP Setup · Spec: docs/superpowers/specs/2026-05-26-sf-mcp-hybrid-integration-design.md · ADR: ADR-039 + ADR-040 (type:http)

Skills & commands

Skills live in skills/{category}/{name}/SKILL.md. Each skill is a self-contained markdown file with YAML frontmatter declaring its inputs, outputs, dependencies, and trigger hints. Claude Code loads them automatically.

A few highlights:

• quick-wins — Scans GSC for pages at positions 11–20 with ≥100 impressions, scores them by realistic uplift potential, and returns a ranked list.
• cannibalization — Detects URLs competing for the same query, ranks severity, and proposes consolidation actions.
• content-decay — Flags pages with declining clicks/impressions month-over-month and grades them by remediation difficulty.
• topical-map — Builds a hub-and-spoke topical map from a seed keyword set + DataForSEO clustering.
• drift-check — Read-only governance audit that checks 30+ invariants across schemas, state files, and the Excel workspace; the foundation of the plugin's self-governance.
• whats-next — Meta-router skill that reads project state and recommends the highest-impact next action.

Browse the full catalog: skills/. Slash commands map 1:1 to commonly-triggered skills: see commands/.

Tech stack

• Python 3.10+ — scripts, schema validation, Excel transactions (openpyxl, jsonschema, pyyaml).
• Claude Code Plugin SDK — skills, slash commands, hooks.
• Model Context Protocol (MCP) — four servers wired in .mcp.json (v1.8+):
  • mcp-server-gsc (Google Search Console, stdio)
  • dataforseo-mcp-server (DataForSEO, stdio)
  • Scrapling (stealthy site fetching, antibot fallback, stdio)
  • sf (Screaming Frog 24 native MCP, HTTP http://127.0.0.1:11435/mcp — v1.8 ADR-039; type:http ADR-040)
• JSON Schema (Draft 7) — 32 schemas in schemas/ (31 *.schema.json + cross-sheet-invariants.json).
• Excel as the operational data plane (master.xlsx), JSONL for the append-only event log.
• GitHub Actions — CI runs schema validation, drift-check, lint, and the full pytest suite on every push.

Status & roadmap

Current: v2.1.0 — the unified remediation + capability-gaps release on top of the v2.0.0 AMO milestone (Autonomy & Multi-project Orchestration): SEO-methodology corrections (decay R-85, cannibalization rewrite, rule-pack fixes R-123+), measurement discipline (core-update calendar, MAD anomaly, intervention-vs-control cohorts, AIO presence + CTR-uplift scoring), 4 new tech-SEO skills (faceted-nav, robots-policy, hreflang, migration-map), merchant + local-SEO modules, schema hardening (63 nodes), and hermetic tests. The AMO layer beneath: per-session project binding, an orchestrator that runs an intent as an ordered pipeline and verifies each step's output, a Stop-hook denetçi that forces skipped steps, per-session consent gates (push / delete / POST / sitemap / Indexing), an AI-disclosure quarantine, an independent correctness oracle (the real ≤5% structured-error number), a portfolio cost/quota ledger with kill-switch, and a fail-closed scheduler. Full pytest suite green, zero regression. Per-session project binding (N windows = N projects), an orchestrator that runs an intent as an ordered pipeline and verifies each step's output, a Stop-hook denetçi that forces skipped steps, per-session consent gates (push / delete / POST / sitemap / Indexing), an AI-disclosure quarantine, an independent correctness oracle (the real ≤5% structured-error number), a portfolio cost/quota ledger with kill-switch, and a fail-closed scheduler. Path A (hard-coded ordered sequences), hardened by a 9-agent adversarial review; live-acceptance (D11) passed end-to-end on a real GSC project. Full pytest suite green, zero regression.

The plugin is delivered in 15 phases. Foundation phases (0–4) are complete; skill phases (5–13) deliver the ~49 skills in batches; phase 14 covers the workspace + CI + a full pilot run end-to-end. Phase 5 is the GO/NO-GO gateway — failing it sends the project back to foundation work rather than papering over gaps.

Phases 11 (Production) and 12 (Publishing) are in progress: their skills are spec- and contract-locked (SKILL.md + paired tests) but the runtime scripts are deferred, so each one's frontmatter is status: wip. The docs track that frontmatter rather than over-advertise.

Detailed status: docs/PHASE_STATUS.md · Open questions: docs/OPEN_QUESTIONS.md · Latest release: docs/RELEASE_NOTES_v2.1.0.md.

Documentation

Contributing

The project follows a manager / worker protocol: a manager session sets context and assigns work; worker sessions execute one phase or skill at a time, then close out with a closeout commit. Contributions outside this rhythm tend to drift, so please read docs/CONTRIBUTING.md first if you'd like to submit changes.

For one-off bug reports or questions, open an issue.

Companion repository

platinum-seo-engine is half of a pair. The other half — platinum-seo-workspace — holds project data, state, and outputs. It is private by default because it contains real client data; if you fork the engine, you'll create your own workspace.

License

AGPL-3.0 — see LICENSE. Free to use, study, modify, and self-host. If you run a modified version as a network service or redistribute it, your changes must be published under the same license — so the engine stays open for everyone.

Commercial support & agency licensing (private modifications, white-label, priority help): [email protected] — or open an issue.

Releases up to and including v2.1.0 were published under MIT and remain so; AGPL-3.0 applies from this point forward.

Author

Built by Süleyman Çapar (@popiliadam) — [email protected].

If you're trying this in production and run into edges the docs miss, an issue with reproduction steps is the fastest way to get it fixed.