Skip to content

MustafaKucukcoskun/Refine-agent-kit / .agents/skills/parallel-agents

parallel-agents

Verified

FileKindSize
SKILL.mdskill md12.7 KB
---
name: parallel-agents
description: Multi-agent orchestration with parallel workspaces and artifact-based handoff via _handoff/ directory. Use when 2+ independent tasks can run simultaneously (different domains, no shared state), when comprehensive review needs security + performance + architecture in parallel, or when feature work splits cleanly into backend / frontend / test streams. Keywords: parallel, orchestration, multi-agent, workspaces, handoff, coordinate, simultaneous.
allowed-tools: Read, Glob, Grep
---

# Parallel Agents — Workspace-Based Multi-Agent Orchestration

> Coordinate specialized agents running in parallel workspaces via Antigravity's Agent Manager

## Overview

This skill enables coordinating multiple specialized agents through Antigravity's Agent Manager. Each agent runs in its own isolated workspace. Agents communicate through filesystem artifacts in the `_handoff/` directory, not through shared context.

## When to Use Parallel Orchestration

**Good for:**
- Complex tasks requiring multiple expertise domains simultaneously
- Code analysis from security, performance, and quality perspectives in parallel
- Comprehensive reviews (architecture + security + testing running at the same time)
- Feature implementation where backend + frontend + database work can proceed independently

**Not for:**
- Simple, single-domain tasks (one agent suffices)
- Debugging chains where each step depends on previous findings (use sequential)
- Tasks where agents need real-time access to each other's in-progress work

---

## Execution Models

### Model A: Parallel Workspaces

Agents run simultaneously in isolated workspaces. Best for independent tasks.

```
Agent Manager
  |
  +-- [Workspace 1: frontend-specialist]  -- UI components
  |     reads: _handoff/orchestrator/plan.md
  |     writes: _handoff/frontend-specialist/output.md
  |
  +-- [Workspace 2: backend-specialist]   -- API endpoints
  |     reads: _handoff/orchestrator/plan.md
  |     writes: _handoff/backend-specialist/output.md
  |
  +-- [Workspace 3: test-engineer]        -- test scaffolding
        reads: _handoff/orchestrator/plan.md
        writes: _handoff/test-engineer/output.md
```

**Key characteristics:**
- Each agent has its own workspace (no shared state)
- Communication through `_handoff/` directory artifacts
- All agents can start immediately if inputs are defined upfront
- Best throughput for independent work

### Model B: Sequential Chain

Agents run one at a time, each consuming the previous agent's output. Best for dependent tasks.

```
explorer-agent
  -> findings -> backend-specialist
                   -> changes -> test-engineer
                                   -> verification
```

**Key characteristics:**
- Agents share context within one session
- Direct context passing (no filesystem artifacts needed)
- Each step depends on previous step's output
- Simpler setup but slower for independent tasks

### Model C: Hybrid (Grouped Parallel + Sequential Dependencies)

Mix of parallel groups with sequential gates between them. Best for complex tasks with partial dependencies.

```
Phase 1 (Parallel):
  [database-architect]  -- schema design
  [security-auditor]    -- auth architecture
           |
     Gate: Both complete
           |
Phase 2 (Parallel):
  [backend-specialist]  -- API implementation (uses schema + auth spec)
  [frontend-specialist] -- UI components (uses schema for types)
           |
     Gate: Both complete
           |
Phase 3 (Sequential):
  [test-engineer]       -- integration tests for all new code
```

### Choosing the Right Model

| Scenario | Model | Reason |
| --- | --- | --- |
| Build feature (frontend + backend + tests) | Parallel or Hybrid | Domains are independent |
| Debug cross-cutting issue | Sequential | Each step depends on findings |
| Security audit (static + dynamic) | Parallel | Analyses are independent |
| Refactor API then update consumers | Sequential | Consumers depend on new API |
| Code review from 3 perspectives | Parallel | Reviewers are independent |
| Full-stack feature with DB migration | Hybrid | Schema first, then parallel impl |

---

## Handoff Protocol

When agents run in separate workspaces, they communicate through the `_handoff/` directory.

### Directory Structure

