Skip to content

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

parallel-agents

Verified

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

ScenarioModelReason
Build feature (frontend + backend + tests)Parallel or HybridDomains are independent
Debug cross-cutting issueSequentialEach step depends on findings
Security audit (static + dynamic)ParallelAnalyses are independent
Refactor API then update consumersSequentialConsumers depend on new API
Code review from 3 perspectivesParallelReviewers are independent
Full-stack feature with DB migrationHybridSchema 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:

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

output.md format:

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

AgentExpertiseBest Paired With
orchestratorCoordination, planningproject-planner
security-auditorOWASP, auth, vulnerabilitiespenetration-tester
penetration-testerActive security testingsecurity-auditor
backend-specialistAPI, Node.js, Python, DBdatabase-architect
frontend-specialistReact, Next.js, Tailwindperformance-optimizer
test-engineerUnit, E2E, coverageany implementation agent
devops-engineerCI/CD, Docker, deploybackend-specialist
database-architectSchema, migrations, SQLbackend-specialist
mobile-developerReact Native, Fluttertest-engineer
debuggerRoot cause analysisexplorer-agent
explorer-agentCodebase discoveryany agent (recon phase)
documentation-writerDocs, README, API docsonly if explicitly requested
performance-optimizerProfiling, Web Vitalsfrontend-specialist
project-plannerTask breakdown, roadmaporchestrator
seo-specialistSEO, meta, analyticsfrontend-specialist
game-developerUnity, Godot, Phasertest-engineer
product-managerPRD, user storiesproject-planner

Antigravity Built-in Agents

AgentModelPurpose
ExploreHaikuFast read-only codebase search
PlanSonnetResearch during plan mode
General-purposeSonnetComplex multi-step modifications

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


Synthesis Protocol

After all agents complete their work, synthesize:

## 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-PatternProblemCorrect Approach
"First do X, then Y, then Z" for independent tasksWastes time serializing parallel workUse parallel workspaces
Agents sharing context directly in parallelImpossible — parallel agents have isolated workspacesUse _handoff/ artifacts
Spawning 6+ agents for a simple taskOverhead exceeds benefit2-3 agents max for simple tasks
No handoff plan before spawningAgents don't know what to produceWrite plan.md first
Skipping synthesisUser gets fragmented findingsAlways merge into one report

Handoff Artifact Templates (copy-ready)

_handoff/orchestrator/plan.md

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

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

---
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)

# 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: 469kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall