SnitchFeed

Build a personal social-listening tool inspired by SnitchFeed, starting from an empty folder. This is an honest consolation build: it watches free, open feeds only and does not replace SnitchFeed's aggregation, tuned scoring, or automation layer.

Stack (use exactly this): Next.js 15 + TypeScript + PostgreSQL + BullMQ + Redis.

Core loop:
- Let me define keywords/brand terms and a poll interval per source.
- Poll Reddit's API, Bluesky's search, and Hacker News's Algolia API via a BullMQ worker on a cron schedule; dedupe matches by source + id.
- Score each match's relevance and sentiment with one LLM call (OpenAI or Anthropic); store both alongside the raw post.
- Push new matches to a Slack or Discord incoming webhook.
- Smallest polished UI that closes the loop: add a keyword, watch matches stream in, mark them read or irrelevant.

Rules:
- Single-user and private by default; all data in local Postgres.
- Every API key, app password, and webhook URL in .env, with .env.example provided; never log secrets; validate untrusted input.
- No analytics, telemetry, ads, or accounts beyond what's declared.
- Clear empty, loading, validation, success, and failure states.

Deliberately out of scope (do not fake these): X/Twitter and LinkedIn coverage, cross-platform aggregation and dedup at scale, continuously tuned relevance scoring and noise auditing, a live real-time dashboard, and any agent-facing API/MCP layer.

Finish line:
- Unit tests for the dedupe logic and the scoring call, plus one end-to-end smoke test: keyword added, fake match flows through to a webhook call.
- README covering setup, the exact free APIs used and their rate limits, and this build's limitations versus a paid multi-source listening tool.
- Scripts for install, development, test, build, and a production-style local run.
- Run the tests and the build before finishing; fix errors rather than describing them.

# AGENTS.md — Build guide for SnitchFeed

