Query System - PairCoder Docs

Overview

The bpsai-pair query command group provides structured access to project state, task data, performance metrics, and skill-generated insights. Every subcommand can emit machine-readable JSON (via --json, or by default for query skill), making it suitable for CI pipelines, dashboards, and scripted workflows.

bash

# Query a metric
bpsai-pair query metrics success_rate

# Query project state
bpsai-pair query state active-tasks

# Query a skill
bpsai-pair query skill sprint_status

query skill defaults to JSON output. Every other subcommand (metrics, state, tasks, task-state, qc-trends) prints a human-readable table by default -- pass --json explicitly to get machine-readable output for scripting. The query skill subcommand also accepts --format json|a2a.

Available Queries

metrics

The query metrics subcommand retrieves computed performance metrics from telemetry data. Each metric is calculated on demand from the local telemetry store.

bash

bpsai-pair query metrics <metric_name> [--days <days>] [--json]

Available Metrics

Metric	Description	Output Fields
`success_rate`	Aggregate success rate across calibrated task types (or a single type with `--task-type`)	`rate`
`estimation_accuracy`	How closely actual effort matched estimated complexity (mean absolute percentage error)	`mape`, `bias`, `sample_count`
`agent_performance`	Per-model task counts, success rates, and average token usage	`models` -- an object keyed by model name, each with `task_count`, `success_rate`, `avg_tokens`

Parameters

Parameter	Default	Description
`--task-type`	(all)	Filter `success_rate` to a single task type
`--days`	(unfiltered)	Filter by recency in days
`--json`	off	Output as JSON instead of a table

state

The query state subcommand reads structured project state from .paircoder/context/ and returns it as JSON.

bash

bpsai-pair query state <key> [--json]

Available State Keys

Key	Description	Source
`active-tasks`	All tasks with status `in_progress` or `pending`	`.paircoder/tasks/`
`current-plan`	The currently active plan with task summary counts	`.paircoder/context/state.md`

tasks

The query tasks subcommand lists tasks with optional filtering by status.

bash

bpsai-pair query tasks [--status <status>] [--json]

Parameters

Parameter	Default	Description
`--status`	(all)	Filter by task status: `pending`, `in_progress`, `done`, `blocked`
`--json`	off	Output as JSON

skill

The query skill subcommand executes a named skill query and returns its structured output. Skills produce domain-specific reports by aggregating data from multiple sources.

bash

bpsai-pair query skill <skill_name> [--format json|a2a] [--root <path>]

Unlike the other subcommands, query skill defaults to JSON output already -- --format only matters if you want the a2a (framework schema) shape instead.

Available Skills

Skill	Description	Output Fields
`sprint_status`	Current sprint progress with task counts by status	`sprint`, `tasks_done`, `tasks_in_progress`, `tasks_blocked`, `tasks_pending`, `total_complexity`
`driver_activity`	Recent driver session history and task throughput	`sessions` (count), `total_duration_s`, `tasks_touched`, `avg_tests_passed`
`review_findings`	Aggregated code review findings and enforcement overrides	`reviews`, `total_errors`, `error_categories`, `enforcement_overrides`
`quality_metrics`	Test pass rate, success rate, and average tokens per task	`test_pass_rate`, `avg_tokens_per_task`, `success_rate`, `sample_count`
`session_outcomes`	Outcome classification for recent coding sessions	`total_sessions`, `outcomes` (counts by outcome), `avg_duration_s`

qc-trends

The query qc-trends subcommand reports QC test pass/fail trends over time.

bash

bpsai-pair query qc-trends [--suite <suite_name>] [--env <environment>] [--json]

Parameters

Parameter	Default	Description
`--suite`	(all)	Filter by QC suite name
`--env`	(all)	Filter by environment name
`--json`	off	Output as JSON

The output includes per-run results with timestamps, suite names, scenario counts, and pass/fail totals.

JSON Output

