Parallel Agents

Multi-Agent Orchestration

Platform-adaptive parallel agent coordination

Overview

This skill enables coordinating multiple specialized agents across different AI platforms. It automatically detects the runtime environment and selects the best orchestration strategy:

Platform Detection

Before orchestrating, detect the current platform:

IF environment has CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  → Use Agent Teams (Strategy A)
ELSE IF environment is Claude Code (has Task tool, /agents command)
  → Use Subagents (Strategy B)
ELSE IF environment is Kiro IDE (.kiro/, POWER.md, autonomous agent available)
  → Use Autonomous Agent (Strategy D)
ELSE
  → Use Sequential Personas (Strategy C)

Important: Always announce which strategy is being used so the user knows what to expect.

Strategy A: Claude Code Agent Teams (Preferred)

Requires: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings or environment.

Agent Teams spawn true parallel Claude Code sessions as teammates. Each teammate runs in its own context with full tool access.

Enabling Agent Teams

Users must enable via settings.json or environment:

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

How to Orchestrate with Agent Teams

The lead agent (you) acts as Team Leader. When a complex multi-domain task is detected:

1. Analyze the task and identify independent work streams
2. Spawn teammates with clear, self-contained prompts
3. Assign tasks to each teammate
4. Monitor progress and steer if needed
5. Synthesize results when teammates complete

Spawn a Team

Create an agent team with 3 teammates:
- "security-reviewer": Review the auth module at src/auth/ for security vulnerabilities. Focus on token handling and session management.
- "api-specialist": Analyze the API layer at src/api/ for best practices, error handling, and performance.
- "test-engineer": Identify test gaps across the project, focus on untested edge cases.

Use Sonnet for each teammate.

Team Display Modes

{ "teammateMode": "in-process" }

Team Communication

• Message teammate: Tell the lead to message a specific teammate
• Broadcast: Send to all teammates (use sparingly — costs scale)
• Task list: Shared task board visible to all agents (Ctrl+T)
• Idle notifications: Teammates auto-notify lead when done

Quality Gates via Hooks

{
  "hooks": {
    "TeammateIdle": [
      { "command": "npm test", "description": "Run tests before idle" }
    ],
    "TaskCompleted": [
      { "command": "./scripts/lint.sh", "description": "Lint on completion" }
    ]
  }
}

Cleanup

Clean up the team

Agent Teams Best Practices

1. Give enough context — teammates don't share the lead's full conversation
2. Size tasks well — not too small (overhead), not too large (risk)
3. Avoid file conflicts — assign non-overlapping file sets to each teammate
4. Wait before synthesizing — let all teammates finish before combining results
5. Start with research — use research/review tasks before implementation tasks

Strategy B: Claude Code Subagents (Fallback on Claude Code)

When Agent Teams aren't enabled on Claude Code, use subagents for parallel work.

Subagents are isolated Claude Code sessions spawned via the Task tool. They can run in foreground (blocking) or background (concurrent).

Built-in Subagents

Custom Subagents

Define in .claude/agents/ or ~/.claude/agents/:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: acceptEdits
skills:
  - vulnerability-scanner
memory: project
---

You are a security reviewer. Analyze code for vulnerabilities, focusing on:

- Authentication and authorization flaws
- Input validation issues
- Secret exposure risks
- Dependency vulnerabilities

Report with severity ratings. Check your memory for patterns seen before.

Subagent Frontmatter Reference

Invoking Subagents

Foreground (blocking):

Use the security-reviewer subagent to audit the authentication module

Background (concurrent):

Run the security-reviewer subagent in the background to audit auth while I continue working

Parallel research:

Research the authentication, database, and API modules in parallel using separate subagents

Chaining:

Use the code-reviewer subagent to find issues, then use the optimizer subagent to fix them

Restricting Subagent Spawning

A coordinator can restrict which subagents it spawns:

---
name: coordinator
description: Coordinates work across specialized agents
tools: Task(worker, researcher), Read, Bash
---

This coordinator can only spawn worker and researcher subagents.

Strategy C: Sequential Personas (Universal Fallback)

For Gemini, Opencode, and other platforms without native agent parallelism.

How It Works

The AI adopts different specialist personas sequentially, passing context between phases:

🤖 Applying knowledge of @security-auditor...
[Security analysis]

🤖 Applying knowledge of @backend-specialist...
[API analysis, informed by security findings]

🤖 Applying knowledge of @test-engineer...
[Test gap analysis, informed by both previous analyses]

Native Agent Invocation

Single Agent:

Use the security-auditor agent to review authentication

Sequential Chain:

First, use the explorer-agent to discover project structure.
Then, use the backend-specialist to review API endpoints.
Finally, use the test-engineer to identify test gaps.

With Context Passing:

Use the frontend-specialist to analyze React components.
Based on those findings, have the test-engineer generate component tests.

Strategy D: Kiro Autonomous Agent (On Kiro IDE)

Kiro's Autonomous Agent provides async parallel task execution in sandboxed environments — the team-level equivalent of Claude Code's Agent Teams, but asynchronous and PR-based.

How It Works

Unlike Claude Code Agent Teams (which are real-time interactive sessions), Kiro's Autonomous Agent:

• Runs tasks in isolated sandbox environments — full dev setup, no local impact
• Opens pull requests for each completed task — you review asynchronously
• Maintains context across tasks, repos, and PRs
• Learns from your code reviews — adapts to team patterns over time
• Works across multiple repos — coordinates related changes into linked PRs

When to Use

✅ Best for:

