@cliangdev/conductor 0.26.0 → 0.27.1

package/assets/claude/skills/conductor-content-studio/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: conductor-content-studio
+description: Runs a small team of subagents (strategist, three ideators, creative director, scriptwriter, art director) that brainstorm competing short-form social post ideas, pick one with a bias-resistant judging method, write the script and visual direction, run pre-publish checks (disclosure, AI label, music, claims, third-party material, accessibility), and render a local draft with a publish pack the publisher later pre-fills from. The person approves at the preview; only then is the Creative uploaded to Conductor. Ideas are either RENDER (a still, carousel, story sequence or motion text that Conductor can render) or FILM (needs real filming, so the output is a shoot-ready script). A run ends at a committed Creative or a shoot script and never creates a Post. Use when asked to come up with, choose and make a short-form post (TikTok, Reels, Shorts, Facebook) from a goal rather than from a given headline, or via /conductor:content. For a headline or photo already chosen, use conductor-creative instead.
+user-invocable: true
+allowed-tools: mcp__conductor__*, Agent, AskUserQuestion, Skill, Read, Write, Glob, Grep, WebFetch
+---
+
+# Conductor Content Studio
+
+Takes a request ("a post about X for Y") to either a committed Creative or a shoot-ready script. The
+team chooses the idea itself; the person is asked once, at the final draft preview. You are the
+orchestrator and run in the main session. Subagents do the thinking and writing; you do every
+Conductor call and every file merge.
+
+## Rules that shape the design
+
+Each exists because of a known failure mode (sources are in `references/rubric.md`).
+
+- **Subagents do not share context.** Hand off through files. Each stage writes its file and
+  returns only the path plus at most about 150 words. Never paste a file's content into a prompt
+  when its path will do.
+- **Flat orchestration.** Only you call `Agent`. Subagents never spawn subagents.
+- **Subagents get no MCP tools.** You make every Conductor call (`get_brand_kit`,
+  `preview_creative_draft`, `commit_creative_draft`, ...). Their tools are Read, Write and, for the
+  trend ideator, WebSearch.
+- **Diverge first.** Three ideators with different angles run in parallel and cannot see each other.
+- **Judge bias.** The judge is a different model tier, sees anonymized ideas at the same length,
+  writes reasoning before scores, compares finalists pairwise in both orders, and argues against its
+  own leader.
+- **One gate.** The person is asked only at the final draft preview. Do not stop to ask which idea.
+  The one exception is S5b's disclosure question, asked only when disclosure cannot be inferred.
+- **A run never creates a Post.** It ends at a committed Creative (or a shoot script).
+
+Cost: a run is about 8 subagent calls (strategist 1, ideators 3, director 2, scriptwriter 1, art
+director 1), and only the strategist and the director use the top model tier. `--quick` runs two
+ideators and skips the finalist renders (about 7 calls).
+
+## Run folder and state
+
+`<projectRoot>/.conductor/content-runs/<YYYYMMDD-HHMM-slug>/`, where `projectRoot` is the working
+directory's repository root and `slug` is 2 to 4 words of the request. The `.conductor/` folder is
+git-ignored. Write files with `Write` (it creates folders). Every path below is relative to the run
+folder; give subagents absolute paths.
+
+```
+request.md  run.json  brief.md  script.md  direction.md  creative-spec.json  decision.md
+context/   brand-kit.json  knowledge.md  performance.md  learning.md  media.json
+ideas/     angle-1.md  angle-2.md  angle-3.md  pool.md
+judging/   scores.md
+drafts/    finalist-<id>/   (contact sheets from the finalist renders)
+publish-pack.md  publish-pack.json   (S5b; see references/publish-pack-template.md)
+shoot/     shoot-script.md  (FILM winner only)
+```
+
+`run.json` is how a run resumes. Update it after every stage:
+
+```json
+{
+  "runId": "20261003-1415-spring-sale", "request": "...", "quick": false, "platform": "...",
+  "stages": {"S0": "done", "S1": "done", "S2": "pending", "merge": "pending", "S3a": "pending",
+             "S3b": "pending", "S3c": "pending", "S4": "pending", "S5": "pending", "S5b": "pending",
+             "S6": "pending"},
+  "idMap": {"I1": {"angle": "story/emotion", "file": "ideas/angle-1.md", "n": 3}},
+  "finalists": [], "winner": null, "tag": null, "runnerUps": [],
+  "tags": {"hookType": null, "angle": null, "format": null},
+  "drafts": {"finalist-I3": "<absolute dir>", "final": "<absolute dir>"},
+  "creativeId": null, "creativeDisplayId": null, "shootDoc": null
+}
+```
+
+Stage values: `pending`, `done`, `failed`, `skipped`. The `idMap` is the only place angles are
+linked to IDs; it is never shown to the director.
+
+**Resume check (first thing).** Glob `.conductor/content-runs/*/run.json`. If one has a stage that is
+not `done` or `skipped` and no `creativeId` or `shootDoc`, ask with `AskUserQuestion` whether to
+**Resume** that run (name it and its last finished stage) or **Start a new run**. On resume, skip
+done stages and continue from the first pending one.
+
+## Delegation prompt template
+
+Every `Agent` call uses this shape, filled in. Keep it short; the agent's own file holds its role.
+
+```
+Objective: <one sentence: what this stage must produce>
+Mode / angle: <text-round | visual-round | angle "story/emotion" with N ideas | n/a>
+Inputs (read only these): <absolute paths>
+Template / rubric: <absolute path to the reference file>
+Output: write only <absolute path>
+Boundaries: do not call Conductor or any MCP tool; do not read or write other files; follow the
+template exactly; <any stage-specific rule>
+Return: at most 150 words plus the output path.
+```
+
+Resolve the reference files once: Glob for `**/conductor-content-studio/references/rubric.md` under
+`.claude/skills/` in this project, then under `~/.claude/skills/`. Use that folder for every
+`references/` path below. A subagent that returns more than 150 words or leaves its file unwritten
+has failed the stage: retry once with a one-line reminder, then tell the person.
+
+## Stages
+
+### S0 — Context snapshot (you)
+
+Write `request.md` (the request verbatim, `--quick` if given, the platform if stated). Then:
+
+1. `get_brand_kit` -> `context/brand-kit.json`. If `configured` is false and the person already
+   skipped setup in the command, note that in the brief's constraints.
+2. Knowledge, for `context/knowledge.md`: `read_knowledge_pages` for the kit's `knowledgePagePath`
+   and `marketing/what-works.md`; `search_knowledge` for persona/audience, campaign and positioning
+   pages and read the best few (at most 6 pages in all). Paste each page under its path heading, trimmed
+   to what bears on the request; keep approved lines verbatim. List every expected page that was not
+   found under "Missing pages". A missing page is a gap to record, never a reason to stop.
+3. Performance, for `context/performance.md`: `get_marketing_insights` (window `30d`, or `90d` if
+   empty) and `list_top_posts` (limit 10). Summarise what the data says; "no performance data yet"
+   is a valid result.
+4. `list_creative_media` for `IMAGE`, `VIDEO` and `AUDIO` -> `context/media.json` (id, kind, label,
+   dimensions or duration, checked, blocked, provenance).
+5. Learning, for `context/learning.md`. Glob `.conductor/content-runs/*/run.json`, skip this run, and
+   keep the runs that have a `creativeId` and `tags`. For each, call `get_creative` (the variants'
+   attributed performance and the family's hook experiment, with its winner once decided) and read
+   its tags (hookType, angle, format). Summarise which hook types and angles did well and which did
+   not, using views, engagement rate, average view percentage, 72 h views and any 3-second or
+   completion figure the insights expose, and any experiment result. Name what you could not
+   measure. With no earlier run or no data, write exactly "No data yet".
+6. Every renderable idea needs a photo (or, for MOTION, a clip); see `references/capabilities.md`. If
+   `media.json` has no unblocked image and no clip, ask once with `AskUserQuestion` before ideating:
+   **Give a photo or two** (local paths; record them in `context/media.json` as `local` entries the
+   art director may use via `photoPath`) or **Plan for filming** (ideas will be `FILM`). Never let
+   the team design a type-only still; the preview refuses it.
+
+### S1 — Strategist -> `brief.md`
+
+`Agent(subagent_type: "conductor-content-strategist")` with the six context files, `request.md`
+and `references/capabilities.md` (so the brief states rendering constraints correctly: motion text
+over a photo is renderable and needs no filming).
+
+### S2 — Ideators, in parallel -> `ideas/angle-<n>.md`
+
+Three `Agent` calls in ONE message so they run in parallel, `subagent_type:
+"conductor-content-ideator"`, with these angles and no knowledge of each other:
+
+1. story/emotion  2. utility/education  3. trend/humor (the only one allowed web search)
+
+Each gets `brief.md`, `context/media.json`, `references/idea-template.md` and
+`references/capabilities.md` (the `RENDER`/`FILM` test), and writes 4 ideas.
+With `--quick`: only angles 1 and 2, 3 ideas each.
+
+### Merge (you) -> `ideas/pool.md`
+
+Build one pool from all the angle files:
+
+- Give every idea an ID `I1..In` in a shuffled order (not grouped by angle, not in file order).
+- Remove angle names and any trace of the source. Put every idea in the identical template from
+  `references/idea-template.md`, trimming any field to its word cap so lengths match.
+- Record the true mapping in `run.json` `idMap`. Keep the tag (`RENDER`/`FILM`) in the pool.
+- Drop an idea that breaks the brief's must-avoid list or copy rules in a way you cannot fix by
+  one word, and note the drop in `run.json`.
+
+### S3a — Creative director, text round -> `judging/scores.md`
+
+`Agent(subagent_type: "conductor-content-creative-director")`, mode `text-round`. Inputs:
+`brief.md`, `ideas/pool.md`, `references/rubric.md`. It scores every idea independently, reasoning
+before each score, and names the top 3. Store the finalists in `run.json`.
+
+### S3b — Finalist drafts (you; skipped in `--quick`)
+
+For each `RENDER` finalist, call `preview_creative_draft` with that idea's draft spec (map the
+draft-spec block to the tool's fields) and `draftDir` set to `<run>/drafts/finalist-<id>`. Use
+`full: false`. Record each draft dir in `run.json`.
+
+- If the validator refuses the copy (accent phrase or a copy rule), fix the copy once yourself and
+  retry. If it still fails, mark that finalist unrenderable in `run.json`, keep its text score, and
+  move on. It is not dropped.
+- A photo id that is not in `media.json`, or a layout the registry rejects, counts as a refusal.
+- The preview result carries `checks` and `passed` (the full-size safe-zone, spill and contrast
+  checks). If a finalist fails a blocking check, fix it once (`layoutOverrides`, `typeOverrides`, a
+  shorter body) and re-preview; otherwise keep it and record the failure for the judge.
+- `FILM` finalists have no render.
+
+### S3c — Creative director, visual round -> `decision.md`
+
+Same agent, mode `visual-round`. Inputs: `brief.md`, `judging/scores.md`, `ideas/pool.md`, the
+finalist image paths (`drafts/finalist-<id>/sheet.jpg`; the director views them with Read), the
+rubric and `references/compliance-checklist.md`. It compares finalists pairwise in both orders, runs
+the devil's-advocate pass against the leader (including the veto questions: an unsubstantiated
+claim, trademark or parody risk, a representation or sensitivity problem, disclosure needed), and
+writes `decision.md`: the winner, why it won, the runners-up, one line per cut idea and the veto
+answers. A veto "yes" that copy cannot fix disqualifies an idea. In `--quick` there are no images,
+so it judges from the text and says so.
+
+Read `decision.md`, then set `winner`, `tag` and `runnerUps` in `run.json`, and the run's own
+`tags`: `hookType` from the winning idea's hook type, `angle` from `idMap` (`story-emotion`,
+`utility-education` or `trend-humor`) and `format` from the idea's format. Do not ask the person
+which idea to take; show the decision at the gate.
+
+### S4 — Scriptwriter -> `script.md`
+
+`Agent(subagent_type: "conductor-content-scriptwriter")` with `brief.md`, `decision.md`, the winning
+idea from `ideas/pool.md`, `references/script-template.md`, `references/platform-specs.md` and
+`references/publish-pack-template.md`. Besides the script it writes the Publish copy section: a
+caption per platform, hashtags, a first comment and 2 to 3 alternate hooks with a hookType each.
+When merging into `publish-pack.json`, append each platform's hashtags to its `captionOverride`
+(caption, blank line, hashtags): that field is posted verbatim.
+
+### S5 — Art director (`RENDER` only) -> `direction.md` + `creative-spec.json`
+
+`Agent(subagent_type: "conductor-content-art-director")` with `script.md`, `context/media.json`,
+`context/brand-kit.json`, `references/shotlist-template.md`, `references/platform-specs.md` and
+`references/publish-pack-template.md`. Besides the spec it writes the Publish assets section of
+`direction.md`: cover frame, alt text per card, on-screen text placement and the sound source and
+licence per platform.
+Tell it the supported options: the kit's enabled placements, and the layouts and themes
+the creative registry supports (at the time of writing `stacked`, `bleed`, `split` dark only, `card` dark or
+light; a refusal from the validator names the valid ones). The spec's keys must be exactly
+`preview_creative_draft` inputs. Give it `references/capabilities.md` too. The spec's `name` is the
+idea's title only: never include the internal `I<n>` ID, which means nothing outside this run. A
+`FILM` winner skips S5 and goes to the shoot script, below.
+
+### S5b — Publish pack and pre-publish checks (you; RENDER after S5, FILM after the shoot script)
+
+Before the gate, so the person sees the settings with the draft. Skip nothing here; a check that
+does not apply is answered "not applicable".
+
+1. Run `references/compliance-checklist.md` against `brief.md`, `script.md`, `direction.md` (or the
+   shoot script), `creative-spec.json` and the provenance in `context/media.json` (`aiGenerated`,
+   `licence`).
+2. Merge the scriptwriter's Publish copy and the art director's Publish assets, add the compliance
+   results, and write `publish-pack.md` and `publish-pack.json` in the shapes of
+   `references/publish-pack-template.md`. Real option keys only. The posting window comes from
+   `get_marketing_insights` (`byHour`, `byWeekday`) for the platform, or "no data yet".
+3. Ask at most ONE `AskUserQuestion`, and only when disclosure cannot be inferred: the request,
+   brief or media names a creator, customer, partner or sponsor and the relationship is unclear.
+   Question "Is anyone in or behind this post paid, gifted, an employee/affiliate?" with options
+   **No, this is the brand's own post**, **Yes, paid partnership**, **Yes, gifted or affiliate**.
+   Otherwise assume the brand's own promotional post and set TikTok `brandOrganicToggle`. Paid
+   sets `brandContentToggle`; gifted or affiliate sets `brandContentToggle` and adds the
+   disclosure to the caption's first line.
+4. A claims or trademark check that fails and cannot be fixed by you in one word goes back to the
+   scriptwriter once, with the failing line; re-run S4's merge and S5 only if the copy changed. If
+   it still fails, show it at the gate as a known issue and never hide it.
+5. Set `S5b` to `done`. On any later copy change, redo this stage so the pack matches the draft.
+
+### S6 — Preview gate (you; `RENDER` winner)
+
+1. `preview_creative_draft` with the fields from `creative-spec.json`, `full: false`, and no
+   `draftDir` (the default location is cleaned up automatically after the commit). Record the
+   returned `draftDir` as `drafts.final`. Local files (`photoPath`, `clipPath`, `audioPath`) go in
+   as given in the spec.
+2. Eye-check the image. Load the `conductor-creative` skill with `Skill(skill: "conductor-creative")` and
+   apply its review guidance (step 7 and the silent-failures list): does the headline read at a
+   glance, does the accent phrase fall on the words that carry the meaning, is copy on a face, are
+   the safe zones clear. Also read the result's `checks`/`passed`: while any blocking check fails,
+   fix it (`layoutOverrides` for photo height, `typeOverrides` for text size, a shorter body) and
+   re-preview **before** showing anything, and never offer Approve & upload while one still fails.
+   Revise at most twice beyond that; if it is still wrong, show it honestly and say what is off.
+3. Show the person: the draft image, the finalist sheets of the runners-up (view them from
+   `drafts/finalist-<id>/sheet.jpg`; say when a runner-up could not be rendered), and a short decision
+   summary (the winner and why, the runners-up, what was cut and why), and a short pack summary: the
+   disclosure setting (which toggle, or none), the AI-label setting, the sound and its licence, and
+   the alternate hooks with their types.
+4. Ask with `AskUserQuestion`, header "Draft", with exactly these four options. `AskUserQuestion`
+   allows at most four, so never add one per runner-up, and **Stop** must always be among them:
+   - **Approve & upload**: if the spec used a local file (`photoPath`, `clipPath`, `audioPath`),
+     first ask for its provenance (`source`, `licence`, and whether it is AI-generated) and pass
+     them to `commit_creative_draft({draftDir, source, licence, aiGenerated})`. Then
+     `get_creative` and read its `readiness`. If provenance or anything else blocking is missing,
+     say exactly what and ask for it; never call a Creative done while `ready` is false. After the
+     commit, write the Creative's id into `publish-pack.json` as `creativeId` (and into `run.json`).
+   - **Use a runner-up**: ask a second `AskUserQuestion` listing the runners-up by title (with
+     their tag; label one that could not be rendered as such and say why, rather than offering it as
+     if it would work). Then set the chosen idea as `winner` and re-run S4 onward for it (S5, S5b and S6,
+     or the FILM path if it is tagged `FILM`).
+   - **Request changes**: take the free text. If it is about the copy, send it with the current
+     script to the scriptwriter (S4), then the art director (S5); if only about the look, send it to
+     the art director. Redo S5b, then re-preview. Do not commit the old draft.
+   - **Stop**: upload nothing. Tell the person where the drafts are
+     (`drafts.final` and the finalist folders) and that the run can be resumed.
+
+### FILM winner
+
+1. After S4, have the art director write the shoot version: `Agent(subagent_type:
+   "conductor-content-art-director")` with `script.md`, `context/media.json`, `context/brand-kit.json`
+   and `references/shotlist-template.md`, output `shoot/shoot-script.md`: script, shot list, capture
+   settings (9:16, 30 fps, sound on), B-roll, safe zones, and the on-screen text and captions ready to
+   paste. It also writes the Publish assets section there. It writes no `creative-spec.json` here.
+2. Run S5b. The shoot script gets the publish pack too (captions, hashtags, first comment,
+   disclosure, music and its licence) so it can be applied when the clip is posted later; append a
+   short "Publish pack" section to `shoot/shoot-script.md`, and leave `creativeId` null in
+   `publish-pack.json`.
+3. Show the shoot script, then ask with `AskUserQuestion` whether to save it as a project doc:
+   **Save to project docs** or **Keep local only**.
+4. On save, `write_project_doc` at path `Content/Shoots/<runId> <title>` with the file's content;
+   verify with `read_project_doc` and record `shootDoc` in `run.json`. Nothing else is uploaded.
+
+## Final message
+
+Keep it short:
+
+- the decision summary: winner, one line on why, the runners-up;
+- the Creative display id (and the readiness gaps, if any) or the shoot doc path;
+- `publish-pack.md` (captions, hashtags, first comment, disclosure and AI-label settings, sound,
+  alternate hooks); say the publisher will pre-fill the Post from `publish-pack.json`, and that the
+  first comment is a manual step;
+- next steps:
+  - make the Post with `/conductor:creative` or the `conductor-publisher` skill (the Creative is
+    not on a Post yet, because a run never creates one);
+  - to test a runner-up's hook, cut it as a lettered variant of the Creative with `variantOf`;
+  - for `FILM`: film it, upload the clip, then run `/conductor:creative` and pick "Video from a
+    clip I have".
+
+## Failure handling
+
+- A subagent that fails twice: mark the stage `failed` in `run.json` and tell the person what
+  stopped, with the run folder, so it can be resumed.
+- MCP tool errors: surface the message as it is; do not work around a validator refusal by changing
+  the rule's field or dropping the check.
+- If every finalist is unrenderable, run S3c in text-only mode as in `--quick`.
+- Never commit a draft the person has not seen and approved. Never call `create_post`,
+  `attach_creative_to_post` or any publishing tool.
+
+## Related
+
+- `conductor-creative`: the single-Creative skill whose checklist S6 uses.
+- `conductor-publisher`: takes the committed Creative onto a Post, pre-filled from `publish-pack.json`.

