chnjinlei/hive
1
0
Fork 0
Code Issues Pull Requests Actions 41 Packages Projects Releases Wiki Activity

fix: simplify game plan

Browse Source
This commit is contained in:
Timothy
2026-03-04 19:15:27 -08:00
parent 93e270dafb
commit c7a47c71f0
8 changed files with 247 additions and 867 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/integration-bounty.yml
+3 -8
View File
@@ -16,14 +16,9 @@ body:
attributes:
label: Bounty Type
options:
- "Smoke Test (10 pts)"
- "Agent Test Report (30 pts)"
- "Edge Case Report (15 pts)"
- "Write README (20 pts)"
- "Add Health Checker (25 pts)"
- "Add Health Check Endpoint (10 pts)"
- "Bug Fix (40 pts)"
- "Complete Promotion Checklist (50 pts)"
- "Test a Tool (20 pts)"
- "Write Docs (20 pts)"
- "Code Contribution (30 pts)"
- "New Integration (75 pts)"
validations:
required: true
docs/bounty-program/README.md
+71 -288
View File
@@ -1,314 +1,111 @@
# Integration Bounty Program
Gamified contribution program for expanding and hardening Aden's integration ecosystem. Community members earn points by testing, documenting, and building integrations — with monetary rewards unlocked at the Core Contributor tier.
Earn XP, Discord roles, and money by testing, documenting, and building integrations for the Aden agent framework.
## Why Contribute?
### Visible Status
**Your name in the product.** When you promote a tool to verified, your GitHub handle goes in the tool's README under `Contributed by`. Every agent that uses that integration carries your name — permanent credit in a production codebase.
Every Discord message you send shows your tier role and badges. When someone asks a question in `#integrations-help` and you answer it with a **Core Contributor** badge, people listen. Your role is earned, not bought.
**Visible status.** Your Discord tier role is earned, not bought. When you answer a question in `#integrations-help` with a Core Contributor badge, people listen.
### Your Name in the Product
**Weekly races.** Every Monday the bot posts the leaderboard. Top 3 get medal emojis. The best work gets highlighted in announcements.
When you promote a tool to verified, your GitHub handle goes in the tool's README under `Contributed by`. Every agent that uses that integration carries your name. This is permanent credit in a production codebase — not a profile badge that disappears.
**The path to paid.** Core Contributor unlocks real money. It takes sustained quality work across testing, docs, and code — the scarcity makes it matter.
### Weekly Races
## How It Works
Every Monday the bot posts the leaderboard. The top 3 get medal emojis next to their name all week. There's a `#integration-showcase` channel where people demo agents using the tools they tested — the best demos get pinned and highlighted in announcements.
### The Path to Paid
Core Contributor unlocks real money. But you can't buy your way in — it takes sustained quality work across testing, docs, and code. The scarcity makes it matter. When you see someone with Core Contributor status, you know they've shipped real integrations.
### Streaks
Consecutive weeks with at least one bounty completion earns streak multipliers:
| Streak | Multiplier | Example |
|--------|-----------|---------|
| 2 weeks | 1.1x | 20pt README = 22 pts |
| 4 weeks | 1.25x | 30pt agent test = 37 pts |
| 8+ weeks | 1.5x | 75pt new tool = 112 pts |
Missing a week resets the streak. This rewards consistency over bursts.
### Achievement Badges
Unlocked permanently and displayed on your Discord profile via bot roles:
| Badge | Requirement | Role Color |
|-------|-------------|------------|
| **First Blood** | Complete your first bounty | — |
| **Bug Hunter** | Find and fix 3 bugs via testing | Red |
| **Docs Champion** | Write 5 tool READMEs | Yellow |
| **Health Inspector** | Add 5 health checkers | Orange |
| **Promoter** | Promote a tool from unverified to verified | Gold |
| **Full Stack** | Complete at least 1 bounty of every type | Rainbow |
| **Ironman** | 8-week contribution streak | — |
1. Pick a bounty from the [GitHub issues board](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22)
2. Claim it by commenting on the issue
3. Do the work and submit a PR (or test report)
4. A maintainer reviews and merges
5. You automatically get XP in Discord via Lurkr
6. At certain levels, you unlock roles. At the top tier, you unlock paid bounties.
## Tiers
| Tier | How to Reach | What You See | Rewards |
|------|-------------|--------------|---------|
| **Agent Builder** | Join Discord + start testing | Bounty board with point values | Discord role, community recognition, achievement badges |
| **Open Source Contributor** | First merged PR | Bounty board with point values | Discord role, listed in CONTRIBUTORS.md, name in tool READMEs |
| **Core Contributor** | Maintainer-approved promotion | Bounty board with **dollar values** | Monetary payout per completed bounty, private dev channel |
| Tier | How to Reach | Rewards |
|------|-------------|---------|
| **Agent Builder** | ~500 XP (Lurkr level 5) | Discord role, bounty board access |
| **Open Source Contributor** | ~2,000 XP (Lurkr level 15) | Discord role, name in CONTRIBUTORS.md and tool READMEs |
| **Core Contributor** | Maintainer-approved | Monetary payout per bounty, private `#bounty-payouts` channel |
### Core Contributor Promotion
Lurkr auto-assigns the first two roles. Core Contributor requires sustained, quality contributions across multiple bounty types and a maintainer vouching for you.
Core Contributor status is **maintainer-approved** and requires:
## Bounty Types
1. **Sustained contribution** — consistent activity over multiple weeks, not a one-time burst
2. **Breadth** — contributions across multiple activity types (not just 20 READMEs)
3. **Quality** — history of clean PRs that pass CI without excessive back-and-forth
4. **Maintainer nomination** — at least one maintainer vouches for the contributor
| Type | Label | Points | What You Do |
|------|-------|--------|-------------|
| **Test a tool** | `bounty:test` | 20 | Test with a real API key, submit a report with logs |
| **Write docs** | `bounty:docs` | 20 | Write a README following the [template](templates/tool-readme-template.md) |
| **Code contribution** | `bounty:code` | 30 | Add health checker, fix a bug, or improve an integration |
| **New integration** | `bounty:new-tool` | 75 | Build a complete integration from scratch |
Core Contributors see dollar values on bounty issues via a private Discord channel. Payouts happen per completed bounty after the PR is merged and approved by a maintainer.
## Point System
### Testing (Highest Priority)
These are the most valuable contributions — testing integrations with real API keys and real agents is the bottleneck for promoting tools from unverified to verified.
| Activity | Points | Requirements |
|----------|--------|-------------|
| **Smoke Test** | 10 | Run a tool with a real API key, submit a pass/fail report with logs |
| **Agent Test Report** | 30 | Build an agent using an unverified tool, submit a structured test report with session ID |
| **Edge Case Report** | 15 | Document a specific edge case (rate limits, auth expiry, malformed data, etc.) |
| **Live Demo** | 25 | Record a short video/GIF of an integration working in an agent |
### Code Contributions
| Activity | Points | Requirements |
|----------|--------|-------------|
| **Bug Fix PR** | 40 | Fix a bug found during testing, merged PR |
| **Add Health Checker** | 25 | Implement health check class + register in HEALTH_CHECKERS, merged PR |
| **Add health_check_endpoint** | 10 | Research correct endpoint, add to CredentialSpec, merged PR |
| **Write README** | 20 | Add missing README following the [tool README template](templates/tool-readme-template.md), merged PR |
| **Complete Promotion Checklist** | 50 | Finish all items on the [promotion checklist](promotion-checklist.md) for a tool, merged PR |
| **New Integration** | 75 | Full implementation (tool + credential spec + tests + docs), merged PR |
### Community
| Activity | Points | Requirements |
|----------|--------|-------------|
| **PR Review** | 15 | Substantive code review on an integration PR (not just "LGTM") |
| **Help in Discord** | 5 | Answer an integration question (mod-verified) |
| **Propose Integration** | 5 | File a well-structured `[Integration]:` issue per existing template |
Promoting a tool from unverified to verified is the final step — submit a PR moving it from `_register_unverified()` to `_register_verified()` after the [promotion checklist](promotion-checklist.md) is complete.
## Quality Gates
Points are only awarded after quality verification:
- **PRs** must be merged by a maintainer (not self-merged)
- **Test reports** must follow the [test report template](templates/agent-test-report-template.md) with logs or session ID
- **READMEs** must follow the [tool README template](templates/tool-readme-template.md)
- **Claim before you start** — comment on the issue, wait for assignment
- No self-review, no splitting one change across multiple PRs, no AI-only submissions without verification
- **PRs**: Must be merged by a maintainer (not self-merged)
- **Test reports**: Must follow the [test report template](templates/agent-test-report-template.md) with reproducible evidence (logs, session ID, screenshots)
- **Health checkers**: Must pass CI (`uv run pytest tools/tests/test_credential_registry.py`)
- **READMEs**: Must follow the [tool README template](templates/tool-readme-template.md)
- **Reviews**: Must include actionable feedback, not just approval
- **Bounties are claimed before work starts** — comment on the issue to claim, wait for maintainer assignment
### Anti-Gaming Rules
- No self-review on PRs
- A different maintainer must approve bounty completion than the one who created it
- Duplicate or near-duplicate submissions are rejected
- Low-effort submissions (copy-pasted from AI without verification) are rejected and may result in point deduction
- Splitting a single change across multiple PRs to farm points is not allowed
## Bounty Issues
Integration bounties are tracked as GitHub Issues with specific labels.
### Labels
## Labels
| Label | Color | Meaning |
|-------|-------|---------|
| `bounty:smoke-test` | `#0E8A16` (green) | Run tool with real API key, report results |
| `bounty:agent-test` | `#1D76DB` (blue) | Test tool in a real agent workflow |
| `bounty:test` | `#1D76DB` (blue) | Test a tool with a real API key |
| `bounty:docs` | `#FBCA04` (yellow) | Write or improve documentation |
| `bounty:health-check` | `#D93F0B` (orange) | Add health check endpoint or checker |
| `bounty:bug-fix` | `#B60205` (red) | Fix a discovered bug |
| `bounty:code` | `#D93F0B` (orange) | Health checker, bug fix, or improvement |
| `bounty:new-tool` | `#6F42C1` (purple) | Build a new integration from scratch |
| `bounty:promote` | `#C2A000` (gold) | Complete full promotion checklist |
| `difficulty:easy` | `#BFD4F2` | Good first contribution |
| `difficulty:medium` | `#D4C5F9` | Requires some familiarity |
| `difficulty:hard` | `#F9D0C4` | Significant effort or expertise needed |
### Bounty Issue Structure
Each bounty issue includes:
- **Activity type** (label)
- **Difficulty** (label)
- **Point value** (visible to all in issue body)
- **Dollar value** (visible only to Core Contributors via private Discord channel)
- **Acceptance criteria** (what "done" looks like)
- **Relevant files** (links to the tool directory, credential spec, etc.)
See the [bounty issue template](../.github/ISSUE_TEMPLATE/integration-bounty.yml) for the standard format.
## Discord Structure
## Discord
```
#integrations-announcements — New bounties, tool promotions, leaderboard updates
#integrations-testing — Coordinate who's testing what, share test reports
#integrations-help — Get help with credential setup, tool development
#integration-showcase — Demos of agents using integrations
# Private (Core Contributors only)
#bounty-payouts — Dollar values, payout tracking, claims
#integrations-announcements — Bounties, leaderboard, tool promotions (bot + admin only)
#integrations-help — Questions, testing coordination, showcases
#bounty-payouts — Dollar values and payout tracking (Core Contributors only)
```
## Leaderboard
Weekly leaderboard posted to `#integrations-announcements`:
- Top 10 contributors by points (rolling 30 days)
- Top 10 contributors all-time
- Recently promoted tools (unverified -> verified)
- Number of open bounties by type
Weekly leaderboard auto-posts to `#integrations-announcements` every Monday. Top 3 get medal emojis. Check your rank anytime with `/rank` in Discord.
Tracking is done via GitHub labels on merged PRs and closed issues. Maintainers tag completed work with the appropriate `bounty:*` label and contributor handle.
XP comes from two sources: GitHub bounties (auto-pushed on PR merge) and Discord activity in `#integrations-help`.
## Launch Plan: The 55-Tool Blitz
A 2-week sprint to get all 55 unverified tools tested, documented, and health-checked. All phases overlap — everything drops at once and runs in parallel.
A 2-week sprint to get all 55 unverified tools tested, documented, and health-checked.
### Day 1: Launch Everything
### Day 1: Post Everything
Post all bounties simultaneously:
- **41 `bounty:docs` issues** — tools missing READMEs, `difficulty:easy`, 20 pts each
- **40 `bounty:code` issues** — tools missing health checkers, `difficulty:medium`, 30 pts each
- **55 `bounty:test` issues** — one per unverified tool, `difficulty:medium`, 20 pts each
- **41 `bounty:docs` issues** — tools missing READMEs, `difficulty:easy`, 20 pts each. Provide the [tool README template](templates/tool-readme-template.md)
- **40 `bounty:health-check` issues** — tools missing health checkers, `difficulty:medium`, 25 pts each. Include example health checker code
- **55 `bounty:agent-test` issues** — one per unverified tool, `difficulty:medium`, 30 pts each. Provide a template agent to swap tools into
### Week 1–2
### Week 1: Blitz Week
- All bounty types are open — contributors self-select based on skill and interest
- Daily progress updates in `#integrations-announcements` ("12 READMEs done, 38 to go")
- **Mid-week milestone:** if 20+ docs are merged, announce "Health Check Bonus Weekend" — 1.5x points on `bounty:health-check` for Sat/Sun
### Week 2: Promotion Push
- Post `bounty:promote` issues for tools that have completed docs + health checks + testing
- `difficulty:hard`, 50 points each
- The contributor who completes the final checklist item gets the promotion bonus
- Each promoted tool gets an announcement in `#integrations-announcements`
- **Day 14 wrap-up:** final leaderboard, shoutouts for top contributors, recap of tools promoted
All bounty types open in parallel. Contributors self-select. Daily progress updates in `#integrations-announcements`. Day 14 wrap-up with final leaderboard and shoutouts.
## Automation
The bounty program runs on **GitHub Actions + Lurkr bot + Discord webhooks**. GitHub Actions calculate points from merged PRs, push XP to Lurkr via its API, and post notifications. Lurkr handles the Discord leveling, leaderboard display, and automatic role assignments.
### How It Works
```
PR merged with bounty:* label
→ GitHub Action fires bounty-tracker.ts
→ Script calculates points from label
→ Script resolves GitHub → Discord ID via contributors.yml
→ Script calls Lurkr API: PATCH /levels/{guild}/users/{user} (+XP)
→ Lurkr auto-assigns role rewards at XP thresholds
→ Script posts Discord webhook notification to #integrations-announcements
→ GitHub Action runs bounty-tracker.ts
→ Calculates points from label
→ Resolves GitHub → Discord ID via contributors.yml
→ Pushes XP to Lurkr API
→ Posts notification to #integrations-announcements
```
One system, one leaderboard, one set of roles. Discord activity XP and GitHub bounty XP flow into the same Lurkr leveling system.
See the [Setup Guide](setup-guide.md) for full configuration (Lurkr, webhooks, secrets, labels).
### GitHub Actions
### Identity Linking
| Workflow | Trigger | What It Does |
|----------|---------|-------------|
| `bounty-completed.yml` | PR merged with `bounty:*` label | Calculates points, pushes XP to Lurkr, posts Discord notification |
| `weekly-leaderboard.yml` | Every Monday 9:00 UTC (or manual) | Generates leaderboard from all merged bounty PRs, posts to Discord |
Both use `scripts/bounty-tracker.ts` (Bun/TypeScript) which:
- Reads `bounty:*` labels from merged PRs to calculate points
- Resolves GitHub username → Discord ID via `contributors.yml`
- Calls Lurkr API to atomically increment XP: `PATCH /levels/{guildId}/users/{userId}` with `{"xp": {"increment": N}}`
- Posts formatted messages to Discord via webhook
### Lurkr Bot Setup
[Lurkr](https://lurkr.gg/) is a free, no-paywall leveling bot with a full REST API that accepts external XP pushes — the only major leveling bot that supports this.
#### 1. Invite Lurkr to your Discord server
Go to https://lurkr.gg/ and invite the bot.
#### 2. Enable leveling
```
/levels enable
```
#### 3. Configure XP for Discord activity
Lurkr will also award XP for regular Discord messages. Configure this so Discord engagement and GitHub bounties both feed into the same system:
- Set message XP range (e.g., 15-25 XP per message)
- Set cooldown (e.g., 60 seconds — prevents spam farming)
- Optionally boost XP in `#integrations-help` and `#integrations-testing` channels so helping others earns more
```
/levels set-xp min:15 max:25
/levels set-cooldown seconds:60
/levels multiplier channel:#integrations-help multiplier:2
/levels multiplier channel:#integrations-testing multiplier:1.5
```
#### 4. Configure role rewards
Map Lurkr levels to your existing Discord tiers. The XP thresholds should be calibrated so that a mix of Discord activity and GitHub bounties is needed to level up.
| Lurkr Level | XP Threshold | Discord Role | How to Reach |
|-------------|-------------|-------------|-------------|
| 5 | ~500 XP | **Agent Builder** | A few bounties or active Discord participation |
| 15 | ~2,000 XP | **Open Source Contributor** | Sustained bounty contributions |
| 30 | ~5,000 XP | Core Contributor *eligible* | Significant sustained contribution |
Note: **Core Contributor** role is still manually assigned by maintainers (since it involves money). Lurkr level 30 signals eligibility, not automatic promotion.
Add role rewards in the Lurkr dashboard or via commands:
```
/levels role-reward add level:5 role:@Agent Builder
/levels role-reward add level:15 role:@Open Source Contributor
```
Achievement badge roles (First Blood, Bug Hunter, etc.) are added manually by maintainers when someone qualifies — these are not level-based.
#### 5. Generate a Read/Write API key
- Go to https://lurkr.gg/ and log in
- Navigate to your profile / API settings
- Create a **Read/Write** API key (not read-only — we need PATCH access)
- Copy the key
#### 6. Add secrets to GitHub repository
Add three secrets in **Repo Settings > Secrets and variables > Actions**:
| Secret | Value |
|--------|-------|
| `DISCORD_BOUNTY_WEBHOOK_URL` | Discord webhook URL for `#integrations-announcements` |
| `LURKR_API_KEY` | Your Lurkr Read/Write API key |
| `LURKR_GUILD_ID` | Your Discord server ID |
To find your server ID: Enable Developer Mode in Discord (Settings > Advanced), then right-click the server name > Copy Server ID.
#### 7. Create the labels and start posting bounties
```bash
./scripts/setup-bounty-labels.sh
```
That's it. When a maintainer merges a PR with a `bounty:*` label, the contributor automatically gets:
- XP added to their Lurkr level
- A notification in `#integrations-announcements` with their new level
- Role upgrades when they cross level thresholds
### Identity Linking (GitHub ↔ Discord)
Contributors link their accounts by adding themselves to `contributors.yml` at the repo root:
Contributors link GitHub ↔ Discord by adding themselves to `contributors.yml`:
```yaml
contributors:
@@ -317,53 +114,39 @@ contributors:
name: Jane Doe
```
This is intentionally a file-in-repo approach (not a database) because:
- It's version-controlled and auditable
- Adding yourself is a PR — which is itself a contribution
- No bot infrastructure needed for identity storage
- Maintainers can review and approve linkages
**To find your Discord ID:** Enable Developer Mode in Discord Settings > Advanced, then right-click your name > Copy User ID.
**Important:** Contributors who haven't linked their Discord ID in `contributors.yml` will still get bounty notifications on GitHub, but won't receive Lurkr XP or Discord pings. The notification will remind them to link.
Without this link, bounties are still tracked but Lurkr can't push XP to your Discord account.
### What Handles What
| Concern | Handled By | How |
|---------|-----------|-----|
| Bounty point calculation | GitHub Actions | `bounty-completed.yml` reads PR labels |
| XP push to Discord | GitHub Actions → Lurkr API | `PATCH /levels/{guild}/users/{user}` with `{"xp": {"increment": N}}` |
| XP push to Discord | GitHub Actions → Lurkr API | `PATCH /levels/{guild}/users/{user}` |
| Discord engagement XP | Lurkr bot | Native message XP (configurable per-channel) |
| Leaderboard | Lurkr bot | Built-in `/levels leaderboard` + web leaderboard |
| Weekly announcement | GitHub Actions | `weekly-leaderboard.yml` posts via webhook |
| Agent Builder role | Lurkr bot | Auto-assigned at level 5 via role reward |
| OSS Contributor role | Lurkr bot | Auto-assigned at level 15 via role reward |
| Core Contributor role | Maintainer | Manual (involves money, level 30 = eligible) |
| Achievement badges | Maintainer | Manual role assignment when criteria met |
| Streak tracking | GitHub Actions | `bounty-tracker.ts` calculates from PR merge dates |
| Leaderboard | Lurkr bot + GitHub Actions | `/levels leaderboard` + weekly webhook post |
| Agent Builder role | Lurkr bot | Auto-assigned at level 5 |
| OSS Contributor role | Lurkr bot | Auto-assigned at level 15 |
| Core Contributor role | Maintainer | Manual (involves money) |
| Identity linking | contributors.yml | PR-based, reviewed by maintainers |
| Discord notifications | GitHub Actions | Webhook post to `#integrations-announcements` |
## Guides
- **[Setup Guide](setup-guide.md)** — Complete admin setup from zero to running (30 min)
- **[Game Master Manual](game-master-manual.md)** — Maintainer operations: posting bounties, reviewing work, managing tiers, anti-gaming
- **[Contributor Guide](contributor-guide.md)** — Everything a contributor needs to start earning XP and completing bounties
- **[Setup Guide](setup-guide.md)** — Admin setup from zero to running
- **[Game Master Manual](game-master-manual.md)** — Maintainer operations
- **[Contributor Guide](contributor-guide.md)** — Everything a contributor needs to start
## Reference
- [Integration Promotion Checklist](promotion-checklist.md) — Formal criteria for unverified -> verified
- [Tool README Template](templates/tool-readme-template.md) — Standard format for tool documentation
- [Agent Test Report Template](templates/agent-test-report-template.md) — Standard format for test reports
- [Building Tools Guide](../tools/BUILDING_TOOLS.md) — How to build integrations
- [Parent Issue #2805](https://github.com/adenhq/hive/issues/2805) — Master integration tracking issue
- [Lurkr API Docs](https://lurkr.gg/docs/api) — API reference for XP push
- [Lurkr Leveling Setup](https://lurkr.gg/docs/guides/setting-up-server-leveling) — Bot configuration guide
- [Promotion Checklist](promotion-checklist.md) — Criteria for unverified → verified
- [Tool README Template](templates/tool-readme-template.md)
- [Agent Test Report Template](templates/agent-test-report-template.md)
- [Building Tools Guide](../tools/BUILDING_TOOLS.md)
- [Lurkr API Docs](https://lurkr.gg/docs/api)
### Automation Files
- `.github/workflows/bounty-completed.yml` — PR merge → Lurkr XP push + Discord notification
- `.github/workflows/bounty-completed.yml` — PR merge → XP push + Discord notification
- `.github/workflows/weekly-leaderboard.yml` — Monday leaderboard post
- `scripts/bounty-tracker.ts` — Point calculation, Lurkr API integration, Discord formatting
- `scripts/bounty-tracker.ts` — Point calculation, Lurkr API, Discord formatting
- `scripts/setup-bounty-labels.sh` — One-time label setup
- `contributors.yml` — GitHub ↔ Discord identity mapping
docs/bounty-program/contributor-guide.md
+53 -192
View File
@@ -1,53 +1,29 @@
# Contributor Guide — Integration Bounty Program
Welcome. This is a program where you earn XP, Discord roles, and eventually real money by testing and building integrations for the Aden agent framework.
Earn XP, Discord roles, and eventually real money by testing and building integrations for the Aden agent framework.
## How It Works
1. You pick a bounty from the [GitHub issues board](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22)
2. You claim it by commenting on the issue
3. You do the work and submit a PR (or test report)
4. A maintainer reviews and merges
5. You automatically get XP in Discord via Lurkr, and your level goes up
6. At certain levels, you unlock roles. At the top tier, you unlock paid bounties.
## Getting Started (10 min)
## Getting Started
### 1. Link your GitHub and Discord
Fork this repo and add yourself to `contributors.yml`:
Add yourself to `contributors.yml` at the repo root:
```yaml
contributors:
# ... existing entries
- github: your-github-username
discord: "your-discord-id"
name: Your Name
```
To find your Discord ID:
1. Open Discord Settings > Advanced > Enable **Developer Mode**
2. Right-click your name in any channel > **Copy User ID**
To find your Discord ID: Discord Settings > Advanced > Enable **Developer Mode**, then right-click your name > **Copy User ID**.
Submit this as a PR with title: `docs: link @your-github to Discord`
Submit as a PR. Without this link, Lurkr can't push XP to your Discord account.
**Why this matters:** Without this link, you'll still get points tracked, but Lurkr can't push XP to your Discord account and you won't get role upgrades or pings.
### 2. Pick your first bounty
### 2. Join the Discord channels
Browse [GitHub Issues with bounty labels](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22). Start with `bounty:docs` or `difficulty:easy`.
- `#integrations-announcements` — Bounty postings, leaderboard, promotions
- `#integrations-testing` — Coordinate with other testers
- `#integrations-help` — Ask questions about tools, credentials, setup
- `#integration-showcase` — Show off what you built
### 3. Pick your first bounty
Filter GitHub issues by label:
- [`bounty:docs`](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3Adocs%22) — Write a README for a tool (20 pts, easiest)
- [`bounty:smoke-test`](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3Asmoke-test%22) — Test a tool with a real API key (10 pts)
- [`difficulty:easy`](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22difficulty%3Aeasy%22) — All easy bounties
Comment on the issue: "I'd like to work on this" and wait for a maintainer to assign you (usually within 24 hours).
Comment "I'd like to work on this" and wait for a maintainer to assign you.
## Tiers
@@ -57,199 +33,84 @@ Comment on the issue: "I'd like to work on this" and wait for a maintainer to as
| **Open Source Contributor** | ~2,000 XP (Lurkr level 15) | Discord role, name in CONTRIBUTORS.md and tool READMEs |
| **Core Contributor** | Maintainer nomination | Dollar values on bounties, paid per completion |
Lurkr auto-assigns the first two roles when you hit the level. Core Contributor requires sustained, high-quality contributions and a maintainer vouching for you.
### How XP Adds Up
You earn XP from two sources:
| Source | How |
|--------|-----|
| **GitHub bounties** | Merge a PR with a `bounty:*` label — auto-pushed to Lurkr |
| **Discord activity** | Messages in `#integrations-*` channels, helping others, voice chat |
Both feed into the same Lurkr level. Helping people in Discord AND doing bounties levels you up faster than either alone.
XP comes from GitHub bounties (auto-pushed on PR merge) and Discord activity in `#integrations-help`.
## Bounty Types
### Smoke Test (10 pts)
### Test a Tool (20 pts)
**What:** Run an unverified tool with a real API key and report if it works.
Test an unverified tool with a real API key and report what happens.
**How:**
1. Pick a tool from the bounty board
2. Get an API key for that service (the bounty issue links to the help URL)
3. Set the environment variable: `export TOOL_API_KEY=your-key`
4. Run the tool functions and note what happens
5. Comment on the bounty issue with your results: pass/fail, any errors, logs
1. Get an API key for the service (the bounty issue links to where)
2. Run the tool functions with real data
3. Fill out the [test report template](templates/agent-test-report-template.md)
4. Submit as a comment on the issue or a file in a PR
**Difficulty:** Easy. You don't need to write code, just test and report.
Report both successes and failures. Finding bugs is valuable.
### Agent Test Report (30 pts)
### Write Docs (20 pts)
**What:** Build a real agent that uses an unverified tool and document the experience.
Write a README for a tool that's missing one.
**How:**
1. Pick a tool from the bounty board
2. Build a simple agent that uses the tool (see [Building Agents Guide](../tools/BUILDING_TOOLS.md))
3. Run the agent with a real task
4. Fill out the [test report template](templates/agent-test-report-template.md)
5. Submit the report as a comment on the bounty issue, or as a file in a PR
1. Read the tool's source code in `tools/src/aden_tools/tools/{tool_name}/`
2. Read the credential spec in `tools/src/aden_tools/credentials/`
3. Fill in the [tool README template](templates/tool-readme-template.md)
4. Submit a PR adding `README.md` to the tool directory
**What to include:** Environment, credential setup, which functions you tested, what worked, what broke, edge cases found, and logs or session ID.
Function names and API URLs must match reality — no AI hallucinations.
**Difficulty:** Medium. Requires an API key and some familiarity with the framework.
### Code Contribution (30 pts)
### Write README (20 pts)
Add a health checker, fix a bug, or improve an integration.
**What:** Write documentation for a tool that's missing its README.
**Health checker:**
1. Find a lightweight API endpoint that validates the credential (GET, no writes)
2. Add `health_check_endpoint` to the tool's CredentialSpec
3. Implement a HealthChecker class in `tools/src/aden_tools/credentials/health_check.py`
4. Register in `HEALTH_CHECKERS`, run `uv run pytest tools/tests/test_credential_registry.py`
**How:**
1. Pick a tool from the bounty board
2. Read the tool's source code in `tools/src/aden_tools/tools/{tool_name}/`
3. Read the credential spec in `tools/src/aden_tools/credentials/`
4. Fill in the [tool README template](templates/tool-readme-template.md)
5. Submit a PR adding `README.md` to the tool directory
**Quality bar:** Function names must match the actual code. Setup instructions must be accurate. API URLs must be real.
**Difficulty:** Easy. Good first bounty — you learn the codebase by reading and documenting it.
### Add Health Checker (25 pts)
**What:** Implement a credential health check so the system can validate API keys at startup.
**How:**
1. Pick a tool from the bounty board
2. Find a lightweight API endpoint that validates the credential (GET, no writes, no charges)
3. Add `health_check_endpoint` to the tool's CredentialSpec
4. Implement a HealthChecker class in `tools/src/aden_tools/credentials/health_check.py`
5. Register it in the `HEALTH_CHECKERS` dict
6. Run `uv run pytest tools/tests/test_credential_registry.py` to verify wiring
7. Submit a PR
**Difficulty:** Medium. Requires reading the service's API docs to find the right endpoint.
### Bug Fix (40 pts)
**What:** Find a bug during testing and fix it.
**How:**
1. Find a bug while doing a smoke test or agent test
2. File an issue describing the bug (or comment on the existing bounty issue)
3. Fix the bug in a PR
4. Add a test that covers the specific bug
5. Reference the bounty issue in your PR
**Difficulty:** Varies. The bug itself tells you the difficulty.
**Bug fix:**
1. Find a bug during testing, file an issue
2. Fix it in a PR with a test covering the bug
### New Integration (75 pts)
**What:** Build a complete new integration from scratch.
Build a complete integration from scratch.
**How:**
1. Check the [Integration Request issues](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22Integration%22) for requested integrations
2. Follow the [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) guide
3. Create: tool implementation + credential spec + health checker + tests + README
4. Register in `_register_unverified()` in `tools/__init__.py`
5. Run `make check && make test`
6. Submit a PR
1. Follow the [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) guide
2. Create: tool + credential spec + health checker + tests + README
3. Register in `_register_unverified()` in `tools/__init__.py`
4. Run `make check && make test`
**Difficulty:** Hard. This is a significant contribution — expect multiple review rounds.
### Complete Promotion Checklist (50 pts)
**What:** Take an unverified tool through the full [promotion checklist](promotion-checklist.md) to make it verified.
**How:**
1. Pick a tool that has most checklist items already done (docs, health check, tests)
2. Complete the remaining items
3. Get at least 1 community test report (coordinate in `#integrations-testing`)
4. Submit a PR that moves the tool from `_register_unverified()` to `_register_verified()`
5. Include links to all checklist evidence in the PR description
**Difficulty:** Hard. Requires coordination and thoroughness.
## Achievement Badges
Permanent Discord roles earned through specific accomplishments:
| Badge | How to Earn |
|-------|-------------|
| **First Blood** | Complete your first bounty of any type |
| **Bug Hunter** | Fix 3 bugs found during testing |
| **Docs Champion** | Write 5 tool READMEs |
| **Health Inspector** | Add 5 health checkers |
| **Promoter** | Promote a tool from unverified to verified |
| **Full Stack** | Complete at least 1 bounty of every type |
| **Ironman** | 8 consecutive weeks with at least 1 bounty completion |
Badges are assigned by maintainers when you qualify. If you think you've earned one and it hasn't been assigned, ask in `#integrations-help`.
## Streaks
Consecutive weeks with at least one bounty completion earns XP multipliers:
| Streak | Multiplier |
|--------|-----------|
| 2 weeks | 1.1x |
| 4 weeks | 1.25x |
| 8+ weeks | 1.5x |
Missing a week resets the streak. A 20-point README bounty at an 8-week streak earns 30 XP instead of 20.
## Leaderboard
Posted every Monday at 9:00 UTC in `#integrations-announcements`. Top 3 get medal emojis.
You can also check your rank anytime in Discord:
```
/rank
```
Or view the web leaderboard via Lurkr's dashboard.
Expect multiple review rounds.
## Rules
1. **Claim before you start** — comment on the issue, wait to be assigned
2. **One person per bounty** — first to claim and get assigned gets it
3. **7-day window** — if you don't submit a PR within 7 days of being assigned, the bounty is unassigned and re-opened
4. **Maximum 3 active claims** — don't hoard bounties
5. **Quality matters** — PRs must pass CI, follow templates, and address review feedback
6. **No self-review** — you can't review your own PR
7. **Honest testing** — report failures, not just successes. Finding bugs is valuable
8. **No AI-only submissions** — AI tools are fine for assistance, but you must verify that function names, API URLs, and behavior match reality
1. **Claim before you start** — comment on the issue, wait for assignment
2. **7-day window** — no PR within 7 days = bounty gets re-opened
3. **Max 3 active claims** — don't hoard bounties
4. **Quality matters** — PRs must pass CI and follow templates
5. **No self-review** and no AI-only submissions without verification
## FAQ
**Q: Do I need an API key for every tool I test?**
A: Yes, for smoke tests and agent tests. Most services have free tiers. The bounty issue links to where you get the key.
**Q: Can I work on multiple bounties at once?**
A: Yes, up to 3 active claims at a time.
**Q: What if I find a bug but can't fix it?**
A: File an issue! Someone else can pick up the `bounty:bug-fix`. Finding bugs during testing is the whole point.
A: Yes. Most services have free tiers. The bounty issue links to where you get the key.
**Q: How do I become a Core Contributor?**
A: Keep contributing consistently across different bounty types for 4+ weeks. Maintainers will notice and nominate you when you're ready. There's no application process — just keep shipping quality work.
A: Contribute consistently across different bounty types for 4+ weeks. Maintainers will nominate you.
**Q: What if I haven't linked my Discord yet?**
A: You'll still be recognized in the GitHub Action logs and Discord webhook message, but Lurkr can't push XP to your account. Link your Discord ID in `contributors.yml` to start earning XP and roles.
**Q: Do I earn XP from Discord messages too?**
A: Yes. Lurkr awards XP for messages in `#integrations-*` channels (with a 60-second cooldown). Helping others in `#integrations-help` earns 2x XP. Both Discord XP and GitHub bounty XP feed into the same level.
A: You'll still get credit in GitHub, but no Lurkr XP or Discord roles. Add yourself to `contributors.yml`.
## Quick Reference
| What | Where |
|------|-------|
| Bounty board | [GitHub Issues with bounty label](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22) |
| README template | [docs/bounty-program/templates/tool-readme-template.md](templates/tool-readme-template.md) |
| Test report template | [docs/bounty-program/templates/agent-test-report-template.md](templates/agent-test-report-template.md) |
| Promotion checklist | [docs/promotion-checklist.md](promotion-checklist.md) |
| Building tools guide | [tools/BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) |
| Contributing guide | [CONTRIBUTING.md](../CONTRIBUTING.md) |
| Bounty board | [GitHub Issues](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22) |
| README template | [templates/tool-readme-template.md](templates/tool-readme-template.md) |
| Test report template | [templates/agent-test-report-template.md](templates/agent-test-report-template.md) |
| Promotion checklist | [promotion-checklist.md](promotion-checklist.md) |
| Building tools | [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) |
| Discord | [Join](https://discord.com/invite/MXE49hrKDk) |
| Your rank | Type `/rank` in Discord |
| Link your accounts | Add yourself to [contributors.yml](../contributors.yml) |
| Your rank | `/rank` in Discord |
docs/bounty-program/game-master-manual.md
+65 -227
View File
@@ -1,269 +1,107 @@
# Game Master Manual
Operations guide for maintainers running the Integration Bounty Program. This covers the day-to-day decisions: posting bounties, approving work, awarding points, managing tiers, and keeping the program healthy.
Operations guide for maintainers running the Integration Bounty Program.
## Your Role
As a game master (maintainer), you:
- Post bounty issues and set dollar values for Core Contributors
- Assign claimed bounties to contributors
- Review and merge bounty PRs (which auto-triggers point/XP awards)
- Manually assign achievement badges and the Core Contributor role
- Review and merge bounty PRs (auto-triggers XP awards)
- Manage the Core Contributor role
- Monitor for gaming and low-quality submissions
- Keep the bounty board fresh and the community engaged
## Daily Operations
## Handling Bounty Claims
### Handling Bounty Claims
When someone comments "I'd like to work on this":
When someone comments "I'd like to work on this" on a bounty issue:
1. For `difficulty:easy`, assign immediately
2. For `difficulty:medium`/`difficulty:hard`, check if they've done easier bounties first
3. Assign via GitHub. If no PR within 7 days, unassign and re-open
1. Check their GitHub profile — do they have relevant experience?
2. For `difficulty:easy` bounties, assign immediately (within 24 hours)
3. For `difficulty:medium` and `difficulty:hard`, check if they've completed easier bounties first
4. Assign the issue to them via GitHub
5. If they don't submit a PR within 7 days, unassign and re-open
## Reviewing Bounty PRs
### Reviewing Bounty PRs
1. Verify the PR matches the bounty issue
2. Check quality gates (below)
3. A **different maintainer** must approve than the one who created the bounty
4. Apply the correct `bounty:*` label to the PR before merging
5. Merge — the GitHub Action auto-awards XP and posts to Discord
6. Close the linked bounty issue
When a bounty PR is submitted:
### Quality Gates
1. **Verify the PR matches the bounty** — does it actually complete what the issue asked for?
2. **Check quality gates** (see below)
3. **A different maintainer** must approve than the one who created the bounty issue
4. **Apply the correct `bounty:*` label** to the PR before merging (if not already present)
5. **Merge** — the GitHub Action automatically awards XP and posts to Discord
6. **Close the linked bounty issue**
### Quality Gate Checks
#### For `bounty:docs` (READMEs):
**`bounty:docs`:**
- [ ] Follows the [tool README template](templates/tool-readme-template.md)
- [ ] Setup instructions are accurate (API key URL works, steps are correct)
- [ ] Tool table lists all functions with correct names
- [ ] At least one usage example per tool function
- [ ] API reference link is valid
- [ ] Not obviously AI-generated without verification (check that API URLs and function names match reality)
- [ ] Setup instructions are accurate (API key URL works)
- [ ] Function names match the actual code
- [ ] Not AI-generated without verification
#### For `bounty:health-check`:
- [ ] `health_check_endpoint` added to CredentialSpec
- [ ] HealthChecker class implemented with proper 200/401/429 handling
- [ ] Registered in `HEALTH_CHECKERS` dict
- [ ] `uv run pytest tools/tests/test_credential_registry.py` passes
- [ ] Endpoint is actually a lightweight validation call (no writes, no charges)
#### For `bounty:agent-test`:
**`bounty:test`:**
- [ ] Test report follows the [template](templates/agent-test-report-template.md)
- [ ] Includes reproducible evidence (logs, session ID, or screenshots)
- [ ] Tests were done with a real API key, not mocked
- [ ] Reports both successes and failures honestly
- [ ] Edge cases section is filled out (even if "none found")
- [ ] Includes logs, session ID, or screenshots
- [ ] Done with a real API key, not mocked
- [ ] Reports failures honestly
#### For `bounty:bug-fix`:
- [ ] Bug was found during actual integration testing (not invented)
- [ ] Fix addresses the root cause, not just the symptom
- [ ] Existing tests still pass
- [ ] New test added for the specific bug
**`bounty:code`:**
- [ ] CI passes (`uv run pytest tools/tests/test_credential_registry.py` for health checks)
- [ ] Fix addresses root cause, not symptom
- [ ] New test added for bug fixes
#### For `bounty:new-tool`:
**`bounty:new-tool`:**
- [ ] Full implementation: tool + credential spec + tests + README
- [ ] Follows [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) patterns
- [ ] `make check && make test` passes
- [ ] Registered in `_register_unverified()` (not verified — needs community testing first)
#### For `bounty:promote`:
- [ ] Every item on the [promotion checklist](promotion-checklist.md) is checked
- [ ] At least 1 community agent test report exists
- [ ] Move registration from `_register_unverified()` to `_register_verified()`
- [ ] Registered in `_register_unverified()` (not verified)
### Rejecting Submissions
When quality is insufficient:
1. Leave specific, constructive feedback
2. Request changes (don't close the PR)
3. 7 days to address. No response → close PR, unassign bounty
1. Leave a specific, constructive review comment — explain exactly what needs to change
2. Request changes on the PR (don't close it)
3. Give them 7 days to address feedback
4. If no response after 7 days, close the PR and unassign the bounty issue
Never merge low-quality work just to be nice.
**Never:**
- Reject without explanation
- Deduct points for good-faith attempts that need revision
- Merge low-quality work just to be nice — it degrades the codebase and the program's credibility
## Core Contributor Promotion
## Weekly Operations
Core Contributor unlocks monetary rewards. The bar must be high.
### Monday: Leaderboard Day
**Promote when:**
- Active for **4+ weeks** with contributions across **3+ bounty types**
- PRs are consistently clean
- At least one maintainer vouches for them
The `weekly-leaderboard.yml` action auto-posts at 9:00 UTC every Monday. After it posts:
**How:** Discuss with maintainers → assign role in Discord → announce in `#integrations-announcements` → add to `#bounty-payouts`
1. Check the leaderboard in `#integrations-announcements`
2. If anyone new entered the top 3, congratulate them in the channel
3. Review the bounty board — are there enough open bounties? Aim for 10+ unclaimed at all times
**Don't promote** if they only do easy bounties, have been active < 4 weeks, or show signs of gaming.
### Thursday: Bounty Refresh
If a Core Contributor is inactive 8+ weeks, reach out privately first, then remove the role if no response.
Mid-week check:
## Dollar Values
1. Are any bounties stale (assigned >7 days, no PR)? Unassign them
2. Are any bounty types depleted? Post more
3. Check `#integrations-help` — are people asking questions that suggest missing documentation? That's a signal for new `bounty:docs` issues
Post dollar values in `#bounty-payouts` (Core Contributors only):
## Tier Management
| Bounty Type | Dollar Range |
|-------------|-------------|
| `bounty:test` | $10–30 |
| `bounty:docs` | $10–20 |
| `bounty:code` | $20–50 |
| `bounty:new-tool` | $50–150 |
### Promoting to Agent Builder (Automatic)
**Payout:** PR merged → verify quality → record in `#bounty-payouts` → process payment.
Lurkr handles this via role reward at level 5. No action needed.
XP is always awarded regardless of budget. Money is a bonus layer.
### Promoting to Open Source Contributor (Automatic)
## Anti-Gaming
Lurkr handles this via role reward at level 15. No action needed.
| Pattern | Response |
|---------|----------|
| Splitting one change across multiple PRs | Reject extras, warn |
| AI-generated without verification | Reject, explain why |
| Claiming many bounties, completing few | Unassign after 7 days |
### Promoting to Core Contributor (Manual)
**First offense:** warning. **Second:** 2-week cooldown. **Third:** permanent removal.
This is the most important decision you make. Core Contributor unlocks monetary rewards, so the bar must be high.
## Keeping It Fresh
**When to promote:**
1. The contributor has been active for **4+ weeks**
2. They have contributions across **3+ bounty types** (not just one category)
3. Their PRs are consistently clean — they don't need multiple rounds of back-and-forth
4. They've demonstrated **technical depth** (not just documentation — they can fix bugs, add health checks, or build tools)
5. At least one maintainer is willing to vouch for them
**How to promote:**
1. Discuss with other maintainers in your private channel
2. If consensus, assign the Core Contributor role in Discord manually
3. Post an announcement in `#integrations-announcements`:
```
Welcome @username as a Core Contributor! They've [brief summary of contributions].
```
4. Add them to the `#bounty-payouts` channel
5. Brief them on how dollar-value bounties work (see below)
**When NOT to promote:**
- They only do easy bounties (all docs, no code)
- They've been active for less than 4 weeks
- Their PRs frequently need significant rework
- They show signs of gaming (splitting work, low-effort submissions)
### Demoting / Pausing Core Contributor
If a Core Contributor becomes inactive or their quality drops:
1. Reach out privately first — "Hey, noticed you've been less active, everything okay?"
2. If quality is the issue, provide specific feedback
3. If they're inactive for 8+ weeks, remove the Core Contributor role (they can earn it back)
4. Never demote publicly — handle it in DMs
## Monetary Bounties
### Setting Dollar Values
For each bounty issue, post the dollar value in `#bounty-payouts` (visible only to Core Contributors):
```
Bounty #1234: Write README for salesforce_tool — $15
Bounty #1235: Add health checker for jira — $25
Bounty #1236: Full promotion of notion_tool — $75
```
**Suggested dollar ranges:**
| Bounty Type | Dollar Range | Notes |
|-------------|-------------|-------|
| `bounty:docs` | $10–20 | $10 for simple tools, $20 for complex ones |
| `bounty:health-check` | $15–30 | $15 for simple GET, $30 for complex auth |
| `bounty:smoke-test` | $5–10 | Quick validation |
| `bounty:agent-test` | $20–40 | Requires real API key and time |
| `bounty:bug-fix` | $20–50 | Depends on complexity |
| `bounty:new-tool` | $50–150 | Depends on integration complexity |
| `bounty:promote` | $50–100 | Full checklist completion |
### Payout Process
1. Core Contributor completes bounty, PR is merged
2. Verify the work meets quality gates
3. Record the payout in `#bounty-payouts`:
```
PAID: @username — Bounty #1234 — $15 — [payment method/reference]
```
4. Process payment via your payment system (PayPal, Wise, crypto, etc.)
### Budget Management
- Set a monthly budget cap and communicate it
- When budget is tight, reduce dollar values rather than stopping bounties entirely
- Point values (XP) are always awarded regardless of budget — money is a bonus layer
## Achievement Badges
These are manually assigned when someone qualifies. Check periodically.
| Badge | Trigger | How to Verify |
|-------|---------|---------------|
| **First Blood** | First bounty completed | Check their first merged PR with `bounty:*` label |
| **Bug Hunter** | 3 `bounty:bug-fix` PRs merged | Search: `is:pr is:merged author:USERNAME label:bounty:bug-fix` |
| **Docs Champion** | 5 `bounty:docs` PRs merged | Search: `is:pr is:merged author:USERNAME label:bounty:docs` |
| **Health Inspector** | 5 `bounty:health-check` PRs merged | Search: `is:pr is:merged author:USERNAME label:bounty:health-check` |
| **Promoter** | 1 `bounty:promote` PR merged | Search: `is:pr is:merged author:USERNAME label:bounty:promote` |
| **Full Stack** | At least 1 PR with each bounty type | Check all 7 bounty labels |
| **Ironman** | 8 consecutive weeks with a bounty PR | Check merge dates — no gap > 7 days |
When assigning a badge:
1. Assign the role in Discord
2. Post in `#integrations-announcements`:
```
@username just earned the Bug Hunter badge! 3 bugs found and fixed.
```
## Anti-Gaming Playbook
### Signs of Gaming
| Pattern | What It Looks Like | Response |
|---------|-------------------|----------|
| **Splitting** | One README split into 3 PRs | Reject extras, warn contributor |
| **AI spam** | README with wrong function names, hallucinated APIs | Reject, explain why verification matters |
| **Claim hoarding** | Claiming 10 bounties, completing 1 | Unassign after 7 days, limit to 3 active claims |
| **Self-review** | Reviewing their own work under alt account | Ban both accounts |
| **Low-effort agent tests** | Test report with no logs, no session ID | Request revision with specific feedback |
### Responses
**First offense:** Warning via PR comment or DM. Be specific about what was wrong.
**Second offense:** 2-week bounty cooldown (they can still contribute, but no bounty labels are applied to their PRs).
**Third offense:** Permanent removal from the bounty program. Core Contributor role revoked if applicable.
Document all actions in a private maintainer thread for transparency.
## Keeping the Program Alive
### What Makes It Stale
- No new bounties for 2+ weeks
- Same 3 people on the leaderboard every week
- Bounties claimed but never completed
- Announcements channel goes quiet
### What Keeps It Fresh
- **New bounty types** — when the Doc Sprint is done, launch the Health Check Sprint
- **Sprint events** — "This week: double XP on agent tests"
- **Shoutouts** — highlight exceptional contributions in announcements
- **Showcase pins** — pin the best demos in `#integration-showcase`
- **Rising stars** — mention newcomers who are ramping up fast
- **Milestones** — "We just promoted the 10th tool to verified!"
### Metrics to Track
| Metric | Healthy Range | Alarm |
|--------|-------------|-------|
| Open unclaimed bounties | 10–30 | < 5 (post more) or > 50 (too many, focus) |
| Active contributors (last 30 days) | 5+ | < 3 |
| Average days claim → PR | 3–7 | > 14 (bounties too hard or claims going stale) |
| Tools promoted (monthly) | 2–5 | 0 (investigate blockers) |
| Core Contributor count | 3–10 | > 15 (bar too low) or 0 (bar too high) |
- Aim for 10+ unclaimed bounties at all times
- Unassign stale claims (>7 days)
- Shoutout exceptional contributions in announcements
- Post milestones ("10th tool promoted to verified!")
docs/bounty-program/promotion-checklist.md
+4 -4
View File
@@ -67,7 +67,7 @@ Formal criteria for promoting a tool from **unverified** to **verified**. A tool
2. **PR description** includes links to: the tool README, the health checker, the test report(s)
3. **Maintainer reviews** the checklist — every required item must be verified
4. **Maintainer moves** the tool registration from `_register_unverified()` to `_register_verified()` in `tools/__init__.py`
5. **Maintainer adds the `bounty:promote` label** to the PR — this triggers the GitHub Action to award 50 XP via Lurkr and post a Discord notification
5. **Maintainer adds the `bounty:code` label** to the PR — this triggers the GitHub Action to award XP via Lurkr and post a Discord notification
6. **Announcement** auto-posted in `#integrations-announcements` on Discord
## Current Status
@@ -94,6 +94,6 @@ yahoo_finance, youtube, youtube_transcript, zendesk, zoho_crm, zoom
| Gap | Count | Bounty Type |
|-----|-------|-------------|
| Missing README | ~41 | `bounty:docs` |
| Missing health_check_endpoint | ~40 | `bounty:health-check` |
| Missing HealthChecker class | ~40 | `bounty:health-check` |
| No community test report | 55 | `bounty:agent-test` |
| Missing health_check_endpoint | ~40 | `bounty:code` |
| Missing HealthChecker class | ~40 | `bounty:code` |
| No community test report | 55 | `bounty:test` |
docs/bounty-program/setup-guide.md
+39 -127
View File
@@ -14,33 +14,26 @@ Complete setup from zero to running. Estimated time: 30 minutes.
./scripts/setup-bounty-labels.sh
```
This creates 10 labels: 7 bounty types (`bounty:smoke-test`, `bounty:agent-test`, `bounty:docs`, `bounty:health-check`, `bounty:bug-fix`, `bounty:new-tool`, `bounty:promote`) and 3 difficulty levels (`difficulty:easy`, `difficulty:medium`, `difficulty:hard`).
This creates 7 labels: 4 bounty types (`bounty:test`, `bounty:docs`, `bounty:code`, `bounty:new-tool`) and 3 difficulty levels (`difficulty:easy`, `difficulty:medium`, `difficulty:hard`).
Verify at: `https://github.com/adenhq/hive/labels`
## Step 2: Create Discord Channels (5 min)
Create these channels (or rename existing ones):
## Step 2: Create Discord Channels (3 min)
```
Category: Integrations
#integrations-announcements (read-only for non-admins)
#integrations-testing
#integrations-help
#integration-showcase
Category: Private
#bounty-payouts (visible only to Core Contributor role)
```
**Channel permissions:**
- `#integrations-announcements`: Everyone can read, only bots + admins can post
- `#bounty-payouts`: Visible only to users with the Core Contributor role
- All others: open to everyone
**Permissions:**
- `#integrations-announcements`: Everyone reads, only bots + admins post
- `#bounty-payouts`: Core Contributor role only
## Step 3: Create Discord Roles (3 min)
## Step 3: Create Discord Roles (2 min)
Create these roles if they don't exist. Order matters — higher = more prestigious:
Order matters — higher = more prestigious:
| Role | Color | Hoisted | Mentionable |
|------|-------|---------|-------------|
@@ -48,55 +41,24 @@ Create these roles if they don't exist. Order matters — higher = more prestigi
| Open Source Contributor | Purple `#9B59B6` | Yes | No |
| Agent Builder | Green `#2ECC71` | Yes | No |
Achievement badge roles (optional, create as needed):
| Role | Color |
|------|-------|
| First Blood | Default |
| Bug Hunter | Red `#E74C3C` |
| Docs Champion | Yellow `#F39C12` |
| Health Inspector | Orange `#E67E22` |
| Promoter | Gold `#F1C40F` |
| Full Stack | Teal `#1ABC9C` |
| Ironman | Default |
## Step 4: Install and Configure Lurkr (10 min)
### 4a. Invite Lurkr
Go to https://lurkr.gg/ and invite the bot to your server. Grant it the permissions it requests (Manage Roles, Send Messages, etc).
Go to https://lurkr.gg/ and invite the bot. Grant requested permissions.
### 4b. Enable Leveling
### 4b. Enable Leveling and Configure XP
In any channel:
```
/levels enable
```
### 4c. Configure Message XP
```
/levels set-xp min:15 max:25
/levels set-cooldown seconds:60
```
### 4d. Set Channel XP Multipliers
Boost XP in channels where helping others matters:
```
/levels multiplier channel:#integrations-help multiplier:2
/levels multiplier channel:#integrations-testing multiplier:1.5
```
Disable XP in bot-only channels:
```
/levels ignore channel:#integrations-announcements
/levels ignore channel:#bounty-payouts
```
### 4e. Configure Role Rewards
### 4c. Configure Role Rewards
```
/levels role-reward add level:5 role:@Agent Builder
@@ -105,38 +67,33 @@ Disable XP in bot-only channels:
Do NOT auto-assign Core Contributor — that's maintainer-only.
### 4f. Generate Lurkr API Key
### 4d. Generate Lurkr API Key
1. Go to https://lurkr.gg/ and log in with Discord
2. Navigate to your profile / API settings
3. Click "Create API Key"
4. Select **Read/Write** (not read-only)
5. Copy the key — you'll need it in the next step
1. Go to https://lurkr.gg/ and log in
2. Profile > API settings > Create API Key
3. Select **Read/Write** (not read-only)
4. Copy the key
## Step 5: Create Discord Webhook (2 min)
1. Go to **Server Settings > Integrations > Webhooks**
2. Click **New Webhook**
3. Name it `Bounty Tracker`
4. Set the channel to `#integrations-announcements`
5. Copy the webhook URL
1. Server Settings > Integrations > Webhooks > New Webhook
2. Name: `Bounty Tracker`, channel: `#integrations-announcements`
3. Copy the webhook URL
## Step 6: Add GitHub Repository Secrets (3 min)
## Step 6: Add GitHub Secrets (3 min)
Go to **Repo Settings > Secrets and variables > Actions > New repository secret** and add:
Repo Settings > Secrets and variables > Actions:
| Secret Name | Value |
|-------------|-------|
| `DISCORD_BOUNTY_WEBHOOK_URL` | The webhook URL from Step 5 |
| `LURKR_API_KEY` | The Lurkr API key from Step 4f |
| Secret | Value |
|--------|-------|
| `DISCORD_BOUNTY_WEBHOOK_URL` | Webhook URL from Step 5 |
| `LURKR_API_KEY` | Lurkr API key from Step 4d |
| `LURKR_GUILD_ID` | Your Discord server ID* |
*To find server ID: Enable Developer Mode in Discord (Settings > Advanced), then right-click the server name > Copy Server ID.
*Enable Developer Mode in Discord, right-click server name > Copy Server ID.
## Step 7: Test the Pipeline (5 min)
### Test 1: Verify the script runs locally
```bash
GITHUB_TOKEN=$(gh auth token) \
GITHUB_REPOSITORY_OWNER=adenhq \
@@ -144,40 +101,15 @@ GITHUB_REPOSITORY_NAME=hive \
bun run scripts/bounty-tracker.ts leaderboard
```
Expected: `Found 0 merged bounty PRs` (or more if you already have bounty PRs).
Then create a test PR with `bounty:docs` label, merge it, verify the Discord notification appears.
### Test 2: Test a webhook notification
## Step 8: Seed the 55-Tool Blitz
Create a test PR, add the `bounty:docs` and `difficulty:easy` labels, merge it, and verify:
- GitHub Action `Bounty completed` runs successfully
- A message appears in `#integrations-announcements`
- If the contributor is in `contributors.yml`, Lurkr XP is awarded
Post all bounties at once on launch day:
### Test 3: Verify Lurkr role rewards
Check that role rewards are configured:
```
/levels role-rewards
```
## Step 8: Seed the 55-Tool Blitz (Day 1)
Post all bounties at once on launch day. Use the bounty issue template for each:
**Documentation bounties (41 issues):**
- Title: `[Bounty]: Write README for {tool_name}`
- Bounty type: `Write README (20 pts)`, Difficulty: `Easy`
- Labels: `bounty:docs`, `difficulty:easy`
**Health check bounties (40 issues):**
- Title: `[Bounty]: Add health checker for {tool_name}`
- Bounty type: `Add Health Checker (25 pts)`, Difficulty: `Medium`
- Labels: `bounty:health-check`, `difficulty:medium`
**Agent test bounties (55 issues):**
- Title: `[Bounty]: Agent test for {tool_name}`
- Bounty type: `Agent Test Report (30 pts)`, Difficulty: `Medium`
- Labels: `bounty:agent-test`, `difficulty:medium`
**Documentation (41 issues):** `bounty:docs`, `difficulty:easy`, 20 pts
**Health checks (40 issues):** `bounty:code`, `difficulty:medium`, 30 pts
**Testing (55 issues):** `bounty:test`, `difficulty:medium`, 20 pts
### Tools missing READMEs
@@ -193,38 +125,18 @@ powerbi, redis
## Verification Checklist
After setup, verify everything works:
- [ ] Labels exist on the repo (`bounty:*` and `difficulty:*`)
- [ ] Discord channels created and permissions set
- [ ] Discord roles created in correct order
- [ ] Lurkr installed, leveling enabled, XP configured
- [ ] Lurkr role rewards set for levels 5 and 15
- [ ] Lurkr API key is Read/Write
- [ ] Labels exist (`bounty:*` and `difficulty:*`)
- [ ] Discord channels and roles created
- [ ] Lurkr installed, XP configured, role rewards set
- [ ] All 3 GitHub secrets added
- [ ] `bounty-completed.yml` workflow exists and is enabled
- [ ] `weekly-leaderboard.yml` workflow exists and is enabled
- [ ] Test PR + merge triggers notification in Discord
- [ ] Both workflows enabled (`bounty-completed.yml`, `weekly-leaderboard.yml`)
- [ ] Test PR + merge triggers Discord notification
- [ ] `contributors.yml` exists at repo root
## Troubleshooting
**Action runs but no Discord message:**
- Check the `DISCORD_BOUNTY_WEBHOOK_URL` secret is set correctly
- Check the webhook channel still exists and the webhook hasn't been deleted
- Check the Action logs for error messages
**No Discord message:** Check `DISCORD_BOUNTY_WEBHOOK_URL` secret and Action logs.
**Lurkr XP not awarded:**
- Confirm `LURKR_API_KEY` and `LURKR_GUILD_ID` secrets are set
- Confirm the API key is Read/Write (not read-only)
- Confirm the contributor has linked their Discord ID in `contributors.yml`
- Check Action logs for `Lurkr XP push failed` messages
**Lurkr XP not awarded:** Confirm API key is Read/Write, contributor is in `contributors.yml`, check Action logs for `Lurkr XP push failed`.
**Role not assigned after level up:**
- Verify role rewards are configured: `/levels role-rewards`
- Lurkr assigns roles on level-up, not retroactively. The user may need to send a message or run `/rank` to trigger it
- Verify Lurkr's role is above the roles it needs to assign in the server role hierarchy
**Weekly leaderboard not posting:**
- The cron schedule is Monday 9:00 UTC. Check that the workflow is enabled
- Manually trigger: Actions > Weekly bounty leaderboard > Run workflow
**Role not assigned:** Verify `/levels role-rewards` config. Lurkr's role must be above the roles it assigns in server hierarchy.
scripts/bounty-tracker.ts
+5 -11
View File
@@ -68,13 +68,10 @@ interface LeaderboardEntry {
// ---------------------------------------------------------------------------
const POINTS: Record<string, number> = {
"bounty:smoke-test": 10,
"bounty:agent-test": 30,
"bounty:test": 20,
"bounty:docs": 20,
"bounty:health-check": 25,
"bounty:bug-fix": 40,
"bounty:code": 30,
"bounty:new-tool": 75,
"bounty:promote": 50,
};
// ---------------------------------------------------------------------------
@@ -275,13 +272,10 @@ function formatBountyNotification(bounty: BountyResult): string {
: `**${bounty.contributor}**`;
const typeEmoji: Record<string, string> = {
"smoke-test": "\u{1F9EA}",
"agent-test": "\u{1F916}",
test: "\u{1F9EA}",
docs: "\u{1F4DD}",
"health-check": "\u{1FA7A}",
"bug-fix": "\u{1F41B}",
"new-tool": "\u{1F527}",
promote: "\u{2B50}",
code: "\u{1F527}",
"new-tool": "\u{2B50}",
};
const emoji = typeEmoji[bounty.bountyType] ?? "\u{1F3AF}";
scripts/setup-bounty-labels.sh
+2 -5
View File
@@ -10,13 +10,10 @@ REPO="${1:-adenhq/hive}"
echo "Setting up bounty labels for $REPO..."
# Bounty type labels
gh label create "bounty:smoke-test" --repo "$REPO" --color "0E8A16" --description "Bounty: run tool with real API key, report results (10 pts)" --force
gh label create "bounty:agent-test" --repo "$REPO" --color "1D76DB" --description "Bounty: test tool in a real agent workflow (30 pts)" --force
gh label create "bounty:test" --repo "$REPO" --color "1D76DB" --description "Bounty: test a tool with real API key (20 pts)" --force
gh label create "bounty:docs" --repo "$REPO" --color "FBCA04" --description "Bounty: write or improve documentation (20 pts)" --force
gh label create "bounty:health-check" --repo "$REPO" --color "D93F0B" --description "Bounty: add health check endpoint or checker (25 pts)" --force
gh label create "bounty:bug-fix" --repo "$REPO" --color "B60205" --description "Bounty: fix a discovered bug (40 pts)" --force
gh label create "bounty:code" --repo "$REPO" --color "D93F0B" --description "Bounty: health checker, bug fix, or improvement (30 pts)" --force
gh label create "bounty:new-tool" --repo "$REPO" --color "6F42C1" --description "Bounty: build a new integration from scratch (75 pts)" --force
gh label create "bounty:promote" --repo "$REPO" --color "C2A000" --description "Bounty: complete full promotion checklist (50 pts)" --force
# Difficulty labels
gh label create "difficulty:easy" --repo "$REPO" --color "BFD4F2" --description "Good first contribution" --force