The Philosophy

Most software teams use five or more tools to manage their requirements process. The business requirement is captured in Confluence. The ticket is in Jira. The design is in Figma. The test plan is in a spreadsheet. The implementation notes are in Slack.

None of these tools talk to each other. By the time a feature reaches QA, the original requirement has mutated across six conversations, two document versions, and a comment thread. Nobody remembers why a decision was made. Nobody can prove what was agreed.

AI cannot help here either. When requirements live in a proprietary system behind a login, an AI agent cannot read them, verify them, or build on them. The context is locked away.

Markdown renders everywhere. It diffs cleanly in git. It can be read, generated, and modified by any AI agent without parsing or API access. It is the only format that is simultaneously human-readable, machine-readable, and version-controllable.

When a BRD is a Markdown file in a git repository, you get something no Confluence page can offer: an immutable, timestamped, attributed history of every change. You can see what the requirement said on day one, who changed it, and why. That is your audit trail.

The same file that your BA writes is the file your developer reads, your QA engineer links from a test case, and Baxter verifies against the codebase. One source of truth. No synchronisation problem.

Every change to a requirement is a commit. Every commit has an author, a timestamp, and a message. Pull request reviews on a BRD become the formal approval record. Branch protection means no requirement changes without review.

This is not a new idea — it is the same principle that made code review a standard practice. Requirements deserve the same rigour. With git, they get it for free.

a3f1c2e  Add AC-05 for role-based access to care plan view
           BA: binu-alexander · 2 days ago

b8d0991  Revise FR-03: load time changed from 3s to 2s after tech review
           BA: binu-alexander · 5 days ago

1e4a7b3  Initial BRD for care plan cloning feature — Baxter (AI)
           BA: binu-alexander · 1 week ago

The harness is designed around one principle: Baxter is fast at producing first drafts, and humans are essential for catching subtle errors. The two roles must not be confused.

Every artefact is AI-generated and human-verified. Baxter reads the raw client request, selects the correct template, checks the draft against the real codebase, and flags any discrepancies — wrong module names, invented field names, routes that do not exist. A human then reviews the output and adds their name to the revision history.

Nothing is authoritative until a human approves it. The codebase check catches obvious errors automatically. Human review catches the rest. Both are required.

There is no server, no database, no proprietary format. The harness is two things: canonical templates that give every artefact consistent, verifiable structure, and a codebase check that prevents invented names from reaching a requirement.

CLAUDE.md exists only to route requests to the right template and enforce the verification step. It is not the product — the templates are. Drop the folder into any project, point your AI agent at it, and start writing requirements.

Templates live in two folders — templates/issues/ (BR, CR, AI) and templates/other/ (BRD, PD, TIP, TC, DIA). Edit any of them to match your team's conventions — Baxter reads whatever is on disk.

For a long time, the business analyst sat between the business and the technical team. Requirements went in one end. Code came out the other. The BA's job was to translate — and the gap in that translation was where most projects failed.

That model is over. Baxter makes it possible — and necessary — for non-technical team members to orchestrate the production of artefacts that are directly grounded in the codebase. Not just documented in plain English. Verified against real module names, real field names, real routes.

This is the paradigm shift: the BA orchestrates Baxter to read the code, check the facts, and produce the first draft. The BA brings domain expertise, stakeholder context, and the final sign-off. Neither alone is sufficient.

You do not need to understand how the code works. You need to work with Baxter — who will flag "the module 'CareRecords' does not exist; did you mean 'CarePlans'?" before the BRD reaches a developer.

Non-technical team members who work this way are now more effective than technical team members who do not. The tooling is not the barrier. Using it is.

BA work arrives messy. A client sends a voice note. A product manager pastes a Slack thread. A stakeholder emails three paragraphs of loosely related requests.

Baxter meets it there. You paste the raw message into your AI agent. Baxter reads it, classifies it, announces which template it will use, and asks for a one-word confirmation before generating anything. No forms to fill in. No structure to impose on the client. No commands to remember.

The formality is in the output, not the input.