Skip to content

v2.4.0 — Guided onboarding (/ads start) + continuous coach (/ads next)

Latest
Latest

Choose a tag to compare

View all tags
@Hainrixz Hainrixz released this 13 May 00:50
v2.4.0
11c2e98

v2.4.0 — Guided onboarding (/ads start) + continuous coach (/ads next)

The first-run UX gap is closed. New users now have a clear entry point that walks them from cold install to a working audit pipeline, and a recurring loop (/ads audit → /ads next → fix → re-audit) that always knows exactly what to do next. v2.4.0 is purely additive on top of v2.3.x — no breaking changes to the audit pipeline, agents, or JSON contract.

Quick start

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Hainrixz/claude-ads/main/install.sh | bash
# Windows
irm https://raw.githubusercontent.com/Hainrixz/claude-ads/main/install.ps1 | iex

Then in Claude Code:

/ads start

The wizard captures your context (industry, monthly spend, primary goal, active platforms), walks you through OAuth setup one platform at a time with live verification calls between steps, and persists everything to ~/.claude-ads/profile.json. No future /ads command ever re-asks. When you're done it suggests /ads audit.

After your audit, type /ads next for the ranked top 3 fixes plus a step-by-step walk-through of #1.

What's new

Added

  • /ads start — guided 5-phase wizard (skills/ads-start/SKILL.md):
    • Phase A: detect first-run vs re-entry; subcommands edit, status, reset.
    • Phase B: 4-question context intake (industry, spend bracket, primary goal, active platforms) saved one-at-a-time.
    • Phase C: per-platform connection wizard — MCP / Direct API / Manual / Skip → step-by-step verified walkthrough (1 step → wait for "done" → live test call → diagnose error → cap retries at 3).
    • Phase D: optional Zernio signup + Meta for Developers account walkthrough.
    • Phase E: prints the exact next command to type (never auto-invokes).
  • /ads next — continuous coach (skills/ads-next/SKILL.md):
    • Auto-persists new cwd audits to ~/.claude-ads/history/.
    • Ranks every Quick Win / Critical / FAIL / WARNING by severity × effort_inverse × platform_budget_share using your profile's spend mix.
    • Regression detection — if Meta drops 78 → 71 since your last audit, that's flagged as Priority 0 above the Top 3.
    • Optional step-by-step walk-through of fixing #1 — same verified loop as /ads start.
    • Subcommands: show (top 10, no prompt), compare (full diff between two most-recent audits per platform), walk (skip prompt, fix #1 immediately).
  • Persistence at ~/.claude-ads/ — profile.json + history/index.json + per-audit snapshots. Validates against new schemas ads/references/profile-schema.json and ads/references/audit-history-schema.json. Secrets are never stored — tokens / API keys live in env vars; the profile records api_key_present: true/false.
  • scripts/profile.py — pure-stdlib CLI: init / get / set / save-audit / compare / reset. Exit code 2 on missing profile signals first-run to the orchestrator.
  • 5 step-by-step setup references (each ≤200 lines, identical Goal / Do this / Expect to see / On error structure):
    • setup-meta.md — claude.ai Facebook MCP / Direct API / Manual exports.
    • setup-google.md — cohnen MCP / Direct API (dev-token + OAuth refresh-token flow) / Manual exports.
    • setup-tiktok.md — AdsMCP / Direct API (auth-code exchange) / Manual exports.
    • setup-zernio.md — signup, free tier highlight, API key creation, dry-run verification.
    • setup-meta-developers.md — Meta for Developers account creation (phone verification, Business app type, Marketing API product).

Changed

  • ads/SKILL.md orchestrator is now profile-aware. Every command runs python3 scripts/profile.py get first; on exit 2 it surfaces a one-line tip to run /ads start but allows the user to proceed inline. Context Intake demoted to a fallback. Sub-Skills 17 → 19.
  • CLAUDE.md adds a new dev rule: "Any new user-facing command must check ~/.claude-ads/profile.json for context before asking inline."
  • README EN + ES — Quick Start leads with /ads start. New "Continuous coaching: /ads next" section. FAQ adds Q&A about profile location, reset, multi-machine sync.
  • install.sh / install.ps1 — post-install message rewritten to lead with /ads start. Agent count corrected (3 audit + 4 creative, not 6).
  • uninstall.sh / uninstall.ps1 — also clean ads-start and ads-next from ~/.claude/skills/. Profile + history at ~/.claude-ads/ is intentionally not touched by uninstall; the script prints a note explaining how to wipe it manually.

What stays unchanged

  • The JSON output contract (audit-output-schema.json) — /ads next consumes exactly the v2.3.x shape.
  • The 7 agents — audit-google, audit-meta, audit-tiktok + 4 creative pipeline. Untouched.
  • The 3 base platforms — no scope changes. v2.4.0 is purely UX.
  • All existing /ads commands work without a profile. The wizard is recommended-but-optional.
  • No external dependencies added. scripts/profile.py is stdlib-only.

Tests

  • 166 passed, 5 skipped on Python 3.9 local. CI matrix runs the same on 3.10–3.12.
  • tests/test_profile_schema.py new — validates both new JSON schemas + round-trips profile.py through init/set/get/save-audit/compare/reset against an isolated HOME=tmp_path.

Migration from v2.3.x

Plug-and-play. Just run the new installer:

curl -fsSL https://raw.githubusercontent.com/Hainrixz/claude-ads/main/install.sh | bash

Or, on existing installs, the next /ads <anything> you run will surface a one-line tip about /ads start. Old commands work as before either way.

Full diff: v2.3.1...v2.4.0

🤖 Generated with Claude Code

Assets 2
Loading