User Guide All Tiers

Core concepts and workflows for AI-augmented pair programming

What is PairCoder?

PairCoder is a toolkit for pairing with AI coding agents. It provides:

  • Structured context - Project memory in .paircoder/ that AI agents read and update
  • Planning workflows - Plans, sprints, and tasks in YAML/Markdown
  • Skills - Reusable workflow templates
  • Autonomous sprints - Run full sprint cycles with bpsai-pair engage
  • Code review - AI-powered review with bpsai-pair review
  • Health diagnostics - Check your setup with bpsai-pair doctor
  • Multi-agent orchestration - Route tasks to the right AI based on complexity
  • Analytics - Token tracking, cost estimation, time tracking
Philosophy

PairCoder treats AI as a pair programming partner: The AI navigates (plans, designs, reviews), you drive (approve, implement, test), and context is shared via standardized files.

The Context Loop

How PairCoder maintains project understanding:

  1. Read - AI reads project.md, workflow.md, state.md
  2. Work - AI performs tasks, writes code
  3. Update - AI updates state.md with progress
  4. Persist - Changes are committed to repo

Project Structure

.paircoder/ Directory

text 
.paircoder/
├── config.yaml           # Project configuration
├── capabilities.yaml     # LLM capability manifest
├── context/
│   ├── project.md       # Project overview, goals
│   ├── workflow.md      # How work is done here
│   └── state.md         # Current state, active tasks
├── plans/               # Plan files (.plan.yaml)
├── tasks/               # Task files (.task.md)
└── history/             # Archives, metrics

.claude/ Directory

text 
.claude/
├── skills/              # Workflow templates
├── agents/              # Custom subagents
└── settings.json        # Claude Code settings

Plans & Tasks

Plans are high-level goals with sprints and tasks. Tasks are specific work items with status, priority, and complexity.

Task Lifecycle

text 
pending → in_progress → done
                  ↘ blocked → pending (when unblocked)
                  ↘ cancelled

Common Commands

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

# List tasks
bpsai-pair task list

# Get next recommended task
bpsai-pair task next

# Update task status
bpsai-pair task update TASK-001 --status in_progress
bpsai-pair task update TASK-001 --status done

Engage: Autonomous Sprints

The engage command runs an autonomous sprint cycle. It picks up pending tasks from your plan, executes them through planning, implementation, testing, and review, then commits the results.

bash 
# Run an autonomous sprint
bpsai-pair engage backlog.md

Engage is the recommended way to process a backlog of tasks. See the Engage Guide for configuration and usage details.

Review: AI Code Review

The review command runs an AI-powered code review on your current changes or a specific branch.

bash 
# Review a pull request
bpsai-pair review pr 42

# Review current branch changes
bpsai-pair review branch

# Auto-detect review target
bpsai-pair review auto

See the Review Guide for details on review modes and output formats.

Skills

Skills are reusable workflow templates in .claude/skills/.

Skill Triggers Purpose
designing-and-implementing "design", "plan", "feature" Feature development
implementing-with-tdd "fix", "bug", "test" Test-driven development
reviewing-code "review", "check", "PR" Code review workflow
finishing-branches "finish", "merge" Branch completion

Orchestration

Pro Feature

Model routing requires Pro or Enterprise license.

Route tasks to the right AI model based on complexity:

yaml 
routing:
  by_complexity:
trivial:   { max_score: 20,  model: claude-haiku-4-5 }
simple:    { max_score: 40,  model: claude-haiku-4-5 }
moderate:  { max_score: 60,  model: claude-sonnet-4-5 }
complex:   { max_score: 80,  model: claude-opus-4-5 }
epic:      { max_score: 100, model: claude-opus-4-5 }

Metrics & Analytics

bash 
# Session summary
bpsai-pair metrics summary

# Task-specific metrics
bpsai-pair metrics task TASK-001

# Budget status
bpsai-pair budget status