package/assets/claude/skills/conductor-content-studio/references/capabilities.md

@@ -0,0 +1,61 @@
+# What Conductor can render
+
+Read this before tagging an idea `RENDER` or `FILM`, and before writing a spec. An idea is `RENDER`
+only if every card or frame it needs fits what is listed here, using media that is in
+`context/media.json` or that the person has offered as a local file. Anything else is `FILM`, or it
+needs changing until it fits.
+
+## Kinds
+
+- **STILL**: one photo with the brand layout over it: headline, optional body, logo lockup and CTA.
+  It renders once per placement.
+  - **Carousel**: 2–10 cards, rendered at one ratio (default 4:5).
+  - **Story**: 2–7 beats, rendered at the `story` placement.
+  - Each card or beat can take its own photo; a beat without one inherits the main photo. Every beat
+    after the first needs a headline.
+- **MOTION**: a short video Conductor animates itself, 3–60 s (default 8 s).
+  - Text animation presets: `fade-up`, `word-by-word`, `accent-pop` or `none`.
+  - Background: a photo with a slow zoom or pan, or a clip from the library.
+  - An end card holds the finished frame for the last 2 s.
+  - Audio: the clip's own sound, a library music track, or none.
+  - This is the right tool for a motion-text post: **it does not need filming.**
+- **CLIP**: a finished video posted as-is. There is no brand layout and nothing to draft. It only
+  applies when the person already has the video.
+
+## Hard requirements (a draft is refused without them)
+
+- **A photo.** Every STILL needs one, and so does a carousel or story, whose beats inherit the main
+  photo. A MOTION needs a photo or a clip as its background. There are no type-only stills. If
+  `media.json` has no usable (unblocked) image, a `RENDER` idea needs the person to supply a photo.
+- **A headline.** If the Brand Kit requires an accent phrase, the headline needs exactly one
+  `*accent phrase*`.
+- **Copy rules and approved lines.** Every Brand Kit copy rule applies to the headline, body,
+  caption and every beat. Approved lines must run word for word.
+- **Real values.** Layouts, themes and placements must exist. The validator names the valid ones
+  if not.
+
+## Layouts and controls
+
+- **Layouts:** `stacked`, `bleed` and `split` are dark only; `card` is dark or light. The photo and
+  text arrangement is fixed per layout.
+  - **`stacked` drops the body at 4:5.** That includes every card of a 4:5 carousel, and it happens
+    silently. If a body line carries meaning (a claim, the product name, the accent phrase), use
+    `card`, `split` or `bleed`, or move the line into the headline.
+- **Placements:** the kit's enabled placements (usually 9x16, 4x5, 1x1). You can also opt in to
+  `story`, `1.91x1`, `2x3` and `16x9`.
+- **`typeOverrides`:** headline size per placement. Use this when text reads too small or too large;
+  don't switch layouts to fix it.
+- **`layoutOverrides`:** photo height or focal point, for example to make the photo fill more of a
+  9:16 frame.
+- **Safe zones:** checked automatically at preview, on every placement. A blocking failure, such as
+  text or a badge under the platform's buttons, is fixed before anyone is asked to approve.
+- **The caption is never drawn on the artwork.** It goes with the post.
+
+## What it cannot do (so the idea needs filming or a rethink)
+
+- Footage of people, places, cooking or the product in use. Screen recordings of an app.
+- Voiceover or spoken dialogue: MOTION has music or clip sound, not speech.
+- Grids, charts, collages of several photos on one card, illustrations, or generated images.
+  Each card is one photo plus text.
+- Anything that relies on a product claim the brief can't confirm. That's a copy problem, not a
+  rendering one: soften the claim or drop the idea.

