Harness Parallel Agents

# Harness Parallel Agents

> Dispatch independent tasks to concurrent agents, integrate results, and verify no conflicts. Only for truly independent problems.

**Invoked automatically by `harness-autopilot` (and standalone `harness-execution`), not only manually.** When a plan's phase has an auto-dispatch wave, the execution loop calls this skill to run that wave. In that mode the caller supplies worktree-per-unit isolation per `docs/guides/agent-worktree-patterns.md` (one worktree per task, sequential commits, squash-merge on integrate) and has already verified independence via `plan_parallelization`; this skill still owns the focused agent briefs (Step 2), concurrent dispatch (Step 3), and integration/verification (Steps 4–5). Manual invocation (a human asking to "work in parallel") continues to work unchanged.

## When to Use

- When 3 or more tasks are truly independent (no shared state, no shared files, different subsystems)
- When tasks involve investigation or implementation in separate parts of the codebase
- When parallel execution would meaningfully reduce wall-clock time
- When a plan has tasks explicitly marked as parallelizable
- When `harness-autopilot`/`harness-execution` reaches an `auto-dispatch` (or confirmed) wave from `plan_parallelization` — this skill is the wave's dispatcher
- NOT when failures across tasks might be related (investigate serially to find the common cause)
- NOT when tasks need full system understanding to complete correctly
- NOT when agents would modify the same files or shared state
- NOT when there are fewer than 3 independent tasks (overhead of coordination outweighs parallelism)
- NOT when the tasks are sequential by nature (each depends on the previous)

## Process

### Step 1: Verify Task Independence

Before dispatching anything in parallel, predict conflicts using `predict_conflicts` (preferred) or `check_task_independence` (fallback):

1. **List the candidate tasks.** Pull from the plan, or identify from the current work. For each task, identify the files it will read and write.

2. **Call `check_task_independence`.** Pass the tasks with their file lists:

   ```json
   {
     "path": "<project-root>",
     "tasks": [
       { "id": "task-a", "files": ["src/module-a/index.ts", "src/module-a/index.test.ts"] },
       { "id": "task-b", "files": ["src/module-b/index.ts", "src/module-b/index.test.ts"] }
     ],
     "depth": 1
   }
   ```

   The tool checks direct file overlap AND transitive dependency overlap (via the knowledge graph when available). It returns:
   - **`pairs`**: Pairwise independence results with overlap details
   - **`groups`**: Safe parallel dispatch groups (connected components of the conflict graph)
   - **`verdict`**: Human-readable summary (e.g., "3 of 4 tasks can run in parallel in 2 groups")
   - **`analysisLevel`**: `"graph-expanded"` (full analysis) or `"file-only"` (graph unavailable)

   **Preferred: Use `predict_conflicts`** for severity-aware analysis with automatic regrouping:

   ```json
   {
     "path": "<project-root>",
     "tasks": [
       { "id": "task-a", "files": ["src/module-a/index.ts", "src/module-a/index.test.ts"] },
       { "id": "task-b", "files": ["src/module-b/index.ts", "src/module-b/index.test.ts"] }
     ],
     "depth": 1
   }
   ```

   The `predict_conflicts` tool extends independence checking with:
   - **`conflicts`**: Severity-classified conflict details with human-readable reasoning
   - **`groups`**: Revised parallel dispatch groups (high-severity conflicts force serialization)
   - **`summary`**: Conflict counts by severity and whether regrouping occurred
   - **`verdict`**: Human-readable summary including severity breakdown

   If `predict_conflicts` is unavailable, fall back to `check_task_independence`.

3. **Act on the result.** Use the returned `groups` for dispatch. Flag any medium-severity conflicts to the coordinator. If high-severity conflicts forced regrouping (`summary.regrouped === true`), log which tasks were serialized and why. If all tasks are in one group, dispatch them all in parallel. If tasks are split across groups, dispatch each group as a separate parallel wave.

