Harness Parallel Agents

Harness Parallel Agents

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

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
• 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:

   {
     "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:

   {
     "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:

{
  "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:

{
  "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