package/assets/claude/skills/conductor-content-studio/references/compliance-checklist.md

@@ -0,0 +1,120 @@
+# Pre-publish compliance checklist
+
+Run by the orchestrator in stage S5b against `brief.md`, `script.md`, `direction.md`,
+`creative-spec.json` and the media provenance in `context/media.json`. The creative director uses
+the veto questions (marked **Veto**) in its devil's-advocate pass. Every check is a yes/no
+question with what to do and the exact publish option it sets. Record each answer in
+`publish-pack.md` and the options in `publish-pack.json` (see `publish-pack-template.md`).
+
+Option keys here are the keys `list_publish_targets` reports under a destination's `optionKeys`
+(camelCase, set under `options` in `create_post` or `publishOptions` in `set_publish_targets`).
+That list is the authority at publish time: if a key is not in a destination's `optionKeys`, do not
+send it. This is guidance for a team that makes content, not legal advice; platform and regulator
+rules change, so check current guidance before relying on it.
+
+## 1. Disclosure (Veto)
+
+**Is anyone in or behind this post paid, gifted, an employee or an affiliate?** (A creator, a
+customer given free product, a staff member speaking about the employer, a partner brand, an
+affiliate link.)
+
+- **Yes**: the relationship is disclosed in the first seconds of any video and in the caption's
+  opening line (for example "Paid partnership with ...", "Gifted by ...", "Affiliate link").
+  Set TikTok `brandContentToggle: true`. TikTok refuses `brandContentToggle` on a post whose
+  `privacyLevel` is `SELF_ONLY`, so the post must be visible.
+- **No, this is the brand promoting its own product on its own account**: set TikTok
+  `brandOrganicToggle: true`. No on-screen disclosure line is needed beyond being obviously the
+  brand's own post.
+- **Which toggle:** "Your brand" (`brandOrganicToggle`) is a business promoting itself.
+  "Branded content" (`brandContentToggle`) is a paid partnership where a third party is promoting
+  someone else's business. Never use `brandOrganicToggle` to cover a paid creator.
+- Other platforms have no disclosure option in Conductor. Put the disclosure in the caption's first
+  line and turn on the platform's own paid-partnership label by hand; list that as a manual step.
+- Default when nothing in the request, brief or media points to a third party: the brand's own
+  promotional post, so `brandOrganicToggle: true`.
+
+Source: FTC Endorsement Guides FAQ (ftc.gov/business-guidance/resources/ftcs-endorsement-guides-what-people-are-asking):
+disclose paid, gifted, employee and affiliate relationships; in video, disclose at the start.
+
+## 2. AI label
+
+**Is any realistic imagery, video or voice AI-generated or AI-altered?** Check the Creative's and
+each media file's provenance (`aiGenerated` in `context/media.json`) and the script's visuals.
+
+- **Yes**: set TikTok `isAigc: true` on a video post. Conductor does not send `isAigc` on a TikTok
+  photo post, so for a photo post note "turn on TikTok's AI label by hand" as a manual step. Set
+  YouTube `containsSyntheticMedia: true`. Meta has no option: note that Instagram's and Facebook's
+  "AI info" label must be turned on in the app.
+- **No**: text, motion graphics over a real photo, and real photos are exempt. So is content that
+  is obviously unrealistic or animated. Say which of these applies.
+- Never leave `isAigc` unset when provenance says `aiGenerated: true` for a realistic asset.
+
+Source: TikTok, Meta and YouTube each require disclosure of realistic AI-generated or AI-altered
+imagery, video or voice.
+
+## 3. Music and sound (Veto, for TikTok)
+
+**For each platform, what is the sound source and is it licensed for this account?** Name it in the
+pack: original audio, a library track (with its recorded `licence`), the clip's own sound, or none.
+
+- A business account cannot use most trending tracks. On TikTok a business account can only use
+  the Commercial Music Library, which is licensed for TikTok only, so a track from it is not
+  cleared for Reels or Shorts. Use the Commercial Music Library or original audio.
+- Never name a trending song a business account cannot license. If the idea depends on one, the
+  idea fails this check and the director may disqualify it.
+- Instagram Reels `audioName` is an attribution label for a Reel's audio; set it only when the
+  sound has a credit to give.
+- A library track used in a MOTION Creative must have its licence recorded (the readiness checklist
+  blocks otherwise).
+- Photo posts on TikTok: `autoAddMusic` lets TikTok pick a soundtrack. Leave it unset unless the
+  person chose it, because the track is not one the team vetted.
+
+## 4. Claims (Veto)
+
+**Is every factual or product claim confirmed?** A claim is anything a viewer could check: a
+number, "first", "best", a result, a feature, a price, a comparison, a health or savings promise.
+
+- Each must be confirmed by `brief.md`, a knowledge page in `context/knowledge.md` or an approved
+  line in the Brand Kit. Quote where.
+- If not confirmed: soften it ("can help" instead of "will"), or remove it. If the idea only works
+  with the unconfirmed claim, it fails the check.
+
+Source: the FTC's endorsement guidance: don't make claims the advertiser can't substantiate.
+
+## 5. Third-party material (Veto, for parody and trademarks)
+
+**List every third-party asset in the post:** music, footage, logos, memes, screenshots, likenesses
+of real people, trademarks and product names, parodies.
+
+- Each gets a row in the pack's third-party list: what it is, whose it is, and the permission or
+  licence (own work, licensed, with consent, or "none, remove").
+- Anything with no permission is removed or replaced.
+- **Flag parody of another company's product or brand.** Even a joke needs a person to approve it;
+  if it can't be fixed in copy (it is the whole premise), the idea fails.
+- A person's likeness or voice, real or imitated, needs consent.
+
+## 6. Representation and sensitivity (Veto)
+
+**Does anything stereotype, exclude, mock or trade on a sensitive subject (health, money
+hardship, grief, religion, politics, a protected group)?** A quick read of the hook, the visuals
+and the caption.
+
+- If yes and it can be fixed by changing words or the picture, fix it and note the change.
+- If it can't be fixed, the idea fails.
+
+## 7. Accessibility
+
+**Does the post work for someone who cannot see it or cannot hear it?**
+
+- Alt text for every image or card (at most 1,000 characters on Instagram). Carry it in the
+  Creative's `altText` and in the pack. Instagram `altText` is an option only on a single feed
+  image; cards in a carousel cannot each carry published alt text, so list it in the pack.
+- Captions or on-screen text for everything spoken, so the post works with the sound off. Burned-in
+  text is preferred over relying on a platform's auto-captions.
+- Contrast and safe zones are already checked by the renderer; do not repeat them.
+
+## Result
+
+Write a table: check, answer (yes / no / not applicable), what was done, option set. A check that
+fails and can't be fixed in copy goes back to the scriptwriter once (S5b step 4); if it still
+fails, say so at the gate rather than hiding it.

