Engage Pro+

Overview

bpsai-pair engage takes a markdown backlog and autonomously executes the entire sprint: parses tasks, creates a feature branch, plans with the Navigator, runs each task through the Driver, commits work, audits for security issues, opens a PR, and dispatches review agents. One command turns a backlog into a shipped pull request.

bpsai-pair engage backlog-sprint-18.md

The command runs through these phases in order:

1. Approval gate and pre-flight checks
2. Feature branch creation
3. Navigator planning (optional)
4. Backlog materialization into plan + task files
5. Sprint execution (task-by-task, phase-by-phase)
6. Pre-PR security audit
7. Cross-module review (for large diffs)
8. PR creation
9. Review agent dispatch
10. Telemetry recording

Backlog Format

Engage consumes a markdown file that defines the sprint tasks. The parser is flexible with formatting but expects a consistent structure.

Minimal Example

# Sprint 18: Auth Overhaul

### Phase 1: Core

### T18.1 -- Add JWT validation | Cx: 8 | P0

**Description:** Add JWT token validation middleware to the API gateway.

**AC:**
- [ ] Middleware validates JWT signature on all protected routes
- [ ] Invalid tokens return 401 with structured error body
- [ ] Token expiry is checked and returns 401 when expired

**Depends on:** None

### T18.2 -- Refresh token endpoint | Cx: 5 | P1

**Description:** Create POST /auth/refresh that issues a new access token.

**AC:**
- [ ] Endpoint accepts refresh token in request body
- [ ] Returns new access token with updated expiry
- [ ] Revoked refresh tokens return 403

**Depends on:** T18.1

### Phase 2: Testing

### T18.3 -- Integration tests for auth flow | Cx: 5 | P1

**Description:** End-to-end tests covering login, refresh, and token expiry.

**AC:**
- [ ] Test covers successful login flow
- [ ] Test covers token refresh
- [ ] Test covers expired token rejection

**Depends on:** T18.1, T18.2

Task Header Format

Each task starts with an H3 heading containing the ID, title, complexity, and priority:

### T18.1 -- Add JWT validation | Cx: 8 | P0

The parser accepts multiple separator styles between the ID and title:

• -- (double hyphen)
• - (single hyphen, spaced)

Field Reference

Phase Markers

Tasks are grouped into phases using H3 headers with the format ### Phase N: Name. Phases execute sequentially. Tasks within a phase can run in parallel (up to --max-parallel). If no phase markers are present, all tasks default to Phase 1.

Execution Flow

Once the backlog is parsed and materialized, Engage builds an execution graph and processes tasks phase by phase.

Phase Execution

1. Dependency check -- each task is marked "ready" only when all its dependencies are done
2. Task execution -- the Driver runs the task via a headless Claude Code session in auto permission mode
3. Commit -- on success, changes are committed with a message referencing the task ID
4. Per-task review -- an optional reviewer checks the committed work for blocking issues
5. Findings loop -- if blocking issues are found, the Driver attempts iterative fixes (up to 3 attempts)
6. Status update -- task is marked done or failed in the execution graph

Circuit Breaker

If the failure ratio within a phase reaches 50% (configurable via circuit_breaker_threshold), Engage stops execution after the current phase completes. This prevents cascading failures from burning through the remaining backlog.

Flags Reference

Examples

# Basic sprint execution
bpsai-pair engage backlog-sprint-18.md

# Preview without executing
bpsai-pair engage backlog-sprint-18.md --dry-run

# Skip planning, limit to 2 parallel tasks
bpsai-pair engage backlog-sprint-18.md --skip-planning --max-parallel 2

# Use a custom branch name
bpsai-pair engage backlog-sprint-18.md --branch feature/auth-overhaul

# Stay on the current branch (no branch creation)
bpsai-pair engage backlog-sprint-18.md --no-create-branch

# Resume after a failure or interruption
bpsai-pair engage backlog-sprint-18.md --resume

# Resume a specific prior run
bpsai-pair engage backlog-sprint-18.md --resume-run run_abc123

