# Harness Architecture — How the Pieces Fit

This is a high-quality, agent-agnostic marketing operator (Hermes / Claude Code / Codex). It is
built in four layers. Higher layers GOVERN lower layers; lower layers EXECUTE for higher ones.
The whole point is that tactical execution is never generic, because it is always downstream of
deep, business-specific research and a disciplined strategic brain.

```
┌─────────────────────────────────────────────────────────────────────┐
│ LAYER 1 — THE BRAIN (governs everything)                            │
│   knowledge/marketing.md         strategic operating system          │
│   knowledge/viral-growth-engine.md  modern AI-native distribution    │
│   knowledge/unit-economics.md    profit lens (CAC/LTV/payback)       │
│   knowledge/verticals/           model packs (saas/ecom/local/info)  │
│   → operating contract, diagnosis-first, frameworks, anti-generic    │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ governs
┌───────────────────────────────▼─────────────────────────────────────┐
│ LAYER 2 — RECON (feeds everything)                                  │
│   skills/market-research/  deep multi-hop research + subagents        │
│   → outputs the Research Brief AND writes .agents/product-marketing.md│
└───────────────────────────────┬─────────────────────────────────────┘
                                │ feeds context to
┌───────────────────────────────▼─────────────────────────────────────┐
│ LAYER 3 — TACTICAL EXECUTION (40+ skills, adopted from Corey Haines) │
│   skills/copywriting, cro, ads, seo-audit, pricing, referrals,       │
│   launch, marketing-psychology, emails, social, offers, ...          │
│   tools/integrations/  (meta-ads, ga4, stripe, klaviyo, semrush, ...) │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ creative produced via
┌───────────────────────────────▼─────────────────────────────────────┐
│ LAYER 4 — AI CREATIVE (the differentiator)                          │
│   skills/ad-static-nano-banana/  polished statics, text-on-image      │
│   skills/ad-static-gpt-image/    UGC-realism statics (narrative)      │
│   skills/ad-video-seedance/      UGC selfie video ads (master prompt) │
└─────────────────────────────────────────────────────────────────────┘
```

## The bridge that makes tactical skills non-generic

Corey Haines' adopted skills (Layer 3) each look for a foundation file at
`.agents/product-marketing.md` and read it before doing anything. We exploit this:

**The research engine (Layer 2) WRITES `.agents/product-marketing.md` from the Research Brief.**

So instead of those skills asking the user shallow intake questions, they inherit our deep,
triangulated, verbatim-customer-language research automatically. The copywriting skill writes
copy from real customer pains; the CRO skill audits against the real funnel; the ads skill
targets the real underpriced-attention wedge. The tactical layer becomes as good as our research,
which is the whole differentiator.

`.agents/product-marketing.md` must contain (mapped from the Research Brief in
skills/market-research/SKILL.md <synthesis>):
- Product, what it does, price
- ICP (validated) — one sentence, plus the verbatim customer pains/desires/objections
- Positioning + the GAP (the wedge)
- Competitive map summary
- The underpriced-attention wedge channel
- The current offer + value-equation read
- The goal

## Precedence (when layers conflict)

1. marketing.md `<operating_contract>` and `<honest_growth_guardrails>` (viral-growth-engine.md)
   outrank any tactical skill. If an adopted skill would produce generic, unsourced, or dishonest
   output, the brain wins — rewrite to comply.
2. The diagnosis (marketing.md `<diagnosis_first>`) decides WHICH tactical skills run and in what
   order. Don't run the ads skill while the offer (Gate 1) is broken.
3. The Research Brief is the shared source of truth; tactical skills cite it, never contradict it.
4. The user's explicit current instruction wins over defaults (state the tradeoff once, comply).

## Run order for an engagement

1. Intake (Layer 1 brain, intake gate in CLAUDE.md — to be written).
2. Deep research + write `.agents/product-marketing.md` (Layer 2).
3. Diagnose the one constraint (marketing.md `<diagnosis_first>`).
4. Site/brand audit (Corey's `cro` / `seo-audit` skills + marketing.md `<audit_rubric>`).
5. Strategy synthesis + offer (marketing.md `<strategy_synthesis>`, `<offer_and_positioning>`).
6. Distribution plan (viral-growth-engine.md) — pick the primary loop.
7. Gate on user consent + budget, then execute tactical skills (Layer 3) and AI creative (Layer 4).
8. Measure, close the loop (marketing.md `<measurement>`).

## What we added that the adopted repos lacked

- A strategic operator BRAIN with diagnosis-first sequencing and an enforced anti-generic
  contract (Corey's skills are excellent tactical executors but assume a human supplies strategy).
- A deep multi-hop RESEARCH ENGINE with dispatchable subagents and a hardened extract→verify→
  fallback→review loop (patterned after, not copied from, mayooear's company researcher).
- The HIGGSFIELD-GRADE VIRAL/DISTRIBUTION ENGINE with built-in honesty guardrails — no repo has
  this.
- A PROFIT BRAIN (knowledge/unit-economics.md) plus a failure-diagnosis ladder (marketing.md
  <when_results_disappoint>): advice is judged in owner economics — CAC, LTV, payback — and
  misses get diagnosed in order instead of guessed at.
- VERTICAL PACKS (knowledge/verticals/): per-business-model priors and diagnosis overrides —
  SaaS, ecommerce, local services, info products — so benchmarks are never cross-contaminated.
- AN 8-ROLE RESEARCH BENCH with a conflict-resolution protocol: added Buyer-Journey Mapper and
  Proof & Asset Auditor, plus rules for when workers' findings disagree.
- AI ad-CREATIVE generation (nano banana 2 / GPT Image 2 / Seedance 2) — Layer 4, in progress.
- The recursive-demo discipline: every output must be real and specific because the marketing IS
  the product demo.

See `vendor/ATTRIBUTION.md` for licenses.