There is no universal envelope -- the shape is flat and varies by subcommand. metrics, state, tasks, and task-state (all backed by the same query builder) share a category field naming which one ran, plus that subcommand's own payload keys at the top level:

json

{
  "category": "metrics",
  "metric": "success_rate",
  "rate": 0.92
}

query skill and query qc-trends return their own payload directly, with no category wrapper at all -- see each subcommand's Output Fields above for the exact keys.

Piping to jq

Query result fields sit at the top level, not under a .data key. Extract them directly: bpsai-pair query metrics success_rate --json | jq '.rate'

CI Integration

The JSON output format makes bpsai-pair query a natural fit for CI pipelines. Use queries to gate deployments, generate reports, or feed dashboards.

Gate on Success Rate

Fail a CI step if the task success rate drops below a threshold:

bash

# In your CI pipeline
RATE=$(bpsai-pair query metrics success_rate --json | jq '.rate')
if (( $(echo "$RATE < 0.85" | bc -l) )); then
  echo "Success rate $RATE is below 85% threshold"
  exit 1
fi

Sprint Progress Report

Generate a sprint summary for Slack or email notifications:

bash

# Extract sprint progress
bpsai-pair query skill sprint_status | jq '{
  sprint: .sprint,
  done: .tasks_done,
  in_progress: .tasks_in_progress,
  pending: .tasks_pending,
  blocked: .tasks_blocked
}'

QC Regression Check

Block merges if QC pass rates are declining:

bash

# Check QC trends for regressions (most recent runs)
FAILS=$(bpsai-pair query qc-trends --json | jq '[.runs[] | select(.failed > 0)] | length')
if [ "$FAILS" -gt 2 ]; then
  echo "QC regressions detected in the most recent runs ($FAILS failing runs)"
  exit 1
fi

GitHub Actions Example

yaml

- name: Check project health
  run: |
    bpsai-pair query metrics success_rate --json > metrics.json
    bpsai-pair query skill quality_metrics --format json > quality.json

    RATE=$(jq '.rate' metrics.json)
    PASS_RATE=$(jq '.test_pass_rate' quality.json)

    echo "Success rate: $RATE"
    echo "Test pass rate: $PASS_RATE"

    if (( $(echo "$RATE < 0.80" | bc -l) )); then
      echo "::error::Success rate below threshold"
      exit 1
    fi

Exit Codes

All query commands exit with code 0 on success and code 1 on failure (invalid metric name, missing data, provider errors, etc.); the failure reason is printed to the terminal, not embedded as a JSON field.

Examples

Check Estimation Accuracy

bash

# How accurate are our complexity estimates?
bpsai-pair query metrics estimation_accuracy --days 60 --json

# Output:
# {
#   "category": "metrics",
#   "metric": "estimation_accuracy",
#   "mape": 14.2,
#   "bias": "under",
#   "sample_count": 32
# }

List Active Tasks as JSON

bash

# Get all in-progress tasks for the current sprint
bpsai-pair query tasks --status in_progress --json

Agent Performance Breakdown

bash

# Which models are performing well?
bpsai-pair query metrics agent_performance --days 14 --json | jq '.models'

Review Findings Summary

bash

# Get aggregated review findings (raw JSON, the default)
bpsai-pair query skill review_findings

# Framework-schema JSON for A2A transport
bpsai-pair query skill review_findings --format a2a

Combined Dashboard Query

bash

# Build a project health snapshot
echo "=== Project Health ==="
bpsai-pair query metrics success_rate --json | jq -r '"Success Rate: \(.rate * 100)%"'
bpsai-pair query skill sprint_status | jq -r '"Sprint: \(.tasks_done) done, \(.tasks_in_progress) in progress, \(.tasks_pending) pending"'
bpsai-pair query skill quality_metrics | jq -r '"Test pass rate: \(.test_pass_rate)%"'
bpsai-pair query qc-trends --json | jq -r '"QC Runs: \(.runs | length)"'