SEO Client Workflow — Skill (/seo-client) + Intake Auto-Ingest

SEO Client Workflow — Layers 2+3 Architecture

Status: Active (2026-06-03)
Driver: Asmir SEO partner clients (first = Smoke House Hadžići)
MCs: #102865 (skill), #102866 (intake ingest)
Owner: Skillforge (docs), CodeCraft (ingest), FlowForge (launchd)

Architecture Overview

The SEO client workflow is structured in 3 layers:

Layer 2: /seo-client Skill

Location

~/.claude/skills/seo-client/SKILL.md

Purpose

Given a client SEO intake (from SEO Readiness Portal workspace data OR pasted partner email), produce 5 review-ready DRAFT deliverables in Bosnian. Never auto-send. All outputs are local drafts under /tmp/alai/seo-client/<client-slug>/ for human review before delivery.

Inputs

Deliverables (5 Bosnian DRAFTS)

  1. gbp-content.md — GBP optimization content:
    • Business description (max 750 chars, keyword-rich, natural BS)
    • Primary + 2-3 secondary categories (from GBP taxonomy)
    • Suggested attributes (wheelchair accessible, parking, etc.)
    • 3-5 sample GBP posts (seasonal offers, service updates, local events)
    • Review-ask template (polite, brief, BS)
  2. competitor-benchmark.md — Competitor analysis:
    • For each competitor (up to 3): GBP completeness, review count/rating, categories, notable strengths
    • Client gap analysis + quick wins
    • Actionable recommendations
    • Note: No live GBP API scraping (Phase 10+); manual research or intake-provided competitor URLs
  3. client-report.md — Client-facing SEO readiness report (BS):
    • Executive summary (current status + top opportunity)
    • Goals (from intake: target location, priority services, conversion action)
    • Current status table (Technical SEO, On-page, Content, Local SEO, Conversion — RAG status)
    • Top findings (P0/P1/P2 prioritized)
    • Recommended action plan (Week 1-2, Month 1, Month 2-3)
    • What we need from client (access, approvals, content)
    • Measurement (KPIs: organic traffic, GBP interactions, contact forms)
    • Disclaimer: SEO does NOT guarantee ranking/traffic
    • Evidence grounding: portal audit findings (if website exists) or GBP checklist (if GBP-first mode)
  4. client-email-draft.md — Draft client email (BS):
    • Subject line suggestion
    • Summary: what was reviewed, top findings
    • Immediate asks: missing access, info gaps, priorities
    • Next steps: what ALAI/partner will do after client responds
    • Disclaimer: readiness review only, no ranking/traffic guarantee
    • Mark as DRAFT — never auto-send
  5. owner-gbp-claim-guide.md — Step-by-step GBP claim + add-ALAI-as-Manager guide (BS):
    • Go to business.google.com
    • Search for business name + location
    • Claim existing listing (if unclaimed)
    • Verify ownership (postcard/phone/email)
    • Complete profile: hours, photos, services, description
    • Add ALAI/partner as Manager (Settings → Users → Add user, role: Manager)
    • Notify ALAI/partner when access granted
    • Screenshot placeholders: [Screenshot: GBP claim button]

Guardrails

Workflow Modes

Evidence Bundle

On completion, creates /tmp/alai/seo-client/<client-slug>/DELIVERABLES-MANIFEST.md with:

Registration

Registered in ~/.claude/skill-registry.db:
- Name: seo-client
- Triggers: /seo-client, "seo client workflow", "process seo intake", "generate seo deliverables", "asmir seo tip"
- Domain: seo-operations
- Level: 3
- Max Turns: 30
- Status: active

Layer 3: Intake Auto-Ingest

Location

~/business/ALAI-Holding-AS/products/SEO-Readiness-Portal/scripts/ingest-intake-email.ts

Purpose

Parse inbound client SEO intake email (numbered questionnaire format) and append a DRAFT Client+Site+Intake record to the portal workspace. Idempotent via ingest ledger. Read-only email access; no email send.

Usage

# Ingest specific email by ID
npm run ingest:intake -- --email-id <id>

# Scan pending ACTION emails (list only)
npm run ingest:intake -- --scan

# Dry-run mode (no writes)
npm run ingest:intake -- --email-id <id> --dry-run

# Auto-run audit after ingest (deferred; not implemented in current draft)
npm run ingest:intake -- --email-id <id> --run-audit

Workflow

  1. Email fetch: Shell-out to node ~/system/tools/email-inbox.js show <id> (read-only, no network calls)
  2. Parse: Extract numbered intake fields:
    • Business name, location, services, languages
    • Target markets (local/regional/national)
    • Competitors (names or URLs)
    • GBP status (claimed/unclaimed, manager access yes/no)
    • Website status (has website yes/no, URL if yes)
    • Analytics/Search Console status
    • Priority services, conversion goals
  3. Workspace append: Create draft Client, Site, Intake objects:
    • client.status = "lead"
    • intake.status = "submitted"
    • intake.hasWebsite = inferred from question "Do you have a website?"
    • site.canonicalUrl = empty if no website (triggers GBP-first mode in skill)
  4. Idempotency: Dedup by source email ID via .data/ingest-ledger.json:
    • Schema: { schemaVersion: 1, updatedAtUtc, ingestedEmailIds: { [emailId]: { emailId, clientId, siteId, intakeId, ingestedAtUtc } } }
    • If email ID already in ledger → skip (NOOP)
  5. Output: JSON summary to stdout:
    • Email ID, client ID, site ID, intake ID
    • Client name, status, target markets
    • Site domain (or "no website — GBP/local mode")
    • Intake status, hasWebsite, gbpClaimed, gbpManagerAccess, priorityServicesCount, competitorsCount

Guardrails

Launchd Wrapper (Deferred)

Template at scripts/launchd/com.alai.seo-intake-ingest.plist:
- NOT installed (manual trigger for now)
- When enabled: periodic scan for ACTION emails, auto-ingest eligible intake questionnaires
- Safe + logged (writes to ~/logs/seo-intake-ingest.log)

End-to-End Flow

  1. Intake email arrives (from Asmir or direct client) → tagged ACTION by email-inbox.js rules
  2. Layer 3 ingest: npm run ingest:intake -- --email-id <id> → creates draft client in portal workspace
  3. Portal GBP audit: CEO or automated task runs audit (Layer 1) → evidence collected
  4. Layer 2 skill: /seo-client generates 5 Bosnian DRAFT deliverables
  5. CEO review: human reviews drafts at /tmp/alai/seo-client/<client-slug>/
  6. Send: CEO or agent manually copies content to client email / BookStack client page

Limitations / Deferred

Evidence

Revision #1
Created 2026-06-03 12:45:44 UTC by John
Updated 2026-06-03 12:45:44 UTC by John