Get started with Baxter

Baxter is a plain-text harness — a folder you drop into any project. No accounts, no subscriptions, no special tooling. You need git, an AI coding tool (Claude Code, Cursor, or similar), and your project's source code.

What you'll have at the end of this guide

✓Baxter installed and reading your codebase
✓Your first artefact generated and saved to git
✓A clear understanding of how to invoke each artefact type

Most important step — where does my code go?

→ coderepo/

Copy or symlink your project's source code into the coderepo/ folder. Baxter reads it to run multi-dimensional sanity checking on every artefact — feasibility, logic, data model, roles, naming, edge cases, and UX challenges. Without this, artefact verification cannot run.

agentic-ba/
├── coderepo/        ← YOUR PROJECT SOURCE CODE HERE
│   └── (your app, API, schema, migrations…)
├── artefacts/
│   ├── issues/      ← bugs, changes, AI features
│   └── other/       ← requirements, product-docs, implementation, test-suites, diagrams
├── templates/
│   ├── issues/      ← BR, CR, AI
│   └── other/       ← BRD, PD, TIP, TC, DIA, ERD, MR
├── preferences.json ← optional configuration
└── CLAUDE.md

three ways to add your code

# Copy your project in
cp -r /path/to/your/project coderepo/

# Or symlink it (keeps one copy on disk)
ln -s /path/to/your/project coderepo/src

# Or clone a sub-repo into it
git clone https://github.com/your-org/your-project coderepo/

coderepo/todo-react/ is already in the repo — a real React codebase bundled for practice. Your own codebase is gitignored and never committed.

Clone or copy the harness

git clone https://github.com/glovarix/agentic-ba.git
cd agentic-ba

Or copy the folder into an existing project repo. The harness is self-contained — it does not affect your project's code or CI.

Add your codebase — or use the bundled one

Already done — coderepo/todo-react/ is bundled

A real React Todo app is committed to coderepo/todo-react/. You can run every artefact type — including the full sanity check against real code — without adding anything. Skip to Step 3.

When you add your own project, Baxter switches automatically

Drop any directory into coderepo/ and Baxter will use that exclusively — ignoring todo-react/ entirely. No configuration needed. todo-react/ is only active when no other codebase is present.

cp -r /path/to/your/project coderepo/

Baxter reads coderepo/ to verify every artefact against your real codebase — checking technical feasibility, logic consistency, data model implications, role and permission logic, and flagging missing edge cases. If your codebase is large, a symlink works just as well.

Open in your AI agent

Open the folder in Claude Code, Cursor, or VS Code with GitHub Copilot. Baxter's instructions are already in the right file for each tool — the agent loads them automatically with no setup.

Tool	Instruction file loaded automatically
Claude Code	CLAUDE.md
Cursor	.cursor/rules/baxter.mdc
GitHub Copilot	.github/copilot-instructions.md

All three files are identical. A pre-commit hook keeps them in sync — edit CLAUDE.md and the others update automatically on your next commit. Run this once after cloning to activate it:

git config core.hooksPath .githooks

Paste a request — any raw text

example requests — paste exactly as received

"The login page returns a 500 error when the user submits without a password"

"Write up the BRD for care plan cloning"

"I need test cases for the vitals module — mandatory fields and role access"

"Add a print to PDF button to the patient profile page"

Baxter classifies the request, tells you which template it will use, and asks for a one-word confirmation before generating anything. You can reply with the artefact code (e.g. BR), a number, or just proceed.

Already in the repo — ready to explore

Sample artefacts — generated from the bundled todo-react codebase

The repo includes a set of sample artefacts generated from coderepo/todo-react/ — a real React app. You can see exactly what Baxter produces, and every sanity check in these artefacts was run against real code.

📖 Product Documentation

artefacts/other/product-docs/

Full PD for the imaginary Todo App — modules, roles, API routes, data model, known limitations

🧪 Test Cases (13 total)

artefacts/other/test-suites/

Authentication, Todos, and Tags — happy path, negative, role-based, and edge cases

📋 BRD + TIP

artefacts/other/requirements/ & implementation/

Due Date Reminders — requirements document and matching implementation plan

🐛 BR · 🔄 CR · 🤖 AI · 📐 DIA · 🗂️ ERD

artefacts/issues/ & other/

One sample of each remaining artefact type — all for the same fictional app

Try every artefact right now — real sanity checks included

todo-react is your sandbox — a real codebase, committed and ready

Open the repo in Claude Code, Cursor, or GitHub Copilot and paste any of the prompts below. Baxter reads coderepo/todo-react/ — a real React app — and runs the full multi-dimensional sanity check against actual source files. This is not a simulation. When you are ready, swap in your own project.

📋 BRD

"Write up the requirements for adding a due date field to todos"

📖 PD

"Document the authentication module"

🏗️ TIP

"Write an implementation plan for adding tag colours to the todo list view"

🧪 TC

"Generate test cases for the Tags module"

🐛 BR

"The Tags endpoint returns 500 when a duplicate name is submitted"

🔄 CR

"Add a bulk delete option to the todos list"

🤖 AI

"We need an AI feature to auto-suggest tags based on the todo title"

📐 DIA

"Diagram the todo creation flow from API request to database"

🗂️ ERD

"Draw an ERD for the todos and tags tables"

🗃️ MR

