team

name	team
description	Durable agy-only tmux team runtime with worktree isolation.

Team

Team is Omagy's durable agy-only tmux runtime. It starts real agy worker sessions in tmux panes and coordinates them through .omagy/state/team/<team> plus omagy team api. Treat Team as an operator workflow, not a generic prompt.

Team is one of the only approved peer overlaps in Omagy's workflow transition contract. It may coexist with /omagy:ralph or /omagy:ultrawork; all other unlisted workflow overlaps are denied until explicitly added to internal/contracts/multi-state-transition-contract.md.

Do not use Team as the default implementation of /omagy:code-review. Plain code-review uses native agy subagents for bounded code-reviewer/architect lanes. Escalate to Team only when the user explicitly asks for durable multi-worker review or the review requires tmux workers, shared task state, recovery, or worktree coordination.

Team vs native Antigravity subagents:

• Use native agy subagents for bounded in-session fanout where the parent can synthesize immediately.
• Use Team for durable workers, shared task state, mailbox/dispatch, recovery, worktree isolation, and explicit lifecycle control.

Start from an attached tmux leader pane:

omagy team 3:implementer "<task description>"

Antigravity slash commands may execute shell tools from ~/.gemini/antigravity-cli/scratch even when the visible CLI session is opened on a project. Never launch Team against scratch unless the user explicitly asks to work there. Before omagy team startup, determine the real project root from the visible Antigravity workspace/current directory or ListPermissions. If the tool cwd is Antigravity scratch, pass the real root explicitly:

omagy team --working-directory /absolute/project/root 3:implementer "<task description>"
omagy team --working-directory /absolute/project/root from-plan --json
omagy team --working-directory /absolute/project/root status <team-name> --json

If no real project root can be determined, stop and report team_requires_project_working_directory; do not create a temporary project in scratch to satisfy the slash command.

Before Team splits worker panes, the runtime checks the current tmux window for duplicate omagy hud --watch panes. If more than one HUD watcher is present, Team fails closed with team_hud_preflight_duplicate_watch_panes; remove the extra HUD pane before launching or scaling workers.

When the user asks to execute the latest approved plan, approved handoff, PRD, or /omagy:plan output, fail closed through the plan handoff gate instead of starting from ambient notes:

omagy plan handoff --mode team --json
omagy team from-plan --json

omagy team from-plan reads the visible /omagy:team launch hint from the latest matched PRD/test-spec pair and starts Team with that approved task, worker count, role, PRD path, and test spec path. If the handoff is missing, ambiguous, or lacks a matching test spec, do not start Team; return to /omagy:plan to fix the PRD/test-spec pair.

Approved execution is leader-owned. When Team starts from an approved plan, the runtime persists .omagy/state/team/<team>/approved-execution.json and injects that binding into worker inboxes. Workers provide task and verification evidence only; the leader owns final PRD/test-spec acceptance, checkpoint, integration, and shutdown. Workers must not mutate .omagy/plans, invent a parallel plan ledger, or claim plan completion without leader verification.

If the user gives a clear direct task that is not plan-bound, start Team directly with omagy team N:role "<task description>".

Startup success must be verified from Omagy runtime state, not inferred from model prose or copied launcher text. After every direct start or from-plan start, immediately run:

omagy team status <team-name> --json

Only report Team as started when the status envelope is status:"ok" and the snapshot contains the expected team name, worker records, and task records. If status is missing, no .omagy/state/team/<team-name> state exists, or worker panes are stopped at an agy trust/auth prompt, report startup as failed or blocked and do not claim the Team is running.

Pre-context intake is mandatory before worker panes are treated as ready. The runtime creates a grounded snapshot under .omagy/context/ and a team-scoped worker instruction overlay at:

.omagy/state/team/<team-name>/worker-agents.md

The overlay carries inherited AGENTS.md guidance plus Omagy worker protocol without mutating project source files. Worker inboxes and launch prompts must point at both files.

In a git repository, workers use per-worker worktrees by default:

.omagy/team/<team-name>/worktrees/<worker-name>

Use --no-worktree only when shared-cwd execution is intentional.

Inspect and coordinate from the leader. Poll status or await events until all tasks are terminal; do not shut down immediately after launch:

omagy team status <team-name>
omagy team resume <team-name>
omagy team recover <team-name>
omagy team rebalance <team-name>
omagy team inspect <team-name>
omagy team diagnose <team-name>
omagy team scale <team-name> <worker-count> [--force]
omagy team await <team-name> --timeout-ms 30000
omagy team api list-tasks --input '{"team_name":"<team-name>"}' --json
omagy team api mailbox-list --input '{"team_name":"<team-name>","worker":"leader-fixed"}' --json
omagy team api read-stall-state --input '{"team_name":"<team-name>"}' --json
omagy team api read-progress-evidence --input '{"team_name":"<team-name>"}' --json

Message delivery is state-first. Use mailbox/task APIs and let the runtime record dispatch requests and delivery outcomes. Direct tmux send-keys is a runtime transport/fallback, not the primary operator mechanism. Verify delivery through read-dispatch-request, read-delivery-log, mailbox state, task status, or omagy team inspect.

