Embed realize-toolkit, align with Apr 2026 brand guardrails#2
Open
amitl-levi wants to merge 5 commits into
Open
Embed realize-toolkit, align with Apr 2026 brand guardrails#2amitl-levi wants to merge 5 commits into
amitl-levi wants to merge 5 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>
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).