bpsai-pair 2.31.0

AI-augmented pair programming framework with 220+ CLI commands for planning, orchestration, Trello/GitHub integration, and autonomous workflows

bpsai-pair

AI-augmented pair programming framework with 220+ CLI commands

Overview

bpsai-pair (PairCoder) is a comprehensive AI pair programming framework that provides structured workflows, enforcement gates, and integrations to ensure AI agents follow proper development practices.

• Planning & Task Management — Sprint planning, task lifecycle, Trello sync, and budget tracking
• Skill-Based Workflows — 9 built-in skills for TDD, code review, releases, architecture, and more
• Integration Hub — Trello, GitHub, MCP servers, and Toggl time tracking
• Architecture Enforcement — File size limits, function boundaries, import caps, and auto-split suggestions
• Telemetry & Feedback — Session telemetry, self-calibrating estimation, anomaly detection
• Workspace Orchestration — Multi-project workspaces, cross-repo contract detection, impact analysis
• Intelligence Pipeline — Usage snapshots, value extraction scoring, tamper detection
• Interactive Setup Wizard — Web-based project configuration with AI-guided setup
• Licensing & Security — Tiered feature gating, secret scanning, containment mode
• Quality Control — Browser-based QC with spec format, execution runtime, and gate enforcement
• Containment Mode — Tiered file access control via PreToolUse hooks
• Autonomous Sprint Execution — bpsai-pair engage runs full sprints: branch, tasks, PR, review, observations
• Machine Interface — --json envelope on all commands for programmatic consumption
• Health Check — bpsai-pair doctor validates setup with 9 checks and auto-repair
• Slash Commands — /make-it-so (intent to PR), /draft-backlog (engage-compatible backlogs)

Installation

# Core installation
pip install bpsai-pair

# With integrations
pip install bpsai-pair[trello]      # Trello board sync
pip install bpsai-pair[github]      # GitHub PR management
pip install bpsai-pair[mcp]         # MCP server support
pip install bpsai-pair[all]         # All extras

Quick Start

# Initialize a new project
bpsai-pair init

# Or use the interactive wizard
bpsai-pair wizard

# Check project status
bpsai-pair status

# Create a sprint plan
bpsai-pair plan new my-feature --type feature

# Start a task (with Trello sync)
bpsai-pair ttask start TRELLO-123

# Run architecture checks
bpsai-pair arch check

# Pack context for AI assistants
bpsai-pair pack

Key Command Groups

Group	Commands	Description
plan	8	Sprint planning, task creation, Trello sync
task	12	Task lifecycle, status updates, archival
trello / ttask	27	Trello board management, card workflows
github	8	PR creation, merge, auto-archive
skill	8	Workflow skills, export to Cursor/Windsurf
license	10	License management, feature gating
telemetry	3	Session telemetry, privacy config, export
feedback	4	Calibration, accuracy, task-type estimates
workspace	5	Multi-project orchestration, impact analysis
arch	2	Architecture enforcement, split suggestions
budget	3	Token budget tracking, task cost estimates
security	4	Secret scanning, containment mode
qc	6	Quality check specs, execution, reporting
query	3	Cross-agent state and telemetry queries
engage	1	Autonomous sprint execution from backlog
fleet	1	Workspace version compliance checking
release	2	Pre-release validation, version file checking
containment	2	File access enforcement and status

License Tiers

Feature	Solo	Pro	Enterprise
Planning & tasks	Y	Y	Y
Skills & enforcement	Y	Y	Y
Setup wizard	Y	Y	Y
Telemetry & feedback	Y	Y	Y
Trello integration		Y	Y
GitHub integration		Y	Y
MCP servers		Y	Y
Token budget & cost tracking		Y	Y
Workspace orchestration		Y	Y
Remote access & SSO			Y

Check your license: bpsai-pair license status

What's New

Full release history and detailed notes: paircoder.ai.

v2.31.0 — Smarter routing, honest telemetry, benchmark-calibrated estimates

• Model routing can now explore. Opt-in routing.exploration.epsilon occasionally samples an equally-qualified model from the routing band so your calibration data learns which models actually perform best on your tasks — off by default, deterministic when off, and every assignment is logged for analysis.
• Telemetry tells the truth. Task records now capture whether acceptance criteria actually passed (ac_verified), real per-session token baselines, what changed (lines/files), and which model really ran — the data your calibration report learns from is now correctness-based, not survival-based.
• Benchmarks that know their place. benchmark matrix-run runs natively (faster, no co-install), prices local models at $0, validates provider keys up front, and its seeds act as decaying cold-start priors — real production data automatically outweighs synthetic seeds as it accumulates.
• Architecture checks, calibrated. Role-aware caps are now opt-in (architecture.role_defaults: true), count only code lines when configured, and grandfathered debt lives in reviewable baseline files instead of blocking unrelated work.
• First-run polish. New projects show a real date and their branch name from the first status, before the first commit.

