Requel started in 2009 as my Harvard Extension thesis: a web-based requirements tool where everyone with a stake in a project works on the same model of it, and an automated assistant points out problems as they write. Last year’s 1.2 moved it onto Java 17 and Spring Boot 3 without changing what it did. Version 2.0, released this week, changes what it does. Like the posts before it, I built this release pairing with Claude: planning, code, the release-candidate testing, and this write-up.

I’ve written about pieces of it already: the MCP server’s move to Streamable HTTP, OAuth 2.1 for MCP clients and making codex mcp login just work. This post is the overview: what’s in 2.0, how I used it on a real project at work, and how to try it yourself in a few minutes.

What Requel models

A Requel project holds more than a list of tickets:

  • Goals say what must be true and why.
  • Stories are prose about a process or an outcome.
  • Actors are the roles that take part.
  • Use cases collect the flows for one task, which can succeed, fail or vary.
  • Scenarios are single flows, made of steps that can be shared between scenarios.
  • The glossary defines the project’s terms, including which names are synonyms of which.
  • Stakeholders are the people (users with permissions) and the organisations with an interest.

On top of that sits a discussion layer: anyone can raise an issue on an entity, propose positions and argue for or against them, and resolve the issue by choosing one. That is the layer the automated assistance writes into. A finding is an issue you discuss, not a lint warning.

What’s new in 2.0

A new user interface

The 2009 Echo2 server-side UI is gone. 2.0 is an Angular single-page app bundled into the same jar, so deployment is still one jar and one database. Pages refresh live when another person, or an assistant, changes something you’re looking at. The user guide walks through every page with screenshots of the sample project.

An API and a CLI

Everything the UI does goes through one command API (POST /api/commands/{type}) and a set of read endpoints, so anything you can do in the UI you can script. requel-cli, attached to each GitHub release, wraps it for the terminal:

java -jar requel-cli-2.0.0.jar login --oauth          # browser sign-in, refreshable token
java -jar requel-cli-2.0.0.jar projects               # what you can read
java -jar requel-cli-2.0.0.jar open-issues Requel     # unresolved issues, highest severity first
java -jar requel-cli-2.0.0.jar run EditGoal --input '{"projectName":"Requel","name":"..."}'

Logging in with --oauth keeps a refresh token, so the CLI stays signed in rather than asking again every hour. A personal access token works too, for scripts.

An MCP server

The same commands are exposed over MCP, so Claude Code, Codex, VS Code and other AI clients can read and edit a project directly, signed in through OAuth as a real Requel user. Every call goes through the same permission checks and audit log as the UI. An agent can only do what the user it signed in as can do, and you can see afterwards what it did. That turned out to be the most useful part of the release for me, and the example below is built on it.

Automated assistance

The original assistant used natural-language processing to flag spelling, vague words, overly complex sentences and phrases that ought to be glossary terms. It’s still there, rewritten to be precise enough to leave on: it no longer flags acronyms or the project’s own vocabulary, raises a glossary candidate once per project rather than once per sentence, and its findings are advisory.

The new part is AI review. Assistants review goals, stories, use cases, scenarios, steps, actors and glossary terms, each with a review definition written for that type. A goal reviewer looks for different problems from a scenario reviewer. Definitions are data, not code: a project can turn them on or off, write its own, or add cross-cutting policies such as “flag anything that looks like a credential”. Some analyses look across the whole project rather than one entity, for goals that overlap or conflict.

It works with OpenAI, Anthropic, Gemini or a local model through Ollama. Before anything leaves the server it’s redacted (credentials, emails, phone numbers, card numbers), and a project can forbid sending anything to an external provider at all. When you edit an entity, its existing findings are marked stale rather than left looking current.

Requirements as a living document

Entities can record where they came from: a ticket, a document, a URL. Report generators render the model back out, including a Markdown ticket format with the open issues sorted by severity. The idea is a round trip: read tickets in, find what’s wrong with them, and emit a corrected version. The next section shows why I wanted that.

Docker images for both architectures

Requel is published to Docker Hub as rreganjr/requel, with 2.0.0 and latest built for both linux/amd64 and linux/arm64. It runs natively on an Apple Silicon Mac or an ARM server without the emulation warning. The repo carries two Compose files: one for Requel and MySQL, and one that adds an Ollama container so AI review works with no API key.

An example: modelling a work side project

The release grew out of using Requel on something real. At Medlive, where I work, I picked up ownership of a small internal tool, a side project for the team, whose handoff was described in two tickets: an epic and one child. They were well-written tickets, which is why I chose them: anything Requel found would be a problem with the format, not the author. I’ll keep the internal details out, but the shape of what happened is the interesting part.

I connected Claude Code to Requel over MCP and had it read the two tickets into a project: goals, actors, use cases with their alternate flows, scenarios, stories and glossary terms, each attached to the entity it came from.

The description held the requirements

