Agent Website Reference

Agent workflows

Repeatable paths through the repo

These workflows prevent future agents from treating website work as disconnected edits. Each path ties source retention, page structure, machine-readable facts, and verification together.

Agent orientation

A future agent receives only the main URL and needs to understand the website and repo.

Inputs

  • Main URL
  • /agent-manifest.json
  • /file-map.json
  • AGENTS.md
  • docs/agent-playbook.md

Outputs

  • Context summary
  • Relevant source-file list
  • QA command plan
  1. Open the main URL.
  2. Read /agent-manifest.json.
  3. Read AGENTS.md and docs/agent-playbook.md.
  4. Read /file-map.json to identify source files and generated outputs.
  5. Run npm run qa:all before changing behavior.

Completion criteria

  • Agent can describe repo purpose without chat context
  • Agent can identify canonical data and QA files
  • Agent knows which command proves baseline health

Adapt this starter to a real site

A business site needs to be created from source evidence.

Inputs

  • Public-safe business facts
  • Raw source archive
  • Brand assets
  • Target PUBLIC_SITE_URL

Outputs

  • Configured site
  • Updated machine endpoints
  • Source manifest
  • QA evidence
  1. Preserve raw inputs in data/sources/raw/ and write a manifest.
  2. Update src/site.config.ts and PUBLIC_SITE_URL.
  3. Replace placeholder pages with public-safe content.
  4. Update page schema endpoints and schemamap.xml entries together.
  5. Update llms.txt, llms-full.txt, sitemap.xml, and navigation.
  6. Run npm run qa:all, then browser and crawl QA.

Completion criteria

  • No placeholder identity remains
  • Every public claim traces to source or approved brief
  • qa:all passes
  • Crawl/browser evidence is recorded

Create a new page pattern

A site needs a new reusable page or endpoint pattern.

Inputs

  • Page objective
  • Source facts
  • Target URL
  • Schema type
  • Internal-link targets

Outputs

  • Astro route
  • Metadata
  • Schema endpoint when needed
  • Updated indexes
  1. Add the Astro route under src/pages/.
  2. Add metadata, canonical path, one H1, semantic sections, and proof/source notes.
  3. Add a matching schema endpoint when the page introduces reusable facts.
  4. Add navigation or hub links if the page is intended to be discovered.
  5. Update sitemap, llms endpoints, examples or file map if relevant.
  6. Run focused QA and fix failures.

Completion criteria

  • Route is linked or intentionally discoverable
  • Metadata and schema match visible content
  • Relevant generated indexes are updated
  • Focused QA passes

SEO and AEO readiness pass

A site has content but needs technical discovery and answer-engine readiness hardened.

Inputs

  • Built site
  • PUBLIC_SITE_URL
  • Page inventory
  • Entity facts
  • QA output

Outputs

  • Metadata fixes
  • Schema fixes
  • llms endpoint updates
  • Internal-link fixes
  1. Run npm run qa:seo and npm run qa:aeo.
  2. Check that page titles, descriptions, H1s, canonicals, and OG tags are unique and accurate.
  3. Check that schema endpoints expose only visible or source-backed facts.
  4. Check llms.txt and llms-full.txt for complete agent-readable coverage.
  5. Fix route, metadata, schema, or endpoint gaps at the source.
  6. Rerun npm run qa:all.

Completion criteria

  • SEO QA passes
  • AEO QA passes
  • Structured facts match public page content
  • Agent endpoints explain the current site

Launch QA

A site is close to release or handoff.

Inputs

  • Production build
  • Real PUBLIC_SITE_URL
  • Browser screenshots
  • Crawl evidence

Outputs

  • Launch QA report
  • Known-risk list
  • Ready/not-ready decision
  1. Run npm run qa:all.
  2. Build with the production PUBLIC_SITE_URL.
  3. Serve the static output and crawl it with Screaming Frog.
  4. Capture desktop and mobile screenshots.
  5. Record evidence and remaining risk in reports/.
  6. Do not call the site ready while placeholders, missing proof, or unresolved crawl issues remain.

Completion criteria

  • qa:all passes
  • Crawl evidence has no unresolved critical issues
  • Desktop and mobile screenshots show no clipping or overlap
  • Remaining risks are documented

Design system integration later

The technical/reference contract is stable and visual system work begins.

Inputs

  • Approved design direction
  • Component inventory
  • Current content model
  • Accessibility constraints

Outputs

  • Component tokens
  • Reusable layout primitives
  • Visual QA evidence
  1. Keep the current agent endpoints stable while changing presentation.
  2. Convert repeated patterns into components only where reuse is real.
  3. Add design tokens and component documentation without hiding technical content.
  4. Check desktop and mobile screenshots for text fit, hierarchy, and navigation clarity.
  5. Rerun npm run qa:all and browser QA.

Completion criteria

  • Main URL remains useful to agents
  • Design tokens do not break readability
  • Visual QA confirms no overlap or clipped text
  • Machine endpoints remain unchanged or intentionally versioned