```
_handoff/
  orchestrator/
    plan.md              # Execution plan with agent assignments
    assignments.md       # What each agent should produce
  {agent-name}/
    status.md            # PENDING | IN_PROGRESS | DONE | BLOCKED
    output.md            # Agent's primary deliverable
    issues.md            # Problems, blockers, questions
    artifacts/           # Generated files (schemas, configs, specs)
```

### Writing Handoff Artifacts

**Every agent MUST:**

1. Read `_handoff/orchestrator/plan.md` before starting
2. Write `_handoff/{self}/status.md` with current state
3. Write `_handoff/{self}/output.md` with deliverables
4. Document cross-agent dependencies in output.md

**status.md format:**
```markdown
---
agent: backend-specialist
status: DONE
---
Completed API endpoint implementation.
Blocked by: none
Produces: artifacts/api-spec.json (for test-engineer)
```

**output.md format:**
```markdown
---
agent: backend-specialist
type: implementation
files_changed:
  - src/api/users.ts
  - src/api/auth.ts
---

## Summary
Implemented user API with JWT auth.

## Dependencies for Other Agents
- test-engineer: New endpoints need E2E tests (see artifacts/api-spec.json)
- frontend-specialist: Auth token format in artifacts/auth-contract.md
```

---

## Orchestration Patterns

### Pattern 1: Comprehensive Code Review

**Model:** Parallel Workspaces

```
Spawn 3 workspaces simultaneously:
  [security-auditor]        -- OWASP compliance, auth review
  [performance-optimizer]   -- bottlenecks, N+1, bundle size
  [test-engineer]           -- coverage gaps, flaky tests

Each writes findings to _handoff/{self}/output.md
Orchestrator synthesizes all findings into unified review
```

### Pattern 2: Full-Stack Feature Implementation

**Model:** Hybrid (Grouped Parallel)

```
Phase 1 (Foundation):
  [database-architect]  -- schema + migration
  [security-auditor]    -- auth spec for new feature

Phase 2 (Implementation — after Phase 1):
  [backend-specialist]  -- API endpoints (uses schema)
  [frontend-specialist] -- UI components (uses schema types)

Phase 3 (Verification — after Phase 2):
  [test-engineer]       -- unit + E2E tests
```

### Pattern 3: Security Audit

**Model:** Parallel Workspaces

```
Spawn simultaneously:
  [security-auditor]    -- static analysis, config review, OWASP
  [penetration-tester]  -- active testing, exploit discovery

Both write to _handoff/ -> orchestrator merges into prioritized report
```

### Pattern 4: Bug Investigation

**Model:** Sequential Chain

```
Step 1: explorer-agent  -- map affected code paths
Step 2: debugger        -- root cause analysis (using explorer's map)
Step 3: test-engineer   -- write regression test
Step 4: [domain-agent]  -- implement fix
```

---

## Available Agents (17 Specialist + 3 Built-in)

### Specialist Agents

| Agent | Expertise | Best Paired With |
| --- | --- | --- |
| `orchestrator` | Coordination, planning | project-planner |
| `security-auditor` | OWASP, auth, vulnerabilities | penetration-tester |
| `penetration-tester` | Active security testing | security-auditor |
| `backend-specialist` | API, Node.js, Python, DB | database-architect |
| `frontend-specialist` | React, Next.js, Tailwind | performance-optimizer |
| `test-engineer` | Unit, E2E, coverage | any implementation agent |
| `devops-engineer` | CI/CD, Docker, deploy | backend-specialist |
| `database-architect` | Schema, migrations, SQL | backend-specialist |
| `mobile-developer` | React Native, Flutter | test-engineer |
| `debugger` | Root cause analysis | explorer-agent |
| `explorer-agent` | Codebase discovery | any agent (recon phase) |
| `documentation-writer` | Docs, README, API docs | only if explicitly requested |
| `performance-optimizer` | Profiling, Web Vitals | frontend-specialist |
| `project-planner` | Task breakdown, roadmap | orchestrator |
| `seo-specialist` | SEO, meta, analytics | frontend-specialist |
| `game-developer` | Unity, Godot, Phaser | test-engineer |
| `product-manager` | PRD, user stories | project-planner |

### Antigravity Built-in Agents

| Agent | Model | Purpose |
| --- | --- | --- |
| **Explore** | Haiku | Fast read-only codebase search |
| **Plan** | Sonnet | Research during plan mode |
| **General-purpose** | Sonnet | Complex multi-step modifications |

