PrimeDocs Agent System Architecture

Version 1.0 | Pre-launch

1. Design Principles

Five rules that determine every decision below.

1. State lives in Postgres, not in context. Agents are stateless functions. Everything durable (opportunities, experiments, learnings, policies, run logs) lives in Supabase. An agent that dies mid-run loses nothing but its turn.

2. No agent reviews its own work. The agent that creates a product never approves it. The agent that writes copy never publishes it. Separation of creation and judgment is the only thing standing between you and a 4.9-star catalog full of broken spreadsheets.

3. Policies are data, not prompts. Brand voice, quality standards, refund rules, pricing rules, and license terms live in a policies table. Every agent reads them at runtime. You change policy in one place and 11 agents update.

4. Write access is scarce. Exactly one agent writes to Stripe. Exactly one publishes products. Everyone else proposes. This turns "an agent went rogue" from a catastrophe into a rejected proposal.

5. Autonomy is earned per action type, not per agent. Every action carries a tier. Tiers loosen with measured performance, not with your optimism.

2. System Topology

Two dispatch modes run simultaneously:

• Scheduled: Operator runs a planning cycle Monday 6am. Analyst rolls up metrics daily at 5am. Publisher batches content weekly.
• Event-driven: a sale fires Lifecycle. A support email fires Concierge. A dispute webhook fires Guardian. A failed download fires Concierge and Guardian.

Operator does not sit in the path of event-driven work. If Operator is down, support still answers and chargebacks still get defended.

3. The Eleven Agents

3.1 OPERATOR (orchestrator)

Weekly cycle: read last week's metrics and experiment results → read open learnings → rank the opportunity backlog → dispatch 8 to 15 tasks with explicit success criteria → generate a one-page brief for you with the 3 decisions it needs from you.

The brief is the interface. If you read one thing per week, it is this.

3.2 SCOUT (research and competitive intelligence)

Opportunity scoring rubric (Scout writes a score, Operator ranks by it):

• demand: search volume, marketplace sales proxies, Pinterest saves
• intent: commercial intent of the query, willingness to pay
• gap: quality and price of what already ranks
• fit: can you make it excellent in your existing formats
• durability: evergreen vs. one-season spike

Every opportunity row carries: the 3 sources that justified it, target price, target format, seasonality window, and the competitor products it would beat.

Seasonality calendar is a first-class output. Wedding planning peaks January to March. Budget and planner products peak late December. Resume products peak January and September. Tax products peak February. Scout maintains this and Operator schedules production 8 to 10 weeks ahead of each peak.

3.3 MAKER (product creation)

Every product ships with three artifacts, not one: the deliverable files, a plain-language "how to use this" page inside the file itself, and the source/editable version. Digital product refunds cluster around "I could not figure out how to use it," not "the file was bad."

3.4 AUDITOR (quality gate)

Product QA checklist, executed as code where possible:

1. Every file opens in its target application without warnings
2. Every formula computes and no cell shows #REF!, #DIV/0!, or #VALUE!
3. Zero placeholder text (Lorem, TODO, [insert], Example Co)
4. Every internal and external link resolves with a 200
5. Print layout holds on US Letter and A4
6. Fonts embed or degrade to a safe fallback
7. Preview images match actual file contents
8. License text present and matches the product's declared license tier
9. Accessibility: PDFs tagged, sufficient contrast, no color-only encoding
10. Filename and folder structure match the naming convention

Monthly regression matters more than it sounds. Google Sheets and Excel change behavior. A product that worked in March breaks in September and you find out through a 1-star review. Auditor re-runs the checklist against the full catalog monthly.

3.5 CURATOR (catalog, merchandising, pricing)

Why one agent owns both merchandising and Stripe: price lives in three places (Supabase, Stripe, the rendered page). Split ownership guarantees drift. Curator writes all three or none, and reconciles nightly.

Merchandising responsibilities nobody was assigned in your list:

• Bundle composition. Your bundles run 20% to 36% off. Someone has to decide what goes in and what the discount is. Curator tests bundle configurations as formal experiments.
• Free-product funnel mapping. Each free product should have a designated paid successor and a measured conversion path. Right now you have 4 free products and no declared funnel for any of them.
• Homepage and collection rotation. Seasonal, driven by Scout's calendar.
• Price laddering. Your catalog runs $10 to$34. That is a narrow band. Curator's first experiment should be testing a $49 to$79 tier on your strongest business and career products.

3.6 PUBLISHER (organic surface: SEO, GEO, agent-readability)

Three surfaces, not one. This is the biggest structural difference between a 2026 agent system and a 2023 one.

