{"description":"Structured product roadmap for building the agent-facing website operating system to full completion.","objective":"Execute every value multiplier with detailed steps, stress tests, acceptance criteria, and alignment back to the system purpose.","roadmap":[{"priority":1,"id":"step-by-step-agent-walkthroughs","title":"Step-by-step agent walkthroughs","valueMultiplier":"Turns vague website work into deterministic operating behavior.","objective":"Every major website-building task decomposes into objective, why, detailed steps, required evidence, pass/warn/fail criteria, and good/bad examples.","why":"Agents often complete the headline request and miss hidden work. The system must force the reasoning path so quality does not depend on agent intuition.","executionItems":["Create a reusable walkthrough data model.","Convert current workflows into detailed walkthroughs.","Add pass, warning, and fail criteria for each walkthrough.","Attach example evidence paths and relevant QA commands.","Expose walkthroughs through the manifest and a dedicated endpoint."],"stressTests":["Give an agent only the main URL and confirm it can enumerate the required steps for SEO, AEO, buildout, and handoff.","Remove one required detail from a walkthrough and confirm QA fails.","Ask an agent to adapt a site type and confirm it cites the walkthrough before editing."],"acceptanceCriteria":["Every roadmap area has objective, why, steps, evidence, and pass/fail criteria.","The manifest exposes the walkthrough model.","QA validates that no major area is only a vague objective statement."],"objectiveAlignment":"Directly supports the system mission by making the agent inspect, plan, build, validate, and improve without prior context."},{"priority":2,"id":"machine-readable-contracts","title":"Machine-readable contracts","valueMultiplier":"Lets agents consume the system reliably without scraping prose.","objective":"Expose every critical concept as structured JSON with matching schemas and validation.","why":"Agents need stable contracts for routes, files, examples, QA, tasks, roadmap, and future evaluation rubrics.","executionItems":["Maintain /agent-manifest.json as the top-level index.","Keep /file-map.json, /qa-contract.json, /examples.json, /agent-tasks.json, and /product-roadmap.json aligned.","Add JSON Schema for each endpoint.","Validate endpoint shapes in qa:aeo.","Document contract-change rules in AGENTS and playbook."],"stressTests":["Fetch every machine endpoint and validate JSON shape.","Break one endpoint schema intentionally in a fixture and confirm validation catches it.","Confirm all file-map paths resolve on disk."],"acceptanceCriteria":["Every machine endpoint has a schema.","qa:aeo validates all required contract fields.","Future agents can identify all machine endpoints from /agent-manifest.json."],"objectiveAlignment":"Supports context discovery from the main URL and prevents drift between human docs and agent-readable data."},{"priority":3,"id":"good-bad-example-library","title":"Good and bad example library","valueMultiplier":"Turns external site audits into reusable training data.","objective":"Create a structured library of site studies with patterns to reuse, failures to avoid, evidence paths, and checks to add.","why":"Agents learn faster from concrete examples. A good example without its failure modes is incomplete training data.","executionItems":["Define a site-study schema.","Add Nectiv as the first site study.","Capture good patterns, bad patterns, why each matters, and how to detect each one.","Link each pattern to roadmap tasks or QA checks.","Add future examples across local service, SaaS, agency, content hub, and poor AI-generated sites."],"stressTests":["Ask an agent what to copy from Nectiv and what to avoid.","Confirm each site-study issue maps to a check, task, or explicit non-action.","Confirm evidence paths exist for each saved site study."],"acceptanceCriteria":["Site studies are structured and machine-readable.","At least one good and one bad pattern exists for each study.","The system can generate QA improvements from site-study findings."],"objectiveAlignment":"Improves the reference layer by grounding standards in real-world evidence."},{"priority":4,"id":"seo-aeo-evaluation-layer","title":"SEO/AEO evaluation layer","valueMultiplier":"Makes the system capable of judging websites, not just describing them.","objective":"Build a repeatable SEO/AEO evaluation suite covering crawlability, indexability, metadata, schema, LLM endpoints, and domain behavior.","why":"Small technical gaps can break search and model consumption even when a site looks polished.","executionItems":["Add apex/www/http/https/TLS checks.","Compare sitemap URLs against crawled indexable URLs.","Check robots, canonicals, titles, descriptions, H1s, and indexability.","Validate schema by page type.","Require llms.txt and llms-full.txt where AEO/AI-search claims exist.","Classify crawler-visible 403s separately from confirmed broken links."],"stressTests":["Run against Nectiv and confirm the known issues are detected.","Run against the local starter build and confirm expected pass state.","Create fixture pages with missing H1/meta/schema and confirm failures are specific."],"acceptanceCriteria":["SEO/AEO checks produce machine-readable findings.","Findings include severity, why, evidence, and remediation.","The suite distinguishes fail, warning, and manual-verification states."],"objectiveAlignment":"Strengthens the evaluation layer and directly supports launch readiness."},{"priority":5,"id":"source-to-site-traceability","title":"Source-to-site traceability","valueMultiplier":"Prevents unsupported claims and makes generated websites auditable.","objective":"Track every public claim from raw source to cleaned fact, derived brief, page copy, schema, and QA evidence.","why":"Agents can invent proof, credentials, metrics, pricing, or service scope unless source truth is enforced.","executionItems":["Expand source-retention fixtures.","Create claim objects with source, allowed-use status, public copy, and schema mapping.","Add page briefs that cite cleaned facts.","Add QA checks for claim/proof traceability on proof-heavy pages.","Document privacy and permission boundaries."],"stressTests":["Insert an unsupported metric into a fixture brief and confirm review catches it.","Ask an agent to build a proof page and confirm it references source facts.","Confirm private/raw data is not surfaced in public outputs."],"acceptanceCriteria":["Every example claim has a source or an explicit placeholder status.","Proof/case-study patterns require source evidence.","Handoff reports include unresolved claim risks."],"objectiveAlignment":"Supports trustworthy buildout and avoids hallucinated website claims."},{"priority":6,"id":"site-type-build-playbooks","title":"Site-type build playbooks","valueMultiplier":"Lets agents choose the right operating path for different business models.","objective":"Create detailed playbooks for local service, B2B SaaS, professional services, ecommerce/product, content hub, proof hub, AI/AEO authority, and agent-facing documentation sites.","why":"A good website pattern changes by business model. A local service site, SaaS site, and proof hub should not share the same page map or schema defaults.","executionItems":["Define required pages for each site type.","Define schema, metadata, internal-link, proof, and conversion requirements.","Map each playbook to examples and QA commands.","Add source-input requirements for each site type.","Expose playbooks as structured JSON."],"stressTests":["Ask an agent to choose a playbook from a short business brief.","Confirm the chosen playbook lists pages, schema, source needs, and QA.","Compare two site types and confirm their requirements differ."],"acceptanceCriteria":["Each site type has detailed requirements and rationale.","Each playbook maps to page patterns and QA checks.","Agents can select and justify a playbook."],"objectiveAlignment":"Moves the execution layer from generic site advice to business-specific build systems."},{"priority":7,"id":"page-pattern-library","title":"Reusable page pattern library","valueMultiplier":"Gives agents page-level contracts instead of blank-page generation.","objective":"Define patterns for homepage, service, product/technology, comparison, case study, proof, FAQ, glossary/entity, article, contact, AI instructions, privacy, and security pages.","why":"Most website quality failures happen at page level: wrong heading, wrong schema, missing proof, weak internal links, or unsupported claims.","executionItems":["Create a page-pattern data model.","Define required sections and schema for each page type.","Add SEO/AEO requirements per page type.","Add good/bad examples for each pattern.","Add page-pattern validation hooks where possible."],"stressTests":["Ask an agent to create a page from a pattern and inspect whether all required sections appear.","Remove a required section from a fixture and confirm QA or review flags it.","Compare visible content against schema facts."],"acceptanceCriteria":["Every core page type has a pattern contract.","Pattern contracts include why, evidence, pass/fail, and examples.","Page patterns are linked from relevant playbooks."],"objectiveAlignment":"Improves build quality by making page creation systematic."},{"priority":8,"id":"browser-visual-qa","title":"Automated browser and visual QA","valueMultiplier":"Catches layout and interaction failures that static crawls cannot see.","objective":"Add browser checks for desktop/mobile rendering, clipping, overlap, navigation, visible headings, and screenshot evidence.","why":"A technically valid site can still fail for users or agents if text clips, controls overlap, or navigation breaks.","executionItems":["Create browser test runner scripts.","Capture desktop and mobile screenshots for core routes.","Check for visible H1, nav, footer, and primary content.","Add heuristics for clipped or overlapping text.","Store screenshots and findings under reports/browser/."],"stressTests":["Run browser QA at mobile and desktop widths.","Introduce a fixture with clipped text and confirm failure.","Confirm screenshot paths are recorded in handoff evidence."],"acceptanceCriteria":["Browser QA is repeatable locally.","Screenshots are saved for core routes.","Visual failures produce actionable findings."],"objectiveAlignment":"Completes the evaluation layer beyond static crawl and build checks."},{"priority":9,"id":"crawl-evidence-artifacts","title":"Crawl evidence as a first-class artifact","valueMultiplier":"Makes launch and audit decisions evidence-backed.","objective":"Standardize crawl execution, exports, summaries, and before/after evidence.","why":"Without saved crawl evidence, agents repeatedly rediscover the same issues and cannot prove readiness.","executionItems":["Create a crawl report format.","Record target, date, settings, exports, findings, and residual risk.","Add summary parsers for Screaming Frog exports.","Add before/after comparison guidance.","Link crawl artifacts from handoff reports."],"stressTests":["Run a crawl and verify required exports exist.","Parse crawl overview into structured findings.","Confirm a missing export fails the report completeness check."],"acceptanceCriteria":["Crawl evidence has a standard path and summary shape.","Critical crawl findings are machine-readable.","Handoff reports cite crawl evidence."],"objectiveAlignment":"Improves evaluation and source-of-truth continuity."},{"priority":10,"id":"agent-backlog-intelligence","title":"Agent backlog intelligence","valueMultiplier":"Lets future agents continue product work without asking what is next.","objective":"Turn /agent-tasks.json into a serious execution queue with priority, rationale, dependencies, acceptance criteria, risks, and evidence links.","why":"The system should always explain what remains incomplete and how to improve it safely.","executionItems":["Expand task fields beyond title/status.","Add dependencies, risk, evidence, and expected output.","Map tasks to roadmap items.","Add task validation to QA.","Add completed-task evidence links."],"stressTests":["Ask an agent to choose the next task and justify the choice.","Confirm every task maps to a roadmap item.","Confirm no high-priority task lacks acceptance criteria."],"acceptanceCriteria":["Every task has enough detail to execute.","Backlog ordering reflects product priorities.","Completed tasks include evidence."],"objectiveAlignment":"Supports continuous improvement without hidden open loops."},{"priority":11,"id":"design-system-contracts","title":"Design system contracts","valueMultiplier":"Makes design agent-operable instead of just attractive.","objective":"Define design tokens, component rules, layout standards, accessibility constraints, and screenshot pass/fail criteria.","why":"Design work should improve clarity and usability without breaking the agent-readable technical surface.","executionItems":["Create design principles tied to site purpose.","Define tokens for typography, spacing, color, and layout.","Define component usage rules.","Add responsive behavior requirements.","Validate screenshots after visual changes."],"stressTests":["Apply design changes and confirm agent pages remain readable.","Check mobile and desktop screenshots.","Confirm UI changes do not hide machine endpoint discovery."],"acceptanceCriteria":["Design rules are documented and structured.","Components have usage guidance.","Visual QA passes after design changes."],"objectiveAlignment":"Adds polish only after the technical operating system remains intact."},{"priority":12,"id":"aeo-geo-model-context","title":"AEO/GEO model context","valueMultiplier":"Makes websites easier for answer engines and agents to understand.","objective":"Standardize model-readable context: AI instructions, LLM files, entity summaries, answer-ready sections, tables, FAQs, schema maps, and source-backed facts.","why":"AEO/GEO work requires explicit context surfaces, not only traditional HTML pages.","executionItems":["Define AI instructions page pattern.","Enhance llms.txt and llms-full.txt requirements.","Add entity-summary and answer-ready content rules.","Add table/FAQ/schema guidance for citation-worthy facts.","Compare model-readable context against visible content."],"stressTests":["Ask an agent to summarize the site from LLM endpoints only.","Confirm model-readable facts match visible source-backed facts.","Run a missing-LLM-endpoint fixture and confirm failure."],"acceptanceCriteria":["AEO pages expose direct answers and source-backed facts.","LLM endpoints are complete and current.","Agent-facing pages are treated as first-class SEO assets."],"objectiveAlignment":"Strengthens the agent-readiness and answer-engine layer."},{"priority":13,"id":"why-explanations-everywhere","title":"Why explanations everywhere","valueMultiplier":"Improves agent compliance by explaining the reason behind each check.","objective":"Attach rationale to every checklist item, QA finding, roadmap task, and page pattern requirement.","why":"Agents are more reliable when they understand why a step exists and what breaks if it is skipped.","executionItems":["Audit existing checks for missing rationale.","Add why fields to tasks, playbooks, page patterns, and QA findings.","Document failure modes beside each check.","Add schema validation for required rationale fields.","Use Nectiv examples to show why small technical gaps matter."],"stressTests":["Remove a rationale field and confirm schema/QA catches it.","Ask an agent why a check exists and confirm it can answer from the manifest.","Confirm final reports include why for major findings."],"acceptanceCriteria":["No major requirement is rationale-free.","Machine endpoints expose why fields.","Reports explain impact, not just status."],"objectiveAlignment":"Supports the detailed walkthrough rule and makes the system teach, not merely assert."},{"priority":14,"id":"real-site-comparisons","title":"Comparison against real sites","valueMultiplier":"Continuously improves the system through external evidence.","objective":"Create repeatable site-study workflows for excellent, average, and poor websites across categories.","why":"The operating system should learn from real-world SEO/AEO patterns rather than staying theoretical.","executionItems":["Define site-study intake process.","Crawl and inspect each target.","Classify good patterns and failure modes.","Convert findings into roadmap tasks or QA checks.","Maintain a site-study index."],"stressTests":["Run the workflow on Nectiv and at least one contrasting weak site.","Confirm each study produces reusable checks.","Confirm study evidence is saved and discoverable."],"acceptanceCriteria":["Every site study has evidence, analysis, and extracted lessons.","Studies feed the roadmap or examples library.","Agents can compare patterns across studies."],"objectiveAlignment":"Keeps the reference layer grounded in live market examples."},{"priority":15,"id":"handoff-reports","title":"Handoff reports","valueMultiplier":"Makes work durable across agents and sessions.","objective":"Create a standard final report format for builds, audits, fixes, verification, residual risks, and next steps.","why":"Without a handoff artifact, future agents lose context and users cannot judge readiness.","executionItems":["Define handoff report schema.","Include changed files, verification, crawl/browser evidence, unresolved risks, and next tasks.","Add templates for audit-only, buildout, launch, and fix reports.","Link handoff reports from agent tasks.","Validate report completeness before ready state."],"stressTests":["Generate a handoff after a crawl audit.","Generate a handoff after a site build fixture.","Confirm missing evidence or unresolved risk is visible."],"acceptanceCriteria":["Every substantial task can produce a standard handoff.","Reports include evidence and residual risk.","Future agents can resume from the report."],"objectiveAlignment":"Completes the operating loop: inspect, build, validate, and hand off."}]}