team

N coordinated agents on shared task list using Claude Code implicit agent teams

By yeachan-heo · 709 installs

npx skills add yeachan-heo/oh-my-claudecode --skill team

Source repository · Upstream listing

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 / /omc teams ). 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 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 Architecture Native Claude Code team model (2.1.178+): 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. 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 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 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 .omc/handoffs/ for session resume. They are not deleted by native Claude Code team cleanup; no TeamDelete call exists in Claude Code 2.1.178+. 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 Resume and Cancel Semantics Resume: restart from the last non terminal stage using staged state + live task status. Read .omc/handoffs/ to recover stage transition context. Cancel: use the authoritative flow in skills/cancel/SKILL.md ; do not duplicate its flag, scope, or state cleanup rules here. Handoff files in .omc/handoffs/ are preserved for 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 Resume Check (Before Initialization) Resolve the current session identity from the invocation context before touching Team state. In CLI contexts, OMC SESSION ID is authoritative; in hook contexts, the payload's session id is authoritative. When an identity is available, pass it explicitly and consistently: state read without session id reads legacy/aggregate state and may include other sessions. Never select or resume a Team from an unscoped aggregate response. If no identity is available, use only an explicitly identified legacy state; never infer ownership from session entries in an aggregate response. Read existing session state before deriving a slug, decomposing work, or writing/initializing state. If active=true and current phase is non terminal, resume the recorded stage using the existing handoffs and task list state for that Team. Preserve team name , current phase , fix loop count , max fix loops , stage history , and all other existing Team state fields, including worker/task/launch attempt records. Use the same session id on every subsequent state write and state clear , applying only partial updates under the existing state lock. Do not run the new team initialization below, derive a replacement slug, create duplicate tasks, spawn duplicate workers, or repeat launch attempts. If state is malformed, unreadable, or otherwise corrupt, report the diagnostic and preserve the original bytes. Do not replace, clear, initialize, or treat it as a new run. The following initialization phases apply only to a new run with no active, scoped state.