bpsai-pair 2.26.0

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

bpsai-pair

AI-augmented pair programming framework with 218+ 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

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, or dispatch is refused with workspace guidance); long-running tasks emit a liveness heartbeat and honor a configurable per-task timeout. Adds a workspace validate subcommand and a daemon-optional membership primitive. Review agents get an explicit --max-turns budget (fixes empty/partial reviews) and large PR diffs are no longer silently truncated to metadata. Default models moved to the current generation (claude-opus-4-8).

• Per-task target_repo + YAML frontmatter on task bodies. Tasks can declare metadata in a structured YAML block (target_repo, depends_on, external_tools, requires) alongside the existing prose form. Typos like target-repo: now log a WARN with the suggested correction instead of silently vanishing.

• Pause/resume reconciliation. RunState now persists per-task baseline SHAs and per-task target repos. On resume the persisted state wins for already-dispatched tasks, and a new pass reconciles run-state against the task .md frontmatter -- persisted SHA wins on mismatch and the frontmatter is re-written so the verifier diffs against the correct baseline.

• Telemetry. Two new signals: task_verification_decision (every verifier outcome, with the SHAs compared and the file classification) and task_verification_legacy_path_taken (deprecation timer on the inference walk-back path).

• Git hardening. Pre-task SHAs are hex-shape validated before reaching git diff, the invocation carries --end-of-options, and _git_safe_env() now disables /etc/gitconfig + ~/.gitconfig via GIT_CONFIG_NOSYSTEM=1 / GIT_CONFIG_GLOBAL=/dev/null in addition to stripping inherited GIT_* vars. The persisted target_repo paths on resume go through the same workspace-boundary check as the backlog-resolution path so a tampered run-state JSON can't escape to /etc.

• Backlog validator reverted to typo-only behavior (the strict-whitelist gate from earlier in the cycle broke real backlogs using legitimate prose like **File:** and **Ship gate:**). The YAML-frontmatter path is the supported way to get strict, schema-validated task metadata.

• Engage + output verifier modularized. Pause/resume extracted to its own module; output verifier split into focused leaf modules (git-arg hardening, telemetry helpers, parser helpers). 15 new tests pin the new contracts.

v2.25.7 -- Bootstrap correctness + auto-upgrade discipline

Two operator-experience improvements from the follow-on review of v2.25.6:

