Follow Builders Sidecar

This skill is the external delivery/scheduling layer for the original follow-builders skill.

It does not patch the upstream repo. It only:

imports the original config once
disables the original digest cron
creates and owns its own hourly cron
checks upstream feed commits
builds the digest
delivers it through OpenClaw or Feishu card

Runtime requirements

This skill expects:

node for all sidecar scripts
python3 for avatar circle-cropping
openclaw for cron inspection, job takeover, and message delivery

It also reads and writes local files during normal operation:

reads ~/.follow-builders/config.json once during takeover
writes ~/.follow-builders-sidecar/config.json
writes ~/.follow-builders-sidecar/state.json
optionally writes ~/.follow-builders-sidecar/credentials.json for local-only direct Feishu app credentials
can reuse OpenClaw-configured Feishu account settings when Feishu card delivery is enabled

When to use this skill

Use this skill when the user asks to:

install or take over from the original follow-builders
switch digest delivery to the sidecar flow
configure timezone / language / daily-vs-weekly / delivery driver
check whether takeover worked
disable sidecar and optionally restore the original cron

Primary commands

Takeover / setup

Before running setup, ask the user which Feishu card mode they want:

Reuse an existing OpenClaw Feishu account
Configure a local direct Feishu app for this sidecar

If the user chooses direct Feishu app mode, collect:

appId
appSecret
chatId
optional domain (feishu by default, lark when needed)

Run:

node scripts/sidecar-setup.js

Optional flags:

--driver openclaw_announce|feishu_card
--channel <channel>
--to <target>
--account <accountId>
--feishu-mode openclaw_account|direct_credentials
--feishu-account <accountId>
--feishu-chat-id <chatId>
--feishu-app-id <appId>
--feishu-app-secret <appSecret>
--feishu-domain feishu|lark
--avatar-fallback-account <accountId>

Configure

Run:

node scripts/sidecar-configure.js ...

Common flags:

--language zh|en|bilingual
--timezone <IANA timezone>
--frequency daily|weekly
--weekly-day monday|...|sunday
--driver openclaw_announce|feishu_card
--channel <channel>
--to <target>
--account <accountId>
--feishu-mode openclaw_account|direct_credentials
--feishu-account <accountId>
--feishu-chat-id <chatId>
--feishu-app-id <appId>
--feishu-app-secret <appSecret>
--feishu-domain feishu|lark

Important:

After takeover, configuration belongs to the sidecar.
Do not tell the user to keep changing the original skill's delivery time.
If the user wants a different trigger window, tell them to edit the sidecar cron itself.

Status

Run:

node scripts/sidecar-status.js

Rollback

Run:

node scripts/sidecar-rollback.js --reenable-original

Use --reenable-original only when the user explicitly wants to restore the original cron.

Manual test run

To test the pipeline without sending anything:

node scripts/run-sidecar.js --skip-delivery

Delivery rules

default driver is openclaw_announce
optional driver is feishu_card
Feishu card mode supports:
- openclaw_account: reuse a Feishu app already configured in OpenClaw
- direct_credentials: store a local-only Feishu appId/appSecret/chatId for this sidecar
feed freshness is based on upstream GitHub commit time
only same-local-day commits are valid
daily: one successful send per local day
weekly: only on the configured weekday, one successful send per week

Upstream compatibility rules

The upstream follow-builders skill may evolve beyond the current three feeds.

When working with this sidecar, always treat upstream evolution as a first-class concern:

Before changing sidecar compatibility logic, inspect the upstream SKILL.md.
Inspect the upstream repo root for all feed-*.json files, not just:
- feed-x.json
- feed-podcasts.json
- feed-blogs.json
If a new upstream feed appears, do not silently ignore it.
First determine whether the new feed can be handled by:
- an existing adapter
- a generic pass-through adapter
- or a new dedicated adapter that must be added
If the sidecar cannot safely interpret the new feed schema yet, explicitly surface that limitation to the user instead of pretending nothing changed.

Design intent:

SKILL.md is for agent/operator understanding
code-level adapter/registry logic is for runtime compatibility

Do not rely on prose alone for runtime support. A note in SKILL.md helps the agent understand what to inspect, but actual support for a new feed still requires code or schema-level compatibility logic.

External endpoints

The sidecar may contact these external services:

https://api.github.com/ to discover upstream feed files and latest relevant commits
https://raw.githubusercontent.com/ to load upstream feed JSON and prompts
https://publish.twitter.com/oembed to expand quoted tweets
podcast RSS hosts declared in config/default-sources.json to repair episode links
https://unavatar.io/ to fetch public avatar images
https://open.feishu.cn/open-apis/ or https://open.larksuite.com/open-apis/ when Feishu card delivery is enabled

Security and privacy

The sidecar does not modify the upstream follow-builders repo.
The sidecar does not send local files to arbitrary third-party endpoints.
OpenClaw and Feishu routing are used only to deliver the digest the user asked for.
Direct Feishu app credentials, when configured, stay in ~/.follow-builders-sidecar/credentials.json and are not intended for repository storage.
The sidecar's own local state lives under ~/.follow-builders-sidecar/.

Trust statement

Installing this skill means allowing it to read the user's local follow-builders config once during takeover, call the upstream public feed sources, reuse OpenClaw-configured delivery accounts or optional local direct Feishu credentials, and optionally send digest data to OpenClaw or Feishu. Only install it if you trust that behavior.

Safety rules

Never modify the original follow-builders repo during normal operation
Never silently re-enable the original cron unless the user asks for rollback
If the original cron is found enabled again during runtime, disable it and keep the sidecar as source of truth