--- 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/` 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: ```bash omagy team 3:implementer "" ``` 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: ```bash omagy team --working-directory /absolute/project/root 3:implementer "" omagy team --working-directory /absolute/project/root from-plan --json omagy team --working-directory /absolute/project/root status --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: ```bash 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//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 ""`. 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: ```bash omagy team status --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/` 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: ```text .omagy/state/team//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: ```text .omagy/team//worktrees/ ``` 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: ```bash omagy team status omagy team resume omagy team recover omagy team rebalance omagy team inspect omagy team diagnose omagy team scale [--force] omagy team await --timeout-ms 30000 omagy team api list-tasks --input '{"team_name":""}' --json omagy team api mailbox-list --input '{"team_name":"","worker":"leader-fixed"}' --json omagy team api read-stall-state --input '{"team_name":""}' --json omagy team api read-progress-evidence --input '{"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-.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: ```json { "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: ```bash omagy team checkpoint --all omagy team integrate --all --strategy merge omagy team commit-hygiene ``` 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: ```bash omagy team shutdown --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 ` or `omagy team await `. 3. For approved-plan teams, read `omagy team api read-approved-execution --input '{"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 ` 2. `omagy team diagnose ` 3. `omagy team inspect ` 4. `omagy team api read-delivery-log --input '{"team_name":""}' --json` 5. `omagy team api read-stall-state --input '{"team_name":""}' --json` 6. `omagy team api read-approved-execution --input '{"team_name":""}' --json` 7. Bounded pane capture only after state evidence shows notification failure or the user explicitly asks for manual pane intervention.