appeeky spec
← Learn

Content · 8 min read

Posts and videos through pull requests

Social posts and UGC clips as files: drafted by your agent, reviewed with the listing, sent after the merge, and measured.

Posts and short videos are growth changes too. In the spec they go the same way as a listing change: drafted as a file, reviewed in a pull request, sent after the merge, and measured. Your agent can draft them; nothing is public until you merge.

Connect once in Appeeky

The spec uses what you set up in Appeeky: the social accounts you connected (X, Instagram, TikTok, LinkedIn and more) and your creator personas. Set APPEEKY_API_KEY where the spec runs.

  • Social

    Posting needs the Startup plan or above. An account that needs reconnecting is marked in accounts.yaml.

  • Personas

    A persona needs a look (reference images) before it can make clips. Pick one in Appeeky UGC, or keep the persona in the repo.

Posts and personas as files

zsh
$ npx @appeeky/spec social pull && npx @appeeky/spec ugc pull
Accounts x, instagram, tiktok, linkedin
Posts 42 · last 30 days
! tiktok needs reconnecting in Appeeky
Personas Mia, Eren (no look yet)
Clips 12
▾ appeeky
▾ social
accounts.yaml# connected accounts
posts.jsonl# each post and each platform's views, likes, shares
summary.md# the last 30 days, and what did best
▾ drafts# posts to send
▾ ugc
personas.yaml# personas from Appeeky, and which can make clips
clips.jsonl# the clips made so far
▾ briefs# videos to make

The daily workflow (or the daily routine on your VM) runs both pulls, so the numbers are always in the repo for you and your agent.

A post is a file

appeeky/social/drafts/2026-11-12-fan-sounds.yaml
# appeeky/social/drafts/2026-11-12-fan-sounds.yaml
accounts: [twitter, instagram] # platforms from accounts.yaml, or account ids
text: "Fan sounds are here. Pick a fan, set a timer, sleep."
when: "2026-11-12T16:00:00Z" # without it, the post goes out on merge
media: ["https://…/fan.mp4"] # Instagram, TikTok and Pinterest need one
why: "Asked for in 9 reviews; shipped in 3.2."

social check flags what would fail before anyone merges: a platform with no connected account, text over a platform's limit, Instagram or TikTok without an image or video, a time in the past.

A video is a brief

appeeky/ugc/briefs/2026-11-10-dance.yaml
# appeeky/ugc/briefs/2026-11-10-dance.yaml
persona: Mia
script: "I made this edit in thirty seconds. The app picked the beat for me."
scene: bedroom with LED strip lights, phone propped on the desk
caption: "30 seconds, no editing skills"
durationSec: 8
aspectRatio: "9:16"
why: "Speed hooks beat feature lists on TikTok last month (summary.md)."

The clip is made in two steps, like Appeeky UGC: a still of the persona in the scene, then a talking video where they say the script in their voice. A script is one clip, about 8 seconds of speech. See the cost first:

zsh
$ npx @appeeky/spec ugc generate --dry-run
appeeky/ugc/briefs/2026-11-10-dance.yaml Mia · 40 credits
40 credits in all. Nothing was made.

Reviewed with the listing

Drafts and briefs go in the same pull request as the listing change they support. The pull request check adds them to its comment, so the reviewer sees what a merge sends out:

zsh
$ npx @appeeky/spec report
**1 post goes out on merge**
| drafts/2026-11-12-fan-sounds.yaml | twitter, instagram | 2026-11-12T16:00:00Z |
**1 clip made on merge**
| briefs/2026-11-10-dance.yaml | Mia | 8s 9:16 | I made this edit in thirty… |

With the specialists installed, the weekly co-founder review drafts one post and one video brief next to its listing change, and explains each in the brief.

Sent after the merge

The push workflow (or the push routine on your VM) runs social push --yes and ugc generate --yes when a merge adds drafts or briefs. Each draft is marked sent and each brief generating, and committed, so nothing goes out twice.

Clips on your own fal key

ugc generate --local makes the clip where the spec runs, with your own FAL_KEY, instead of in Appeeky with media credits. fal bills you directly. The persona can come from Appeeky, or live in the repo with its images:

appeeky/ugc/personas/mia.yaml
# appeeky/ugc/personas/mia.yaml
name: Mia
appearance: early 20s, dyed pink bob, oversized hoodie
personality: playful, talks fast
lane: dance trends and sound edits
looks: [mia/front.png, mia/side.png] # images next to this file, or URLs
zsh
$ npx @appeeky/spec ugc generate --local --dry-run
appeeky/ugc/briefs/2026-11-10-dance.yaml Mia · 8s 9:16 · veo-3.1-fast · about $1.24 on fal
About $1.24 on your fal account in all. Nothing was made.

The clip is saved to .appeeky/media/ and the brief records its videoUrl, ready for a post's media:. In GitHub Actions, add FAL_KEY as a secret: the push workflow renders locally and keeps the mp4 with the run.

What worked comes back

The next social pull brings every platform's views, likes, comments, shares and saves into posts.jsonl and summary.md. The social and UGC specialists read them before the next draft, so a hook that worked is tried again and one that did not is left out.

zsh
$ cat appeeky/social/summary.md
| platform | posts | views | likes |
| instagram | 12 | 41.3k | 1,902 |
| tiktok | 9 | 63.0k | 4,110 |
Best: “I made this edit in thirty seconds” · tiktok · 18.2k views