linkedin-studio/CLAUDE.md

LinkedIn Studio Plugin (v0.5.3)

Full-spectrum LinkedIn content engine — short-form feed posts, carousels, video scripts, and long-form newsletter editions — with the 2026 relevance-ranking model baked in. Maturity v0.5.3: M0 (per-user data dir ${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/, idempotent session-start migration — see references/data-path-convention.md) complete; all 29 command surfaces through the interactive quality-gate (docs/hardening/log.md). Remaining for v1.0.0: a GUI + independent cold-review coverage (the /trekreview artifact docs/hardening/review.md persists for S1 only — see docs/hardening/plan.md). Version history → CHANGELOG.md.

Architecture

• State file: ~/.claude/linkedin-studio.local.md (YAML frontmatter, auto-initialized from config/state-file.template.md)
• State updater: hooks/scripts/state-updater.mjs — deterministic state mutations (post tracking, streak, content history pruning). Pure functions, tested, no AI involvement
• Clipboard helper: hooks/scripts/clipboard-helper.mjs — cross-platform clipboard (macOS pbcopy, Linux xclip/xsel, WSL clip.exe). All content commands auto-copy
• iCal generator: hooks/scripts/ical-generator.mjs — RFC 5545 calendar files for batch scheduling. Standalone CLI + importable module
• Figure renderer: render/build-figur.mjs — coded data figures (SVG/HTML → PNG via headless Chrome); three targets (article/carousel/single); brand tokens from the user data dir's profile/brand-tokens.json, neutral defaults otherwise (see references/figure-design-guidelines.md). Standalone CLI + importable module
• Post queue: assets/drafts/queue.json (managed by hooks/scripts/queue-manager.mjs)
• Analytics: CLI scripts/analytics/ (TypeScript, needs tsx + npm install); data assets/analytics/ (gitignored)
• Analytics metrics (S16): parsed CSV columns + an optional, manually-entered saves count (count-only in native LinkedIn analytics since ~Sept 2025, no CSV export / no API). parseOptionalCount(): blank / non-numeric / negative → undefined (unknown, never 0), a genuine 0 is kept; saves surfaced per-post + as totalSaves, but not folded into engagementRate. dwell stays explicitly unmeasurable (internal to LinkedIn, no export/API). All analytics I/O routes through the getAnalyticsRoot() seam (M0 per-user data-dir).

Hooks

9 hooks across 7 events. All Node.js (.mjs). PreToolUse/PostToolUse hooks use parameterized content-gatekeeper.mjs with isLinkedInContent() check.

Event	Purpose
SessionStart	Load state, REMEMBER.md, milestone tracker
PreToolUse (Write|Edit)	Content quality gate, voice guardian, topic rotation gate
Stop	State update, pre-publish reminders, content history
UserPromptSubmit	LinkedIn context enrichment (three-tier matching)
PostToolUse (Write)	Post-creation automation (5x5x5, posting time)
PreCompact	Preserve LinkedIn context during compaction
Notification	Posting reminders (rate-limited 30min)

Session markers: /tmp/linkedin-hooks/session-active (Stop hook gating, 12h staleness). Shared modules: linkedin-content-filter.mjs, queue-manager.mjs, personalization-score.mjs, state-updater.mjs, clipboard-helper.mjs.

State updates: post tracking, streak, and content history are handled deterministically by state-updater.mjs (Stop hook + commands); entries older than 90 days are auto-pruned at session start.

Hook editing: edit hooks/hooks.template.json + hooks/prompts/*.md, then run python3 hooks/scripts/compile-hooks.py. Do not edit hooks.json directly. Prompts load at runtime via gatekeeper scripts; the compile step is only needed when adding type: prompt hooks.

Commands (29)

All content commands auto-copy output to clipboard via clipboard-helper.mjs; interactive steps are minimized (angle/format/post-type inferred from context, max 2 questions per post). Organized into five journeys (Start · Create · Engage · Measure · Grow): create/measure are guided creation/analytics front-doors, onboarding/strategy the Start/Grow front-doors, and the 27 atomic commands are the execution tier.

Command	Purpose
/linkedin	Router — status line + five-journey command menu
/linkedin:create	Create front-door — routes to the command owning the format (post/quick/react/carousel/video/multiplatform/batch/newsletter); delegates only
/linkedin:measure	Measure front-door — routes to the analytics command (import/report/analyze/audit/ab-test); delegates only
/linkedin:onboarding	Multi-step onboarding wizard (profile → setup → first-post); Start-journey front-door
/linkedin:first-post	First-post accelerator (10 min)
/linkedin:setup	Guided personalization setup
/linkedin:react	URL-to-post pipeline
/linkedin:post	Full post creation (10-15 min)
/linkedin:quick	5-minute quick post (3-line formula) + 8 post-type templates
/linkedin:pipeline	Full end-to-end content pipeline
/linkedin:newsletter	Long-form orchestrator (newsletter / essay / series article) — multi-session 18-phase pipeline with gates before prose (skeleton + spine), fact-check, editorial-review (Step 5.5), persona sweep, headless adversarial review (Step 6.5), and visual-assets — all before lock
/linkedin:headless-review	Cold adversarial review package — 3 headless archetypes (content-reviewer, language-reviewer, fact-reviewer) + persona-reviewer on a FROZEN draft, no drafting-session context; operator-gated report (Step 6.5 standalone surface)
/linkedin:pivot	Re-open a long-form edition after a late substantive change so cleared gates re-run before lock (pivot heuristic: >20% word-count or >2 new sections)
/linkedin:batch	Create a full week of content
/linkedin:calendar	View/manage post scheduling queue + publish action
/linkedin:firsthour	Post-publish first-hour / reply-loop sprint — delegates to engagement-coach, persists the plan (recordFirstHourPlan), hands off to post-feedback-monitor
/linkedin:carousel	Structured multi-slide carousel generator
/linkedin:video	Video script generator (30s-2min)
/linkedin:multiplatform	Adapt content for other platforms (long-form → /linkedin:newsletter)
/linkedin:analyze	Content/performance analysis
/linkedin:audit	Periodic content strategy audit
/linkedin:import	Import CSV export → structured JSON (delegates analysis to /linkedin:report)
/linkedin:report	Generate weekly performance report
/linkedin:ab-test	Design and manage A/B content tests
/linkedin:strategy	Growth strategy + authority building; Grow-journey front-door
/linkedin:competitive	Competitive analysis of niche
/linkedin:monetize	Monetization strategy and funnels (unlocks at ~1K followers)
/linkedin:outreach	Outreach orchestrator — collaborations + speaking (unlocks at ~1K followers)
/linkedin:profile	Profile/topic-relevance optimization

Agents (19)

Agent	Model	Color	Responsibility
content-optimizer	Sonnet	Blue	Optimize existing posts
strategy-advisor	Sonnet	Green	Growth recommendations
analytics-interpreter	Sonnet	Yellow	Audience pattern analysis + weekly/monthly performance reports (interpret/report modes)
engagement-coach	Sonnet	Magenta	5x5x5 + first-hour tactics + CEA commenting + target selection
content-planner	Sonnet	Cyan	Content audit + weekly/monthly plans
network-builder	Sonnet	Teal	Strategic networking + outreach
content-repurposer	Sonnet	Purple	Format conversion + evergreen refresh
trend-spotter	Sonnet	White	Trending topics + opportunity scores
voice-trainer	Sonnet	Pink	Voice profile building + drift detection
differentiation-checker	Sonnet	Gray	Originality scoring + commodity detection
post-feedback-monitor	Opus	Lime	Post-publish 48h monitoring
video-scripter	Sonnet	Violet	Video script creation with pacing
fact-checker	Opus	Brown	Factual-claim verification against primary sources + post-cutoff web-search mandate (longform)
editorial-reviewer	Opus	Orange	Editor's craft gate (Step 5.5, before persona sweep): prosa-håndverk + narrativ-arkitektur, ≤10 flags BLOCK/REWORK/NICE, operator-gated via SendUserFile (longform)
persona-reviewer	Opus	Olive	Reader-persona gate — skeleton (before prose) + resonance (before lock) + hook-conversion (after lock), blocking hard-fail list (longform)
voice-scrubber	Opus	Red	De-AI scrub + Norwegian-chronicle voice-drift correction (longform)
content-reviewer	Opus	Maroon	Cold/headless argument-integrity review on a frozen draft (Step 6.5): logical holes, unsupported assumptions, contradiction, missing concretization, unanswered objection; ≤8 flags (longform)
language-reviewer	Opus	Navy	Cold/headless Norwegian-language review on a frozen draft (Step 6.5): repetition, anglicisms, stiff register, self-contradiction, rhythm; ≤10 flags (longform)
fact-reviewer	Opus	Gold	Cold/headless re-verification on the frozen/pivoted version (Step 6.5, web search): verifiable claims, quote precision, number attribution, source quality + pivot-risk (longform)

Rule: Always read assets/voice-samples/ before generating content.

Invocation form: commands invoke plugin agents by their namespaced type — subagent_type: linkedin-studio:<name>, never the bare <name> (a bare type does not resolve and the Task call fails).

Reload requirement: a NEW agent file under agents/ registers only after a Claude Code session reload (the plugin agent set is built at session start). Reload before invoking a freshly-added agent.

Content Quality Rules

1. Hook: 110-140 characters (mobile cutoff)
2. Post length: 1,200-1,800 chars (standard), 150-500 chars (quick)
3. No external links in post body (correlate with lower reach; see references/algorithm-signals-reference.md)
4. No corporate buzzwords: leverage, synergy, paradigm shift, thought leader, disruptive, value proposition, ecosystem, holistic approach
5. Topic must align with user's 5 core expertise areas (topic-relevance signal)
6. Topic rotation: no back-to-back same pillar, no pillar >50% in 14 days (warn-only)
7. Progressive onboarding: personalization score hidden until 3+ posts; voice guardian suppressed until 5+ voice samples