package/assets/claude/skills/conductor-content-studio/references/idea-template.md

@@ -0,0 +1,54 @@
+# Idea template
+
+Every idea in `ideas/angle-<n>.md` uses exactly this template, so the merged pool reads the same
+whichever agent wrote it. Keep the word caps; the judge is told not to reward length, and equal
+length also keeps the comparison fair.
+
+Heading: `## Idea <n>: <title>` where the title is 8 words or fewer.
+
+```
+## Idea <n>: <title, max 8 words>
+
+- **Concept:** <one line, max 25 words: what the viewer sees and why it works>
+- **Hook, spoken:** <max 12 words, or "none (text only)">
+- **Hook, on screen:** <max 12 words>
+- **Hook type:** <question | bold-claim | pattern-interrupt | relatable-pain | how-to | number | curiosity-gap | story | social-proof>
+- **Format:** <still | carousel | story sequence | motion text over photo | motion text over clip | talking head | demo | skit | other>
+- **Platform:** <primary platform, then any others>
+- **Tag:** RENDER | FILM
+- **Why this audience cares:** <max 30 words, tied to the brief's tension>
+- **Assets needed:** <ids and labels from media.json, or "none", or what must be filmed>
+
+Draft spec (RENDER only):
+
+- kind: STILL | MOTION
+- layout: <a layout the brand kit and registry support>
+- theme: dark | light
+- headline: <with exactly one *accent phrase* if the kit requires it>
+- body: <max 20 words, or none>
+- caption: <the post caption, within the platform's limit>
+- photoId: <id from media.json, or none>
+- sequence: <for a story or carousel only: one line per beat, "headline | body">
+- motion: <MOTION only: preset, durationSec, background>
+```
+
+## Sound
+
+An idea may not rely on a trending song. A business account cannot license most trending tracks, so
+name original audio or a Commercial Music Library track, or leave sound out of the concept.
+
+## Tagging honestly
+
+- `RENDER` means Conductor can make it end to end: a still, a carousel, a story sequence, or motion
+  text over photos or clips that exist in `media.json` (or need no photo at all). Nothing in it
+  requires a person to be filmed or footage that is not on hand.
+- `FILM` means it needs real filming: a person speaking to camera, a demonstration, a skit, a
+  product in use. A `FILM` idea has no draft spec; it gets a shoot-ready script instead.
+- Tag against the media actually on hand. If the idea needs a clip that is not in `media.json`, it
+  is `FILM`, or it is `RENDER` with the missing photo named under "Assets needed" as something the
+  user must supply.
+
+## Distinctness
+
+Within one angle file no two ideas may share a mechanic (for example two list posts, or two
+before/after reveals). Differ in the hook device, the format, or the emotional register.