Surface A: classic SEO. Guides that rank, product pages that rank, internal links that pass authority to money pages. Your guides section is already the right shape. Each guide must have a declared target product.

Surface B: GEO. Roughly 69% of Google searches now end without a click, so ranking is no longer the same as traffic. Publisher optimizes for being the cited source when someone asks Claude or ChatGPT "what should I use to build a monthly budget." That means: original data (publish aggregate anonymized stats from your own catalog), specific claims with numbers, clean extractable structure, and named entity consistency. Apply your CITED framework here directly.

Surface C: agent-readability. Shopping agents parse structured attributes, not prose. Every product needs complete Product schema with offers, price, availability, aggregateRating, license, fileFormat, and isAccessibleForFree. Ship a machine-readable product feed at a stable URL. This is cheap now and expensive to retrofit later.

3.7 BROADCASTER (social distribution)

Weight Pinterest at 70% of this agent's effort. Planners, wedding binders, budget spreadsheets, and resume templates are Pinterest-native categories with multi-year pin half-lives. Pinterest is a search engine that happens to look like a social network, which means Broadcaster's Pinterest work is really Publisher's work in visual form. Instagram and TikTok are brand surface, not acquisition, for this catalog. LinkedIn matters only for the Business and Career categories.

3.8 LIFECYCLE (email, reviews, retention)

This was the largest gap in your original list. For a digital product catalog with a free tier and an email capture on the homepage, email is typically the number two revenue channel behind organic search, and it is the only channel you own outright.

The seven sequences, in build order:

