Epic Team

Epic Team Orchestration

Backing Status () — NON-RUNNABLE via canonical event-bus dispatch

This skill has no deterministic node backing and is de-listed from event-bus / node-routed dispatch — deliberately, by design. Its omniclaude "node" (node_skill_epic_team_orchestrator) is a generated Polly-passthrough shell (maturity: stub in its contract.yaml). Its real execution mechanism, plugins/onex/skills/epic_team/run.sh, itself shells out to claude -p (headless Claude Code) — still an LLM session, not a canonical COMPUTE/EFFECT/ORCHESTRATOR/REDUCER node. Spawning live Task()/TeamCreate() subagents is inherently a Claude-session capability; there is no I/O boundary a backend node can call to create a new agent session.

This is intentional, not a gap to silently paper over: epic_team is, and should remain, session-native (Skill-tool / headless-launcher driven only). Future evaluation of a gated-EFFECT wrapper around the run.sh launch step is tracked in .

Tools Required

This skill spawns workers via Agent(team_name=...). Workers run in fresh sessions where the Agent tool is deferred (schema not pre-loaded). Any worker that needs to dispatch further sub-agents (e.g. a ticket-pipeline worker spawning a verifier) must call:

ToolSearch(query="select:Agent,SendMessage,TaskCreate,TaskUpdate,TaskGet", max_results=5)

Inject this as the first line of every Agent() dispatch prompt in the wave loop. The worker must call it before any other tool use. Without it, recursive dispatch fails silently with "Agent tool unavailable".

Mode Declaration

This skill operates in BUILD mode only.

Valid --mode values: build

If --mode is omitted or set to any value other than build, emit the following usage error and stop — do NOT proceed to dispatch:

ERROR: /epic-team requires --mode build

Usage: /epic-team <epic_id> --mode build [options]

Valid modes:
  build    Orchestrate autonomous implementation of a Linear epic across repos

This skill is BUILD mode only. For close-out or reporting tasks:
  Close-out: /merge-sweep --mode close-out
  Reporting: /linear-insights --mode deep-dive

First output line when mode is valid must be:

[epic-team] MODE: build | epic: <epic_id>

No tool calls, file reads, or bash commands may precede this output.

Headless Mode (Overnight Pipelines)

Use plugins/onex/skills/epic_team/run.sh for overnight/unattended runs:

# Full headless run
plugins/onex/skills/epic_team/run.sh PROJ-1000 --mode build

# Dry run (no spawning)
plugins/onex/skills/epic_team/run.sh PROJ-1000 --mode build --dry-run

# Resume after context limit or crash
plugins/onex/skills/epic_team/run.sh PROJ-1000 --mode build --resume

Minimum tool allowlist for headless epic-team:

tracker.get_issue, tracker.list_issues,
tracker.save_issue, tracker.save_comment,
tracker.list_projects, tracker.get_project,
tracker.list_teams, Bash, Read, Write, Edit, Glob, Grep,
TeamCreate, TeamDelete, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList, SendMessage

Failure doctrine in headless mode:

• Missing epic_id: exit 1, structured JSON error — no partial run ever started
• Missing credentials (LINEAR_API_KEY): exit 2 immediately, no retries
• Ambiguity (cannot determine epic state, conflicting lock files): write $ONEX_STATE_DIR/epics/<id>/ambiguity_<ts>.json, exit 3 — never guess
• Blocked tool (not in allowlist): log denial, exit 4 — never silently substitute
• Context limit: checkpoint to $ONEX_STATE_DIR/epics/<id>/state.yaml before stopping; re-run with --resume to continue from last completed wave

Checkpointable state: All in-progress state is written to $ONEX_STATE_DIR/epics/<epic_id>/state.yaml before each wave and updated after each ticket completion. A coordinator killed at any point can be resumed by re-running with --resume against the same state.yaml.

Dispatch Surface: Agent Teams

epic-team uses Claude Code Agent Teams for all worker dispatch. The team lead (this session) creates a named team, generates task contracts, dispatches workers, monitors for stalls, and shuts down the team on completion.