# Run hooks in advisory mode (non-blocking)
bpsai-pair engage backlog-sprint-18.md --hooks-advisory

# JSON output for CI integration
bpsai-pair engage backlog-sprint-18.md --dry-run --json

Human-Gated Tasks

Some tasks cannot be fully automated. Mark them in the backlog with **Requires:** human to pause execution and hand control back to the operator.

### T18.5 -- Configure production secrets | Cx: 3 | P0

**Description:** Set up production environment variables in the deployment platform.

**Requires:** human

**AC:**
- [ ] DATABASE_URL set in production environment
- [ ] JWT_SECRET rotated and stored in vault
- [ ] Deployment smoke test passes

**Depends on:** T18.3

When Engage reaches a human-gated task, it:

1. Pauses execution and prints the task details to the terminal
2. Waits for the operator to complete the task manually
3. Resumes execution after the operator confirms completion

Dependent tasks are blocked until the human-gated task is marked done. Non-dependent tasks in the same phase continue executing in parallel.

Resume Flow

If an Engage run is interrupted (network failure, manual stop, circuit breaker), you can resume where it left off instead of starting over.

Resume the last run

bpsai-pair engage backlog-sprint-18.md --resume

This loads the execution state from the last run, identifies which tasks completed successfully, and resumes from the next incomplete task in the current phase.

Resume a specific run

bpsai-pair engage backlog-sprint-18.md --resume-run run_abc123

Use --resume-run with a specific run ID when you have multiple incomplete runs and need to target one. Run IDs are printed at the start of each Engage session and recorded in telemetry.

What resume preserves

• Completed task statuses (skipped on resume)
• The existing feature branch and its commits
• Plan and task files already materialized

What resume does not preserve

• In-progress tasks at the time of interruption (re-executed from scratch)
• Failed tasks (retried on resume)

Security Gate

Before creating a PR, Engage runs a security audit against the full branch diff. This is the last gate before code leaves your local machine.

Pre-PR Security Check

1. Computes the full diff between the feature branch and the base branch (main, dev, or master, auto-detected)
2. Dispatches a security-auditor agent with read-only access (Read, Glob, Grep only)
3. The auditor analyzes for vulnerabilities, credential exposure, and OWASP top-10 issues
4. Findings are classified by severity

Approval Gate

Before any execution begins, Engage runs an approval gate that checks containment policy and cleans up stale auto-stashes older than 7 days. If the gate blocks, Engage exits with code 1.

Protected Branch Guard

Engage refuses to run on protected branches. By default, main, dev, and master are protected. Customize this list in your config:

# .paircoder/config.yaml
engage:
  protected_branches:
    - main
    - dev
    - master
    - release/*

PR Creation

After all phases complete and the security gate passes, Engage pushes the feature branch and creates a pull request.

PR Title

The title is derived from the H1 heading in your backlog file, capped at 70 characters, with a summary suffix:

Auth Overhaul (5 done, 1 failed)

If the backlog has no H1 heading, the fallback format is Sprint {N}: {done} done, {failed} failed.

PR Body

The body is auto-generated with sections for completed, failed, and blocked tasks:

## Completed
- T18.1
- T18.2
- T18.3

## Failed
- T18.4

## Blocked
- T18.5

Review Dispatch

After the PR is created, Engage dispatches two review agents that post their findings as a combined PR review.

Reviewer Agent

Analyzes the full PR diff for code quality, correctness, and best practices. Runs in plan mode with read-only tools.

Security-Auditor Agent

Re-analyzes the PR diff specifically for security vulnerabilities, credential exposure, and OWASP issues. Also runs in plan mode with read-only tools.

Review Actions

The combined findings are classified into a review action:

Cross-Module Review

For large diffs (500+ lines changed or 10+ files modified), Engage dispatches an additional cross-module reviewer that focuses on:

• Cross-module interactions and integration issues
• Architectural concerns from wide-reaching changes
• Contract breaks between modules

Troubleshooting