01What SEOKit Is
SEOKit is an SEO operating layer for an autonomous agent. It is not a dashboard a human clicks through, and it is not a pile of scripts a human runs. It is the doctrine, the guard-rails, and the instruments that let the agent research search demand, form strategy, produce content and entities, review its own quality, watch live rankings, and respond to incidents — mostly on its own, stopping only where a human decision is genuinely required.
The core thesis
SEO failure is mostly hallucinated capability — an agent inventing rankings and page state from training data instead of measuring reality. SEOKit's answer is a single hard rule: real data or nothing.
The mechanism
Strategic actions must resolve to freshly-fetched evidence (SERP / Search Console / index / live page render). No evidence → the action is blocked, not guessed.
The output
Reproducible, auditable ranking work: a goal registry, a hypothesis registry, a task registry, and an append-only per-project action log — so any session can pick up exactly where the last one stopped.
02Operating Stance — what changed, and why
Earlier versions of this system were modelled as a team operating system: a dispatch table, a dynamic priority matrix, multi-channel team coordination, a multi-state status machine, and a three-layer human approval before any plan could run. That scaffolding was retired. It was team-coordination ceremony that fought against the way a single autonomous agent actually works.
Retired — ceremony
- Mandatory multi-agent delegation for every step
- Dynamic priority matrix & "strike mode" boosts
- Multi-channel team coordination / broadcast protocol
- Three-layer plan approval before execution
- Five-state status machine + heavy per-task logging
Kept — the load-bearing core
- The AI drives; the human approves only real gates
- A small, inviolable harness of universal rules
- Evidence-anchored planning ("no data, no plan")
- Goal → Hypothesis → Task continuity across sessions
- An immutable brand/entity map as input
- A cross-project knowledge base that learns
Principle behind the cut: a rule earns its place only if it is both universal and inviolable. Anything else is either a per-instrument default or a rule worth deleting. The result is a leaner agent that spends its budget on judgment, not on process.
03Architecture — a lean harness, plus per-instrument doctrine
SEOKit splits its rules into two tiers. This is the whole architecture in one idea.
The harness
The tiny set of rules that hold for every SEO task and that no instrument may override. Loaded lazily — only when an SEO signal appears — so pure-code sessions stay lean. Because everything in it is inviolable, there is no precedence table: nothing conflicts by construction.
The doctrine
Each skill, agent, or loop carries its own operational doctrine — how it orders its gates, when it acts automatically versus asks, what content tiers it enforces. Doctrine sets choices but never violates the harness, and never restates it (it inherits).
04The Inviolable Harness — 7 rules
These are universal to SEO work and cannot be overridden by any instrument. They are the safety envelope inside which the agent is free to act autonomously.
| # | Rule | What it forbids / requires |
|---|---|---|
| 1 | No fabrication | Never invent reviews, licences, odds/bonuses, schema, dates, authors, awards, contact details, or content. Real data or nothing. |
| 2 | Human authorization for money / live / mass / irreversible | Stop and get approval before writing a live site, spending money, mass or off-page actions, or anything hard to reverse — unless the human durably authorized it. Snapshot before a live edit; purge cache after; verify the render. |
| 3 | Contradiction in inputs → confirm | If the human's own inputs disagree (two values for one key, a directive vs a constraint), stop, quote the exact conflict, confirm which is intended — then run. Never self-decide past it. |
| 4 | Published content is gated | Depth per tier, non-fabricated, human-voiced (anti-footprint style, never thin). Substantial or sensitive topics face an adversarial fact + consistency check before shipping. |
| 5 | Verify before claiming done | Check outputs against evidence; state failures plainly; never overclaim. "Green" from a tool is a signal, not a finish line. |
| 6 | The entity map is immutable input | Consult the brand/entity map before writing, structuring, or scoring; never fabricate its fields. |
| 7 | Privacy | Never leak secrets or environment files; never publish the operator's identity. A privacy hook is authoritative and blocks sensitive-file access without approval. |
Full-auto is not a bypass of rule 2 — it means authorization was already granted. The agent still snapshots, still verifies, still refuses to fabricate.
05Specialist Lenses — instruments, not ceremony
SEOKit registers a family of specialist agents. The driver delegates to one only when a specialized lens genuinely helps — never as a ritual. Each is a focused perspective the orchestrator can summon and then fold back into its own reasoning.
| Group | Lens | What it sees |
|---|---|---|
| Strategy / Research | strategist | Brief, topical map, content plan, cluster priority |
| researcher | Keyword demand, SERP shape, competitor gaps, UGC presence, entity signals | |
| strategy-reviewer | Adversarial red-team of a plan through multiple hostile personas before commit | |
| Production | producer | Classify briefs, propose executors, track production state |
| entity-builder | Identity pages, schema, sameAs web — "authority" vs "just HTML" | |
| link-builder | Off-page authority tactics against a target profile (out of scope for on-page work) | |
| Quality | quality-reviewer | Facts, E-E-A-T, brand voice, intent match — adversarial by design |
| task-reviewer | Generic deliverable gate across any executor type | |
| Tracking | tracker | Ranking / Search Console / analytics snapshots, anomaly detection |
| data-ingestor | Fresh ranking + Search Console snapshot as a strict JSON contract | |
| validator | Slow-loop recovery checkpoints (weeks, not seconds) | |
| Incident | forensics | Build the incident timeline — pure data collection, no diagnosis |
| diagnostician | Hypothesize root cause with confidence levels | |
| recovery-strategist | Turn a diagnosis into concrete recovery actions | |
| auditor | Technical + on-page + content-quality health audit | |
| Process | librarian | Curate the knowledge base; promote, verify, deprecate tactics |
| kaizen | Continuous-improvement engineer for the workflow itself — hunts process waste |
The count is deliberately not the point. What matters is that these are lenses the single driver reaches for, not a headcount it must coordinate.
06Lifecycle — the instruments the driver chains
A project moves through phases, but the agent chains them itself and revisits them as evidence demands. Each phase is an instrument the driver invokes when the state calls for it.
Brief & brand foundation
Establish goals with a KPI and a deadline, and the brand/entity foundation. The entity map becomes immutable input for everything downstream. GATE missing foundation → blocked.
Research — measure, don't guess
Pull real keyword demand, SERP shape, competitor gaps, and entity/authority signals from live sources. GATE every keyword needs a raw, recent capture with intent classified. No data → no synthesis.
Strategy + adversarial red-team
Synthesize a content and structure plan where every claim cites evidence, then have it attacked by hostile personas (algorithm, skeptical competitor, budget watchdog, helpful-content) before it is committed.
Production — content, entity, authority
Produce content packages, deploy identity + schema, and (when in scope) pursue off-page authority against a target profile. On-page and off-page are scoped separately and never conflated.
Quality gate
Drafts face an adversarial review across facts, E-E-A-T, brand voice, and intent, plus a technical pass on schema and internal-link logic. Weak work bounces back with negative constraints; exemplary work is archived as a positive few-shot example.
Tracking
Ongoing ranking / Search Console / analytics snapshots feed anomaly detection. A confirmed anomaly triggers the incident chain automatically.
Incident chain concurrent
Forensics (timeline) → Diagnosis (root cause with confidence) → Recovery (concrete plan) → Validation (T+7 / T+14 / T+30 checkpoints) → Intelligence (post-mortem promoted to the knowledge base so the whole portfolio inherits the lesson).
07Goal / Hypothesis / Task — intent that survives sessions
The single most important continuity mechanism. Strategic intent is stored, not re-derived, so a fresh session inherits why each task exists.
Every task carries its parent hypothesis. When a hypothesis is disproven by the evidence, in-flight tasks under it pause and the agent forms the next hypothesis or retires the bet — the work never drifts free of the reason it was started.
08State & Memory — the source of truth per project
| Artifact | Purpose |
|---|---|
| State file | Agent-first, hot-state only: current phase, health, active goals, blockers, open loops. The human reads nothing here; history lives elsewhere. |
| Goals registry | Each goal with its KPI table (query / page / current / target / source), deadline, and checkpoint dates. |
| Project memory | Decisions, learnings, and project-specific constraints that are not derivable from the code or history. |
| Entity map | Immutable input. Brand identity, core entities, topics to avoid, primary pillars. Consulted before any write; never fabricated. |
| Audit-actions log | Append-only record of every action, tagged to its task, with an evidence link. This is what lets a later session trust the past. |
09Gates & Verification — how autonomy stays safe
Autonomy is bounded by a few mechanical guards and a small number of human gates. The guards are cheap and always on; the human gates fire only where a decision is genuinely the human's to make.
Data-anchor guard
Strategy, briefs, new-page proposals, and cannibalization calls must resolve to a fresh evidence file. Missing evidence is a hard block — the agent cannot infer its way past it.
Anti-inference guard
Any claim about a live URL's current state (schema, layout, format) requires a real fetch within a short freshness window. The agent cannot fabricate the tool events the harness recorded, so "I checked" must be true.
Content-publish gate
Published content must clear a depth-per-tier check, be non-fabricated, and read in a human voice. Substantial or sensitive pages add an adversarial fact + consistency pass.
Render-not-claim verification
After a live edit: snapshot first, purge the cache, then verify the rendered page — never a database write or a stale cache — before reporting done.
The human gates (and only these)
Money
Any spend.Live
Writing a production site not already durably authorized.Mass
Bulk or off-page actions at scale.Irreversible
Anything hard to undo, or a contradiction in the human's own inputs.10Knowledge Base — the portfolio learns as one
Wins, failures, and deprecations do not stay trapped in the project that produced them. A librarian curates a cross-project knowledge base so a lesson learned once protects every future project.
Validated tactics
Patterns confirmed across multiple projects, promoted to reusable playbooks and re-verified over time.
Deprecated tactics
Approaches that failed or drew a penalty signal, retired with the reason — so nobody re-runs a known mistake.
Reference & benchmarks
Runbooks, per-vertical reference numbers, and update observations verified against a tracked history rather than quoted from memory.
Typed-edge overlay
A non-linear retrieval layer over the knowledge frontmatter — query relationships and cross-project reuse edges before scanning raw files.
Query before scan
A context index answers cross-repo and relationship questions cheaply, so the agent looks things up instead of re-reading everything.
Verify-on-read
Retrieved knowledge reflects what was true when written; if it names a file or flag, the agent confirms it still exists before acting on it.
11Levels of Autonomy — where the AI truly holds the wheel
Not every loop is equally autonomous, and SEOKit is honest about the difference. A scheduled script that runs on a timer is automated but brainless. A genuine autonomous agent is one where the LLM decides the next action from the current world-state — not one where a tool decides and the LLM merely narrates.
Automated ≠ autonomous
A cron job that fetches and formats data is deterministic. Useful, but it makes no decisions. Calling it "an agent" is the trap SEOKit explicitly avoids.
The real loop
Wake → read world-state → decide the next action (a judgment call) → act through existing instruments → log the decision. The decision step is an actual choice, and it is preserved, logged, and measurable.
The litmus test
An honest autonomous loop leaves behind a trail of decisions — not just outputs. If you can point to a log where the agent chose between real alternatives based on state, it is driving. If the "decisions" are always the same because a script pre-decided them, it is a tool wearing an agent's costume. SEOKit's design goal is to keep the judgment loop LLM-owned, and to reserve determinism for the mechanical work underneath it.
12Core Principles
AI drives, human oversees
The agent decides what to do and in what order; the human approves only at money / live / mass / irreversible gates.
Deliver results, not tools
Building a tool is a means the agent may choose for its own use. The human receives outcomes, never something they must operate.
No data, no plan
Search ranking is a real-world constraint. An LLM cannot infer outcomes from a keyword string. Evidence, or block.
Taste over ceremony
YAGNI › KISS › DRY. Scout before acting. Prove a cause before fixing it. No process for its own sake.
Verify before claiming done
Check outputs against evidence and state failures plainly. A tool's green light is a signal, not proof.
The portfolio learns as one
Every incident, win, and deprecation feeds a shared knowledge base — the whole portfolio improves, not one project at a time.