v2.30.1 — Review noise fix (patch)

• The code-review wiring guard now honors the .wiring-baseline.json allowlist correctly — reviews flag only NEW unwired code instead of re-reporting pre-existing debt on every pull request.
• Internal reliability and test-stability fixes.

v2.30.0 — Sprints that finish what they start

• Sprints can no longer end silently incomplete. Every completed sprint ends with a PR (the run refuses to exit without one), merged branches are cleaned up automatically, and issues referenced by the work are closed with an evidence comment.

• bpsai-pair fleet audit --branches --issues — one command reports leftover branches and unclosed-but-fixed issues across every repo in your workspace.

• review sprint <id> audits multi-repo sprints as a whole — one review pass over every repo the sprint touched, catching integration issues per-repo reviews miss.

• Review findings become data you can analyze. Every review — including clean passes — records per-finding data (agent, file, line range, defect class) locally for your own quality analytics.

• Fixes. Engage PR creation no longer fails on very long descriptions; fable model alias recognized in model config.

• Cross-repo engage runs no longer false-fail a healthy task when a diff check errors, and a task's completion verdict and sibling-repo commit both land in the actual target repo instead of the run repo.

• engage --dry-run now shows each task's resolved target repo, and preflight warns (or, with --strict-targets, refuses) when a task's description implies a sibling-repo target that failed to resolve — catching the authoring mistake before dispatch.

v2.29.0 — Full model routing for the latest Claude models

• Route every task to the model built for it. Full model-routing support across the current Claude lineup (Fable 5, Sonnet 5, Opus, Haiku): /pc-plan and /draft-backlog assign a model: to every task, and one unified router applies the same explicit > calibration > complexity precedence everywhere a model decision is made — engage dispatch, advisory hooks, and --dry-run previews always agree.
• More output from every token. Plan-time routing keeps frontier models on the reasoning-heavy work and fast models on the high-volume driver work — increasing throughput while maximizing token efficiency across a whole fleet of agents.
• Routing that improves itself. Telemetry records routed_model, routing_tier, and session_role per task; bpsai-pair calibration report recomputes calibration and flags drift between what was routed and what actually ran — so routing gets sharper with every task you complete.
• Engage reliability. Completion no longer false-blocks on already-landed work; cross-repo runs push sibling-repo branches at kickoff and after every task gate for crash durability; pushes always target the intended branch.
• Code review reliability. review pr/review branch run their checks against an isolated copy of the reviewed code — no more false failures from a busy checkout.

v2.28.2 — Latest-model support + engage durability (patch)

• Claude Sonnet 5 and Fable 5 selectable in the wizard/config; current-gen context limits corrected to 1M for accurate budgets.
• Engage pushes its branch at kickoff and after every task — crash durability + mid-run visibility.
• Fixes: engage on Windows, support create/list scope, upgrade artifact hygiene, fail-closed review pr, engage auto-PR --head.

v2.28.0 — Cross-repo engage, provider-agnostic PM, plan-time arch headroom (minor)

• Cross-repo engage. A sprint can target sibling repos — engage commits, branches, opens PRs, and verifies in the right repo per task; backlogs declare a Target repo: (backlog-level or per-task), and QA/security/review fan out across every touched repo.
• Provider-agnostic project management. pm.provider defaults to none — tasks are local files completed with bpsai-pair task update <id> --status done; Trello is opt-in. New bpsai-pair pm command group; backlog cards with status rollup.
• bpsai-pair arch headroom — reports files approaching their architecture caps so you can plan an extraction before a change is forced to "trim to fit"; surfaced automatically when engage starts.
• Engage completion-gate unification (--engage-mode) plus a race-immune per-task start record, ending a class of flaky completion gates.

v2.27.1 — Patch

• Fixed a CLAUDE.md upgrade that could duplicate the Slash Commands / CLI Reference sections. Upgrade now keeps only your ## Project-Specific Notes section and refreshes the rest from the canonical template.

v2.27.0 — Multi-provider groundwork, engage hardening, new lints

A minor release: groundwork for alternate model backends, engage-lifecycle hardening, and two author-time architecture lints.