Non-Blocking Foreground Contract

Agent(...) dispatches return immediately — workers run as independent background sessions. The team lead must never await or block the foreground on any single worker. The wave monitoring loop (see "Stall Detection in Wave Dispatch" below) polls TaskGet status and only advances to the next wave when the current wave has reported terminal status or a stall has been handled. This is the canonical dispatch pattern referenced by Workstream D of the 2026-04-02 Insights Plan: read epic tickets from Linear → group by repo → TeamCreate → one Agent(team_name=...) per ticket → poll status non-blocking. No separate /dispatch-epic skill is needed; that workflow is exactly this skill's dispatch phase.

Stall detection integrates agent_healthcheck and dispatch_watchdog: two minutes of zero tool calls from a worker is a stall signal, and stalled workers are killed and redispatched with narrower scope per the watchdog's escalation policy.

Lifecycle

1. TeamCreate(team_name="epic-{epic_id}")
2. For each ticket in wave:
   a. Generate a ModelTaskContract from the ticket's Linear DoD and inject into the worker prompt
   b. TaskCreate(subject="{ticket_id}: {title}", description=ticket_requirements)
   c. Agent(name="worker-{ticket_id}", team_name="epic-{epic_id}",
            prompt="Execute ticket-pipeline for {ticket_id}. Task contract: {contract_json}")
3. Workers execute in background, report progress via SendMessage(to="team-lead")
4. Team lead monitors progress, handles stalls (5-min inactivity timeout)
5. On each worker completion: verification chain runs (see below)
6. TeamDelete(team_name="epic-{epic_id}") after all tasks complete or are terminal

Task Contract Generation

Before dispatching each worker, the team lead generates a task contract:

1. Fetch ticket DoD from Linear (description, acceptance criteria)
2. Build ModelTaskContract with mechanical checks (test pass, lint clean, type-check clean)
3. Inject the serialized contract into the worker's dispatch prompt
4. The contract travels with the worker — it is the single source of truth for what "done" means

Verification Chain (Part 2 Reference)

Each worker task must produce evidence through the full Part 2 verification chain:

1. Task contract — ModelTaskContract persisted before dispatch
2. Self-check — worker runs SelfCheckResult against its own contract checks
3. Verifier — independent verifier agent validates self-check evidence
4. Quorum gate — ModelQuorumResult evaluates self-check + verifier verdicts
5. Completion event — ModelTaskCompletedEvent emitted with evidence to unified event stream

A worker is not considered complete until all five artifacts are present. Missing evidence triggers a re-verification pass before the task is marked done.

Stall Detection

After dispatching workers in a wave, the team lead monitors for stalls:

• Inactivity timeout: 5 minutes with no tool calls from a worker → stall detected
• On stall: Log friction event to .onex_state/friction/, cancel stalled worker, mark task for retry in next wave
• Retry policy: Each ticket gets 1 retry. If stalled twice → mark blocked, add Linear comment, skip
• Wave timeout: 30 minutes total per wave. Remaining in-progress tasks are timed out and retried once

Failure on Dispatch

If Agent Teams dispatch fails (TeamCreate error, Agent tool unavailable, auth error): STOP immediately. Report the exact error to the user and wait for direction. Do NOT fall back to direct Bash, Read, Edit, Write, or Glob calls — falling back bypasses observability, context management, and the orchestration layer.

Session lifetime: The monitoring phase is alive only while this session runs. Use /epic-team {epic_id} --resume to re-enter after a disconnection.

Architecture note (v3.0.0): epic-team is a thin orchestrator. All business logic lives in independently-invocable composable sub-skills. epic-team's job is coordination, state, and routing — not implementation. Workers are Agent Teams members, not poly-agent subagents.

Overview

Decompose a Linear epic into per-repo workstreams and autonomously drive them to completion. The team lead (this session) owns planning, dispatch, state persistence, and lifecycle notifications. Tickets are executed by dispatching workers via Agent Teams (TeamCreate + Agent(team_name=...)) in dependency-respecting waves.

