Cross-Repo Orchestration - PairCoder Docs

PairCoder's workspace orchestration enables multi-repo awareness: detect contract changes in one project and trace their impact across the dependency graph.

Workspace Required

Orchestration features require a configured workspace with multiple projects. See the Workspace guide to set up your workspace before using orchestration.

Overview

When working across multiple repositories, a change in one project can silently break consumers downstream. PairCoder's orchestration system solves this by:

Detecting contract changes (schemas, routes, commands, configs) from git diffs
Mapping those changes to affected consumer projects via the dependency graph
Producing impact reports with severity levels and recommended actions
Enabling sibling project audits for compliance and consistency

Workspace Setup

Orchestration is configured through .paircoder-workspace.yaml, which defines projects, paths, and dependency relationships.

Initialize a Workspace

bash

bpsai-pair workspace init --name my-platform --projects cli:./tools/cli,api:./services/api,web:./apps/web

Workspace Configuration

Each project in the workspace can declare its dependency relationships:

yaml

# .paircoder-workspace.yaml
name: my-platform
projects:
  cli:
path: ./tools/cli
consumers:
  - web
consumes: []
  api:
path: ./services/api
consumers:
  - cli
  - web
consumes: []
  web:
path: ./apps/web
consumers: []
consumes:
  - cli
  - api

consumers — projects that depend on this project (who depends on me)
consumes — projects that this project depends on (who I depend on)

Impact Analysis Workflow

The impact analysis workflow runs in three stages to identify and report cross-repo effects of changes:

1. Contract Detection

The ContractDetector scans git diffs for changes that constitute contract modifications. It recognizes four categories of contract changes:

Schema changes — database models, API request/response shapes, data structures
Route changes — API endpoints, URL patterns, HTTP methods
Command changes — CLI commands, arguments, flags, subcommands
Config changes — configuration file formats, environment variables, settings

2. Consumer Mapping

Detected changes are mapped to affected consumers via the workspace dependency graph. If the api project has a route change and cli and web are declared as consumers, both are flagged as potentially impacted.

3. Impact Analysis

The ImpactAnalyzer produces an ImpactReport that includes severity levels, affected projects, and recommended actions for each detected change.

bash

# Run impact analysis on recent changes
bpsai-pair workspace check-impact

# Analyze changes since a specific commit
bpsai-pair workspace check-impact --since abc1234

# Output as JSON for CI integration
bpsai-pair workspace check-impact --json

Severity Levels

Each detected contract change is assigned a severity level based on its potential to break consumers:

Severity	Trigger	Description
HIGH	Schema or route changes	Breaking API contracts — likely to cause failures in consumers
MEDIUM	Command changes	CLI interface changes — may break scripts or integrations
LOW	Config changes	Configuration file modifications — may require consumer updates

CI Integration

Use bpsai-pair workspace check-impact --json in your CI pipeline to automatically detect breaking changes before merge. The JSON output includes structured severity data suitable for automated gate checks.

Sibling Audit

The sibling audit feature lets you audit a specific project in your workspace for compliance issues, configuration drift, and consistency problems.

bash

# Audit a sibling project
bpsai-pair workspace audit api

# Audit and automatically fix detected issues
bpsai-pair workspace audit api --fix

# Output audit results as JSON for CI
bpsai-pair workspace audit api --json

The audit checks for:

Missing or outdated configuration files
Dependency declaration mismatches
Convention violations across sibling projects
Stale contract references

When --fix is specified, the auditor will attempt to resolve detected issues automatically and report what was changed.

Agent Team Integration

Orchestration integrates with PairCoder's agent team model, where different roles collaborate on cross-repo tasks:

Role	Team Position	Responsibility	Permission Mode
Navigator	Lead	Planning, coordination, cross-repo strategy	plan
Driver	Teammate	Implementation, execution of changes	auto
Reviewer	Teammate	Audit, compliance checks, impact review	plan

Effort levels are calibrated from the feedback system, allowing the team to learn from past task estimates
Navigator and Reviewer operate in plan mode — they propose changes but require confirmation
Driver operates in auto mode — executes approved changes autonomously

CLI Commands

Initialize Workspace

bash

bpsai-pair workspace init --name <name> --projects <name:path,...>

Creates a .paircoder-workspace.yaml with the specified projects and initializes the dependency graph.

View Workspace Status

bash

bpsai-pair workspace status

Displays the current workspace configuration, registered projects, and dependency relationships.

Check Impact

bash

# Detect contract changes and analyze impact
bpsai-pair workspace check-impact

# Since a specific commit
bpsai-pair workspace check-impact --since abc1234

# JSON output for CI
bpsai-pair workspace check-impact --json

Scans for contract changes in the current project and reports their impact on consumer projects.

Audit Sibling Project

bash

# Audit a specific project
bpsai-pair workspace audit <project>

# Auto-fix detected issues
bpsai-pair workspace audit <project> --fix

# JSON output
bpsai-pair workspace audit <project> --json

Runs compliance and consistency checks against a sibling project in the workspace.

Pull Latest Changes

bash

# Pull all projects
bpsai-pair workspace pull

# Pull a specific project
bpsai-pair workspace pull api

# Pull with rebase
bpsai-pair workspace pull --rebase

Pulls the latest changes for one or all projects in the workspace. Use --rebase to rebase instead of merge.