PM Integration - PairCoder Docs

Overview

The bpsai-pair pm command group provides a provider-agnostic abstraction layer for project management. It connects local work items to remote PM systems (Trello, Jira, and others) through a unified interface for lifecycle management, synchronization, and hierarchy navigation.

The PM system is organized around three concepts:

Work items represent units of work (tasks, stories, epics) with a defined lifecycle
Providers connect to remote PM systems through a common interface
Workflows define valid status transitions, completion rules, and automations

bash

# Start working on a task
bpsai-pair pm start TASK-42

# Complete with summary
bpsai-pair pm done TASK-42 --summary "Implemented retry logic"

# Check provider health
bpsai-pair pm status

Provider Setup

The PM system discovers providers at startup. Each provider registers itself in the provider registry and is selected through configuration.

Available Providers

Provider	Package	Status
Trello	`bpsai_pair.pm_trello`	Built-in
Jira	`bpsai_pair.pm_jira`	Plugin (if installed)
Slack	`bpsai_pair.pm_slack`	Plugin (if installed)
None	Built-in	No-op provider for local-only workflows

Configuration

Configure the active provider in .paircoder/config.yaml using the pm: section:

yaml

# New style (preferred)
pm:
  provider: trello
  board_id: 694176ebf4b9d27c
  workflow: simple            # Preset name

# Or with custom workflow overrides
pm:
  provider: trello
  board_id: 694176ebf4b9d27c
  workflow:
    preset: bps-full          # Base preset
    automations:              # Override specific sections
      - trigger: checklist_to_card
        source_checklist: Stories
        creates_in: Planned/Ready

Legacy trello: section configs are still supported for backward compatibility. If both pm: and trello: sections exist, the pm: section takes precedence.

Workflow Presets

Two built-in presets are available:

Preset	Mode	Work Item Types	Description
`simple`	simple	Task only	Flat task management with basic status transitions
`bps-full`	hierarchy	Epic, Story, Task	Full hierarchy with automations, completion rules, and button actions

Work Item Lifecycle

Work items move through a defined set of statuses. The workflow configuration determines which transitions are valid.

Statuses

Status	Description
`pending`	Not yet started
`planning`	In planning phase
`enqueued`	Queued and ready to begin
`in_progress`	Currently being worked on
`review`	In review or testing
`testing`	Testing phase
`done`	Completed
`blocked`	Blocked by a dependency or issue
`cancelled`	Cancelled

Starting Work

The pm start command transitions an item to in_progress and adds a comment on the remote provider.

bash

bpsai-pair pm start TASK-42

The lifecycle manager validates the transition before executing it. Starting an item that is already in_progress or done raises a PMTransitionError.

Completing Work

The pm done command transitions an item to done. By default, strict acceptance criteria checking is enabled.

bash

# Complete with strict AC check (default)
bpsai-pair pm done TASK-42 --summary "Added retry logic with backoff"

# Skip AC check (audited)
bpsai-pair pm done TASK-42 --summary "Quick fix" --no-strict

When --strict is active (the default), all acceptance criteria checklist items must be checked before the item can be marked done. Unchecked items cause a PMTransitionError with a list of what remains.

Blocking Work

The pm block command transitions an item to blocked with a required reason.

bash

bpsai-pair pm block TASK-42 --reason "Waiting on API credentials from infra team"

The reason is posted as a comment on the remote provider for visibility.

Transition Rules

Valid transitions depend on the workflow preset. The simple preset uses these rules:

From	Allowed Transitions
`pending`	`in_progress`, `cancelled`
`in_progress`	`review`, `done`, `blocked`
`review`	`done`, `in_progress`
`done`	(terminal)
`blocked`	`in_progress`

The bps-full preset adds planning, enqueued, and testing states with additional transitions. Use bpsai-pair pm config to see the resolved transitions for your active workflow.

Sync

The pm sync command synchronizes local work items with the remote PM provider. It supports both push (local to remote) and conflict detection.

bash

# Sync all local items to provider
bpsai-pair pm sync

Sync Behavior

For each local work item, the sync manager:

Looks up the remote item by ID
Compares title, status, and description fields
Detects conflicts where both local and remote have different non-empty values
Creates, updates, or skips the item based on the comparison

Sync Results

Each item reports one of four outcomes:

Action	Meaning
`CREATED`	Item did not exist remotely and was created
`UPDATED`	Item was updated on the remote provider
`SKIPPED`	No differences detected, nothing to do
`ERROR`	Sync failed for this item (other items continue)

A one-sided difference (only local or only remote has a value) is treated as a safe update. Conflicts are reported but do not block the sync of other items.

Hierarchy

The hierarchy system supports epic, story, and task relationships. Epics contain stories, stories contain tasks. This structure enables automatic rollup of completion status.

License Required

Hierarchy commands require the pm_hierarchy feature gate (Enterprise tier). See Licensing for details.

Viewing Children

bash

# List child items of a parent
bpsai-pair pm children EPIC-1

# Display full hierarchy tree
bpsai-pair pm tree EPIC-1

The tree command renders a recursive hierarchy up to 10 levels deep. It shows each item's ID, title, and status.

Work Item Types