• engage lifecycle hardening. A gate error printed to stdout could be misread as a transient API failure and retried with the wrong cause; the retry now reads both output channels and fails fast with the real reason. The dirty-tree gate is churn-aware (no longer trips on engage's own bookkeeping), the planning artifact is reconciled to a single id, lifecycle hooks resolve regardless of PATH, and a fast task-cycle "PR storm" is fixed.
• bpsai-pair arch check-encoding — flags text-mode file I/O missing an explicit encoding= (the Windows cp1252 crash class) at authorship time.
• bpsai-pair arch check-wiring — advisory lint catching code that's written and unit-tested but never wired into the live flow.
• upgrade preserves your CLAUDE.md notes. Upgrade refreshes CLAUDE.md to the canonical template while keeping your ## Project-Specific Notes section.
• Harness-adapter groundwork. Experimental scaffolding (config provider presets for OpenRouter, Ollama, Azure, and more) toward alternate model backends; Claude Code remains the harness.

v2.26.1 — Cross-platform & telemetry robustness (patch)

• Fixed a Windows UnicodeEncodeError crash when engage diffs contained non-cp1252 characters (tempfiles now written as UTF-8).
• telemetry aggregate now reads the correct source instead of discarding records, and tolerates a missing telemetry file.

v2.26.0 — Engage Workspace Pre-flight + Liveness

• Cross-repo engage runs are gated by a pre-flight check: a covering .paircoder-workspace.yaml must list every target repo, or dispatch is refused with guidance.
• Long-running tasks emit a liveness heartbeat and honor a configurable per-task timeout. Adds bpsai-pair workspace validate.
• Review agents get an explicit turn budget (fixes empty/partial reviews) and large PR diffs are no longer truncated. Tasks can declare structured metadata (target_repo, depends_on) in a YAML block.

v2.25.7 — Bootstrap correctness + auto-upgrade discipline

• The remote-session bootstrap now fires only in Claude Code cloud sessions (CLAUDE_CODE_REMOTE=true); local and headless sessions are untouched (force with PAIRCODER_BOOTSTRAP_FORCE=1).
• Auto-upgrade no longer silently commits — it stages the re-templated .paircoder/ files for review and notifies on stderr (restore the old behavior with BPSAI_UPGRADE_COMMIT=1).

v2.25.6 — Hotfix: remote-session bootstrap tracks the release

• The remote-session bootstrap pin and its dependency set are corrected so fresh remote/CI/engage sessions install the current CLI.

v2.25.5 — Engage hardening (round 2) + spend visibility

• Stricter backlog dependency parsing, transient-failure retries on lifecycle/planning dispatch, cross-repo dispatch via a **Target repo:** declaration, a --preserve-failed-branch recovery flag, and transactional backlog materialization.
• New bpsai-pair budget programmatic reports month-to-date API spend against your configured tier cap, with an optional monthly cap that can gate dispatch.

v2.25.4 — Engage reliability + provider env-var presets

• Documentation/content tasks are recognized as completed work; running engage against a plan file points you to /draft-backlog; **Acceptance criteria:** is accepted as a synonym for **AC:**.
• New bpsai-pair config provider <name> prints environment-variable presets for the major Anthropic-API-compatible providers (Anthropic, OpenRouter, Ollama, LM Studio, Azure), plus a providers guide.

v2.25.3 — CLI hardening + test parallelization

• Test suite parallelized for a ~10× speedup; license machine-binding enforced; a UTF-8-safe subprocess wrapper closes the Windows cp1252 crash class; new bpsai-pair arch check-subprocess lint.

v2.25.2 — Engage stability + Windows UTF-8 fix

• Windows engage made usable (UTF-8 sweep); quieter hook chain; workspace scope-leak fix; more precise task-file matching.

v2.25.1 — Engage hook-failure hotfix

• Hook failures propagate correctly instead of being swallowed; security findings are visible when engage blocks a PR.

v2.25.0 — Engage driver intelligence + pipeline reliability

• Skip already-completed tasks on retry; recognize driver self-commits; bpsai-pair preflight runs CI-matching tests before pushing.

v2.24.0 — Sweep: diff-aware dead-code cleanup

• bpsai-pair sweep finds dead imports, orphaned tests, and stale helpers after changes, with --fix for high-confidence removals.

v2.23.x — Engage reliability, resume, and lifecycle hardening

• engage --resume skips completed tasks on retry; human-gated tasks via requires: human in backlog frontmatter; branch lifecycle flags; more reliable automated task completion.

v2.22.0 — Agent identity + Vaivora review agent

• Named review agents (Nayru, Laverna, Bellona, Vaivora, Divona); a third review agent engages automatically for large diffs.

v2.21.x — Review command, enforcement, and observability

• bpsai-pair review pr/branch/task; targeted per-task tests; intent recognition and an approval gate for autonomous dispatch; protected-branch guard.

v2.20.0 — Engage pipeline

• bpsai-pair engage runs full sprints autonomously (branch, tasks, PR, review); /make-it-so (intent to shipped PR); bpsai-pair doctor health checks with --fix.

Documentation

• Website & Docs
• Quick Start Guide

Requirements

• Python 3.10 or higher
• Git (for project management features)

Support

• Email: [e-mail]