Operator Runbook

Quick Start (Demo Mode)

git clone https://github.com/akshan-main/revcat-agent-advocate.git
cd revcat-agent-advocate
pip install -e .
export DEMO_MODE=true
export ANTHROPIC_API_KEY=sk-ant-...
revcat-advocate demo-run
python -m http.server -d site_output 8000

Quick Start (Real Mode)

git clone https://github.com/akshan-main/revcat-agent-advocate.git
cd revcat-agent-advocate
pip install -e .
export REVENUECAT_API_KEY=sk_your_key
export ANTHROPIC_API_KEY=sk-ant-...
export DEMO_MODE=false
revcat-advocate ingest-docs
revcat-advocate write-content --topic "Your Topic" --type tutorial
revcat-advocate build-site

Safety Gates

Autonomy Model

Signal Pipeline

The supervisor ingests signals from 5 producers, scores them, and acts on the highest-priority signal each cycle. Agent-task issues are handled by a separate event-driven workflow, not the signal pipeline.

Signal Scoring

Each signal is scored: score = impact × urgency × confidence × freshness. Freshness decays linearly from 1.0 to 0.05 over the signal's TTL. The highest-scoring unclaimed signal is acted on.

Deduplication & Expiry

Signals are deduped by (source, url) or title hash. Each signal has a TTL — expired signals are marked and excluded from scoring. This prevents the agent from re-processing stale information.

Agent Tasks (Event-Driven)

Agent tasks are not part of the signal pipeline. They have their own GitHub Actions workflow (agent-task.yml) that triggers when an issue is labeled agent-task:

1. Issue labeled agent-task → workflow triggers immediately
2. Task injected as a signal, claimed directly by ID — no producer ingestion, no scoring queue
3. Supervisor decides the action (including submit_form for browser-based tasks) and executes it
4. Ledger entry recorded
5. Issue closed on success, left open on failure (CLI exits non-zero if task not acted on)

This separation ensures operator tasks get immediate execution without competing against scored signals in the supervisor queue, while retaining access to all supervisor actions including browser automation.

Browser Automation

The supervisor can browse the web via Playwright MCP (pinned to @playwright/mcp@0.0.28). Used for signal enrichment (fetching page content) and form submission.

Community Scanning

The agent monitors developer communities for RevenueCat questions and discussions. All responses stay in draft status — nothing is auto-posted.

Dev.to Closed Loop

Content published to Dev.to feeds engagement data back into the agent's decision-making:

write-content → publish-devto → Dev.to API
    ↓
devto-stats (pulls views, reactions, comments back to Turso)
    ↓
Bandit reward = max(views/500, reactions/20, comments/10)
    ↓
Thompson sampling updates Beta(alpha, beta) priors
    ↓
Next topic selection favors higher-engagement categories

The supervisor calls sync_rewards_from_devto to update bandit priors from Dev.to engagement stats. The autonomous agent core also enforces Dev.to stats sync as a post-cycle step (conditional on has_devto). This creates a self-improving content strategy based on real engagement data.

Memory Pruning

Agent memory grows over time as lessons are recorded each cycle. The pruning system keeps memory useful instead of noisy:

revcat-advocate prune-memory                  # apply default policies
revcat-advocate prune-memory --dry-run         # preview what would be pruned
revcat-advocate prune-memory --max-age 60      # tighter window
revcat-advocate prune-memory --min-confidence 0.5  # stricter quality gate

Reliability Engineering

Pre-Execution Action Firewall

External actions are checked against applicable gates before execution:

External actions are gated by applicable layers. DRY_RUN/ALLOW_WRITES and the tweet critic are enforced in code; the YAML firewall provides additional configurable rules for actions routed through both the supervisor and the agent core.

Supervisor Rate Limits

Per-day limits enforced by the YAML firewall to prevent runaway autonomous actions:

Eval Gates (Post-Production)

Quality thresholds checked after content is produced. Failures trigger rollback:

Failure Categories and Retry Strategy

Rollback Criteria

• Ledger chain break: If verify-ledger reports breaks, the site build includes a red "BROKEN" badge. Deployment proceeds but the break is visible to reviewers.
• Publish gate failure: submit command will not deploy if the letter fails gate checks after max regen attempts. The previous deployed version remains live.
• Tweet rejection: If the critic agent rejects a tweet 3 times, it is logged as "skipped" and never posted. No partial posts.
• Failed run: Every failed run is logged to the ledger with success=0. Failed runs are shown on the scorecard with timestamps for post-mortem.