## Project scope
Poll a couple of free, open feeds (Reddit's API, Bluesky's firehose, Hacker News's Algolia API) for keyword matches, run each hit through an LLM for a rough relevance/sentiment tag, and push matches to a Slack or Discord webhook.

Catalogue verdict: no. A weekend build gets you a keyword matcher; SnitchFeed is a signal refinery. Five platforms in one stream (Reddit, X, LinkedIn, Bluesky, Hacker News), run through layered filtering: boolean queries, AI scoring for relevance, sentiment, and buying intent, and noise auditing that keeps trimming. What comes out is a shortlist of threads worth answering, delivered where you act: Slack, Discord, a live dashboard, or your own AI agent via MCP and REST API. To be fair: if you only care about Reddit and Hacker News, a DIY build gets you further than the verdict suggests. It's the X and LinkedIn coverage, the cross-platform aggregation, and the tuned scoring that a one-shot build can't reach.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Reddit API app credentials (free)
- Bluesky app password for firehose/search access
- Hacker News Algolia API (no key required)
- OpenAI/Anthropic API key for relevance & sentiment tagging
- hosted Postgres + a cron worker or queue
- Slack/Discord incoming webhook URL(s)

## Stack and architecture
- Stack (use exactly this): Next.js 15 + TypeScript + PostgreSQL + BullMQ + Redis.
- Model sources or channels, posts, dated observations, drafts, and reports; keep stable source IDs and timestamps.
- Interface for this social listening & buying-intent signals workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Clear empty, loading, validation, success, and failure states.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: X/Twitter and LinkedIn coverage entirely (neither has a free public search API), so two of the five platforms are simply gone.

## Agent implementation rules
- Project rule, data: Model sources or channels, posts, dated observations, drafts, and reports; keep stable source IDs and timestamps.
- Project rule, behavior: Smallest polished UI that closes the loop: add a keyword, watch matches stream in, mark them read or irrelevant.
- Project rule, recovery: Clear empty, loading, validation, success, and failure states.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this social listening & buying-intent signals operation with sample or user-owned data: Smallest polished UI that closes the loop: add a keyword, watch matches stream in, mark them read or irrelevant.
- Show a concrete result or export: Find buyers at peak intent: 24/7 monitoring of Reddit, X, LinkedIn, Bluesky, and Hacker News, AI-scored and delivered to your team or your agents in real time.
- State the practical limit: X/Twitter and LinkedIn coverage entirely (neither has a free public search API), so two of the five platforms are simply gone.

## Engineering roadmap
1. Phase 1, architecture and data: Stack (use exactly this): Next.js 15 + TypeScript + PostgreSQL + BullMQ + Redis. Model sources or channels, posts, dated observations, drafts, and reports; keep stable source IDs and timestamps.
2. Phase 2, implement: Smallest polished UI that closes the loop: add a keyword, watch matches stream in, mark them read or irrelevant.
3. Phase 3, implement: Poll a couple of free, open feeds (Reddit's API, Bluesky's firehose, Hacker News's Algolia API) for keyword matches, run each hit through an LLM for a rough relevance/sentiment tag, and push matches to a Slack or Discord webhook.
4. Phase 4, review and output: Find buyers at peak intent: 24/7 monitoring of Reddit, X, LinkedIn, Bluesky, and Hacker News, AI-scored and delivered to your team or your agents in real time.
5. Phase 5, recovery and acceptance: Clear empty, loading, validation, success, and failure states. Verify this invariant with a saved fixture: An API gap must be labelled missing; a replayed export cannot double-count the same observation. State the practical limit: X/Twitter and LinkedIn coverage entirely (neither has a free public search API), so two of the five platforms are simply gone.

## Paid-product capabilities outside this build
- X/Twitter and LinkedIn coverage entirely (neither has a free public search API), so two of the five platforms are simply gone
- one aggregated, deduplicated stream across five platforms instead of five half-working pollers
- the noise-reduction stack: boolean query grammar, AI fit scores, sentiment, intent tags, and automated noise auditing that keeps tuning what gets through
- a real-time dashboard with curated feeds, saved views, and analytics reports instead of a Slack ping you learn to ignore
- an agent-native surface: an MCP server and public REST API so your own AI agents can search mentions, create listeners, and act on intent directly

## Implementation prompt
Build a personal social-listening tool inspired by SnitchFeed, starting from an empty folder. This is an honest consolation build: it watches free, open feeds only and does not replace SnitchFeed's aggregation, tuned scoring, or automation layer.

Stack (use exactly this): Next.js 15 + TypeScript + PostgreSQL + BullMQ + Redis.

Core loop:
- Let me define keywords/brand terms and a poll interval per source.
- Poll Reddit's API, Bluesky's search, and Hacker News's Algolia API via a BullMQ worker on a cron schedule; dedupe matches by source + id.
- Score each match's relevance and sentiment with one LLM call (OpenAI or Anthropic); store both alongside the raw post.
- Push new matches to a Slack or Discord incoming webhook.
- Smallest polished UI that closes the loop: add a keyword, watch matches stream in, mark them read or irrelevant.

Rules:
- Single-user and private by default; all data in local Postgres.
- Every API key, app password, and webhook URL in .env, with .env.example provided; never log secrets; validate untrusted input.
- No analytics, telemetry, ads, or accounts beyond what's declared.
- Clear empty, loading, validation, success, and failure states.

Deliberately out of scope (do not fake these): X/Twitter and LinkedIn coverage, cross-platform aggregation and dedup at scale, continuously tuned relevance scoring and noise auditing, a live real-time dashboard, and any agent-facing API/MCP layer.

Finish line:
- Unit tests for the dedupe logic and the scoring call, plus one end-to-end smoke test: keyword added, fake match flows through to a webhook call.
- README covering setup, the exact free APIs used and their rate limits, and this build's limitations versus a paid multi-source listening tool.
- Scripts for install, development, test, build, and a production-style local run.
- Run the tests and the build before finishing; fix errors rather than describing them.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.