Plans

Plan: Close background-mode gaps for social-media-tools skills

todo
2026-05-28 agentics feature
Objective

Make every social-media-tools skill runnable in the background so the main session's context stays free. The router and two background agents already cover seven of nine skills; this closes the remaining gaps — give media-library a non-interactive mode, make the router reach it, and reconcile the completion-line contract — then version and document the full capability.

File add-background-mode-social-skills.html
Path docs/plans/add-background-mode-social-skills.html
Acceptance criteria 0 / 7 done

Context

The user wants the plugin's skills to run in the background, in a separate agent context, so developers can keep working without the share workflow consuming their main session window.

Exploration showed this is mostly already built. Two background chains exist: the social-share router skill classifies a request and dispatches the agent-social-share subagent (background: true), covering share-code, share-blog, share-github, share-video, share-selection, and share-project; and /digest-bg dispatches agent-digest for share-scan. All seven honor the --background non-interactive contract in references/non-interactive-mode.md (v0.9.0).

Three real gaps remain: (1) media-library is purely interactive — it has no --background mode and the router has no rule to reach it; (2) the digest chain emits its own Digest complete: … line rather than the contract's SOCIAL-SHARE: DONE line, and the contract documents only card-rendering output (png=/html=), not file-producing skills; (3) security-scrub is already non-interactive and stays a sub-step utility — out of scope by decision.

Steps

1
Add a generic file-output completion line to references/non-interactive-mode.md.
The current contract only defines a card line (png=/html=). A catalog dump and the digest produce a single file, so the contract needs a generic form before media-library can conform. Reconciling this first lets Step 2 reference it.
Verify
Re-read the file: it documents SOCIAL-SHARE: DONE skill=<name> output=<path> for file-producing skills alongside the existing card form, and a short note that share-scan/digest uses its own --days/--base/--max/--codebase flags and Digest complete: line.
2
Add --background non-interactive mode to skills/media-library/SKILL.md.
This is the one core skill with no background path. In background mode it must not call AskUserQuestion; instead it writes the saved-posts table to .claude/digests/media-library-YYYY-MM-DD.md and emits the generic completion line from Step 1.
Verify
The SKILL.md has a ## Non-interactive mode pointer block; Step 3's AskUserQuestion is marked (Interactive mode only); a background branch writes the catalog file and emits SOCIAL-SHARE: DONE skill=media-library output=<path>; allowed-tools gains Write. Interactive mode (no --background) still asks via AskUserQuestion.
3
Add a classification rule to skills/social-share/SKILL.md Phase 1 routing browse/library intent to media-library.
The router is the single background entry point; it must reach media-library so a developer can snapshot the catalog in the background. The rule must sit above the git fallbacks (rules 7–8) so "browse my saved posts" never falls through to share-code.
Verify
Phase 1 has a new rule matching terms like browse, library, saved posts, prior post → target media-library, placed before rule 7. Dispatching /social-share-bg browse my saved posts classifies to media-library and builds DISPATCH_FLAGS containing --background.
4
Update agents/agent-social-share.md to list media-library as a valid target and relay the output= form.
The agent forwards the Skill call and relays the status line verbatim, so it already works mechanically — but its Step 1 example list and Step 3 should explicitly acknowledge the generic output= completion line so the doc stays accurate. Doc-level change, no behavioral rewrite.
Verify
Step 1's TARGET_SKILL examples include media-library; Step 3 notes that a SOCIAL-SHARE: DONE … output=<path> line is relayed as-is just like the card form.
5
Bump the plugin version in .claude-plugin/marketplace.json from 1.0.1 to 1.1.0 and add a CHANGELOG.md entry.
A new non-interactive mode on media-library plus a new router rule is additive new capability — a MINOR bump per the repo's versioning table. Version lives only in marketplace.json for relative-path plugins.
Verify
The social-media-tools entry in marketplace.json reads "version": "1.1.0" and the auto-validate hook reports no JSON errors; CHANGELOG.md has a ## v1.1.0 — 2026-05-28 entry describing the media-library background mode, router rule, and contract reconciliation.
6
Update README.md to document full background coverage.
Discoverability was a real gap — developers may not know the background capability exists. The README should state that all share skills run in the background via /social-share-bg and /digest-bg, and document the new media-library --background catalog-snapshot behavior.
Verify
README lists the background entry points and the skills each covers, including media-library, and shows the .claude/digests/media-library-YYYY-MM-DD.md output path.

Acceptance Criteria

Verification

End-to-end background dispatch: from a session in this repo, run /social-media-tools:social-share-bg browse my saved posts. Confirm the router acks with a single line, the agent-social-share subagent runs in the background, and it reports back a SOCIAL-SHARE: DONE skill=media-library output=… line. Confirm .claude/digests/media-library-YYYY-MM-DD.md exists and contains the saved-posts table (or the "no saved posts" notice if the media dir is empty).

Interactive regression: invoke media-library without --background and confirm it still lists posts and asks via AskUserQuestion.

Plugin integrity: run /validate-plugin social-media-tools (or the validate-plugin skill) — structure, version, and homepage checks pass; the marketplace.json auto-validate hook reports no JSON errors after the version bump.

Existing chains unaffected: spot-check that /social-share-bg share my latest commit still routes to share-code and /digest-bg still routes to share-scan — the new router rule sits above the git fallbacks and must not shadow them.

Next Steps

Add a dedicated /media-library-bg command

Paste this prompt into Claude to execute this follow-up:

In kit/plugins/social-media-tools, add a commands/media-library-bg.md command (mirroring digest-bg.md) that dispatches a background agent to run the media-library skill with --background and write the catalog snapshot to .claude/digests/. Reuse agent-social-share if it can carry a non-share target, or add a thin agent-media-library if a dedicated agent reads cleaner. Bump the version a PATCH/MINOR as appropriate and update CHANGELOG.md and README.md.
Fully unify the digest chain onto the SOCIAL-SHARE contract

Paste this prompt into Claude to execute this follow-up:

Refactor share-scan and agent-digest in kit/plugins/social-media-tools so the digest chain emits the generic SOCIAL-SHARE: DONE skill=share-scan output=<path> completion line instead of the bespoke "Digest complete: …" message, while keeping its --days/--base/--max/--codebase flags. Update references/non-interactive-mode.md, the agent, and tests/fixtures if any reference the old line. This is a contract-unification cleanup — verify digest-bg still works end to end.
🔭 Wish List
Scheduled background digest + auto-catalogWish List

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Design a routine/cron setup that runs /social-media-tools:digest-bg weekly and refreshes the media-library catalog snapshot, writing both to .claude/digests/, so a developer always has an up-to-date "what's shareable" digest and post inventory without ever spending main-session context. Human review still required before posting. Propose the schedule config and where it should live.