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 the core skills (templated artefacts) and the power tools (slash commands)
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/
│ ├── bug-reports/ ← bug reports
│ ├── change-requests/ ← change requests
│ ├── ai-features/ ← AI feature specs
│ ├── requirements/ ← business requirements documents
│ ├── product-docs/ ← product documentation
│ ├── implementation-plans/ ← technical implementation plans
│ ├── test-suites/ ← test cases
│ ├── diagrams/ ← diagrams and ERDs
│ └── client-clarifications/ ← client clarification requests
├── templates/ ← core skills: BR, CR, AI, BRD, PD, TIP, TC, DIA, ERD, CLQ
├── .claude/commands/ ← power tools: six slash-command workflows
├── preferences.json ← optional configuration
└── CLAUDE.md # 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/
Anything you drop into coderepo/ is gitignored and never committed — your code stays private to your machine.
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
Copy or symlink your project's source code into coderepo/. This is what Baxter reads to verify every artefact — required for everything except an initial BRD.
cp -r /path/to/your/project coderepo/
Your code never leaves your machine
Everything inside coderepo/ is gitignored — it is never committed or pushed. If your codebase is large, a symlink works just as well as a copy.
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.
Open in your AI agent
Open the folder in your AI agent. Baxter's instructions are already in the right file for each tool — the agent loads them automatically with no setup.
Recommended for beginners
VS Code + the Claude Code extension
If you are new to this, install VS Code and add the Claude Code extension from the marketplace. You get a familiar editor with Baxter running in a side panel — no terminal required. Open the agentic-ba folder, open the Claude Code panel, and start pasting requests.
It works just as well in the Claude Code CLI, Cursor, or VS Code with GitHub Copilot — each picks up its own instruction file:
| Tool | Instruction file loaded automatically |
|---|---|
| VS Code + Claude Code extension (recommended) | CLAUDE.md |
| Claude Code (CLI) | CLAUDE.md |
| Cursor | .cursor/rules/baxter.mdc |
| GitHub Copilot | .github/copilot-instructions.md |
The instruction files are identical (both Claude Code editions read CLAUDE.md). 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
"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.
Try every artefact — example prompts
Example prompts to get you started
Add your codebase to coderepo/, then paste any of the prompts below into Claude Code, Cursor, or GitHub Copilot. Baxter classifies the request, runs the full multi-dimensional sanity check against your source files, and asks before saving. These are illustrative — phrase yours however you like.
📋 BRD
"Write up the requirements for recurring invoices"
📖 PD
"Document the authentication module"
🏗️ TIP
"Write an implementation plan for the bulk import feature"
🧪 TC
"Generate test cases for the billing module"
🐛 BR
"The reports endpoint returns 500 when a duplicate name is submitted"
🔄 CR
"Add a bulk export option to the orders list"
🤖 AI
"We need an AI feature to auto-suggest categories from the item description"
📐 DIA
"Diagram the checkout flow from API request to database"
🗂️ ERD
"Draw an ERD for the orders and customers tables"
Baxter will classify each request, confirm the template, generate the artefact with a full sanity check, and ask before saving.
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. Power tools are not listed here — they are slash-command workflows, covered in the power tools section below.
| Artefact | Signal words Baxter listens for | Template used |
|---|---|---|
| 🐛 Bug Report (BR) | "not working", "broken", "error", "404", "500", "crash", "fails" | BR.md |
| 🔄 Change Request (CR) | "add", "new", "improve", "enhance", "change", "feature request" | CR.md |
| 🤖 AI Feature (AI) | "AI feature", "auto-fill", "auto-generate", "suggest", "LLM" | AI.md |
| 📋 Business Requirements (BRD) — pre-dev | "BRD", "business requirements", "spec for", "write up the requirements" | BRD.md |
| 📖 Product Documentation (PD) — post-dev | "PD", "document the module", "how it works", "what was built" | PD.md |
| 🏗️ Implementation Plan (TIP) | "TIP", "implementation plan", "how to build", "dev plan" | TIP.md |
| 🧪 Test Cases (TC) | "test cases", "test suite", "QA cases", "test steps" | TC.md |
| 🗂️ Entity Relationship Diagram (ERD) | "ERD", "entity relationship", "data model diagram", "draw the schema", "show the tables" | ERD.md |
| 📐 Diagram (DIA) | "diagram", "flowchart", "mermaid", "draw", "visualise", "sequence diagram", "state diagram" | DIA.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.
{
"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. |
Power tools — slash commands
Everything above this point is a core skill — a templated artefact you invoke by pasting raw text, produced from a template in templates/. Power tools are different: six automation workflows you run explicitly as slash commands — /validate-release, /generate-module-registry, /generate-samples, /generate-test-plan, /generate-release-notes, and /compare-branches. Their outputs may have a defined structure, but that structure lives in each command file in .claude/commands/ — never in templates/. Three of them are covered in detail below.
Comparing branches with /compare-branches
A power tool 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. |
/compare-branches # 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-module-registry
Baxter uses artefacts/modules/modules.md to verify module names in every artefact. Run /generate-module-registry 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/modules/modules.md. From that point, every artefact is verified against it. |
/generate-module-registry # Baxter scans coderepo/ and drafts the module table # Review, edit, then say "save" # Writes → artefacts/modules/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.
Generating a test plan with /generate-test-plan
Once you have a test suite folder full of *_TC*.md files, run /generate-test-plan to synthesise a complete, structured test plan — no manual drafting required. Baxter reads every test case, derives all sections from the actual content, and exports the result as both Markdown and PDF in a single step.
| Step | What happens |
|---|---|
| 1. Discover | Baxter reads every *_TC*.md file in the target folder, extracting ID, title, priority, type, source reference, and a precondition summary from each. |
| 2. Synthesise | Test areas are inferred from the TC sequence. Type counts, role requirements, data dependencies, ordering risks, and entry/exit criteria are all derived — nothing is invented. |
| 3. Save | Baxter writes [MODULE]_TEST_PLAN.md alongside the test cases. If a plan already exists, it offers to increment the version instead of overwriting. |
| 4. Export PDF | Immediately runs npx md-to-pdf on the saved file. The PDF is generated in the same folder — no separate step, no HTML files left behind. |
| Section | What it contains |
|---|---|
| Document Information | Version, date, status, prepared by, reviewed by |
| Introduction | Feature description and purpose of the plan, inferred from TC preconditions and area names |
| Test Objectives | One bullet per area stating what is being verified |
| Scope | In-scope checklist (one item per area) and explicit out-of-scope exclusions |
| Test Approach | Happy Path / Negative / Role-Based / Edge Case breakdown with counts and any ordering dependencies |
| Test Environments | Environment table and data prerequisites checklist derived from TC preconditions |
| User Roles Under Test | Roles, internal names, and areas covered — derived from TC preconditions |
| Area Coverage | Area name, TC range, count, and High priority TC IDs |
| TC Summary Table | All test cases: ID, title, area, type, priority — in one place |
| Entry / Exit Criteria | Concrete checklists — what must be true before testing starts and before sign-off |
| Dependencies and Risks | Risk table: data setup complexity, role-switching, ordering constraints, boundary data |
| Execution Schedule | Phased table with placeholder dates and owners for QA lead to complete |
| Defect Management | Required fields for every defect: TC ID, steps, expected/actual result, environment, severity P1–P4 |
| Revision History | Version 1.0 with today's date — incremented automatically on subsequent runs |
/generate-test-plan artefacts/test-suites/SERVICES # Baxter reads all SERVICES_TC*.md files # Synthesises 15-section test plan, confirms filename # Writes → SERVICES_TEST_PLAN.md # Exports → SERVICES_TEST_PLAN.pdf (via npx md-to-pdf)
Omit the folder path and Baxter lists the available test suites under artefacts/test-suites/ for you to pick from.
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/ 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.
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.