jordanurbs/aeo-forge

1. Repository purpose

- This is an internal Claude Code workflow for AEO, not a product app.

- Its architecture centers on generating, validating, and tracking AI-search optimization work for a single brand profile at a time.

2. Primary control plane: Claude Code commands

- The main user entrypoints are /setup, /aeo-plan, /aeo-build, and /aeo-track.

- These commands orchestrate the whole lifecycle: configuration, research/planning, artifact generation, and ongoing citation measurement.

3. Agent-based pipeline

- The .claude/agents directory defines specialized roles that each own a narrow phase of work: crawler, API caller, competitor researcher, demand researcher, analyst, strategist, builders, validator, and citation tracker.

- This creates a staged pipeline where each agent hands structured outputs to the next rather than one monolithic prompt.

4. Skills as reusable policy/knowledge modules

- .claude/skills contains reusable guidance for AEO, schema authoring, citation tracking, local SEO, technical SEO, llms.txt, and related practices.

- These skills act like shared domain libraries that inform the agents’ decisions and keep outputs consistent across runs.

5. Configuration boundary

- Brand-specific inputs live in config/brand-profile.md with an example template in config/brand-profile.example.md.

- This file is the main source of truth for domains, entity signals, tech stack, AEO targets, and governance constraints.

6. Plan-stage data flow

- /aeo-plan gathers evidence from site crawling, external tool/API checks, competitor benchmarking, and demand research.

- The AEO Analyst synthesizes those inputs into a readiness assessment, and the AEO Strategist turns that into plan/aeo-plan.md, which becomes the approval gate for build selection.

7. Build-stage artifact generation

- /aeo-build consumes the approved plan items and emits deployable artifacts under output/<brand-slug>/artifacts/.

- The build is modular: answer-first content, stacked JSON-LD schema, metadata tags, entity knowledge graph, measurement pack, content briefs, optional llms.txt, and optional edge injection config.

8. Validation boundary

- Artifact validation is not left to the agents alone; it is enforced by scripts/validate-artifacts.py.

- The README indicates this validator checks JSON parsing, coverage of selected plan items, AEO traceability, schema/entity consistency, and FAQ/HowTo visible-text parity before output is considered shippable.

9. Citation tracking loop

- /aeo-track turns the manual measurement plan into an executed run against AI answer engines.

- The deterministic runner in scripts/run-citation-checks.py handles orchestration, while the Citation Tracker agent interprets results and maintains a running citation scoreboard.

10. External services and evidence sources

- The plan stage can incorporate real API data from PageSpeed Insights, TLS/SSL checks, W3C validation, Wayback Machine, and WHOIS/RDAP.

- Demand signals may also come from Google Autocomplete, People Also Ask, and optional search-volume providers; measurement can use Perplexity, OpenAI web search, or SerpAPI when keys are available.

11. Output structure as the main artifact boundary

- output/<brand-slug>/ is the durable workspace for one brand run, with subfolders for research, plan, artifacts, measurement runs, and reports.

- fixtures/sample-output/acme-analytics/ provides a complete example of the expected shape and acts as a reference implementation for the repo’s contract.

12. Operational quality model

- The repo explicitly distinguishes COMPLETE, PARTIAL_CONFIDENCE, and BLOCKED states.

- That means the architecture is evidence-driven: outputs must be traceable to brand profile, crawl data, tool data, competitor analysis, AEO analysis, or clearly labeled inference before they are treated as valid work product.