kubical-ai/aeo-geo-agent

AEO/GEO Optimization Agent

A five-phase optimization agent that audits your documentation site against a 29-item AEO/GEO checklist, lets you choose which items to tackle, creates research-backed implementation plans, executes them one at a time with your approval at each step, and verifies results.

Before starting: Ask the user for their docs project path (local directory). If they haven't provided one, ask now.

---

Five-Phase Workflow

Phase 1: Assess   → Scan project, score all 29 items, identify quick wins
Phase 2: Select   → Human-in-the-loop item selection via multi-select
Phase 3: Plan     → Research-backed implementation plan per selected item
Phase 4: Execute  → Implement one item at a time, checkpoint after each
Phase 5: Verify   → Re-scan and compare before/after, produce final report

---

Phase 1 — Assessment

Goal: Produce a scored assessment of all 29 AEO/GEO items for the user's project.

Steps:

1. Load references/checklist.md — this is your master reference for all 29 items
2. Run the scanner script:

   python3 scripts/assess_project.py --project-root <path> --output /tmp/aeo-assessment.json
   

3. Follow the assessor subagent instructions in agents/assessor.md for qualitative analysis of content-quality items
4. Run the report generator:

   python3 scripts/generate_report.py --assessment /tmp/aeo-assessment.json --output /tmp/aeo-report.md
   

5. Present the report to the user. Highlight the Quick Wins section (high impact + low difficulty + not implemented).

Rating scale: ✅ Implemented · 🟡 Partial · ❌ Not Implemented · ⬜ N/A

Save the assessment JSON to /tmp/aeo-assessment-baseline.json for later comparison in Phase 5.

---

Phase 2 — Selection (Human-in-the-Loop)

Goal: Let the user choose which items to implement.

Approach: Present items in priority-ordered groups:

Round 1 — Quick Wins

Show the not-implemented items that are High Impact + Low/Medium Difficulty. Ask:

"Which Quick Win items do you want to tackle? (select all that apply)"

Format each option as: #N — Item Name (⏱ time estimate)

Round 2 — High Impact (remaining)

Show remaining High Impact items not yet selected. Same format.

Round 3 — Medium Impact

Continue with medium-impact items.

After all rounds: Present the complete selected list, sorted by dependency order (see Dependency Map below). Ask the user to confirm or reorder before planning begins.

Dependency Map:

• #2 requires #1 (llms-full.txt requires llms.txt)
• #25 requires #1 (directory registration requires llms.txt)
• #6 benefits from #5 (SoftwareApplication JSON-LD after Organization)
• #11 benefits from #5 and #6 (FAQPage after base schemas)
• Execute in dependency order automatically

---

Phase 3 — Planning

Goal: Create a research-backed implementation plan for each selected item.

Follow the planner subagent instructions in agents/planner.md.

Present all plans to the user as a single document. They can:

• Approve all plans → begin execution
• Request changes to specific plans → revise and re-present
• Remove items from the list → update execution queue

---

Phase 4 — Execution (Sequential with Checkpoints)

Goal: Implement items one at a time, in dependency order, with user approval between each.

For each item, follow the executor subagent instructions in agents/executor.md.

Delegation Routing Table

| Item(s) | Strategy | Action | |---------|----------|--------| | #1, #2 | llms-txt-creator skill | Use the llms-txt-creator skill (uploaded separately) | | #3, #4, #7, #8, #10, #15, #16, #18, #19, #21, #23, #28 | direct | Implement directly per the plan (GEO content, technical SEO, meta tags) | | #5, #6, #11, #14 | direct | Implement directly (JSON-LD schema generation) | | #17, #22 | direct | Implement directly (meta audit, Core Web Vitals) | | #12 | ai-prompt-files skill | Use the ai-prompt-files skill (uploaded separately) | | #13 | direct | Implement directly (MCP server scaffolding) | | #25, #26 | ai-discoverability skill | Use the ai-discoverability skill (uploaded separately) | | #9, #20, #24, #27, #29 | direct | Implement directly per the plan |

