Build Prompt — GrowReach Swarm Engagement Engine
What to build
A complete web application implementing the Swarm Engagement Engine — a dashboard feature for coordinating a swarm of 17 AdsPower Reddit profiles to amplify GrowReach promotional posts on Reddit. The app manages campaigns (upvote/comment/question boosts), tracks every action per profile per subreddit, orchestrates timezone-aware scheduling, and enforces 12 anti-detection guardrails.
Context files (read all three before coding)
| # | Document | URL | What it contains |
|---|---|---|---|
| 1 | PRD | https://github.com/rahul-10xers/hermes/blob/main/growreach-reddit-strategy/swarm-engagement-prd.md | Full product requirements: 7 SQLite tables with DDL, 12 strategy playbooks, 12 guardrails (G1-G12), timezone orchestration matrix, shared-IP awareness, question-asker rotation rules, phases (P0-P3), success metrics, open questions |
| 2 | Flow Diagrams | https://github.com/rahul-10xers/hermes/blob/main/growreach-reddit-strategy/swarm-flow-diagrams.md | 6 Mermaid diagrams: master navigation (19 screens), new campaign creation flow, per-action execution lifecycle, question→link conversion flow, gap resolution status, complete clickable-element navigation map |
| 3 | Full Mockup | https://github.com/rahul-10xers/hermes/blob/main/growreach-reddit-strategy/swarm-mockups/swarm-full-mockup.html | Complete HTML mockup with all 19 screens and every navigation path wired with working JS (go()/goBack()). This is the visual spec — match the UI exactly. |
Read all three files completely before writing any code. The PRD defines the data model, the flow diagrams define the user journeys, and the mockup defines the UI. All three must agree.
Existing infrastructure (DO NOT rebuild — reuse)
The swarm engine plugs into an existing system on this Windows VPS:
| Component | File | What it does |
|---|---|---|
| Profile registry | C:\Users\Administrator\adspower-dashboard\profile-registry.json | 19 profiles with username, karma, timezone, IP, bans, status, account age. The swarm reads this for profile assignment. |
| Fetch pipeline | C:\Users\Administrator\adspower-dashboard\fetch-reddit-metrics.py | Opens AdsPower profiles, reads cookies (dual-path CLI→HTTP v2), fetches Reddit about.json/overview.json, detects bans via Matrix API, updates registry + SQLite. Has get_profile_cookies(), open_profile(), close_profile(), curl_get(), fetch_about() functions the swarm engine should import and reuse. |
| Dashboard server | C:\Users\Administrator\adspower-dashboard\dashboard-server.py | Python HTTP server on port 8080, serves the existing dashboard at r.10xers.co. Add swarm endpoints here or create a new server that proxies. |
| AdsPower CLI | Port 50725 (CLI runtime) + 50325 (app) | ads.CMD CLI for profile open/close/cookies. MCP tools available for navigate/click/type/screenshot. |
| SQLite DB | C:\Users\Administrator\adspower-dashboard\reddit_metrics.db | Existing tables: daily_snapshots, daily_comments, daily_posts. Add swarm tables to this same DB. |
| Comment generator | C:\Users\Administrator\hermes-repo\reddit-rpa-prompts\reddit-comment-system-prompt-v4-unified.md | V4 unified prompt (classifier + generator, per-subreddit templates). The swarm uses this to generate sub-matched comments. |
19 screens to build (from the mockup)
The mockup file has all 19 screens as <div class="view" id="v-SCREEN-NAME"> blocks with working go('screen-name') navigation. Build each as a real page or view:
- campaigns — Campaigns list with playbook badges, status, score, View/Abort buttons
- new — New campaign form: type selector, post URL, playbook dropdown, TZ-aware schedule, profile picker with 9 exclusion rules, safety panel
- live — Live execution: timeline, stat cards, actions table with question→link flow
- posts — Post registry: all tracked posts with score sparklines, playbook tags, campaign linkage
- playbooks — Playbook analytics: performance table + 12-playbook catalog
- subs — Subreddit map: profile × subreddit matrix with role cells (P/U/C/Q/B)
- tz — Timezone windows: UTC × timezone availability matrix, shared-IP pairs, optimal launch windows
- health — Profile health: week actions, cooldown, last Q asked, banned subs, status
- campaign-detail — Campaign detail with 5 sub-tabs: Timeline, Actions, Comments & Question thread, Score history, Profile roster
- register-post — Register post form: URL, subreddit auto-detect, playbook, posted-by, product link checkbox
- playbook-detail — Playbook detail: all posts using this playbook, comment strategy, link policy, question types
- sub-detail — Subreddit detail: profiles active, campaigns, posts in this subreddit
- profile-detail — Profile detail with 5 sub-tabs: Action History, Subreddit Activity, Ban History, Question History, Cooldown & Rotation
- rotation — Rotation rules config: G6 caps, G12 Q-rotation, G8 circuit breaker thresholds
- breaker — Circuit breaker log: ban events with recovery status
- q-history — Question-asker history: all Q actions with reply status and stats
- score-history — Score history chart: cross-campaign score comparison, filterable
- export — Export panel: data type, date range, filters, download (JSON/CSV)
- notify — Main account notifications: pending question inbox with reply/mark-replied buttons
7 SQLite tables (DDL in PRD §5.2)
Build these exactly as specified in the PRD:
swarm_posts— every post the swarm has touched (URL, subreddit, posted-by, playbook, score, link status)swarm_playbooks— 12 strategy playbooks (id, name, comment_strategy, link_policy, question_strategy, source_account, expected_score_range)swarm_campaigns— each boost event (post_id FK, type, subreddit, playbook, target_profiles, status, schedule, cap_ratio)swarm_actions— every individual action (campaign_id FK, profile_id, action_type upvote/comment/question, comment_text, comment_url, question_type, main_account_reply_url, score_before/after, verified_at, ban_hit)swarm_profile_subs— profile × subreddit map (profile_id, subreddit, role, total_actions, banned_at)swarm_profile_limits— rotation + circuit breaker (profile_id, week_actions, cooldown_until, consecutive_bans, paused, last_question_* fields)swarm_post_scores— time-series of post score (post_id, checked_at, score, num_comments, upvote_ratio)
Plus indexes as specified in the PRD.
6 API endpoints (PRD §5.3)
| Endpoint | Method | Purpose |
|---|---|---|
/api/swarm/campaigns | GET/POST | List campaigns / Create campaign |
/api/swarm/campaigns/<id> | GET | Campaign detail + actions |
/api/swarm/campaigns/<id>/abort | POST | Stop remaining actions |
/api/swarm/posts | GET | Post registry (filterable) |
/api/swarm/playbooks | GET | Playbook catalog + performance |
/api/swarm/profiles/eligible?subreddit=X | GET | Eligible profiles for a subreddit (applies 9 assignment rules) |
/api/swarm/profiles/subs | GET | Profile-subreddit map |
/api/swarm/profiles/limits | GET | Per-profile limits + cooldowns |
/api/swarm/analytics?group_by=playbook | GET | Performance analytics |
/api/swarm/timezone-windows | GET | Awake/sleep status + optimal windows |
/api/swarm/notify | GET | Pending question notifications |
12 anti-detection guardrails (PRD §4.8 — must enforce in code)
| # | Rule | How to enforce |
|---|---|---|
| G1 | Min 45s stagger between swarm actions on same post | Scheduler enforces min gap in swarm_actions.scheduled_for |
| G2 | Swarm ≤ 30% of post’s early votes | Cap swarm_campaigns.swarm_cap_ratio, check live score before dispatching |
| G3 | No all-upvote behavior — profiles must have mixed vote patterns | Cross-reference with RPA karma-farming activity log |
| G4 | Comments must be value-first, no link-dropping | Validate swarm_actions.comment_text has no URLs before posting |
| G5 | Shared-IP pairs never vote same post < 1h apart | Check profile-registry.json IP field, enforce in scheduler |
| G6 | Max 10 swarm actions/day, max 3 campaigns/week per profile | swarm_profile_limits.week_actions, cooldown_until |
| G7 | Human-like jitter: 30-90s scroll before action | AdsPower automation timing |
| G8 | Ban circuit-breaker: auto-pause on ban | swarm_profile_limits.paused=1, consecutive_bans++ |
| G9 | No swarm in no-promo subs (r/SaaS etc.) | Subreddit risk-level check from growreach-reddit-subreddits-expanded.md |
| G10 | Comment uniqueness per profile | SHA-256 hash of comment_text, check no duplicates in same campaign |
| G11 | No comment on deleted/removed posts | Check swarm_posts.post_status before dispatching |
| G12 | Question-asker rotation: max 1 Q/week, no same Q type in same sub within 14d | swarm_profile_limits.last_question_* fields |
9 profile assignment rules (PRD §4.6)
When auto-assigning profiles to a campaign, apply ALL of these:
- Ban-aware — exclude profiles banned in target sub (check
profile-registry.json→bans[]+swarm_profile_subs.banned_at) - Sleep-aware — skip profiles in local 1am-9am window (check
profile-registry.json→timezone+is_sleep_time()) - Age-aware — accounts <30 days: upvote-only (check
account_created_ts) - Karma-aware — <50 karma: comment-cap only; 200+: eligible for question-asker role
- Timezone-stagger — assign so actions land in each profile’s non-sleep window
- Proxy/IP-aware — shared-IP pairs split to opposite ends of stagger (known pairs: 82.23.94.252 = Reasonable_Owl+Terrible_Risk, 9.142.29.97 = ProfitSoft873+Emotional-Shift-7557)
- Rotation-aware — exclude if cooldown active or weekly cap hit (check
swarm_profile_limits) - Sub-assignment-aware — commenter needs prior activity in target sub; upvoter = any
- Q-rotation-aware — questioner: no same Q type in same sub within 14 days, max 1 Q/week
Question-asker flow (PRD §4.4 — the key monetization path)
This is the most important conversion flow in the system:
- Swarm profile asks a question on the post (e.g., “Do you have a link where we can try it?”)
- Main account gets notified (via
/api/swarm/notifyendpoint + dashboard notification inbox) - Main account replies with growreach.app link
- System records:
swarm_actions.main_account_reply_url,swarm_posts.link_drop_comment_url - Analytics track: Q→link conversion rate, time-to-reply, which question type works best
4 question types: direct_link_request, feature_clarification, comparison_request, pricing_question
Timezone orchestration (PRD §4.7)
4 timezones across 17 profiles: AEST(1), EDT(8), BST(4), PDT(6). Sleep window 1am-9am local.
Optimal campaign launch windows (most profiles awake):
- 18:00-22:00 UTC = 18 profiles awake (EDT+BST+PDT) ← best
- 00:00-02:00 UTC = 15 profiles awake (EDT+PDT+AEST)
- 06:00-12:00 UTC = only 5-7 profiles (avoid)
The scheduler must: check which profiles are awake at the target launch time, recommend delaying if <5 awake, queue sleeping profiles’ actions for when they wake.
Tech stack
| Layer | Technology |
|---|---|
| Frontend | HTML/CSS/JS (single-page app, match the mockup exactly — dark theme, no framework needed, vanilla JS view switching) |
| Backend | Python HTTP server (extend existing dashboard-server.py or create new swarm-engine.py) |
| Database | SQLite (same reddit_metrics.db, add the 7 swarm tables) |
| Execution | AdsPower CLI/MCP (open profile → navigate → click/type → verify → close) |
| Comment generation | V4 unified prompt via LLM API (Qwen or equivalent) |
| Profile data | profile-registry.json (read-only for assignment rules) |
| Proxy | Existing AdsPower proxies per profile (no new proxies needed) |
Build order (phases from PRD §5.4)
P0 (safe pilot) — build first:
- SQLite tables (all 7, with indexes)
/api/swarm/campaigns(GET + POST)/api/swarm/profiles/eligible?subreddit=X(GET — apply 9 assignment rules)- Campaigns list screen + New Campaign form screen
- UPVOTE_BOOST only, manual profile selection
- Basic Campaign Detail (actions table only)
- Test with 1 post, 5 profiles
P1 (hybrid pilot) — build second:
- Comment generation via V4 prompt
- Question-asker flow (ask → notify → reply → record)
- Ban circuit-breaker (G8)
- Timezone-aware scheduling
- Live Execution screen with timeline
- Profile Health screen with cooldowns
P2 (productize) — build third:
- All 19 screens from the mockup
- All API endpoints
- Post Registry + Playbook Analytics + Subreddit Map + Timezone Windows
- Score history tracking (15min → hourly → daily sampling)
- Export panel
- Rotation rules config
- Circuit breaker log + Q-asker history
Critical constraints
- Do NOT modify the existing fetch pipeline (
fetch-reddit-metrics.py) — import its functions, don’t rewrite it - Do NOT commit secrets —
start-adspower-cli.batcontains the API key and is git-ignored - Test suite must pass —
python dashboard-tests.py --live(168 tests) before any commit - Match the mockup UI exactly — the mockup is the visual spec. Same dark theme, same colors, same components, same navigation flow
- SQLite only — no Postgres, no Redis, no external databases
- Single server — serve swarm pages from the same port 8080 as the existing dashboard (or a new port if cleaner, but not a different machine)
- Windows VPS — all paths are
C:\Users\Administrator\adspower-dashboard\, Python 3.11, bash via git-bash
How to verify your build
- Open the mockup HTML file in a browser — click through all 19 screens, verify navigation works
- Read the PRD §5.2 — create all 7 SQLite tables with exact DDL
- Read PRD §4.6 — implement all 9 assignment rules in the profile eligibility endpoint
- Read PRD §4.8 — enforce all 12 guardrails in the scheduler
- Read flow diagram 3 (Campaign Execution) — implement the per-action lifecycle: sleep check → open → cookies → navigate → jitter → ban check → action → verify → score → close → DB write
- Run
python dashboard-tests.py --live— existing 168 tests must still pass - Create a test campaign with 1 profile, verify the action executes end-to-end
Questions for Rahul (PRD §7.2 — must be answered before P1)
These are open questions that affect the build. If you (the coding agent) can’t answer them, ask Rahul:
- Who is the main GrowReach account that posts? (new founder account, existing high-karma account, or fresh “Rahul” account?)
- Is the swarm allowed to comment on competitor comparison threads?
- Max swarm size per post? (proposed: 8-12, G2 guardrail)
- Should swarm comments ever mention GrowReach by name? (proposed: 0% in first 60 days)
- Budget for comment-gen LLM per campaign?
- Should RPA karma-farming subs be kept strictly separate from ICP campaign subs per profile?
- For the question-asker role, should the main account always reply with a link or sometimes just answer?