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 using AskUserQuestion multi-select.

Approach: Present items in priority-ordered batches of ≤4 (tool cap). Group by tier:

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. Keep batches to 4.

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

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

Custom Subskills

The three custom subskills in skills/ handle items with no equivalent on the registry:

Reference Files

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

Item Reference (Quick Lookup)