BTRS Documentation
24 specialist AI agents. 24 skills. Discipline enforced.
AI agent orchestration with discipline enforcement (TDD, verification, debugging), session continuity, and the Superpowers merge. /btrs picks up where you left off and enforces the Iron Laws on every task.
Get Started →One Command
Type /btrs and describe what you need. The router handles the rest.
24 Specialists
Architects, engineers, security, ops, and business agents — each with deep domain knowledge.
Convention-Aware
Auto-detects your project patterns. Agents follow YOUR style, not generic templates.
Self-Verifying
Every agent checks its own work with evidence before reporting done.
Obsidian Vault
All decisions and documentation auto-written to a linked knowledge base.
Any AI Tool
Designed for Claude Code. Agent definitions work with other AI tools (Cursor, Copilot, Windsurf) but the full workflow requires Claude Code.
Quick Start
Get BTRS running in under 60 seconds.
# Install BTRS git clone https://github.com/btrs-ai/btrs.git ~/.claude/btrs && ~/.claude/btrs/install.sh # Then in any project: /btrs build me a user dashboard
First time in a project? BTRS auto-scans your codebase. No setup needed.
Installation
BTRS supports all major AI development tools. Pick yours below.
Install via script:
git clone https://github.com/btrs-ai/btrs.git ~/.claude/btrs && ~/.claude/btrs/install.sh
Symlinks all skills and agents into ~/.claude/. Run install.sh again to update.
After install, /btrs is available globally in every project you open with Claude Code.
BTRS is designed for Claude Code. For Cursor, you can reference the agent definitions at agents/btrs-*/AGENT.md and the universal instructions in AGENTS.md. The full skill workflow (subagent dispatch, TDD enforcement, session continuity) requires Claude Code.
BTRS is designed for Claude Code. For GitHub Copilot, you can reference the agent definitions at agents/btrs-*/AGENT.md and the universal instructions in AGENTS.md. The full skill workflow (subagent dispatch, TDD enforcement, session continuity) requires Claude Code.
BTRS is designed for Claude Code. For Windsurf, you can reference the agent definitions at agents/btrs-*/AGENT.md and the universal instructions in AGENTS.md. The full skill workflow (subagent dispatch, TDD enforcement, session continuity) requires Claude Code.
BTRS is designed for Claude Code. For OpenAI Codex, you can reference the agent definitions at agents/btrs-*/AGENT.md and the universal instructions in AGENTS.md. The full skill workflow (subagent dispatch, TDD enforcement, session continuity) requires Claude Code.
Upload AGENTS.md as project context in Claude AI. Load individual agent files (agents/btrs-*/AGENT.md) as needed for specialized tasks.
The web interface does not support slash commands. Paste agent instructions directly into your conversation context.
First Run
When you use /btrs in a project for the first time, the system will:
Scan your project
BTRS reads your file structure, dependencies, and existing patterns to build a conventions profile.
Generate conventions
A btrs/conventions/ folder is created with your project's detected patterns — naming, structure, style, and anti-patterns.
Initialize the vault
The btrs/ Obsidian-compatible vault is set up for decision logs, ADRs, and documentation.
Ready to work
Every subsequent /btrs call in this project uses the conventions automatically. No repeated setup.
How It Works
You describe what you need
Type /btrs followed by a natural language request. No special syntax required.
BTRS classifies the request
The router analyzes your request to determine which domain(s) it belongs to — architecture, frontend, security, ops, etc.
Specialist agents are dispatched
The appropriate agents are loaded with your project's conventions injected as mandatory context. Complex tasks may involve multiple agents in sequence.
Agents verify their own work
Each agent runs a 5-point self-verification check before reporting completion. If anything fails, the agent self-corrects.
Documentation is auto-updated
Decisions, changes, and rationale are written to the btrs/ Obsidian vault automatically.
The /btrs Command
The /btrs command is the universal entry point. Here are examples of different request types:
# Building /btrs build a notification system with email and push # Fixing /btrs the login page crashes on mobile Safari # Planning /btrs plan the Q2 product roadmap # Security /btrs audit the API for vulnerabilities # DevOps /btrs set up CI/CD with GitHub Actions # Research /btrs compare Postgres vs CockroachDB for our use case # Documentation /btrs document the payments API with examples
You can be as specific or as vague as you want. BTRS will ask clarifying questions if needed.
Follow-Up Conversations
After your initial /btrs command, you do not need to prefix every message. Just keep talking naturally.
# Start with /btrs /btrs build a user settings page # Then just follow up normally Add a dark mode toggle to that page Actually, make it a dropdown with 3 options: light, dark, system Now add tests for the theme switching logic
The active agent retains context from the conversation. Use /btrs again when you want to switch to a completely different task.
Agents — Management
1 AgentBoss Agent
Central coordinator. Breaks down requests, dispatches agents, tracks progress.
/btrs build a full-stack app• /btrs plan the migration to microservicesAgents — Technical
4 AgentsArchitect
System design, architecture decisions, ADRs, technology selection.
/btrs design the auth system• /btrs propose a caching strategyQA & Test Engineering
Unit, integration, e2e, performance, and security testing.
/btrs write tests for the payment flow• /btrs set up e2e testing with PlaywrightDocumentation
Technical writing, API docs, guides, changelogs.
/btrs document the REST API• /btrs write the onboarding guideResearch
Technology evaluation, competitive analysis, innovation scouting.
/btrs compare React vs Vue for our needs• /btrs research real-time sync solutionsAgents — Engineering
6 AgentsAPI Engineer
Backend APIs, REST, GraphQL, microservices, server logic.
/btrs build a REST API for orders• /btrs add GraphQL subscriptionsWeb Engineer
React, Vue, frontend applications, SPAs, SSR.
/btrs build a dashboard with React• /btrs fix the responsive layoutMobile Engineer
React Native, Flutter, iOS, Android development.
/btrs build the onboarding screens• /btrs fix push notifications on iOSDesktop Engineer
Electron, Tauri, native desktop applications.
/btrs build a system tray app• /btrs add auto-update functionalityUI Engineer
Component libraries, design systems, Storybook, visual polish.
/btrs create a button component system• /btrs build the design tokensDatabase Engineer
Schema design, optimization, migrations, query tuning.
/btrs design the schema for multi-tenancy• /btrs optimize the slow queriesAgents — Security
2 AgentsCode Security
SAST/DAST, vulnerability scanning, secure coding practices, OWASP compliance.
/btrs audit the auth code for vulns• /btrs add input sanitizationSecurity Ops
Infrastructure security, compliance (GDPR, SOC2, HIPAA), access controls.
/btrs review our AWS IAM policies• /btrs prepare for SOC2 auditAgents — Operations
5 AgentsCloud Ops
AWS, Azure, GCP, infrastructure as code, networking.
/btrs set up the staging environment• /btrs migrate from Heroku to AWSCI/CD Ops
Deployment pipelines, GitHub Actions, automated releases.
/btrs set up CI/CD with GitHub Actions• /btrs add preview deploys for PRsContainer Ops
Docker, Kubernetes, orchestration, container security.
/btrs dockerize the application• /btrs set up Kubernetes manifestsMonitoring Ops
Prometheus, Grafana, alerting, observability, log aggregation.
/btrs set up monitoring and alerts• /btrs add distributed tracingDevOps
Combined DevOps workflows, deployment orchestration, platform engineering.
/btrs set up our DevOps workflow• /btrs orchestrate the deployment pipelineAgents — Business
6 AgentsProduct
Product strategy, roadmap, requirements, user stories.
/btrs write user stories for onboarding• /btrs plan the Q2 roadmapMarketing
Campaigns, growth strategies, SEO, content marketing.
/btrs write the launch email sequence• /btrs optimize our landing page SEOSales
Sales strategy, pipeline optimization, revenue analysis.
/btrs build the sales pitch deck outline• /btrs analyze the conversion funnelAccounting
Financial management, bookkeeping, revenue tracking.
/btrs set up the billing system logic• /btrs model the subscription pricing tiersCustomer Success
Retention strategies, support workflows, NPS tracking.
/btrs design the customer onboarding flow• /btrs build a churn prediction modelData Analyst
Business intelligence, analytics, dashboards, data modeling.
/btrs build a KPI dashboard• /btrs analyze user engagement metricsSkills — Core
3 Skills| Skill | Description | When to Use |
|---|---|---|
/btrs | Universal router. Classifies your request, resumes active work, and dispatches the right agent(s). | Starting any new task or resuming a session. This is your default entry point. |
/btrs-init | Initializes BTRS in the current project. Scans conventions, creates vault. | First time using BTRS in a project (auto-runs on first /btrs). |
/btrs-dispatch | Routes work to specialist agents with context injection and progress tracking. | Used internally by the pipeline. Power users can invoke directly. |
Skills — Planning
4 Skills| Skill | Description | When to Use |
|---|---|---|
/btrs-brainstorm | Explores intent, requirements, and design before implementation. Mandatory before any creative work. | Automatically invoked before building features. Also available directly. |
/btrs-plan | Creates a detailed implementation plan with task breakdown and agent assignments. | Before starting complex, multi-step work. |
/btrs-propose | Generates a proposal with multiple solution approaches (minimal, conventional, scalable). | When you need to evaluate options before committing to an approach. |
/btrs-spec | Writes a technical specification with requirements, constraints, and acceptance criteria. | Before building a new feature or system. |
Skills — Building
4 Skills| Skill | Description | When to Use |
|---|---|---|
/btrs-execute | Executes implementation plans task-by-task with TDD enforcement and review checkpoints. | When you have a plan and are ready to build. Replaces manual agent dispatching. |
/btrs-implement | Implements a plan or spec. Dispatches engineering agents with conventions enforced. | When you have a plan and are ready to build. |
/btrs-worktree | Creates isolated git worktrees for feature work. Keeps main branch clean. | Before starting any feature branch work. Auto-invoked by the pipeline. |
/btrs-deploy | Handles deployment configuration, CI/CD setup, and release management. | When code is ready to ship. |
Skills — Discipline
3 Skills| Skill | Description | When to Use |
|---|---|---|
/btrs-tdd | Test-driven development enforcement. Red → Green → Refactor cycle on every implementation. | Automatically invoked during execution. Can also be used standalone for any coding task. |
/btrs-debug | Systematic 4-phase debugging: observe, hypothesize, test, conclude. No guessing allowed. | Any bug, test failure, or unexpected behavior. |
/btrs-sanity-check | Runs all tests, linters, and checks. Produces evidence of pass/fail status. | After implementation, before finishing. Auto-invoked by the pipeline. |
Skills — Workflow
4 Skills| Skill | Description | When to Use |
|---|---|---|
/btrs-finish | Completes a development branch: merge, PR, or cleanup with structured options. | When implementation is done and all tests pass. |
/btrs-request-review | Requests code review before merging. Produces structured review request. | After completing a feature, before merge. |
/btrs-receive-review | Processes code review feedback with technical rigor. No blind agreement. | When receiving review comments. Verifies suggestions before implementing. |
/btrs-handoff | Creates a context handoff document for continuing work in a new session. | End of session. Passing work to another developer. |
Skills — Quality
4 Skills| Skill | Description | When to Use |
|---|---|---|
/btrs-review | Code review with convention compliance, best practices, and security checks. | Before merging code. After implementation. |
/btrs-audit | Deep security and compliance audit of code and infrastructure. | Before releases. Periodic security checks. |
/btrs-verify | Verifies convention compliance across the project. Catches drift. | Periodically, or after large changes. |
/btrs-health | Project health check — dependency freshness, tech debt, test coverage. | Regular maintenance. Sprint planning. |
Skills — Knowledge
4 Skills| Skill | Description | When to Use |
|---|---|---|
/btrs-research | Deep research on technologies, patterns, or business topics with citations. | Evaluating new tools. Making technology decisions. |
/btrs-analyze | Data analysis, metrics review, and insights generation. | Understanding user behavior. Measuring impact. |
/btrs-doc | Generates or updates documentation (API docs, guides, READMEs). | After building features. Onboarding new team members. |
/btrs-tech-debt | Tech debt lifecycle — scan, triage, fix, report. | Sprint planning. Reducing accumulated debt. Maintenance cycles. |
Workflow Pipeline
Every task in BTRS v2.0.0 follows a structured pipeline. No shortcuts, no skipped steps.
TDD per task
Classify
BTRS analyzes your request and determines the type: feature, bugfix, question, research, or multi-domain task.
Brainstorm
Explores your intent, requirements, and design constraints before touching any code. Uses /btrs-brainstorm.
Plan
Creates a detailed implementation plan with task breakdown, agent assignments, and acceptance criteria.
Worktree
Isolates work in a git worktree so your main branch stays clean. Uses /btrs-worktree.
Execute with TDD
Each task is implemented test-first: write failing test, write minimal code to pass, refactor. Uses /btrs-execute and /btrs-tdd.
Sanity-Check
Runs all tests, linters, and verification checks. Uses /btrs-sanity-check.
Finish
Merges work, cleans up worktree, updates documentation. Uses /btrs-finish.
For simple questions or quick lookups, BTRS skips the full pipeline and answers directly from conventions.
Discipline — The Three Iron Laws
BTRS v2.0.0 enforces three non-negotiable laws on every task. These cannot be skipped or overridden.
1. TDD or No Code
Every implementation starts with a failing test. No test, no code. Enforced by /btrs-tdd. Red → Green → Refactor on every task.
2. Evidence Before Assertions
Never claim "it works" without proof. Show test output, build logs, or command results. Verification is mandatory, not optional.
3. Systematic Debugging
No guessing. Bugs are debugged through a 4-phase process: observe, hypothesize, test, conclude. Uses /btrs-debug.
These laws are enforced automatically. Agents cannot skip TDD, cannot claim success without evidence, and cannot guess at bug fixes. This is what makes BTRS output reliable.
Session Continuity
Start a new session and /btrs picks up where you left off. No manual handoffs needed.
# New session — BTRS detects active work /btrs # Output: Active work detected in btrs/work/: Feature: user-notifications (3/5 tasks complete) Worktree: feature/user-notifications Next task: Build push notification service Resume? [Y/n]
BTRS tracks active work in the btrs/work/ directory. Plans, progress, and evidence are all persisted so sessions can resume seamlessly across conversations.
Convention System
Conventions are how BTRS prevents AI drift — the tendency for AI tools to generate code that ignores your project's existing patterns.
How Conventions Work
Auto-detected from your project
BTRS scans file structure, naming patterns, imports, component styles, and configuration to build a conventions profile specific to YOUR project.
Injected into agent context
Conventions are loaded as mandatory context for every agent dispatch. Agents cannot ignore them — they are part of the prompt.
Component registry prevents duplicates
A registry of existing components, utilities, and services means agents reuse what exists instead of recreating it.
Anti-pattern lists prevent mistakes
Known bad patterns from your codebase are explicitly flagged so agents avoid them.
/btrs-verify catches violations
Run /btrs-verify to scan the entire project for convention violations and get automated fix suggestions.
Conventions are project-specific. Each project gets its own conventions profile. Moving between projects automatically switches context.
Self-Verification
Every agent performs a 5-point verification check before reporting work as complete. This is not optional — it is built into every agent's instructions.
The 5-Point Check
- Convention compliance — Does the output follow all detected project conventions?
- Functional correctness — Does the code compile, run, and produce correct results?
- Integration safety — Does it break any existing functionality?
- Security baseline — Are there any obvious security issues (injection, exposure, etc.)?
- Evidence provided — Can the agent show proof of verification (test output, build success, etc.)?
If any check fails, the agent fixes the issue and re-verifies. You only see the final, verified result.
Multi-Solution Exploration
When you use /btrs-propose, the system generates three distinct approaches to solve your problem, ranked by complexity and scalability.
The 3-Approach Pattern
Approach A: Minimal
Fewest changes. Solves the immediate problem. Low risk, fast to ship. Best when time is critical.
Approach B: Conventional
Industry-standard solution. Balanced effort and quality. Good documentation and community support.
Approach C: Scalable
Future-proof architecture. Higher upfront cost but handles 10x growth. Best for core systems.
Each approach includes estimated effort, tradeoffs, and a recommendation. You pick the one that fits your situation.
Obsidian Vault
BTRS v2.0.0 uses a btrs/ directory (no dot prefix) with a three-tier structure: knowledge, work, and evidence. It is plain Markdown, compatible with Obsidian for visual graph exploration.
Three-Tier Directory Structure
config.json
knowledge/ # Persistent project knowledge
conventions/
decisions/
code-map/
tech-debt/
work/ # Active session state
specs/
plans/
todos/
changelog/
status.md
evidence/ # Verification proof
reviews/
verification/
debug/
sessions/
.obsidian/
You do not need Obsidian installed. The vault is plain Markdown files. Obsidian just gives you a nice visual graph view of how decisions and documentation are interconnected.
Cross-AI Compatibility
BTRS is designed for Claude Code. The agent definitions in agents/btrs-*/AGENT.md and the universal instructions in AGENTS.md can be referenced by other AI tools, but the full skill workflow requires Claude Code.
Universal Source
Each adapter file translates the universal agent instructions into the format expected by that platform. When you update AGENTS.md, the adapters stay in sync.
| Platform | Adapter File | Auto-loads? |
|---|---|---|
| Claude Code | CLAUDE.md + ~/.claude/ symlinks | Yes |
| Cursor | .cursorrules | Yes |
| GitHub Copilot | .github/copilot-instructions.md | Yes |
| Windsurf | .windsurfrules | Yes |
| OpenAI Codex | AGENTS.md (native) | Yes |
| Claude AI (Web) | Manual upload | No |
FAQ
/btrs again when you want to switch to a completely different task./btrs auto-scans your project on first use. No configuration file to write, no setup wizard. It detects your conventions from the codebase itself.AGENTS.md works with any AI tool. Cursor, Copilot, Windsurf, and Codex all have adapter files that auto-load. For tools without native support, upload the agent files as context manually.btrs/ vault is plain Markdown files that work with any text editor. Obsidian just provides a nice visual graph view and linked note browsing. It is entirely optional.AGENT.md file as context in your AI tool and interact with it directly. The /btrs router is a convenience layer, not a requirement.~/.claude/btrs/install.sh again — it pulls the latest and re-links everything.~/.claude/btrs/uninstall.sh. It removes all symlinks from ~/.claude/ cleanly. Your projects are not affected.