diff --git a/docs/skills/README.md b/docs/skills/README.md index 2b2aff7d7..6ddb32265 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -110,6 +110,7 @@ Invoked when a specific need arises — not part of any chain. | Skill | Description | |-------|-------------| | [`/ce-demo-reel`](./ce-demo-reel.md) | Capture visual evidence (GIF, terminal recording, screenshots) for PR descriptions — strict separation from test output | +| [`/ce-promote`](./ce-promote.md) | Draft user-facing announcement copy for a shipped feature (X, changelog, LinkedIn, email) — voice-matched via the optional Spiral CLI, a lite layer of editorial & social expertise without it, drafts only | | [`/ce-resolve-pr-feedback`](./ce-resolve-pr-feedback.md) | Evaluate, fix, and reply to PR review feedback in parallel — including nitpicks | | [`/ce-test-browser`](./ce-test-browser.md) | End-to-end browser tests on PR / branch-affected pages using `agent-browser` exclusively | | [`/ce-test-xcode`](./ce-test-xcode.md) | Build and test iOS apps on simulator using XcodeBuildMCP — screenshots, logs, human verification | diff --git a/docs/skills/ce-promote.md b/docs/skills/ce-promote.md new file mode 100644 index 000000000..fcac4f7c5 --- /dev/null +++ b/docs/skills/ce-promote.md @@ -0,0 +1,100 @@ +# `ce-promote` + +> Turn a shipped feature into copy-pasteable, user-facing announcement copy — right inside the engineering workflow. Spiral-agnostic by default; voice-matched when the Spiral CLI is installed. + +`ce-promote` is the **post-ship messaging** skill. After a feature merges, it figures out what shipped, picks the right channels, and drafts the announcement copy — an X post or thread, a one-line changelog blurb, a LinkedIn post, an email, a blog intro, a short demo script. It produces good copy with nothing installed, and uses the [Spiral CLI](https://www.npmjs.com/package/@every-env/spiral-cli) for brand-voice-matched drafts when it's present and authed. + +It drafts only. It never posts, publishes, commits, or opens PRs — shipping the copy is a human action. + +--- + +## TL;DR + +| Question | Answer | +|----------|--------| +| What does it do? | Summarizes what shipped, picks channels, drafts announcement copy, presents it for review | +| When to use it | Right after a feature ships and you want the user-facing messaging drafted in-workflow | +| What it produces | Copy-pasteable drafts, labeled by channel — never an auto-post | +| Spiral | Optional enhancement: voice-matched drafts when the CLI is ready; otherwise offers setup once, then drafts with a lite layer of editorial & social expertise | + +--- + +## The Problem + +Messaging usually waits for a separate marketing pass, so it lags the ship — and the engineer who has the most context on the user value isn't the one who writes the copy. When announcement copy *is* written ad hoc, it tends toward AI tells ("We're thrilled to announce…"), hashtag spam, and implementation-speak instead of user value. + +## The Solution + +`ce-promote` drafts the copy at ship time, from ship context: + +- **Derives what shipped** from a free-form description, or from the merged PR, the diff, the changelog, and recent commits — then summarizes the *user-facing value*, not the code. +- **Picks channels** sensibly (an X post + a changelog blurb by default) and scales to what the user asks for and what the change warrants. +- **Drafts voice-matched copy via Spiral** when ready; when not, offers setup once (sign in or install), and on a decline draws on a lite layer of editorial & social-media fundamentals to draft strong channel-specific copy on its own. +- **Presents drafts for review** — copy-pasteable, labeled by channel, never posted. + +--- + +## What Makes It Novel + +### 1. Spiral as a subtle, optional enhancement — never a dependency + +Spiral is detected into three states (`which spiral` + `spiral auth status --json`): ready, installed-but-unauthed, or absent. When ready, drafts are voice-matched to the user's brand and persist to their Spiral account (each draft carries a web-app `url` for tweaking). When not ready, the skill offers setup **once** — if installed but unauthed the agent runs `spiral login` and shares the sign-in link (you approve in a browser — the API key never touches the agent); if absent it points to the one-step install command — and a decline is always fine: it falls back to a lite layer of editorial & social-media expertise to draft strong copy on its own, and records the opt-out so it never nags again. The skill is equally useful with or without Spiral. + +### 2. The multi-channel / cue-word gotcha is encoded + +Spiral's multi-channel behavior is phrasing-driven, not flag-driven, and it has a sharp edge the skill handles explicitly: + +- **N variations of one channel** → ask for "3 tweet options", *avoid* cue words (`campaign`, `across`, `multi-channel`, `everywhere`, `cross-post`), and pass `--num-drafts 3`. A stray cue word trips campaign mode and collapses output to a single draft, silently ignoring `--num-drafts`. +- **A real cross-channel set** → name the channels in the prompt; Spiral returns a set of drafts per channel — it decides the count, often several — and `--num-drafts` is ignored. One call produces the whole cross-channel set. + +### 3. Drafts only — posting is always human + +The skill never posts, schedules, publishes, commits, or opens a PR. Output is always review-ready drafts. This keeps a human in the loop for the one action that's outward-facing and hard to reverse. + +### 4. User value over implementation + +The "what shipped" summary describes what a user can now do and why they'd care — never the serializer or endpoint that made it possible. Direct drafting bans AI tells, throat-clearing, and hashtag spam, and matches length/tone to each channel. + +--- + +## Quick Example + +You merge a PR adding one-click CSV export. + +**Single-channel variations:** `/ce-promote 3 tweet options for the new one-click CSV export` → the skill summarizes the value, then (Spiral path) runs `spiral write "3 tweet options for one-click CSV export" --instant --num-drafts 3 --json` with no cue words, or (no-Spiral path) writes three distinct tweets directly. All three are presented as copy-pasteable blocks. + +**Cross-channel set:** `/ce-promote draft a launch across X, LinkedIn, and email` → (Spiral path) `spiral write "announcing one-click CSV export — a launch across X, LinkedIn, and email" --instant --json` returns a set of drafts per channel (Spiral decides the count); (no-Spiral path) the skill drafts one X post, one LinkedIn post, and one email directly. Every returned draft is labeled by channel and ready to copy. + +--- + +## When to Reach For It + +Reach for `ce-promote` when: + +- A feature just shipped and you want the announcement drafted before context fades +- You need cross-channel copy (tweet + LinkedIn + email) from one prompt +- You want voice-matched copy and have Spiral installed + +Skip it when: + +- Nothing user-facing shipped (internal refactor, CI-only, test-only) +- You only need internal release notes — use `/ce-release-notes` for plugin release history + +--- + +## Reference + +| Argument | Effect | +|----------|--------| +| _(empty)_ | Derives what shipped from PR/diff/changelog/commits; drafts the default channel set | +| `` | Free-form description of what shipped, used as the source of truth | +| `` | e.g., "a tweet thread and a LinkedIn post", "3 tweet options", "a launch across X, LinkedIn, and email" | + +Detailed Spiral CLI mechanics live in the skill's `references/spiral-cli.md`. + +--- + +## See Also + +- [`ce-release-notes`](./ce-release-notes.md) — internal release history of the plugin (different audience: developers, not end users) +- [`ce-demo-reel`](./ce-demo-reel.md) — capture visual evidence of a shipped feature for a PR (pairs well as the visual to accompany announcement copy) diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index c05571562..8ab2216da 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -57,6 +57,7 @@ The primary entry points for engineering work, invoked as slash commands. Detail | Skill | Description | |-------|-------------| | [`/ce-demo-reel`](../../docs/skills/ce-demo-reel.md) | Capture a visual demo reel (GIF demos, terminal recordings, screenshots) for PRs with project-type-aware tier selection | +| [`/ce-promote`](../../docs/skills/ce-promote.md) | Draft user-facing announcement copy for a shipped feature (X post, changelog blurb, LinkedIn, email); voice-matched via the Spiral CLI when installed, a lite layer of editorial & social expertise without it | | [`/ce-report-bug`](../../docs/skills/ce-report-bug.md) | Report a bug in the compound-engineering plugin | | [`/ce-resolve-pr-feedback`](../../docs/skills/ce-resolve-pr-feedback.md) | Resolve PR review feedback in parallel | | [`/ce-test-browser`](../../docs/skills/ce-test-browser.md) | Run browser tests on PR-affected pages | diff --git a/plugins/compound-engineering/skills/ce-promote/SKILL.md b/plugins/compound-engineering/skills/ce-promote/SKILL.md new file mode 100644 index 000000000..0177b9436 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-promote/SKILL.md @@ -0,0 +1,138 @@ +--- +name: ce-promote +description: "Draft user-facing announcement and marketing copy for a feature that just shipped — an X post or thread, a changelog blurb, a LinkedIn post, an email, a blog intro, or a short demo script. Spiral-agnostic by default; voice-matched via the Spiral CLI when it is installed and authed. Use when the user says 'promote this', 'draft the announcement', 'write the launch copy', 'market this feature', 'announce this feature', 'write the release tweet', or 'ce-promote'." +argument-hint: "[optional: what shipped and/or channels, e.g. 'a tweet thread and a LinkedIn post']" +--- + +# /ce-promote + +Turn a feature that just shipped into copy-pasteable, user-facing announcement copy — right inside the engineering workflow. + +## Purpose + +After you ship, the messaging shouldn't wait for a separate marketing pass. `ce-promote` figures out what shipped, picks the right channels, and drafts the copy. It is **spiral-agnostic by default**: with nothing installed it draws on a lite layer of editorial and social-media expertise to produce strong channel-specific copy. When the Spiral CLI (see `references/spiral-cli.md`) is present and authed, it uses Spiral so the drafts are voice-matched to your brand — a subtle enhancement, never a requirement. + +**This skill drafts only. It never posts, publishes, commits, or opens PRs.** Posting is a human action. The output is always drafts for you to review, edit, and ship yourself. + +## Usage + +```bash +/ce-promote # Derive what shipped from context, draft defaults +/ce-promote [free-form description] # You describe what shipped +/ce-promote a tweet thread and a LinkedIn post # Request specific channels +/ce-promote 3 tweet options for the new export feature +``` + +## Phase 1 — Figure out what shipped + +If the user gave a free-form description of the feature, use it as the source of truth. + +Otherwise, derive it from context (use what's available; don't block on any one source): + +- **Merged/active PR** — `gh pr view --json title,body,url 2>/dev/null` (and `gh pr view` for the current branch). The title and body usually state the user-facing value. +- **The diff** — `git diff main...HEAD --stat` and skim notable changes to ground the claim in what actually changed. +- **Changelog** — the top/`[Unreleased]` entry in `docs/changelog.md`, `CHANGELOG.md`, or similar. +- **Recent commits** — `git log --oneline -15` for the arc of the change. + +Then write a 1–3 sentence summary of the **user-facing value** — what a user can now do that they couldn't before, and why they'd care. Describe the outcome, not the implementation. ("You can now export any report to CSV in one click" — not "Added a CsvSerializer and an export endpoint.") + +If you can't confidently tell what shipped, ask the user one short question rather than guessing. + +## Phase 2 — Pick channels + +Default to a small, sensible set: + +- **An X post or short thread** (lead with the value; thread only if the change warrants it) +- **A one-line changelog / release blurb** + +Scale to what the change warrants and to what the user asked for. If they named channels ("LinkedIn", "email", "a blog intro", "a short demo script"), draft those instead of or in addition to the defaults. A small fix needs one or two short drafts; a flagship feature can justify a cross-channel set. Don't force a fixed template. + +## Phase 3 — Draft the copy + +First, detect Spiral's state with two quick, non-blocking commands: + +```bash +which spiral +spiral auth status --json 2>/dev/null +``` + +Classify into one of three states: + +- **Absent** (no binary, `which spiral` finds nothing) → **Path 0** (install), then Path A if set up, else **Path B**. +- Otherwise read `spiral auth status --json`: + - **Ready** — JSON with `"authenticated": true` (equivalently `"status": "authenticated"`) → **Path A** (voice-matched). + - **Unauthed** — JSON with `"authenticated": false` → **Path 0**, then Path A if the user signs in, else **Path B**. + - If the output isn't JSON (older CLI that ignores `--json` on `auth status`), fall back to the legacy signal in that same output: **ready** iff it contains `spiral_sk_`, else **unauthed**. + +Never let a Spiral failure, timeout, or odd output block or slow the skill — when in doubt, treat it as not-ready and continue. + +### Path 0 — Offer Spiral setup (first run, declinable) + +When Spiral isn't ready, offer to set it up **once** — unless the user previously opted out. The point is one proactive nudge, never a recurring one, and never a blocker: a decline always proceeds to Path B. **Any dismissal records the opt-out**, so a single first-run decline stops the offer for good in this repo — the user is never asked twice. + +Read `references/spiral-cli.md` for the exact setup prompt (built with the platform's blocking-question tool), the connect/install steps, and how the opt-out is recorded so later runs skip this. In short: + +- **Unauthed** → the agent runs `spiral login --json` (CLI >= 1.8.0; non-blocking, the API key never passes through the agent). On `status: already_authenticated` → use Path A. On `status: pending` → surface the `auth_url`, the user approves in their browser, then poll `spiral auth status --json` until `authenticated: true` → Path A. Never have the user paste a key into chat. (Older CLI without agent login → suggest `npm i -g @every-env/spiral-cli@latest`, or have the user run `spiral login` themselves.) Escape hatch: "or the agent can just draft directly, without Spiral's personalization and humanization." +- **Absent** → guide the user to install + connect in one step via the pairing-code command from Settings → Connect an Agent. +- **Decline** → record the opt-out (best-effort) and go to Path B. + +Skip Path 0 entirely — straight to Path B — when the opt-out is already recorded, or when running headless / non-interactive (no human to answer). If a human is present but no blocking-question tool is available, do **not** skip — fall back to a numbered list of the two options in chat and wait for a reply (per the Ask section of `references/spiral-cli.md`). + +### Path A — Spiral ready (voice-matched) + +Use the Spiral CLI so drafts match the user's brand voice. **Read `references/spiral-cli.md` before composing the prompt** — multi-channel vs. single-channel-variations is phrasing-driven (channel keywords / cue words vs. `--num-drafts`) and getting it wrong silently returns the wrong number or shape of drafts. The exact phrasing rules live there; don't restate them from memory. Essentials: + +- Always pass `--instant` and `--json`. Parse `drafts[]` (each carries its own `channel`) plus `session_id`. +- **Present every returned draft, grouped by `channel`.** Spiral decides how many drafts per channel — multi-channel runs often return several per channel — so never assume one-per-channel or drop extras. + +If the `spiral write` call errors or returns no usable drafts, silently fall back to Path B for the affected channels. + +### Path B — Direct drafting (lite editorial & social expertise) + +No Spiral needed — draft strong copy directly using a compact layer of editorial and social-media fundamentals. (The Spiral path goes further: brand-voice matching, humanization, saved styles, and cross-channel campaign orchestration.) + +**Editorial fundamentals** — every channel: +- Lead with the user-facing outcome: what someone can now do, not how it was built. +- One idea per piece. Cut windup, hedges, and throat-clearing. +- Be concrete and specific; show the value, don't assert it. +- Plain, active language. Strip AI tells — "thrilled/excited to announce," "game-changer," "in today's fast-paced world," "unlock/leverage/seamless," em-dash padding. +- Sanity check: read it as if saying it to one user. If a person wouldn't say it, rewrite it. + +**Social fundamentals** — distributed channels: +- The first line is the hook and has to earn the next line (feeds truncate). No preamble. +- Match each channel's native shape and length; never reuse one draft verbatim across channels. +- One clear CTA where the channel supports it. +- Hashtags: 0–2, only where the channel expects them — never a wall of tags. + +**Per channel:** +- **X** — value in the first line; ~1–3 tight lines. Thread only when there's more than one beat worth its own line. +- **Changelog / release blurb** — one declarative line naming the new capability. Plain, not promotional. +- **LinkedIn** — a short paragraph: human angle (why it matters), then the what. Warmer than X. +- **Email** — benefit-stating subject + 2–4 sentence body + one CTA. +- **Blog intro** — one strong opening paragraph framing the problem and the new capability; leave the deep-dive to the author. +- **Demo script** — 3–6 spoken beats: hook, problem, action, payoff. + +**Drafts per channel:** one strong draft by default; produce more only when asked ("3 tweet options"), capped ~3. + +## Phase 4 — Present the drafts + +Show every draft as a clean, copy-pasteable block, labeled by channel. For each: + +``` +### X post + +``` + +- If Spiral produced them, also surface the `session_id` and each draft's `url` so the user can open and tweak them in the Spiral web app. +- Offer to revise (tone, length, angle, more variations, another channel). +- **Do not post, publish, schedule, commit, or open a PR.** End by reminding the user the drafts are theirs to ship. + +## Examples + +**Single-channel variations — "3 tweet options":** +> User: `/ce-promote 3 tweet options for the new one-click CSV export` +> → Summarize the value. Spiral path: `spiral write "3 tweet options for one-click CSV export" --instant --num-drafts 3 --json` (no cue words). No-Spiral path: write 3 distinct tweets directly. Present all three. + +**Multi-channel set — "a campaign across X, LinkedIn, and email":** +> User: `/ce-promote draft a launch across X, LinkedIn, and email` +> → Spiral path: `spiral write "announcing one-click CSV export — a launch across X, LinkedIn, and email" --instant --json` returns a set of drafts per channel (Spiral decides the count — often several), each carrying its `channel`. (`--num-drafts` ignored here.) No-Spiral path: draft one X post, one LinkedIn post, one email directly. Present every returned draft, grouped by channel. diff --git a/plugins/compound-engineering/skills/ce-promote/references/spiral-cli.md b/plugins/compound-engineering/skills/ce-promote/references/spiral-cli.md new file mode 100644 index 000000000..004f7b793 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-promote/references/spiral-cli.md @@ -0,0 +1,147 @@ +# Spiral CLI reference + +Spiral (`@every-env/spiral-cli`) drafts copy in a user's brand voice. `ce-promote` uses it as an **optional enhancement** — every call must be wrapped so a missing, unauthed, or erroring CLI never blocks the skill. + +## Detection — three states + +```bash +which spiral +spiral auth status --json 2>/dev/null +``` + +- **Absent** — `which spiral` finds nothing. → Path 0 (offer to install + connect). +- Otherwise parse `spiral auth status --json`: + - **Ready** — `"authenticated": true` (equivalently `"status": "authenticated"`, any `source`). Use Path A. + - **Unauthed** — `"authenticated": false`. → Path 0 (offer to sign in). + - **Older CLI** that ignores `--json` (output isn't JSON): fall back to the human-readable signal in that same output — ready iff it contains `spiral_sk_`, else unauthed. + +Prefer the JSON `authenticated` flag over substring-matching `spiral_sk_` — the flag is the designed contract, and the substring is only the backward-compat fallback. Any error or timeout → treat as not-ready and continue; never block. + +## Path 0 — Offer setup (first run, declinable) + +When Spiral is unauthed or absent, offer setup once. First check the opt-out so this never nags. + +### Check the opt-out + +Read the project config (resolve the repo root, never CWD): + +```bash +cat "$(git rev-parse --show-toplevel 2>/dev/null)/.compound-engineering/config.local.yaml" 2>/dev/null || echo '__NO_CONFIG__' +``` + +If the contents have an **uncommented** top-level `ce_promote_spiral_optout: true` line, **skip Path 0** and go straight to Path B. **Ignore commented lines** — `ce-setup`'s template ships a `# ce_promote_spiral_optout: true` example, and a commented line is documentation, not an opt-out (a naive substring match would wrongly suppress the offer for any project that accepted the default template). Otherwise, offer setup. + +### Ask + +Use the platform's blocking-question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini / Pi. If no blocking tool exists or the call errors, present the same options as a numbered list in chat and wait for a reply — never silently skip. + +For the **unauthed** state, the **agent itself** runs `spiral login --json` (CLI >= 1.8.0): it's non-blocking and the API key never passes through the agent — the agent shares the returned `auth_url`, the user approves in a browser, and the credential is delivered server->CLI. The blocking question is mainly the escape hatch. + +Use the question stem to teach the mechanic, offer the escape hatch, AND disclose that declining is durable (so the permanent side effect isn't hidden behind a transient-sounding label): "Spiral personalizes and humanizes the copy in your voice. [It's installed but not signed in / It isn't installed yet] — sign in now, or have the agent draft directly without Spiral? (Declining drafts your copy now and won't bring up Spiral again in this project; you can set it up anytime by asking.)" + +Offer exactly **two** options (labels must be self-contained): + +- **Unauthed** state: `Sign in to Spiral` · `Draft directly without Spiral` +- **Absent** state: `Install Spiral` · `Draft directly without Spiral` + +There is deliberately no separate "don't ask again" option: **dismissing is itself the opt-out.** A single first-run decline records the flag and the offer never recurs in this repo. This is what keeps a per-ship skill from nagging — never make the user choose a special variant to stop being asked. + +### Act on the choice + +- **Sign in to Spiral** (installed, unauthed) — the agent runs `spiral login --json` itself. It's non-blocking, and the **API key never touches the agent** (the token is exchanged server->CLI via a device-code flow). Parse the JSON `status`: + - `already_authenticated` — `{ "authenticated": true, "status": "already_authenticated", "prefix": "..." }`: a credential already exists; nothing to approve. Go to Path A. (To switch accounts the user runs `spiral logout` first.) + - `pending` — `{ "status": "pending", "auth_url": "...", "user_code": "ABCD-2345", "expires_in": 900 }`: surface the `auth_url` for the user to open and approve in their browser (the `user_code` is embedded in the URL — show it too so they can confirm it matches), then wait. Once the user says they've approved, confirm by running `spiral auth status --json`: it returns `"authenticated": true` when claimed, or `"status": "pending"` if not yet (re-check, don't busy-loop with sleeps — let the user's confirmation drive the re-check). If it stays unclaimed or the code expires (~`expires_in`s), offer to retry or fall to Path B. On success -> Path A. + - **Never have the user paste an API key into chat** — with agent login the agent never handles the key at all. + - **Older CLI (< 1.8.0, no agent login):** if `spiral login --json` returns the legacy `API key required ... --token` text instead of JSON, suggest `npm i -g @every-env/spiral-cli@latest`, or have the user run `spiral login` themselves in their terminal (browser sign-in) and re-check `spiral auth status`. If they would rather not, go to Path B. +- **Install Spiral** (absent) — the pairing-code command installs and connects in one step. Direct the user to Settings → Connect an Agent at https://app.writewithspiral.com to copy their command, which looks like: + ```bash + npx @every-env/spiral-cli@latest setup --pairing-code + ``` + The pairing code is single-use and expires in ~15 minutes, so the user must fetch a fresh one from the web app — do not hardcode it. Once installed, if still unauthed, follow the **Sign in to Spiral** flow above (`spiral login --json`). If the user can't or won't install, go to Path B. +- **Draft directly without Spiral** — record the opt-out (below) so the offer never re-prompts in this repo, then go to Path B. (A failed/abandoned **sign-in or install** attempt does NOT record the opt-out — only an explicit "draft directly" dismissal does — so a user whose auth didn't complete still gets one clean re-offer next run.) + +### Record the opt-out (best-effort) + +Resolve the repo root, then add `ce_promote_spiral_optout: true` as a top-level key to `/.compound-engineering/config.local.yaml`, using the native file-write/edit tool: + +- **File already exists:** ensure an **uncommented** `ce_promote_spiral_optout: true` line is present — add one (or uncomment the example) unless an uncommented one already exists. A commented `# ce_promote_spiral_optout: true` (from `ce-setup`'s template) does **not** count as present; leaving only the comment would let the comment-ignoring read path re-prompt next run. +- **File absent:** create it (and its `.compound-engineering/` directory) with the key, AND make sure the machine-local config won't be committed. Check whether the root-relative path `/.compound-engineering/config.local.yaml` is already ignored (`git check-ignore -q `); if it isn't, append `.compound-engineering/*.local.yaml` to git's **local exclude file** — resolve that file's path with `git rev-parse --git-path info/exclude` (this is correct in worktrees too, where `.git` is a *file* and `info/exclude` lives in the common git dir; do **not** hardcode `/.git/info/exclude`). Use the local exclude, **not** `.gitignore`: it keeps the rule local and avoids dirtying a tracked file on what was a drafts-only action. `ce-setup` is the canonical place that adds the shared `.gitignore` entry for teammates. Without any ignore, a user who runs `/ce-promote` before `/ce-setup` could accidentally commit machine-local opt-out state. + +If the root can't be resolved or any write fails, proceed to Path B anyway; the opt-out is a convenience, never a blocker. + +After recording, confirm it in one line so the write isn't silent and the user knows how to undo it — e.g. "Got it — I won't bring up Spiral here again (saved to `.compound-engineering/config.local.yaml`, kept out of git). Want it back later? Just ask, or remove the `ce_promote_spiral_optout` key." Keep it to a single line; don't belabor it. + +## Generate + +```bash +spiral write "" --instant --num-drafts <1-5> --json +``` + +- `--instant` — skip clarifying questions. **Always use it**; this is a headless context with no human mid-call. +- `--json` — machine-readable output. Always use it. +- `--num-drafts <1-5>` — number of drafts (single-channel mode only; see gotcha). +- `--workspace ` — scope to a brand-voice workspace. List with `spiral workspaces`. Use only if the user names one. +- `--style ` — pin a specific voice/style. Use only if the user names one. + +### Output shape + +JSON with (fields verified against the Spiral CLI `write` output): + +```json +{ + "session_id": "uuid", + "status": "complete | needs_input", + "drafts": [ + { "id": "uuid", "title": "...", "content": "markdown", "channel": "x", + "url": "https://app.writewithspiral.com/chat/?draft=", "display_hint": "inline | expandable" } + ], + "text": "pipeline commentary — DO NOT show the user unless drafts is empty", + "style_used": null, + "quota_remaining": 42 +} +``` + +- `channel` (lowercase) is one of `x`, `linkedin`, `email`, `newsletter`, `blog`, `instagram_tiktok`, `research`, or `null`. +- `url` opens that draft in the Spiral web app for editing. Drafts persist to the user's account — surface `session_id` + each `url` in your output (Phase 4). +- **Do not surface the `text` field** to the user — it's internal pipeline commentary. Only fall back to it if `drafts` is empty. +- With `--instant`, `status` should be `complete`. If it comes back `needs_input` (rare with `--instant`), don't relay Spiral's questions to the user — either answer from the context you already have via a `--session` follow-up, or fall back to Path B for that channel. + +If parsing fails or `drafts` is empty, fall back to direct drafting for the affected channels. + +## The multi-channel / cue-word gotcha (important) + +Multi-channel output is **phrasing-driven, not a flag.** Spiral enters "campaign mode" when the prompt contains **≥2 channel keywords** (tweet/X, LinkedIn, email, blog, …) **OR** any cue word: `campaign`, `across`, `multi-channel`, `everywhere`, `cross-post`. + +Two consequences to encode: + +### (a) To get N variations of ONE channel + +Ask for `"3 tweet options for "` and: + +- **Avoid** the cue words above. Ironically, a prompt literally containing `campaign` or `multi-channel` trips campaign mode — so describe the task **without** those words. +- Pass `--num-drafts 3`. + +If you accidentally include a cue word, Spiral decides it's a single campaign piece and returns **1 draft**, ignoring `--num-drafts`. + +✅ `spiral write "3 tweet options for one-click CSV export" --instant --num-drafts 3 --json` +❌ `spiral write "a tweet campaign for CSV export" --instant --num-drafts 3 --json` (collapses to 1 draft) + +### (b) To get a real multi-channel set + +Phrase the prompt with the multiple channels named. Spiral returns **one set of drafts per channel**, each draft carrying its `channel`. In this mode **`--num-drafts` is ignored** — per-channel counts apply. + +✅ `spiral write "announcing one-click CSV export — a tweet and a LinkedIn post" --instant --json` +✅ `spiral write "a campaign across email, LinkedIn, and Twitter for CSV export" --instant --json` + +This one-call cross-channel set is the ideal fit for `ce-promote` when the user wants to announce across surfaces. + +**Spiral picks per-channel counts itself.** In campaign mode the count per channel is Spiral's call, not yours — e.g. "a tweet and a LinkedIn post" (verified live) returned 3 X drafts + 2 LinkedIn drafts (5 total), each tagged with its `channel`. Group the returned `drafts` by `channel` for Phase 4; don't assume one per channel. + +## Failure handling + +Detection that comes back not-ready routes through Path 0 above. Once on Path A, any of these → fall back to direct drafting (SKILL.md Path B), silently, for the affected channels: + +- `spiral write` exits non-zero, hangs, or emits non-JSON +- `drafts` is empty or missing expected fields + +Never surface raw Spiral errors to the user as a blocker. The skill always produces drafts. diff --git a/plugins/compound-engineering/skills/ce-setup/references/config-template.yaml b/plugins/compound-engineering/skills/ce-setup/references/config-template.yaml index b494006f0..822cc432c 100644 --- a/plugins/compound-engineering/skills/ce-setup/references/config-template.yaml +++ b/plugins/compound-engineering/skills/ce-setup/references/config-template.yaml @@ -40,3 +40,9 @@ # plan_output: html # md | html (default: md) # brainstorm_output: html # md | html (default: md) + +# --- ce-promote --- +# Written automatically when you decline the Spiral setup offer in /ce-promote. +# Suppresses that one-time setup nudge in this project. Remove the key to re-enable. + +# ce_promote_spiral_optout: true # true | (absent) (default: absent -- offer once)