Meta + Google Ads agent, set up yourself

# .env · personal, never shared, never committed. Copy to .env and fill in.
# Brand settings (sources, limits) are in workspace.config.yml.

USER_NAME=Your-Name
USER_ROLE=owner          # owner | marketing | agency
# Connectors in Claude and ChatGPT log in with OAuth, so no ad-account token belongs here.
# If you run the Google Ads MCP server locally, its settings go here, never in a committed file.

# AGENTS.md

You are in the workspace of one ecommerce brand. Hooks may not be running (the Claude or ChatGPT
app has none). **Read `CONTRACT.md` in full before doing anything.** It is the rulebook when hooks are absent.

Before your first answer:

1. State brand, markets, level, from `workspace.config.yml`.
2. State which sources are `live`, `stale`, `absent`, from the same file.
   Absent means: say "no data". Never estimate.
3. Then answer.

Read only: you draft changes, the owner makes them. Output goes to `work/<your-name>/` or `reports/`.

<!-- contract-version: 1.0 · adapted for one ecommerce brand from the open-source Mega-Context workspace skeleton -->
<!-- DO NOT CONDENSE. This file is the rulebook for sessions that cannot run hooks
     (the Claude or ChatGPT app). Every section is there on purpose. -->

# CONTRACT.md · {{BRAND_NAME}}

> For the AI agent. People: start at START-HERE.md.

## Identity

- Brand: **{{BRAND_NAME}}** ({{DOMAIN}})
- Markets: {{MARKETS}} · Currency: {{CURRENCY}} · Language for reports: **{{LANGUAGE}}**
- Level: **{{LEVEL}}** (see `workspace.config.yml`)

## What you have, and what you do NOT have

Read `workspace.config.yml` → `sources`. Each source is `live`, `stale` or `absent`. Treat these as facts:

- **live**: read it through its connector. Do not say "I have no access", you do.
- **stale**: the data is older than its freshness window. Say so. Do not present it as current.
- **absent**: there is no data. Say "no data". **Do not guess, estimate or infer a number.**

Most bad answers do not come from missing data. They come from not saying that data is missing.

## Before your first answer

1. State the brand, markets, currency and level from this file.
2. List the sources and their state from `workspace.config.yml`.
3. List the skills you have.
4. Only then answer.

If you cannot check step 2, say which sources you could not check. Do not carry on as if they were live.

## Changes in the ad accounts

- You connect with read-only logins. You cannot change anything, and you do not try.
- You draft changes (pause, budget, bid, negative keyword, new ad, feed fix). The owner makes them in their own account.
- Never suggest a budget change bigger than the limit in `workspace.config.yml` → `limits`.
- If a tool ever lets you write, do not use it. Tell the owner the login is not read only.

## Numbers

- Every number says where it came from (platform, report, date range).
- Platform conversions are what the platform claims. Say so when you compare channels.
- Meta, Google and the shop will disagree. Show the gap. Do not pick a winner without the shop's orders.

## Where output goes

- Working files → `work/<your-name>/`
- Reports for other people → `reports/`
- Never: the repository root, a personal drive.

## What you must never do

- Write a token, password or `.env` file into any file or message.
- Put customer names, emails, phone numbers or addresses in a report. Counts and totals only.
- Condense or rewrite this file.

#!/usr/bin/env bash
# session-start.sh · SessionStart hook for Claude Code (adapted for one ecommerce brand from the
# open-source Mega-Context workspace skeleton). Put it in .claude/hooks/ and wire it in .claude/settings.json.
# SessionStart hook. Assembles context and hands it to the agent
# before the first prompt. Deliberately minimal: the production version is ~500 lines
# and grows with every incident. The one rule that must survive any rewrite:
#
#   NAME WHAT IS ABSENT. A source that is not connected is listed as not connected.
#   Silence is read as "everything is fine", and that is how invented numbers happen.
#
# Output: JSON on stdout: { hookSpecificOutput: { hookEventName, additionalContext } }
set -uo pipefail
ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
CFG="$ROOT/workspace.config.yml"
PY=$(command -v python3 || echo /usr/bin/python3)

