Parallel Work

Run N autonomous agents in parallel, each working on a separate GitHub issue in its own isolated worktree. Each agent creates a branch, implements the task, commits, and opens a PR.

Default: 3 agents. Override with argument: /parallel-work 2 or /parallel-work 5.

Parse the agent count from $ARGUMENTS if provided (extract the number). Default to 3 if not specified or not a number between 1-5.

Step 0: Pre-Flight Check

Before anything else, ensure a clean starting point:

1. Check current branch: If not on main, warn the user. Worktrees branch from HEAD — spawning from a feature branch means agents won't have the latest merged code.
2. Check for uncommitted changes: If the working tree is dirty, offer to stash (git stash -u -m "pre-parallel-work") before switching branches. Always restore the stash after switching.
3. Switch to main and pull: git checkout main && git pull to ensure agents start from the latest code.
4. Restore stash if needed: git stash pop to bring back any uncommitted work.

Only proceed to Step 1 after confirming the user is on an up-to-date main with their changes preserved.

Step 1: Gather Context

Run all of these in parallel:

Open issues

gh issue list --repo Destrayon/Connapse --state open --json number,title,labels,milestone,assignees,createdAt,updatedAt --limit 100

Recent merged PRs (for momentum scoring)

gh pr list --repo Destrayon/Connapse --state merged --json number,title,mergedAt,labels --limit 5

Current git state

git status --short
git branch --show-current

Project board state (filter to Todo only)

gh project item-list 3 --owner Destrayon --format json

Filter the results to items with status == "Todo" only. Exclude items with status "Done" or "In Progress" — those are already being worked on or completed.

Architecture context

Read .claude/state/decisions.md and .claude/state/issues.md for blockers or dependencies.

Step 2: Score and Select

Score each open issue using these criteria (same as /next-task):

Priority Weight

Milestone Urgency

Dependency Readiness

Momentum Bonus

Size Preference

Tiebreaking

When issues have equal scores, break ties in this order:

1. Type priority: bug > enhancement > refactor > test > docs > infrastructure > feature (bugs are more impactful to fix)
2. Issue number: lower number first (older issues should be addressed sooner)

Conflict Detection

After scoring and tiebreaking, select the top N tasks that do NOT share area: labels. The goal is to avoid merge conflicts by ensuring each agent works on a different part of the codebase.

Algorithm:

1. Sort all eligible issues by total score (descending), then by tiebreaker rules
2. Initialize an empty selected list and a taken_areas set
3. Walk through sorted issues:

• Extract this issue's area: labels
• If ANY area overlaps with taken_areas, skip this issue
• Otherwise, add to selected and add its areas to taken_areas
• Issues with NO area: label never conflict (they can always be selected)

1. Stop when selected has N items or no more issues remain

If fewer than N non-conflicting tasks exist, tell the user and proceed with however many were found. If the ONLY way to get N tasks is to allow area overlap, present the conflict and ask the user whether to proceed.

Step 3: Present Selection

Show the selected tasks and ask for confirmation:

## Parallel Work Plan

I've selected {N} non-conflicting tasks to work on simultaneously:

### Agent 1: [Issue Title] (#number)
**Score**: [total] | **Priority**: [P-level] | **Milestone**: [version] | **Size**: [size]
**Area**: [area labels] | **Branch**: [branch name]
**Summary**: [1 sentence from issue body]

### Agent 2: [Issue Title] (#number)
...

### Agent 3: [Issue Title] (#number)
...

**Conflict check**: No overlapping area labels — these tasks touch different parts of the codebase.

Ready to spawn {N} agents? Each will create a branch, implement the task, and open a PR.

Wait for user confirmation before proceeding. If the user wants to swap any task, re-select.

Step 4: Spawn Agents

Once confirmed, spawn all N agents in a SINGLE message using the Agent tool. Each agent MUST use isolation: "worktree" and model: "sonnet".

For each selected task, spawn an Agent with this prompt template (fill in the placeholders):

You are working on GitHub issue #{ISSUE_NUMBER} for the Connapse project.

## Your Task
{ISSUE_TITLE}

## Issue Details
{FULL_ISSUE_BODY from gh issue view}

