Skip to main content

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 1: SEO Readiness Portal tool — local/cloud dual-mode audit, GBP/local-first for no-website clients (MC #102861, see GBP/Local-First Audit Mode)
  • Layer 2: /seo-client skill — generates 5 Bosnian DRAFT deliverables from intake
  • Layer 3: Intake auto-ingest — parses inbound email into portal workspace

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

  • Portal workspace: /path/to/portal/.data/workspace.json (client, site, intake objects)
  • Pasted intake email: numbered questionnaire text (like Asmir partner emails)
  • Email ID: --email-id <id> (fetches via email-inbox.js, read-only)

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

  • No ranking/traffic guarantees: forbidden words enforced (ranking|traffic|guarantee|guaranteed|first page|top results)
  • Drafts only: all outputs are local files; NO auto-send, NO email trigger
  • Optional Lexicon BS check: route to Lexicon (Dževad Jahić) for linguistic QA if requested
  • MAX TURNS: 30 (skill execution timeout)
  • No fabricated metrics: no Search Console/Analytics data without verified access
  • No hardcoded competitor data: always from intake or prompt user

Workflow Modes

  • GBP_FIRST mode: no website detected (intake.hasWebsite === false OR site.canonicalUrl empty)
    • Focus: owner-gbp-claim-guide.md as P0 deliverable
    • Skip website-specific audit findings
    • All deliverables optimized for GBP
  • WEBSITE_AND_GBP mode: website exists
    • Run portal audit: npm run audit -- --client <slug>
    • Parse audit findings for client report evidence
    • Include both website + GBP recommendations

Evidence Bundle

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

  • File checklist (all 5 deliverables)
  • Validation: PASS (no forbidden words)
  • Linguistic QA: PENDING | REVIEWED_BY_LEXICON
  • Approval: PENDING_HUMAN_REVIEW
  • Next steps: human review required before client delivery

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

  • DRAFT only: status = "lead"/"submitted" — no active/onboarded promotion
  • No audit auto-run: unless --run-audit flag (not implemented; manual run via portal)
  • No email send: read-only email access, no outbound mail
  • No production mutation: writes only to local workspace file (.data/workspace.json) + ledger

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

  • Live GBP API: Google OAuth + Places API deferred pending CEO approval (Phase 10+)
  • Launchd not installed: manual trigger for intake ingest (no auto-scan yet)
  • No auto-send: all deliverables require human review gate
  • No Search Console/Analytics API: access verification deferred
  • Single language: Bosnian (BS) only; EN/DE deferred
  • No BookStack page auto-creation: manual copy-paste for client-facing docs
  • Layer 1: GBP/Local-First Audit Mode
  • SEO Operations Playbook: ~/business/ALAI-Holding-AS/sales/seo-automation/SEO-OPERATIONS-PLAYBOOK.md
  • Client Report Template: ~/business/ALAI-Holding-AS/sales/seo-automation/seo-client-report-template.md
  • Bosnian Linguistic QA: ~/system/rules/bosnian-linguistic-validation.md

Evidence

  • MC #102865: /seo-client skill authored at ~/.claude/skills/seo-client/SKILL.md
  • MC #102866: Intake ingest script at scripts/ingest-intake-email.ts
  • Test fixture: Asmir email #8792 (Smoke House Hadžići)
  • Skill registration: ~/.claude/skill-registry.db
  • Status: DRAFT (no deploy, no auto-send, no production data mutation)

No comments to display

Back to top