4. **When in doubt, run serially.** The cost of a false parallel dispatch (merge conflicts, subtle bugs, wasted work) far exceeds the cost of running serially.

#### Manual Fallback (when MCP tool is unavailable)

If `check_task_independence` is not available, verify independence manually:

1. **Check file overlap.** For each pair of tasks, compare the files they will read and write. Any overlap in WRITE targets means they are NOT independent. Overlap in READ targets is acceptable only if neither task writes to those files.

2. **Check state overlap.** Do any tasks share database tables, configuration files, environment variables, or in-memory state? If yes, they are NOT independent.

3. **Check import graph overlap.** If Task A modifies module X and Task B imports module X, they are NOT independent — Task B's tests may be affected by Task A's changes.

4. **When in doubt, run serially.** Same principle as above.

### Graph-Enhanced Context (when available)

When a knowledge graph exists at `.harness/graph/`, `check_task_independence` automatically uses it for transitive dependency analysis (this is the `"graph-expanded"` analysis level). No manual graph queries are needed for independence checking.

For custom queries beyond independence checking, these tools remain available:

- `query_graph` — get the dependency subgraph for a specific module or file
- `get_impact` — assess the impact radius of changes to a specific module

When no graph is available, `check_task_independence` falls back to file-only overlap detection and flags `analysisLevel: "file-only"` so you know transitive dependencies were not checked.

### Step 2: Create Focused Agent Tasks

For each independent task, write a focused agent brief:

1. **Scope.** Exactly what files and directories this agent may touch. Be explicit about boundaries — the agent should not explore outside its scope.

2. **Goal.** One sentence: what is the observable outcome when this agent is done?

3. **Constraints.** What the agent must NOT do:
   - Do not modify files outside your scope
   - Do not install new dependencies without approval
   - Do not change shared configuration
   - Run `harness validate` before your final commit

4. **Expected output.** What the agent should produce:
   - Commit(s) on the current branch
   - Test results (all pass)
   - Summary of what was done and any surprises

5. **Context.** Give each agent the minimum context it needs. Include relevant file paths, type definitions it will use, and API contracts it must respect. Do not dump the entire codebase context — focused agents work better with focused context.

### Step 3: Dispatch Concurrently

1. **Launch agents in parallel.** Use subagent dispatch (TaskCreate or platform-specific parallel execution).

2. **Do not intervene while agents are running** unless one reports a blocker. Let them complete independently.

3. **Collect results.** Wait for all agents to finish. Gather their outputs: commits, test results, and summaries.

### Step 4: Integrate Results

1. **Check for conflicts.** Even with verified independence, unexpected conflicts can occur:
   - Git merge conflicts in any file
   - Two agents added the same import or export
   - Test names collide
   - Shared configuration was modified despite constraints

2. **If conflicts exist, resolve them manually.** Do not ask an agent to fix conflicts it does not have full context for. You have the full picture; the agents did not.

3. **Run the FULL test suite.** Not just each agent's tests — the complete project test suite. Parallel changes can cause integration failures that individual test runs miss.

4. **Run `harness validate`.** Verify project-wide health after integration.

5. **If integration fails,** identify which agent's changes caused the failure. Revert that agent's commits, fix the issue serially, and re-integrate.

### Step 5: Verify and Commit

1. **Verify all observable truths** from the plan are satisfied after integration.

2. **If all tests pass and harness validates,** the parallel execution is complete.

3. **Write a summary** of what was parallelized, what each agent produced, and any integration issues that were resolved.

## Harness Integration

- **`harness validate`** — Each agent runs this before its final commit. Run again after integration.
- **`harness check-deps`** — Run after integration to verify no cross-boundary violations were introduced by the combined changes.
- **Agent dispatch** — Use platform-specific parallel execution (e.g., Claude Code subagents via TaskCreate, or separate terminal sessions).
- **Test runner** — Full suite must run after integration, not just individual agent tests.

## Success Criteria

