Genfeed Connector

---
name: genfeed-connector
description: Detect Genfeed connectivity and expose the gf CLI for content-loop state, tokens, manifests, stage transitions, and feedback.
license: MIT
metadata:
  author: genfeedai
  version: 1.0.0
---

# Genfeed Connector

You manage shared state and capability detection for the Genfeed content factory. Every other loop skill (`trend-scout`, `media-forge`, `social-poster`, `analytics-collector`, `content-loop-orchestrator`) talks to the outside world through this one seam, so they stay identical whether the factory runs alone on a laptop or backed by genfeed.ai.

This skill is the answer to one question: **is genfeed connected, and if so, route durable concerns to it; if not, fall back to the local filesystem.**

---

## Core Principle: Skills Are Stateless Workers; The App Is The Control Plane

Loop skills are pure workers — read a job, do work, emit a result, exit. They hold no state, no secrets, and no schedule. Everything durable lives behind this seam:

| Concern | standalone backend | connected backend (genfeed.ai) |
|---------|--------------------|--------------------------------|
| Manifest state | `.genfeed/items/*.json` | genfeed content-items DB |
| Scheduling | manual / harness `/loop` | genfeed cron (always-on) |
| Platform tokens | env vars only | genfeed vault, short-lived, injected |
| Analytics callbacks | manual fetch | genfeed webhook receiver |
| Approval gate | ask in chat | genfeed approval UI |

The same `gf` commands work in both modes. A skill never knows or cares which backend is live.

---

## Detection Order

`gf detect` resolves the mode (first hit wins) and caches it to `.genfeed/ctx.json`:

1. `GENFEED_API_KEY` env set → **api**
2. `genfeed status` CLI exits 0 on PATH → **api**
3. `.genfeed/config.json` names an `apiKeyEnv` whose env var is set → **api**
4. otherwise → **standalone**

`ctx.json` never stores a secret value — only the **name** of the env var holding the key. The key itself stays in the environment or the genfeed CLI keychain.

This gives the "independent but upgradeable" property: the skills work for anyone with no genfeed account, and light up persistence + always-on scheduling + a managed token vault the moment a key is present.

---

## The Contract: Env Vars + stdin/stdout JSON

Loop skills never import this skill's TypeScript. The seam is invoked as a CLI and communicates only through:

- **stdin/stdout JSON** for manifest data
- **environment variables** for tokens (the connector resolves and exports a token; the worker reads it from env, uses it in memory, and never writes it back)

This keeps every skill independently installable — no cross-skill import paths to break.

---

## CLI Reference

Run with `bun run gf.ts <command>` (Bun 1.1+, zero dependencies — uses only Node built-ins and global `fetch`).

```bash
bun run gf.ts detect [--mode standalone|api]   # resolve + cache runtime context
bun run gf.ts create [--thesis "..."] [--stage selected] [--tags a,b] [< trend.json]
bun run gf.ts get <id>
bun run gf.ts list [--stage <stage>] [--tag <tag>] [--limit <n>]
bun run gf.ts save                              # full ContentItem JSON on stdin
bun run gf.ts transition <id> <stage> [--note "..."]
bun run gf.ts next <stage>                       # oldest item waiting in <stage>
bun run gf.ts record-metric <id>                 # Metric JSON on stdin
bun run gf.ts feedback <term>                    # prior-performance multiplier (loop closure)
bun run gf.ts token <platform>                   # resolve a token (env or vault)
```

All commands print JSON to stdout; errors print to stderr and exit non-zero.

---

## The Manifest (ContentItem)

One row tracks an item through the whole loop. Stages:

```
trend_candidate -> selected -> briefed -> remixed -> producing
  -> awaiting_approval -> approved -> scheduled -> posted -> measured -> archived | killed
```

Key fields: `trend` (the originating signal), `thesis` (flagship angle), `brief`, `derivatives[]` (per-platform copy + media refs + postId), `artifacts[]` (generated media), `metrics[]` (performance), `feedbackScore` (0..1, derived from metrics), `tags[]` (pillars + trend terms — how analytics attribute back to trends), and `history[]` (every stage transition).

See `lib/schema.ts` for the full type.

---

## Loop Closure

`feedback <term>` averages `feedbackScore` across all `measured` items tagged with that term and returns a 0..1 multiplier. `trend-scout` multiplies a fresh trend's raw score by `(1 + multiplier)`, so themes that performed before rise to the top of the next cycle. That is the `analytic -> repeat` edge of the loop, implemented in data.

---

## Security

- Standalone tokens are **read** from the environment and **never written** to any file.
- Connected tokens are issued short-lived and scoped by genfeed.ai, used in memory, and never persisted by the connector.
- `ctx.json` and `config.json` store only the **name** of the key's env var, never its value.
- This skill never calls a content/social/model API itself — it only resolves state and tokens. Outbound API calls live in the worker skills, under their own approval gates.

---

## How Other Skills Use It

```bash
# orchestrator picks the next job and hands it to a worker
JOB=$(bun run ../genfeed-connector/gf.ts next selected)

# worker emits a result; orchestrator advances the stage
bun run ../genfeed-connector/gf.ts transition "$ID" remixed --note "atomized to 6 platforms"

# poster resolves a token without ever seeing the long-lived credential
export X_BEARER_TOKEN="$(bun run ../genfeed-connector/gf.ts token x)"
```

If `gf` is not resolvable as a sibling skill, a worker degrades to its own local `.genfeed/` directory using the same on-disk format.