Skip to content

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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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",
+ },
];
/**