hive/docs/bounty-program/contributor-guide.md

Contributor Guide — Bounty Program

Earn XP, Discord roles, and eventually real money by contributing to the Aden agent framework — from quick fixes to major features and integration work.

Getting Started

1. Link your GitHub and Discord

Run /link-github your-github-username in Discord. The bot will give you a verification code — create a public gist with that code, then run /verify. Done.

Without this link, Lurkr can't push XP to your Discord account.

2. Pick your first bounty

Browse GitHub Issues with bounty labels. Start with bounty:docs or difficulty:easy.

Comment "I'd like to work on this" and wait for a maintainer to assign you.

Tiers

Tier	How to Reach	What You Get
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 nomination	Dollar values on bounties, paid per completion

XP comes from GitHub bounties (auto-pushed on PR merge) and Discord activity in #integrations-help.

Bounty Types

There are two categories: integration bounties (tool-specific) and standard bounties (general contributions).

---

Integration Bounties

Test a Tool (20 pts)

Test an unverified tool with a real API key and report what happens.

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
4. Submit as a comment on the issue or a file in a PR

Report both successes and failures. Finding bugs is valuable.

Write Docs (20 pts)

Write a README for a tool that's missing one.

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
4. Submit a PR adding README.md to the tool directory

Function names and API URLs must match reality — no AI hallucinations.

Code Contribution (30 pts)

Add a health checker, fix a bug, or improve an integration.

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

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)

Build a complete integration from scratch.

1. Follow the 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

Expect multiple review rounds.

---

Standard Bounties

General contributions to the framework — not tied to a specific integration. Sized by effort and impact.

Small (10 pts)

Quick, focused fixes. Great for first-time contributors.

• Fix typos or broken links in documentation
• Improve an error message to include actionable guidance
• Add missing type annotations to a module
• Reproduce and confirm a bug report with environment details
• Fix linting or CI warnings

How: Open a PR with the fix. Tag with bounty:small.

Medium (30 pts)

Meaningful improvements that require reading and understanding existing code.

• Fix a non-critical bug with a regression test
• Write a how-to guide or tutorial
• Add or significantly improve test coverage for a core module
• Improve CLI help text, argument validation, or UX
• Add structured logging or observability to a module

How: Claim the issue first. Submit a PR with tests where applicable. Tag with bounty:medium.

Large (75 pts)

Significant work that adds real capability or improves the project substantially.

• Implement a new user-facing feature end to end
• Performance optimization with before/after benchmarks
• Build a new CLI command or subcommand
• Write comprehensive architecture documentation for a subsystem
• Add a new credential adapter type

How: Claim the issue and discuss your approach in the issue before starting. Submit a PR. Tag with bounty:large.

Extreme (150 pts)

Major contributions that shape the project's direction. Requires maintainer pre-approval.

• Design and implement a major subsystem (e.g., plugin system, caching layer)
• Security audit of a core module with findings and fixes
• Major refactor of core architecture
• Build a complete example application or reference implementation
• End-to-end testing framework for agent workflows

How: Comment on the issue with a design proposal. Wait for maintainer approval before starting work. Tag with bounty:extreme.

Rules

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. Most services have free tiers. The bounty issue links to where you get the key.

Q: How do I become a Core Contributor? 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 get credit in GitHub, but no Lurkr XP or Discord roles. Run /link-github in Discord.

Quick Reference

What	Where
Bounty board	GitHub Issues
README template	templates/tool-readme-template.md
Test report template	templates/agent-test-report-template.md
Promotion checklist	promotion-checklist.md
Building tools	BUILDING_TOOLS.md
Discord	Join
Your rank	/rank in Discord