Team

Spawn N coordinated agents working on a shared task list. Uses VS Code's native subagent system for team management, inter-agent messaging, and task dependencies.

When to Use

Task is decomposable into independent subtasks
Multiple files/modules need parallel work
Large-scale refactoring, migration, or multi-service work

When NOT to Use

Single-file changes → use /omg-autopilot or direct editing
Sequential pipeline → use /omg-autopilot
Just need a plan → use /plan or /ralplan

Usage

/team 3:executor "fix all TypeScript errors"
/team 4:designer "implement responsive layouts"
/team "refactor the auth module"
/team ralph "build a complete REST API"

Parameters

N — Number of agents (1-20). Defaults to auto-sizing.
agent-type — Agent for team-exec stage (executor, debugger, designer, etc.). Defaults to stage-aware routing.
ralph — Wraps team in Ralph's persistence loop (retry on failure, verification before completion).
task — High-level task to decompose and distribute.

Architecture

User: "/team 3:executor fix all TypeScript errors"
              |
              v
      [omg-coordinator (Lead)]
              |
              +-- Analyze & decompose → subtask list
              |
              +-- Create tasks with dependencies
              |
              +-- Spawn N worker agents (subagents)
              |
              +-- Monitor loop (messages + task polling)
              |
              +-- Completion → shutdown workers → cleanup

Staged Pipeline

team-plan → team-prd → team-exec → team-verify → team-fix (loop)

Stage Agent Routing

Each stage uses specialized agents — not just executors:

Stage	Required Agents	Optional Agents
team-plan	@explore, @planner	@analyst, @architect
team-prd	@analyst	@critic
team-exec	@executor	@debugger, @designer, @writer, @test-engineer
team-verify	@verifier	@test-engineer, @security-reviewer, @code-reviewer
team-fix	@executor	@debugger

Routing rules:

Lead picks agents per stage, not the user. User's N:agent-type only overrides team-exec workers.
Specialist agents complement executors. Route analysis to @architect, UI to @designer.
Security-sensitive or >20 file changes must include @security-reviewer + @code-reviewer in team-verify.

Stage Entry/Exit Criteria

team-plan: Entry = invocation. Exit = task graph ready.
team-prd: Entry = scope ambiguous. Exit = acceptance criteria explicit.
team-exec: Entry = tasks created + workers spawned. Exit = tasks reach terminal state.
team-verify: Entry = execution pass done. Exit (pass) = gates pass. Exit (fail) = fix tasks generated.
team-fix: Entry = defects found. Exit = fixes done, return to team-verify.

Verify/Fix Loop

Continue team-exec → team-verify → team-fix until:

Verification passes with no required fixes, or
Max fix attempts exceeded (default: 3) → terminal failed

Workflow

Phase 1: Parse Input

Extract N (agent count, validate 1-20)
Extract agent-type
Extract task description
Check for ralph modifier

Phase 2: Analyze & Decompose

Use @explore or @architect to analyze the codebase and break the task into N subtasks:

Each subtask should be file-scoped or module-scoped
Subtasks must be independent or have clear dependencies
Each needs a concise subject and detailed description

Phase 3: Create Team

Write team state via omg_write_state:

{
  "mode": "team",
  "active": true,
  "team_name": "fix-ts-errors",
  "agent_count": 3,
  "current_phase": "team-plan",
  "task": "fix all TypeScript errors"
}

Phase 4: Create Tasks

Create subtasks with dependencies. Pre-assign owners to avoid race conditions.

Phase 5: Spawn Workers

Spawn N subagents in parallel using the agents field references:

Each worker gets team preamble + assigned tasks
Workers execute independently and report back

Phase 6: Monitor

Monitor via two channels:

Inbound messages — workers report completion or need help
Task polling — check overall progress periodically

Coordination actions:

Unblock a worker with guidance
Reassign work if a worker finishes early
Handle failures — reassign or spawn replacement

Watchdog policy:

Task stuck >5 min without messages → send status check
No messages >10 min → reassign task
Worker fails 2+ tasks → stop assigning to it

Phase 7: Stage Transitions

Update state on every stage transition via omg_write_state.

Phase 8: Completion

Signal shutdown to all workers
Wait for responses (15s timeout)
Clean up team resources and state
Report summary

Stage Handoff Convention

Each stage produces a handoff document before transitioning:

## Handoff: <current-stage> → <next-stage>
- **Decided**: [key decisions]
- **Rejected**: [alternatives and why]
- **Risks**: [identified risks]
- **Files**: [key files modified]
- **Remaining**: [items for next stage]

Handoffs saved to .omc/handoffs/<stage-name>.md. Survive cancellation for resume.

Team + Ralph Composition

When ralph modifier is present:

Ralph creates PRD with stories
Each story executed as a team pipeline
Team verify/fix loop satisfies story acceptance criteria
Ralph verifies story completion
Next story begins

State Tracking

Track in .omc/state/team-state.json via omg_write_state/omg_read_state.

Resume and Cancel

Resume: Restart from last non-terminal stage using state + handoffs
Cancel: /cancel → graceful shutdown → cleanup → state preserved/cleared per policy

team