## Setup Steps

1. Create and switch to branch:

git checkout -b {BRANCH_TYPE}/{ISSUE_NUMBER}-{SHORT_DESCRIPTION}

2. Move the issue to "In Progress" on the project board:

ITEM_ID=$(gh project item-list 3 --owner Destrayon --format json | jq -r '.items[] | select(.content.number == {ISSUE_NUMBER} and .content.repository == "Destrayon/Connapse") | .id') gh project item-edit --project-id PVT_kwHOAldLE84BQszG --id "$ITEM_ID" --field-id PVTSSF_lAHOAldLE84BQszGzg-vn-U --single-select-option-id 47fc9ee4

## Implementation Guidelines

- This is a .NET 9 project using Blazor Server, EF Core, and PostgreSQL
- Follow existing patterns in the codebase — read similar files before writing new code
- Run `dotnet build` after making changes to verify compilation
- Run `dotnet test` if you modified testable logic
- Keep changes focused on THIS issue only — do not fix unrelated things
- PR should be under 300 lines of changes

## Project Structure

src/ ├── Connapse.Web/ # Blazor WebApp (UI + API endpoints) ├── Connapse.Core/ # Domain models, interfaces, shared logic ├── Connapse.Identity/ # Auth: Identity, PAT, JWT, RBAC ├── Connapse.Ingestion/ # Document parsing, chunking, embedding ├── Connapse.Search/ # Vector search, hybrid search, reranking └── Connapse.Storage/ # Vector DB, document store, connectors

## When Done

1. Stage and commit your changes:

git add [specific files] git commit -m "$(cat <<'EOF' {COMMIT_TYPE}: {SHORT_DESCRIPTION}

Closes #{ISSUE_NUMBER}

Co-Authored-By: Claude Sonnet 4.6 <[email protected]> EOF )"

2. Push and create a PR:

git push -u origin {BRANCH_TYPE}/{ISSUE_NUMBER}-{SHORT_DESCRIPTION} gh pr create --title "{PR_TITLE}" --body "$(cat <<'EOF'

Summary

• {BULLET_POINTS}

Test plan

• [ ] dotnet build passes
• [ ] dotnet test passes
• [ ] {SPECIFIC_TEST_STEPS}

Closes #{ISSUE_NUMBER}

🤖 Generated with Claude Code EOF )"

3. Report back with the PR URL.

IMPORTANT: You MUST read the full issue body with gh issue view {NUMBER} BEFORE spawning agents, so you can fill in the prompt template completely. Spawn all agents in a single message for true parallelism.

Step 5: Report Results

As agents complete, collect their results and present a summary:

## Parallel Work Complete

| # | Issue | Branch | PR | Status |
|---|-------|--------|----|--------|
| 1 | #{N} {Title} | `fix/N-desc` | [PR #{X}](url) | Done |
| 2 | #{N} {Title} | `feature/N-desc` | [PR #{X}](url) | Done |
| 3 | #{N} {Title} | `refactor/N-desc` | [PR #{X}](url) | Done |

All PRs are ready for review.

If any agent fails, report what went wrong and suggest next steps (e.g., manual intervention, re-running just that task).

Edge Cases

• Fewer than N eligible tasks: Tell the user how many were found and proceed with that number. Suggest /create-tickets or /discover-work if the board is thin.
• All tasks share areas: Present the conflict and ask the user which combination they prefer, accepting the overlap risk.
• Dirty working tree: Warn the user and suggest committing or stashing before spawning agents. Worktree isolation means the main tree state shouldn't matter, but uncommitted changes won't be in the worktrees.
• Already on a feature branch: Note this — worktrees branch from HEAD, so make sure main is up to date. Suggest git checkout main && git pull first.
• Agent failure: If an agent errors out, the worktree persists with partial work. Report what happened and suggest manual completion or re-running /parallel-work 1 for just that task.
• Rate limits: 3 parallel Sonnet agents is manageable. If running 4-5, warn about potential rate limit pressure.
• Worktree cleanup: After all PRs are merged, remind the user they can clean up leftover worktrees with rm -rf .claude/worktrees/agent-*. Worktrees with no changes are auto-cleaned, but ones with commits persist.