DEV Community

Zane
Zane

Posted on

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:

  1. standards/: human-readable policy and boundaries.
  2. rulemaps/: machine-readable rule contracts.
  3. core/: execution engine (discover / generate / audit).
  4. skills/seo-audit/SKILL.md: agent workflow contract (with staged guardrails).
  5. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 (1)

Collapse
 
jane_mayfield profile image
Jane Mayfield • • 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?