• Bootstrap now only fires in Claude Code cloud sessions. The remote-session bootstrap (introduced for cloud / Ultra Plan handoffs) now gates on CLAUDE_CODE_REMOTE=true (Claude Code's documented cloud-session env var). Local interactive sessions and headless claude -p background-agent dispatches no longer trigger the bootstrap, so local development venvs stay untouched. Operators who need to force the bootstrap in a TTY context can export PAIRCODER_BOOTSTRAP_FORCE=1.

• Auto-upgrade no longer silently commits. When the CLI detects a version change at startup, it now stages the re-templated .paircoder/ files (visible in git status for operator review) and prints a notification on stderr, instead of producing a hidden chore: upgrade bpsai-pair to vX.Y.Z commit that operators sometimes merged by accident. To restore the old auto-commit behavior, export BPSAI_UPGRADE_COMMIT=1. Explicit operator-initiated paths (bpsai-pair upgrade --commit, bpsai-pair fleet check --upgrade --commit) are unchanged.

Bootstrap failure on stderr is now a multi-line banner pointing at the audit log (.paircoder/telemetry/bootstrap_audit.jsonl) instead of a single-line WARNING. Also healed: the root .paircoder/capabilities.yaml skill manifest, which was missing three skills (auditing-sibling-projects, planning-with-pm, running-qc) that the cookiecutter template ships. New consistency invariants prevent the manifest/directory pair from drifting in future releases.

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

The remote-session bootstrap script was pinned to a stale version since v2.21.1 and was missing two startup dependencies (pydantic, httpx). Fresh remote, CI, and Engage sessions without a prior PairCoder install were getting an old CLI. The pin now tracks the current release, the dependency set has been verified against every hook, and an invariant test prevents the pin from going stale in future releases. Local installs with a prior bpsai-pair on PATH were not affected.

v2.25.5 -- Engage hardening (round 2) + Phase 1 Anthropic API mitigation

Engage hardening (the second wave; closes the bugs operators surfaced running multi-sprint engage flows since v2.25.4):

• Backlog parser strictly validates **Depends on:** values: only None, N/A, empty, or a comma-separated list of bare task IDs. Lines like Depends on: KE4.6, KE4.8. (trailing period) or none (refactor only) no longer silently corrupt the dependency graph -- the parser logs a clear WARNING naming the rejected items.
• Engage retries transient subprocess failures (Anthropic API 5xx mid-call, network blips) on the post-task lifecycle hook and the Navigator /pc-plan dispatch -- up to 3 attempts with 1.0s / 2.0s backoff. No more dropping tasks into hook_failed because the API hiccupped.
• New **Target repo:** line in backlog markdown declares cross-repo dispatch: engage runs from one repo (the orchestrator) and dispatches tasks that land commits in a sibling repo. The "no meaningful output" detector now reads git diff in the declared target instead of the orchestrator cwd, closing the false-failure that hit cross-repo sprints.
• New --preserve-failed-branch flag (or engage.preserve_failed_branch: true in config) keeps the engage branch for recovery on failure instead of force-deleting. Successful sprints clean up regardless. Driver work is safe.
• Engage's "already satisfied -- skipping" pre-dispatch check now requires git evidence that the file claim has been modified since the task was registered. Stub files (NotImplementedError) that pre-existed the task no longer cause engage to skip the work.
• Backlog materialization is transactional: task files write to a staging dir first, then atomic-move into place. A crash mid-write leaves staging intact for inspection but the canonical tasks dir contains no partial state. The next engage run warns about leftover staging and clears it cleanly.
• Engage's complete_task_lifecycle now passes --auto-check by default so AC-checkbox bookkeeping in the planning artifact no longer trips the strict-AC gate and tanks the circuit breaker. Engage's own gates (arch check, contract break, pytest) still enforce correctness.
• New hooks.lifecycle_overrides.task_update_done_args config lets operators extend or replace the default args for the post-task hook -- useful for projects with custom enforcement workflows.
• New docs/engage-monitor-format.md documents the stdout line shapes engage emits, with a reference grep filter for live-monitoring tools. docs/engage.md adds a "Before You Dispatch" section recommending --dry-run as standard practice.

Phase 1 of the Anthropic API change mitigation (visibility + enforcement layers; ahead of the 2026-06-15 billing cutover):

• New bpsai-pair budget programmatic command reports month-to-date programmatic API spend from the local burn log, with comparison against your configured tier cap. Aggregate by surface | model | repo | day via --by; color-coded thresholds at 80% / 90% / 100%; CI-friendly exit codes (0 below 80%, 1 in band, 2 over cap); --json envelope output.
• Monthly programmatic-credit cap enforcement is now wired into check_token_budget. Configure programmatic_credit.monthly_cap_usd and programmatic_credit.tier_label in .paircoder/config.yaml; engage and direct CLI calls emit threshold signals at 50% / 80% / 100%, and at 100% the gate blocks new dispatch unless --budget-override is passed (audited to bypass_log.jsonl).
• Telemetry now records a dispatch_surface field distinguishing programmatic (subscription-billed via Claude Code today, programmatic-credit-billed after the cutover) from interactive dispatch. Same isatty check the budget gate uses. Optional field; pre-2.25.5 records remain queryable.
• A new by_surface query splits historical telemetry without requiring backfill.

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

• Tasks that produce documentation, generated text, or other content files are correctly recognized as completed work.
• Running bpsai-pair engage against a plan file (rather than a backlog) exits immediately with a clear pointer to /draft-backlog.
• **Acceptance criteria:** is accepted as a synonym for **AC:** so plans handed off from other tools parse cleanly.
• New bpsai-pair config provider <name> prints eval-safe environment-variable exports for the major Anthropic-API-compatible providers (Anthropic, OpenRouter, Ollama, LM Studio, Azure via proxy) plus a new docs/providers.md.
• New /prime-learn command for in-session knowledge capture with --yes / --reject flags for non-interactive use.
• Upgrade warnings stay quiet in non-interactive environments.
• The deprecated --hooks-advisory flag has been removed.
• Backlog files over 5 MB are rejected with a clear message.

v2.25.3 -- CLI Hardening + Test Parallelization

• Test suite 22+ min → 1:50 with pytest-xdist parallelization (10× speedup, ~13,700 tests)
• License machine binding actually enforced: copying license.json to a second machine is now rejected (3-day grace period for legitimate first-install activation)
• Pre-dispatch AC check tightened: tasks with no implementation no longer falsely "satisfy" the heuristic via stray symbol matches
• New sysproc.run() UTF-8-safe subprocess wrapper closes the Windows cp1252 crash class permanently
• New bpsai-pair arch check-subprocess lint rule (report-only by default)
• Lifecycle hooks (Stop/SubagentStop) wrapped to degrade gracefully when commands aren't yet installed
• platform-check workflow no longer requires A2A secrets — sources project context from local state.md
• 28 task-level cleanups closing #126, #157, #178 (phase 1), #195, #196, #197, #213

v2.25.2 -- Engage Stability Patches + Windows UTF-8 Fix

• Windows engage now usable: UTF-8 encoding sweep on engage subprocess (security agent dispatch + PR creation paths)
• Engage hook chain no longer noisy: orchestrate evaluate --quiet flag now exists, ending No such option errors on every TaskCompleted/TeammateIdle
• Self-PR --request-changes review-post no longer silently swallowed (falls back to --comment for solo developers)
• Workspace scope leak fixed: bpsai-pair plan new from a non-workspace project no longer pushes bogus task files to unrelated sibling repos
• Greedy task-file glob fixed: searching T1 no longer matches T18.1.task.md
• Nayru/Vaivora model config aligned across config.yaml and agent frontmatter (regen path also fixed)
• sync_pm/sync_trello hook chain deduped (legacy sync_trello removed via DEPRECATED_HOOKS)
• 4 pure-CLI skills marked slash-command-only via disable-model-invocation: true
• PreToolUse containment hooks now emit JSON additionalContext payload on block; fail-closed with clean error on unexpected exception (no traceback bleed into hook stdin)
• New E2E smoke test for bpsai-pair mcp serve --transport stdio (skipped on older mcp packages)

v2.25.1 -- Engage Hook Failure Loop Hotfix

• Root cause fix: hook failures now propagate correctly instead of being silently swallowed
• Security audit findings are now visible when engage blocks a PR
• Driver self-commit completeness: remaining uncommitted changes are committed automatically
• Pre-dispatch AC satisfaction check excludes non-source directories
• Release workflow hardened: correct ref on manual dispatch, PyPI-first ordering

v2.25.0 -- Engage Driver Intelligence + Pipeline Reliability

• Pre-dispatch AC check: skip tasks whose work was already completed in prior sprints
• Driver self-commit detection: recognize when drivers commit their own work
• Engage-mode enforcement bypass: headless drivers no longer blocked by interactive hooks
• bpsai-pair preflight: run tests with CI-matching env before pushing
• CI triggers on dev only (no more duplicate runs on main+dev)
• Sweep full-file parsing fix: reads complete files from git refs instead of diff fragments

v2.24.0 -- Sweep: Diff-Aware Dead Code Cleanup

• bpsai-pair sweep: find dead imports, orphaned tests, stale helpers after code changes
• Diff-aware reverse impact analysis with provider auto-detection (Python AST + generic regex)
• --fix auto-removes high-confidence dead imports
• --deep requests full dependency graph analysis from Amunet via A2A
• Post-engage hook: cleanup opportunities in PR body (advisory)
• Review posting fix: large review bodies piped via stdin
• Engage lifecycle hooks pass --allow-dirty for reliable automated sprints
• Full CI test suite green (13,253+ tests) with license bypass for CI

v2.23.2 -- Hotfix: Engage Lifecycle + CI Test Suite

• Engage lifecycle hooks pass --allow-dirty (dirty-tree guard no longer blocks automated task completion)
• Full CI test suite green: 13,253 tests passing on every push
• BPSAI_UNLOCK_ALL_FEATURES env var for CI testing without a license
• NO_COLOR in CI prevents Rich ANSI codes from breaking assertions

v2.23.1 -- Hotfix: Engage Commit Verification + Upgrade Commit

• Fixed false positive engage_commit_empty on every task when repo had a stale CLI version
• Auto-upgrade now commits config artifacts to git (clean tree after upgrade)
• upgrade --commit flag for explicit commit after manual upgrade
• fleet check --upgrade --commit triggers project upgrade + commit per repo

v2.23.0 -- Engage Reliability + Hook Intelligence + Resume

• engage --resume: skip completed tasks on retry, no more re-running entire sprints
• Security agent fail-closed for ALL exceptions (not just OSError). Diff piped via temp file.
• Hook failure propagation: tasks no longer silently succeed when hooks fail
• On-disk dependency verification prevents stale in-memory state
• Human-gated tasks: requires: human in backlog frontmatter pauses engage
• --create-branch / --branch flags for branch lifecycle management
• Pre-engage containment audit warns about protected path conflicts
• TaskCompleted verifies meaningful output (empty commits flagged)
• StopFailure blocks next task and surfaces reason
• SubagentStop + TeammateIdle push status to A2A channels
• Pre-task budget heuristic warns before session limits hit
• Review skills use context: fork for agent isolation
• Forgiving backlog parser (em dash, double hyphen, single hyphen)
• UTF-8 encoding on all engage subprocess calls (Windows cp1252 fix)
• Full test suite CI on every push to dev/main
• 13,275+ tests passing

v2.22.1 -- Hotfix: License Activation Auth

• Machine activation, deactivation, and listing now send the required X-License-Key auth header

v2.22.0 -- Mythology Agent Identity + Vaivora Review Agent

• All agents use mythology names as identifiers: Nayru (reviewer), Laverna (security auditor), Bellona (pre-execution gatekeeper), Vaivora (cross-module review), Divona (QC)
• Vaivora wired as third review agent for large diffs (>500 lines or >10 files)
• Review pipeline refactored: engage, branch, and PR review use shared dispatch with mythology display names
• REVIEW intent type: "review these PRs" routes to the review skill instead of generic reasoning
• Laverna upgraded to Opus model for complete security findings
• Engage auto-created PRs now target dev branch when dev exists
• 12,844+ tests passing

v2.21.5 -- Branch Enforcement + Intent Merge Strategy

• Branch enforcement: source code on main/dev is blocked, docs/state allowed through
• Intent-driven merge strategy: squash vs merge based on work intent and branch pattern
• PR labels (merge:squash, merge:merge) carry strategy to merge time
• Auto-upgrade stages .paircoder/ files to prevent dirty tree in engage
• Stale containment stash cleanup in engage pre-flight
• 12,500+ tests passing

v2.21.4 -- Review Command + Targeted Tests + Engage Fixes

• bpsai-pair review pr/branch/task: Python-enforced review dispatch with agent scaling
• Intent sub-classification routes review requests to the right variant
• Engage tasks run targeted tests (seconds) instead of full suite (minutes)
• Engage executor no longer crashes on lifecycle hook failures
• Engage commits exclude .paircoder/ bookkeeping files (no more merge conflicts)
• Agent mythology display names in review dispatch and output
• Error-as-approval bug fixed: failed reviews no longer pass as approvals
• 12,500+ tests passing

v2.21.3 -- Release Hardening + Engage Review Loop

• Version downgrade protection: CLI no longer overwrites config with older versions
• bpsai-pair release validate-versions: pre-tag gate with --fix auto-repair
• bpsai-pair fleet check: workspace version compliance with --upgrade and --json
• Per-task review loop in autonomous sprints with automatic correction
• Pre-PR security gate blocks pull requests with critical findings
• Agent upgrade preserves custom fields (memory, maxTurns, display names)
• support open shows actual error details instead of generic messages
• 12,500+ tests passing

v2.21.1 -- Remote Session Enforcement

• SessionStart hook auto-installs PairCoder in remote sessions
• API error surfacing across all license, support, and subscription commands

v2.21.0 -- Enforcement + Observability

• Intent recognition and approval gate for autonomous dispatch
• Operational signals: uncommitted code, abandoned sessions, gate blocks
• Protected branch guard: engage refuses to run on main/dev

v2.20.0 -- Engage Pipeline

• bpsai-pair engage runs full sprints autonomously (branch, tasks, PR, review)
• /make-it-so command: intent to shipped PR in one command
• bpsai-pair doctor with 9 health checks and --fix auto-repair

Documentation

• Website & Docs
• Quick Start Guide

Requirements

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

Support

• Email: [e-mail]