Open-source SEO, GEO, and marketing skills for AI agents.
feat(notfair-cmo): add X Ads specialist agent with onboarding parity
Yuting Zhong03fc426a059b
diff --git a/notfair-cmo/src/components/agent-avatar.tsx b/notfair-cmo/src/components/agent-avatar.tsxindex beeba212..5e1a9b86 100644--- a/notfair-cmo/src/components/agent-avatar.tsx+++ b/notfair-cmo/src/components/agent-avatar.tsx@@ -7,8 +7,8 @@ import type { AgentTemplateKey } from "@/server/agent-templates";** - a role-tinted soft background circle, matching the colored chip* used elsewhere in the system (CMO blue, Google Ads amber, Meta- * pink, SEO emerald)- * - a per-character palette (hair colour, accent) so the four faces+ * pink, SEO emerald, X Ads sky)+ * - a per-character palette (hair colour, accent) so the five faces* are visually distinct at small sizes* - one signature accessory (glasses, headset, hair clip, magnifying* glass) so the role reads in one glance@@ -182,11 +182,50 @@ const SEO: Avatar = {],};+/**+ * Max — X Ads specialist. Jet-black hair and dark shades over a black+ * tee (the platform's monochrome brand), on a sky wash so the chip+ * still reads friendly next to the others.+ */+const X_ADS: Avatar = {+ bg: "#D6ECF8",+ palette: {+ h: "#3F3F46", // near-black hair+ H: "#18181B",+ s: SKIN,+ S: SKIN_SHADOW,+ m: MOUTH,+ c: CHEEK,+ x: "#0A0A0B", // shades frame+ w: "#52525B", // lens highlight+ t: "#18181B", // black tee+ },+ grid: [+ "................",+ "................",+ ".....HHHHHH.....",+ "....HhhhhhhH....",+ "...HhhhhhhhhH...",+ "...Hhssssshhh...",+ "...hsSssssShh...",+ "...xxxxsxxxx....", // shades band+ "...xwwxsxwwx....", // lenses + highlight+ "....hssssssh....",+ "....cssmsscs....",+ ".....ssssss.....",+ "....tssssst.....",+ "...tttttttt.....", // black tee+ "..tttttttttt....",+ "..tttttttttt....",+ ],+};+const AVATARS: Record<AgentTemplateKey, Avatar> = {cmo: CMO,google_ads: GOOGLE_ADS,meta_ads: META_ADS,seo: SEO,+ x_ads: X_ADS,};/**diff --git a/notfair-cmo/src/components/onboarding-flow.test.tsx b/notfair-cmo/src/components/onboarding-flow.test.tsxindex b44bd09e..0440081e 100644--- a/notfair-cmo/src/components/onboarding-flow.test.tsx+++ b/notfair-cmo/src/components/onboarding-flow.test.tsx@@ -251,8 +251,12 @@ describe("OnboardingFlow — ConnectStep", () => {expect(screen.getByRole("button", { name: /^Google Analytics/i }),).toBeInTheDocument();+ // X Ads provisions a specialist like the trio — its tile must carry+ // the agent badge in the accessible name.expect(- screen.getByRole("button", { name: /^X Ads/i }),+ screen.getByRole("button", {+ name: /^X Ads MCP — required for X Ads agent/i,+ }),).toBeInTheDocument();expect(screen.getByRole("button", { name: /More tools/i }),diff --git a/notfair-cmo/src/components/onboarding-flow.tsx b/notfair-cmo/src/components/onboarding-flow.tsxindex 14a1bda4..e8fe6d51 100644--- a/notfair-cmo/src/components/onboarding-flow.tsx+++ b/notfair-cmo/src/components/onboarding-flow.tsx@@ -388,10 +388,10 @@ function HarnessPicker({ disabled }: { disabled: boolean }) {/*** Spec for one of the recommended-MCP tiles in the connect step. The core- * MCPs (Google Ads, Meta Ads, Google Search Console) each get their own- * first-class tile because connecting them triggers the provisioning of a- * matching specialist agent; Google Analytics and X Ads get tiles too but- * provision no specialist (their data flows to the CMO + existing agents).+ * MCPs (Google Ads, Meta Ads, Google Search Console, X Ads) each get their+ * own first-class tile because connecting them triggers the provisioning of+ * a matching specialist agent; Google Analytics gets a tile too but+ * provisions no specialist (its data flows to the CMO + existing agents).*/type RecommendedTile = {mcp_key: string;@@ -462,6 +462,7 @@ const RECOMMENDED_TILES: RecommendedTile[] = [{mcp_key: "notfair-xads",mcp_display_name: "X Ads MCP",+ agent_badge: "X Ads agent",description:"Audits X (Twitter) campaigns and line items, tracks spend and engagement.",resource_url: "https://notfair.co/api/mcp/x_ads",diff --git a/notfair-cmo/src/lib/agent-colors.test.ts b/notfair-cmo/src/lib/agent-colors.test.tsindex b10a87ff..c40bed11 100644--- a/notfair-cmo/src/lib/agent-colors.test.ts+++ b/notfair-cmo/src/lib/agent-colors.test.ts@@ -29,13 +29,20 @@ describe("colorForAgentSlug", () => {expect(c.label).toContain("text-emerald-700");});+ it("returns the sky palette for x-ads (with or without a name suffix)", () => {+ expect(colorForAgentSlug("x-ads").dot).toBe("bg-sky-500");+ expect(colorForAgentSlug("x-ads-max").dot).toBe("bg-sky-500");+ });+it("returns a non-template color for custom slugs", () => {const c = colorForAgentSlug("growth-engineer");// Custom slugs must never land on a template dot color (they would clash- // with the reserved cmo/google_ads/seo legend swatches).+ // with the reserved cmo/google_ads/meta_ads/seo/x_ads legend swatches).expect(c.dot).not.toBe("bg-blue-500");expect(c.dot).not.toBe("bg-amber-500");+ expect(c.dot).not.toBe("bg-pink-500");expect(c.dot).not.toBe("bg-emerald-500");+ expect(c.dot).not.toBe("bg-sky-500");});it("maps the same custom slug to the same color across calls", () => {diff --git a/notfair-cmo/src/lib/agent-colors.ts b/notfair-cmo/src/lib/agent-colors.tsindex b4207845..021d7219 100644--- a/notfair-cmo/src/lib/agent-colors.ts+++ b/notfair-cmo/src/lib/agent-colors.ts@@ -38,6 +38,13 @@ const PALETTE: Record<AgentTemplateKey, AgentColor> = {dot: "bg-emerald-500",label: "text-emerald-700 dark:text-emerald-300",},+ // Sky, not cyan: cyan-500 lives in EXTRA_PALETTE and a reserved role+ // hue must never collide with a hashed custom-agent swatch.+ x_ads: {+ chip: "bg-[hsl(var(--notfair-surface-2))] text-[hsl(var(--notfair-ink-3))] border-transparent",+ dot: "bg-sky-500",+ label: "text-sky-700 dark:text-sky-300",+ },};/**diff --git a/notfair-cmo/src/server/agent-templates.test.ts b/notfair-cmo/src/server/agent-templates.test.tsindex 5a626953..886d4612 100644--- a/notfair-cmo/src/server/agent-templates.test.ts+++ b/notfair-cmo/src/server/agent-templates.test.ts@@ -10,9 +10,9 @@ import {} from "./agent-templates";describe("AgentTemplate catalog", () => {- it("ships four templates: cmo + google_ads + meta_ads + seo (which owns GSC)", () => {+ it("ships five templates: cmo + google_ads + meta_ads + seo (which owns GSC) + x_ads", () => {const keys = TEMPLATES.map((t) => t.key).sort();- expect(keys).toEqual(["cmo", "google_ads", "meta_ads", "seo"]);+ expect(keys).toEqual(["cmo", "google_ads", "meta_ads", "seo", "x_ads"]);});it("only CMO is included in the default onboarding bundle", () => {@@ -22,7 +22,7 @@ describe("AgentTemplate catalog", () => {);});- it("the three specialists declare their required MCP catalog key — SEO owns GSC", () => {+ it("the four specialists declare their required MCP catalog key — SEO owns GSC", () => {expect(templateForKey("google_ads")?.requires_mcp_key).toBe("notfair-googleads",);@@ -32,6 +32,7 @@ describe("AgentTemplate catalog", () => {expect(templateForKey("seo")?.requires_mcp_key).toBe("notfair-googlesearchconsole",);+ expect(templateForKey("x_ads")?.requires_mcp_key).toBe("notfair-xads");});it("CMO has no requires_mcp_key — it never blocks", () => {@@ -46,6 +47,9 @@ describe("AgentTemplate catalog", () => {expect(SPECIALIST_TEMPLATE_BY_MCP_KEY["notfair-googlesearchconsole"]).toBe("seo",);+ expect(SPECIALIST_TEMPLATE_BY_MCP_KEY["notfair-xads"]).toBe("x_ads");+ // Google Analytics deliberately provisions no specialist.+ expect(SPECIALIST_TEMPLATE_BY_MCP_KEY["notfair-googleanalytics"]).toBeUndefined();expect(SPECIALIST_TEMPLATE_BY_MCP_KEY["stripe"]).toBeUndefined();});@@ -53,10 +57,12 @@ describe("AgentTemplate catalog", () => {expect(templateForUrlSlug("google-ads")?.key).toBe("google_ads");expect(templateForUrlSlug("meta-ads")?.key).toBe("meta_ads");expect(templateForUrlSlug("seo")?.key).toBe("seo");+ expect(templateForUrlSlug("x-ads")?.key).toBe("x_ads");});it("agentUrlSlug produces stable slugs for the new templates", () => {expect(agentUrlSlug("meta_ads", "Mia")).toBe("meta-ads-mia");expect(agentUrlSlug("seo", "Sam")).toBe("seo-sam");+ expect(agentUrlSlug("x_ads", "Max")).toBe("x-ads-max");});});diff --git a/notfair-cmo/src/server/agent-templates.ts b/notfair-cmo/src/server/agent-templates.tsindex d1015e9c..7a0da689 100644--- a/notfair-cmo/src/server/agent-templates.ts+++ b/notfair-cmo/src/server/agent-templates.ts@@ -102,7 +102,7 @@ Style:starting the next.`;export type AgentTemplate = {- key: "cmo" | "google_ads" | "meta_ads" | "seo";+ key: "cmo" | "google_ads" | "meta_ads" | "seo" | "x_ads";/*** Label for the ROLE this template represents (e.g. "CMO", "Google* Ads"). Used in the sidebar role pill + anywhere the UI says@@ -147,9 +147,9 @@ export type AgentTemplateKey = AgentTemplate["key"];* Subset of TEMPLATES included in the default onboarding bundle. Single* source of truth for "which agents does a freshly-created project get?".*- * Only CMO ships by default now. The three specialists (Google Ads,- * Meta Ads, SEO) are gated on the user connecting the matching MCP —- * the connect step in onboarding triggers provisioning via+ * Only CMO ships by default now. The four specialists (Google Ads,+ * Meta Ads, SEO, X Ads) are gated on the user connecting the matching+ * MCP — the connect step in onboarding triggers provisioning via* provisionSpecialistForMcp as each token lands. Google Search Console* isn't its own specialist — connecting GSC provisions the SEO agent,* which uses GSC alongside on-page / technical SEO work.@@ -164,12 +164,15 @@ export const DEFAULT_ONBOARDING_TEMPLATE_KEYS: AgentTemplateKey[] = ["cmo"];** Notice GSC maps to `seo` — there's no dedicated GSC agent. The SEO* specialist owns search-console work as part of its broader remit- * (technical SEO, content, ranking analysis).+ * (technical SEO, content, ranking analysis). Google Analytics is+ * deliberately absent: its data serves the CMO + existing specialists,+ * so connecting it provisions no agent.*/export const SPECIALIST_TEMPLATE_BY_MCP_KEY: Record<string, AgentTemplateKey> = {"notfair-googleads": "google_ads","notfair-metaads": "meta_ads","notfair-googlesearchconsole": "seo",+ "notfair-xads": "x_ads",};export function templateForKey(key: string): AgentTemplate | undefined {@@ -196,7 +199,7 @@ export const TEMPLATES: AgentTemplate[] = [capabilities: ["Talk through marketing strategy and prioritization","Propose experiments + 30-day plans",- "Delegate work to specialist agents (Google Ads, SEO)",+ "Delegate work to specialist agents (Google Ads, Meta Ads, SEO, X Ads)","Schedule recurring jobs via openclaw cron","Coordinate signals across channels",],@@ -332,6 +335,53 @@ for files in your workspace, and the orchestration MCP for coordination.`,default_onboarding: false,requires_mcp_key: "notfair-googlesearchconsole",},+ {+ key: "x_ads",+ display_name: "X Ads Specialist",+ default_name: "Max",+ description:+ "Runs X (Twitter) Ads campaigns, line items, promoted posts, targeting, budgets.",+ capabilities: [+ "Audit campaign + line-item spend, CPM, engagement",+ "Diagnose delivery + targeting issues",+ "Surface creative fatigue + winners on promoted posts",+ "Propose budget shifts + bid changes",+ "Schedule recurring performance + pacing checks",+ "Uses notfair-xads MCP when account connected",+ ],+ model: "openai-codex/gpt-5.5",+ system_prompt: `You are an X Ads (Twitter) specialist agent on the notfair-cmo platform.++${SPECIALIST_ROLE}++## Your domain tools++When the notfair-xads MCP is connected to this project, use its tools+for everything on the ads account — campaigns, line items (X's ad+groups), promoted posts, funding instruments, targeting, and analytics.+Prefer the widest read the surface offers on a first pass (analytics+across all campaigns / line items), then narrow — one broad read beats+many small calls.++Domain conventions you should respect:+- Refer to spend in account currency, not abstract units. Always quote+ numbers (spend, impressions, engagement rate, CPM, CTR) when+ reporting findings.+- Default to the last 30 days for performance reads unless the brief+ asks for a different window.+- X's structure is campaign → line item → promoted post. Bids,+ targeting, and placements live on the LINE ITEM — most "why is this+ campaign behaving oddly" questions resolve at line-item level.+- Creative fatigue shows up fast on X: engagement rate decaying while+ frequency climbs is the first thing to check in a "what's wrong"+ pass; engagement rate + cost-per-engagement by promoted post is the+ "what's working" pass.++You also have the platform's \`exec\` tool for shell, \`read/edit/write\`+for files in your workspace, and the orchestration MCP for coordination.`,+ default_onboarding: false,+ requires_mcp_key: "notfair-xads",+ },];/**