Type	Contains	Completion Rule
`epic`	Stories	All child stories must be done
`story`	Tasks	All child tasks must be done
`task`	(leaf)	All acceptance criteria must be checked

When all children of a parent are done, the parent can be automatically completed using the configured completion rules.

Managing Relationships

bash

# Link children to a parent
bpsai-pair pm link STORY-1 TASK-10 TASK-11 TASK-12

# Remove a parent relationship
bpsai-pair pm unlink TASK-10

Configuration

The pm config command displays the resolved workflow configuration for the active provider, including statuses, transitions, completion rules, and automations.

bash

bpsai-pair pm config

Workflow Modes

Mode	Description
`simple`	Single work item type (task). Flat status transitions.
`hierarchy`	Epic, story, and task types with parent-child relationships.
`local`	Local-only mode with no remote provider.
`custom`	User-defined workflow with custom transitions and rules.

Completion Rules

Completion rules define what must be true before an item can be marked done. Two built-in rule handlers are available:

Rule	Description
`ac_complete`	All acceptance criteria checklist items must be checked
`all_children_done`	All child work items must have `done` status

Automations

The bps-full preset includes automation rules that trigger when checklist items are converted to cards. For example, checking items in an Epic's "Stories" checklist can automatically create Story cards in the target list.

License Required

Automations require the pm_automations feature gate. Custom workflows require the pm_custom_workflow gate. Both are available on the Enterprise tier.

Button Actions

Workflows can define button actions that execute composite operations in a single call:

bash

# Execute a named button action
bpsai-pair pm action claim_card TASK-42
bpsai-pair pm action mark_as_deployed TASK-42

A button action can move an item, set fields, add a member, set dates, mark as complete, and post a comment in a single atomic operation. The requires_field option blocks execution until a specific field is populated.

Command Reference

Core Lifecycle

Command	Description
`pm start <item_id>`	Move item to `in_progress`
`pm done <item_id> --summary <text>`	Complete item (strict AC check by default)
`pm block <item_id> --reason <text>`	Mark item as blocked with reason
`pm status`	Show provider connection health and capabilities
`pm diagnostics`	Run provider diagnostics and connectivity checks
`pm config`	Show resolved workflow configuration

Sync

Command	Description
`pm sync`	Sync local items to remote provider with conflict detection

Hierarchy

Command	Description	License
`pm children <parent_id>`	List child work items	`pm_hierarchy`
`pm tree <root_id>`	Display recursive hierarchy tree	`pm_hierarchy`
`pm link <parent_id> <child_ids...>`	Link children to parent	`pm_hierarchy`
`pm unlink <child_id>`	Remove parent relationship	`pm_hierarchy`

CRUD Operations

Command	Description
`pm create --type <type> --title <title>`	Create a work item (task, story, or epic)
`pm move <item_id> --status <status>`	Move item to a new status
`pm comment <item_id> <message>`	Add a comment to an item
`pm check <item_id> <checklist_item_id>`	Check an acceptance criteria item
`pm set-field <item_id> --field <name> --value <value>`	Set a custom field value
`pm action <action_name> <item_id>`	Execute a workflow button action

Sprint Management

Command	Description
`pm sprint start <plan_id>`	Mark a sprint plan as in-progress
`pm sprint complete <plan_id>`	Complete sprint with task summary

License Requirements

PM features are gated by license tier:

Feature Gate	Tier	Includes
`pm_basic`	Solo	start, done, block, sync, status, diagnostics, config, CRUD operations
`pm_hierarchy`	Enterprise	children, tree, link, unlink, parent-child relationships
`pm_automations`	Enterprise	Automation rules (checklist-to-card, enrichment, discovery)
`pm_custom_workflow`	Enterprise	Custom workflow configurations beyond built-in presets

Commands that require a feature gate will raise a FeatureNotAvailable error if your license does not include it. See Licensing for tier details.

Error Handling

The PM system uses a typed error hierarchy:

Error	Cause
`PMItemNotFoundError`	Work item ID does not exist locally or remotely
`PMTransitionError`	Invalid status transition (e.g., `done` to `pending`)
`PMConnectionError`	Cannot reach the remote PM provider
`PMSyncConflictError`	Local and remote have conflicting field values
`FeatureNotAvailable`	License does not include the required feature gate

Examples

Basic Task Workflow

bash

# Start a task
bpsai-pair pm start TASK-42

# Check acceptance criteria status
bpsai-pair pm check TASK-42 ac-item-1

# Complete the task
bpsai-pair pm done TASK-42 --summary "Implemented with tests"

# Sync to remote
bpsai-pair pm sync

Hierarchy Workflow (Enterprise)

bash

# View the epic tree
bpsai-pair pm tree EPIC-1

# List stories in an epic
bpsai-pair pm children EPIC-1

# Link tasks to a story
bpsai-pair pm link STORY-5 TASK-50 TASK-51 TASK-52

# Complete all tasks, then the story rolls up
bpsai-pair pm done TASK-50 --summary "Done"
bpsai-pair pm done TASK-51 --summary "Done"
bpsai-pair pm done TASK-52 --summary "Done"

Diagnostics and Troubleshooting

bash

# Check provider connection
bpsai-pair pm status

# Run full diagnostics
bpsai-pair pm diagnostics

# View resolved workflow config
bpsai-pair pm config