Use **Explore** for quick searches, **specialist agents** for domain expertise.

---

## Synthesis Protocol

After all agents complete their work, synthesize:

```markdown
## Orchestration Synthesis

### Task Summary
[What was accomplished]

### Execution Model Used
[Parallel / Sequential / Hybrid — and why]

### Agent Contributions
| Agent | Finding / Deliverable | Status |
| --- | --- | --- |
| security-auditor | Found XSS in form handler | DONE |
| backend-specialist | Refactored auth middleware | DONE |
| test-engineer | Added 12 new tests, 94% coverage | DONE |

### 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 (from security-auditor)
- [ ] Refactor API endpoint (from backend-specialist)
- [ ] Add missing E2E tests (from test-engineer)
```

---

## Best Practices

1. **Define outputs before spawning** — Each agent must know what artifacts to produce
2. **Use parallel when tasks are independent** — Don't serialize work that can run simultaneously
3. **Use sequential when tasks have dependencies** — Don't parallelize when order matters
4. **Always include test-engineer** — Any code modification needs verification
5. **Keep handoff artifacts concise** — Agents read each other's output; verbosity wastes tokens
6. **Synthesize into one report** — User gets unified findings, not 5 separate documents

---

## Anti-Patterns

| Anti-Pattern | Problem | Correct Approach |
| --- | --- | --- |
| "First do X, then Y, then Z" for independent tasks | Wastes time serializing parallel work | Use parallel workspaces |
| Agents sharing context directly in parallel | Impossible — parallel agents have isolated workspaces | Use `_handoff/` artifacts |
| Spawning 6+ agents for a simple task | Overhead exceeds benefit | 2-3 agents max for simple tasks |
| No handoff plan before spawning | Agents don't know what to produce | Write plan.md first |
| Skipping synthesis | User gets fragmented findings | Always merge into one report |

---

## Handoff Artifact Templates (copy-ready)

### `_handoff/orchestrator/plan.md`
```markdown
---
orchestrator: true
created: <ISO timestamp>
model: Parallel | Sequential | Hybrid
---

## Goal
<one-paragraph outcome statement>

## Agent Assignments

| Agent | Task | Inputs | Deliverables |
|---|---|---|---|
| frontend-specialist | Build auth UI | design-system/MASTER.md | _handoff/frontend-specialist/output.md |
| backend-specialist | Implement auth API | docs/api-spec.md | _handoff/backend-specialist/output.md |
| test-engineer | E2E auth tests | both outputs above | _handoff/test-engineer/output.md |

## Dependencies
- test-engineer waits for frontend-specialist AND backend-specialist
- others run in parallel

## Success Criteria
- [ ] Each agent's status.md reads DONE
- [ ] Synthesis merges all outputs into final report
```

### `_handoff/<agent-name>/status.md`
```markdown
---
agent: <agent-name>
status: PENDING | IN_PROGRESS | DONE | BLOCKED
updated: <ISO timestamp>
produces_for: [list of dependent agents]
depends_on: [list of prerequisite agents]
blockers: [if BLOCKED, what's blocking; otherwise empty]
---

## Progress
<brief description of what's been done>

## Next
<what this agent will do next, or "complete">
```

### `_handoff/<agent-name>/output.md`
```markdown
---
agent: <agent-name>
complete: true
files_changed: [list]
tests_added: [list]
---

## Summary
<one-paragraph description of deliverable>

## Key Decisions
- Chose X over Y because Z

## Findings for Other Agents
- For test-engineer: endpoints at `/api/auth/*`, happy-path + 3 error cases
- For frontend-specialist: use `/api/auth/me` for session check

## Open Questions
- <anything the synthesizer needs to resolve>
```

### Synthesis Report Template (orchestrator produces)
```markdown
# Synthesis Report — <task name>

## Execution
- Model: Parallel / Sequential / Hybrid
- Agents: [list]
- Duration: <estimate>

## Agent Contributions
| Agent | Status | Key Finding |
|---|---|---|
| ... | DONE | ... |

## Consolidated Findings
1. 🔴 Critical: <if any>
2. 🟡 Important: <if any>
3. 🟢 Enhancement: <if any>

## Action Items
- [ ] Critical item (owner: agent)
- [ ] Important item (owner: agent)

## Overall: PASS | PASS_WITH_WARNINGS | FAIL
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall