yeachan-heo/oh-my-claudecode/team

Team Skill

Spawn N coordinated agents working on a shared task list using Claude Code's implicit agent team. Claude Code 2.1.178+ removed native TeamCreate/TeamDelete; with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, each session has one implicit team and teammates are spawned directly with the Agent/Task tool using distinct name values. This skill still preserves OMC's legacy tmux/CLI worker orchestration where documented (omc team). The implicit team and omc team do not share a result: one finishing does not make the other succeed.

The swarm compatibility alias was removed in #1131.

Usage

/oh-my-claudecode:team N:agent-type "task description"
/oh-my-claudecode:team "task description"
/oh-my-claudecode:team ralph "task description"

Parameters

• N - Number of teammate agents (1-20). Optional; defaults to auto-sizing based on task decomposition.
• agent-type - OMC agent to spawn for the team-exec stage (e.g., executor, debugger, designer, codex, gemini, antigravity). Optional; defaults to stage-aware routing. Use codex to spawn Codex CLI workers, gemini for Gemini CLI workers (enterprise/API-key tier), or antigravity for Antigravity CLI (agy) workers (Google's successor to the Gemini CLI; 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

/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"
# With Antigravity CLI workers (requires: install per https://antigravity.google)
/team 2:antigravity "redesign the UI components"
# Mixed: Codex for backend analysis, Gemini/Antigravity for frontend (delegate per-task with /oh-my-claudecode:ask)

Architecture

User: "/team 3:executor fix all TypeScript errors"
              |
              v
      [TEAM ORCHESTRATOR (Lead)]
              |
              +-- Use the session's implicit Claude Code team
              |       -> no TeamCreate call; lead remains current session
              |
              +-- Analyze & decompose task into subtasks
              |       -> explore/architect produces subtask list
              |
              +-- Create task list entries from the implementation plan
              |       -> TODO/task entries #1, #2, #3 with dependencies
              |
              +-- Update task-list entries (pre-assign owners)
              |       -> task #1 owner=worker-1, etc.
              |
              +-- Task(name="worker-1") x 3
              |       -> spawns teammates into the team
              |
              +-- Monitor loop
              |       <- teammate messages (auto-delivered by the active team surface)
              |       -> task-list/TodoWrite review for progress
              |       -> message teammates through the active team surface to unblock/coordinate
              |
              +-- Completion
                      -> request shutdown from each teammate through the active team surface
                      <- shutdown acknowledgement from teammates
                      -> state_clear(mode="team", session_id="<current_session_id>")
                      -> preserve shared/legacy state for explicit --all cleanup

Native Claude Code team model (2.1.178+):

- No per-team ~/.claude/teams/<name>/ directory is created by this skill.
- No TeamCreate/TeamDelete calls are available.
- `team_name` is accepted by native Claude Code only as ignored legacy metadata; do not rely on it for routing.
- Spawn teammates directly via Agent/Task with `name="worker-N"`.

Goal Workflow Relationship

Team is the OMC 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 Claude Code /goal, Ralph, or artifact-only Ultragoal, keep Team as the primary loop authority unless the leader explicitly hands off. Use /goal only as a documented native Claude Code 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.

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 do not participate in Claude's native team messaging.
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: task list 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).

Run closeout (either terminal outcome). Before /oh-my-claudecode:cancel state cleanup, append at most three factual lines to .omc/notepads/team/problems.md (blockers additionally in .omc/notepads/team/issues.md) — what broke (defects that survived a fix round, three-strike halts) and what dragged (worker environment friction, missing checks, unreachable information). Preserve existing entries: append only and never replace the shared file. If there are no observations, append nothing; an empty closeout is valid, so do not write “no lessons.” Observations only; landing them on repo surfaces is refit's job, with the user's approval. For a terminal failed outcome, also draft an incident work item with the failure signature, evidence pointers, and reopen path; append it to the local .omc/notepads/team/issues.md. Post it to a tracker only when the user or mode invocation explicitly authorizes that external action.

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 .omc/handoffs/<stage-name>.md.

Handoff Format

## 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