Eval and Observability

• Hash-chained ledger: Key commands (content generation, experiments, feedback, tweets, agent cycles) produce a RunEntry with inputs, tool calls, sources, outputs, and SHA256 hash linking to the previous entry. Tamper detection is automatic.
• Citation verification: Content verifier HEAD-checks every cited URL, matches quoted snippets against cached doc hashes, and validates code snippet syntax.
• Scorecard metrics: Success rate, word count, citation count, experiment outcomes, and failure log are computed live from the database on every site build.
• Staged rollout: build-site renders locally for inspection. deploy is a separate, explicit command. The submit pipeline gates deployment on publish-gate pass.

Post-Cycle Enforcement

After every autonomous agent cycle, the following actions run in code, not prompt — the agent cannot skip them:

This is a deliberate contract: post_cycle_devto_sync = conditional(has_devto). The agent decides what to create; the code decides what happens after.

Where the Receipts Are

• /content: Posts have a Sources section with cited doc URLs. SHA256 hashes shown when available.
• /experiments: Every experiment has hypothesis, metric, and results.
• /feedback: Feedback items include repro steps and evidence links where available.

Commands

Reproduce a Post

revcat-advocate write-content --topic "Charts API for Agents" --type tutorial
# Output: site_output/content/charts-api-for-agents/index.md
# Includes: outline, citations, code snippets, verification results

Reproduce an Experiment

revcat-advocate run-experiment --name programmatic-seo
# Output: SEO pages in site_output/content/
# DB record in growth_experiments table

Architecture

RevenueCat Docs (LLM Index + .md mirrors)
    -> Hybrid RAG (BM25 + ChromaDB vectors + Contextual AI reranker)
        -> Content Engine (Claude + citation verification)
        -> Growth Engine (experiments + SEO)
        -> Feedback Engine (doc analysis)
        -> Social (Dev.to + Twitter + GitHub/Reddit scanning)
    -> Supervisor (signal-driven OODA loop, 6-hour cycles)
        -> Signal Pipeline (5 producers: GitHub, Reddit, Dev.to, docs, schedule)
        -> Thompson Sampling Bandit (10 topic categories, Beta priors)
        -> Playwright MCP Browser (enrichment + form submission)
        -> Action Firewall (YAML rules + rate limits + eval gates)
    -> Turso (10-table cloud DB, all state)
    -> Ledger (SHA256 hash chain + optional HMAC signing)
    -> Agent Memory (lessons + pruning policies)
    -> MCP Server (22 tools + 3 resources via FastMCP)
    -> Static Site (GitHub Pages)

Claude Code Skills

Clone this repo into any project and get RevenueCat developer tools as Claude Code slash commands. These aren't wrappers. Each skill adds a new capability that combines the agent's ingested doc knowledge base with your actual codebase to solve real developer problems.

Try it

git clone https://github.com/akshan-main/revcat-agent-advocate.git
cd revcat-agent-advocate && pip install -e .

# In Claude Code, inside any project:
/review-rc          # Review your RC integration against docs
/migrate            # Generate migration plan from StoreKit/Stripe/Adapty
/paywall            # Generate paywall UI code for your platform
/debug-webhook      # Paste a webhook payload, get plain-English explanation
/rc-audit           # Full integration audit with scored report
/pricing-strategy   # Pricing optimization based on category benchmarks
/search-docs        # Search ingested RC docs with hybrid RAG
/quiz               # Product comprehension quiz on your code changes

MCP Server Integration

The agent also runs as an MCP server with 22 tools. MCP clients like Claude Desktop and Claude Code can connect and use the agent's capabilities.

Connect via stdio (local)

claude mcp add revcat-agent-advocate -- revcat-advocate mcp-serve

Connect via SSE (remote)

revcat-advocate mcp-serve --transport sse --port 8090
claude mcp add revcat-agent-advocate -t http -- http://localhost:8090/mcp

Available MCP Tools (22)

RevenueCat MCP (upstream)

claude mcp add revenuecat -t http -- https://mcp.revenuecat.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"