• Async workflows where multiple tasks can run overnight or during focus time
• Cross-repo changes (e.g., update API contract + client SDK + documentation)
• Routine fixes, follow-ups, and status updates
• Tasks that benefit from sandboxed execution (no risk to local environment)

❌ Not ideal for:

• Real-time interactive collaboration (use Agent Teams on Claude Code instead)
• Quick single-file fixes (use direct agent invocation)

Example: Multi-Task Delegation

Create a Kiro task:
  - "Refactor authentication module to use JWT refresh tokens"
  - Repository: backend-api
  - Let Kiro plan the implementation, execute in sandbox, and open a PR

Create another Kiro task:
  - "Update the React login flow to handle JWT refresh"
  - Repository: frontend-app
  - Reference the backend PR for API contract changes

Both tasks run in parallel in isolated environments. When complete, you get two linked PRs to review.

Integration with Kiro Powers

The Autonomous Agent automatically uses installed Powers for expertise. If the Supabase Power is installed and the task involves database changes, the agent activates the Supabase Power for best-practice guidance.

Orchestration Patterns (Platform-Independent)

These patterns work across all strategies. The platform dictates whether they run in parallel or sequentially.

Pattern 1: Comprehensive Analysis

Agents: explorer → [domain-agents] → synthesis

1. explorer-agent: Map codebase structure
2. security-auditor: Security posture
3. backend-specialist: API quality
4. frontend-specialist: UI/UX patterns
5. test-engineer: Test coverage
6. Synthesize all findings

On Claude Code Agent Teams: Steps 2-5 run as parallel teammates On Claude Code Subagents: Steps 2-5 run as background subagents On Kiro IDE: Steps 2-5 dispatched as autonomous agent tasks (async, PR-based) On Other Platforms: Steps 1-5 run sequentially with context passing

Pattern 2: Feature Review

Agents: affected-domain-agents → test-engineer

1. Identify affected domains (backend? frontend? both?)
2. Invoke relevant domain agents
3. test-engineer verifies changes
4. Synthesize recommendations

Pattern 3: Security Audit

Agents: security-auditor → penetration-tester → synthesis

1. security-auditor: Configuration and code review
2. penetration-tester: Active vulnerability testing
3. Synthesize with prioritized remediation

Pattern 4: Cross-Layer Feature Implementation

Agents: database-architect → backend-specialist → frontend-specialist → test-engineer

1. database-architect: Schema changes
2. backend-specialist: API endpoints
3. frontend-specialist: UI components
4. test-engineer: Full-stack tests

On Agent Teams: Split into backend teammate + frontend teammate + test teammate

Available Agents

Synthesis Protocol

After all agents/teammates complete, synthesize:

## Orchestration Synthesis

### Task Summary

[What was accomplished]

### Strategy Used

[Agent Teams / Subagents / Sequential — and why]

### Agent Contributions

| Agent              | Finding      |
| ------------------ | ------------ |
| security-auditor   | Found X      |
| backend-specialist | Identified Y |

### Consolidated Recommendations

1. **Critical**: [Issue from Agent A]
2. **Important**: [Issue from Agent B]
3. **Nice-to-have**: [Enhancement from Agent C]

### Action Items

- [ ] Fix critical security issue
- [ ] Refactor API endpoint
- [ ] Add missing tests

Best Practices

1. Platform-first — Always use the highest-capability strategy available
2. Announce strategy — Tell the user which orchestration mode is being used
3. Logical order — Discovery → Analysis → Implementation → Testing
4. Share context — Pass relevant findings between agents/teammates
5. Single synthesis — One unified report, not separate outputs
6. Verify changes — Always include test-engineer for code modifications
7. Avoid file conflicts — Assign non-overlapping file scopes to parallel agents

Focused Agent Prompt Structure

Adapted from obra/superpowers — applies when dispatching parallel agents for independent problems.

Good agent prompts are:

1. Focused — One clear problem domain
2. Self-contained — All context needed to understand the problem
3. Specific about output — What should the agent return?

[Clear problem description with specific scope]

Context:

- [Error messages, test names, or specific symptoms]
- [Relevant file paths]

Your task:

1. [Specific investigation step]
2. [Root cause analysis]
3. [Fix with constraints]

Constraints:

- [What NOT to change]
- [Scope boundaries]

Return: Summary of what you found and what you fixed.

Common Mistakes

When NOT to Use Parallel Agents

Review and Integrate Protocol

After all agents/teammates complete:

1. Review each summary — Understand what changed
2. Check for conflicts — Did agents edit overlapping code?
3. Run full test suite — Verify all fixes work together
4. Spot check — Agents can make systematic errors
5. Use verification-before-completion — Evidence before claiming success

Integration

AGI Framework Integration

Qdrant Memory Integration

Before executing complex tasks with this skill:

python3 execution/memory_manager.py auto --query "<task summary>"

Decision Tree:

• Cache hit? Use cached response directly — no need to re-process.
• Memory match? Inject context_chunks into your reasoning.
• No match? Proceed normally, then store results:

python3 execution/memory_manager.py store \
  --content "Description of what was decided/solved" \
  --type decision \
  --tags parallel-agents <relevant-tags>

Note: Storing automatically updates both Vector (Qdrant) and Keyword (BM25) indices.

Agent Team Collaboration

• Strategy: This skill communicates via the shared memory system.
• Orchestration: Invoked by orchestrator via intelligent routing.
• Context Sharing: Always read previous agent outputs from memory before starting.

Local LLM Support

When available, use local Ollama models for embedding and lightweight inference:

• Embeddings: nomic-embed-text via Qdrant memory system
• Lightweight analysis: Local models reduce API costs for repetitive patterns