After Each Item — Checkpoint

After each item is complete, present:

✅ Item #N (Item Name) complete.

Changes made:
  • [list files created/modified]

How would you like to proceed?
(a) Approve and continue to next item
(b) Request changes to this item
(c) Skip to next item
(d) Stop and review all changes so far

• Response (a): continue to next item
• Response (b): loop executor with feedback, re-implement, re-checkpoint
• Response (c): mark as skipped, continue to next
• Response (d): stop execution, summarize all changes, offer to resume or go to Phase 5

Write a brief summary of each completed item to .aeo-work-log.md in the project root.

---

Phase 5 — Verification

Goal: Confirm what was implemented, flag any issues, produce a final report.

Follow the verifier subagent instructions in agents/verifier.md.

Steps:

1. Re-run the scanner and compare to baseline:

   python3 scripts/verify_implementations.py \
     --baseline /tmp/aeo-assessment-baseline.json \
     --project-root <path> \
     --output /tmp/aeo-verification.md
   

2. Do qualitative spot checks on implemented items
3. Present final report: items improved, items with issues, remaining items

---

Companion Skills

Upload these skills alongside this one for full coverage:

| Skill | Items | Upload as | |-------|-------|-----------| | llms-txt-creator | #1, #2 | Separate skill ZIP | | ai-prompt-files | #12 | Separate skill ZIP | | ai-discoverability | #25, #26 | Separate skill ZIP |

---

Reference Files

Load on-demand as needed (don't pre-load all):

| File | Load When | |------|-----------| | references/checklist.md | Phase 1 (always) — 29-item master reference | | references/assessment-rubric.md | Phase 1 — qualitative scoring criteria | | references/geo-research.md | Phase 3 — planning GEO content items (#3, #4, #15, #16, #19) | | references/llms-txt-spec.md | Phase 3 — planning items #1, #2, #25 |

---

Item Reference (Quick Lookup)

| # | Item | Category | Impact | Time | |---|------|----------|--------|------| | 1 | llms.txt | AI Files | High | 2h | | 2 | llms-full.txt | AI Files | High | 1h | | 3 | GEO content optimization | Content | High | 8h | | 4 | Question-based headings | Content | High | 4h | | 5 | Organization JSON-LD | Structured Data | High | 1h | | 6 | SoftwareApplication JSON-LD | Structured Data | High | 1h | | 7 | robots.txt AI crawler access | Technical | High | 30m | | 8 | Meta tags (title/description) | Technical | High | 2h | | 9 | Multi-language code examples | Content | High | 8h | | 10 | OG / social meta tags | Technical | Med | 2h | | 11 | FAQPage JSON-LD | Structured Data | High | 3h | | 12 | AI editor prompt files | AI Files | Med | 2h | | 13 | MCP server | AI Integration | High | 16h | | 14 | BreadcrumbList JSON-LD | Structured Data | Med | 1h | | 15 | Comparison guides | Content | High | 8h | | 16 | Glossary / terminology | Content | Med | 4h | | 17 | Core Web Vitals | Technical | Med | 8h | | 18 | Sitemap.xml | Technical | Med | 1h | | 19 | Long-tail FAQ content | Content | High | 6h | | 20 | Semantic search | Technical | Med | 16h | | 21 | Canonical URLs | Technical | Med | 1h | | 22 | Title/description optimization | Technical | Med | 4h | | 23 | TechArticle JSON-LD | Structured Data | Med | 2h | | 24 | Changelog | Content | Low | 2h | | 25 | llms.txt directory registration | AI Discoverability | High | 1h | | 26 | External backlinks / authority | AI Discoverability | High | 8h | | 27 | i18n / multilingual | Content | Med | 16h | | 28 | Internal linking | Technical | Med | 4h | | 29 | OpenAPI spec | AI Integration | Med | 8h |