- Independence was verified before dispatch via `check_task_independence` (or manual fallback if tool unavailable)
- Each agent had a focused brief with explicit scope, goal, constraints, and expected output
- All agents completed successfully (or blockers were reported)
- Integration produced no merge conflicts (or conflicts were resolved)
- Full test suite passes after integration
- `harness validate` passes after integration
- No agent modified files outside its declared scope

## Rationalizations to Reject

| Rationalization                                                                              | Why It Is Wrong                                                                                                                                |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| "These two tasks touch different functions in the same file, so they are independent enough" | If both tasks write to the same file, they are NOT independent. Even different functions in the same file creates merge conflicts.             |
| "I verified independence manually -- no need to run check_task_independence"                 | Manual verification misses transitive dependency overlap. check_task_independence with graph-expanded analysis catches transitive conflicts.   |
| "There are only 2 independent tasks, but parallelism would save time"                        | NOT when there are fewer than 3 independent tasks. Coordination overhead outweighs parallelism benefit for 2 tasks.                            |
| "Each agent's tests pass, so integration is fine"                                            | Step 4 requires running the FULL test suite after integration. Parallel changes can cause integration failures that individual test runs miss. |

## Examples

### Example: Parallel Implementation of Three Independent Services

**Context:** Plan has Tasks 4, 5, and 6 which implement UserService, ProductService, and NotificationService. Each service is in its own directory, has its own types, and has no cross-service dependencies.

**Step 1: Verify independence**

Call `check_task_independence`:

```json
{
  "path": ".",
  "tasks": [
    {
      "id": "task-4-user",
      "files": [
        "src/services/user/service.ts",
        "src/services/user/service.test.ts",
        "src/types/user.ts"
      ]
    },
    {
      "id": "task-5-product",
      "files": [
        "src/services/product/service.ts",
        "src/services/product/service.test.ts",
        "src/types/product.ts"
      ]
    },
    {
      "id": "task-6-notification",
      "files": [
        "src/services/notification/service.ts",
        "src/services/notification/service.test.ts",
        "src/types/notification.ts"
      ]
    }
  ]
}
```

Result:

```json
{
  "analysisLevel": "graph-expanded",
  "groups": [["task-4-user", "task-5-product", "task-6-notification"]],
  "verdict": "3 of 3 tasks can run in parallel in 1 group"
}
```

All tasks are independent — safe to parallelize.

**Step 2: Create agent briefs**

```
Agent A — UserService:
  Scope: src/services/user/, src/services/user.test.ts
  Goal: UserService with CRUD operations, all tests passing
  Constraints: Do not modify files outside src/services/user/. Run harness validate.
  Context: User type definition in src/types/user.ts, DB helper in src/utils/db.ts

Agent B — ProductService:
  Scope: src/services/product/, src/services/product.test.ts
  Goal: ProductService with CRUD operations, all tests passing
  Constraints: Do not modify files outside src/services/product/. Run harness validate.
  Context: Product type definition in src/types/product.ts, DB helper in src/utils/db.ts

Agent C — NotificationService:
  Scope: src/services/notification/, src/services/notification.test.ts
  Goal: NotificationService with create and list, all tests passing
  Constraints: Do not modify files outside src/services/notification/. Run harness validate.
  Context: Notification type in src/types/notification.ts, email utility in src/utils/email.ts
```

**Step 3-4: Dispatch, integrate**

```
All 3 agents complete. No merge conflicts.
Run full test suite: 34 tests, all pass.
Run harness validate: passes.
```

### Example: When NOT to Parallelize

**Situation:** Tasks 7 and 8 both modify `src/api/routes/index.ts` to add new route handlers.

```
Task 7: writes src/api/routes/users.ts, MODIFIES src/api/routes/index.ts
Task 8: writes src/api/routes/products.ts, MODIFIES src/api/routes/index.ts

File overlap: BOTH WRITE to src/api/routes/index.ts
Verdict: NOT INDEPENDENT — run serially
```