"/generate-modules — scan the codebase and build the module registry"

Baxter will classify each request, confirm the template, generate the artefact with a full sanity check, and ask before saving — exactly as it would on your real project.

What to say for each artefact

Baxter uses signal words to classify your request. You never need to name the template — just describe what you need. The table below shows the words Baxter listens for.

Artefact	Signal words Baxter listens for	Template used
🐛 Bug Report (BR)	"not working", "broken", "error", "404", "500", "crash", "fails"	issues/BR.md
🔄 Change Request (CR)	"add", "new", "improve", "enhance", "change", "feature request"	issues/CR.md
🤖 AI Feature (AI)	"AI feature", "auto-fill", "auto-generate", "suggest", "LLM"	issues/AI.md
📋 Business Requirements (BRD) — pre-dev	"BRD", "business requirements", "spec for", "write up the requirements"	other/BRD.md
📖 Product Documentation (PD) — post-dev	"PD", "document the module", "how it works", "what was built"	other/PD.md
🏗️ Implementation Plan (TIP)	"TIP", "implementation plan", "how to build", "dev plan"	other/TIP.md
🧪 Test Cases (TC)	"test cases", "test suite", "QA cases", "test steps"	other/TC.md
🗂️ Entity Relationship Diagram (ERD)	"ERD", "entity relationship", "data model diagram", "draw the schema", "show the tables"	other/ERD.md
📐 Diagram (DIA)	"diagram", "flowchart", "mermaid", "draw", "visualise", "sequence diagram", "state diagram"	other/DIA.md
🗃️ Module Registry (MR)	Run /generate-modules — Baxter scans the codebase and drafts the list for your review	other/MR.md

Baxter applies the first match in priority order. If nothing matches, Baxter asks you one clarifying question.

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.

preferences.json — all defaults shown

{
  "commitArtefacts":       false,
  "pushAfterCommit":       false,
  "confirmBeforeSave":     true,
  "confirmBeforeCommit":   true,
  "confirmBeforeGenerate": true,
  "runSanityCheck":        true,
  "includeTechnicalNotes": true,
  "language":              "en-GB"
}

Setting	Default	What it controls
commitArtefacts	false	Commit all artefacts to git. When false, only filenames starting with sample- are committed.
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.
language	"en-GB"	Writing language. Use "en-GB" for UK English or "en-US" for US English.

Comparing branches with `/compare`

Baxter includes a built-in slash command for comparing two branch snapshots side by side. It produces Markdown files and converts them to PDFs — no HTML files left behind.

Where do branch snapshots go?

→ coderepo/branches/

Each branch is a plain folder containing a copy of that branch's source code. The folder name becomes the branch label in the output.

coderepo/
├── branches/
│   ├── my-app-production/   ← production snapshot
│   └── my-app-staging/      ← staging snapshot
└── (your main codebase here, if any)

Output	Audience	Contents
Technical	Developers / tech leads	New files, removed files, and a breakdown of every changed file grouped by functional area — with exact before/after behaviour per item.
Non-technical	Product / QA / clinical leads	Plain-English features and use cases: what users can do in each branch, colour-coded status badges, and a known-issues section.

in Claude Code

/compare
# Baxter asks: 1 Technical | 2 Non-technical | 3 Both
# Saves {branch-a}-vs-{branch-b}-diff.md + .pdf
# and/or {branch-a}-vs-{branch-b}-usecases.md + .pdf

PDF generation uses pandoc if installed, or Chrome headless as a fallback. If there are more than two branch folders, Baxter lists them and asks which two to compare.

Building a module registry with `/generate-modules`

Baxter uses artefacts/other/modules.md to verify module names in every artefact. Run /generate-modules to generate it automatically from your codebase — no manual editing required.

Step	What happens
1. Scan	Baxter reads your codebase — routes, pages, navigation — and any existing artefacts.
2. Draft	A module table is presented for your review. Edit any rows, add or remove modules.
3. Save	Say "save" and Baxter writes artefacts/other/modules.md. From that point, every artefact is verified against it.

in Claude Code

/generate-modules
# Baxter scans coderepo/ and drafts the module table
# Review, edit, then say "save"
# Writes → artefacts/other/modules.md

The context/ folder is free-form — drop in any project-specific reference files you need. Nothing in it is committed to git by default.

Tips for getting the best results

You never need to structure your input

Paste raw emails, Slack messages, voice transcripts, or Google Doc excerpts exactly as they are. Baxter extracts what it needs. The messier the input, the more value Baxter adds.

Coderepo is the key to verification

Baxter automatically reads coderepo/ before writing every non-BRD artefact — without being asked, every time. Without it, artefact verification cannot run and Baxter will explicitly flag every field, module, and route it could not confirm. For production teams, always add your codebase.

You review. You approve. You commit.

Baxter always asks for confirmation before generating, and always presents the artefact for review before saving. Nothing is written without your sign-off. Your name goes in the revision history.

Templates are yours to change

Open any file in templates/issues/ or templates/other/ and edit the sections to match your team's standards. Baxter reads whatever is on disk — no config required.

One request at a time

If a client request contains multiple needs (e.g. a bug and a feature), handle them separately. Paste the bug first, then the feature request. Baxter handles one artefact per conversation.

Baxter The Agentic BA

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.

Get Started Star on GitHub