A multi-brand SEO content engine. An AI agent does every editorial judgment step — research, planning, writing, reviewing — following written rulebooks. A Node.js engine does everything that must be exact — converting, validating, generating images, publishing to the CMS. Every step reads specific files and writes specific files, so the whole system is an auditable chain of documents. The design principle: separate judgment from determinism, and make rule-compliance a gate that physically blocks bad output.
Hover (or tap) any box to light up everything it reads and writes. Solid lines = data flowing between files and workers. Dashed lines = rules, triggers, and enforcement. Arrows point in the direction the information travels.
These files are loaded before any work starts. They never produce content themselves; they constrain everyone who does. One of them is not even a document — it is a hook that physically blocks output written without proof the rules were read.
CLAUDE.md · AGENTS.mdThe constitution: the exact 6-phase pipeline, the non-negotiable rules, and where every detailed procedure lives. AGENTS.md is its identical twin read by Codex.
loaded every sessionshared/operating-principles.mdSection S2: no fabrication, confidence labels on every claim, linking rules, punctuation bans, the Adherence Protocol (§S2.19), ignore-word-counts (§S2.20).
shared/subagent-patterns.mdHow Claude splits work across parallel agents: max 5 concurrent, each owns ONE file, Pattern H = the merged write+review pass with one shared research dossier.
shared/tool-capability-map.md · tool-fallback-reference.mdWhich research tool to use for what (SERP, scraping, keyword data) and what to fall back to when one fails or runs out of credits.
shared/koray-glossary.mdThe semantic-SEO vocabulary (Koray Tugberk Gubur's framework) the whole system is built on: topical maps, entities, contextual coverage.
.claude/hooks/adherence-gate.mjsA machine gate: it BLOCKS any attempt to save an article or brief until that item's adherence file exists. Skipping the rules is physically impossible, not just discouraged.
machine-enforcedBefore a single article is planned, Claude researches the product's own website and the live web to write the brand's "identity card", then does the same for each competitor. Every later phase reads these files in full — they are the single source of who the brand is and what its rivals actually offer.
/brand-foundation · /product-detailThe triggers. Claude studies the product's live site plus outside research and writes the two canonical brand files.
runbooks/brand-foundation-runbook.mdThe step-by-step procedure: voice, audience, ideal customer, pains, jobs-to-be-done, competitors, positioning.
/competitor-foundationRepeats the same deep research for each competitor. Required before ANY comparison, alternative, review, or "best of" page may exist.
runbooks/competitor-foundation-runbook.mdThe procedure for profiling a rival: their product, pricing, gaps, and reputation on review platforms.
SERP · Firecrawl · DataForSEO · G2 / Capterra / RedditThe outside world. Every fact in the system is retrieved fresh from here in-session — nothing is written from memory.
00-brand/{brand}-brand-foundation.mdTHE canonical brand context. Never condensed, never copied — read in full by every downstream phase.
read by phases 3–600-brand/{brand}-product-details.mdFeature-by-feature product depth. The authoritative source for any claim about the product itself.
00-brand/{brand}-review-methodology.mdA weighted scoring rubric. Every review, comparison, and "best of" page computes its verdict score from this — no score without it. Also published once as the public "How We Review" page.
gate for evaluative pages00-brand/competitors/{c}/…-brand-foundation.md + …-product-details.mdOne pair of files per competitor. Comparison, alternative, and "best of" pages quote these, never guesses.
One spreadsheet row per future page: its exact URL, target search query, page type (out of 39 types), which pages it must link to, and its lifecycle status. It is generated by a Python script — never typed by hand — so the plan is reproducible and self-validating.
/topical-mapClaude reads the brand + ALL competitor foundations, validates every planned query against the real search results, and edits the builder script.
runbooks/topical-map-generation-runbook.mdHow to design the map: topic clusters, query validation, internal-link architecture.
schemas/topical-map-schema.md · page-type-inventory.mdThe column contract for the CSV, plus the catalog of 39 page types (PT1–PT39) — review, comparison, how-to, what-is, FAQ hub…
01-topical-map/_scratch/{brand}-build_map.pyRe-runnable Python script — the map's durable source. To change the map you edit this and re-run it; it validates and writes the CSV atomically, preserving lifecycle columns.
never hand-type the CSV01-topical-map/{brand}-topical-map.csvThe heart of the system. Every page's proposed_url, query, page type, planned internal links — plus the lifecycle columns every phase updates.
01-topical-map/{brand}-entity-inventory.csvEvery named thing (laws, tools, concepts) the site must cover, and where. Keeps hundreds of articles consistent about facts and terminology.
rebuilt by review…-topical-map-overview.md · …-source-log.mdThe human-readable summary of the map's strategy, and the audit trail of every source consulted while building it.
/csv-to-jsonlTrigger for the engine's convert step.
engine convert (csv-convert.mjs)Deterministically converts the CSV into the machine-readable spec file the engine's commands consume.
content-plan/{brand}-specs.jsonlAuto-generated, never hand-edited. One JSON object per page; read by validate, publish, and thumbnails.
For each map row, Claude runs fresh search-results research and writes a brief: the page's angle, required sections, required entities, and its internal-link plan. In a batch, every brief gets its own independent agent doing its own research — briefs never copy each other.
/content-briefThe trigger. Reads the map row, brand + competitor context, and the live SERP; writes the brief; then marks the map row briefed.
runbooks/content-brief-generation-runbook.mdThe universal brief procedure: research phases, validation gates, output format.
reference-briefs/PT13…PT33-*.mdPer-page-type playbooks layered ON TOP of the master runbook (both always load): a review brief is structured differently from a how-to brief.
02-briefs/briefs/{id}-brief.mdOne blueprint per page: intent, angle, heading skeleton, required entities, link plan, competitor gaps to beat.
Writing and reviewing run as ONE pass per article with three separate specialist agents. A research agent builds a shared evidence dossier. A writer drafts from that dossier only. A reviewer — a stronger model with a deliberately cold, adversarial handoff — re-judges everything and edits the draft in place. No article ships without surviving this.
/content-write · /content-reviewThe triggers. /content-write runs the full merged pass; /content-review alone re-reviews an older article from scratch.
Claude (Opus) — batch conductorDispatches at most 5 agents at once, then runs the checks no single-file agent can see: anchor-text variety, link resolution, sibling overlap. Updates the map's lifecycle columns.
runbooks/content-writing-runbook.mdThe writing law: answer-first sections, sentence/paragraph caps, lists over prose, first-person evidence, Grammarly grammar.
runbooks/content-review-runbook.mdSelf-contained review law: embeds the SEO, AEO, GEO, and grammar rules verbatim. Bar = 10× information gain, "not longer, better".
reference-writers/PT13…PT33-*.mdPer-page-type writing playbooks. The writer follows them; the reviewer audits against the SAME file.
Research subagentFetches the live SERP, AI Overview, full competitor pages, and review-platform evidence ONCE per article into a shared dossier — so writer and reviewer never duplicate the research.
03-content/_scratch/{id}/dossier/The raw evidence locker: session-fresh captures, not interpretations. The reviewer reuses the captures but re-derives every conclusion itself.
03-content/_scratch/{id}/adherence.mdProof-of-work: a load manifest (which rulebooks were read) + a conformance attestation (every checklist item ticked). The hook demands it before any output can be saved.
Write subagentDrafts the article from the dossier, the brief, and the brand files. Ignores the brief's word counts entirely — length follows content need.
Review subagentAdversarial editor: re-reads the raw evidence cold, re-judges every fact, beats every competitor page, applies the scoring rubric, and edits the article file in place. Runs the validator last.
03-content/articles/{id}-content.mdThe article itself — one file per page, edited in place forever (never forked). Frontmatter carries its URL, entities, and review score.
the productengine validate (validate.mjs)Deterministic final check: no em/en-dashes, sentence & paragraph caps, lead-in before lists, resolvable internal links, entity minimums. Runs only as review's last step.
02-briefs/{brand}-linking-anchor-inventory.csvEvery internal link's anchor text across the whole site — so hundreds of articles don't all link with the same words. Written ONLY by review; read by briefs for context.
review-ownedTwo visual pipelines share one division of labor: Claude decides WHAT each image should be (never forcing one where a table already works), OpenAI's Codex generates the pixels, and Node.js code applies the brand finish. The three run as separate sequential processes driven by one PowerShell script.
/article-image-planClaude reads a finished article and plans its in-body images: which sections earn one, the type, SEO filename, alt text, and the generation prompt. Skips sections a table or list already serves.
runbooks/article-image-planning-runbook.mdThe planning law: never force images, never re-analyze an already-planned article.
04-assets/article-images/{id}/plan.json + placement docThe machine-readable image plan per article — prompts, filenames, alt text, and exactly where each image goes.
run-article-images.ps1PowerShell conductor: runs plan → render → finalize as three separate processes (Codex is never launched from inside Claude).
OpenAI Codex CLI (codex exec)The image generator. Receives each plan's prompt non-interactively and renders the raw image.
04-assets/{brand}-brand-guideline.md + brand-assets/The visual identity extracted from the brand's design file: its primary color, the display typeface, and the logo files used for overlays.
engine/src/article-images.mjsThe finisher: picks the right logo variant by measuring the image's luminance, overlays it, and compresses — it never regenerates.
engine thumbnails (thumbnails.mjs · codex-runner.mjs)The blog-card thumbnail pipeline: reads the specs, prompts Codex per page, writes finished thumbnails.
04-assets/thumbnails/One cover image per article, pushed to the CMS by sync-thumbnails.
The engine converts each reviewed article to the CMS's format and pushes it over the CMS API (idempotent — re-running never duplicates). Then the loop closes: the live CMS and sitemap are the source of truth, and a reconcile command rebuilds the map's status columns from them, so the plan can never drift from reality.
engine publish (publish.mjs)Reads a reviewed article + its spec row and orchestrates the push.
md-to-editorjs.mjsConverts Markdown into EditorJS blocks + HTML — the two body formats the CMS requires.
cms-client.mjs · sync-thumbnails.mjsThe API client: authenticates, creates or updates each post by slug, attaches the thumbnail as the item's image.
Headless CMS — Blog collectionWhere articles live once published. Authoritative for item IDs, publish state, and thumbnails.
{site}/blog/sitemap.xmlThe only legitimate source of published_url and publish_date — never guessed, never defaulted to today.
engine reconcile (reconcile.mjs)Rebuilds the map's lifecycle columns from the CMS + local files. Idempotent, only upgrades, never demotes. Run at the start of every session that touches lifecycle.
the anti-drift loopEvery row in the topical map is in exactly one state. The state only moves forward, and each transition is owned by one phase. Nothing is published without passing review.
In the merged pass, written is only a transient blip — articles normally land straight at reviewed because review runs in the same session. And critically, these status columns are a derived cache, not hand-kept truth: if they are ever lost or clobbered, reconcile rebuilds them from the live CMS and the files on disk.
| File | Written by | Read by |
|---|---|---|
{name}-brand-foundation.md | Phase 1 (brand-foundation skill), once | Every later phase, always in full — never summarized into a copy |
competitors/… foundations | Phase 2, once per competitor | Topical map, briefs, and review for all comparison/review/best pages |
{name}-review-methodology.md | Once per brand | Reviewer (computes every verdict score); published once as "How We Review" |
build_map.py → topical-map.csv | The Python builder (structure); the orchestrator (lifecycle columns only) | Briefs, production, engine convert/publish/thumbnails — the hub of everything |
entity-inventory.csv | Builder initially; rebuilt only by review from finished articles | Brief and write phases, for cross-article consistency |
linking-anchor-inventory.csv | Review only | Briefs (context for the link plan) |
{id}-brief.md | Phase 4, one independent agent per brief | Research + write agents (intent and required entities — never as a research substitute) |
_scratch/{id}/dossier/ | Research agent, once per article | Write agent and review agent (raw captures only; each re-derives its own judgment) |
_scratch/{id}/adherence.md | The producing agent, before its output | The adherence-gate hook — no gate file, no saved article |
{id}-content.md | Write agent; then edited in place by review, forever | Image planner, validator, publish, reconcile |
{name}-specs.jsonl | engine convert, from the CSV — never hand-edited | Engine validate, publish, thumbnails |
plan.json + placement doc | article-image-plan skill | PowerShell driver → Codex (render) → article-images.mjs (finish) |
| Headless CMS + live sitemap | engine publish / sync-thumbnails | engine reconcile, which writes truth back into the CSV |
PT14-product-review.md). The reference overrides only the structure it names; the master stays authoritative on research integrity and validation. Loading one without the other is a hard error.I build AI-powered SEO content systems for early-stage B2B SaaS: full-scale SEO, semantic topical maps, content briefs, content writing, and end-to-end content automation. This map is a sanitized view of the architecture; client names and proprietary methodology are abstracted.
LinkedIn Book a 30-min call salehin.riad96@gmail.com See the dependency map