team

# Team Skill Spawn N coordinated agents working on a shared task list using OMQ's self-contained file-based team tools (MCP). Team coordination is implemented entirely at the plugin layer via `team_*` MCP tools — no host CLI built-in team support required. **Architecture:** Team lifecycle, task management, and inter-agent messaging use file-based IPC under `.omq/state/team/{teamName}/`. Member spawning uses Qoder CLI's built-in `Agent` tool. All coordination flows through these MCP tools: - `team_create` / `team_delete` — lifecycle - `team_task_create` / `team_task_list` / `team_task_get` / `team_task_update` — shared task list - `team_claim_task` / `team_next_ready_task` / `team_transition_task` / `team_release_claim` — atomic task claim protocol - `team_register_worker` / `team_update_heartbeat` — worker identity and liveness - `team_send_message` / `team_broadcast` / `team_list_mailbox` / `team_mark_message_delivered` — messaging - `team_request_shutdown` / `team_read_shutdown_ack` — graceful shutdown - `team_status` — aggregate status view - `team_reap` — reclaim stale tasks from dead workers The `swarm` compatibility alias was removed in #1131. ## Usage ``` /oh-my-qoder:team N:agent-type "task description" /oh-my-qoder:team "task description" /oh-my-qoder:team ralph "task description" ``` ### Parameters - **N** - Number of teammate agents (1-20). Optional; defaults to auto-sizing based on task decomposition. - **agent-type** - OMQ agent to spawn for the `team-exec` stage (e.g., executor, debugger, designer, codex, gemini). Optional; defaults to stage-aware routing. Use `codex` to spawn Codex CLI workers or `gemini` for Gemini CLI workers (requires respective CLIs installed). See Stage Agent Routing below. - **task** - High-level task to decompose and distribute among teammates - **ralph** - Optional modifier. When present, wraps the team pipeline in Ralph's persistence loop (retry on failure, architect verification before completion). See Team + Ralph Composition below. ### Examples ```bash /team 5:executor "fix all TypeScript errors across the project" /team 3:debugger "fix build errors in src/" /team 4:designer "implement responsive layouts for all page components" /team "refactor the auth module with security review" /team ralph "build a complete REST API for user management" # With Codex CLI workers (requires: npm install -g @openai/codex) /team 2:codex "review architecture and suggest improvements" # With Gemini CLI workers (requires: npm install -g @google/gemini-cli) /team 2:gemini "redesign the UI components" # Mixed: Codex for backend analysis, Gemini for frontend (use /ccg instead for this) ``` ## Architecture ``` User: "/team 3:executor fix all TypeScript errors" | v [TEAM ORCHESTRATOR (Lead)] | +-- team_create("fix-ts-errors") | -> lead becomes team-lead@fix-ts-errors | +-- Analyze & decompose task into subtasks | -> explore/architect produces subtask list | +-- team_task_create x N (one per subtask) | -> tasks #1, #2, #3 with dependencies | +-- Agent(subagent_type="oh-my-qoder:executor", prompt="<worker loop prompt>") x 3 | -> each worker calls team_register_worker on startup | -> each worker loops: team_update_heartbeat → team_next_ready_task → work → team_transition_task | +-- Monitor loop | -> team_status polling for progress + heartbeats | -> team_reap to reclaim stale tasks from dead workers | -> team_send_message to unblock/coordinate | +-- Completion -> team_request_shutdown to each worker <- team_read_shutdown_ack confirms exit -> team_delete("fix-ts-errors") ``` **Storage layout (managed by Qoder CLI):** ``` ~/.qoder/ teams/fix-ts-errors/ config.json # Team metadata + members array tasks/fix-ts-errors/ .lock # File lock for concurrent access 1.json # Subtask #1 2.json # Subtask #2 (may be internal) 3.json # Subtask #3 ... ``` ## Goal Workflow Relationship Team is the OMQ authority for parallel, staged execution. Use the deterministic conflict policies `refuse`, `adopt_existing`, and `artifact_only` rather than non-deterministic warning handling. If a task mentions Qoder CLI `/goal`, Ralph, UltraQA, or artifact-only Ultragoal, keep Team as the primary loop authority unless the leader explicitly hands off. Use `/goal` only as a documented native Qoder CLI handoff target or as visible evidence from the lead session; do not claim the `/goal` evaluator independently runs commands, reads files, or replaces `team-verify` / `team-fix`. Artifact-only Ultragoal references should be treated as durable goal ledger/checkpoint/evidence artifacts, not as worker execution by themselves. ## Staged Pipeline (Canonical Team Runtime) Team execution follows a staged pipeline: `team-plan -> team-prd -> team-exec -> team-verify -> team-fix (loop)` ### Stage Agent Routing Each pipeline stage uses **specialized agents** -- not just executors. The lead selects agents based on the stage and task characteristics. | Stage | Required Agents | Optional Agents | Selection Criteria | | --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **team-plan** | `explore` (haiku), `planner` (opus) | `analyst` (opus), `architect` (opus) | Use `analyst` for unclear requirements. Use `architect` for systems with complex boundaries. | | **team-prd** | `analyst` (opus) | `critic` (opus) | Use `critic` to challenge scope. | | **team-exec** | `executor` (sonnet) | `executor` (opus), `debugger` (sonnet), `designer` (sonnet), `writer` (haiku), `test-engineer` (sonnet) | Match agent to subtask type. Use `executor` (model=opus) for complex autonomous work, `designer` for UI, `debugger` for compilation issues, `writer` for docs, `test-engineer` for test creation. | | **team-verify** | `verifier` (sonnet) | `test-engineer` (sonnet), `security-reviewer` (sonnet), `code-reviewer` (opus) | Always run `verifier`. Add `security-reviewer` for auth/crypto changes. Add `code-reviewer` for >20 files or architectural changes. `code-reviewer` also covers style/formatting checks. | | **team-fix** | `executor` (sonnet) | `debugger` (sonnet), `executor` (opus) | Use `debugger` for type/build errors and regression isolation. Use `executor` (model=opus) for complex multi-file fixes. | **Routing rules:** 1. **The lead picks agents per stage, not the user.** The user's `N:agent-type` parameter only overrides the `team-exec` stage worker type. All other stages use stage-appropriate specialists. 2. **Specialist agents complement executor agents.** Route analysis/review to architect/critic Claude agents and UI work to designer agents. Tmux CLI workers are one-shot and don't participate in team communication. 3. **Cost mode affects model tier.** In downgrade: `opus` agents to `sonnet`, `sonnet` to `haiku` where quality permits. `team-verify` always uses at least `sonnet`. 4. **Risk level escalates review.** Security-sensitive or >20 file changes must include `security-reviewer` + `code-reviewer` (opus) in `team-verify`. ### Stage Entry/Exit Criteria - **team-plan** - Entry: Team invocation is parsed and orchestration starts. - Agents: `explore` scans codebase, `planner` creates task graph, optionally `analyst`/`architect` for complex tasks. - Exit: decomposition is complete and a runnable task graph is prepared. - **team-prd** - Entry: scope is ambiguous or acceptance criteria are missing. - Agents: `analyst` extracts requirements, optionally `critic`. - Exit: acceptance criteria and boundaries are explicit. - **team-exec** - Entry: `team_create`, `team_task_create`, assignment, and worker spawn are complete. - Agents: workers spawned as the appropriate specialist type per subtask (see routing table). - Exit: execution tasks reach terminal state for the current pass. - **team-verify** - Entry: execution pass finishes. - Agents: `verifier` + task-appropriate reviewers (see routing table). - Exit (pass): verification gates pass with no required follow-up. - Exit (fail): fix tasks are generated and control moves to `team-fix`. - **team-fix** - Entry: verification found defects/regressions/incomplete criteria. - Agents: `executor`/`debugger` depending on defect type. - Exit: fixes are complete and flow returns to `team-exec` then `team-verify`. ### Verify/Fix Loop and Stop Conditions Continue `team-exec -> team-verify -> team-fix` until: 1. verification passes and no required fix tasks remain, or 2. work reaches an explicit terminal blocked/failed outcome with evidence. `team-fix` is bounded by max attempts. If fix attempts exceed the configured limit, transition to terminal `failed` (no infinite loop). ### Stage Handoff Convention When transitioning between stages, important context — decisions made, alternatives rejected, risks identified — lives only in the lead's conversation history. If the lead's context compacts or agents restart, this knowledge is lost. **Each completing stage MUST produce a handoff document before transitioning.** The lead writes handoffs to `.omq/handoffs/<stage-name>.md`. #### Handoff Format ```markdown ## Handoff: <current-stage> → <next-stage> - **Decided**: [key decisions made in this stage] - **Rejected**: [alternatives considered and why they were rejected] - **Risks**: [identified risks for the next stage] - **Files**: [key files created or modified] - **Remaining**: [items left for the next stage to handle] ``` #### Handoff Rules 1. **Lead reads previous handoff BEFORE spawning next stage's agents.** The handoff content is included in the next stage's agent spawn prompts, ensuring agents start with full context. 2. **Handoffs accumulate.** The verify stage can read all prior handoffs (plan → prd → exec) for full decision history. 3. **On team cancellation, handoffs survive** in `.omq/handoffs/` for session resume. They are not deleted by `team_delete`. 4. **Handoffs are lightweight.** 10-20 lines max. They capture decisions and rationale, not full specifications (those live in deliverable files like DESIGN.md). #### Example ```markdown ## Handoff: team-plan → team-exec - **Decided**: Microservice architecture with 3 services (auth, api, worker). PostgreSQL for persistence. JWT for auth tokens. - **Rejected**: Monolith (scaling concerns), MongoDB (team expertise is SQL), session cookies (API-first design). - **Risks**: Worker service needs Redis for job queue — not yet provisioned. Auth service has no rate limiting in initial design. - **Files**: DESIGN.md, TEST_STRATEGY.md - **Remaining**: Database migration scripts, CI/CD pipeline config, Redis provisioning. ``` ### Resume and Cancel Semantics - **Resume:** restart from the last non-terminal stage using staged state + live task status. Read `.omq/handoffs/` to recover stage transition context. - **Cancel:** `/oh-my-qoder:cancel` requests teammate shutdown, waits for responses (best effort), marks phase `cancelled` with `active=false`, captures cancellation metadata, then deletes team resources and clears/preserves Team state per policy. Handoff files in `.omq/handoffs/` are preserved for potential resume. - Terminal states are `complete`, `failed`, and `cancelled`. ## Windows psmux tmux-compatible gate On native Windows, do **not** tell users that `/team` requires WSL or that tmux is unavailable until the actual tmux-compatible binary has been checked. Native [psmux](https://github.com/psmux/psmux) installs a `tmux`-compatible command (often `tmux` / `tmux.cmd`) and is a supported Team multiplexer. Before blocking or falling back on Windows: 1. Check `tmux -V` (or the platform equivalent such as `where tmux` followed by `tmux -V`). 2. Treat a successful psmux-backed `tmux -V` as tmux available. 3. If psmux/tmux is available, continue the normal Team flow; do not emit WSL-required guidance. 4. Only when no tmux-compatible binary is available, tell the user to install psmux for native Windows support or use WSL2 as an alternative. ## Workflow ### Phase 1: Parse Input - Extract **N** (agent count), validate 1-20 - Extract **agent-type**, validate it maps to a known OMQ subagent - Extract **task** description ### Phase 2: Analyze & Decompose Use `explore` or `architect` (via MCP or agent) to analyze the codebase and break the task into N subtasks: - Each subtask should be **file-scoped** or **module-scoped** to avoid conflicts - Subtasks must be independent or have clear dependency ordering - Each subtask needs a concise `subject` and detailed `description` - Identify dependencies between subtasks (e.g., "shared types must be fixed before consumers") ### Phase 3: Create Team Call `team_create` with a slug derived from the task: ```json {