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: attributes:
label: Bounty Type label: Bounty Type
options: options:
- "Smoke Test (10 pts)" - "Test a Tool (20 pts)"
- "Agent Test Report (30 pts)" - "Write Docs (20 pts)"
- "Edge Case Report (15 pts)" - "Code Contribution (30 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)"
- "New Integration (75 pts)" - "New Integration (75 pts)"
validations: validations:
required: true required: true
docs/bounty-program/README.md
+71 -288
View File
@@ -1,314 +1,111 @@
# Integration Bounty Program # 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? ## 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. 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
### The Path to Paid 3. Do the work and submit a PR (or test report)
4. A maintainer reviews and merges
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. 5. You automatically get XP in Discord via Lurkr
6. At certain levels, you unlock roles. At the top tier, you unlock paid bounties.
### 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 | — |
## Tiers ## Tiers
| Tier | How to Reach | What You See | Rewards | | Tier | How to Reach | Rewards |
|------|-------------|--------------|---------| |------|-------------|---------|
| **Agent Builder** | Join Discord + start testing | Bounty board with point values | Discord role, community recognition, achievement badges | | **Agent Builder** | ~500 XP (Lurkr level 5) | Discord role, bounty board access |
| **Open Source Contributor** | First merged PR | Bounty board with point values | Discord role, listed in CONTRIBUTORS.md, name in tool READMEs | | **Open Source Contributor** | ~2,000 XP (Lurkr level 15) | Discord role, name in CONTRIBUTORS.md and tool READMEs |
| **Core Contributor** | Maintainer-approved promotion | Bounty board with **dollar values** | Monetary payout per completed bounty, private dev channel | | **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 | Type | Label | Points | What You Do |
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 | **Test a tool** | `bounty:test` | 20 | Test with a real API key, submit a report with logs |
4. **Maintainer nomination** — at least one maintainer vouches for the contributor | **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. 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.
## 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 |
## Quality Gates ## 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) ## Labels
- **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
| Label | Color | Meaning | | Label | Color | Meaning |
|-------|-------|---------| |-------|-------|---------|
| `bounty:smoke-test` | `#0E8A16` (green) | Run tool with real API key, report results | | `bounty:test` | `#1D76DB` (blue) | Test a tool with a real API key |
| `bounty:agent-test` | `#1D76DB` (blue) | Test tool in a real agent workflow |
| `bounty:docs` | `#FBCA04` (yellow) | Write or improve documentation | | `bounty:docs` | `#FBCA04` (yellow) | Write or improve documentation |
| `bounty:health-check` | `#D93F0B` (orange) | Add health check endpoint or checker | | `bounty:code` | `#D93F0B` (orange) | Health checker, bug fix, or improvement |
| `bounty:bug-fix` | `#B60205` (red) | Fix a discovered bug |
| `bounty:new-tool` | `#6F42C1` (purple) | Build a new integration from scratch | | `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:easy` | `#BFD4F2` | Good first contribution |
| `difficulty:medium` | `#D4C5F9` | Requires some familiarity | | `difficulty:medium` | `#D4C5F9` | Requires some familiarity |
| `difficulty:hard` | `#F9D0C4` | Significant effort or expertise needed | | `difficulty:hard` | `#F9D0C4` | Significant effort or expertise needed |
### Bounty Issue Structure ## Discord
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
``` ```
#integrations-announcements — New bounties, tool promotions, leaderboard updates #integrations-announcements — Bounties, leaderboard, tool promotions (bot + admin only)
#integrations-testing — Coordinate who's testing what, share test reports #integrations-help — Questions, testing coordination, showcases
#integrations-help — Get help with credential setup, tool development #bounty-payouts — Dollar values and payout tracking (Core Contributors only)
#integration-showcase — Demos of agents using integrations
# Private (Core Contributors only)
#bounty-payouts — Dollar values, payout tracking, claims
``` ```
## Leaderboard ## Leaderboard
Weekly leaderboard posted to `#integrations-announcements`: Weekly leaderboard auto-posts to `#integrations-announcements` every Monday. Top 3 get medal emojis. Check your rank anytime with `/rank` in Discord.
- Top 10 contributors by points (rolling 30 days)
- Top 10 contributors all-time
- Recently promoted tools (unverified -> verified)
- Number of open bounties by type
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 ## 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) ### Week 1–2
- **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: Blitz Week All bounty types open in parallel. Contributors self-select. Daily progress updates in `#integrations-announcements`. Day 14 wrap-up with final leaderboard and shoutouts.
- 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
## Automation ## 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 PR merged with bounty:* label
→ GitHub Action fires bounty-tracker.ts → GitHub Action runs bounty-tracker.ts
→ Script calculates points from label → Calculates points from label
→ Script resolves GitHub → Discord ID via contributors.yml → Resolves GitHub → Discord ID via contributors.yml
→ Script calls Lurkr API: PATCH /levels/{guild}/users/{user} (+XP) → Pushes XP to Lurkr API
→ Lurkr auto-assigns role rewards at XP thresholds → Posts notification to #integrations-announcements
→ Script posts Discord webhook 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 | Contributors link GitHub ↔ Discord by adding themselves to `contributors.yml`:
|----------|---------|-------------|
| `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:
```yaml ```yaml
contributors: contributors:
@@ -317,53 +114,39 @@ contributors:
name: Jane Doe name: Jane Doe
``` ```
This is intentionally a file-in-repo approach (not a database) because: Without this link, bounties are still tracked but Lurkr can't push XP to your Discord account.
- 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.
### What Handles What ### What Handles What
| Concern | Handled By | How | | Concern | Handled By | How |
|---------|-----------|-----| |---------|-----------|-----|
| Bounty point calculation | GitHub Actions | `bounty-completed.yml` reads PR labels | | 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) | | Discord engagement XP | Lurkr bot | Native message XP (configurable per-channel) |
| Leaderboard | Lurkr bot | Built-in `/levels leaderboard` + web leaderboard | | Leaderboard | Lurkr bot + GitHub Actions | `/levels leaderboard` + weekly webhook post |
| Weekly announcement | GitHub Actions | `weekly-leaderboard.yml` posts via webhook | | Agent Builder role | Lurkr bot | Auto-assigned at level 5 |
| Agent Builder role | Lurkr bot | Auto-assigned at level 5 via role reward | | OSS Contributor role | Lurkr bot | Auto-assigned at level 15 |
| OSS Contributor role | Lurkr bot | Auto-assigned at level 15 via role reward | | Core Contributor role | Maintainer | Manual (involves money) |
| 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 |
| Identity linking | contributors.yml | PR-based, reviewed by maintainers | | Identity linking | contributors.yml | PR-based, reviewed by maintainers |
| Discord notifications | GitHub Actions | Webhook post to `#integrations-announcements` |
## Guides ## Guides
- **[Setup Guide](setup-guide.md)** — Complete admin setup from zero to running (30 min) - **[Setup Guide](setup-guide.md)** — Admin setup from zero to running
- **[Game Master Manual](game-master-manual.md)** — Maintainer operations: posting bounties, reviewing work, managing tiers, anti-gaming - **[Game Master Manual](game-master-manual.md)** — Maintainer operations
- **[Contributor Guide](contributor-guide.md)** — Everything a contributor needs to start earning XP and completing bounties - **[Contributor Guide](contributor-guide.md)** — Everything a contributor needs to start
## Reference ## Reference
- [Integration Promotion Checklist](promotion-checklist.md) — Formal criteria for unverified -> verified - [Promotion Checklist](promotion-checklist.md) — Criteria for unverified → verified
- [Tool README Template](templates/tool-readme-template.md) — Standard format for tool documentation - [Tool README Template](templates/tool-readme-template.md)
- [Agent Test Report Template](templates/agent-test-report-template.md) — Standard format for test reports - [Agent Test Report Template](templates/agent-test-report-template.md)
- [Building Tools Guide](../tools/BUILDING_TOOLS.md) — How to build integrations - [Building Tools Guide](../tools/BUILDING_TOOLS.md)
- [Parent Issue #2805](https://github.com/adenhq/hive/issues/2805) — Master integration tracking issue - [Lurkr API Docs](https://lurkr.gg/docs/api)
- [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
### Automation Files ### 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 - `.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 - `scripts/setup-bounty-labels.sh` — One-time label setup
- `contributors.yml` — GitHub ↔ Discord identity mapping - `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 # 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 ## Getting Started
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)
### 1. Link your GitHub and Discord ### 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 ```yaml
contributors: contributors:
# ... existing entries
- github: your-github-username - github: your-github-username
discord: "your-discord-id" discord: "your-discord-id"
name: Your Name name: Your Name
``` ```
To find your Discord ID: To find your Discord ID: Discord Settings > Advanced > Enable **Developer Mode**, then right-click your name > **Copy User ID**.
1. Open Discord Settings > Advanced > Enable **Developer Mode**
2. Right-click your name in any channel > **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 Comment "I'd like to work on this" and wait for a maintainer to assign you.
- `#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).
## Tiers ## 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 | | **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 | | **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. XP comes from GitHub bounties (auto-pushed on PR merge) and Discord activity in `#integrations-help`.
### 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.
## Bounty Types ## 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. Get an API key for the service (the bounty issue links to where)
1. Pick a tool from the bounty board 2. Run the tool functions with real data
2. Get an API key for that service (the bounty issue links to the help URL) 3. Fill out the [test report template](templates/agent-test-report-template.md)
3. Set the environment variable: `export TOOL_API_KEY=your-key` 4. Submit as a comment on the issue or a file in a PR
4. Run the tool functions and note what happens
5. Comment on the bounty issue with your results: pass/fail, any errors, logs
**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. Read the tool's source code in `tools/src/aden_tools/tools/{tool_name}/`
1. Pick a tool from the bounty board 2. Read the credential spec in `tools/src/aden_tools/credentials/`
2. Build a simple agent that uses the tool (see [Building Agents Guide](../tools/BUILDING_TOOLS.md)) 3. Fill in the [tool README template](templates/tool-readme-template.md)
3. Run the agent with a real task 4. Submit a PR adding `README.md` to the tool directory
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
**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:** **Bug fix:**
1. Pick a tool from the bounty board 1. Find a bug during testing, file an issue
2. Read the tool's source code in `tools/src/aden_tools/tools/{tool_name}/` 2. Fix it in a PR with a test covering the bug
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.
### New Integration (75 pts) ### New Integration (75 pts)
**What:** Build a complete new integration from scratch. Build a complete integration from scratch.
**How:** 1. Follow the [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) guide
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. Create: tool + credential spec + health checker + tests + README
2. Follow the [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) guide 3. Register in `_register_unverified()` in `tools/__init__.py`
3. Create: tool implementation + credential spec + health checker + tests + README 4. Run `make check && make test`
4. Register in `_register_unverified()` in `tools/__init__.py`
5. Run `make check && make test`
6. Submit a PR
**Difficulty:** Hard. This is a significant contribution — expect multiple review rounds. 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.
## Rules ## Rules
1. **Claim before you start** — comment on the issue, wait to be assigned 1. **Claim before you start** — comment on the issue, wait for assignment
2. **One person per bounty** — first to claim and get assigned gets it 2. **7-day window** — no PR within 7 days = bounty gets re-opened
3. **7-day window** — if you don't submit a PR within 7 days of being assigned, the bounty is unassigned and re-opened 3. **Max 3 active claims** — don't hoard bounties
4. **Maximum 3 active claims** — don't hoard bounties 4. **Quality matters** — PRs must pass CI and follow templates
5. **Quality matters** — PRs must pass CI, follow templates, and address review feedback 5. **No self-review** and no AI-only submissions without verification
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
## FAQ ## FAQ
**Q: Do I need an API key for every tool I test?** **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. A: Yes. 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.
**Q: How do I become a Core Contributor?** **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?** **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. A: You'll still get credit in GitHub, but no Lurkr XP or Discord roles. Add yourself to `contributors.yml`.
**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.
## Quick Reference ## Quick Reference
| What | Where | | 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) | | Bounty board | [GitHub Issues](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) | | README template | [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) | | Test report template | [templates/agent-test-report-template.md](templates/agent-test-report-template.md) |
| Promotion checklist | [docs/promotion-checklist.md](promotion-checklist.md) | | Promotion checklist | [promotion-checklist.md](promotion-checklist.md) |
| Building tools guide | [tools/BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) | | Building tools | [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) |
| Contributing guide | [CONTRIBUTING.md](../CONTRIBUTING.md) |
| Discord | [Join](https://discord.com/invite/MXE49hrKDk) | | Discord | [Join](https://discord.com/invite/MXE49hrKDk) |
| Your rank | Type `/rank` in Discord | | Your rank | `/rank` in Discord |
| Link your accounts | Add yourself to [contributors.yml](../contributors.yml) |
docs/bounty-program/game-master-manual.md
+65 -227
View File
@@ -1,269 +1,107 @@
# Game Master Manual # 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 ## Your Role
As a game master (maintainer), you:
- Post bounty issues and set dollar values for Core Contributors - Post bounty issues and set dollar values for Core Contributors
- Assign claimed bounties to contributors - Assign claimed bounties to contributors
- Review and merge bounty PRs (which auto-triggers point/XP awards) - Review and merge bounty PRs (auto-triggers XP awards)
- Manually assign achievement badges and the Core Contributor role - Manage the Core Contributor role
- Monitor for gaming and low-quality submissions - 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? ## Reviewing Bounty PRs
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 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? **`bounty:docs`:**
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):
- [ ] Follows the [tool README template](templates/tool-readme-template.md) - [ ] Follows the [tool README template](templates/tool-readme-template.md)
- [ ] Setup instructions are accurate (API key URL works, steps are correct) - [ ] Setup instructions are accurate (API key URL works)
- [ ] Tool table lists all functions with correct names - [ ] Function names match the actual code
- [ ] At least one usage example per tool function - [ ] Not AI-generated without verification
- [ ] API reference link is valid
- [ ] Not obviously AI-generated without verification (check that API URLs and function names match reality)
#### For `bounty:health-check`: **`bounty:test`:**
- [ ] `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`:
- [ ] Test report follows the [template](templates/agent-test-report-template.md) - [ ] Test report follows the [template](templates/agent-test-report-template.md)
- [ ] Includes reproducible evidence (logs, session ID, or screenshots) - [ ] Includes logs, session ID, or screenshots
- [ ] Tests were done with a real API key, not mocked - [ ] Done with a real API key, not mocked
- [ ] Reports both successes and failures honestly - [ ] Reports failures honestly
- [ ] Edge cases section is filled out (even if "none found")
#### For `bounty:bug-fix`: **`bounty:code`:**
- [ ] Bug was found during actual integration testing (not invented) - [ ] CI passes (`uv run pytest tools/tests/test_credential_registry.py` for health checks)
- [ ] Fix addresses the root cause, not just the symptom - [ ] Fix addresses root cause, not symptom
- [ ] Existing tests still pass - [ ] New test added for bug fixes
- [ ] New test added for the specific bug
#### For `bounty:new-tool`: **`bounty:new-tool`:**
- [ ] Full implementation: tool + credential spec + tests + README - [ ] Full implementation: tool + credential spec + tests + README
- [ ] Follows [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) patterns
- [ ] `make check && make test` passes - [ ] `make check && make test` passes
- [ ] Registered in `_register_unverified()` (not verified — needs community testing first) - [ ] Registered in `_register_unverified()` (not verified)
#### 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()`
### Rejecting Submissions ### 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 Never merge low-quality work just to be nice.
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:** ## Core Contributor Promotion
- 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
## 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` **Don't promote** if they only do easy bounties, have been active < 4 weeks, or show signs of gaming.
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
### 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 Post dollar values in `#bounty-payouts` (Core Contributors only):
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
## 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:** - Aim for 10+ unclaimed bounties at all times
- Unassign stale claims (>7 days)
1. The contributor has been active for **4+ weeks** - Shoutout exceptional contributions in announcements
2. They have contributions across **3+ bounty types** (not just one category) - Post milestones ("10th tool promoted to verified!")
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) |
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) 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 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` 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 6. **Announcement** auto-posted in `#integrations-announcements` on Discord
## Current Status ## Current Status
@@ -94,6 +94,6 @@ yahoo_finance, youtube, youtube_transcript, zendesk, zoho_crm, zoom
| Gap | Count | Bounty Type | | Gap | Count | Bounty Type |
|-----|-------|-------------| |-----|-------|-------------|
| Missing README | ~41 | `bounty:docs` | | Missing README | ~41 | `bounty:docs` |
| Missing health_check_endpoint | ~40 | `bounty:health-check` | | Missing health_check_endpoint | ~40 | `bounty:code` |
| Missing HealthChecker class | ~40 | `bounty:health-check` | | Missing HealthChecker class | ~40 | `bounty:code` |
| No community test report | 55 | `bounty:agent-test` | | 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 ./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 (3 min)
## Step 2: Create Discord Channels (5 min)
Create these channels (or rename existing ones):
``` ```
Category: Integrations Category: Integrations
#integrations-announcements (read-only for non-admins) #integrations-announcements (read-only for non-admins)
#integrations-testing
#integrations-help #integrations-help
#integration-showcase
Category: Private Category: Private
#bounty-payouts (visible only to Core Contributor role) #bounty-payouts (visible only to Core Contributor role)
``` ```
**Channel permissions:** **Permissions:**
- `#integrations-announcements`: Everyone can read, only bots + admins can post - `#integrations-announcements`: Everyone reads, only bots + admins post
- `#bounty-payouts`: Visible only to users with the Core Contributor role - `#bounty-payouts`: Core Contributor role only
- All others: open to everyone
## 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 | | 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 | | Open Source Contributor | Purple `#9B59B6` | Yes | No |
| Agent Builder | Green `#2ECC71` | 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) ## Step 4: Install and Configure Lurkr (10 min)
### 4a. Invite Lurkr ### 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 /levels enable
```
### 4c. Configure Message XP
```
/levels set-xp min:15 max:25 /levels set-xp min:15 max:25
/levels set-cooldown seconds:60 /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-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:#integrations-announcements
/levels ignore channel:#bounty-payouts /levels ignore channel:#bounty-payouts
``` ```
### 4e. Configure Role Rewards ### 4c. Configure Role Rewards
``` ```
/levels role-reward add level:5 role:@Agent Builder /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. 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 1. Go to https://lurkr.gg/ and log in
2. Navigate to your profile / API settings 2. Profile > API settings > Create API Key
3. Click "Create API Key" 3. Select **Read/Write** (not read-only)
4. Select **Read/Write** (not read-only) 4. Copy the key
5. Copy the key — you'll need it in the next step
## Step 5: Create Discord Webhook (2 min) ## Step 5: Create Discord Webhook (2 min)
1. Go to **Server Settings > Integrations > Webhooks** 1. Server Settings > Integrations > Webhooks > New Webhook
2. Click **New Webhook** 2. Name: `Bounty Tracker`, channel: `#integrations-announcements`
3. Name it `Bounty Tracker` 3. Copy the webhook URL
4. Set the channel to `#integrations-announcements`
5. 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 | | Secret | Value |
|-------------|-------| |--------|-------|
| `DISCORD_BOUNTY_WEBHOOK_URL` | The webhook URL from Step 5 | | `DISCORD_BOUNTY_WEBHOOK_URL` | Webhook URL from Step 5 |
| `LURKR_API_KEY` | The Lurkr API key from Step 4f | | `LURKR_API_KEY` | Lurkr API key from Step 4d |
| `LURKR_GUILD_ID` | Your Discord server ID* | | `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) ## Step 7: Test the Pipeline (5 min)
### Test 1: Verify the script runs locally
```bash ```bash
GITHUB_TOKEN=$(gh auth token) \ GITHUB_TOKEN=$(gh auth token) \
GITHUB_REPOSITORY_OWNER=adenhq \ GITHUB_REPOSITORY_OWNER=adenhq \
@@ -144,40 +101,15 @@ GITHUB_REPOSITORY_NAME=hive \
bun run scripts/bounty-tracker.ts leaderboard 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: Post all bounties at once on launch day:
- GitHub Action `Bounty completed` runs successfully
- A message appears in `#integrations-announcements`
- If the contributor is in `contributors.yml`, Lurkr XP is awarded
### Test 3: Verify Lurkr role rewards **Documentation (41 issues):** `bounty:docs`, `difficulty:easy`, 20 pts
**Health checks (40 issues):** `bounty:code`, `difficulty:medium`, 30 pts
Check that role rewards are configured: **Testing (55 issues):** `bounty:test`, `difficulty:medium`, 20 pts
```
/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`
### Tools missing READMEs ### Tools missing READMEs
@@ -193,38 +125,18 @@ powerbi, redis
## Verification Checklist ## Verification Checklist
After setup, verify everything works: - [ ] Labels exist (`bounty:*` and `difficulty:*`)
- [ ] Discord channels and roles created
- [ ] Labels exist on the repo (`bounty:*` and `difficulty:*`) - [ ] Lurkr installed, XP configured, role rewards set
- [ ] 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
- [ ] All 3 GitHub secrets added - [ ] All 3 GitHub secrets added
- [ ] `bounty-completed.yml` workflow exists and is enabled - [ ] Both workflows enabled (`bounty-completed.yml`, `weekly-leaderboard.yml`)
- [ ] `weekly-leaderboard.yml` workflow exists and is enabled - [ ] Test PR + merge triggers Discord notification
- [ ] Test PR + merge triggers notification in Discord
- [ ] `contributors.yml` exists at repo root - [ ] `contributors.yml` exists at repo root
## Troubleshooting ## Troubleshooting
**Action runs but no Discord message:** **No Discord message:** Check `DISCORD_BOUNTY_WEBHOOK_URL` secret and Action logs.
- 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
**Lurkr XP not awarded:** **Lurkr XP not awarded:** Confirm API key is Read/Write, contributor is in `contributors.yml`, check Action logs for `Lurkr XP push failed`.
- 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
**Role not assigned after level up:** **Role not assigned:** Verify `/levels role-rewards` config. Lurkr's role must be above the roles it assigns in server hierarchy.
- 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
scripts/bounty-tracker.ts
+5 -11
View File
@@ -68,13 +68,10 @@ interface LeaderboardEntry {
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
const POINTS: Record<string, number> = { const POINTS: Record<string, number> = {
"bounty:smoke-test": 10, "bounty:test": 20,
"bounty:agent-test": 30,
"bounty:docs": 20, "bounty:docs": 20,
"bounty:health-check": 25, "bounty:code": 30,
"bounty:bug-fix": 40,
"bounty:new-tool": 75, "bounty:new-tool": 75,
"bounty:promote": 50,
}; };
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -275,13 +272,10 @@ function formatBountyNotification(bounty: BountyResult): string {
: `**${bounty.contributor}**`; : `**${bounty.contributor}**`;
const typeEmoji: Record<string, string> = { const typeEmoji: Record<string, string> = {
"smoke-test": "\u{1F9EA}", test: "\u{1F9EA}",
"agent-test": "\u{1F916}",
docs: "\u{1F4DD}", docs: "\u{1F4DD}",
"health-check": "\u{1FA7A}", code: "\u{1F527}",
"bug-fix": "\u{1F41B}", "new-tool": "\u{2B50}",
"new-tool": "\u{1F527}",
promote: "\u{2B50}",
}; };
const emoji = typeEmoji[bounty.bountyType] ?? "\u{1F3AF}"; const emoji = typeEmoji[bounty.bountyType] ?? "\u{1F3AF}";
scripts/setup-bounty-labels.sh
+7 -10
View File
@@ -10,17 +10,14 @@ REPO="${1:-adenhq/hive}"
echo "Setting up bounty labels for $REPO..." echo "Setting up bounty labels for $REPO..."
# Bounty type labels # 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:test" --repo "$REPO" --color "1D76DB" --description "Bounty: test a tool with real API key (20 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:docs" --repo "$REPO" --color "FBCA04" --description "Bounty: write or improve documentation (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:code" --repo "$REPO" --color "D93F0B" --description "Bounty: health checker, bug fix, or improvement (30 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:new-tool" --repo "$REPO" --color "6F42C1" --description "Bounty: build a new integration from scratch (75 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: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 # Difficulty labels
gh label create "difficulty:easy" --repo "$REPO" --color "BFD4F2" --description "Good first contribution" --force gh label create "difficulty:easy" --repo "$REPO" --color "BFD4F2" --description "Good first contribution" --force
gh label create "difficulty:medium" --repo "$REPO" --color "D4C5F9" --description "Requires some familiarity" --force gh label create "difficulty:medium" --repo "$REPO" --color "D4C5F9" --description "Requires some familiarity" --force
gh label create "difficulty:hard" --repo "$REPO" --color "F9D0C4" --description "Significant effort or expertise needed" --force gh label create "difficulty:hard" --repo "$REPO" --color "F9D0C4" --description "Significant effort or expertise needed" --force
echo "Done. Labels created for $REPO." echo "Done. Labels created for $REPO."