@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/social-distribute/SKILL.md

@@ -0,0 +1,485 @@
+---
+name: social-distribute
+description: "This skill should be used when distributing a blog article across social platforms (Discord, X/Twitter, IndieHackers, Reddit, Hacker News, LinkedIn). Writes a persistent content file for automated publishing."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Social Distribute
+
+Generate platform-specific content variants from a blog article and write them to a persistent content file for the automated publishing pipeline. Discord can optionally be posted immediately via webhook after approval. The content file feeds into the directory-driven cron pipeline (`content-publisher.sh`) for scheduled publishing.
+
+## Headless Mode Detection
+
+If `$ARGUMENTS` contains `--headless`, set `HEADLESS_MODE=true` and strip `--headless` from `$ARGUMENTS`. The remainder is the blog post path.
+
+**Argument format:** `<blog-post-path> [--headless]`
+
+**Headless defaults for interactive gates:**
+
+- Phase 7 (Discord Approval): auto-selects **Skip** (never auto-post to external platforms without human approval). `channels` is always `discord, x, bluesky, linkedin-company`.
+- Phase 9 Step 2 (Overwrite Check): auto-selects **Overwrite** (content is regenerated from the same blog post, so overwriting is idempotent).
+
+## Prerequisites
+
+Before generating content, verify all prerequisites. If a hard prerequisite fails, display the error message and stop. Soft prerequisites display a warning and continue.
+
+### 1. Brand Guide (hard)
+
+Check if `knowledge-base/marketing/brand-guide.md` exists.
+
+**If missing:**
+> No brand guide found. Run the brand architect agent first to establish brand identity:
+> `Use the soleur:marketing:brand-architect agent to define our brand.`
+
+Stop execution.
+
+### 2. Blog Post Path (hard)
+
+The skill expects a blog post path as an argument (e.g., `soleur:social-distribute plugins/soleur/docs/blog/my-article.md`).
+
+**If no path provided or file does not exist:**
+> Provide a path to a blog post markdown file:
+> `soleur:social-distribute <path-to-blog-post.md>`
+
+Stop execution.
+
+### 3. Discord Webhook URL (soft)
+
+Check if `DISCORD_BLOG_WEBHOOK_URL` or `DISCORD_WEBHOOK_URL` environment variable is set.
+
+**If both missing:**
+> Neither `DISCORD_BLOG_WEBHOOK_URL` nor `DISCORD_WEBHOOK_URL` is set. Discord posting will be skipped (manual output only).
+> To configure: Server Settings > Integrations > Webhooks > Copy URL from the #blog channel > `export DISCORD_BLOG_WEBHOOK_URL="..."`
+
+Continue execution -- Discord will be included in the content file's `channels` field for cron publishing instead of immediate webhook posting.
+
+## Content Input
+
+### Phase 1: Read Blog Post
+
+1. Read the blog post markdown file at the provided path
+2. Parse YAML frontmatter to extract: `title`, `description`, `date`, `tags`
+
+### Phase 2: Gather Current Stats
+
+Run these shell commands to get current component counts:
+
+```bash
+# Count agents (recursive .md files under agents/)
+find plugins/soleur/agents -name '*.md' | wc -l
+
+# Count skills (directories with SKILL.md)
+find plugins/soleur/skills -maxdepth 2 -name 'SKILL.md' | wc -l
+
+# Count commands
+ls plugins/soleur/commands/*.md | wc -l
+
+# Count departments (non-empty top-level dirs under agents/)
+find plugins/soleur/agents -mindepth 1 -maxdepth 1 -type d | wc -l
+
+# Get site URL
+cat plugins/soleur/docs/_data/site.json
+```
+
+Extract: `agents` count, `skills` count, `commands` count, `departments` count, `site.url`.
+
+### Phase 3: Build Article URL
+
+Construct the article URL from `site.url` and the blog post path:
+
+- Strip `plugins/soleur/docs/` prefix from the path
+- Replace `.md` extension with `/`
+- Strip any leading `YYYY-MM-DD-` date prefix from the filename portion of the path (regex: `/\d{4}-\d{2}-\d{2}-(.*)/`). Eleventy's `page.fileSlug` strips this prefix, so URLs must match. If no date prefix exists, leave the path unchanged.
+- Prepend `site.url`
+
+Example: `plugins/soleur/docs/blog/2026-03-24-vibe-coding-vs-agentic-engineering.md` becomes `https://soleur.ai/blog/vibe-coding-vs-agentic-engineering/`
+
+**UTM Tracking:** Derive the campaign slug from the article URL path — strip `/blog/` prefix and trailing `/`. Example: `/blog/caas-pillar/` → `caas-pillar`. If the slug contains characters other than `a-z`, `0-9`, hyphens, or underscores, replace them with hyphens.
+
+Construct platform-specific tracked URLs using this mapping:
+
+| Platform | Tracked URL |
+|----------|------------|
+| Discord | `<base-url>?utm_source=discord&utm_medium=community&utm_campaign=<slug>` |
+| X/Twitter | `<base-url>?utm_source=x&utm_medium=social&utm_campaign=<slug>` |
+| IndieHackers | `<base-url>?utm_source=indiehackers&utm_medium=community&utm_campaign=<slug>` |
+| Reddit | `<base-url>?utm_source=reddit` |
+| Hacker News | `<base-url>?utm_source=hackernews&utm_medium=community&utm_campaign=<slug>` |
+| LinkedIn Personal | `<base-url>?utm_source=linkedin-personal&utm_medium=social&utm_campaign=<slug>` |
+| LinkedIn Company Page | `<base-url>?utm_source=linkedin-company&utm_medium=social&utm_campaign=<slug>` |
+| Bluesky | `<base-url>?utm_source=bluesky&utm_medium=social&utm_campaign=<slug>` |
+
+Reddit gets minimal UTM parameters (`utm_source` only) to reduce spam filter risk — long marketing-looking URLs can trigger irreversible domain reputation damage on Reddit.
+
+Use each platform's tracked URL in the corresponding Phase 5 variant section instead of the bare base URL.
+
+## Content Generation
+
+### Phase 4: Read Brand Guide
+
+Read the brand guide sections that inform content generation:
+
+1. Read `## Voice` -- apply brand voice, tone, do's and don'ts
+2. Read `## Channel Notes > ### Discord` -- apply Discord-specific guidelines
+3. Read `## Channel Notes > ### X/Twitter` -- apply X/Twitter-specific guidelines
+4. Read `## Channel Notes > ### LinkedIn Personal` -- apply LinkedIn personal profile guidelines
+5. Read `## Channel Notes > ### LinkedIn Company Page` -- apply LinkedIn company page guidelines
+6. Read `## Channel Notes > ### Blog` and `### Hacker News` -- apply any rule they set for distributing a blog post (for example, not submitting it to Hacker News as-is)
+
+If a channel notes section is missing for a platform, generate content using only the `## Voice` section.
+
+### Phase 5: Generate All Variants
+
+Using the blog post content, stats values, article URL, and brand guide as context, generate all platform-specific variants. The LLM handles template variable substitution (replace `{{ stats.agents }}` with actual counts), markup stripping (ignore JSON-LD, HTML tags, FAQ accordions), and content adaptation per platform.
+
+**Important:** Every variant must contain resolved numbers, not template syntax like `{{ stats.agents }}`. Use the stats gathered in Phase 2.
+
+**Lead with the differentiating hook, not the source.** For a news-hook / response post (adopting an external term, reacting to an essay or announcement), open EACH variant with the strongest claim about *what is unique here* — credit the source immediately after, but never bury the original contribution under the news peg. The previews readers actually see — X tweet 1, the LinkedIn first line (shown before "see more"), the Bluesky opener, the Discord first line — must carry the differentiator. **Keep that opening hook consistent across all channels** for campaign cohesion. **Why (#5088):** the first loop-engineering draft opened every variant with "Addy Osmani coined…" and buried Soleur's cross-domain expansion in paragraph 3; the operator rewrote all four to lead with the founder-vs-engineer differentiator ("loop engineering replaced the engineer who prompts the coding agent; Soleur replaces the founder who prompts every department").
+
+#### 5.1 Discord Announcement
+
+- Maximum 2000 characters (UTM-tagged URLs are ~60-80 chars longer than bare URLs — account for this in the character budget)
+- Include Discord tracked URL
+- Match brand voice from `## Voice` and `## Channel Notes > ### Discord`
+- Plain text only (no rich embeds)
+- Declarative, concrete, builder-to-builder tone
+
+#### 5.2 X/Twitter Thread
+
+- Hook tweet (standalone value, no "thread" announcement)
+- Numbered body tweets (2/ 3/ 4/)
+- Final tweet with X/Twitter tracked URL and up to one hashtag
+- Each tweet maximum 280 characters
+- Match brand voice from `## Voice` and `## Channel Notes > ### X/Twitter`
+- Links only in final tweet
+- No emojis in hook tweet
+
+#### 5.3 IndieHackers Building Update
+
+- Markdown format
+- Transparent metrics and numbers
+- Building-in-public framing
+- Include IndieHackers tracked URL
+- Honest, first-person builder voice
+
+#### 5.4 Reddit Post
+
+- Subreddit-appropriate framing (suggest target subreddits: r/SaaS, r/startups, r/solopreneur, r/artificial)
+- Non-promotional title and body
+- Value-first: lead with the insight, not the product
+- Include Reddit tracked URL naturally in context, not as a CTA (minimal UTM: `?utm_source=reddit` only)
+- Reddit detects and punishes self-promotion -- frame as sharing knowledge
+
+#### 5.5 Hacker News Submission
+
+If the brand guide's `### Blog` or `### Hacker News` note says not to submit blog posts to Hacker News as-is, write the section as a one-line note instead: point to the post's technical write-up if the post links one, otherwise say HN is skipped for this post.
+
+- Title maximum 80 characters
+- No marketing language, no ALL CAPS, no exclamation marks
+- Factual, understated, curiosity-driven
+- Format: `Title | Hacker News tracked URL`
+- HN titles that work: questions, counterintuitive claims, concrete results
+
+#### 5.6 LinkedIn Personal
+
+- Thought-leadership framing: case studies, reflections, lessons learned
+- First-person, authentic founder voice ("I built..." not "We launched...")
+- Aim for ~1,300 characters (optimal organic visibility), max 3,000
+- Professional but not corporate -- substantive, measured, and direct
+- Match brand voice from `## Voice` and `## Channel Notes > ### LinkedIn Personal`
+- Hook-first: opening line must deliver a complete, compelling idea that works in the feed preview
+- Include LinkedIn Personal tracked URL naturally in context, not as a standalone CTA
+- One or two relevant hashtags maximum (#solofounder, #buildinpublic, #AIagents)
+- No promotional framing -- "Here's what I learned building X" outperforms "Check out our new feature Y"
+- Tuesday-Thursday mornings perform best (note in content, not enforced)
+- Section heading: `## LinkedIn Personal`
+
+#### 5.7 LinkedIn Company Page
+
+- Official announcement tone, third-person company voice ("Soleur now supports...")
+- ~1,300 chars optimal, max 3,000
+- Professional framing: product updates, feature announcements, milestones
+- Match brand voice from `## Voice` and `## Channel Notes > ### LinkedIn Company Page`
+- Include LinkedIn Company Page tracked URL naturally in context
+- Minimal hashtags (1-2 max)
+- Section heading: `## LinkedIn Company Page`
+
+#### 5.8 Bluesky Post
+
+- Maximum 300 characters (grapheme count; Bluesky uses codepoint counting as approximation)
+- Standalone value post (no threads -- single posts perform better for distribution)
+- Match brand voice from `## Voice`
+- Include Bluesky tracked URL
+- No hashtags (Bluesky has no hashtag discovery)
+- Conversational, direct tone suited to the developer/indie community
+- Note: URLs will render as plain text (facet support for clickable links is a future enhancement)
+- Section heading: `## Bluesky`
+
+## Approval Flow
+
+### Phase 5.5: Marker Validation (hard gate)
+
+Before presenting variants (Phase 6), scan every generated section for unresolved Liquid/Jinja template markers: `{{`, `}}`, `{%`, `%}`.
+
+You MUST run the committed linter on the assembled variant text (write it to a temp file with a minimal `---\n---\n` frontmatter preamble, then `bash scripts/lint-distribution-content.sh <tmpfile>`). Do NOT substitute an LLM visual inspection — the rule is "delegate to the deterministic tool that `lefthook` and `content-publisher.sh` both enforce against." Exit code 0 means clean; exit 1 means markers found.
+
+**Procedure:**
+
+1. Assemble each generated variant into a `tmpfile` with a minimal frontmatter preamble.
+2. Run `bash scripts/lint-distribution-content.sh <tmpfile>`.
+3. If exit 1, do NOT proceed to Phase 6. Regenerate the offending section with explicit substitution of `site.url` (resolved value: `https://soleur.ai`) and any `{{ stats.* }}` placeholders using Phase 2 values. Re-run the linter against the new output.
+4. If the re-generation still produces markers, STOP and surface to the user: "Auto-regeneration did not resolve Liquid markers -- manual intervention required." Do not loop further.
+
+Template markers in distribution content files are always a bug.
+
+### Phase 6: Present All Variants
+
+Display all variants in a summary view with clear headers and character counts:
+
+```
+## Discord (1847/2000 chars)
+[content]
+
+## X/Twitter Thread (4 tweets)
+[tweet 1] (267/280 chars)
+[tweet 2] (243/280 chars)
+...
+
+## IndieHackers
+[content]
+
+## Reddit
+Suggested subreddits: r/SaaS, r/startups
+[title]
+[body]
+
+## Hacker News
+[title] (72/80 chars)
+[url]
+
+## LinkedIn Personal (1247/1300 optimal, 1247/3000 max)
+[content]
+
+## LinkedIn Company Page (1247/1300 optimal, 1247/3000 max)
+[content]
+
+## Bluesky (287/300 chars)
+[content]
+```
+
+### Phase 7: Discord Approval
+
+**If `HEADLESS_MODE=true`:** auto-select **Skip**. Discord is deferred to the content file for cron publishing.
+
+**If `DISCORD_BLOG_WEBHOOK_URL` or `DISCORD_WEBHOOK_URL` is set:**
+
+Use the **AskUserQuestion tool** with three options:
+
+- **Accept** -- Post this content to Discord
+- **Edit** -- Provide feedback to revise the Discord variant (regenerate with feedback, re-present)
+- **Skip** -- Skip Discord posting, include Discord in content file's `channels` field for cron publishing
+
+**If neither is set:**
+
+Skip this phase. Discord will be included in the content file's `channels` field for cron publishing.
+
+## Posting
+
+### Phase 8: Post to Discord (conditional)
+
+**This phase only runs if the user accepted Discord posting in Phase 7.** If the user skipped Discord or no webhook URL is set, skip to Phase 9.
+
+On acceptance, post the Discord content via webhook.
+
+First get the webhook URL with `printenv DISCORD_BLOG_WEBHOOK_URL || printenv DISCORD_WEBHOOK_URL`, then use the literal URL:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" \
+  -H "Content-Type: application/json" \
+  -d "{\"content\": \"ESCAPED_CONTENT\", \"username\": \"Sol\", \"avatar_url\": \"AVATAR_URL\", \"allowed_mentions\": {\"parse\": []}}" \
+  "<webhook-url>"
+```
+
+Replace `<webhook-url>` with the actual URL from `printenv`.
+
+Set `avatar_url` to the hosted logo URL (e.g., the GitHub-hosted `logo-mark-512.png`). Webhook messages freeze author identity at post time -- these fields ensure consistent branding.
+
+**Content must be properly JSON-escaped** before inserting into the payload. Escape double quotes, backslashes, and newlines.
+
+**Payload format:** Plain `content` field only. No rich embeds.
+
+**On success (HTTP 2xx):**
+> Posted to Discord successfully.
+
+Track that Discord was posted successfully -- this affects the `channels` field in Phase 9.
+
+**On failure (HTTP 4xx/5xx):**
+> Failed to post to Discord (HTTP [status_code]).
+>
+> Draft content (copy-paste manually):
+>
+> ```
+> [full draft content]
+> ```
+
+Display the draft so the user can post it manually. Do not retry automatically. Treat a failed post as "Discord not posted" for Phase 9's `channels` field.
+
+## Content File Output
+
+### Phase 9: Write Content File
+
+After content generation and approval, write a persistent content file for the directory-driven publishing pipeline.
+
+**Step 1: Derive slug and output path**
+
+Derive the slug from the blog post filename: strip path, strip `.md`, keep kebab-case.
+
+Example: `plugins/soleur/docs/blog/why-most-agentic-tools-plateau.md` → `why-most-agentic-tools-plateau`
+
+Output path: `knowledge-base/marketing/distribution-content/<slug>.md`
+
+**Step 2: Check for existing file**
+
+Check for an existing content file matching this slug. The check must account for both slug-only filenames and legacy numeric-prefixed filenames:
+
+```bash
+ls knowledge-base/marketing/distribution-content/*<slug>.md 2>/dev/null
+```
+
+If a match is found (either `<slug>.md` or `NN-<slug>.md`), use the matched filename as the output path (preserving the existing naming convention).
+
+**If `HEADLESS_MODE=true`:** auto-select **Overwrite** and continue.
+
+**If interactive and a file exists**, use the **AskUserQuestion tool**:
+
+- **Overwrite** -- Replace the existing file with new content
+- **Cancel** -- Abort file writing and stop. The user can rename or delete the existing file, then re-run.
+
+**Step 3: Determine channels field**
+
+- If Discord was posted successfully in Phase 8: set `channels: x, bluesky, linkedin-company` (Discord already done)
+- If Discord was skipped, failed, or no webhook configured: set `channels: discord, x, bluesky, linkedin-company`
+
+**Step 4: Write the content file**
+
+Write the file with YAML frontmatter and a section per platform. Use the blog post's frontmatter `title` for the content file title. If the blog post has no frontmatter title, fall back to the first H1 heading or the filename.
+
+```markdown
+---
+title: "<blog post title>"
+type: pillar
+publish_date: ""
+channels: <channels from step 3>
+status: draft
+---
+
+## Discord
+
+<discord content>
+
+---
+
+## X/Twitter Thread
+
+<tweet 1 with label>
+
+<tweet 2 with label>
+
+...
+
+---
+
+## IndieHackers
+
+**Title:** <ih title>
+
+**Body:**
+
+<ih body content>
+
+---
+
+## Reddit
+
+**Subreddit:** <suggested subreddits>
+**Title:** <title>
+
+**Body:**
+
+<body>
+
+---
+
+## Hacker News
+
+**Title:** <title>
+**URL:** <Hacker News tracked url>
+
+---
+
+## LinkedIn Personal
+
+<linkedin personal content>
+
+---
+
+## LinkedIn Company Page
+
+<linkedin company page content>
+
+---
+
+## Bluesky
+
+<bluesky content>
+```
+
+**Step 5: Pre-write marker validation (belt-and-suspenders)**
+
+Before writing the assembled content to disk, scan the full content buffer one final time for `{{`, `}}`, `{%`, `%}`. This repeats the Phase 5.5 check against the fully assembled file (including headings, frontmatter, and inter-section transitions). If any marker is present, STOP and do not write the file. Regenerate the offending section or escalate to the user.
+
+Writing a content file that contains Liquid markers is a workflow violation -- `lefthook`'s `distribution-content-liquid-guard` will reject the commit, and if the file is somehow committed, `content-publisher.sh`'s runtime gate will refuse to post it. Catch it here so the skill does not produce a broken artifact in the first place.
+
+### Phase 10: Summary & Next Steps
+
+Output the file path, channel status, and instructions:
+
+```
+Content file written: knowledge-base/marketing/distribution-content/<slug>.md
+
+Distribution summary:
+- Discord: [Posted now via webhook / Will publish via cron when scheduled]
+- X/Twitter: Will publish via cron when scheduled
+- Bluesky: Will publish via cron when scheduled
+- LinkedIn Company Page: Will publish via cron when scheduled
+- IndieHackers: Manual (content in file)
+- Reddit: Manual (content in file)
+- Hacker News: Manual (content in file)
+- LinkedIn Personal: Manual (content in file)
+
+Next steps:
+1. Review the content file
+2. Set publish_date to the target date (YYYY-MM-DD format)
+3. Change status from "draft" to "scheduled"
+4. The daily cron will publish to Discord, X, Bluesky, and LinkedIn Company Page on the scheduled date
+5. Reddit, IndieHackers, Hacker News, and LinkedIn Personal sections are for manual posting
+```
+
+## Important Guidelines
+
+- All Discord posting requires explicit user approval before sending -- no auto-send
+- Character limits are enforced during generation, not as a post-hoc check (2000 for Discord, 280 per tweet for X/Twitter, 80 for HN title, 300 for Bluesky, 1300 optimal / 3000 max for LinkedIn Personal and LinkedIn Company Page)
+- Variants are NEW prose, not a copy of checked prose: every factual sentence in a channel that posts automatically (Discord, X, Bluesky, both LinkedIn pages) must be checked against the fact-checked post, and hook compression drifts toward cause-and-effect and "the whole X" claims the post avoided. Run `soleur:marketing:fact-checker` on the distribution file, or diff each variant's factual sentences against the post. Compute every `-- NNN chars` label and the Bluesky length from the final text (Bluesky's 300 includes the URL); never hand-count. **Why:** #8548 — LinkedIn and tweet variants turned two side-by-side defects into a causal claim the checked post had avoided; review rated it High.
+- Discord uses the plain `content` field, not rich embeds
+- JSON-escape all Discord content before inserting into the webhook payload
+- When posting via webhook, always include `username`, `avatar_url`, and `allowed_mentions: {parse: []}` fields
+- If the brand guide's channel notes section is missing for a platform, generate content using only the `## Voice` section (no error)
+- If the user selects "Edit" for Discord, incorporate their feedback and regenerate -- do not present the same draft
+- Template variables in blog source (`{{ stats.agents }}` etc.) are resolved by passing current stats as LLM context -- the LLM substitutes actual values during generation
+- Distribution content files are raw API payloads (Discord webhook `content` field, X tweet text, LinkedIn share text), NOT Eleventy templates. Liquid/Jinja markers (`{{`, `}}`, `{%`, `%}`) in the body will be posted verbatim to third parties -- a `{{ site.url }}` becomes a literal `{{ site.url }}` in the Discord message. Phase 5.5 and Phase 9 Step 5 enforce this mechanically; do NOT weaken these gates
+- Markup artifacts (JSON-LD scripts, HTML details/summary tags, Nunjucks tags) in the blog source are ignored during generation -- they are meaningless in social posts
+- Missing `DISCORD_BLOG_WEBHOOK_URL` and `DISCORD_WEBHOOK_URL` does not block execution -- Discord is included in the content file's `channels` field for cron publishing
+- New content files use the blog post slug as filename. If an existing file with a numeric prefix matches the slug (e.g., `06-<slug>.md`), the existing filename is preserved