An Update to OpenSpec's Contribution Policy

We're no longer accepting unsolicited pull requests. Please open a GitHub issue first. PRs require maintainer approval.

Over the past year, OpenSpec has grown from a small project into something used by developers across a wide range of coding agents and workflows. We've also seen a steady increase in people wanting to contribute.

AI coding agents have made it easier than ever to go from having an idea to opening a PR in minutes. That's been great to see, but reviewing pull requests still takes considerable time and attention.

It's not just about whether the code works. We need to understand the problem, evaluate the approach, consider its impact on the rest of the project, and decide whether it's something we should be prioritizing.

Many PRs end up sitting open for longer than we'd like, often because we haven't agreed on whether the change is something we want to pursue.

We'd previously encouraged contributors to discuss larger changes and submit OpenSpec change proposals before implementation. But even a change proposal can be too far along in the process. By then, someone has often settled on a solution before we've discussed whether OpenSpec should solve the problem at all.

So we're making a change. Going forward, we won't be accepting unsolicited pull requests. Instead, we'd like contributions to start with a GitHub issue.

What's changed about contributing?

I remember contributing to open-source projects before AI coding agents became commonplace. Before opening a PR, I'd spend hours exploring an unfamiliar codebase, getting the project running, and figuring out how everything fitted together.

That effort didn't guarantee a good contribution, but it helped me develop an understanding of the project beyond the particular problem I was trying to solve.

Today, much of that work can be handed off to an agent. You can describe a bug or feature you'd like and get back a working implementation without ever needing to understand the surrounding system yourself.

The problem isn't necessarily the quality of the code. It's that an agent is usually working from the perspective of the person making the request.

It might produce a perfectly reasonable solution for that person's workflow without considering whether it makes sense for everyone else.

That's particularly tricky for OpenSpec. We support many different coding agents, models, and workflows. A change that benefits one person's workflow might introduce problems for others, or add complexity we're not prepared to maintain.

The expectations for a good contribution haven't really changed. We still value people who understand the problem, question their assumptions, and consider how a change fits into the larger project.

What's changed is how easily someone can produce an implementation without developing that understanding along the way.

What makes a good contribution?

Not all issues are the same, and we don't expect every contribution to come with a detailed analysis.

For bugs, we're primarily interested in reproducibility. Tell us what you were trying to do, what happened, what you expected instead, and how we can reproduce it. Error messages, logs, and minimal examples are especially helpful.

For agent behavior issues, context matters (quite literally, including what's in the agent's context window). OpenSpec runs across different models, coding agents, and environments, all of which can influence the results. Agent session traces are particularly helpful here. Understanding which files an agent read, which tools it called, and how its behavior changes across multiple sessions can help us narrow down what's actually going wrong.

For feature requests and larger changes, we're looking for more than a proposed solution. We'd love to understand the problem, how it affects other users, what alternatives you've considered, and whether the added complexity is worth maintaining.

Sometimes a reported limitation is actually a deliberate design choice. Before changing that behavior, we need to consider why it exists, what trade-offs were made, and whether supporting the new use case is something OpenSpec should take on.

You don't need to have all the answers. But we do want issues to reflect some understanding and consideration of the problem, rather than simply forwarding an agent-generated diagnosis or implementation.

How contributions will work

Start with a GitHub issue. We can discuss the problem, explore possible approaches, and decide whether it fits with OpenSpec's priorities.

If we agree to pursue it, maintainers can implement the change directly or invite the contributor to help build it with us.

Of course, moving to issues won't solve everything. AI-generated issues can be just as poorly considered as PRs, and we won't be able to respond to or implement every suggestion.

But we'd rather spend our time discussing ideas with the community than reviewing implementations we haven't agreed to pursue.

If you've contributed to OpenSpec before, thank you. We genuinely appreciate the time and effort you've put into making the project better.

And if you've got an idea for what we should do next, open an issue. We'd love to hear about it.