package/assets/claude/skills/conductor-content-studio/references/platform-specs.md

@@ -0,0 +1,59 @@
+# Platform specs for short-form posts
+
+Every number on this page is a planning default taken from public platform guidance at the time of
+writing. **Check current platform guidance before relying on any of it**; platforms change limits and
+ranking signals without notice, and the brief's own platform list always wins.
+
+## Craft that holds on every platform
+
+- Hook in the first 0 to 3 seconds, both spoken and on screen. The first frame is the thumbnail
+  and the ad.
+- A new beat or pattern interrupt every 3 to 5 seconds (a cut, a new line of text, a zoom, a
+  reveal), then a payoff, then one call to action.
+- Captions on screen so it works with the sound off. Decide sound design on purpose: sound-on
+  platforms reward voice and music, but many people watch muted.
+- Vertical 9:16 for TikTok, Reels, Stories and Shorts. Keep text out of the platform's own UI.
+- Plan for retention, not reach: a shorter piece that is watched to the end beats a longer one that
+  is abandoned.
+
+## Safe zone (9:16, 1080x1920)
+
+Use the Reels zone as the default for every vertical placement: keep text and faces out of the top
+~14%, the bottom ~35% and ~6% at each side. That leaves a central band of roughly 1000 px of height
+for the hook, headline and CTA. TikTok's right-hand button column and caption area, and the Shorts
+channel and title strip, take comparable space (check current platform guidance).
+
+## Platforms
+
+| Platform | Format and aspect | Length | What the ranking rewards | Sound and captions |
+|---|---|---|---|---|
+| TikTok | Video 9:16 (photo carousels also exist) | Up to several minutes; short pieces of about 15 to 45 s are the planning default | Watch time and completion, rewatches, shares, comments; TikTok's Creative Codes frame a piece as hook, body, close | Built for sound on; on-screen captions still matter. Caption text up to about 2,200 characters, but only the first line is visible before "more" |
+| Instagram Reels | Video 9:16 | Up to 3 minutes; about 15 to 30 s is the planning default | Watch time, likes and sends (shares by direct message); originality | Captions on screen; sound-off viewing is common. Caption up to 2,200 characters, about 125 shown before "more" |
+| Instagram feed | Image or carousel 4:5 (also 1:1) | Carousels 2 to 10 cards | Saves, sends, likes; carousel swipes | No sound; the first card carries the hook |
+| Instagram Stories | 9:16, 2 to 7 beats | Each story card is short; sequences aim for 3 to 5 beats | Taps forward and replies; completion of the sequence | Text on screen; stickers and links sit in the UI zones |
+| YouTube Shorts | Video 9:16 | Up to 3 minutes (older limits were 60 s) | Viewed vs swiped away, then average view duration | Sound on, captions on screen; title up to 100 characters |
+| Facebook | Reels 9:16; feed image or video 1:1 | Reels are short vertical video; feed video varies | Watch time, shares, meaningful comments | Most feed video is watched muted: captions are required |
+
+## Mapping to Conductor placements
+
+| Placement key | Shape | Typical destinations |
+|---|---|---|
+| `9x16` | 1080x1920 vertical | TikTok, Instagram Reels, YouTube Shorts, Facebook Reels |
+| `4x5` | portrait | Instagram feed |
+| `1x1` | square | Facebook feed (also Instagram feed) |
+| `story` | vertical, sequence frames | Instagram and Facebook Stories |
+| `16x9` | landscape | YouTube (standard) |
+| `1.91x1` | wide link-ad | link ads |
+| `2x3` | tall pin | Pinterest |
+
+The enabled placements come from the Brand Kit; a Creative can opt in to more via `placements`.
+`attach_creative_to_post` does the placement to destination mapping later; this skill stops at the
+committed Creative.
+
+## Picking a format from the idea
+
+- A single claim or quote: a STILL at `9x16` plus `4x5` and `1x1`.
+- A sequence with a payoff on the last beat: a carousel (5 to 7 cards perform best, one shared
+  ratio) or a story (3 to 5 beats).
+- A beat-by-beat reveal or kinetic text: MOTION, 6 to 15 s, over a photo or a clip on hand.
+- A person, demonstration or skit: `FILM`, vertical, shot to the safe zones above.