player-coach

What this skill does

# Player-Coach: Adversarial Cooperation Loop

You are the orchestrator of a player-coach loop. The player implements code, `/verify --mode=report-only --scope=branch` runs the full verification pipeline against all branch changes, and then (by default) a PR is created and CI must pass. The loop ends when a PR exists with green CI — or when `--no-pr` is set, after verification is clean.

There is no separate coach skill. The verify skill runs all verification skills and produces the report. You apply the severity threshold mechanically.

## Phase 0: Pre-Loop Setup

### 1. Check that a plan exists

The plan file is the requirements document for this loop. Without it, there's nothing to implement.

```bash
ls .claude/plans/*.md 2>/dev/null | head -5
```

If no plan exists, tell the user:
> "The player-coach loop needs a plan to work from. Create one first with `/plan` or enter plan mode. The plan should describe what you want implemented — requirements, constraints, tech stack, expected behavior."

Then STOP.

### 2. Read the plan

Read the plan file. You need a basic understanding of what's being built to ask good clarifying questions. Note the plan file path — you'll pass it to the player skill.

### 3. Parse arguments

Check `$ARGUMENTS` for:
- `--max-turns=N` — maximum iterations
- `--severity=N` — minimum severity threshold for issues that must be fixed
- `--no-pr` — skip PR creation and CI checking (just run the verify loop)

### 4. Clarify with the user

Use `AskUserQuestion` to fill in anything not specified. Only ask what's genuinely needed — don't ask for the sake of asking.

**Always ask (if not in arguments), using the EXACT format below:**

- **Max turns** — ask with these exact options:
  - `5` — quick (small fixes, focused tasks)
  - `10` — standard (typical features) **[default]**
  - `20` — thorough (large features, complex changes)

- **Severity threshold** — ask with these exact options:
  - `3` — strict (fix almost everything)
  - `5` — moderate (fix meaningful issues) **[default]**
  - `7` — lenient (only fix critical/high issues)

**Ask only if the plan is unclear about:**

- Scope or ambiguity in requirements
- Missing critical information the player will need
- Anything that would cause the player to get stuck

### 5. Confirm and start

Briefly summarize the configuration to the user:
> "Starting player-coach loop: [max_turns] turns, severity threshold [N], PR+CI [enabled/disabled]. Plan: [1-line plan summary]"

## Phase 1: The Loop

```
Initialize:
  turn = 0
  feedback = ""
  feedback_history = []
  sticky_issues = {}        # VI-IDs that reappear across turns → friction signals
  player_concerns = []      # non-"none" remaining concerns from player reports
  ci_failures_log = []      # CI failure details for journey narrative
  phase = "verify"          # "verify" or "ci"
  pr_url = ""
  pr_enabled = true         # false if --no-pr
```

For each turn (1 to max_turns):

### Step 1: Invoke the Player

Use the Skill tool to invoke `player` with a fresh context:

**Prompt template:**
```
You are the player skill on turn {turn} of {max_turns} in a player-coach loop.

Plan file: {plan_file_path}
Severity threshold: {severity}

{if turn == 1}
This is turn 1. There is no previous feedback. Implement the plan from scratch.
{else}
Verification feedback from turn {turn - 1} that you must address:

{feedback}
{endif}
```

Wait for the player to complete. Extract the PLAYER REPORT from the result.

**Output to the user immediately after the player completes:**
```markdown
## Turn N/M — Player Report

**Changes:**
- path/to/file.ts — what was changed
- path/to/other.ts — what was changed

**Build:** pass/fail
**Tests:** X passed, Y failed
**App starts:** yes/no/N/A
**Concerns:** [any remaining concerns from player report, or "none"]
```

### Step 2: Run Verification

Invoke the report-only verification pipeline via the Skill tool:

```
/verify --mode=report-only --scope=branch
```

**CRITICAL: Always use `--scope=branch`.** This ensures every turn verifies the FULL set of changes from the entire plan — not just the latest fix. Without this, later turns only scope to the most recent unstaged changes, causing verifiers to lose the bigger picture (architecture, coherence, cross-cutting concerns). The verifiers need to see everything.

This runs ALL verification skills (tester, exerciser, reviewer, qa, codex-reviewer, ux-reviewer, and any others in the verify pipeline), deduplicates findings, and produces a unified verification report with VI-{n} issue IDs and severity ratings. It does NOT fix anything — that's the player's job on the next turn.

The verify skill handles skill invocation, parallelism, deduplication, and reporting. No need to manage helper lists here — if verify adds new skills in the future, they're automatically included.

**The exerciser must run every single turn.** The exerciser does a real E2E smoke test — it starts the application, uses the feature, and checks data flows. Tests passing is not sufficient; the feature must actually work end-to-end with real interactions. Do not rationalize skipping it ("the changes were small", "just a fix", "saving time") — the exerciser runs every turn because any code change can break E2E behavior in ways that unit tests miss. If the verification report comes back without an exerciser row in the Skill Results Summary, treat verification as incomplete and re-invoke verify.

Wait for verify to complete.

### Step 2.5: Continuation anchor (REQUIRED — do not skip)

Immediately after verify returns, before any summary markdown, run this bash command with the actual values substituted for `{turn}`, `{max_turns}`, and `{severity}`:

```bash
echo "VERIFY RETURNED (turn {turn}/{max_turns}, phase=verify). NEXT ACTION: apply severity threshold {severity}. If any issues >= threshold → call Skill(player) for turn {turn+1} with feedback. If zero issues at/above threshold → check exerciser/custom/codex gates then proceed to Phase 1.5 (PR). DO NOT stop here. The loop continues until PR+CI green, --no-pr approval, or turn limit."
```

This step exists because Opus 4.7 treats verify's polished report as a natural end and tends to hand control back. The echo places the continuation instruction adjacent to the verify result in context — without it, the model reads the report as done and stops. Do not skip this, even if it feels redundant with the CRITICAL note below.

**Output to the user (after Step 2.5):**
```markdown
## Turn N/M — Verification Complete
```
The verify skill already outputs its own detailed report (skill results table + deduplicated issues table), so just add the turn context header above it.

**CRITICAL: The verify skill will output its report and return. After it returns, YOU (the player-coach) MUST run Step 2.5 (continuation anchor) and then continue to Step 3 — apply the severity threshold and decide whether to loop. Do NOT stop here.**

### Step 3: Apply severity threshold and decide

This is mechanical — no judgment call needed.

**Extract the issues from the verification report. Count issues at or above the severity threshold.**

**Friction tracking (do this every turn, before the APPROVED/FEEDBACK decision):**

1. **Sticky issues**: Compare this turn's issues against the previous turn's feedback by title, location, and description — NOT by VI-ID (VI-IDs are sequential counters regenerated each run, so VI-1 in turn 1 and VI-1 in turn 2 are unrelated). If an issue from this turn matches a previous turn's issue by content (same file/location, same root cause), add it to `sticky_issues` with both turn numbers. These are issues the player failed to fix on the first attempt — a friction signal.
2. **Player concerns**: If the player report's "Remaining concerns" section lists any items (is not empty, "none", "N/A", or similar), append it to `player_concerns` with the turn number.

**EXERCISER GATE (check this before the APPROVED/FEEDBACK decision):**

Look at the verification report's