mktg: Agent-Native Marketing Playbook CLI

[!IMPORTANT] For runtime CLI usage (commands, flags, output formats), read CONTEXT.md first. For /cmo runtime indexes, read skills/cmo/rules/cli-runtime-index.md, skills/cmo/rules/publish-index.md, and skills/cmo/rules/studio-api-index.md. For /axi (AXI catalog router), read skills/axi/SKILL.md and skills/axi/rules/. For agent/skill contributor guidance, read AGENTS.md. This file is the project's development contract: architecture, standards, and rules.

What This Is

A TypeScript/Bun agent-native marketing playbook CLI. 76 marketing skills (74 playbook + /cmo + /axi), 7 agents (4 research + 3 review), 24 commands, 2 upstream catalogs (postiz, openseo). The Studio dashboard (Next.js + Bun API) ships inside the same tarball and is launched via mktg studio.

Repo Layout

This is a bun-workspaces monorepo with one publishable package: marketing-cli. The studio/ subfolder is a workspace member; its source ships inside the marketing-cli tarball, so npm i -g marketing-cli installs the CLI and the dashboard together. The workspace exists because Studio is a Next.js app with its own build pipeline.

Architecture

src/
├── cli.ts              # Entry point, command router, global flag parsing
├── types.ts            # All shared TypeScript types
├── commands/           # One file per command (init, doctor, status, setup, list, etc.)
├── core/
│   ├── output.ts       # JSON/TTY formatting, --fields filtering, size warnings
│   ├── args.ts         # Canonical --flag value parsing (flagValue/flagValues)
│   ├── project-assess.ts # Project health/next-step assessment (status/plan)
│   ├── url-validation.ts # SSRF guard: public-URL validation, one-hop redirect, size cap
│   ├── publish/postiz/ # Postiz raw-fetch client, markers, media, adapter, admin (single client; studio imports it)
│   ├── errors.ts       # Structured errors, exit codes 0-6, sandboxPath()
│   ├── brand.ts        # Brand dir management + freshness assessment
│   ├── skills.ts       # Skill registry, install, integrity verification
│   ├── skill-add.ts    # External skill chaining (mktg skill add)
│   ├── agents.ts       # Agent registry, install to ~/.claude/agents/
│   └── transcribe.ts   # whisper.cpp + yt-dlp + ffmpeg pipeline
skills/                  # 76 SKILL.md files installed to ~/.claude/skills/
skills-manifest.json     # Definitive skill list with metadata
agents/                  # 6 agent .md files installed to ~/.claude/agents/
agents-manifest.json     # Definitive agent list with metadata
catalogs-manifest.json   # Upstream catalog registry (postiz v1, openseo; parallel to skills/agents)
studio/                  # Studio dashboard workspace member (ships inside the tarball)
├── app/                 # Next.js dashboard
├── server.ts            # Bun API server
├── server/http.ts       # HTTP helpers for the API
└── server/routes/       # activity, brand, content, publish, signals
├── bin/mktg-studio.ts   # Local launcher (mktg studio resolves this first)
├── components/          # React UI
└── package.json         # Workspace package.json: Next.js deps + build scripts (no separate publish)

Key Principles

[!IMPORTANT] These principles are non-negotiable. Every PR, skill, and command must uphold them.

1. Progressive Enhancement: Every skill works at zero context. Brand memory enhances, never gates.
2. Agent-native: Built for agents to run, not humans. Predictability over discoverability.
3. Self-bootstrapping: mktg init installs everything on any machine.
4. Drop-in skills: Add a skill: drop SKILL.md + update skills-manifest.json. No CLI code changes.
5. Drop-in agents: Add an agent: drop .md in agents/ + update agents-manifest.json. No CLI code changes.
6. Skills never call skills: Skills read/write files. /cmo orchestrates. Agents never call agents.
7. Parallel by default: Foundation building spawns 3 research agents simultaneously.

Security Posture

[!IMPORTANT] The agent is not a trusted operator. All inputs from agent callers are treated as potentially adversarial.

All validators return { ok, message } and never throw. Error messages explain what failed and why.

Agent DX Score: 21/21

[!IMPORTANT] Every code change must maintain this score. Tests enforce it.

CLI Command Standards

Every command handler must:

Skill Standards

Every SKILL.md must:

Upstream-Mirrored Skills

When a skill mirrors content from an upstream OSS source (the firecrawl pattern, now also Remotion), it MUST ship:

• upstream.json provenance manifest (snapshot SHAs, per-file blob SHAs, source list) — the canonical record of which upstream blobs the mirror tracks.
• scripts/check-upstream.sh drift detector (emits {ok, in_sync, sources[].drift} JSON envelope; exit 0 in sync / 1 drift / 2 error).
• Attribution footer in SKILL.md crediting upstream maintainers and linking the source repo.
• Manifest source: "new" plus an upstream object recording the source repos and paths (see remotion-best-practices for the canonical example). The skill content was curated and mirrored — "new" matches the intent (we authored/curated it). The dedicated upstream object carries the upstream-mirror semantics: it tracks the source repos, paths, and provenance.

Mirrored content is verbatim. The skill's mktg-adapted SKILL.md is the only file that wraps upstream content with mktg conventions (drop-in frontmatter, brand-ground On Activation section). Drift checks treat adapted files specially via the note: "adapted-frontmatter" flag in upstream.json.

See marketing-cli/skills/remotion-best-practices/ for the canonical example. Phase 2 of /mktg-steal added mktg skill check-upstream and mktg skill upgrade CLI commands that fan across every skill with an upstream.json.

Brand File Standards

Per brand/SCHEMA.md: 10 memory files (plus the schema file itself), each with defined required sections.

Testing Standards

[!IMPORTANT] NO MOCKS. NO FAKE DATA. Real file I/O in isolated temp dirs. This is non-negotiable.

tests/                    # Unit tests per module
tests/integration/        # Per-command integration tests (all 7 DX axes)
tests/integration/cmo/    # CMO coherence tests (orchestrator visibility)
tests/e2e/                # Full pipeline soup-to-nuts tests

Dev Notes

Upstream Catalogs

mktg treats selected OSS projects as upstream catalogs: we build on top of them via REST API rather than vendoring their code or linking their SDKs. This lets us inherit providers (postiz ships 30+ social channels; future catalogs like cal.com would ship 40+ calendar integrations) without owning the implementation burden or the license inheritance.

The current publish stack also includes mktg-native, a local-first workspace backend for X, TikTok, Instagram, Reddit, and LinkedIn queue/history state. Native provider/account state lives under .mktg/native-publish/ and is documented for /cmo in skills/cmo/rules/publish-index.md.

License firewall. A catalog's own license never touches mktg's code. For AGPL-licensed upstreams (e.g., postiz), we use transport: "http" and raw fetch; the upstream's npm package never gets installed. A package.json test asserts banned packages stay out of all dependency sections. mktg's license posture stays MIT-clean.

Runtime model. Catalogs are BYO: the user runs (or subscribes to) the upstream, mktg detects its env vars via mktg doctor, and mktg catalog info <name> --fields configured,missing_envs reports readiness. Hosted is the default path (less Docker complexity); self-host is documented as advanced.

Adding a catalog: see AGENTS.md §Drop-in Catalog Contract. Catalogs extend mktg's publish adapters (social, email), research_adapters + mcp blocks (openseo: SEO data plane, OPENSEO_MCP_URL override), scheduling (future), and skills catalog without CLI code changes; they drop in via catalogs-manifest.json.

Distinct from Ecosystem. The Ecosystem table below lists local CLIs mktg shells out to (ffmpeg, firecrawl, gh). Catalogs are remote services with REST APIs. Different trust model, different install story, different version pinning.

Ecosystem

mktg orchestrates external tools but does not bundle them. mktg doctor detects missing tools and surfaces install commands.

MCP + Exa skills: Exa MCP for deep web research (wired via .mcp.json) plus first-class skills ported from exa-labs/agent-skills: exa-search, exa-contents, company-research, lead-generation, build-with-exa. Requires EXA_API_KEY (surfaced by mktg doctor).

Adding a new chained tool

1. Add to the tools array in src/commands/doctor.ts
2. Add a row to the Ecosystem table above
3. Optionally ship a best-practices skill under skills/<tool>/ with a rules/ subdirectory
4. Register the skill in skills-manifest.json