CTX=$("$PY" - "$CFG" "$ROOT" <<'PY'
import sys, os, re, json, datetime
cfg_path, root = sys.argv[1], sys.argv[2]
# Tiny YAML reader for the flat shape we use: avoids a dependency. Swap for PyYAML if you have it.
def read_cfg(p):
    d, cur = {}, None
    if not os.path.isfile(p): return d
    for line in open(p, encoding="utf-8"):
        line = line.split("#", 1)[0].rstrip()
        if not line.strip(): continue
        m = re.match(r"^(\w+):\s*(.*)$", line)
        if m and not line.startswith(" "):
            k, v = m.groups(); d[k] = v.strip() or {}; cur = k if v.strip() == "" else None; continue
        if cur and line.startswith("  "):
            m2 = re.match(r"^\s+(\w+):\s*\{?(.*?)\}?\s*$", line)
            if m2:
                k, body = m2.groups()
                kv = dict(re.findall(r"(\w+):\s*([^,}]+)", body))
                d.setdefault(cur, {})[k] = {a: b.strip() for a, b in kv.items()} if kv else body.strip()
    return d
c = read_cfg(cfg_path)
lines = [f"# {c.get('brand','?')} · {c.get('markets','?')} · Level {c.get('level','?')} · {datetime.date.today()}", ""]
lines += ["**Language for deliverables:** " + str(c.get("language", "?")), ""]
lines += ["## Data sources: what you have and what you do NOT have", ""]
src = c.get("sources", {}) if isinstance(c.get("sources"), dict) else {}
if not src:
    lines.append("⚠ No sources declared. Treat every data question as ABSENT: say 'no data', do not guess.")
for name, meta in src.items():
    st = (meta.get("state") if isinstance(meta, dict) else str(meta)).lower()
    mark = {"live": "✓ live", "stale": "⚠ STALE", "absent": "✗ ABSENT"}.get(st, "? " + st)
    extra = f" (last seen {meta.get('last_seen')})" if isinstance(meta, dict) and meta.get("last_seen") else ""
    lines.append(f"- {name}: {mark}{extra}")
absent = [n for n, m in src.items() if (m.get("state") if isinstance(m, dict) else str(m)).lower() == "absent"]
if absent:
    lines += ["", f"**Absent: {', '.join(absent)}.** If asked about these, answer 'no data'. Do not estimate."]
skills = sorted(d for d in os.listdir(os.path.join(root, ".claude", "skills")) if os.path.isdir(os.path.join(root, ".claude", "skills", d))) if os.path.isdir(os.path.join(root, ".claude", "skills")) else []
lines += ["", "## Skills available", "", ", ".join(skills) if skills else "(none installed)"]
lines += ["", "## Before your first answer", "", "1. Repeat the brand, markets, level. 2. Repeat the source states above. 3. Then respond."]
print("\n".join(lines))
PY
)

"$PY" -c 'import json,sys; print(json.dumps({"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":sys.stdin.read()}}))' <<< "$CTX"

# Start here

This folder is the workspace for **{{BRAND_NAME}}**'s ad agent. What the agent knows about your brand,
your accounts and your rules lives here, so neither you nor the agent starts from zero.

## First time

1. Copy `.env.example` to `.env` and fill in your name. Never share or commit `.env`.
2. Fill in `workspace.config.yml`: brand, markets, which sources are connected, your budget limits.
3. Open the folder in Claude Code (the session-start hook loads context), or upload `CONTRACT.md`
   and `workspace.config.yml` to a Claude Project or a ChatGPT project as instructions.
4. Read `CONTRACT.md` once. It is written for the agent, and it tells you what the agent will and will not do.

## Where things are

- `work/<you>/`: your working files.
- `reports/`: what other people see (your team, your boss, your agency).
- `memory/`: stable facts about your brand: margins, best-sellers, seasons, what was tested.

## What you never do here

Put a token or password in a file. Paste customer lists. Shorten `CONTRACT.md` because it looks long.

# workspace.config.yml · the agent reads this at the start of every session.
# Secrets never go here. Example values, replace them with yours.

brand: Example Outdoor Co
domain: example-outdoor.example
markets: [IE, NL, DE]
currency: EUR
language: en
level: L1              # L0 no sources · L1 read only (this guide) · L3 scheduled briefs

# Be honest here. "absent" is a useful state. "live" that is not live is how invented numbers happen.
sources:
  meta_ads:        { state: live,   freshness_hours: 24 }
  google_ads:      { state: live,   freshness_hours: 24 }
  merchant_center: { state: stale,  freshness_hours: 24, last_seen: 2026-10-20 }
  shop_orders:     { state: absent }
  analytics:       { state: absent }

limits:
  max_budget_change_pct: 20     # never suggest a bigger budget change in one step
  changes: owner_only            # read-only logins; the agent drafts, the owner makes every change

margins:
  gross_margin_pct: 55          # used to turn revenue into profit; replace with your number

---
name: ads-morning-brief
description: Use every morning, or when the owner asks "how are my ads doing", "what needs attention today" or "shall we review Meta / Google / Merchant Center".
---

# The 10-minute morning brief

Needs the Meta Ads, Google Ads and (optional) Merchant Center connectors, read only.

## Steps
1. Read workspace.config.yml. Say which sources are live, stale, absent.
2. Meta Ads: yesterday vs the 7 days before. Spend, results, cost per result, by campaign. Flag campaigns whose cost per result rose over 30%.
3. Google Ads: the same by campaign, plus search terms with spend and no conversions in the last 7 days.
4. Merchant Center: count of disapproved or limited products and the top 3 reasons.
5. Pick at most 3 things that need the owner today.