The hook layer records leader-side shell activity for active Team runs, so status and Stop gates can distinguish a stale leader from one that is still actively coordinating workers.

Leader attention is evidence-driven. The runtime combines worker heartbeat, status changes, mailbox state, current-task baseline files, and progress evidence before reporting a stall. When a stall is reported, inspect the structured reminder_intent:

• pending-mailbox-review: read leader/worker mailboxes before nudging panes.
• stalled-unblock: unblock or reassign the affected worker/task.
• done-review-or-shutdown: review terminal evidence, then checkpoint, integrate, or shut down.
• followup-reuse: resume the existing team instead of relaunching.
• followup-relaunch: relaunch only after confirming no active work remains.

Idle pane nudges are runtime-owned. If enabled by the operator environment, the runtime may send a bounded next-action nudge only to idle worker panes; it never nudges the leader pane. Do not replace this with ad-hoc repeated tmux send-keys.

Worker launch inherits an explicit model/reasoning contract from OMAGY_TEAM_WORKER_LAUNCH_ARGS and role defaults. Do not invent per-worker model settings in prompts; inspect read-config or diagnose for the recorded worker_launch_args.

Team start follows the OMX planning handoff order:

1. If an approved plan has a Team DAG Handoff, use it as the source of truth for task nodes, dependencies, worker policy, role routing, and allocation.
2. Prefer .omagy/plans/team-dag-<prd-slug>.json sidecars. If no sidecar is present, read a ## Team DAG Handoff fenced JSON block from the approved PRD.
3. Fail closed on malformed DAG JSON, duplicate node IDs, unknown dependencies, cycles, plan slug mismatch, or source PRD mismatch. Do not silently invent a replacement plan.
4. If the approved plan has no Team DAG handoff, fall back to repo-aware text decomposition. The fallback records path/domain hints when the task names files and reserves a verifier lane when multiple workers are available.

The DAG handoff schema is:

{
  "schema_version": 1,
  "plan_slug": "20260523T010203Z-example",
  "source_prd": "prd-20260523T010203Z-example.md",
  "worker_policy": {
    "requested_count": 3,
    "count_source": "plan-suggested",
    "max_count": 6,
    "reserve_verification_lane": true,
    "strict_max_count": false
  },
  "nodes": [
    {
      "id": "impl",
      "subject": "Implement scoped change",
      "description": "Concrete work item.",
      "role": "implementer",
      "lane": "implementation",
      "filePaths": ["packages/cli/src/team/runtime.ts"],
      "domains": ["team-runtime"],
      "depends_on": [],
      "requires_code_change": true,
      "acceptance": ["Targeted test passes"]
    }
  ]
}

When a DAG node omits role, Omagy applies the OMX-style role router. When multiple workers are available, Omagy applies the OMX-style allocation policy so related file/domain work stays grouped and dependencies remain explicit in task state.

omagy team scale is the operator scaling surface. Scale-up starts additional agy worker panes, writes their inboxes, creates owned work, and records task ownership. Scale-down drains removed workers: pending/blocked work is reassigned, in-progress work blocks unless --force is explicit, then panes are cleaned up.

Checkpoint, integrate, and finalize:

omagy team checkpoint <team-name> --all
omagy team integrate <team-name> --all --strategy merge
omagy team commit-hygiene <team-name>

Runtime checkpoint and integration commits are scaffolding. Final semantic commits should be made by the leader after reading the commit hygiene report.

Shutdown only after tasks are terminal, or use --force for explicit process cleanup. Worktrees are not removed unless --remove-worktrees is also passed:

omagy team shutdown <team-name> --force

Workers must use omagy team api for claims, task transitions, heartbeat, mailbox, dispatch, shutdown, and approvals. Do not directly edit .omagy/state/team/*.

Required lifecycle:

1. Start Team and report startup evidence: team name, tmux target, worker panes, worktree mode, context snapshot, worker-agents path, and initial ACK/mailbox path.
2. Monitor with omagy team status <team-name> or omagy team await <team-name>.
3. For approved-plan teams, read omagy team api read-approved-execution --input '{"team_name":"<team-name>"}' --json before final acceptance.
4. Continue until pending=0, in_progress=0, and failed=0, unless the user explicitly accepts unresolved failures.
5. Run checkpoint/integrate/commit-hygiene when workers made changes.
6. Shutdown only after terminal state, or use --force for explicit cleanup.

Troubleshooting order:

1. omagy team status <team-name>
2. omagy team diagnose <team-name>
3. omagy team inspect <team-name>
4. omagy team api read-delivery-log --input '{"team_name":"<team-name>"}' --json
5. omagy team api read-stall-state --input '{"team_name":"<team-name>"}' --json
6. omagy team api read-approved-execution --input '{"team_name":"<team-name>"}' --json
7. Bounded pane capture only after state evidence shows notification failure or the user explicitly asks for manual pane intervention.