google-ads

Turn what the Product's Google Ads account shows into the smallest reversible changes. Every change leaves as a spend Proposal in the Approval feed; nothing here reaches Google before the User approves. The decisions belong to ads: read its references/google-search-playbook.md (the weekly search-terms ritual, bidding by conversion volume, ±10–15 % target moves), references/audit-guardrails.md (smallest reversible change, never invent a negative) and references/reading-google-ads-data.md (the traps in the account's numbers) before proposing anything.

Create campaigns

A Chat asked to start, build or add Google Ads campaigns takes this branch in place of Gather, Decide and Output; a Loop Run lays the structure out in its Output and the User starts it from a Chat. It proposes Search campaigns for the Product's Site, one Proposal per campaign, through connector_google_ads_propose_campaign, with the reads in their own step before it. The Contract below binds Proposals on existing campaigns; a new campaign starts with the playbook's starter negatives. Read references/campaign-creation.md before the first Proposal: the reads that find ids, and what Google accepts in each field.

1. Budget — ask the User for their monthly Google Ads budget, in the account currency, before anything else. Done when one monthly figure is agreed.
2. Structure — size the account to that budget with ads → references/google-search-playbook.md: Brand, high-intent non-brand and Competitor campaigns, each with its share of the budget, its bidding strategy by conversion volume, its countries and languages, and themed ad groups of Phrase and Exact keywords seeded from read_context, the Site and, when connected, Search Console queries. Show the whole plan in one message. Done when every campaign names its daily budget, strategy, targeting, ad groups, keywords and landing page.
3. Propose — one connector_google_ads_propose_campaign call per campaign, carrying it whole: budget, bidding, countries, languages, negatives, ad groups, keywords and one responsive search ad per ad group. Its why gives the campaign's share of the monthly budget and its target. On approve, Kwern creates it all in that order, enabled; a write Google refuses fails that Proposal with Google's reason, and Retry resumes from what exists. A change the User asks for on a campaign still pending is one edit_proposal call on its Proposal, carrying the whole new plan in googleAdsCampaign. Done when every campaign of the plan waits as its own Proposal.
4. Report — the campaigns waiting for approval, their daily budgets against the monthly budget, and what is left for the User to decide. The Google Ads Loop tunes the new campaigns once they are live.

Every text this Run files for a person to read passes two of copywriting's rules before it is filed. No AI Tells: read references/ai-tells.md of copywriting with read_reference, and run its Self-Check on each draft. Claims Must Be Supportable: "Write only claims the source material supports." Every claim about what the Product or its maker has done, has or has shipped comes from the Foundation doc or from data this Run read, and a claim neither source supports stays out of the text.

Gather

1. read_context — positioning, ICP, target CPA or LTV, competitors.
2. connector_google_ads_campaigns — every campaign in scope, read live: type, bidding strategy, daily budget, target, primary status, learning state, budget sharing, networks and location setting; plus the 30-day performance of campaigns, ad groups and keywords, with conversion value, impression share and Quality Score.
3. connector_google_ads_search_terms — what people typed over 30 days, with clicks, conversions, conversion value, spend, the match type that triggered each term and whether it is a keyword yet.

Without the Google Ads Connector the run is a structure recommendation from the Foundation doc alone: no audit, no Proposals, and the Output says what the Connector would add.

Decide

Run the three passes of the search-terms ritual per campaign — waste, winners, drift — then check pacing (budget-capped vs bid-limited: primaryStatusReasons, impression share lost to budget vs to rank) and each Smart Bidding campaign's learning state (biddingStrategySystemStatus). Benchmarks and thresholds come from the ads references; a spike on a handful of conversions is a question, not a verdict.

The waste pass reads the search terms as a sample. Per campaign, state the disclosed clicks (the sum over connector_google_ads_search_terms) out of the campaign's total clicks (connector_google_ads_campaigns). A term is waste once its clicks make a readable sample at its break-even CVR, per reading-google-ads-data.md; below that it is unmeasured, and the Output says when it will be readable.

Contract

Kwern refuses two things in code: a campaign outside scope, and an amount at or below zero. Every other call is yours, and the User's approval is the gate. A write Google refuses fails the Proposal with Google's reason, and the User can retry it.

• Scope — only the campaigns connector_google_ads_campaigns lists can change.
• Budget — the briefing carries the Loop's monthly budget, or says none is set, with what the month has spent so far. Pace against it; a Proposal that takes the month past it says so in its Why.
• Step — move a budget, a target or a bid by at most 20 % of its live value per Proposal. A bigger step says why in its Why.

When each change applies

Read each campaign's type and biddingStrategy in connector_google_ads_campaigns before proposing on it:

• Keyword changes (add, negative, bid, pause) apply to campaigns with keywords. An App campaign (MULTI_CHANNEL) has none: tune it with connector_google_ads_set_budget and connector_google_ads_set_target.
• Keyword bids and keyword adds carry a CPC bid, which only manual CPC (MANUAL_CPC) uses. On Smart Bidding, move the target instead.
• Target changes apply where the strategy already carries that target: targetCpa or targetRoas is set on the campaign. A campaign with neither needs a bidding-strategy change first, which is the User's call in Google Ads.
• Negatives come from connector_google_ads_search_terms: a term the waste pass calls waste. Campaign-level, and mind the match type: negative broad needs every word present.

Tools: connector_google_ads_set_budget, connector_google_ads_set_target (tCPA or tROAS), connector_google_ads_set_bid, connector_google_ads_pause (campaign, ad group or keyword), connector_google_ads_add_negative, connector_google_ads_add_keyword. Each takes an expectedEffect sentence the User reads on the card.

Output

Per campaign: 30-day spend, clicks, conversions, CPA against the target; the pass findings; the Proposals made, each current value → proposed value with the expected effect; and the structural recommendations. Done when every campaign with spend in the period is classified, every Proposal carries current, proposed and expected effect, with the reason for any step past 20 %, and every negative proposed names the search term it came from.

Related Skills

• ads — the playbook and the guardrails every decision here defers to.
• apple-search-ads — the same shape on Apple's network.
• analytics — attribution and LTV to set the target CPA.