Metadata-Version: 2.4
Name: bpsai-pair
Version: 2.25.5
Summary: AI-augmented pair programming framework with 218+ CLI commands for planning, orchestration, Trello/GitHub integration, and autonomous workflows
Author-email: BPS AI Software <support@bpsaisoftware.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://paircoder.ai
Project-URL: Documentation, https://paircoder.ai/#/docs
Project-URL: Repository, https://github.com/BPSAI/paircoder
Keywords: ai,pair-programming,cli,claude,gpt,codex,gemini,mcp,trello,github,autonomous,workflow,planning,tasks
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=41.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: sse-starlette>=1.6.0
Requires-Dist: toggl>=0.1.0
Requires-Dist: anthropic>=0.76.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Requires-Dist: pytest-timeout>=2.3; extra == "test"
Requires-Dist: pytest-xdist>=3.5; extra == "test"
Requires-Dist: respx>=0.21; extra == "test"
Provides-Extra: trello
Requires-Dist: py-trello>=0.19.0; extra == "trello"
Provides-Extra: github
Requires-Dist: PyGithub>=2.1; extra == "github"
Provides-Extra: timer
Requires-Dist: toggl>=0.1.0; extra == "timer"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-click>=5.0; extra == "docs"
Provides-Extra: sandbox
Requires-Dist: docker>=7.0.0; extra == "sandbox"
Requires-Dist: dockerpty>=0.4.1; extra == "sandbox"
Provides-Extra: wizard
Requires-Dist: anthropic>=0.76.0; extra == "wizard"
Provides-Extra: all
Requires-Dist: py-trello>=0.19.0; extra == "all"
Requires-Dist: mcp>=1.0.0; extra == "all"
Requires-Dist: docker>=7.0.0; extra == "all"
Requires-Dist: dockerpty>=0.4.1; extra == "all"
Provides-Extra: integrations
Requires-Dist: py-trello>=0.19.0; extra == "integrations"
Dynamic: license-file

# bpsai-pair

> AI-augmented pair programming framework with 218+ CLI commands

[![PyPI version](https://img.shields.io/pypi/v/bpsai-pair)](https://pypi.org/project/bpsai-pair/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)

## 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

```bash
# 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

```bash
# 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.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](https://paircoder.ai)
- [Quick Start Guide](https://paircoder.ai/docs/getting-started/)

## Requirements

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

## Support

- Email: support@bpsaisoftware.com
