A standard for writing open source issues that AI assistants can help solve.
Most people want to contribute to projects they use but don't know where to start. The codebase is unfamiliar, the setup is complex, and who has time to learn a whole project just to fix one thing?
AI-Ready Issues solve this by giving contributors everything they need — context, requirements, expected behavior — formatted so they can paste it into Claude, ChatGPT, or any AI assistant and get working code back.
The question isn't "should we use AI in open source?"
The question is: how do we structure participation so AI becomes a force multiplier for contribution, not a substitute for it?
Most people want to contribute to projects they use but don't know where to start. The codebase is unfamiliar, the setup is complex, and who has time to learn a whole project just to fix one thing?
But what if maintainers gave you everything you needed — context, requirements, expected behavior — formatted so you could paste it directly into Claude/ChatGPT and get working code back?
That's the idea behind AI-Ready Issues: a standard that lets anyone contribute their AI subscription to a project.
Here's how it works:
- Contributors find an AI-Ready issue
- Copy the issue into their AI assistant
- Review and test the output — understand every line
- Submit it back to GitHub as a pull request
- Note that AI was used so maintainers know what to scrutinize
The bottleneck in open source has never been talent. It's context. A skilled developer can fix most bugs in most projects, but they'd need hours just to understand the codebase enough to attempt it. AI-Ready Issues eliminate that barrier.
AI assistants are good at taking structured context and producing working code. Humans are good at reviewing, testing, and understanding intent. This standard combines both strengths — crowdsourced open source, powered by distributed AI compute.
The contributor still needs to:
- Understand what the code does
- Test it in their environment
- Take responsibility for what they submit
- Disclose that AI was used
The AI just gets them past the blank-page problem.
I've applied this to my own crowdsec-blocklist-import (147 stars, 10+ AI-ready issues). If you'd like to participate or see it in action, check it out.
An AI-Ready issue includes:
- Context — what the project does, relevant files, architecture
- Current behavior — what happens now (with code references)
- Expected behavior — what should happen
- Implementation guide — file paths, function names, code snippets showing where to make changes
- Acceptance criteria — specific, testable requirements (checkboxes)
- Constraints — what not to break
- AI Prompt — a copy-paste-ready block that feeds the AI everything it needs
Maintainer writes AI-ready issue
|
v
Contributor copies it into Claude/ChatGPT/Copilot
|
v
Contributor reviews output, tests it, learns from it
|
v
Contributor submits PR with AI disclosure
|
v
Maintainer reviews and merges
The AI-ready format has a cost. Writing a good issue takes 10-20 minutes of structured thinking — context, implementation guide, acceptance criteria, AI prompt. That investment only pays off when the issue is the right size.
Too small — If you can fix it faster than you can describe it, just fix it. A two-line change doesn't need a structured template. The overhead of writing the issue exceeds the value of crowdsourcing the fix.
Too large — If the change touches 10 files across 3 subsystems, no amount of context will make it AI-friendly. The model loses coherence, the contributor can't meaningfully review the output, and the PR becomes un-reviewable.
The sweet spot — A single, well-bounded change that requires real codebase knowledge to implement but not to understand. Adding a new endpoint behind a clear interface. Fixing a bug where you know the root cause but the fix touches code a newcomer wouldn't find. Implementing a feature where the design is settled but the contributor needs to know where things live.
The maintainer's judgment is what makes this work. You know your codebase — you know which changes are self-contained enough for someone to pick up cold. That curation is the standard's real value.
See the Maintainer Guide for detailed guidance on when to use (and not use) this standard.
- Lowering the barrier to open source participation
- AI handles boilerplate, humans handle thinking
- Turning "I wish this had feature X" into "I'll just add it"
- Distributed development using distributed compute
- Dumping untested AI garbage
- Submitting code you don't understand
- Replacing real developers
- Writing issues for things you could fix faster yourself
- Copy the issue templates into your repo
- Adapt the CONTRIBUTING.md template for your project
- Write issues using the AI-Ready format
- Label them
ai-readyso contributors can find them
- Find an issue labeled
ai-ready - Copy the issue body + the project's AI context block (from CONTRIBUTING.md)
- Paste into your AI assistant
- Review every line of output — understand it before submitting
- Test locally
- Submit a PR with AI disclosure
| File | Purpose |
|---|---|
| templates/CONTRIBUTING.md | Drop-in CONTRIBUTING.md with AI contribution guidelines |
| .github/ISSUE_TEMPLATE/ai-ready-bug.md | Bug report formatted for AI consumption |
| .github/ISSUE_TEMPLATE/ai-ready-feature.md | Feature request formatted for AI consumption |
| templates/PR_TEMPLATE.md | Pull request template with AI disclosure section |
| guide/MAINTAINER_GUIDE.md | How to write effective AI-ready issues |
| guide/CONTRIBUTOR_GUIDE.md | How to use AI responsibly for contributions |
- crowdsec-blocklist-import — 147 stars, 10+ AI-ready issues
- crowdsec-unifi-bouncer — 13 stars, 10 open issues
- emby-playback-guardian — Playback protection for Emby/Jellyfin
- homeops-mcp — Home infrastructure MCP server
Using this standard? Open a PR to add your project here.
Inspired by Fedora's 2025 policy on AI-assisted contributions which established that AI-assisted contributions are welcome when contributors take responsibility for the output.
This standard takes that a step further: instead of just allowing AI contributions, we actively optimize for them by structuring issues so AI tools can be maximally effective.
This standard itself is open for contributions. If you have ideas for improving the templates, workflow, or documentation, open an issue or PR.
MIT — use these templates in any project, commercial or open source.