/marathon

name: marathon
description: >
  Run a list of work units to completion with an Agent Team: derive a dependency DAG and
  hot-file map, spawn one ephemeral teammate per unit (or combined group), drive each PR
  through pr-review-merge, smart-merge in waves, recover from crashes, and run a
  retrospective. Source-agnostic — the caller supplies a work-source adapter. A library
  skill invoked BY the /tm and /issues commands, not run directly by a user (it needs a
  caller-supplied adapter). TRIGGER when a command needs autonomous multi-unit team
  orchestration to completion — a tag, issue queue, backlog, or set of tickets run to done
  with Agent Teams. For a single PR use pr-review-merge instead; not for one-off single-task
  work.

<!-- floor:cold-verify-completion -->

Marathon Engine

Source-agnostic team orchestration. The caller supplies a **work-source adapter**; this skill owns DAG analysis, hot-file combining, team lifecycle, waves, crash recovery, and the retrospective. It uses the `pr-review-merge` skill for every PR.

Work-Source Adapter Contract

The calling command MUST fill these four operations before invoking this skill:

| Operation | What it returns / does | |-----------|------------------------| | **enumerate** | A list of work units, each `{id, title, requirements, dependencies[], complexity}` | | **mark in-progress** | Marks one unit started in the source of truth | | **close on merge** | How a merged PR closes the unit (e.g. a label, a status set, or PR `Closes #N`) | | **branch / worktree** | The branch name and `worktree/<...>` path convention for a unit |

The caller also passes Marathon Configuration values (base branch, required approvals, bot-reviewer rules, CI patterns) read from the project's CLAUDE.md.

Phase 0: Capability Detection

# Agent Teams
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Set `$TEAMS_AVAILABLE` (`true` if result is `"1"`).

Project-Specific Configuration

Read the repo's CLAUDE.md for a `## Marathon Configuration` section. This provides project-specific overrides for marathon behavior. Extract these values (with defaults if section is missing):

| Setting | Default | Description | |---------|---------|-------------| | `$BASE_BRANCH` | `main` | Branch to create worktrees from and merge PRs into | | `$REQUIRED_APPROVALS` | 1 | Minimum approvals for auto-merge | | `$MARKDOWN_APPROVALS` | 1 | Approvals for markdown-only PRs | | `$RETRO_LOG` | (none) | Path to retrospective log file | | Bot reviewer rules | (none) | Per-bot thread resolution patterns | | CI patterns | (none) | Known flaky checks, pre-existing failures |

If no Marathon Configuration section exists, **advise the user to set one up — this is non-blocking; emit the notice and proceed with defaults** (do not wait for an answer):

No Marathon Configuration found in this project's CLAUDE.md.

For best results, add a ## Marathon Configuration section to your project's CLAUDE.md.
Run `/tm-marathon-config-example` to see the configuration template (it covers both /tm and /issues), then copy and customize it for your project.

Proceeding with defaults: base branch=main, 1 approval, no bot reviewer rules.

Defaults apply for non-marathon use (single task mode, planning mode) without prompting. The template below uses `$BASE_BRANCH` where previous versions hardcoded `develop`.

Execution Modes

The steps below are written for **team mode** — the lead chairs an Agent Team, spawns one ephemeral teammate per unit, and coordinates via `SendMessage` and `shutdown_request`. Phase 0's `$TEAMS_AVAILABLE` selects the mode:

| Mode | When | How the body maps | |------|------|-------------------| | **Team** | `$TEAMS_AVAILABLE` true | Run the body as written: spawn one background teammate (`Agent` with `run_in_background`) per unit/combined group into the session's single implicit team, message-driven monitoring. | | **Phased sub-agent** | `$TEAMS_AVAILABLE` false | No persistent team and no `SendMessage`. The lead runs each wave as a batch of parallel subagents, reads their returned transcripts in place of messages, and drives the same loop. See [Subagent Fallback](#subagent-fallback-no-teams). |

Everything else — the DAG analysis, hot-file combining, tracking file, smart-merge, crash recovery, and retrospective — is identical across modes; only the teammate-coordination mechanism differs. Where a step is team-only (the `SendMessage` events, early-shutdown, and idle-ping handling), the phased fallback simply has no equivalent: subagents return rather than message.

**One team per session.** This build allows exactly one implicit team per Claude Code session, and the main session is its permanent lead. A team-mode marathon claims that single team - so do not start another team-mode skill (a second marathon, a `/huddle`) in the *same* session: its teammates would join this marathon's team and share one task list and mailbox. To run two team-mode workstreams at once (two PRDs in flight, or a huddle defining the next PRD while this marathon implements the current one), use a *separate* session - a second terminal with its own worktree. Each session gets its own isolated team (`session-<id>`-named), lead, task list, and mailbox. (Cross-session, the only shared state to watch is Task Master's global tag selection: pass `--tag` on every call or use the MCP tools so two concurrent marathons don't stomp each other's active tag.)

Entry Gate (non-removable)

Before decomposing the run (Step 1), the acceptance contract must be frozen. Invoke the start gate first:

The contract scripts live in the plugin package (`${CLAUDE_PLUGIN_ROOT}/scripts/contract/`), while the contract artifacts (contract, kill test, completion record) live in the target repository's `.claude/contracts/` by default. Every contract script resolves the folder the same way: its `--contract-dir` flag, then the `ACCEPTANCE_CONTRACT_DIR` environment variable, then the default, so setting the variabl