Platinum SEO Engine
Status: v2.1.4 — production-ready core (production/publishing suites + 4 new tech-SEO skills are wip: contracts + tests locked, runtime deferred) · 50 skills · 31 commands · 6 hooks · 6 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, 50 skills across 8 categories cover an end-to-end SEO loop:
| Category | What it covers | Skills |
|---|
| Ingestion | Pull data from Google Search Console, DataForSEO, Screaming Frog (file-drop + native MCP-primary orchestrator), Scrapling | 5 |
| Discovery | Quick wins, content gaps, cannibalization, content decay, on-page audit, schema audit, tech audit, geo analysis, competitive analysis, AIO competitor map, GBP audit, faceted-nav audit, robots-policy audit, hreflang audit | 14 |
| Planning | Topical map, cluster map, new content plan, internal links, master task sync, migration map | 6 |
| Production | New blog drafting, content revision, FAQ optimization, content remediation, image generation | 5 |
| Publishing | Indexing ping (URL Indexing API), index status verification | 2 |
| Reporting | Weekly/monthly site reports + 6 portfolio-level reports (overview, heatmap, KPI trend, etc.) | 9 |
| Meta | Init project, brand onboarding, whats-next router, mark-done | 4 |
| Governance | Schema validation, glossary audit, drift-check, context loader | 4 |
Plus 31 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 6 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.11+
- 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
| Variable | Where to get it |
|---|
GOOGLE_APPLICATION_CREDENTIALS | Google Cloud Console → IAM → Service Accounts (JSON key path) |
DATAFORSEO_USERNAME | app.dataforseo.com → API tab |
DATAFORSEO_PASSWORD | same |
PSEO_WORKSPACE_ROOT | local path to your workspace repo (see Architecture) |
Optional:
| Variable | Used by |
|---|
HIGGSFIELD_API_KEY | generate-images skill (Phase 11+) |
SCRAPLING_BIN | site scraping fallback when Screaming Frog is unavailable |
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/ (50 SKILL.md) │ │ • projects/{slug}/ │
│ • commands/ (31 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:
| # | Discipline | What it means |
|---|
| 1 | Single Source of Truth | Each term, schema, and rule is defined in exactly one place |
| 2 | Schema-First | No data is written before its *.schema.json exists |
| 3 | Project-Agnostic Plugin | Project names never appear in the plugin repo (CI greps for them) |
| 4 | Append-Only State | events.jsonl and workflows/{run_id}.json are never overwritten |
| 5 | Atomic Excel Writes | master.xlsx is written only via a transaction wrapper with backup + invariant check |
| 6 | Naming | Slugs and skills kebab-case; sheets and Python snake_case; run IDs {slug}-{date}-{uuid} |
| 7 | Secrets Management | API keys never committed; .env only; pre-commit guards |
| 8 | Glossary Discipline | Every technical term lives in docs/GLOSSARY.md |
| 9 | Skill Description Discipline | Every skill frontmatter validates against skill-frontmatter.schema.json |
| 10 | Time Discipline | All timestamps stored in UTC ISO-8601, presented in local time |
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
- Install Screaming Frog 24+ (screamingfrog.co.uk)
- Open SF → Configuration → API Access → MCP Server tab → click Start
- 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)
| Setting | Value | Why |
|---|
| Port | 11435 | Default; matches .mcp.json |
| Max Response Size (Bytes) | 100000 | D-SF-05; orchestrator handles big data via file path |
| Directory | /Users/apple/seo_spider_mcp_server (recommended) | D-SF-03; opt-in F-15 isolation. The project-config sf.mcp.allowed_directory default is null (SF GUI default applies; isolation not enforced) until you set it to match this path. |
| Node.js Runtime Environment | ☐ Unchecked | D-SF-04; security (v1.1+ scope) |
.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.11+ — 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.4 — patch releases on top of v2.1.0: v2.1.4 gives the secret scanner (PreToolUse hook + CI step 6) the same left word boundary for sk-, so writes carrying a long task-… id are no longer blocked, and makes it catch sk-proj- / sk-ant- keys, v2.1.3 stops events_writer redacting an sk- that sits inside a word (long task-… CRM ids were persisted as ta***REDACTED***) and lowers a task-id ratchet pin after the owner made a rename permanent, v2.1.2 closes the events.jsonl write boundary (inline-Python writes, test-only schema_path), v2.1.1 fixed the one-step consent hint, removed the xquik MCP server and added T-10690 absolute-rank uplift (see RELEASE_NOTES_v2.1.4, RELEASE_NOTES_v2.1.3, RELEASE_NOTES_v2.1.2, RELEASE_NOTES_v2.1.1). Beneath them is 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 ~50 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.
| Phase | Title | Status | Skills |
|---|
| 0 | Manager Bootstrap | done | — |
| 1 | Schema Migration | done | — |
| 2 | Rules + Templates | done | — |
| 3 | Core Scripts | done | — |
| 4 | Hooks + Commands | done | — |
| 5 | Critical Path Skills (GO/NO-GO) | done | 5 |
| 6 | Ingestion Suite | done | 4 |
| 7 | Discovery Suite | done | 10 |
| 8 | Planning Suite | done | 5 |
| 9 | Reporting Suite | done | 9 |
| 10 | Content Rules Processing | done | — |
| 11 | Production Suite | in progress | 5 |
| 12 | Publishing + Specialized | in progress | 2 |
| 13 | Governance Final | done | 4 |
| 14 | Workspace + CI + Pilot E2E | in progress | — |
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.4.md.
Documentation
| Doc | What's inside |
|---|
ARCHITECTURE.md | Vision, two-repo strategy, 10 disciplines, phase roadmap, v1 acceptance criteria |
INSTALL.md | Requirements, install, configuration, first-run smoke test, troubleshooting |
CONTRIBUTING.md | Manager/worker protocol, skill authoring, phase discipline |
WORKFLOWS.md | The full 49-skill catalog with inputs/outputs |
GLOSSARY.md | Spec terminology — every technical term defined once |
DECISIONS.md | Architecture Decision Records (append-only) |
PHASE_STATUS.md | Current phase + history |
OPEN_QUESTIONS.md | Pending decisions and unresolved scopes |
SESSION_PROTOCOL.md | How a manager session opens, runs, and closes |
| Release notes |
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.
