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 # shared repo
git worktree add $HOME/work-<branch> <branch> # create local worktree
cd $HOME/work-<branch> # work here
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> # optional, per 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
1---2name: vibecoding-general-swarm3description: 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.4---56# Vibecoding General — Multi-Agent Coding Orchestration78Design-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.910## Core Principles11121. **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.132. **Spec fidelity.** Subagents implement SPEC.md faithfully — exact interfaces, exact module boundaries, exact data formats. No unilateral changes.143. **Main agent owns init, merge, integration.** Subagents implement and commit on their branches.154. **Parallelism by modules & features.** Each subagent owns one or more modules/features. Group related work into one agent to minimize cross-agent dependencies.165. **Git worktrees isolate work.** Each subagent works in its own git worktree to avoid conflicts. The shared repo is the coordination hub.176. **Interface contracts are sacred.** Define function signatures, data schemas, and file formats in the spec. Subagents implement to these contracts so modules integrate cleanly.187. **Test before merge.** Each subagent runs tests for their module before committing. Main agent runs integration tests after merge.1920## Mode Selection2122| Condition | Mode |23|-----------|------|24| Task has 3+ distinct modules or components | **Mode A** (multi-agent) |25| Task involves both infrastructure and application logic | **Mode A** (multi-agent) |26| Task is a full system (API + workers + data pipeline, etc.) | **Mode A** (multi-agent) |27| Task is a single script, tool, or focused feature | **Mode B** (single agent) |28| Task is a bug fix or small enhancement | **Mode B** (single agent) |29| When in doubt | **Mode B** (single agent) |3031---3233## Worktree Reference3435Git worktrees allow multiple agents to work on the same repo simultaneously without conflicts.3637### Setup (each subagent)38```bash39cd /mnt/agents/output/project # shared repo40git worktree add $HOME/work-<branch> <branch> # create local worktree41cd $HOME/work-<branch> # work here42```4344### Rules45- Each subagent MUST use a unique worktree path (`$HOME/work-<branch>`).46- **Never run `git worktree prune`** — it destroys other agents' worktree entries.47- Never work directly in `/mnt/agents/output/project` — always use a worktree.48- After committing in a worktree, the main agent merges from the shared repo.4950### Cleanup (main agent, after all merges complete)51```bash52cd /mnt/agents/output/project53git worktree remove $HOME/work-<branch> # optional, per branch54```5556---5758## File Layout5960```61/mnt/agents/output/62├── SPEC.md # Project specification (single source of truth)63├── info.md # Research findings (if applicable)64├── project/ # Shared git repo (coordination hub)65│ ├── .git/66│ └── ... # Project structure per SPEC.md67│68$HOME/work-<branch>/ # Local worktree (unique per subagent)69└── ... # Same structure, isolated working copy70```
serejaris