requirements · supabase_json
AD SEO Agent requirements
requirements artifact · for AD SEO Agent · status draft
Agent Handoff
Start Here
requirements artifact · for AD SEO Agent · status draft
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Artifact Shape
- status: approved
- handoff: notes_for_zara: object, notes_for_vikram: object, ready_for_ux_arch: boolean, blocking_question_ids: object
- project: id: string, name: string, client_id: string, intent_ref: string, intake_triage_ref: string, platform_project_id: string, platform_project_title: string
- features: 7 items
- dev studio: views: object, render_as: string
- ai first model: principle: string, object_model: object, primary_unit: string, ux_implications: object, architecture_implications: object
- schema version: 1.0
- product summary: goal: string, problem: string, must_show: object, primary_users: object, success_metrics: object
- global out of scope: 5 items
- global open questions: 2 items
- cross feature constraints: 9 items
Structured Payload
Machine-readable source fields
status
approved
handoff
notes for zara
- Prioritize a production demo flow: Hubbard identity, ROI first, opportunity board, agent activity/audit, governance actions, white-label story.
- The interface should feel like an operational product, not a marketing landing page.
- Mobile must remain usable, but desktop is likely the primary buyer-demo surface.
- Treat AD SEO Agent as a buyer-facing client project route, not an internal Dev Studio surface. It can have its own responsive product shell.
notes for vikram
- Use a hybrid data strategy: versioned seeded Hubbard dataset is required for Monday; live SEO providers are adapters/future enrichment.
- Define clear boundaries for provider failures, credential isolation, and browser-safe data.
- Agent activity/audit can use seeded event records if shaped like future live task events.
- Architecture must follow client project platform conventions: Cloudflare Pages/Workers/Images/Stream, Supabase Projects/Demo, and suite routing at
/seo. - Vikram owns platform-fit details if there is disagreement between generic app assumptions and client project architecture.
ready for ux arch
true
blocking question ids
No items captured.
project
id
ad-seo-agent
name
AD SEO Agent for Affiliated Distributor Networks
client id
ad
intent ref
docs/projects/ad-seo-agent/artifacts/INTENT.json
intake triage ref
docs/projects/ad-seo-agent/artifacts/INTAKE_TRIAGE.json
platform project id
0.0.8832348
platform project title
AD SEO Agent
features
| id | why | name | today | target | priority |
|---|---|---|---|---|---|
| F-01 | The demo only works if the buyer immediately sees Hubbard Supply Co. and its industrial distribution context, not a generic SEO product. | Hubbard Onboarding and Domain Context | The source thought defines the product concept, but no production pilot context exists for Hubbard. | The product opens with Hubbard Supply Co., domain https://www.hubbardsupply.com/, industrial/MRO positioning, and selected competitors or competitor placeholders. | P0 |
| F-02 | The CEO buying frame is money, not rankings. AD SEO Agent must show economic value before SEO detail. | ROI Baseline and Payback Story | The thought defines directional ROI framing but not concrete pilot fields. | The pilot shows editable current-spend baseline, projected replacement savings, opportunity value, and payback period for Hubbard. | P0 |
| F-03 | The product's core difference is not showing gaps; it shows winnable gaps, value, and action plans. | Actionable Competitor Opportunity Analysis | The thought describes competitor comparison done right but does not specify the opportunity artifact. | The pilot shows at least 10 Hubbard-specific opportunities with keyword/theme, competitor evidence, why winnable, estimated value, action plan, owner agent, and confidence. | P0 |
| F-04 | AD SEO Agent is also a agent-infrastructure proof point; users need to see governed agents doing the work, not a black-box report. | Visible Agent Cluster and Audit Trail | The thought defines the agent cluster concept but not the required production display. | The pilot shows agent activity cards, recommendation reasoning, action history, approval status, and audit metadata. | P0 |
| F-05 | The product must prove agents can execute without creating uncontrolled risk. | Governed Action Tiers | The source thought defines three tiers but not required behaviors. | Every recommended action is assigned to one of three governance tiers: autonomous, prepared-for-approval, or strategy-required. | P0 |
| F-06 | The affiliate distributor buyer needs to see AD SEO Agent as a native member-network product, not only a Dreamborn demo. | White-Label Network Story | The thought defines white-label requirements and exclusivity, but not what the first pilot must show. | The pilot includes a visible white-label preview or configuration summary showing how an affiliate distributor organization could brand and verticalize the Hubbard experience for its members. | P1 |
| F-07 | The target is production-ready by Monday, not a fragile mockup. | Production Pilot Reliability | No production pilot exists yet. | The pilot runs at /seo from stable seeded data, handles missing provider data, has no obvious broken states, and is ready to show on Monday, May 4, 2026. | P0 |
dev studio
views
- product_summary
- feature_cards
- scenario_table
- done_when_matrix
- open_questions
- handoff
render as
requirements
ai first model
principle
AD SEO Agent is not a dashboard with AI features. It is an agent operating surface where the core unit is a governed recommendation.
object model
| id | name | purpose |
|---|---|---|
| OBJ-01 | CompanyProfile | Defines the company being analyzed, its domain, vertical, categories, competitors, assumptions, and white-label context. |
| OBJ-02 | AnalysisRun | Represents one AI/agent analysis pass over a company profile. Owns status, freshness, source mode, cost, and output summary. |
| OBJ-03 | AgentStep | Shows accountable agent work: role, task, state, evidence produced, cost, duration, handoff, and blockers. |
| OBJ-04 | Recommendation | The central product object. A ranked business/action recommendation with evidence, reasoning, expected value, confidence, risk, action, governance tier, and owner agent. |
| OBJ-05 | Evidence | Structured support for recommendations: source, freshness, extracted facts, assumptions, confidence, and caveats. |
| OBJ-06 | Action | The executable next step produced by a recommendation: content brief, technical fix, internal link plan, outreach draft, or strategy decision. |
| OBJ-07 | ApprovalDecision | Human governance object: approve, edit, reject, defer, return with reason, or change constraints. |
| OBJ-08 | Constraint | Buyer or operator rules that shape analysis and ranking: budget, risk tolerance, brand guardrails, competitors, excluded categories, approval policy. |
| OBJ-09 | OutcomeMetric | Tracked result after action: ranking movement, traffic value, completion state, savings, pipeline estimate, or accepted risk. |
primary unit
Recommendation = evidence + reasoning + expected value + risk + action + governance tier + agent owner
ux implications
- Start with diagnosis and recommended actions, not navigation.
- Expose AI work as agent steps, not a generic loading spinner.
- Make recommendation reasoning inspectable.
- Make governance and human decisions first-class surfaces.
- Let human constraint changes re-rank or reshape recommendations.
architecture implications
- Persist recommendations, evidence, actions, constraints, and approval decisions as structured objects.
- Seeded data must use the same object model as future live provider data.
- Agent activity must be event-shaped so the UI can switch from seeded events to live RedKey task events later.
schema version
1.0
product summary
goal
Deliver a production-ready Monday pilot for Hubbard Supply Co. at /seo where AD SEO Agent turns Hubbard domain and competitor context into ROI, prioritized opportunities, governed agent actions, and a showable agent-backed execution workflow.
problem
Mid-market industrial distributors have SEO tools, agency reports, and content backlogs, but the tools stop at reporting. Humans still translate data into priorities, briefs, tickets, content work, technical fixes, and ROI justification.
must show
- Hubbard Supply Co. domain and industrial/MRO context are visible in the first experience.
- ROI appears before keyword tables: current spend baseline, projected savings, organic traffic value, and pipeline impact.
- Competitor analysis is actionable: vulnerable keywords, why they are winnable, estimated value, and next actions.
- Agent cluster activity is visible and specific: crawler, competitor analyst, content gap analyst, backlink analyst, recommendation planner.
- Every recommendation has reasoning, confidence, governance tier, and an execution path.
- Human approval boundaries are explicit for publishing, outreach, and strategic decisions.
- White-label story is visible without requiring a full white-label admin console.
- agent infrastructure is revealed subtly through observability, audit trail, or agent activity.
- AD SEO Agent appears as a client project, available at
/seowith/products/seoas a short alias if routing supports it.
primary users
| id | name | success | description |
|---|---|---|---|
| USER-1 | Distributor CEO | Sees a clear payback story, traffic/pipeline upside, and a credible path from opportunity to execution. | Executive evaluating whether AD SEO Agent creates measurable business value and replaces current SEO spend. |
| USER-2 | Distributor CIO | Sees every recommendation and agent action as traceable, controlled, and approval-gated where needed. | Technology owner evaluating governance, observability, approval boundaries, and auditability. |
| USER-3 | Head of Digital | Receives prioritized actions and agent-prepared work instead of another passive dashboard. | Operator responsible for SEO, content, technical fixes, reporting, and agency/tool coordination. |
| USER-4 | Affiliate distributor organization | Can see how the same product becomes native to its brand, members, and verticals. | Network-level buyer that can white-label AD SEO Agent as a differentiated member benefit. |
success metrics
| id | metric | target |
|---|---|---|
| METRIC-1 | Time to first meaningful insight | Under 60 seconds from landing/demo start using seeded Hubbard data. |
| METRIC-2 | Recommendation actionability | At least 10 Hubbard-specific opportunities include action, owner agent, governance tier, and evidence. |
| METRIC-3 | Production readiness | Monday pilot can run at /seo without manual code edits, with seeded data, stable Cloudflare route, no console errors, and clear fallback states. |
| METRIC-4 | Buyer coverage | CEO, CIO, and Head of Digital each have at least one explicit value proof in the demo flow. |
global out of scope
- Full production SEO provider integration parity with SEMrush, Ahrefs, or Moz.
- Autonomous publishing or live website mutation by Monday.
- Final commercial pricing, contract terms, or exclusivity agreements.
- Complete multi-tenant white-label administration.
- Supplier-network exclusivity or supplier-focused sales motion.
global open questions
| id | owner | blocks | status | question | answer |
|---|---|---|---|---|---|
| OQ-001 | justin | Final opportunity data quality, but not UX/architecture start if placeholder competitor set is used. | deferred | Which competitors should be included in the Hubbard seeded dataset? | |
| OQ-002 | atlas | No longer blocks release acceptance; deployment implementation must follow Cloudflare/client project conventions. | answered | Which route/domain will host the Monday production pilot? | Host as a client project at /seo; /products/seo may redirect to it. |
cross feature constraints
- Every insight must lead to an action, plan, or agent task.
- Seeded data must be labeled and versioned; do not present seeded estimates as live audited results.
- Human approval is mandatory for publishing, outreach, strategic repositioning, and budget decisions.
- The product must use Hubbard Supply Co. and industrial/MRO context in the first pilot.
- The agent infrastructure reveal must support credibility without stealing the AD SEO Agent headline.
- Secrets and provider credentials must never reach the browser.
- The product route is
/seo;/products/seomay redirect there as a short alias. - Cloudflare is the deployment/runtime/media platform for this product family: Pages, Workers, Images, and Stream as appropriate.
- Supabase Projects/Demo is the product-build data layer for seeded demo records and future project records.