QA Captain

Turn branch diffs into QA-ready test plans. A local-first CLI that prepares structured change-analysis bundles and generates Claude Code prompts for detailed QA handoff reports.

What it does

QA Captain bridges the gap between "code complete" and "ready for QA." It:

1. Analyzes your branch diff against the base branch
2. Prepares a structured context bundle (diff, file list, commits, metadata)
3. Generates a dynamic prompt optimized for Claude Code
4. Produces a comprehensive QA test plan via the /qa-handoff Skill

Install

npm install -g qa-captain

Requires Node.js 18+ and Git.

Quick Start

# 1. Initialize in your repo
cd your-project
qa-captain init

# 2. Edit project context files
#    .qa-captain/project-context/product.md
#    .qa-captain/project-context/architecture.md
#    .qa-captain/project-context/test-conventions.md

# 3. On a feature branch, prepare the context
qa-captain prepare --base main --intent "Add subscription cancellation flow"

# 4. In Claude Code, generate the QA report
/qa-handoff

Commands

qa-captain init

Initialize QA Captain in your git repository. Creates the .qa-captain/ directory structure, config file, project context starters, and installs the Claude Code /qa-handoff Skill.

qa-captain init          # Skip existing files
qa-captain init --force  # Overwrite existing files

qa-captain prepare

Prepare a QA context bundle from the current branch's changes.

qa-captain prepare                          # Compare against configured base branch
qa-captain prepare --base develop           # Compare against specific branch
qa-captain prepare --range main...feature   # Use explicit git range
qa-captain prepare --intent "Add OAuth2"    # Include developer intent
qa-captain prepare --intent-file intent.md  # Intent from file
qa-captain prepare --json                   # Output summary as JSON

qa-captain doctor

Check your QA Captain setup and dependencies.

qa-captain doctor

qa-captain version

Print the version number.

Claude Code Skill

qa-captain init installs a project-level Claude Code Skill at:

.claude/skills/qa-handoff/SKILL.md

This Skill is invoked with /qa-handoff in Claude Code. It reads the prepared context from .qa-captain/context/ and generates a detailed QA handoff report.

Passing extra instructions

You can pass optional focus areas when invoking the Skill:

/qa-handoff focus especially on push notification deep links and cold-launch behavior

The Skill will incorporate these as additional QA focus while still relying on the prepared context as the primary evidence.

What the Skill does

1. Reads prepared context (diff, file list, commits, metadata)
2. Reads the generated prompt contract
3. Inspects the wider repository for affected flows and regression risk
4. Generates both a Markdown test plan and a JSON report
5. Writes reports to .qa-captain/reports/
6. Prints a summary in chat (risk level, test count, ambiguities)

Configuration

Edit .qa-captain/config.yml:

# Base branch for comparison
base_branch: main

# Max diff size before truncation (characters)
max_diff_size: 200000

# Project context files for the QA prompt
context_files:
  - .qa-captain/project-context/product.md
  - .qa-captain/project-context/architecture.md
  - .qa-captain/project-context/test-conventions.md

# Keywords that trigger risk signals
risk_keywords:
  - auth
  - payment
  - security
  - migration
  - database

Project Context

Fill in the project context files to give Claude Code domain knowledge:

• product.md -- What the product does, key user flows, business rules
• architecture.md -- Tech stack, components, data flow, integrations
• test-conventions.md -- Test environments, tools, known limitations

The more context you provide, the better the QA reports.

How It Works

1. qa-captain prepare collects the git diff, file list, commit log, and metadata
2. It detects risk signals by scanning for configured keywords
3. Large diffs are truncated (largest files dropped first, full file list preserved)
4. A dynamic prompt is generated with embedded metadata
5. /qa-handoff in Claude Code reads the prepared context and generates:
   • A Markdown test plan (.qa-captain/reports/latest-handoff.md)
   • A JSON report (.qa-captain/reports/latest-handoff.json)

Directory Structure

.qa-captain/
├── config.yml              # Configuration (committed)
├── project-context/        # Domain knowledge (committed)
│   ├── product.md
│   ├── architecture.md
│   └── test-conventions.md
├── context/                # Generated per prepare (gitignored)
├── prompts/                # Generated prompts
└── reports/                # Generated reports (gitignored)

.claude/
└── skills/
    └── qa-handoff/
        └── SKILL.md        # Claude Code Skill (committed)

Migrating from v0.1.x

QA Captain v0.2.0 switches the recommended Claude Code integration from legacy project commands to native Claude Skills.

Existing .claude/commands/qa-handoff.md files continue to work, but new installs generate:

.claude/skills/qa-handoff/SKILL.md

To install the latest Skill integration:

qa-captain init --force

Skills take precedence over commands when both share the same slash name.

License

MIT - John Anthony Pecson