# jordanurbs/aeo-forge architecture

> Architecture diagram of the GitHub repository jordanurbs/aeo-forge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jordanurbs/aeo-forge
- Repository: https://github.com/jordanurbs/aeo-forge

## Overview

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.

Main entry points: [`.claude/agents/aeo-analyst.md`](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/aeo-analyst.md) (AEO Analyst), [`.claude/commands/aeo-plan.md`](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/aeo-plan.md) (aeo-plan), [`.claude/skills`](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/skills) (Skills), [`output`](https://github.com/jordanurbs/aeo-forge/tree/main/output) (Artifacts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control_plane["Control Plane"]
  node_setup_cmd["setup<br/>command<br/>[setup.md]"]
  node_plan_cmd["aeo-plan<br/>command<br/>[aeo-plan.md]"]
  node_build_cmd["aeo-build<br/>command<br/>[aeo-build.md]"]
  node_track_cmd["aeo-track<br/>command<br/>[aeo-track.md]"]
end

subgraph group_agents["Agents"]
  node_crawler_agent(("Crawler<br/>agent<br/>[web-crawler.md]"))
  node_api_agent(("API Caller<br/>agent<br/>[api-caller.md]"))
  node_competitor_agent(("Competitor Researcher<br/>agent"))
  node_demand_agent(("Demand Researcher<br/>agent"))
  node_analyst_agent(("AEO Analyst<br/>agent<br/>[aeo-analyst.md]"))
  node_strategist_agent(("AEO Strategist<br/>agent<br/>[aeo-strategist.md]"))
  node_builder_agent["Builders<br/>agent-set"]
  node_validator_agent(("Validator<br/>agent"))
  node_tracker_agent(("Citation Tracker<br/>agent"))
end

subgraph group_knowledge["Skills"]
  node_skills_core{{"Skills<br/>skill library<br/>[skills]"}}
end

subgraph group_workspace["Brand Workspace"]
  node_brand_profile["Brand Profile<br/>config"]
  node_plan_artifact["AEO Plan<br/>plan artifact<br/>[aeo-plan.md]"]
  node_artifacts_root[("Artifacts<br/>build output")]
  node_sample_output[("Sample Run<br/>reference output")]
end

subgraph group_automation["Automation"]
  node_validate_script["Validate Artifacts<br/>script"]
  node_run_checks_script["Run Checks<br/>script"]
end

node_setup_cmd -->|"configures"| node_brand_profile
node_plan_cmd -->|"runs"| node_crawler_agent
node_plan_cmd -->|"runs"| node_api_agent
node_plan_cmd -->|"runs"| node_competitor_agent
node_plan_cmd -->|"runs"| node_demand_agent
node_crawler_agent -->|"feeds"| node_analyst_agent
node_api_agent -->|"feeds"| node_analyst_agent
node_competitor_agent -->|"feeds"| node_analyst_agent
node_demand_agent -->|"feeds"| node_analyst_agent
node_analyst_agent -->|"hands off"| node_strategist_agent
node_strategist_agent -->|"writes"| node_plan_artifact
node_plan_cmd -->|"unlocks"| node_builder_agent
node_builder_agent -->|"validated by"| node_validate_script
node_builder_agent -->|"emits"| node_artifacts_root
node_validate_script -->|"approves"| node_artifacts_root
node_track_cmd -->|"executes"| node_run_checks_script
node_run_checks_script -->|"reports"| node_tracker_agent
node_tracker_agent -->|"updates"| node_artifacts_root
node_skills_core -.->|"guides"| node_analyst_agent
node_skills_core -.->|"guides"| node_strategist_agent
node_skills_core -.->|"guides"| node_builder_agent
node_skills_core -.->|"guides"| node_tracker_agent
node_sample_output -.->|"reference"| node_artifacts_root

click node_setup_cmd "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/setup.md"
click node_plan_cmd "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/aeo-plan.md"
click node_build_cmd "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/aeo-build.md"
click node_track_cmd "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/aeo-track.md"
click node_crawler_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/web-crawler.md"
click node_api_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/api-caller.md"
click node_competitor_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/competitor-researcher.md"
click node_demand_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/demand-researcher.md"
click node_analyst_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/aeo-analyst.md"
click node_strategist_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/aeo-strategist.md"
click node_validator_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/artifact-validator.md"
click node_tracker_agent "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/citation-tracker.md"
click node_brand_profile "https://github.com/jordanurbs/aeo-forge/blob/main/config/brand-profile.example.md"
click node_plan_artifact "https://github.com/jordanurbs/aeo-forge/blob/main/fixtures/sample-output/acme-analytics/plan/aeo-plan.md"
click node_artifacts_root "https://github.com/jordanurbs/aeo-forge/tree/main/output"
click node_sample_output "https://github.com/jordanurbs/aeo-forge/tree/main/fixtures/sample-output/acme-analytics"
click node_validate_script "https://github.com/jordanurbs/aeo-forge/blob/main/scripts/validate-artifacts.py"
click node_run_checks_script "https://github.com/jordanurbs/aeo-forge/blob/main/scripts/run-citation-checks.py"
click node_skills_core "https://github.com/jordanurbs/aeo-forge/blob/main/.claude/skills"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup_cmd,node_plan_cmd,node_build_cmd,node_track_cmd toneBlue
class node_crawler_agent,node_api_agent,node_competitor_agent,node_demand_agent,node_analyst_agent,node_strategist_agent,node_builder_agent,node_validator_agent,node_tracker_agent toneAmber
class node_skills_core toneMint
class node_brand_profile,node_plan_artifact,node_artifacts_root,node_sample_output toneRose
class node_validate_script,node_run_checks_script toneIndigo
```

## Components

### Control Plane

Claude Code commands that orchestrate the repo workflow.

- [setup](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/setup.md): command · Initializes brand-specific configuration and workflow state. · `.claude/commands/setup.md`
- [aeo-plan](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/aeo-plan.md): command · Drives research, evidence gathering, and plan synthesis. · `.claude/commands/aeo-plan.md`
- [aeo-build](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/aeo-build.md): command · Generates deployable AEO artifacts from an approved plan. · `.claude/commands/aeo-build.md`
- [aeo-track](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/commands/aeo-track.md): command · Executes citation checks and updates tracking state. · `.claude/commands/aeo-track.md`

### Agents

Specialized roles that execute stages of the AEO workflow.

- [Crawler](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/web-crawler.md): agent · Collects site and page evidence for analysis. · `.claude/agents/web-crawler.md`
- [API Caller](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/api-caller.md): agent · Runs external checks and tool/API lookups. · `.claude/agents/api-caller.md`
- [Competitor Researcher](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/competitor-researcher.md): agent · Benchmarks competing pages and SERP-adjacent patterns. · `.claude/agents/competitor-researcher.md`
- [Demand Researcher](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/demand-researcher.md): agent · Surfaces queries, intent, and demand signals. · `.claude/agents/demand-researcher.md`
- [AEO Analyst](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/aeo-analyst.md): agent · Synthesizes evidence into readiness and gap assessment. · `.claude/agents/aeo-analyst.md`
- [AEO Strategist](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/aeo-strategist.md): agent · Turns analysis into the approved AEO plan. · `.claude/agents/aeo-strategist.md`
- **Builders**: agent-set · Produces answer content, schema, metadata, entity, brief, llms.txt, and measurement artifacts.
- [Validator](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/artifact-validator.md): agent · Checks artifact consistency and shippability. · `.claude/agents/artifact-validator.md`
- [Citation Tracker](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/agents/citation-tracker.md): agent · Interprets citation run results and maintains scoreboard. · `.claude/agents/citation-tracker.md`

### Skills

Reusable policy and domain guidance shared across agents.

- [Skills](https://github.com/jordanurbs/aeo-forge/blob/main/.claude/skills): skill library · Shared domain guidance for optimization, schema, SEO, demand, and tracking. · `.claude/skills`

### Brand Workspace

Brand-specific inputs, plans, artifacts, and measurement outputs.

- [Brand Profile](https://github.com/jordanurbs/aeo-forge/blob/main/config/brand-profile.example.md): config · Single source of truth for brand inputs and constraints. · `config/brand-profile.example.md`
- [AEO Plan](https://github.com/jordanurbs/aeo-forge/blob/main/fixtures/sample-output/acme-analytics/plan/aeo-plan.md): plan artifact · Approved plan that gates build selection. · `fixtures/sample-output/acme-analytics/plan/aeo-plan.md`
- [Artifacts](https://github.com/jordanurbs/aeo-forge/tree/main/output): build output · Durable output tree for generated AEO deliverables. · `output`
- [Sample Run](https://github.com/jordanurbs/aeo-forge/tree/main/fixtures/sample-output/acme-analytics): reference output · Example brand workspace showing the expected repository contract. · `fixtures/sample-output/acme-analytics`

### Automation

Deterministic scripts that validate artifacts and run tracking.

- [Validate Artifacts](https://github.com/jordanurbs/aeo-forge/blob/main/scripts/validate-artifacts.py): script · Deterministic artifact validation before output is considered shippable. · `scripts/validate-artifacts.py`
- [Run Checks](https://github.com/jordanurbs/aeo-forge/blob/main/scripts/run-citation-checks.py): script · Deterministic runner for citation measurement orchestration. · `scripts/run-citation-checks.py`

## Connections

- setup → Brand Profile: configures · Creates or updates the brand-specific input boundary.
- aeo-plan → Crawler: runs · Starts crawl-based evidence collection.
- aeo-plan → API Caller: runs · Collects external checks and API evidence.
- aeo-plan → Competitor Researcher: runs · Adds competitor benchmarking to the research set.
- aeo-plan → Demand Researcher: runs · Adds demand and intent signals.
- Crawler → AEO Analyst: feeds · Provides crawl evidence for synthesis.
- API Caller → AEO Analyst: feeds · Provides tool and API evidence for synthesis.
- Competitor Researcher → AEO Analyst: feeds · Provides competitor comparisons for synthesis.
- Demand Researcher → AEO Analyst: feeds · Provides query and demand evidence for synthesis.
- AEO Analyst → AEO Strategist: hands off · Converts evidence into a readiness assessment.
- AEO Strategist → AEO Plan: writes · Produces the approved AEO plan.
- aeo-plan → Builders: unlocks · Approved plan items become build inputs.
- Builders → Validate Artifacts: validated by · Artifacts are checked for parsing, traceability, and parity.
- Builders → Artifacts: emits · Generates the modular artifact set under the brand workspace.
- Validate Artifacts → Artifacts: approves · Marks generated artifacts as shippable when checks pass.
- aeo-track → Run Checks: executes · Runs citation measurement checks.
- Run Checks → Citation Tracker: reports · Provides measurement results for interpretation.
- Citation Tracker → Artifacts: updates · Maintains citation scoreboard and run outputs.
- Skills → AEO Analyst: guides · Provides shared analysis and policy guidance.
- Skills → AEO Strategist: guides · Provides shared planning and optimization guidance.
- Skills → Builders: guides · Informs content, schema, metadata, and measurement generation.
- Skills → Citation Tracker: guides · Informs citation tracking behavior and interpretation.
- Sample Run → Artifacts: reference · Defines the expected output contract and folder shape.