If the epic has zero child tickets, epic-team invokes decompose-epic to create sub-tickets, then posts a Slack LOW_RISK gate. Silence for 30 minutes = proceed.

Execution Rules

Execute end-to-end without stopping between tasks. If blocked on one task, record a skip note and continue to the next. Only pause for: (a) credentials not available in the session, (b) a destructive action not explicitly covered by the plan, or (c) an explicit user gate in the plan. Do not exit plan mode or stop to "await direction" in any other circumstance.

Wave Cap

Dispatch tickets in waves of 5 tickets maximum to prevent usage-limit interruptions. Start the next wave only after all Agent() workers in the current wave have reported back. Never dispatch more than 5 tickets in a single wave, even if more are independent.

Sequential PR Chaining

When creating PRs for sequential tasks that modify the same files:

1. PR N+1 should target PR N's branch (not main) if they share modified files
2. Maximum chain depth: 3 PRs
3. If chain would exceed 3, wait for earlier PRs to merge before creating more

Detection: Before creating a PR, check if another open PR from the same epic modifies any of the same files:

# Get files in current change
CHANGED_FILES=$(git diff --name-only main...)

# Check open PRs from same epic for overlapping files
for PR_NUM in $(gh pr list --label "epic:<EPIC-ID>" --json number -q '.[].number'); do
  PR_FILES=$(gh pr view $PR_NUM --json files -q '.files[].path')
  OVERLAP=$(comm -12 <(echo "$CHANGED_FILES" | sort) <(echo "$PR_FILES" | sort))
  if [[ -n "$OVERLAP" ]]; then
    echo "Overlapping files with PR #$PR_NUM: $OVERLAP"
    echo "Target PR #$PR_NUM's branch instead of main"
  fi
done

Composable Sub-Skills

epic-team orchestrates these independently-invocable primitives:

ticket-pipeline in turn composes:

Each layer is independently invocable:

• ticket-pipeline runs standalone without epic-team
• ticket-work runs standalone without ticket-pipeline
• ci-watch runs standalone on any PR

If the epic has zero child tickets, epic-team automatically invokes the decompose-epic sub-skill to analyze the epic description and create sub-tickets, then posts a Slack LOW_RISK gate. Silence for 30 minutes means proceed with newly created tickets.

Usage Examples

# Dry run — see decomposition without spawning agents
/epic-team PROJ-1000 --dry-run

# Full run
/epic-team PROJ-1000

# Resume after session disconnect
/epic-team PROJ-1000 --resume

# Force restart (archive existing state; pauses if workers active)
/epic-team PROJ-1000 --force

# Force restart even with active workers (dangerous)
/epic-team PROJ-1000 --force --force-kill

# Route unmatched tickets to omniplan triage
/epic-team PROJ-1000 --force-unmatched

Orchestration Flow

epic-team <EPIC-ID>
  → Fetch child tickets from Linear
  → If 0 child tickets:
      → Dispatch decompose-epic (composable, returns skill_result)
      → Read $ONEX_STATE_DIR/skill-results/{context_id}/decompose-epic.json
      → Dispatch slack-gate (LOW_RISK, 30 min, silence=proceed)
      → Read $ONEX_STATE_DIR/skill-results/{context_id}/slack-gate.json
      → If rejected: stop
      → Re-fetch newly created tickets
  → Assign tickets to repos via repo_manifest
  → Build dependency waves:
      Wave 0: independent tickets + cross-repo Part 1 splits (run in parallel)
      Wave 1: cross-repo Part 2 splits (run after Wave 0 completes)
  → For each wave: dispatch ticket-pipeline per ticket as Agent() workers in parallel
  → Start stall-detection watchdog for the wave
  → Await all Agent() workers in wave to report via SendMessage before starting next wave
  → If watchdog detects stall: cancel stalled worker, log to state, retry in next wave
  → Collect results (status, pr_url, branch) from SendMessage reports
  → Post-wave integration check: run gap cycle --no-fix per repo touched
      → GREEN/YELLOW/RED per repo → post to Slack epic thread
      → Write integration_check section to state.yaml (non-blocking — always advances)
  → Post-orchestration verification sweep: invoke /verification-sweep --epic {epic_id}
      → Verify dashboard endpoints return HTTP 200 with real data
      → Verify database tables contain expected rows
      → Verify dod_evidence rendered_output items have passing receipts
      → Write receipts to .onex_state/verification-receipts/ (non-blocking — always advances)
  → DoD compliance gate: invoke /dod-sweep {epic_id} (targeted mode)
      → If FAIL: do NOT mark epic Done; follow-ups auto-created; post Slack block
      → If PASS: proceed to mark epic Done; post Slack clean notification
      → If UNKNOWN (all exempt): proceed (rollout accommodation); post review warning
  → Send Slack lifecycle notifications (started, ticket done, epic done)
  → Persist state to $ONEX_STATE_DIR/epics/{epic_id}/state.yaml

