Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(notfair-cmo): multi-platform onboarding audit, minted for any ads connect

Yuting Zhong1935e555204c
diff --git a/notfair-cmo/src/server/onboarding/accounts.test.ts b/notfair-cmo/src/server/onboarding/accounts.test.ts
index b620556a..f00ffbd8 100644
--- a/notfair-cmo/src/server/onboarding/accounts.test.ts
+++ b/notfair-cmo/src/server/onboarding/accounts.test.ts
@@ -31,6 +31,18 @@ vi.mock("next/cache", () => ({
revalidatePath: vi.fn(),
}));
+// getOnboardingTaskForSkipAction awaits provisioning + reads the token
+// table to decide whether to mint the audit task.
+vi.mock("./provisioning-state", () => ({
+ awaitProvisioning: async () => ({ kind: "done" }),
+}));
+const listTokensMock = vi.fn<(slug: string) => Array<{ server_name: string }>>(
+ () => [],
+);
+vi.mock("@/server/mcp/tokens", () => ({
+ listProjectMcpTokens: (slug: string) => listTokensMock(slug),
+}));
+
// Dynamic imports inside setOnboardingAccountAction need mocks too — it
// auto-creates the CMO's onboarding task as the final step of the action.
const createTaskMock = vi.fn();
@@ -88,6 +100,7 @@ vi.mock("@/server/agent-meta", () => ({
}));
import {
+ getOnboardingTaskForSkipAction,
listGoogleAdsAccounts,
setOnboardingAccountAction,
listMetaAdsAccounts,
@@ -498,3 +511,70 @@ describe("setOnboardingGscPropertyAction", () => {
afterEach(() => {
vi.clearAllMocks();
});
+
+describe("getOnboardingTaskForSkipAction", () => {
+ const ONBOARDING_TASK = {
+ id: "onboarding-uuid",
+ display_id: "acme-0",
+ project_slug: "acme",
+ agent_id: "acme-cmo-greg",
+ title: "Learn the project and write PROJECT.md",
+ status: "done",
+ };
+
+ beforeEach(() => {
+ getProjectMock.mockReturnValue({
+ id: "p1",
+ slug: "acme",
+ display_name: "Acme",
+ archived_at: null,
+ google_ads_account_id: null,
+ website_url: null,
+ codebase_path: null,
+ harness_adapter: "codex-local",
+ });
+ listTasksMock.mockReturnValue([ONBOARDING_TASK]);
+ listTokensMock.mockReturnValue([]);
+ createTaskMock.mockClear();
+ });
+
+ it("mints the audit for an X-Ads-only connect (no account picker on that path)", async () => {
+ listTokensMock.mockReturnValue([{ server_name: "notfair-xads" }]);
+ const r = await getOnboardingTaskForSkipAction("acme");
+ expect(r.ok).toBe(true);
+ expect(createTaskMock).toHaveBeenCalledWith(
+ expect.objectContaining({
+ agent_id: "acme-cmo-greg",
+ title: expect.stringContaining("Audit the connected ad platforms"),
+ }),
+ );
+ // Onboarding task is terminal → the freshly minted audit is surfaced.
+ if (r.ok) expect(r.task_display_id).toBe("acme-1");
+ });
+
+ it("creates no audit on a true skip (nothing connected)", async () => {
+ const r = await getOnboardingTaskForSkipAction("acme");
+ expect(r.ok).toBe(true);
+ expect(createTaskMock).not.toHaveBeenCalled();
+ if (r.ok) expect(r.task_display_id).toBe("acme-0");
+ });
+
+ it("does not double-create when an audit already exists", async () => {
+ listTokensMock.mockReturnValue([{ server_name: "notfair-googleads" }]);
+ listTasksMock.mockReturnValue([
+ ONBOARDING_TASK,
+ {
+ id: "audit-uuid",
+ display_id: "acme-9",
+ project_slug: "acme",
+ agent_id: "acme-cmo-greg",
+ title: "Audit the connected ad platforms and propose a starter playbook",
+ status: "proposed",
+ },
+ ]);
+ const r = await getOnboardingTaskForSkipAction("acme");
+ expect(r.ok).toBe(true);
+ expect(createTaskMock).not.toHaveBeenCalled();
+ if (r.ok) expect(r.task_display_id).toBe("acme-9");
+ });
+});
diff --git a/notfair-cmo/src/server/onboarding/accounts.ts b/notfair-cmo/src/server/onboarding/accounts.ts
index b335d9fd..6252cc14 100644
--- a/notfair-cmo/src/server/onboarding/accounts.ts
+++ b/notfair-cmo/src/server/onboarding/accounts.ts
@@ -188,8 +188,7 @@ export async function setOnboardingAccountAction(
//
// Avoid duplicates if the user navigates back and resubmits — reuse
// the existing one when a CMO audit task is already present.
- const { buildOnboardingBrief } = await import("./cmo-task-brief");
- const { listTasks, createTask } = await import("@/server/db/tasks");
+ const { listTasks } = await import("@/server/db/tasks");
const { listProjectAgents } = await import("@/server/agent-meta");
// Resolve the CMO agent by template_key — agent_ids now encode the
// personal name, so we can't synthesize one from project_slug alone.
@@ -199,40 +198,18 @@ export async function setOnboardingAccountAction(
return { ok: false, error: "CMO agent has not been provisioned yet." };
}
const cmoAgentId = cmo.agent_id;
- const allTasks = listTasks(project_slug);
- const existingAudit = allTasks.find(
- (t) => t.agent_id === cmoAgentId && t.title?.startsWith("Audit the account"),
- );
- // Find the project-onboarding task. Created synchronously by
- // createProjectForOnboardingAction; should always exist by the time
- // the user gets here.
- const onboardingTask = allTasks.find(
+ const audit = await ensureAuditTask({
+ project_slug,
+ project_display_name: updated.display_name,
+ google_ads_account_id: match.id,
+ cmoAgentId,
+ });
+ const onboardingTask = listTasks(project_slug).find(
(t) =>
t.agent_id === cmoAgentId &&
t.title === "Learn the project and write PROJECT.md",
);
- let audit = existingAudit;
- if (!audit) {
- // When the onboarding task is missing or already terminal, createTask
- // drops the blocker automatically — the audit runs immediately.
- const { title, brief, success_criteria } = buildOnboardingBrief({
- project_slug,
- project_display_name: updated.display_name,
- google_ads_account_id: match.id,
- });
- audit = createTask({
- project_slug,
- agent_id: cmoAgentId,
- title,
- brief,
- success_criteria,
- assigner_agent_id: null,
- status: "proposed",
- blocked_by_task_id: onboardingTask?.id ?? null,
- });
- }
-
// Pick the task to surface in the redirect:
// - Prefer the onboarding task while it's still non-terminal — that's
// what's actually executing; the audit sits blocked behind it.
@@ -242,7 +219,10 @@ export async function setOnboardingAccountAction(
const surfaceTask =
onboardingTask && !TERMINAL.has(onboardingTask.status)
? onboardingTask
- : audit;
+ : (audit ?? onboardingTask);
+ if (!surfaceTask) {
+ return { ok: false, error: "Onboarding task not found." };
+ }
revalidatePath("/", "layout");
return {
@@ -253,6 +233,63 @@ export async function setOnboardingAccountAction(
};
}
+/** Ads platforms whose connection makes the CMO audit meaningful. */
+const ADS_PLATFORM_KEYS = [
+ "notfair-googleads",
+ "notfair-metaads",
+ "notfair-xads",
+] as const;
+
+/**
+ * Mint the CMO's multi-platform audit task — shared by the Google Ads
+ * account-pick path and the setup step (which covers X-Ads-only /
+ * Meta-Ads-only connects that never pass through an account picker;
+ * without the setup-step hook those projects got NO audit at all and
+ * their specialists sat idle forever).
+ *
+ * Callers are responsible for only invoking this when at least one ads
+ * platform is connected (the account-pick path just validated Google
+ * Ads; the setup path checks the token table). Dedupes by title prefix
+ * so back-navigation / both paths firing can't create two audits. Gated
+ * on the PROJECT.md onboarding task while that's in flight; createTask
+ * drops the blocker automatically when it's already terminal.
+ */
+async function ensureAuditTask(input: {
+ project_slug: string;
+ project_display_name: string;
+ google_ads_account_id: string | null;
+ cmoAgentId: string;
+}): Promise<import("@/types").Task | null> {
+ const { listTasks, createTask } = await import("@/server/db/tasks");
+ const allTasks = listTasks(input.project_slug);
+ const existing = allTasks.find(
+ (t) => t.agent_id === input.cmoAgentId && t.title?.startsWith("Audit the"),
+ );
+ if (existing) return existing;
+
+ const onboardingTask = allTasks.find(
+ (t) =>
+ t.agent_id === input.cmoAgentId &&
+ t.title === "Learn the project and write PROJECT.md",
+ );
+ const { buildOnboardingBrief } = await import("./cmo-task-brief");
+ const { title, brief, success_criteria } = buildOnboardingBrief({
+ project_slug: input.project_slug,
+ project_display_name: input.project_display_name,
+ google_ads_account_id: input.google_ads_account_id,
+ });
+ return createTask({
+ project_slug: input.project_slug,
+ agent_id: input.cmoAgentId,
+ title,
+ brief,
+ success_criteria,
+ assigner_agent_id: null,
+ status: "proposed",
+ blocked_by_task_id: onboardingTask?.id ?? null,
+ });
+}
+
export type ProvisioningProgressResult =
| { ok: true; steps: { key: string; label: string; status: string; error?: string }[]; overall: "running" | "done" | "failed" }
| { ok: false; error: string };
@@ -344,12 +381,14 @@ export type SkipAccountResult =
| { ok: false; error: string };
/**
- * Skip-Google-Ads variant of the onboarding finish. Resolves the CMO agent
- * and its already-created "Learn the project and write PROJECT.md" task so
- * the client can land the user on the same task workspace the connect path
- * lands on. No account is persisted, no audit task is minted — the audit
- * task is only meaningful once Google Ads is wired up, and the user can
- * always reach the connect screen later from /connections.
+ * Resolve where the setup step lands the user (both the connect and the
+ * skip paths route through here). Resolves the CMO agent + its
+ * "Learn the project and write PROJECT.md" task, and — when at least one
+ * ads platform is connected — ensures the multi-platform audit task
+ * exists. This is what covers X-Ads-only / Meta-Ads-only connects: they
+ * never pass through the Google Ads account picker, which used to be the
+ * only place the audit was minted. With nothing connected (true skip) no
+ * audit is created — the user can connect later from /connections.
*
* Blocks until provisioning has fully resolved — `ensureProjectAgents`
* itself waits for the gateway's runtime config to surface the new agent
@@ -395,12 +434,34 @@ export async function getOnboardingTaskForSkipAction(
t.agent_id === cmo.agent_id &&
t.title === "Learn the project and write PROJECT.md",
);
- if (!onboardingTask) {
+ // Only mint the audit when an ads platform is actually connected — a
+ // true skip (nothing connected) lands on the PROJECT.md task alone.
+ const { listProjectMcpTokens } = await import("@/server/mcp/tokens");
+ const connected = new Set(
+ listProjectMcpTokens(project_slug).map((t) => t.server_name),
+ );
+ const audit = ADS_PLATFORM_KEYS.some((k) => connected.has(k))
+ ? await ensureAuditTask({
+ project_slug,
+ project_display_name: project.display_name,
+ google_ads_account_id: project.google_ads_account_id,
+ cmoAgentId: cmo.agent_id,
+ })
+ : null;
+ // Land on whatever is actually executing: the onboarding task while
+ // it's in flight, else the audit (which auto-kicks off on page open),
+ // else the onboarding task as the terminal-state fallback.
+ const TERMINAL = new Set(["done", "failed", "cancelled"]);
+ const surfaceTask =
+ onboardingTask && !TERMINAL.has(onboardingTask.status)
+ ? onboardingTask
+ : (audit ?? onboardingTask);
+ if (!surfaceTask) {
return { ok: false, error: "Onboarding task not found." };
}
return {
ok: true,
- task_display_id: onboardingTask.display_id,
+ task_display_id: surfaceTask.display_id,
cmo_agent_slug: cmo.slug,
};
}
diff --git a/notfair-cmo/src/server/onboarding/cmo-task-brief.ts b/notfair-cmo/src/server/onboarding/cmo-task-brief.ts
index 6a98558c..42d69859 100644
--- a/notfair-cmo/src/server/onboarding/cmo-task-brief.ts
+++ b/notfair-cmo/src/server/onboarding/cmo-task-brief.ts
@@ -57,6 +57,12 @@ export function buildProjectOnboardingBrief(args: {
"understand it in 90 seconds of reading. Quote specifics from the",
"site/codebase rather than handwaving.",
"",
+ "Do NOT write anything about which ad platforms / accounts are",
+ "connected — this task runs while the user is still connecting them,",
+ "so any claim you make goes stale immediately. The platform injects",
+ "live connection facts into every task assignment; PROJECT.md is for",
+ "the business, not the plumbing.",
+ "",
"## 3. Close the task",
"",
"After `set_project_brief` returns ok, call `submit_task_status` with",
@@ -75,10 +81,12 @@ export function buildProjectOnboardingBrief(args: {
/**
* Build the brief for the CMO's first task — the audit that used to be its
* own special-purpose code path in src/server/onboarding/audit.ts. Now the
- * audit IS a task: the CMO does the GAQL probes itself via the Google Ads
- * MCP, writes findings inline, and delegates ongoing work via the
- * notfair-orchestration MCP tools (the same surface the CMO uses for every
- * other planning turn — see agent-templates.ts for the full teaching).
+ * audit IS a task, and it covers EVERY connected ads platform (Google,
+ * Meta, X) — the kickoff message's platform-connections facts block tells
+ * the CMO which ones are live. The CMO runs the probes itself via each
+ * platform's MCP, writes findings inline, and delegates ongoing work via
+ * the notfair-orchestration MCP tools (the same surface the CMO uses for
+ * every other planning turn — see agent-templates.ts for the full teaching).
*
* Keeping this server-side so the wording stays in lockstep with the CMO
* system prompt; templated rather than free-form so each new project
@@ -91,20 +99,22 @@ export function buildOnboardingBrief(args: {
}): { title: string; brief: string; success_criteria: string } {
const account = args.google_ads_account_id ?? "(none picked — ask the user)";
- const title = "Audit the account and propose a starter playbook";
+ const title = "Audit the connected ad platforms and propose a starter playbook";
const brief = [
`Project: ${args.project_display_name} (${args.project_slug})`,
`Google Ads account: ${account}`,
"",
- "This is your first turn as CMO for this project. Audit the connected",
- "Google Ads account, present findings, then delegate ongoing work to",
- "the google-ads specialist.",
+ "This is your first turn as CMO for this project. Audit EVERY",
+ "connected ads platform — the \"Platform connections\" list in this",
+ "assignment is ground truth: audit each ads platform it shows as",
+ "connected, skip the rest. Present findings per platform, then",
+ "delegate ongoing work to each platform's specialist.",
"",
- "## 1. Probe the account",
+ "## 1. Probe each connected platform",
"",
- "Use the notfair-googleads MCP `runScript` tool to gather (GAQL via",
- "`ads.gaql`, fan out with `ads.gaqlParallel`):",
+ "**Google Ads** — use the notfair-googleads MCP `runScript` tool",
+ "(GAQL via `ads.gaql`, fan out with `ads.gaqlParallel`):",
"- Customer info: status, currency, time zone",
"- Last 30 days per enabled campaign: cost, impressions, clicks,",
" conversions, conversion_value",
@@ -113,40 +123,60 @@ export function buildOnboardingBrief(args: {
"- Keywords with quality_score < 5",
"- Campaigns within $5 of their daily budget cap",
"",
- "## 2. Classify the archetype",
+ "**Meta Ads** — use the notfair-metaads MCP `runScript` tool",
+ "(`ads.graphParallel`): campaign / ad set / ad listings with 30-day",
+ "insights (spend, ROAS, CPM, CTR, frequency); flag learning-limited",
+ "ad sets, creative fatigue (rising frequency + falling CTR), and",
+ "audience overlap.",
+ "",
+ "**X Ads** — use the notfair-xads MCP tools: campaigns + line items",
+ "with 30-day spend / impressions / engagement, promoted posts, and",
+ "funding instruments; flag zero-spend or fully-paused accounts.",
"",
- "One of:",
- "- empty — no enabled campaigns",
- "- no_tracking — campaigns but zero conversion_actions",
- "- low_volume — < 50 clicks / month or < $200 spend",
+ "## 2. Classify each platform's archetype",
+ "",
+ "One per audited platform:",
+ "- empty — no enabled/serving campaigns",
+ "- no_tracking — campaigns but no conversion tracking",
+ "- low_volume — too little traffic/spend to optimize (< ~50 clicks or",
+ " < ~$200 / month)",
"- active — meaningful data to optimize on",
"",
"## 3. Report findings to the user (in this reply)",
"",
- "Markdown, scannable. Sections (skip any with no findings, don't pad):",
- "- **Account snapshot** — 1-2 sentences naming the archetype + spend",
- "- **Wasted spend** — top 3 search-term gaps with $ amounts",
- "- **Low quality scores** — top 3 keywords + their QS",
+ "Markdown, scannable, one section per audited platform (skip findings",
+ "that don't exist, don't pad):",
+ "- **Snapshot** — 1-2 sentences naming the archetype + spend",
+ "- **Wasted spend** — top gaps with $ amounts (search terms on Google;",
+ " fatigued creatives / overlapping audiences on Meta; dead line items on X)",
+ "- **Quality issues** — low QS keywords, learning-limited ad sets, etc.",
"- **Budget pacing** — campaigns hitting cap",
- "- **Next steps** — 3 concrete actions tailored to the archetype",
+ "- **Next steps** — up to 3 concrete actions per platform, tailored to",
+ " its archetype",
"",
"Lead with the dollar figure or the most actionable finding. Don't ask",
'"want me to..." — you\'re an orchestrator; delegate, don\'t advise.',
"",
"## 4. Delegate the ongoing work",
"",
- "For each Next Step that's actionable + repeatable, delegate it to the",
- "google_ads specialist. Include the cadence in the brief itself (\"daily",
- "9am Pacific anomaly check on enabled campaigns\", \"weekly Monday",
- "search-term review\", etc.) — the specialist will schedule its own cron.",
- "",
- "Tight one-line tail after delegating: \"Handed these to your Google Ads",
- 'specialist — open the agent\'s Tasks tab to follow along."',
+ "For each Next Step that's actionable + repeatable, delegate it to",
+ "THAT platform's specialist (google_ads / meta_ads / x_ads — use",
+ "`list_project_agents` to get exact agent ids). Include the cadence in",
+ "the brief itself (\"daily 9am Pacific anomaly check on enabled",
+ "campaigns\", \"weekly Monday search-term review\", etc.) — the",
+ "specialist will schedule its own cron.",
+ "",
+ "ONLY IF you actually delegated tasks, close with a one-line tail",
+ "naming which specialists got work (\"Handed these to your Google Ads",
+ 'and X Ads specialists — open their Tasks tabs to follow along.").',
+ "When you skipped delegation for a platform (e.g. empty account), say",
+ "what would unlock it instead — don't claim a handoff that didn't happen.",
].join("\n");
const success_criteria = [
- "Findings reported as inline markdown; ongoing work delegated to",
- "google_ads (skip delegation when archetype = empty); this audit task",
+ "Findings reported per connected ads platform as inline markdown;",
+ "ongoing work delegated to each platform's specialist (skip a",
+ "platform's delegation when its archetype = empty); this audit task",
"marked done.",
].join(" ");