/seo-flow

name: seo-flow
description: >
  FLOW framework integration — evidence-led SEO using the Find → Leverage →
  Optimize → Win loop. Surfaces stage-specific AI prompts from the FLOW
  knowledge base (41 prompts, CC BY 4.0). Use when user says "FLOW", "FLOW
  framework", "seo flow", "evidence-led SEO", "find leverage optimize win",
  or wants stage-specific SEO prompts.
user-invokable: true
argument-hint: "[stage] [url|topic]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "1.9.6"
  category: seo

FLOW Framework — Find · Leverage · Optimize · Win

Shared Data Cache

**Step 0 -- Check shared data cache:**

Before gathering, check `.seo-cache/` for reusable context from related SEO skills. Reference: `../seo/references/shared-data-cache.md` for schemas and dependency map.

Check these cache files when present:

• `.seo-cache/site-meta.json` for domain, business type, industry, and crawl context
• `.seo-cache/audit-scores.json` for prior full-audit priorities
• `.seo-cache/pages/{url-slug}/page-analysis.json` for page-level context when a URL is provided

• If found: parse and use clearly valid fields (note "Using cached [X] from [date]")
• If missing, corrupt, or irrelevant: continue with fresh evidence
• If the user says "refresh" or "re-run": ignore cache reads and overwrite on write

> Framework and prompts © Daniel Agrici, CC BY 4.0 — github.com/AgriciDaniel/flow

FLOW is an evidence-led SEO operating model built for the AI-search era. Codex SEO integrates the FLOW prompt library (41 prompts across 5 stages) so every analysis can be driven by structured, evidence-backed AI prompts rather than improvised queries.

**Runtime context:** Load `references/flow-framework.md` on every `/seo flow` activation. Load prompt files on demand — only for the stage the user requests.

---

Commands

| Command | What it does | |---------|-------------| | `/seo flow` | Show FLOW overview + stage menu | | `/seo flow find [url\|topic]` | Find-stage: keyword research, gap analysis, SERP intent mapping (5 prompts) | | `/seo flow leverage [url]` | Leverage-stage: backlink strategy, off-site authority (1 prompt) | | `/seo flow optimize [url]` | Optimize-stage: select 2-3 most relevant of 21 prompts based on context | | `/seo flow win [url]` | Win-stage: BOFU, conversion rate, dual-surface scorecard (3 prompts) | | `/seo flow local [url]` | Local-stage: GBP optimization, meta, title tags, local audits (11 prompts) | | `/seo flow prompts` | Full index of all 41 prompts — stage, name, trigger conditions | | `/seo flow sync` | Pull latest prompt files from github.com/AgriciDaniel/flow |

---

Orchestration Logic

On `/seo flow` (no sub-command)

1. Read `references/flow-framework.md` 2. Show the FLOW stage overview with a one-line description of each stage 3. Ask: which stage matches the user's current situation?

On `/seo flow find [url|topic]`

1. Read all files in `references/prompts/find/` 2. Apply each prompt to the URL or topic 3. Cross-reference: "For deeper SERP clustering, see `/seo cluster <seed-keyword>`"

On `/seo flow leverage [url]`

1. Read the file in `references/prompts/leverage/` 2. Apply to the URL's current backlink context 3. Cross-reference: "For raw backlink data, see `/seo backlinks <url>`"

On `/seo flow optimize [url]`

1. Read all file names in `references/prompts/optimize/` 2. Read prior analysis context (URL, industry vertical, any prior skill output in conversation) 3. Select 2-3 most relevant prompts; load only those files 4. Apply selected prompts; note the others are accessible via `/seo flow prompts` 5. Cross-reference: "For full content quality analysis, see `/seo content <url>` and `/seo geo <url>`"

On `/seo flow win [url]`

1. Read all files in `references/prompts/win/` 2. Apply each prompt to the URL's conversion and BOFU context 3. Cross-reference: "For SXO persona scoring, see `/seo sxo <url>`"

On `/seo flow local [url]`

1. Read all files in `references/prompts/local/` 2. Apply to the URL's local SEO context 3. Cross-reference: "For full local SEO analysis, see `/seo local <url>` and `/seo maps [command]`"

On `/seo flow prompts`

1. Read `references/prompts/README.md` 2. Display the full index: all 41 prompts with stage, name, trigger conditions

On `/seo flow sync`

1. Run: `python scripts/sync_flow.py` 2. Display the JSON summary (files added, updated, unchanged) 3. Show attribution notice after sync completes

---

Context Matching (Optimize stage)

The optimize stage has 21 prompts. Dumping all 21 is noise. Select by priority:

1. **Industry vertical** (SaaS → on-page + technical; local → citations + GBP; publisher → E-E-A-T + freshness) 2. **Prior skill output** (seo-technical flagged crawl issues → technical optimize prompts; seo-content flagged E-E-A-T gaps → content optimize prompts) 3. **URL signals** (product pages → conversion; blog → freshness + authority)

Always surface exactly 2-3 prompts. State which prompts you chose and why.

---

Reference Files

Load on-demand — do NOT load all at startup:

• `references/flow-framework.md` — FLOW operating model (load on every `/seo flow` activation)
• `references/bibliography.md` — Evidence sources; load when citing studies or statistics
• `references/prompts/README.md` — Prompt index; load for `/seo flow prompts`
• `references/prompts/find/` — 5 prompts; load for `/seo flow find`
• `references/prompts/leverage/` — 1 prompt; load for `/seo flow leverage`
• `references/prompts/optimize/` — 21 prompts; load selectively for `/seo flow optimize`
• `references/prompts/win/` — 3 prompts; load for `/seo flow win`
• `references/prompts/local/` — 11 prompts; load for `/seo flow local`

---

Attribution

Every `/seo flow` activation (any sub-command) outputs before analysis:

Framework and prompts © Daniel Agrici, CC BY 4.0 — github.com/AgriciDaniel/flow

Do not omit or modify the attribution.

---

Error Handling

| Scenario | Action | |----------|--------| | `