Seven goals came from the acceptance criteria, one each. Everything else came from the prose around them: every actor (operator, viewer, panelist, host, the engineer on call), every use case, the stories, and the only statement anywhere of what the system is for.

The reason wasn’t careless writing. The acceptance-criteria field was being used for verification steps (“the test script passes on a clean checkout”) rather than requirements. A test procedure tells you how you’ll know, not what must be true or why, so the real requirements drifted into the description where people explain things. Requel keeps those apart: a goal states what must be true, and a scenario is a flow you can walk. One acceptance criterion was really a six-step scenario packed into a checkbox.

Findings inside a single goal

Reviewing goals one at a time turned up problems a generic “is this ambiguous?” prompt flattens into one bucket:

  • A solution, not an outcome. A goal that named a specific identity provider’s mechanism. Swap the provider and the goal becomes impossible, though the intent hasn’t changed.
  • A person, not a role. A goal saying a named individual is “no longer required”. Modelled properly, that person is an actor (the operator role) and separately a stakeholder. The part that’s about software becomes the operator role can be filled by more than one person, which is testable.
  • Two goals welded together. “Alarms route to the team, each with a documented response” has two parts that finish independently.
  • A goal that’s true when nothing exists. “All alarms route to the team” was satisfied perfectly at the time, because there weren’t any alarms. A goal over a set needs the set’s existence stated too.

Findings across the tickets

The most valuable findings weren’t in any single entity. Each ticket was correct on its own:

  • The epic’s CI requirement listed exactly the checks in one script. The child ticket warned that the UI tests, which aren’t in that script, skip silently when a dependency is missing, “so an unnoticed skip reads as a pass”. The specified pipeline never ran them at all.
  • The epic said the recording is produced “when the room is ended”. The child listed ending a room and archiving one as separate steps. So end and archive are different states, neither is defined, and someone reading only the epic builds the wrong state machine.
  • The epic required every review finding to be “fixed or closed with a written reason”. The child reported findings as “fixed or deferred”. Deferred isn’t closed, so the parent’s criterion couldn’t be met by the child’s own account.
  • Three different names were used for a test session. In Requel that became one glossary term with two synonyms, the only fix in the exercise that landed in the model rather than in a comment.

More sources beat more analysis

Then I added two more sources: the operator guide and an earlier code review. They changed the model more than any further analysis of the tickets could have. The guide described a second streaming channel the tickets didn’t mention, a second state machine, and which control is for recovery versus a leaked key.

The humbling one: the tickets reported the review findings as a split that added up, and I had checked the arithmetic and treated “the numbers are consistent” as fine. The review itself said the split was a recollection, never a count, and the real split was different. Consistency checking can’t detect a shared wrong premise. Two documents that agree can both be wrong. Requel’s AI review test fixture now includes a case exactly like that, and its scoring flags any review that calls the numbers consistent.

Emitting the ticket back out of the three-source model gave a version that was clearer and more correct than the original. Every material correction came from a new source, not from reviewing harder. A living document is only as good as what feeds it.

What it did to 2.0

This exercise shaped a good part of the release. The first pass buried nine real findings under 65 spelling, vague-word and glossary-candidate issues. That’s why the lexical assistant was rewritten and made advisory. Separate review definitions for each entity type, cross-entity analyses, sibling goals in a goal’s review context, goal relations beyond “supports” and “conflicts”, source tracking, and the ticket report generator all trace back to something this project needed and Requel couldn’t hold.

Try it out

All you need is Docker. This runs Requel, MySQL and Ollama together with no API key:

mkdir requel && cd requel
curl -fsSLO https://raw.githubusercontent.com/rreganjr/Requel/v2.0.0/docker-compose.local-ai.yml
echo "REQUEL_JWT_SECRET=$(openssl rand -base64 48)" > .env
docker compose -f docker-compose.local-ai.yml up -d
docker compose -f docker-compose.local-ai.yml exec ollama ollama pull qwen2.5:3b

The first start takes a few minutes while the dictionary loads. Then open http://localhost:8080/, sign in as admin / admin, and change the password. To have something to look at straight away, download the sample project (Requel’s own requirements) and import it from Projects → Import.

In 2.0 an AI review is requested through the API, as you. Create a personal access token under Settings → Personal Access Tokens, open any goal (its id is the number at the end of the URL), and ask for a review:

export REQUEL_TOKEN=reqpat_...   # the token you just created
curl -X POST "http://localhost:8080/api/ai/reviews?entityType=Goal&entityId=2" \
  -H "Authorization: Bearer $REQUEL_TOKEN"

It runs in the background, and its findings appear as issues on the goal when it finishes. Or connect an MCP client and ask it to review the project for you.

A 3-billion-parameter local model is enough to see how the review works, not enough for good reviews. For real use, point Requel at a larger local model or a cloud provider.

For anything beyond a local trial:

If you try it, I’d like to hear what it finds in your requirements. Issues and ideas are welcome on GitHub.