Zane

Posted on Apr 8

SEO as Code, Not SEO as Spreadsheets: A Publish-Grade Governance Workflow

#ai #seo #agentskills

Most teams do not fail at SEO because they do not care.
They fail because the process is disconnected:

standards are in docs, but not executable,
audits happen after release,
remediation is ad hoc and hard to track.

SAR (SEO-Audit-Remediation) is built to close that gap with a rulemap-driven, CI-friendly workflow.

What SAR Actually Includes

SAR is a repository-first governance stack with 5 connected layers:

standards/: human-readable policy and boundaries.
rulemaps/: machine-readable rule contracts.
core/: execution engine (discover / generate / audit).
skills/seo-audit/SKILL.md: agent workflow contract (with staged guardrails).
skills/seo-audit/scripts/*.cjs: bundled runtime artifacts.

The key is that standards, execution, and remediation guidance live in one versioned system.

Why Rulemap-Driven Runtime Matters

Rules are not hardcoded in application flow.

They are executed from rulemap config fields such as:

category
severity
blocking
runtime.scope
runtime.evaluator
runtime.params

Runtime scopes are explicit:

page
cross-page
host
gate

This keeps architecture stable while rules evolve.

Why `skills` Is a Core Differentiator

Many tools can report issues. Fewer can orchestrate fix workflows safely.

skills/seo-audit/SKILL.md defines a practical agent runbook:

staged execution (discover -> generate -> audit),
mandatory human checkpoint after route discovery,
explicit command contract,
re-audit loop after fixes.

In other words: it is not “AI auto-fix magic.” It is controlled automation with review gates.

End-to-End Flow (CLI)

Route-based one-shot audit:

pnpm seo:audit --routes core/examples/routes.sample.json --origin https://your-site.com

Step-by-step flow:

pnpm seo:discover --project-root /path/to/project --origin https://your-site.com
pnpm seo:generate --routes .outputs/<project>/routes.json --origin https://your-site.com
pnpm seo:audit --urls .outputs/<project>/urls.txt

Outputs You Can Feed Into Engineering

Each run produces concrete artifacts:

audit-report.json for machine processing and CI records,
action-plan.md for prioritized remediation execution,
optional AI remediation suggestions (--ai-remediation) for top issues.

AI output is recommendation-oriented, not blind code mutation.

CI Gate Strategy

Typical release gate:

P0 violations = 0
passRate >= 99.5%

Verification command:

pnpm seo:verify

Packaging and Runtime Consistency

SAR ships bundled CJS artifacts:

skills/seo-audit/scripts/discover.cjs
skills/seo-audit/scripts/generate.cjs
skills/seo-audit/scripts/audit.cjs

This enables predictable execution in CI/CD without relying on runtime node_modules.

Who Should Use It

SAR is a strong fit for teams that need:

cross-repo SEO governance,
auditable release criteria,
and deterministic CLI + agent workflows.

Repo: https://github.com/zandko/seo-foundation

Top comments (5)

Jane Mayfield • Apr 8 • Edited

Really like this approach — treating SEO like code instead of a bunch of spreadsheets just makes sense.

The rulemaps idea is 🔥 too — keeps everything flexible without breaking the system every time rules change.

Curious how it scales though — does CI stay fast as projects grow, or does it start slowing things down?

Zane • Apr 10

At present, there is no significant difference in response time as the number of routes increases. In my opinion, this solution is highly scalable, as addresses can be grouped for parallel and synchronous processing.