/tm

name: tm
disable-model-invocation: true
description: Task Master - plan, start, review, and close
argument-hint: [tag [task-id] | feature description] (optional - derives context from worktree if omitted)

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

Task Master Orchestrator

**$ARGUMENTS**

> Thin orchestrator. Delegates to subagents for implementation and review loops. > > **Planning Mode** (`/tm use stripe as kyc provider`): When args don't match an existing tag, explores the codebase, writes a PRD, creates a tag, generates tasks, runs complexity analysis, and expands. Stops after planning - run `/tm <tag>` to start work. > > **Marathon Mode** (`/tm <tag>`): When only a tag is given (no task-id), automatically progress through all ready tasks. > When Agent Teams are available, each task gets its own teammate with shared task list. > When teams unavailable, falls back to parallel subagents. > PRs auto-merge when CI green, no conflicts, required approvals met, and 0 changes requested.

---

TM Work-Source Adapter

This command supplies the marathon skill's adapter as:

• **enumerate** — `task-master tags use "<tag>" && task-master list --json`; use `jq` on `tasks.json` for reliable status filtering (`task-master next` can suggest subtask IDs of done parents).
• **mark in-progress** — `task-master set-status --project ~/dev/github.com/<org>/<repo> --id=<id> --status=in-progress` (run sequentially inline — never as a parallel background job; concurrent TM writes race the global tag). **Every TM write passes `--project <container root>`**: `set-status` has no `--tag`, the shell cwd persists across calls, and a write run from `<repo>-main/` or a worktree prints its banner but writes nothing. Re-read `tasks.json` after each write to confirm.
• **close on merge** — `task-master tags use "<tag>" --project ~/dev/github.com/<org>/<repo> && task-master set-status --project ~/dev/github.com/<org>/<repo> --id=<id> --status=done` (same rule: sequentially inline, never in parallel - `tags use` switches the shared active tag, so an interleaved write lands on the wrong tag).
• **branch / worktree** — branch `<tag>--<task-id>--<slug>`; worktree `worktree/<tag>/<task-id>--<slug>`.

---

Phase 0: Detect Capabilities

# 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, **prompt the user to set one up before starting marathon mode**:

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 template, then copy and customize it.

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`.

---

Phase 1: Detect Context and Mode

**Parse arguments to determine mode:**

• No arguments → Report mode
• One argument that matches an existing TM tag → Marathon mode (`$MARATHON_MODE = true`)
• Two arguments (tag + task-id) → Single task mode
• **Arguments that don't match any existing tag** → Planning mode (`$PLANNING_MODE = true`)

**Tag match check** (use tasks.json directly - CLI output has formatting that breaks grep):

cd ~/dev/github.com/<org>/<repo>
FIRST_ARG="<first-argument>"
jq -e --arg tag "$FIRST_ARG" '.[$tag]' .taskmaster/tasks/tasks.json >/dev/null 2>&1 && echo "TAG_EXISTS" || echo "NEW_IDEA"

**If NEW_IDEA, search for existing PRD in the repo:**

cd ~/dev/github.com/<org>/<repo>/<repo>-main
# Search common PRD locations and filename patterns
fd -t f "$FIRST_ARG" --extension md . | head -5
# Also check conventional path
ls .taskmaster/prd/$FIRST_ARG.md 2>/dev/null

• File found → `$PLANNING_MODE = true`, `$PRD_EXISTS = true`, `$PRD_FILE = <path>`
• No match → `$PLANNING_MODE = true`, `$PRD_EXISTS = false`

**Early routes:**

• If `$PLANNING_MODE`: Jump to [Planning Mode](#planning-mode)
• If `$MARATHON_MODE` AND `$TEAMS_AVAILABLE`: Jump to [Marathon Mode: Agent Teams](#marathon-mode-agent-teams)

**Check context in order:** 1. Current directory - pwd matches TM worktree pattern? 2. Conversation context - Recent "📍 Current Work" footer with worktree path? 3. Arguments - Explicit tag/task-id provided?

Detect Worktree Pattern

pwd | grep -q '/worktree/[^/]*/[^/]*--' && echo "IN_WORKTREE" || echo "NOT_IN_WORKTREE"

**If IN_WORKTREE**: Extract tag and task-id from path, proceed with PR check. **If NOT_IN_WORKTREE but conversation shows active work**: cd to the worktree.

**Decision tree:**

Is current directory a TM worktree?
(Pattern: worktree/<tag>/<task-id>--<slug>)
│
├─ YES → Check PR state
│   ├─ PR merged → CLEANUP mode
│   ├─ PR open   → REVIEW mode
│   └─ No PR     → IMPLEMENT mode
│
└─ NO → START mode
    ├─ Args match existing tag → Marathon or single task
    ├─ Args don't match any tag → PLANNING mode
    └─ No args → Report ready tasks

**CRITICAL: Never auto-start new tasks.** Conversation context can continue existing work, but starting a NEW task requires explicit `$ARGUMENTS`.

Check PR Stat