## Output
Three short blocks (Meta, Google, Merchant Center), then "Today: 1… 2… 3…". End with one question: "Shall we start with 1?"

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.

---
name: meta-bleeding-ads
description: Use when the owner asks which Meta ads waste money, which ads to pause, or why cost per result went up.
---

# Meta ads that spend without results

## Steps
1. Read ad-level results for the last 14 days: spend, impressions, results, cost per result, frequency, CTR.
2. Mark ads with spend above 2× the target cost per result and zero results, or cost per result 50% above the ad set median.
3. For each marked ad: when it started to slip, and whether frequency rose at the same time.
4. Draft a change per ad (pause, lower budget, new creative). Do not apply it.

## Output
A table: ad, spend, results, cost per result vs median, frequency, suggested change. Then: "Which one do you want to do first?"

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.

---
name: meta-creative-fatigue
description: Use when the owner asks which creatives are tired, when to refresh ads, or why CTR is falling.
---

# Creative fatigue on Meta

## Steps
1. For each active ad over the last 28 days, by week: frequency, CTR, cost per result.
2. Flag ads where frequency rose for 2+ weeks while CTR fell.
3. Rank by spend, so the expensive tired ads come first.

## Output
A table by ad with the weekly trend and a one-line reason. Suggest which ad needs a new hook first.

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.

---
name: google-wasted-search-terms
description: Use when the owner asks where Google Ads wastes money, which search terms to exclude, or for negative keyword ideas.
---

# Wasted search terms on Google Ads

## Steps
1. Read the search terms report for the last 30 days: term, campaign, cost, clicks, conversions.
2. List terms with cost above the target cost per conversion and zero conversions.
3. Group them by theme (competitor names, jobs, free, wrong product).
4. Draft negative keywords per theme, with match type. Do not add them.

## Output
Wasted spend total, a table by theme, and the draft negative list. Then: "Which ones will you add?"

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.

---
name: gmc-feed-errors
description: Use when the owner asks about Merchant Center errors, disapproved products, or why products do not show in Shopping.
---

# Merchant Center feed errors

Needs the Merchant API MCP Access Service (alpha). If it is not connected, ask for a CSV export of product issues.

## Steps
1. Count products by status: approved, limited, disapproved.
2. Group issues by reason and count products per reason.
3. Put best-sellers first if the shop orders are connected, otherwise by issue count.
4. For the top 3 reasons, say what fixes it and where (feed, product page, settings).

## Output
Status counts, a table by reason, and the fix per reason. Do not change the feed or settings.

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.

---
name: cross-channel-check
description: Use when the owner asks why Meta, Google and the shop show different sales, or what really came from ads.
---

# Meta vs Google vs the shop

## Steps
1. Last 7 and 28 days: purchases and revenue as Meta reports them, as Google Ads reports them, and orders and revenue in the shop.
2. Add the platform numbers together and compare with the shop.
3. Show the gap in orders and in percent.

## Output
One table and one sentence: "Platforms claim X orders, the shop has Y." Platforms count the same order more than once. Which ads created extra sales needs a test, not this table.

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.

---
name: next-budget-step
description: Use when the owner asks where to put the next euro, whether to raise a budget, or how to split budget between Meta and Google.
---

# Where the next euro could go

## Steps
1. For each campaign: spend, cost per result and how it changed in the last 4 weeks as spend changed.
2. Mark campaigns where cost per result stayed flat while spend rose (room to grow) and where it rose fast (saturating).
3. Draft one budget move within max_budget_change_pct from workspace.config.yml.

## Output
A table and one suggested move with its reason. Say plainly: this is a suggestion from platform data, only a test proves extra sales.

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.

---
name: ad-copy-from-winners
description: Use when the owner asks for new hooks, scripts, headlines or primary text, or "help me create new ads".
---

# New ads from what already works

## Steps
1. Find the 5 ads with the lowest cost per result and enough spend in the last 60 days.
2. Write down what they share: first line, offer, proof, format, length.
3. Draft 5 hooks, 3 short scripts (15–25 s) and 5 headlines in the same pattern, in the brand language.
4. Check each draft against the brand facts in memory/: no claim the brand cannot prove.

## Output
The pattern in 3 lines, then the drafts. Nothing is uploaded or published. The owner picks, edits and publishes.

## Rules
- Read only: you cannot change anything. Draft a change, and the owner makes it in their own ad account.
- Every number says its source, report and date range.
- If a source is absent or stale in workspace.config.yml, say so instead of guessing.
- Platform conversions are what the platform claims, not proven extra sales.
- No customer names, emails or addresses. Counts and totals only.