Dispatch: decompose-epic

When epic has 0 child tickets:

Agent(
  name="decompose-{epic_id}",
  team_name="epic-{epic_id}",
  prompt="The epic {epic_id} has no child tickets.

    Invoke: Skill(skill=\"onex:decompose_epic\", args=\"{epic_id}\")

    Read result from $ONEX_STATE_DIR/skill-results/{context_id}/decompose-epic.json
    Report back via SendMessage: created_tickets (list of IDs and titles), count."
)

Pre-Dispatch Verification Preamble

Before dispatching any ticket in a wave, the team lead performs a lightweight verification pass to catch misaligned tickets early -- before they consume a full pipeline run.

Worker Model Enforcement

All workers dispatched by epic-team MUST use Sonnet (not Opus). Do NOT dispatch workers with model: opus or leave the model unspecified in environments where Opus is the default.

Add to every Agent() dispatch prompt:

MODEL: claude-sonnet-4-6

Rationale: Opus is reserved for orchestrator-level reasoning. Worker cost scales with the number of tickets; Sonnet is sufficient for implementation tasks.

ONEX Pattern Gate (pre-dispatch static review)

DISABLED: hostile_reviewer is currently disabled pending eval framework validation. Skip this gate entirely. Do NOT invoke. Proceed to Verification Steps directly.

Before dispatching any ticket in a wave, run hostile_reviewer --static on each task description to catch ONEX anti-patterns before they consume a full pipeline run.

Invoke:

Skill(skill="onex:hostile_reviewer", args="--static --text \"<task_description>\"")

Block dispatch if any of the following patterns are detected:

On block: Mark the ticket as pattern_gate_failed in state.yaml with the violation detail. Add a Linear comment: "[epic-team] Pattern gate blocked dispatch: {violation}". Do NOT dispatch. Escalate to user if more than 2 tickets in a wave are blocked by the pattern gate.

On pass: Record pattern_gate: passed in the ticket's contract before Agent() dispatch.

Verification Steps (per ticket, before Agent() dispatch)

1. ONEX pattern gate: Run hostile_reviewer --static on task description DISABLED — skip this step, proceed to step 2.

2. Ticket readiness check: Fetch ticket via tracker.get_issue and verify:

   • Description is non-empty and contains actionable content
   • Repo target is identifiable (from title, description, or labels)
   • No blocking dependencies are in non-Done state

3. Approach sanity check: For each ticket, state in the dispatch prompt:

   • What the ticket requires (1-sentence summary)
   • Which repo and approximate files will be modified
   • Any known constraints or patterns to follow

4. Skip unready tickets: If a ticket fails verification:

   • Mark as skipped in state.yaml with reason: "verification_failed: {detail}"
   • Add a Linear comment: "Skipped by epic-team: {reason}"
   • Do NOT dispatch -- move to next ticket in wave
   • Unready tickets are re-evaluated in the next wave (dependency may have resolved)

Verification in the Dispatch Prompt

The verification context is injected directly into each Agent() dispatch prompt so the ticket-pipeline agent starts with pre-validated understanding rather than re-deriving it.

Dispatch: Ticket-Pipeline per Ticket (Agent Teams Pattern)

For each ticket in a wave, generate a task contract and dispatch a worker via Agent Teams:

# 1. Generate task contract from Linear DoD
contract = generate_task_contract(ticket_id, ticket_description, ticket_acceptance_criteria)
# Persist contract to $ONEX_STATE_DIR/epics/{epic_id}/contracts/{ticket_id}.json

# 2. Create a task for tracking
TaskCreate(subject="{ticket_id}: {title}", description=ticket_requirements)

# 3. Dispatch worker as Agent Teams member
Agent(
  name="worker-{ticket_id}",
  team_name="epic-{epic_id}",
  prompt="FIRST ACTION — fetch deferred dispatch tool schemas:
    ToolSearch(query=\"select:Agent,SendMessage,TaskCreate,TaskUpdate,TaskGet\", max_results=5)

    You are executing ticket {ticket_id} for epic {epic_id}.

    Ticket: {ticket_id} - {title}
    URL: {url}
    Repo: {repo} at {repo_path}
    Epic: {epic_id}  Run: {run_id}

    TASK CONTRACT (source of truth for done):
    {contract_json}

    VERIFIED CONTEXT (from epic-team pre-dispatch check):
    - Summary: {verified_summary}
    - Target files: {verified_file_targets}
    - Pattern to follow: {verified_pattern_reference}
    - Dependencies met: {dependency_status}

    VERIFICATION CHAIN — you must produce ALL of these before reporting done:
    1. Run self-check against the task contract (SelfCheckResult)
    2. Evidence is verified by an independent verifier agent
    3. Quorum gate evaluates self-check + verifier verdicts (ModelQuorumResult)
    4. Emit ModelTaskCompletedEvent with all evidence

    Invoke: Skill(skill=\"onex:ticket_pipeline\", args=\"{ticket_id}\")

    After ticket-pipeline completes, report back via SendMessage(to=\"team-lead\"):
    - ticket_id: {ticket_id}
    - status: (merged/failed/blocked)
    - pr_url: (if available)
    - branch: (branch name used)
    - verification_verdict: (PASS/FAIL/INCOMPLETE)"
)

Wave parallelism: Agent Teams workers run as independent concurrent Claude sessions. Dispatch all Agent() calls for a wave before monitoring. Do NOT dispatch tickets sequentially within a wave.

Wave serialization: Wave N+1 starts only after all workers from Wave N have reported back via SendMessage or been timed out by stall detection.

Stall Detection in Wave Dispatch

After dispatching all Agent() calls in a wave, the team lead monitors for stalled agents using the dispatch_watchdog skill. This prevents a single stalled agent from blocking the entire wave indefinitely.

Monitoring Loop

# After dispatching wave N tasks:
wave_start_time = now()
stall_timeout = 300  # 5 minutes with no tool calls

while any_task_still_running(wave_tasks):
    # Check each running task
    for task in wave_tasks:
        if task.status == "in_progress":
            elapsed_since_last_activity = now() - task.last_tool_call_time

            if elapsed_since_last_activity > stall_timeout:
                # Stall detected
                log("[epic-team] STALL: {task.ticket_id} idle for {elapsed}s")
                write_stall_event(epic_id, task.ticket_id, elapsed)

                # Recovery: mark as failed, retry in next wave
                task.status = "stalled"
                task.retry_in_next_wave = true

    # Check wave-level timeout (30 minutes total)
    if now() - wave_start_time > 1800:
        log("[epic-team] WAVE TIMEOUT: cancelling remaining tasks")
        for task in wave_tasks:
            if task.status == "in_progress":
                task.status = "timeout"
                task.retry_in_next_wave = true
        break

    sleep(60)  # Check every minute

Stall State in state.yaml

waves:
  - wave_id: 0
    dispatched_at: "2026-03-29T10:00:00Z"
    completed_at: "2026-03-29T10:15:00Z"
    tasks:
      - ticket_id: PROJ-1001
        status: merged
        pr_url: "https://github.com/..."
      - ticket_id: PROJ-1002
        status: stalled
        stall_detected_at: "2026-03-29T10:08:00Z"
        idle_seconds: 480
        retry_wave: 1

Retry Policy

• Stalled tasks are retried once in the next wave
• If a task stalls twice: mark as blocked, add Linear comment, skip
• Timeout tasks (wave-level) are always retried once
• Maximum retry count per ticket: 1 (prevents infinite retry loops)

Integration with dispatch_watchdog Skill

The monitoring logic above is the inline version for the team-lead session. For more sophisticated monitoring (e.g., headless overnight runs), invoke the dispatch_watchdog skill as a composable sub-skill:

Skill(skill="onex:dispatch_watchdog", args="--epic-id {epic_id} --timeout 300 --action report")

Skill Result Communication

All sub-skills write their output to $ONEX_STATE_DIR/skill-results/{context_id}/:

Skill Result Input Contract

Input contract: All sub-skill result files conform to ModelSkillResult from omnibase_core.models.skill.

Note: This contract reference is behavioral guidance for the LLM executing this skill. Runtime validation not yet implemented.

Load result files and check outcomes as follows:

result = ModelSkillResult.from_json(path.read_text())

# Check if the sub-skill completed successfully (success, partial, or dry_run)
if result.is_success_like:
    # Proceed with next wave or action
    pass

# Check for hard failure
elif result.status == EnumSkillResultStatus.FAILED:
    # Record failure, apply circuit breaker (max 2 retries per ticket)
    pass

# Check for blocking states
elif result.status == EnumSkillResultStatus.GATED:
    # Human approval is pending — do not advance wave
    pass

# Access skill-specific fields via extra dict (not direct attribute access).
# Use .get() with a default — extra may be empty on non-success paths.
created_tickets = result.extra.get("created_tickets", [])   # decompose-epic result
iterations_run = result.extra.get("iterations_run", 0)      # local-review result

Behaviorally significant extra_status values by sub-skill:

Promotion rule for extra fields: If any orchestrator consumer (epic-team, ticket-pipeline) branches on extra["x"], that field MUST be promoted to a first-class field in ModelSkillResult. extra is a migration bridge, not a permanent schema extension mechanism.

State Persistence

Runtime state is persisted to $ONEX_STATE_DIR/epics/{epic_id}/state.yaml:

epic_id: PROJ-XXXX
run_id: f084b6c3
status: monitoring  # queued | monitoring | done | failed
checkpoint:
  schema_version: 1
  last_completed_wave: 0
  waves:
    - wave_id: 0
      tickets: [PROJ-1001, PROJ-1002]
      status: completed  # pending | in_progress | completed | failed
      completed_at: "2026-03-06T..."
    - wave_id: 1
      tickets: [PROJ-1003]
      status: pending
  open_prs:
    PROJ-1001: {pr_number: 45, repo: "omniclaude", branch: "<user>/omn-2001-..."}
  failures:
    PROJ-1003: {class: "ci_failure_ruff", attempts: 1, last_error: "..."}
  last_update_utc: "2026-03-06T..."
workers:
  - repo: omniclaude
    tickets: [PROJ-1001, PROJ-1002]
    status: running  # running | done | failed
ticket_status:
  PROJ-1001: merged
  PROJ-1002: running

Use --resume to re-enter monitoring from persisted state after session disconnect.

Empty Epic Auto-Decompose

When epic has 0 child tickets:

[LOW_RISK] epic-team: Auto-decomposed PROJ-XXXX

Epic had no child tickets. Created N sub-tickets:
  - PROJ-YYYY: [title]
  - PROJ-ZZZZ: [title]
  ...

Reply "reject" within 30 minutes to cancel. Silence = proceed with orchestration.

--dry-run behavior for empty epic

Invoke decompose-epic --dry-run (returns plan, no tickets created). Print plan. Do not post Slack gate.

Repo Manifest

Ticket-to-repo assignment uses plugins/onex/skills/epic-team/repo_manifest.yaml:

MIN_TOP_SCORE: 4

repos:
  - name: omniclaude
    path: ~/Code/omniclaude
    keywords: [hooks, skills, agents, claude, plugin, ticket-pipeline]
  - name: omnibase_core
    path: ~/Code/omnibase_core
    keywords: [nodes, contracts, runtime, onex]
  - name: omnibase_infra
    path: ~/Code/omnibase_infra
    keywords: [kubernetes, deploy, infra, helm]

Keyword matching is case-insensitive. Tickets with no keyword match are UNMATCHED. Use --force-unmatched to route them to omniplan as TRIAGE tasks.

Stacked Branch Execution

When Wave N+1 tickets depend on Wave N (via cross-repo Part 2 splits or file-overlap chains), the downstream ticket branches from the Wave N branch tip instead of main. This avoids merge conflicts and ensures later tickets see earlier changes without waiting for merge.

How it works:

1. After Wave N completes, collect {ticket_id: branch_name} from worker results
2. When dispatching Wave N+1, check if any ticket has a dependency on a Wave N ticket (via chain_targets from detect_file_overlap_chains or cross-repo Part 2 mapping)
3. If a dependency exists and the upstream ticket succeeded, pass --base-branch <branch> to the downstream ticket's ticket-pipeline invocation
4. ticket-pipeline creates its worktree from the specified base branch and opens its PR targeting that base branch

Fallback: If the upstream ticket failed or returned no branch, fall back to main.

Chain depth limit: Maximum 3 levels of stacking. Beyond that, tickets target main independently to avoid deep rebase chains.

State tracking: The ticket_results dict in state.yaml records branch per ticket, making stacked branch resolution available across waves and on --resume.

Worktree Policy

Workers create isolated git worktrees at:

$ONEX_STATE_DIR/worktrees/{epic_id}/{run_id}/{ticket_id}/

Stale worktrees are cleaned up automatically after merge when auto_cleanup_merged_worktrees: true (default).

Architecture

epic-team is a thin composition layer. It owns:

• Epic decomposition (via decompose-epic)
• Ticket-to-repo assignment (via repo_manifest)
• Wave construction (group tickets by dependency into parallel waves)
• Agent Teams dispatch of ticket-pipeline per ticket (TeamCreate + Agent with team_name)
• State persistence ($ONEX_STATE_DIR/epics/{epic_id}/state.yaml)
• Slack lifecycle notifications (started, ticket done, epic done)

It does NOT own:

• Ticket implementation (delegated to ticket-pipeline → ticket-work)
• Code review (delegated to local-review)
• CI polling (delegated to ci-watch)
• PR review polling (delegated to pr-watch)
• Merge execution (delegated to auto-merge)

Execution Model

Agent Teams dispatch from team-lead session is the authoritative execution pattern:

1. Team-lead creates the team via TeamCreate(team_name="epic-{epic_id}")
2. Team-lead constructs waves of tickets grouped by dependency
3. For each wave, team-lead dispatches Agent() workers in parallel with team_name parameter
4. Workers execute in background and report completion via SendMessage(to="team-lead")
5. Team-lead monitors SendMessage reports and stall detection before starting the next wave
6. After all waves complete, team-lead cleans up via TeamDelete()

Circuit Breaker / Heartbeat Timeout

Every Agent() dispatch has a configurable timeout to prevent stalled agents from blocking the entire wave indefinitely. If an agent produces no output for DISPATCH_TIMEOUT_MINUTES (default: 30, configurable via EPIC_TEAM_DISPATCH_TIMEOUT_MINUTES env var), the circuit breaker trips:

1. The Agent() dispatch returns a timeout error
2. The ticket is marked AGENT_TIMEOUT in state.yaml
3. A Kafka event onex.evt.omniclaude.agent-circuit-breaker.v1 is emitted for observability
4. The wave continues with remaining tickets (timeout is non-blocking)

This prevents the first autopilot close-out failure mode where a release dispatch stalled for 1+ hour with zero output.

Agent Health-Check Integration

The agent_healthcheck skill provides more sophisticated stall detection beyond the simple timeout circuit breaker. During wave monitoring, epic-team checks agent health using three heuristics:

1. Inactivity: No tool calls for 10 minutes (configurable)
2. Context overflow: Context window usage > 80% (preemptive recovery before hard limit)
3. Rate limits: Agent encounters rate-limit errors

On stall detection, the health-check module:

• Snapshots progress to a checkpoint file (using the checkpoint protocol from an earlier pass)
• Summarizes completed vs remaining work
• Relaunches a fresh agent with the summary and remaining tasks only

See @skills/agent_healthcheck/SKILL.md for the full detection and recovery protocol.

Failure Taxonomy and Recovery Strategies

Failure Attempt Definition

A failure attempt is counted when ticket-pipeline returns non-zero exit OR the summary contains an explicit failure class. Partial completions (branch exists, some steps done) count as one attempt.

Self-Healing Rules

• Attempt retry up to 2 times within the same run only. On interruption + re-run, counts reset.
• After 2 failed attempts: produce failure report and stop dispatching new tickets.
• Escalation = log the failure report and continue with remaining unblocked tickets.

DoD Compliance Gate

After all ticket-pipeline waves complete and before marking the epic as Done:

1. Invoke /dod-sweep {epic_id} (targeted mode)
2. If overall_status == FAIL:
   • Do NOT mark the epic Done
   • Follow-up tickets are auto-created by dod_sweep
   • Post Slack notification: "Epic {epic_id} blocked by DoD gaps: {failed} failed, {exempted} exempted, {passed} passed"
   • Leave epic in current state for manual resolution
3. If overall_status == PASS:
   • Proceed to mark epic Done
   • Post Slack notification: "Epic {epic_id} DoD gate cleared: {passed} passed, {exempted} exempted, {failed} failed"
4. If overall_status == UNKNOWN (e.g., all tickets exempted):
   • Post Slack notification: "Epic {epic_id} DoD gate: no evidence-backed passes -- {exempted} exempted, review recommended"
   • Proceed to mark epic Done (non-blocking) but flag for review
   • NOTE: Allowing all-exempted epics to proceed under UNKNOWN is a rollout accommodation, not the intended long-term steady state. This allow-through must sunset after the cutoff exemption review trigger fires (4 weeks or warning volume <10%, whichever first).

Notifications must always include passed/failed/exempted counts separately -- never imply all tickets passed when exemptions are present.

See Also

• prompt.md — full orchestration logic, state machine, and error handling reference
• ticket-pipeline skill — per-ticket pipeline invoked by workers
• ticket-work skill — implementation phase (autonomous mode)
• local-review skill — review + fix loop
• ci-watch skill — CI polling and auto-fix
• pr-watch skill — PR review polling and auto-fix
• auto-merge skill — merge gate
• decompose-epic skill — empty epic auto-decompose
• slack-gate skill — LOW_RISK notification gate
• verification-sweep skill — post-orchestration endpoint/DB/DoD verification
• plugins/onex/skills/epic-team/repo_manifest.yaml — repo keyword mapping
• Linear MCP tools (tracker.*) — epic and ticket access

Container / Degraded Environment

When running without the full omniclaude plugin (e.g., container-based Claude Code sessions):

• general-purpose is used as a safety-net fallback when the preferred skill is unavailable or returns an error. ONEX intelligence integration, action logging, and observability will be inactive. Skill instructions still execute correctly — only metadata and telemetry are affected.
• Cross-skill dispatch (Skill(skill="onex:...")) requires the plugin's skill registry. If skills are not registered, dispatch calls will fail. Verify: check if the skill appears in the system-reminder skills list.
• Hook enforcement (poly_enforcer, authorization_shim, bash_guard) will not be active.
• Linear MCP may not be available. See --local mode (if applicable) for offline ticket management.