The Philosophy
Why Markdown, git, and the Baxter agentic framework are the right foundation for SDLC knowledge management.
What is an agentic harness?
Definition
An agentic harness is a structured layer of instructions, rules, templates, samples, and folder structure that wraps an AI agent and makes it produce ridiculously better, more reliable results for a specific job. It gives the agent the ultimate context for a repeatable task — what to do, what not to do, and what a good result looks like — so the output is the one you actually want, every time. The agent brings the reasoning and the actions; the harness brings the discipline, the context, and the format.
It is the agent-specific form of the broader idea of an AI harness. The two terms are often used interchangeably — the difference is whether the model simply responds, or actually acts.
AI harness vs. agentic harness
An AI harness is the umbrella term: any layer of instructions and templates wrapped around a language model to make its output consistent and useful.
An agentic harness is the agent-specific form. The model does not just answer a question — it acts. It classifies the incoming request, decides which path to take, reads a real source of truth, calls tools, and verifies the result before returning it. Every agentic harness is an AI harness; not every AI harness is agentic.
That difference is the whole point of Baxter: it does not simply draft a document from a prompt. It reads your codebase, checks each claim, and flags anything that cannot be built — the behaviour of an agent, governed by a harness.
Why an agentic harness beats raw prompting
A modern model will answer almost anything you ask. The problem is not capability — it is consistency. Ask the same model for a requirements document twice and you get two different shapes, two different levels of rigour, and no guarantee either one checked its facts.
An agentic harness removes that variance. It tells the agent exactly what role to play, forces it to classify the request before acting, hands it the right template, and requires it to verify every claim against a real source of truth. The output stops being a plausible-sounding draft and starts being something a human — or another system — can act on immediately.
What goes into an agentic harness
Everything the agent needs to repeat a task well: what to do, what not to do, what to learn from, and where it all lives — plus the decision loop that makes it agentic.
Things to do
Instructions
Who the agent is, what it is for, and the steps for each repeatable task — its role and its standing orders.
Things not to do
Rules
Guardrails and routing logic that keep every run on the rails — the hard limits the agent must never cross.
The shape of the output
Templates
A fixed, verifiable structure for every output, so results are repeatable and reviewable — never ad hoc.
Things to learn from
Samples
Worked examples the agent pattern-matches against, so it learns the standard from demonstration, not description.
Where everything lives
Folder structure
A disciplined layout so the agent — and your team — always know where inputs go and where each output belongs.
What makes it agentic
The decision loop
The agent acts on all of the above — it classifies each request, chooses a path, reads a real source of truth, and verifies the result before returning it.
Agentic harness vs. app vs. framework
| Approach | What it is | What you run |
|---|---|---|
| App | Software with its own server, database, and login. | A hosted service you subscribe to. |
| Framework | A codebase you build on top of and deploy. | Your own application, plus infrastructure. |
| Agentic harness | Plain files — instructions, rules, templates, samples — that steer an agent you already have. | An AI agent you already use, pointed at a folder. |
The harness is the lightest of the three by design. There is nothing to host, install, or maintain — which is exactly why it is the fastest way to get reliable, specialised output from an AI agent you already pay for.
Configuring Baxter
Drop a preferences.json file in the project root to change how Baxter behaves. All settings are optional — Baxter runs on the defaults below if the file is absent.
{
"pushAfterCommit": false,
"confirmBeforeSave": true,
"confirmBeforeCommit": true,
"confirmBeforeGenerate": true,
"runSanityCheck": true,
"includeTechnicalNotes": true,
"includeAcceptanceCriteria": true,
"language": "en-GB",
"integrations": {
"issueTracker": { "enabled": false, "provider": "none", "workspace": "" },
"github": { "enabled": false, "useCli": false, "useProjects": false,
"repo": "", "projectNumber": "" }
}
} | Setting | Default | What it controls |
|---|---|---|
| pushAfterCommit | false | Push to remote automatically after every commit. When false, you push manually. |
| confirmBeforeSave | true | Ask before writing any artefact file. Set to false to save immediately. |
| confirmBeforeCommit | true | Ask before running any git commit. Set to false to commit without prompting. |
| confirmBeforeGenerate | true | Announce the classified artefact type and ask for confirmation before generating. Set to false to skip straight to output. |
| runSanityCheck | true | Read coderepo/ and run the full sanity check after every applicable artefact. Set to false for faster, unverified drafts. |
| includeTechnicalNotes | true | Include the Technical Notes section in all artefacts. Set to false to omit it — useful for non-technical audiences. |
| includeAcceptanceCriteria | true | Include an Acceptance Criteria section in Change Request (CR) and Bug Report (BR) artefacts where applicable. Set to false to omit it from both. Other artefact types are unaffected. |
| language | "en-GB" | Writing language. Use "en-GB" for UK English or "en-US" for US English. |
| integrations | all off | Which external systems Baxter may use — an issue tracker, and GitHub. Every one is off on a fresh clone; see below. |
Any codebase, any stack — and every integration is optional
Baxter assumes nothing about your language, framework, folder layout, repository host, or issue tracker. All it needs is your source code in coderepo/ and the templates. When a skill has to find something — an AI feature, a module, a schema — it reads your codebase to work out where that lives rather than expecting a particular path, and tells you which locations it used.
Nothing external is touched until you say so. The two integrations that talk to other systems are declared in the integrations block of preferences.json and are off on a fresh clone. A toggle that is off is a decision, not a gap — Baxter skips that step, says so in one line, and produces the artefact anyway.
Issue tracker
integrations.issueTracker
Filling a Change Request's Source Request URL, and enriching release notes with links. Pick your provider: ClickUp, Jira, Linear, Azure DevOps, GitHub Issues, or another — Baxter uses that product's own vocabulary.
When off: The field stays a placeholder. Nothing else changes.
GitHub
integrations.github
gh CLI for fetching issues for release notes, cross-referencing them during release validation, and duplicate-checking before creating one. Projects support adds a new issue to a board.
When off: Skipped with a one-line note — the artefact is produced anyway. Paste the issue text if it is needed.
PDF tooling
md-to-pdf · pandoc · Chrome
Exporting a PDF alongside a Markdown artefact, for test plans, release notes, and validation reports.
When off: You get the Markdown, plus a note naming the tool that would produce the PDF.
Publishing your own fork? One extra file to know about. +
To configure Baxter you edit preferences.json — that is the whole story for almost everyone. But it is a committed file, so whatever you set in it is what anyone cloning your fork receives. If you are publishing a fork and would rather your own integration settings did not travel with it, leave that file on the defaults and put yours in preferences.local.json instead — gitignored, never published, overlaid on the defaults at session start. It does not exist in a fresh clone and most projects never need it.
{
"integrations": {
"issueTracker": { "enabled": true, "provider": "clickup" },
"github": { "enabled": true, "useCli": true }
}
} No core artefact — BRD, PRD, PD, TIP, TC, BR, CR, AI, DIA, ERD, CLQ — depends on any of them. A project on GitLab, Bitbucket, or no remote at all, tracked in Jira, Linear, or a spreadsheet, is fully supported.
Frequently asked questions
What is an agentic harness? +
An agentic harness is a structured layer of instructions, rules, templates, and worked samples that wraps an AI agent — a model that classifies a request, decides what to do, calls tools, and verifies its own work — and makes it produce dramatically better, more reliable results for a specific job. The agent supplies the reasoning and the actions; the harness supplies the discipline, the context, and the format.
What is the difference between an AI harness and an agentic harness? +
An AI harness is the broad term for any instructions-and-templates layer wrapped around a language model. An agentic harness is the agent-specific form of it: the model does not just answer, it acts — routing the request, reading a real source of truth, calling tools, and checking the result before returning it. Every agentic harness is an AI harness; not every AI harness is agentic.
How is an agentic harness different from an app or a framework? +
An app is software you log into, with its own server, database, and account. A framework is a codebase you build on top of. An agentic harness is neither — it is configuration and context (plain files) that you point an existing AI agent at. There is nothing to host, install, or subscribe to; you bring your own model through an agentic tool like Claude Code, Cursor, or GitHub Copilot.
What goes into an agentic harness? +
Five things: instructions (what to do), rules (what not to do), templates (the shape of the output), samples (worked examples to learn from), and a folder structure (where every input and output lives). On top of those, an agentic harness adds the decision loop: the agent classifies each request, acts on it, and verifies the result against a real source of truth before returning it.
Is Baxter an agentic harness? +
Yes. Baxter is an agentic business-analysis harness. You clone it, drop your codebase into its coderepo/ folder, and point your AI agent at it. It then behaves like a senior business analyst — classifying each request, drafting the right artefact, and verifying every one against your real code before you see it.
How does an agentic harness stop the AI from inventing plausible details? +
By deciding, in advance, what counts as evidence for each kind of claim — and by making the evidence travel with the claim. Baxter does this with two registries generated from the codebase: one for the modules the product is made of, one for the roles built into it. A module or role that is not in the code cannot enter either, no matter how confidently a document, a spreadsheet, or the model itself asserts it. Roles are held to the stricter standard of the two, because the failure is silent: a wrong module name shows up in a filename slug, whereas a wrong role name quietly corrupts every access statement built on it. So every role is written with its literal code identifier beside it — the one code-level string allowed in an artefact body, and the thing that makes the claim checkable rather than merely plausible.
Can an agentic harness document a product that was already built without any requirements? +
Yes — this is where an agentic harness pulls ahead of a template pack, because the agent can read the source of truth rather than wait to be told about it. In Baxter, the /generate-retrospective-brd skill points at a codebase and works backwards to a client-facing business requirements document: the modules, the roles and personas, why the product exists, and what each module lets a user do. It runs standalone, so nothing else has to exist first. Anything the code cannot evidence — the business case in particular — is left as an explicit placeholder for the client to confirm rather than invented, and the finished document says on its face that it was reverse-engineered from shipped code rather than written before the build, so nobody mistakes one for the other.
How Baxter works — end to end
Every request follows the same path: raw input in, verified artefact out, saved to your local artefacts/ folder. Baxter handles classification, drafting, and codebase verification. You handle review and approval — and every generated artefact stays off GitHub by default.
email · Slack · voice note · Google Doc
reads signal words · confirms before writing
BR · CR · AI · BRD · PRD · PD · TIP · TC · DIA · ERD
→ templates/
coderepo/ seven dimensions — names · feasibility · logic · data model · roles · gaps · UX
module + role registries re-read every time, never remembered
flagged and auto-corrected in draft
❌ blockers → optional CLQ (templates/CLQ-Client-Clarification-Request.md)
draft presented for review
read, question, challenge
tell Baxter what to revise — loops back to draft
Iterate as many times as needed before approving
your name goes in the revision history
artefacts/ date-prefixed filename · correct subfolder
full audit trail · review like code
in your own repo — the harness ships with artefacts/ gitignored
The seven dimensions of the sanity check
Verification is not a spell-check on module names. Every artefact except an initial BRD is read back against the real codebase across seven dimensions, and the findings are reported after the artefact rather than buried inside it — so you can see what was checked, not just what was written.
Names
Module, field, and role names, and route paths, checked against coderepo/ and the two registries generated from it. A role additionally carries its code identifier so the claim can be checked at all; a module not yet in the registry is marked (new module) rather than assumed.
Technical feasibility
Can what is described actually be built on the current codebase, data model, and architecture — or does it quietly assume rework nobody has scoped?
Logic consistency
Do the requirements contradict each other, or contradict behaviour the product already has?
Data model
Are new fields, tables, or relationships consistent with the schema that exists? Missing migrations and conflicts are called out.
Roles and permissions
Are the role-based rules consistent with how access is actually enforced in the code — not with how someone assumes it works?
Gaps and edge cases
What is missing that would surface later as a defect or a blocked test — the scenario nobody wrote down.
UX challenges
What the front-end and design team will have to solve, raised while it is still cheap to change.
Findings are graded — verified, corrected, blocker, or recommendation. When a blocker appears, Baxter offers to turn it into a Client Clarification Request rather than guessing at the answer on your behalf.
The problem with SDLC tooling
Most teams spread a single requirement across five tools — the spec in Confluence, the ticket in Jira, the design in Figma, the test plan in a spreadsheet, the implementation notes in Slack. None of them talk to each other.
By the time a feature reaches QA, the original requirement has mutated across six conversations and two document versions, and nobody can prove what was agreed. AI cannot help either: when requirements live behind a proprietary login, an agent cannot read them, verify them, or build on them. The context is locked away.
Markdown in git is the answer
Markdown renders everywhere, diffs cleanly, and can be read and written by any AI agent without an API. It is the only format that is human-readable, machine-readable, and version-controllable at once.
When a BRD is a Markdown file in git, every change is a commit with an author, a timestamp, and a message, and pull request reviews become the formal approval record — an immutable audit trail for free. The same file your BA writes is the one your developer reads, your QA engineer links from a test case, and Baxter verifies against the codebase. One source of truth, no synchronisation problem.
Baxter drafts. Humans verify.
The harness rests on one principle: Baxter is fast at first drafts, humans are essential for catching subtle errors, and the two roles must not be confused. Baxter reads the raw request, selects the right template, checks the draft against the real codebase, and flags discrepancies — wrong module names, invented fields, routes that do not exist. Nothing is authoritative until a human reviews it and adds their name to the revision history.
The same split governs the registries the artefacts are checked against. What may enter them is decided by the code — Baxter can never invent a module or a role to fill a gap, and no BRD, spreadsheet, or plausible-sounding assumption may introduce one. What they finally say is decided by you: both files are yours to edit, and a correction is applied immediately and in full, because a reading of a codebase is fallible and the person who knows the product is the one who will spot what was missed. When you add something the code does not appear to contain, it is kept and marked as unlocated rather than argued with or quietly dropped — your judgement wins, and the provenance stays visible.
There is no server, no database, no proprietary format. CLAUDE.md exists only to route each request to the correct template and enforce that verification step — the eleven templates in templates/ (BR, CR, AI, BRD, PRD, PD, TIP, TC, DIA, ERD, CLQ) are the product, and the thirteen power skills live separately in .claude/commands/. Edit any of them; Baxter reads whatever is on disk.
It works backwards, too
Most requirements tooling assumes you start at the beginning. Real teams rarely do. Far more often the product already exists, shipped over several years, and the documentation that should describe it either never got written or stopped being true a long time ago.
Because the codebase is the source of truth Baxter already reads, it can run in the other direction. /generate-retrospective-brd takes a codebase folder and infers a client-facing BRD from it — the modules, the roles and personas, and each module's features at one line apiece. It is deliberately standalone: no PRD, no change requests, and no module registry have to exist first, so a repository path on its own is a complete input.
The same discipline applies in reverse as in forward. What the code evidences is stated plainly; what it cannot — the business case above all — is left as an explicit placeholder for the client to confirm, and the sanity check reports how much of the document is evidenced versus inferred before you put it in front of anyone. A retrospective BRD earns its authority the same way every other artefact does: a human reads it, corrects it, and signs it.
It also never pretends to be something it is not. The document declares itself retrospective in its title, its type line, its artefact ID, and its filename, and every module in it is marked Existing. A BRD written before the build and one reverse-engineered from shipped code are read very differently — so when both sit in the same folder, telling them apart cannot depend on remembering which was which.
The BA is no longer a translator — they are an orchestrator
The BA used to sit between business and engineering, translating one into the other — and the gap in that translation was where most projects failed. That model is over. Baxter makes it possible for non-technical team members to produce artefacts grounded in the codebase: verified against real module names, real fields, and real routes, not just documented in plain English.
You do not need to understand how the code works. You work with Baxter — who flags "the module 'OrderHistory' does not exist; did you mean 'Orders'?" before the artefact reaches a developer. You bring domain expertise, stakeholder context, and the final sign-off. Neither alone is sufficient.
The new standard for every non-technical team member:
- → Use Baxter to produce the first draft of every artefact, verified against the codebase before you read it
- → Review the output, apply your domain judgement, and approve it by adding your name to the revision history
- → Commit and raise a pull request — to the repository that holds the code, not a document system
You never structure the input. Paste the raw email, Slack thread, or voice note exactly as it arrived — Baxter classifies it, announces the template, and asks for a one-word confirmation before generating anything. The formality is in the output, not the input.
Ready to work with Baxter?
Open source and free. Drop the harness into any project, open it in Claude Code, Cursor, or GitHub Copilot, and paste your first raw request.