Query System Pro+

Structured state and metrics queries with JSON output for CI integration

Overview

The bpsai-pair query command group provides structured access to project state, task data, performance metrics, and skill-generated insights. Every query returns machine-readable JSON, 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

All subcommands default to JSON output. Pass --json for explicit JSON when 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 Percentage of tasks completed without rollback or failure rate, total, passed, failed
estimation_accuracy How closely actual effort matched estimated complexity accuracy, avg_deviation, sample_size
agent_performance Per-agent success rates and response quality scores agents[] with name, invocations, success_rate

Parameters

Parameter Default Description
--days 30 Number of days of telemetry data to include
--json off Output as JSON

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> [--days <days>] [--format json|a2a]

Available Skills

Skill Description Output Fields
sprint_status Current sprint progress with task counts by status sprint, total, done, in_progress, pending
driver_activity Recent driver session history and task throughput sessions[], tasks_completed, avg_duration
review_findings Aggregated code review findings by severity total, critical, warning, info
quality_metrics Test pass rates, coverage trends, and lint scores test_pass_rate, coverage, lint_score
session_outcomes Outcome classification for recent coding sessions sessions[] with outcome, duration, tasks

qc-trends

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

bash 
bpsai-pair query qc-trends [--suite <suite_name>] [--days <days>] [--json]

Parameters

Parameter Default Description
--suite (all) Filter by QC suite name
--days 30 Number of days to include
--json off Output as JSON

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

JSON Output

All query subcommands return a consistent JSON envelope:

json 
{
  "query": "metrics",
  "key": "success_rate",
  "timestamp": "2026-04-13T10:30:00Z",
  "window_days": 30,
  "data": {
    "rate": 0.92,
    "total": 48,
    "passed": 44,
    "failed": 4
  }
}

The envelope always contains:

Field Type Description
query string The subcommand that was executed
key string The specific metric, state key, or skill name queried
timestamp string ISO 8601 timestamp of when the query ran
window_days number The time window used (if applicable)
data object The query result payload (structure varies by query)
Piping to jq

Use jq to extract specific fields from query output: bpsai-pair query metrics success_rate | jq '.data.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 | jq '.data.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: .data.sprint,
  done: .data.done,
  total: .data.total,
  percent: ((.data.done / .data.total) * 100 | floor)
}'

QC Regression Check

Block merges if QC pass rates are declining:

bash 
# Check QC trends for regressions
FAILS=$(bpsai-pair query qc-trends --days 7 | jq '[.data.runs[] | select(.failed > 0)] | length')
if [ "$FAILS" -gt 2 ]; then
  echo "QC regressions detected in last 7 days ($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 '.data.rate' metrics.json)
    COVERAGE=$(jq '.data.coverage' quality.json)

    echo "Success rate: $RATE"
    echo "Coverage: $COVERAGE"

    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, etc.). The JSON output includes an error field on failure with a human-readable message.

Examples

Check Estimation Accuracy

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

# Output:
# {
#   "query": "metrics",
#   "key": "estimation_accuracy",
#   "timestamp": "2026-04-13T10:30:00Z",
#   "window_days": 60,
#   "data": {
#     "accuracy": 0.78,
#     "avg_deviation": 1.4,
#     "sample_size": 32
#   }
# }

List Active Tasks as JSON

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

Agent Performance Breakdown

bash 
# Which agents are performing well?
bpsai-pair query metrics agent_performance --days 14 | jq '.data.agents[] | {name, success_rate}'

Review Findings Summary

bash 
# Get aggregated review findings
bpsai-pair query skill review_findings

# Table output for quick terminal review
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 | jq -r '"Success Rate: \(.data.rate * 100)%"'
bpsai-pair query skill sprint_status | jq -r '"Sprint: \(.data.done)/\(.data.total) tasks done"'
bpsai-pair query skill quality_metrics | jq -r '"Coverage: \(.data.coverage)%"'
bpsai-pair query qc-trends --days 7 | jq -r '"QC Runs (7d): \(.data.runs | length)"'