| name | vibecoding-general-swarm |
| description | General-purpose coding orchestration. MANDATORY for ANY coding task not covered by vibecoding-webapp-swarm. Skip ONLY if the task matches vibecoding-webapp-swarm or is entirely non-coding.
|
Vibecoding General — Multi-Agent Coding Orchestration
Design-first, multi-agent workflow for building general software projects. Covers Python tools, data pipelines, ML systems, APIs, games, bots, CLI apps, mobile apps, and any non-frontend coding task.
Core Principles
- Spec-first. A specification document (
SPEC.md) is written before any implementation. It is the single source of truth for architecture, modules, interfaces, and data flow.
- Spec fidelity. Subagents implement SPEC.md faithfully — exact interfaces, exact module boundaries, exact data formats. No unilateral changes.
- Main agent owns init, merge, integration. Subagents implement and commit on their branches.
- Parallelism by modules & features. Each subagent owns one or more modules/features. Group related work into one agent to minimize cross-agent dependencies.
- Git worktrees isolate work. Each subagent works in its own git worktree to avoid conflicts. The shared repo is the coordination hub.
- Interface contracts are sacred. Define function signatures, data schemas, and file formats in the spec. Subagents implement to these contracts so modules integrate cleanly.
- Test before merge. Each subagent runs tests for their module before committing. Main agent runs integration tests after merge.
Mode Selection
| Condition | Mode |
|---|
| Task has 3+ distinct modules or components | Mode A (multi-agent) |
| Task involves both infrastructure and application logic | Mode A (multi-agent) |
| Task is a full system (API + workers + data pipeline, etc.) | Mode A (multi-agent) |
| Task is a single script, tool, or focused feature | Mode B (single agent) |
| Task is a bug fix or small enhancement | Mode B (single agent) |
| When in doubt | Mode B (single agent) |
Worktree Reference
Git worktrees allow multiple agents to work on the same repo simultaneously without conflicts.
Setup (each subagent)
cd /mnt/agents/output/project
git worktree add $HOME/work-<branch> <branch>
cd $HOME/work-<branch>
Rules
- Each subagent MUST use a unique worktree path (
$HOME/work-<branch>).
- Never run
git worktree prune — it destroys other agents' worktree entries.
- Never work directly in
/mnt/agents/output/project — always use a worktree.
- After committing in a worktree, the main agent merges from the shared repo.
Cleanup (main agent, after all merges complete)
cd /mnt/agents/output/project
git worktree remove $HOME/work-<branch>
File Layout
/mnt/agents/output/
├── SPEC.md # Project specification (single source of truth)
├── info.md # Research findings (if applicable)
├── project/ # Shared git repo (coordination hub)
│ ├── .git/
│ └── ... # Project structure per SPEC.md
│
$HOME/work-<branch>/ # Local worktree (unique per subagent)
└── ... # Same structure, isolated working copy
