Content Os Builder

Content OS Builder

You are an AI coding agent (Claude Code, Codex, Kimi, Cursor, or similar) with file-write and shell access. Your job: build the user a personalized content operating system — a local web dashboard that turns idea → plan → produce → publish → learn into one machine, styled and scoped entirely to their brand.

This skill is a playbook, not a fixed template. You will INTERVIEW the user, then GENERATE their OS from the answers. Never hardcode another brand's identity, colors, voice, or topics — everything comes from the interview.

The reference implementation this is distilled from is "jamal-os" (an Arabic applied-AI creator's OS). You are recreating that architecture, reskinned for the current user. If this skill lives inside a repo that already has an engine/ app, you may clone + reskin it instead of building from scratch (see Stage 4).

The golden rule: INTERVIEW FIRST, BUILD SECOND

Do NOT write a single file until the intake interview is complete and the user has confirmed the summary. The whole value is personalization. Skipping the interview produces a generic clone, which is a failure.

Run the interview conversationally (ask in the user's language), accept short answers, offer sensible defaults, and let them say "use defaults for the rest." Then echo a compact summary and get a "yes" before building.

The full question set + the brand-kit.json schema is in references/1-interview.md. The condensed intake (ask all of these) is:

1. Identity — brand/creator name, @handle(s), one line on what you do, niche, primary language (+ any secondary), is the primary language RTL (Arabic/Hebrew/Farsi)?
2. Audience — who you serve, their level (beginner→pro), the topics/interests you cover.
3. Voice — tone/register (formal? casual? a specific dialect?), 2–3 do's, 2–3 don'ts, emoji policy, one or two sample lines that "sound like you."
4. Visual identity — primary color, accent color, light or dark default (or both), background feel (flat / gradient / editorial), display font, mono/code font, path to a logo or profile image if any. (Optional: a second palette for print/booklets.)
5. Platforms — which platforms, in priority order; which formats you post (Reel, Carousel, Story, YouTube long, Short, Presentation, Post, TikTok…); any custom canvas sizes.
6. Strategy — your content pillars and their ratio (e.g. 70% teaching / 20% journey / 10% offer), the 2–4 things you want to be known for (each with a one-line test — this becomes a hard gate on every idea), your funnel stages, your offers, your default CTA, whether it's "one CTA per piece", whether a no-CTA piece is acceptable, and the destination you funnel to (community / product / newsletter).
7. Radar — the topics/keywords the trend-radar should scout, the sources/competitors/handles to watch, the daily scan time, and hard filters/no-gos (topics to NEVER touch).
8. Grounding & goals — real projects/ventures to ground content in, the proof points you can actually stand behind (the only things the AI may cite), anything you've retired and never want repeated, and the goal metric (followers, subs, revenue).
9. Analytics & competitors (the "never open the app again" layer — optional but high value) — do you want your own posts + insights + comments pulled in? Which accounts (Instagram Business/Creator? YouTube channel?). Do you have (or can you create) a Meta app + IG Business account, a YouTube API key, an OpenAI key for transcription? Which competitors/creators do you want to study? Should transcription use free YouTube captions where available (cheaper) or always OpenAI?
10. Ops — package manager (pnpm/npm), does your agent have shell access + can run a local dev server, can your agent invoke itself headlessly (a claude --print-style CLI a Node process can spawn — this decides whether generation runs automatically or falls back to prompt-handoff), is there a scheduler available (cron/launchd/Task Scheduler), any connectors to wire (Notion, Buffer — optional), and do you want the OS to draft/schedule posts or just hand you the assets (default)? Either way state the rule back: nothing is ever posted to a live account without an explicit go-ahead at that moment.

Store every answer in content-os/brand-kit.json (schema in reference 1). This file is the single source of truth the whole build reads from.

Build stages (after the interview is confirmed)

Work top-to-bottom. Read the matching reference file before starting a stage, and run that stage's checkpoint before moving on — each reference ends with one. A stage that "looks done" but fails its checkpoint fails everything built on top of it, three stages later, somewhere unrelated. After each stage tell the user what you did in one line.

Stage numbers and reference-file numbers are not the same sequence — references 7 and 8 were added later and slot into the middle. Follow this table, not the filenames.

Stage 0 — Prerequisites (probe three INDEPENDENT capabilities, don't assume). These are separate axes — test each and pick the matching mode:

1. Node ≥ 18 + package manager? No → Lite Mode (files + scripts, no web app).
2. Playwright/Chromium installs? Try pnpm dlx playwright install chromium. Fails → keep the app but export HTML only (no PNG rendering).
3. Can your agent invoke itself headlessly? (a claude --print-style non-interactive CLI that Node can spawn.) Many can't — Cursor's composer, Kimi/IDE-plugin chats, sandboxes that forbid child processes. Get this from the Ops interview answer. No → keep the app but degrade generation/radar to prompt-handoff (reference 3). This is orthogonal to Next.js/Playwright — an agent with both can still lack self-spawn.

Stage 1 — Brand kit. Write content-os/brand-kit.json from the interview — with real ids on pillars, personas, funnel stages, associations and offers; those exact strings become the validated taxonomy in Stage 3. → references/1-interview.md

Stage 2 — Brand knowledge base + design tokens. Generate content-os/brand/ docs (identity.md, voice.md, strategy.md, visual-system.md, no-gos.md) and the design-token CSS (colors light/dark, fonts, RTL) from the answers. → references/2-brand-and-design.md

⭐ Stage 3 — The core libs. Build these BEFORE any view. Four zero-dependency ESM modules in app/src/lib/: the ONE strategy renderer (brand-kit.json → a prompt block per scope, shared by the app and the cron), the idea store (ideas.json — uuids, taxonomy validation, atomic writes, deterministic dedup, statuses), and the radar output contract + ingest. Everything downstream imports them. Skip this stage and you will parse markdown, drift five copies of the brand summary, and re-insert the same idea daily. → references/7-core-libs.md

Stage 4 — The dashboard app. START with the Stage 3.0 bootstrap (the exact create-next-app command + the Tailwind-v4 setup — no tailwind.config.js) before writing any feature; a weak model that skips it ships an unstyled or non-existent app. Then build the sidebar + views, filesystem-as-database API routes (each try/catch → empty default, and seed the empty data files), dark/light theme, RTL if needed, URL-hash navigation, inline SVG icons (NO emoji in the UI chrome). Ideas is a review queue (approve / reject-with-a-reason), and Strategy is read-only. → references/3-dashboard-app.md

Stage 5 — Background AI generation + the export engine. The Produce views (Carousels/Stories/Presentations) are one reused component that shows approved ideas on top and the produced pieces of that collection below, refreshing itself when a job ends — an idea must visibly become a piece in the same screen. Wire the /api/generate (and /api/radar) background-job pattern (survives reload, has Stop, reconnects), the Playwright HTML→PNG export engine, the scaffold script, and the per-format builder specs (carousel/story/presentation/script/thumbnail). Generation is gated on an approved idea and takes an idea_id, never a free string. → references/4-builders-and-export.md

Stage 6 — Radar + interactive calendar. The Radar view is part of this stage, not an afterthought: signals and ideas as cards with their fields as chips and badges (reference 5b) — a scan rendered as one paragraph of text is the default failure here. The scout prompt from the strategy renderer + the user's topics/sources/no-gos, emitting structured JSON against the contract; the on-demand /api/radar route; a scheduled daily run (cron/launchd/Task Scheduler) that ingests through the same code path as the app; and a health check with a visible banner — a scheduled job nobody watches fails silently, which is the failure mode that actually happens. Then the Notion-style month calendar backed by a JSON store, with rich items (title, type, platform, pillar, status, description, markdown body). Optionally wire read-only connectors (Notion import) if the user has them. → references/5-radar-and-calendar.md

Stage 7 — Publish + Growth (close the loop). The publish panel (assets + caption + one CTA + a pre-publish checklist), the three-layer no-auto-publish guarantee and its verify script, and — if a connector is wired — media that actually reaches the draft (a connector runs on remote servers and cannot read a local path or localhost; a caption-only draft is a failure, not a partial success). If the connector has no upload tool (Buffer does not), you are hosting the files yourself: read reference 8b before writing a line of it — it carries a security rule (never tunnel the dashboard, its generate route runs an agent with permissions skipped) and a failure mode where every server-side signal reports success while the images render broken. then the Growth view — metrics, the weekly review, and hooks that graduate into the bank with their real number. Without this the OS produces forever and learns nothing. → references/8-publish-and-growth.md

Stage 8 — The Assistant (chat) surface (optional, but the highest-value view per line of code). A chat pane that opens with the strategy block, so the user can ask for hooks or a rewrite without re-explaining their brand. Conversations are a real store (chats.json), each one a real route (/assistant/<id>), replies render as markdown with per-message direction, and the agent runs with its tools disabled so it answers instead of announcing it will go read files. → references/9-assistant-chat.md

Stage 9 — Analytics + Inspiration + Transcription (only if the user gave credentials in Q9 — otherwise skip and say so). Their own posts with real insights, comments, inline playback, click-to-transcribe; an account-level audience tab; a competitor library with hooks, public numbers, playback and transcripts. Two deliverables: the grids AND the post detail window that opens on click — the window is the half that gets skipped, and without it a competitor library teaches nothing (their captions are often just the keyword gate; the value is in the transcript). Validate every credential live BEFORE building on it (a dead Meta token is the #1 blocker) and tell the user exactly how to fix any that fail. → references/6-analytics-and-inspiration.md

Stage 10 — Verify + handoff. Typecheck (tsc --noEmit) — and prefer typecheck over a full build if the user has a dev server running, since building wipes .next. Never start a dev server to "verify" — the user runs that. Run the end-to-end walkthrough below, then print how to run it (<pm> dev in content-os/app), where assets land, how the radar scheduler was installed and how to remove it, and remind them to rotate any API key pasted into the chat.

The Stage 10 walkthrough — do all nine, in order

Per-stage checkpoints catch broken parts. This catches a broken loop, which is a different failure.

1. node tools/strategy-block.mjs radar | head -20 → the brand's real positioning, not the fallback
2. Run the radar once → radar/runs/<id>.json exists, ideas.json grew. Run it again → the same stories come back deduplicated, not inserted 2b. Break it on purpose — rename brand-kit.json, run the cron script: it must abort before spending a scan, log a fail row, and raise the banner in the UI. Restore, confirm the banner clears
3. Try to generate from a new idea → 409. Approve it → generation runs
4. The piece exports at the right dimensions, in the brand font, with exactly the CTA the record specified (or none, if it was null) — and it appears in that format's own view without a manual reload. An empty Carousels tab after a successful job is the #1 build failure: the view was never wired to the filesystem
5. The idea flipped to produced; the calendar event moves planned → published; the publish panel shows real assets
6. If the assistant was built: a starter prompt from the empty state gets a reply (the path that breaks when navigation happens mid-turn), Arabic and English both render un-mangled, and a reload keeps the conversation
7. If analytics was built: clicking a card — your own AND a competitor's — opens the detail window, plays, and transcribes
8. If a publishing connector was wired: a draft made from an 8-slide carousel arrives with 8 images in the right order, not the caption alone — and open it in the connector's own web UI, because an API that reports attached: 8 can still be showing eight broken thumbnails (reference 8b)
9. node tools/verify-publishing-safety.mjs exits 0 — and exits 1 when you temporarily move a publish tool into allow

Report honestly which of the six passed. Do not report the build as done with a failing step unmentioned — say which one failed and what you tried.

Degradation matrix (don't collapse these into one yes/no)

Capabilities are independent (Stage 0). Pick the highest tier each supports:

• Full — Node + Playwright + self-spawn: the whole OS as described.
• HTML-only export — Node + self-spawn, but Playwright/Chromium won't install: build the app, generation writes the HTML pieces but skips the PNG screenshot step (deliver/preview the HTML).
• Prompt-handoff generation — Node app builds, but the agent can't spawn itself: the Generate/Radar/Edit buttons write the composed prompt to content-os/<collection>/<slug>/PROMPT.md (or a modal/clipboard); the user runs their agent on it; an "I ran it — refresh" button re-scans. Dashboard is a full planning/viewing/calendar surface with manual generation. (See reference 3.)
• Lite Mode — no Node app at all (below).

Lite Mode (no web app possible)

If a full web app isn't feasible, still deliver a real content OS as files + scripts:

• content-os/brand/ knowledge base + design-tokens.css (Stage 2, unchanged).
• The core libs anyway (Stage 3 / reference 7) — they are plain ESM with zero dependencies and need no app. node tools/strategy-block.mjs generate prints the brand block to paste into any chat, and ideas.json + tools/radar-ingest.mjs still give you a deduplicated, validated idea store from the CLI. This is the highest-value part of the OS and it survives having no dashboard.
• Per-format builder skills (markdown specs) + self-contained HTML templates the agent fills per piece; export to PNG via a headless-browser script if available, else deliver the HTML.
• A radar command: a prompt the agent runs (with its own web-search tool) that writes a structured run to content-os/radar/runs/<id>.json, ingested by tools/radar-ingest.mjs; radar/feed.md stays the human log.
• A calendar as content-os/calendar.json + a tiny static HTML viewer (single file, no build step).
• growth/metrics.md + the weekly-review prompt (reference 8c) — the learning loop needs no app either. Everything else (voice, no-gos, pillars, CTAs) still comes from the interview. Tell the user which parts are file-based vs app-based.

Non-negotiables (carry these into whatever you generate)

• Personalization only. Every color, font, voice rule, pillar, CTA, radar topic, and no-go comes from brand-kit.json. No leftover reference-brand values.
• ⭐ One source of truth, one renderer. brand-kit.json is the only place the brand is defined, and strategy-block.mjs is the only thing that turns it into a prompt. Every AI surface — app routes and the cron — imports that one renderer and reads the kit fresh per request. Never hand-write a brand summary into a route. Five summaries drift silently the first time a pillar changes.
• ⭐ The kit is human-controlled. The AI reads it and may propose changes; it must never write it. Serve it GET-only. A system that can rewrite its own guardrails has none.
• ⭐ Structured data is stored structured. ideas.json is the database; markdown files are research records for humans to read. Never scrape prose to build a view.
• ⭐ Nothing gets produced unreviewed, and nothing gets published unconfirmed. Generation requires an idea whose status is approved; publishing to a live account requires an explicit go-ahead in that moment, every time.
• Never invent. No fabricated numbers, results, features, or client details — anywhere, in any generated piece. The proof bank in the kit is the whole list of what may be cited. A piece with no proof says less, it doesn't make things up.
• Respect the user's no-gos in the radar prompt, the voice docs, and any generation prompt — as hard filters.
• RTL correctness if the primary language is RTL: set dir at the root, use logical CSS properties, never hardcode dir per element, never apply negative letter-spacing to Arabic. (See reference 2.)
• Local-only AI actions. Routes that spawn a coding agent or skip permissions must be guarded to local/dev (return 403 in production) — they run the user's own agent CLI on their machine. And the dashboard has no publish endpoint.
• The filesystem is the database. No DB/ORM. API routes read/write real files under content-os/ and are non-cached (force-dynamic / no-store).
• ⭐ A record with fields renders as FIELDS. Chips for taxonomy, badges for state, a pull-quote for the hook, a link for the source — never a record stringified into a paragraph. The stores here are deliberately structured (ideas, radar runs, pieces, chats); a view that flattens them back into prose throws away the whole point and cannot be scanned. If you are joining fields with — or reaching for JSON.stringify, the view is wrong.
• ⭐ Data specified ≠ screen built. Each reference describes a store and then how to arrange what it shows; it is easy to read both and never build the screen in between. The views that get skipped this way, every time: the post detail window (ref 6), the Produce views (ref 3), and the Radar view (ref 5b). Check those three by name before you call a build done.
• ⭐ A control that refuses must say why. Every disabled button, skipped guard and early return needs a visible reason. A silently inert control is indistinguishable from a broken backend, and that mistake costs hours of debugging in the wrong layer.
• Verify by typecheck/build, not by the dev server. Never start a long-running dev server to "check" — the user runs that.

Start by reading references/1-interview.md, then run the interview.