jmagly/parallel-dispatch

parallel-dispatch

Generic parallel agent orchestration utility for launching multiple agents concurrently.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "fan out" → parallel agent dispatch shorthand
• "run all [N] in parallel" → explicit parallel execution

Purpose

This skill provides the foundational infrastructure for launching multiple agents in parallel, collecting their results, and handling timeouts. It is used by higher-level skills like artifact-orchestration, review-synthesis, and gate-evaluation.

Behavior

When triggered, this skill:

1. Parses agent configuration:

   • Agent names (from built-in or custom)
   • Prompt templates for each agent
   • Shared context/artifact reference
   • Timeout settings

2. Prepares agent-specific prompts:

   • Loads prompt template per agent
   • Injects shared context (artifact path, requirements)
   • Adds output format requirements

3. Launches agents in parallel:

   • Uses single message with multiple Task tool calls
   • Each agent runs independently
   • No inter-agent communication during execution

4. Collects results:

   • Waits for all agents or timeout
   • Captures success/failure per agent
   • Structures results for downstream processing

5. Returns consolidated results:

   • Per-agent output
   • Execution metadata (duration, status)
   • Aggregated insights (if configured)

Configuration Format

dispatch:
  name: "artifact-review"
  timeout: 300  # seconds

  agents:
    - name: security-architect
      prompt: |
        Review the artifact at {artifact_path} for security concerns.
        Focus on: authentication, authorization, data protection, input validation.
        Output format: structured findings with severity ratings.

    - name: test-architect
      prompt: |
        Review the artifact at {artifact_path} for testability.
        Focus on: test coverage gaps, edge cases, integration points.
        Output format: test recommendations with priority.

    - name: requirements-analyst
      prompt: |
        Review the artifact at {artifact_path} for requirements traceability.
        Focus on: requirement coverage, gaps, conflicts.
        Output format: traceability assessment.

  context:
    artifact_path: ".aiwg/architecture/sad.md"
    requirements_path: ".aiwg/requirements/"

  result_format: structured  # or 'raw'
  aggregate: true  # combine findings

Usage Examples

Basic Parallel Review

User: "Launch parallel review of the SAD by security-architect, test-architect, and requirements-analyst"

Skill executes:
1. Loads SAD from .aiwg/architecture/
2. Prepares review prompts for each agent
3. Dispatches all three agents in single message
4. Collects reviews (timeout: 5 min)
5. Returns structured results

Custom Agent Configuration

User: "Dispatch agents with config from .aiwg/config/review-config.yaml"

Skill executes:
1. Loads configuration file
2. Validates agent names exist
3. Prepares prompts from templates
4. Dispatches with configured timeout
5. Returns results in configured format

Result Format

Structured Results

{
  "dispatch_id": "review-20251208-143022",
  "status": "completed",
  "duration_seconds": 127,
  "agents": {
    "security-architect": {
      "status": "success",
      "duration": 45,
      "output": {
        "findings": [...],
        "severity_summary": {...},
        "recommendations": [...]
      }
    },
    "test-architect": {
      "status": "success",
      "duration": 52,
      "output": {
        "coverage_gaps": [...],
        "test_recommendations": [...],
        "priority_order": [...]
      }
    },
    "requirements-analyst": {
      "status": "success",
      "duration": 38,
      "output": {
        "traced_requirements": [...],
        "gaps": [...],
        "conflicts": [...]
      }
    }
  },
  "aggregate": {
    "total_findings": 12,
    "critical_issues": 2,
    "recommendations": 8
  }
}

Raw Results

{
  "dispatch_id": "review-20251208-143022",
  "agents": {
    "security-architect": "Full text output from agent...",
    "test-architect": "Full text output from agent...",
    "requirements-analyst": "Full text output from agent..."
  }
}

Error Handling

Timeout Handling

timeout_behavior:
  action: "partial"  # or "fail"
  # partial: return results from completed agents
  # fail: return error if any agent times out

Agent Failure

failure_behavior:
  action: "continue"  # or "abort"
  # continue: proceed with other agents
  # abort: stop all if one fails
  retry: 1  # retry failed agents once

Built-in Agent Groups

For convenience, common agent combinations are pre-defined:

Architecture Review Group

group: architecture-review
agents:
  - security-architect
  - test-architect
  - requirements-analyst
  - technical-writer

Security Review Group

group: security-review
agents:
  - security-architect
  - security-auditor
  - privacy-officer

Documentation Review Group

group: documentation-review
agents:
  - technical-writer
  - requirements-analyst
  - domain-expert

Marketing Review Group

group: marketing-review
agents:
  - brand-guardian
  - legal-reviewer
  - quality-controller
  - accessibility-checker

Integration

This skill is the foundation for:

• artifact-orchestration (SDLC)
• gate-evaluation (SDLC)
• review-synthesis (MMK)
• brand-compliance (MMK)

CLI Usage

# Using Python script
python parallel_dispatcher.py --config review-config.yaml

# With inline agents
python parallel_dispatcher.py \
  --agents "security-architect,test-architect" \
  --artifact ".aiwg/architecture/sad.md" \
  --timeout 300

# List available groups
python parallel_dispatcher.py --list-groups

# Validate configuration
python parallel_dispatcher.py --config review-config.yaml --validate

Performance Considerations

• Optimal parallelism: 3-5 agents per dispatch
• Timeout guidance: 2-5 minutes for document review
• Memory: Each agent has isolated context
• Cost: Parallel execution uses more tokens but reduces wall-clock time

References

• Agent definitions: Framework agents/ directories
• Configuration schema: schemas/dispatch-config.schema.json
• Result schema: schemas/dispatch-result.schema.json