pitcrew

Pit Crew

Autonomous issue-to-PR pipeline for Claude Code. Label a GitHub issue pitcrew-ready, run the orchestrator, and get a reviewed pull request — no manual intervention required.

How it works

The pipeline runs 7 stages per issue, each powered by a specialist Claude agent:

pitcrew-ready label
      │
      ▼
  orchestrate          checks blockers, skips issues with open deps
      │
      ▼
1. setup-workspace     creates branch + worktree, moves board to In Progress
2. plan                ticket-analyst reads issue → writes brief.json with ACs + assignments
3. implement           specialist agents (frontend, backend, db, ...) write the code
4. verify              one verifier agent per acceptance criterion, re-dispatches failures
5. test                playwright-engineer writes E2E tests
6. review-loop         /code-review in a loop until clean (max 5 rounds)
7. finalize            draft → ready for review, board → In Review, worktree cleaned up

Failures at any stage label the issue pitcrew-failed and post a comment explaining what broke.

Prerequisites

• Claude Code CLI installed and authenticated
• GitHub CLI authenticated with repo and project scopes
• A GitHub repo with a GitHub Projects v2 board (Status field with Ready / In Progress / In Review / Blocked / Done columns)

Installation

Clone this repo into your Claude Code plugins directory:

git clone https://github.com/briannaworkman/pitcrew ~/.claude/plugins/pitcrew

Claude Code auto-discovers plugins in ~/.claude/plugins/. The commands, agents, and hooks load on next session start.

Project setup

1. Generate pipeline-config.json

From inside your project repo:

bash ~/.claude/plugins/pitcrew/setup/fetch-project-ids.sh <owner/repo>

This queries your GitHub Projects board and prints a pre-filled config. Redirect it into place:

bash ~/.claude/plugins/pitcrew/setup/fetch-project-ids.sh owner/repo > .claude/pipeline-config.json

The config format:

{
  "repo": "owner/repo",
  "project": {
    "id": "PVT_...",
    "number": 1,
    "statusFieldId": "PVTSSF_...",
    "statusOptions": {
      "backlog": "<option-id>",
      "ready": "<option-id>",
      "inProgress": "<option-id>",
      "inReview": "<option-id>",
      "blocked": "<option-id>",
      "done": "<option-id>"
    }
  },
  "labels": {
    "trigger": "pitcrew-ready",
    "failed": "pitcrew-failed"
  },
  "branchPrefix": "pitcrew/"
}

2. Create labels

gh label create pitcrew-ready  --repo owner/repo --color "0E8A16" --description "Ready for Pit Crew pipeline"
gh label create pitcrew-failed --repo owner/repo --color "B60205" --description "Pit Crew pipeline failed"

3. Add a verify command to your project

The pipeline runs npm run verify (or equivalent) after each implementation stage. Make sure your project has a verify script in package.json that covers typecheck + lint + unit tests.

Usage

Label an issue

Add the pitcrew-ready label to any open issue. The issue body should include clear acceptance criteria (checkboxes work well).

Run the orchestrator

In your project directory:

/pitcrew:orchestrate

This discovers all pitcrew-ready issues, checks blockers (blocked by: #N / depends on: #N in the issue body), and dispatches the pipeline for each eligible issue in the background.

To run a single issue directly:

bash ~/.claude/plugins/pitcrew/setup/run-issue.sh <issue_number>

Logs land in .pipeline/runs/issue-<N>.log.

Writing good issues

The pipeline works best when issues have:

• A clear Scope — what files/components to create or change
• A Reference section — Figma links, API contracts, existing code to follow
• Acceptance criteria as a checkbox list — each criterion maps to one verifier agent

Example structure:

## Scope

Create `components/ui/MyComponent.tsx` …

## Reference

- Figma: `<file-key>`, node `12:34`
- Token docs: `tokens/colors.css`

## Acceptance criteria

- [ ] Exported from `components/ui/`
- [ ] Zero hardcoded values — all via CSS tokens
- [ ] Accessible: keyboard navigable, correct ARIA roles

Specialists