1. Free product delivery + welcome (fires on email capture, 4 emails over 10 days, ends with a paid recommendation)
2. Post-purchase onboarding (delivery confirmation, how to use it, what to do if stuck, day 3)
3. Review request (day 7 post-purchase, one follow-up at day 14, then never again)
4. Cross-sell (day 21, driven by Curator's cross-sell map)
5. Abandoned cart (1 hour, 24 hours, 72 hours with a soft offer)
6. Product update notification (fires when Maker ships a v2 of something they own; this is your highest-goodwill email and your best review-generation lever)
7. Win-back (90 days inactive, new-arrivals angle)

3.9 CONCIERGE (support, refunds, fulfillment health)

Fulfillment health monitoring is the part people skip. Digital stores die silently: signed URLs expire, a storage bucket permission changes, a file gets replaced with a corrupt version. Concierge runs an hourly synthetic check that purchases nothing but exercises the delivery path on 5 rotating products and verifies file integrity by checksum. A failure pages you directly.

Refund data is a quality signal, not just a cost. Concierge tags every refund with a reason code and writes it to learnings. Any product exceeding a 5% refund rate gets auto-flagged to Auditor for regression review and to Curator for potential delisting.

3.10 GUARDIAN (risk, fraud, legal, site health)

Digital goods have brutal chargeback economics because there is no shipping proof and no physical return. Your defense is evidence discipline, assembled automatically at the moment of sale rather than reconstructed weeks later.

The evidence packet, captured at purchase and stored immutably:

• IP address, user agent, and timestamp of purchase
• Email delivery receipt with timestamp
• Download log: which files, when, from what IP, how many times
• Checkout page screenshot showing the digital-goods and refund policy at time of purchase
• Terms acceptance record with the exact policy version hash
• Any support correspondence

Reaching 0.75% disputes gets you into Stripe's early fraud programs, and 1% risks your processing account. For a business that is 100% digital and 100% instant delivery, this is an existential metric, not a nuisance metric.

Piracy sweep: weekly search for your product names and distinctive phrases on Etsy, Gumroad, Telegram, and file-sharing sites. Draft takedowns, you send them.

3.11 ANALYST (measurement, funnels, finance)

Analyst must refuse to call experiments that lack power. At launch volumes you will not have significance on most conversion tests for weeks. An analyst agent that produces confident readouts from n=40 is worse than no analyst, because it manufactures false learnings that pollute learnings and get repeated forever. Build the minimum-sample check into its charter as a hard rule: no directional claim below 100 conversions per arm, and it says so explicitly.

The metrics that matter, in tiers:

• North star: revenue per 1,000 sessions
• Supply: products live, products shipped per month, first-pass QA rate
• Demand: non-brand organic sessions, Pinterest sessions, email list growth, AI citation share
• Conversion: session-to-cart, cart-to-purchase, free-to-paid conversion, AOV, bundle attach rate
• Retention: repeat purchase rate, email revenue share, review rate
• Risk: refund rate, dispute rate, delivery failure rate

4. Shared Memory Schema

The 14 tables that make this a system rather than 11 disconnected scripts.

Product status lifecycle (enforced by database constraints, not by prompt instructions):

A row cannot reach live without a passing qa_reports entry. Put this in a check constraint. Prompts are suggestions, constraints are guarantees.

The learnings table is what makes the system compound. Format every row as: claim, evidence, confidence (0 to 1), source run id, domain tag, expiry date. Agents query it filtered by domain and confidence above 0.6. Learnings expire by default at 180 days, because a truth about 2026 Pinterest behavior is not a truth about 2027 Pinterest behavior.

5. Autonomy Tiers

Tier promotion rule: an action type moves from Tier 2 to Tier 1 after 30 consecutive approvals with zero reversals. Track this in agent_runs and let Operator propose promotions in the weekly brief. This gives you a principled path from "approve everything" at launch to a genuinely autonomous system by month 6, rather than a vibes-based loosening that ends in a $9 price on a$29 product.

Approval interface: a single queue view showing item, proposing agent, diff or preview, rationale, and expected impact. Batch it into your morning. Anything sitting more than 72 hours auto-expires and returns to the agent as rejected, which prevents a silent backlog from becoming the real bottleneck.

6. Runtime Stack

Decisive recommendation, one option each:

Model routing (this is the difference between a $300/month and a$3,000/month agent system):

• Opus: Operator, Scout, Analyst, Auditor, Publisher strategy, dispute evidence assembly
• Sonnet: Maker, Curator, Concierge, Lifecycle, page copy
• Haiku: classification, routing, monitoring checks, social scheduling

Non-negotiable engineering guardrails:

1. Every Stripe write carries an idempotency key derived from the task id
2. Every agent run has a hard token budget and a wall-clock timeout
3. Destructive operations run against a Supabase branch first, diff reviewed, then merged
4. A global kill switch in policies that all agents check at start of run
5. Monthly spend cap per agent, enforced at the runtime layer, not in the prompt
6. Every agent run logged to agent_runs before it acts, not after

7. Build Sequence

Phase 0: Foundations (weeks 1 to 2)

Nothing agentic ships until this exists.

• The 14 tables with constraints and RLS
• policies populated: brand voice, quality standards, refund rules, pricing bounds, license tiers
• Inngest wired, agent_runs logging, kill switch, spend caps
• Approval queue UI (a plain table view is fine)

Phase 1: Supply chain (weeks 3 to 6, pre-launch)

Scout → Maker → Auditor → Curator. These four are the business. Everything else is amplification of what these produce.

Run them at Tier 2 on everything. Target: 25 QA-passed products live before launch, with at least 4 free and 3 bundles.

Phase 2: Launch-critical operations (weeks 5 to 8, overlapping)

Concierge and Guardian. These must be live on day one of taking money. A support inbox with no agent is a 48-hour response time, and an undefended dispute is a lost dispute.

Publisher starts here too, because SEO has a 90-day lag. Every week you delay Publisher is a week of delayed compounding.

Phase 3: Demand engine (weeks 8 to 14, post-launch)

Lifecycle, then Broadcaster. Lifecycle first: your email list has more revenue per hour of build than Pinterest does, and it depends on Phase 1 and 2 data existing.

Phase 4: Intelligence (week 12 onward)

Analyst, then Operator. Deliberately last. Analyst needs 30 days of data to be anything but noise, and Operator needs Analyst to make decisions worth making. Before Operator exists, you are the orchestrator, which is correct for the first 90 days because that is when you learn what the orchestrator should actually optimize for.

8. Three Things to Fix Before Any of This

1. The review counts. The live site shows products with 214, 261, and 302 reviews. If those are seeded placeholder data, they must go to zero before you take a dollar. Fabricated review counts are an FTC Section 5 problem with a rule specifically covering fake reviews since 2024, and they make Lifecycle's review engine unmeasurable because you cannot tell real signal from the seed. Zero them, and let the review agent earn them.

2. Declare the funnel for every free product. You have 4 free products and no stated paid successor for any of them. Curator cannot optimize a funnel that has not been declared, and Analyst cannot measure free-to-paid without a mapping table.

3. Decide your defensibility now, because it determines Scout's charter. A catalog of AI-generated templates has close to zero moat, and every competitor has the same tools you do. The three viable moats: brand and trust (your Editorial Standards and Quality Standards pages are the beginning of this, lean in hard), distribution (own the organic and Pinterest surface before the category floods), or depth per product (a $29 wedding binder that is genuinely better than a$9 one because a system maintains and improves it over years). Pick one and point Scout at it. If you do not pick, Scout will optimize for volume and you will end up with 400 mediocre products and no reason for anyone to choose you.

9. Summary Table