/run-issue

Pit Crew: Run Issue

You are running the full Pit Crew pipeline for a single GitHub issue. Execute all 7 stages in order. If any stage fails, run the Error Handler.

Read .claude/pipeline-config.json first:

cat .claude/pipeline-config.json

Store: REPO, PROJECT_ID, STATUS_FIELD_ID, and all statusOptions IDs (inProgress, inReview, ready, blocked).

Then fetch the issue:

gh issue view <issue_number> --repo "$REPO" --json title,body

Store: ISSUE_TITLE, ISSUE_BODY.

---

Stage 1: Setup Workspace

Invoke pitcrew:setup-workspace passing: issue_number, issue_title, repo, project_id, status_field_id, col_in_progress=statusOptions.inProgress, label=labels.trigger.

Store returned WORKTREE and BRANCH.

---

Stage 2: Plan

Invoke pitcrew:plan passing: issue_number, worktree_path=WORKTREE, repo.

After this stage, <WORKTREE>/brief.json exists with acceptance_criteria and specialist_assignments.

---

Stage 3: Implement

Read brief.json from the worktree:

cat <WORKTREE>/brief.json

Extract specialist_assignments. Dispatch specialists in this order:

3a: Database Engineer (if assigned)

If specialist_assignments.database-engineer is present, dispatch a pitcrew:database-engineer subagent:

Acceptance criteria:
<acceptance_criteria from brief.json, one per line>

Your task:
<specialist_assignments.database-engineer>

Worktree: <WORKTREE>
Codebase context: Read <WORKTREE>/CLAUDE.md and <WORKTREE>/.claude/rules/database.md before starting.

Run `npm run verify` from <WORKTREE> before stopping. Self-verify until green.
Report: DONE | DONE_WITH_CONCERNS | BLOCKED

Wait for the database engineer to complete before proceeding. The schema must exist before backend/frontend can use it.

3b: Backend Dev + Frontend Dev (if assigned, run in parallel)

Dispatch pitcrew:backend-dev and pitcrew:frontend-dev simultaneously (as parallel subagents) for whichever are assigned in specialist_assignments:

Backend prompt:

Acceptance criteria:
<acceptance_criteria>

Your task:
<specialist_assignments.backend-dev>

Worktree: <WORKTREE>
Codebase context: Read <WORKTREE>/CLAUDE.md and <WORKTREE>/.claude/rules/api.md before starting.

Run `npm run verify` from <WORKTREE> before stopping. Self-verify until green.
Report: DONE | DONE_WITH_CONCERNS | BLOCKED

Frontend prompt:

Acceptance criteria:
<acceptance_criteria>

Your task:
<specialist_assignments.frontend-dev>

Worktree: <WORKTREE>
Codebase context: Read <WORKTREE>/CLAUDE.md and <WORKTREE>/.claude/rules/design-system.md before starting.
Figma MCP: Available if the issue includes a Figma frame URL. Use get_design_context to pull the spec.

Run `npm run verify` from <WORKTREE> before stopping. Self-verify until green.
Report: DONE | DONE_WITH_CONCERNS | BLOCKED

Wait for both to complete.

3c: Handle Specialist Results

If any specialist reports BLOCKED: route to Error Handler with stage "implement". If any specialist reports DONE_WITH_CONCERNS: note the concerns, but continue.

Post one implement comment:

gh issue comment <issue_number> --repo "$REPO" \
  --body "## 🔧 Implementation Complete

Specialists dispatched:
<list which specialists ran>

All self-verified green. Proceeding to acceptance criterion verification."

---

Stage 4: Verify

Invoke pitcrew:verify passing: issue_number, worktree_path=WORKTREE, repo.

If verify reports VERIFY_FAILED after 2 rounds: route to Error Handler with stage "verify".

---

Stage 5: Test

Invoke pitcrew:test passing: issue_number, worktree_path=WORKTREE, repo.

If test reports TEST_BLOCKED: route to Error Handler with stage "test".

---

Stage 6: Review Loop

Invoke pitcrew:review-loop passing: issue_number, worktree_path=WORKTREE, repo, branch=BRANCH, max_iterations=5.

---

Stage 7: Finalize

Invoke pitcrew:finalize passing: issue_number, worktree_path=WORKTREE, repo, project_id, status_field_id, col_in_review=statusOptions.inReview.

---

Error Handler

Call this if any stage fails or a specialist is BLOCKED.

Inputs: failed_stage (string), error_summary (string).

Derive BRANCH if not already known:

BRANCH = "pitcrew/<issue_number>-<slugify(ISSUE_TITLE)>"

1. Add pitcrew-failed label:

gh issue edit <issue_number> --repo "$REPO" --add-label "pitcrew-failed"

2. Move board to Blocked:

ITEM_ID=<look up via GraphQL as in setup-workspace>
gh project item-edit \
  --project-id "$PROJECT_ID" \
  --id "$ITEM_ID" \
  --field-id "$STATUS_FIELD_ID" \
  --single-select-option-id <statusOptions.blocked>

3. Post error comment:

gh issue comment <issue_number> --repo "$REPO" \
  --body "❌ **Pit Crew failed at stage: <failed_stage>**

<error_summary>

Branch (if created): \`$BRANCH\`
Log: \`.pipeline/runs/issue-<issue_number>.log\`

Fix the issue and re-label \`pitcrew-ready\` to retry.

🏁 Pit Crew"

4. Clean up worktree if no PR was opened:

PR_EXISTS=$(gh pr list --repo "$REPO" --head "$BRANCH" --state open 2>/dev/null | head -1)
if [ -z "$PR_EXISTS" ]; then
  git worktree remove --force "../worktrees/pitcrew-<issue_number>" 2>/dev/null || true
  git branch -D "$BRANCH" 2>/dev/null || true
fi
rm -f .pipeline/.active-worktree

5. Print: "Pipeline failed for issue #<issue_number> at stage: <failed_stage>."

---