From 9567689c4a2faee50ea9b2ac08dca7da8547e90d Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 29 Jun 2026 10:14:23 +0200 Subject: [PATCH] =?UTF-8?q?docs(claude-md):=20trim=20CLAUDE.md=20to=20inva?= =?UTF-8?q?riants=20(=E2=88=922,266=20always-tok)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md is loaded every turn while working in this repo (measured 4,846 always-loaded tokens — the entire per-repo delta, since the repo has no .claude/rules or .mcp.json). The bulk was a version-history narrative: the 2026-05-31 re-baseline note plus a single paragraph recounting the full v2.0.0 → v4.1.0 journey (per-version motivation, gate-by-gate evolution). That is CHANGELOG material, not an invariant for working on the plugin — CHANGELOG.md (18 version headings) already owns it. Trimmed to what is invariant: a terse current-maturity intro (v0.5.3, M0 done, v1.0.0 remainder) pointing to CHANGELOG/docs; the architecture, hooks, command (29) and agent (19) tables, and content-quality rules. The verbose per-row prose (newsletter phase-list, agent (vX.Y)/Step-tag motivation) is compressed to one-liners. Agent name/model/color cells, all counts, and the version stay byte-exact so the structure lint holds. Verified with the repo's own gates: scripts/test-runner.sh 138/0 ("All structural checks passed!" — counts, version-consistency, stat-consistency, model-consistency, render-chain all green); scripts/check-model-consistency.mjs OK (19 agents, all surface declarations match frontmatter). CLAUDE.md 127→109 lines, 19,572→10,457 B, 4,846→2,580 tok (−47%). Docs-only — no version bump, no catalog ref change. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01683eAqVecv9VZfQzL8CQ9h --- CLAUDE.md | 76 +++++++++++++++++++++---------------------------------- 1 file changed, 29 insertions(+), 47 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 85f1159..5777c27 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,29 +1,16 @@ # LinkedIn Studio Plugin (v0.5.3) -> **Version re-baseline (2026-05-31) · M0 landed (2026-06-18, v0.5.0).** Previously numbered 1.0.0–4.1.0; those were pre-release iterations. The honest maturity is **v0.5.3** — **the architecture workstream (M0) is complete: user data now lives in a per-user data dir (`${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/`) resolved through one seam per runtime, with automatic idempotent migration on session-start** (see `references/data-path-convention.md`). **Hardening has landed:** all 29 command surfaces have been through the interactive quality-gate — per-command audit trail in `docs/hardening/log.md` (dispositions HARDENED/PASS/FIXED), plus the S27–S30 reference-consistency, terminology, and magnitude scrubs — and command testing is effectively that campaign (each command persona-simulated + 4-axis-evaluated + lint-verified), backed by the script-level suites. **Two items remain on the path to v1.0.0:** (1) a **GUI** — the one workstream not yet begun; (2) **independent cold-review coverage** — the `/trekreview` adjudication artifact (`docs/hardening/review.md`) persists for **S1 only (4/29)**; S2–S26 were gated by the operator-in-the-loop v2 method after the cold-reviewer swarm was dropped following the S2 fabrication incident (see `docs/hardening/plan.md`), so brief SC-H is not met as written. The development narrative below is preserved as history. - -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. **v4.0.0** is an **audit-remediation release (Voyage Phase 0–3)**: a critical self-review found overclaiming (tracking/analytics/review-independence the plugin couldn't deliver), dormant capability (11 agents never invoked by any command), and structural rot (a dead lint, a self-contradicting algorithm claim, an unpublishable model brand/date in user copy). The fix wires **all 11 orphaned agents** (no deletions → 19 agents), adds **`/linkedin:firsthour`** (→ 27 commands) + a short-form de-AI gate + a video quality gate, promotes `post-feedback-monitor` to Opus, makes the newsletter-distribution / profile-SEO / outreach surfaces honest, **reconciles the algorithm signals to one sourced statement** (no model name or date; `references/algorithm-signals-reference.md` is the single source of truth), fixes the analytics fresh-clone crash, closes the voice-profile leak (placeholder + sentinel + gitignore), and rebuilds the structure lint with version/count/stat/model-consistency + render-chain-propagation + `$`-safety guards (each agent's frontmatter model must match every surface declaration; no honesty pattern a command was cleaned of survives in the reference it renders from — S12; no untrusted value reaches a `String.replace` replacement string in `state-updater.mjs`, proven behaviorally + coverage-complete + self-testing — S13). Breaking — reinstall/reload required for the newly-wired agents; consolidates the v3.0.0 identity break (slug, agent namespace, state-file path). v2.0.0 consolidated the surface (27 commands → 24, 16 agents → 14) while adding the long-form `/linkedin:newsletter` orchestrator + two longform-quality gate agents (`fact-checker`, `persona-reviewer`). v2.1.0 added two gates BEFORE prose (Step 2.5 skeleton + Step 3a spine prose) + a third `persona-reviewer` mode (`skjelett`). v2.2.0 hardened the longform gates with the lessons from the second production run (Seres-serien): blocking persona hard-fails, a post-cutoff fact-check mandate, a `voice-scrubber` agent, render+annotate operator gates, and STATE.md-reconciled edition state. v2.3.0 made **visual assets an explicit pipeline phase** — Step 7.5 (visual-assets) between annotation (Step 7) and lock (Step 8): cover (+ optional inline figures) or a carousel deck, generated (default `mcp-image`, external `cover-raw.png` accepted) and operator-gated BEFORE lock so `render/build-linkedin.mjs` picks up `cover.png` at lock without a post-lock re-render. **v2.4.0** makes an **editor's craft gate an explicit pipeline phase** — new **Step 5.5 (editorial-review)** between fact-check (Step 5) and the persona sweep (Step 6): a new **`editorial-reviewer` agent** (Opus) judges **craft** (prosa-håndverk + narrativ-arkitektur), not reader-response, returning ≤10 flags (BLOCK/REWORK/NICE) as direction, **operator-gated via `SendUserFile` BEFORE the persona sweep** so the personas measure resonance instead of stumbling on craft noise. Motivated by Del 4: every persona reported PASS, yet the editor found 8 fresh points on first reading, ~6/8 of them craft/architecture blind spots no agent measured. Mirrors the Maskinrommet writing-contract §C2. Pipeline 14 → 15 phases; agents 15 → 16; additive `editorialReview` state. Doc/orchestration-only for the wiring (the new agent + its fasit fixture + lint test are the only new files); commands unchanged (24). **v3.1.0 (Endring 9)** adds an **adversarial review package** run COLD on a frozen draft — new **Step 6.5 (headless-review)** between the persona sweep (Step 6) and lock, plus a standalone **`/linkedin:headless-review`** command (run in a fresh session for maximum isolation): three new headless archetypes — **`content-reviewer`** (argument integrity), **`language-reviewer`** (Norwegian language), **`fact-reviewer`** (cold re-verification incl. claims a late pivot bolted on) — plus `persona-reviewer` in resonance + conversion modes, all with NO drafting-session context (the independence layer the in-session gates structurally cannot be). v3.1.0 also adds **`/linkedin:pivot`** (re-opens cleared gates after a late change + a >20 %/>2-section pivot-detection gate at lock) and **per-artifact personas** (`articles.NN.personas` — one or more readers configurable per edition, resolved edition-state → series file → plugin library → interactive). Pipeline 15 → 16 phases; agents 16 → 19; commands 24 → 26; additive `personas` / `pivots` / `headlessReview` state. Motivated by Del 4: the in-session editor + persona sweep shared the drafting session's framing-bias, so the version that shipped was never independently re-reviewed. **v4.1.0** adds a **journey layer** over the (unchanged) command surface: two guided front-doors — **`/linkedin:create`** (routes to the right creation command) and **`/linkedin:measure`** (routes to the right analytics command) — plus a router re-tiered into five journeys (Start · Create · Engage · Measure · Grow), with `onboarding`/`strategy` elevated as the Start/Grow front-doors and the 27 atomic commands kept as the execution tier (→ 29 commands). Additive: 14a's cold command-rationalization found **zero redundancy** (no merges/cuts; `docs/remediation/command-rationalization.md` + `journey-layer-design.md`), so the journey layer organizes rather than removes; reload registers the two new commands. +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 integration (macOS `pbcopy`, Linux `xclip`/`xsel`, WSL `clip.exe`). All content commands auto-copy to clipboard -- **iCal generator:** `hooks/scripts/ical-generator.mjs` — RFC 5545 calendar file generation for batch scheduling. Standalone CLI + importable module +- **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 - **Post queue:** `assets/drafts/queue.json` (managed by `hooks/scripts/queue-manager.mjs`) -- **Analytics CLI:** `scripts/analytics/` (TypeScript, requires `tsx` and `npm install`) -- **Analytics data:** `assets/analytics/` (gitignored) -- **Analytics metrics (S16):** the parsed CSV columns plus an **optional, manually-entered** `saves` count. - Saves are count-only in native LinkedIn post analytics (~Sept 2025), absent from the CSV export, and - have no self-serve API — so the ingest path is the user adding a `Saves` column with the number they - read off LinkedIn. `parseOptionalCount()` parses it when present: blank / non-numeric / negative → - `undefined` (`unknown`, never 0), a genuine `0` is kept, and saves is **not** folded into - `engagementRate` (kept comparable to older imports). Surfaced per-post + as `totalSaves` in the - weekly/monthly reports; **never auto-tracked**. -- **Unmeasured by design:** `dwell` time stays **explicitly unmeasurable** — internal to LinkedIn for - organic posts, no exportable count, no API; no dwell field or surface exists. The S16 analytics - extension routes all I/O through the existing `getAnalyticsRoot()` seam, so the planned per-user - data-dir migration (UI-brief §9b/M0) relocates the root in one place without reworking the schema. +- **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 @@ -41,45 +28,45 @@ Full-spectrum LinkedIn content engine — short-form feed posts, carousels, vide **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 management, and content history are handled deterministically by `state-updater.mjs` (called from Stop hook and commands). Content history entries older than 90 days are auto-pruned at session start. +**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 are loaded at runtime by gatekeeper scripts; the compile step is only needed when adding `type: prompt` hooks. +**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 (post, quick, react, pipeline, first-post, video, multiplatform, carousel, newsletter) auto-copy output to clipboard via `clipboard-helper.mjs`. Interactive steps are minimized — angle, format, and post type are inferred from context, with max 2 questions per post. **v2.0.0 net change:** 5 commands removed (`templates`, `publish`, `authority`, `collab`, `speaking` — absorbed into `quick`, `calendar`, `strategy`, `outreach` respectively) + 2 commands added (`newsletter`, `outreach`) = 27 → 24. **v3.1.0** adds 2 longform companions (`headless-review`, `pivot`) = 24 → 26. **Remediation Step 16** adds `firsthour` (wiring orphan agent #11 `engagement-coach`) = 26 → 27. **v4.1.0 (S14)** adds the two journey front-doors (`create`, `measure`) = 27 → 29. The surface is organized into **five journeys** (Start · Create · Engage · Measure · Grow); `create`/`measure` are new guided front-doors, `onboarding`/`strategy` are elevated as the Start/Grow front-doors, and the 27 atomic commands remain the execution tier (14a found zero redundancy → no merges/cuts). +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` | **(v4.1) Create front-door** — guided "what to make?" → routes to the creation command that owns the format (post/quick/react/carousel/video/multiplatform/batch/newsletter); delegates only | -| `/linkedin:measure` | **(v4.1) Measure front-door** — guided "how am I doing?" → 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 (v4.1)** | +| `/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 edition / essay / series article — multi-session 18-phase pipeline with **lived-specifics extraction BEFORE research (Step 1.5, Fix #2 — kilde-så-draft; binding-gate enforced at Step 2.5)**, **skeleton + spine-prose gates BEFORE prose (v2.1)**, a **deterministic §B/§C1 contract-gate BEFORE the AI sweeps (Step 4.5)**, **editorial-review craft gate BEFORE the persona sweep (Step 5.5, v2.4)**, fact-check + persona-sweep BEFORE lock, **headless adversarial review BEFORE lock (Step 6.5, v3.1)**, and **visual-assets gate BEFORE lock (Step 7.5, v2.3)** | -| `/linkedin:headless-review` | **(v3.1)** Cold adversarial review package — run the 3 headless archetypes (`content-reviewer`, `language-reviewer`, `fact-reviewer`) + `persona-reviewer` (resonance/conversion) on a FROZEN draft with no drafting-session context; consolidated, operator-gated report. Step 6.5's standalone surface (run in a fresh session for maximum isolation) | -| `/linkedin:pivot` | **(v3.1)** Re-open a long-form edition after a late substantive change so cleared gates (fact-check → editorial → persona → headless) re-run before lock; logs `pivots[]`, resets `currentPhase`, un-locks if needed (pivot heuristic: >20 % word-count change or >2 new sections) | +| `/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 (mark scheduled posts as published) | -| `/linkedin:firsthour` | Post-publish first-hour / reply-loop sprint — delegates to `engagement-coach` for a timestamped target list + draft comments + timeline, persists the plan to state (`recordFirstHourPlan`), hands off to `post-feedback-monitor` | +| `/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 (short-form/cross-format; long-form → `/linkedin:newsletter`) | +| `/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 (phase guidance, trajectory, signature content compounding) | +| `/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 opportunities (unlocks at ~1K followers) | -| `/linkedin:profile` | profile/topic-relevance optimization | +| `/linkedin:outreach` | Outreach orchestrator — collaborations + speaking (unlocks at ~1K followers) | +| `/linkedin:profile` | Profile/topic-relevance optimization | ## Agents (19) @@ -97,24 +84,19 @@ All content commands (post, quick, react, pipeline, first-post, video, multiplat | `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 (v2.4, Step 5.5, before persona sweep): prosa-håndverk + narrativ-arkitektur, ≤10 flags BLOCK/REWORK/NICE as direction, operator-gated via `SendUserFile`; mirrors Maskinrommet §C2 (longform) | -| `persona-reviewer` | Opus | Olive | Reader-persona skeleton (v2.1, before prose) + resonance (before lock) + hook-conversion (after lock) gate, blocking hard-fail list (longform) | -| `voice-scrubber` | Opus | Red | De-AI scrub + Norwegian-chronicle voice-drift correction; gold standard = approved Norwegian editions, not the English post corpus (longform, v2.2) | -| `content-reviewer` | Opus | Maroon | **(v3.1, Step 6.5 — cold/headless)** Argument-integrity review on a frozen draft: C1 logical holes · C2 unsupported assumptions · C3 argument contradiction · C4 missing concretization · C5 unanswered objection. ≤8 flags BLOCK/REWORK/NICE as direction; refuses drafting-session framing as context pollution (longform) | -| `language-reviewer` | Opus | Navy | **(v3.1, Step 6.5 — cold/headless)** Norwegian-language review on a frozen draft: L1 verbatim repetition · L2 anglicisms · L3 stiff bureaucratic register · L4 language-level self-contradiction · L5 clang/rhythm. ≤10 flags BLOCK/REWORK/NICE; deliberate cold re-take of editorial's prose axis (longform) | -| `fact-reviewer` | Opus | Gold | **(v3.1, Step 6.5 — cold/headless)** Cold re-verification on the frozen/pivoted version (web search): F1 verifiable claims · F2 quote precision · F3 number attribution · F4 source quality. 🔴/🟡/🟢 + pivot-risk subsection; deliberate redundancy with `fact-checker` to catch a pivot premise that arrived after Step 5 (longform) | +| `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:` — never the bare `` (a bare -type does not resolve and the `Task` call fails). +**Invocation form:** commands invoke plugin agents by their **namespaced** type — `subagent_type: linkedin-studio:`, never the bare `` (a bare type does not resolve and the `Task` call fails). -**Reload requirement:** Adding a NEW agent file under `agents/` registers it only after -a Claude Code **session reload** — the plugin agent set is built at session start, so a -freshly-added agent (e.g. `fact-checker`, `persona-reviewer` when first added) is not -invokable until the session reloads. After adding an agent, reload before invoking it. +**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