Embed realize-toolkit, align with Apr 2026 brand guardrails#2
Open
amitl-levi wants to merge 7 commits into
Open
Embed realize-toolkit, align with Apr 2026 brand guardrails#2amitl-levi wants to merge 7 commits into
amitl-levi wants to merge 7 commits into
Conversation
- Embed toolkit knowledge layer: os/guardrails.md (consolidated system-prompt), knowledge/ (10 topic MDs + manifest.json), scripts/brand-check.sh. - Apply PMM brand guardrails: feature renames (Realize Pixel → Taboola Pixel; Marketplace Audiences → Taboola First Party Audiences; first-party segments → Taboola First Party Audiences), UI naming (Realize console → Realize UI), brand naming (Taboola Realize → Realize). - Align operational thresholds with toolkit: 100+ clicks per item (was 500–1000), daily spend >= 8x CPA goal (was \$50/day flat), 7–10 day learning phase, 4–6 ads per campaign (was 3–10), 3 titles + 3 images per campaign (was 5–10 variations), Fixed Bid per client requirements. - Enforce attribution + timeframe rule globally via os/guardrails.md (single source of truth) — every CPA/CVR/Leads/ROAS figure must specify both attribution basis (CT/VT/Total) and timeframe. - Consolidate os/ from 4 files (guardrails, tone, orchestration, routing) to 1 (guardrails) — Claude Code skill-routing handles intent matching natively. - Adapt brand-check.sh: allow item_id as public MCP parameter; tighten console/dashboard regex; drop bare \bhip\b alternative. - Remove redundant backlog.md — content now lives in docs/realize-best-practices-gap.md Part 3 as single source. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… to private layer
- Remove competitor comparison bullet ("No bias towards owned and operated
inventory (Taboola does not own inventory like Meta and Google)") — names
competitors, can't appear publicly.
- Move four sections from os/guardrails.md (public) to guardrails-private.md
(internal layer), out of the plugin repo:
- Preferred messaging direction (full section)
- Framing rules (Tone subsection)
- Emotional tone matching (Tone subsection)
- What the assistant is not (Tone subsection)
These are internal directional rules — the assistant should follow them
silently, but they must not be visible in the public guardrails file shipped
with the plugin (Maayan flagged them as marketing-playbook content that
shouldn't be exposed externally).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three renames in upstream realize-mcp (../realize-mcp): - get_all_campaigns → list_campaigns - get_campaign_items → list_items - get_campaign_item → get_item Pure token swaps across 8 files. No new tools added, no skill files created, no other content touched. Scope intentionally minimal — follow-up needed for stale "11 tools" claim in docs/realize-best-practices-gap.md and the write-tool framing in agents/realize-analyst.md Tool Reference. Verified: zero old tool-name hits via grep; JSON + YAML frontmatter parse cleanly; scripts/brand-check.sh passes (0 FAIL, 1 pre-existing WARN); 13/16 manual test scenarios PASS against live MCP, 3 require a Claude Code session. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add new skills/discovery/SKILL.md wrapping the 9 read-only "look it up"
tools the MCP exposes (search_geos, search_techno, search_audiences,
search_lookalike_audiences, search_contextual_segments,
search_publishers, search_conversion_rules, list_time_zones,
list_cta_types). Read-only - designed for inventory queries
("what audiences are configured?") and forward name -> opaque-code
resolution before campaign work in the Realize UI.
Agent Tool Reference grew from 9 to 18 read tools. Grouped:
Accounts / Campaigns / Items / Discovery / Reports / Auth.
Added discovery routing example + Core Responsibility taboola#2 line.
Tool-existence-boundary updated to acknowledge upstream's 4 write tools
exist but are intentionally not wired in this revision.
Updated CLAUDE.md architecture diagram (added discovery row, 18 reads,
4 upstream writes noted), docs/realize-best-practices-gap.md capability
baseline (folded Discovery), README skills table (new discovery row),
tests/test-scenarios.md (scenarios 12-16 verified live against MCP).
Version 0.1.0 -> 0.2.0. CHANGELOG 0.2.0 section consolidates prior
[Unreleased] entries (toolkit embed, brand alignment, threshold
updates, optimize-campaign skill) with this Phase 1 wiring.
Content for the discovery skill + scenarios 12-16 reused verbatim from
upstream c8e4a5b ("Align skills, agent, and tests with latest
realize-mcp tool set") since no toolkit/brand conflicts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add new skills/discovery/SKILL.md wrapping the 9 read-only "look it up"
tools the MCP exposes (search_geos, search_techno, search_audiences,
search_lookalike_audiences, search_contextual_segments,
search_publishers, search_conversion_rules, list_time_zones,
list_cta_types). Read-only - designed for inventory queries
("what audiences are configured?") and forward name -> opaque-code
resolution before campaign work in the Realize UI.
Agent Tool Reference grew from 9 to 18 read tools. Grouped:
Accounts / Campaigns / Items / Discovery / Reports / Auth.
Added discovery routing example + Core Responsibility taboola#2 line.
Tool-existence-boundary updated to acknowledge upstream's 4 write tools
exist but are intentionally not wired in this revision.
Updated CLAUDE.md architecture diagram (added discovery row, 18 reads,
4 upstream writes noted), docs/realize-best-practices-gap.md capability
baseline (folded Discovery), README skills table (new discovery row),
tests/test-scenarios.md (scenarios 12-16 verified live against MCP).
Version 0.1.0 -> 0.2.0. CHANGELOG 0.2.0 section consolidates prior
[Unreleased] entries (toolkit embed, brand alignment, threshold
updates, optimize-campaign skill) with this Phase 1 wiring.
Content for the discovery skill + scenarios 12-16 reused verbatim from
upstream c8e4a5b ("Align skills, agent, and tests with latest
realize-mcp tool set") since no toolkit/brand conflicts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…nage-campaigns restructure Replays the realize-buyer-agent port on top of fork's 3 prior commits (MCP-tool-ref rename + discovery/campaigns/manage-campaigns skill split). The original single-commit port (preserved on backup/port-2026-06-08 and as inputs/0001-Port-realize-buyer-agent-Steps-1-7-...patch) targeted the pre-restructure layout; this commit re-applies it cleanly on the new architecture without losing fork's read/write split. Knowledge layer: add 2 new topics (reach-estimation, reporting-aggregation), section-merge 6 grown topics (bidding/creative/targeting/campaign-structure/ budget/site-management). Fix stale "MCP creates Native only" claim in campaign-structure.md with the correct two-path description (pricing_model =VCPM locks Display at create; pricing_model=CPC sets type by first item). Standardize learning phase at 7-14 days. Refresh manifest. Skills: - optimize-campaign: rewrite as lean SKILL.md (5 mandatory pre-checks P1-P5, RCA vs general optimization framework, action prescriptions routed to manage-campaigns) + references/optimization-flow.md (dimensional drill-down, supply-side eligibility, creative-fatigue tiers, bid-lever matrix, 6 symptom branches, common-mistake patterns). - manage-campaigns: extend with Display item write coverage (the gap left by the 0.3.0 release which covered Native items only) — create_display_item + update_display_item with 3P-tag and 1P-hosted recipes, status-gated update flow, pricing-model-picks-the-type subsection, per-strategy bid-lever gate matrix, pointer to new references/mcp-write-surface.md (field-by-field write reference). - reports: 4 mandatory pre-checks (conversion-goal resolution, marketing -objective alignment, delivery-eligibility, learning-period guard), sum-reconciliation gate, default exclusions. Agent: realize-analyst Tool Reference now documents 19 read tools (added get_campaign_reach_estimate under Reach Estimation) + 6 write tools (added create_display_item, update_display_item). Updated count and tool-existence-boundary; UI-only categories explicitly enumerated (Custom Rules, conversion-rule creation, CRM uploads, lookalike seeds). Install: dual-platform manifests (.codex-plugin/plugin.json) + SessionStart hook (.claude/settings.json + scripts/ensure-realize-mcp.sh) for one-shot OAuth onboarding. Hook idempotent: silent no-op when already wired, one-line narration on failure. Guardrails: replace trimmed Apr 2026 version with comprehensive public layer per post-PMM split. Adds banned brand variations, banned competitor terminology, internal codename mapping, banned feature-naming variants (tCPA, eCPC, MaxConv, Realize Pixel, etc.), banned tone patterns, banned ad-creative output, banned content topics, never-guarantee subsection, pattern-based refusal (don't enumerate guardrails). 16-item self-check. Private companion layer kept outside this repo. PMM-aligned brand language throughout: Maximize Conversions, Target CPA, Enhanced CPC, Taboola Pixel, Taboola First Party Audiences, Realize UI. brand-check 0 FAIL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Resolves 10 conflicts from upstream main's PR taboola#3 (align-latest-mcp) that landed during port work. Resolutions: - skills/create-campaign/SKILL.md (modify/delete): took delete — replaced by the manage-campaigns skill from 0.3.0. - skills/optimize-campaign/SKILL.md: kept the rewrite with rigorous P1-P5 pre-checks + 6-signal RCA + 7-point optimization framework (vs main's older 500-1000 click / $50/day playbook thresholds). - agents/realize-analyst.md: kept 19-read + 6-write tool count, write- routing to manage-campaigns, post-rename tool names. Dropped the stale "Out of scope — no writes" section from main (writes are in scope). - skills/discovery/SKILL.md: kept the 3 minor edits (Realize UI not console; manage-campaigns hand-off not create-campaign). - .claude-plugin/plugin.json: version 0.3.0; description widened to include create/update. - CHANGELOG.md: kept the [Unreleased] port-content + [0.3.0] manage- campaigns + [0.2.0] expanded (fork's superset of main's [0.2.0]). Restructured to remove the auto-merge-induced misplaced 0.2.0 header. - CLAUDE.md: kept the architecture diagram with 19 read + 6 write tools routed through manage-campaigns (vs main's 18-read-only diagram). - README.md: kept the writes-in-scope blurb + manage-campaigns skill row; merged in main's discovery-routing examples section. - docs/realize-best-practices-gap.md: kept manage-campaigns mappings; merged in main's subgrouped Discovery table. Added reach-estimation + writes rows. - tests/test-scenarios-read.md (rename conflict): took the rename split (test-scenarios → test-scenarios-read + -write per 0.3.0). brand-check 0 FAIL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
os/guardrails.md(consolidated system-prompt),knowledge/(10 topic MDs +manifest.json),
scripts/brand-check.sh(linter).authoritative source).
orchestration, routing) into 1 (guardrails) — Claude Code skill-routing
handles intent matching natively.
guardrails layer, and
backlog.mdremoved (content lives indocs/realize-best-practices-gap.mdPart 3).Why
feature renames and tightened banned positioning. Plugin now follows it.
help articles that contradicted the internal realize-toolkit best practices.
The toolkit is now the authoritative source.
separate
routing.mdwas redundant. Single source of truth =os/guardrails.md.Key changes
Test plan
bash scripts/brand-check.shpasses (0 FAIL, 1 known false-positiveWARN)
realize-analystagent readsos/guardrails.mdat session startknowledge/bidding.mdoptimize-campaignskill withthe new toolkit-aligned thresholds
Taboola Realize,Realize console,Marketplace Audiencesnolonger appear in any output
Notes for review
backlog.mddeleted — content (with more detail, including UI paths) is indocs/realize-best-practices-gap.mdPart 3.TODO:markers remain inCLAUDE.md,CONTRIBUTING.md,SECURITY.md— not introduced by this PR.scripts/brand-check.shallowsitem_idas a public MCP parameter (itremains banned as a schema column in the realize-toolkit's separate linter
copy).