jmstar85/oh-my-githubcopilot/team

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:

Routing rules:

1. Lead picks agents per stage, not the user. User's N:agent-type only overrides team-exec workers.
2. Specialist agents complement executors. Route analysis to @architect, UI to @designer.
3. 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:

1. Verification passes with no required fixes, or
2. 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:

1. Inbound messages — workers report completion or need help
2. 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

1. Signal shutdown to all workers
2. Wait for responses (15s timeout)
3. Clean up team resources and state
4. 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 .omg/handoffs/<stage-name>.md. Survive cancellation for resume.

Team + Ralph Composition

When ralph modifier is present:

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

State Tracking

Track in .omg/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