feature-autopilot

What this skill does

# Feature Autopilot

End-to-end runbook for taking an `idea.md` entry in `docs/features/<id>/` and landing the change on the configured base branch. Chains the existing per-phase skills, gates on the configured reviewer between phases, and auto-advances when the reviewer is happy.

This skill **does not replace** `feature-plan`, `feature-implement`, `feature-review-plan`, `feature-review-impl`, or `feature-ship`. It calls them in order and adds the wait/classify/auto-advance logic between phases.

**Multi-repo workspace?** If the root has a `.feature-workspace.yml`, a single-member feature autopilots from inside that member (`cd <member>` first). A cross-repo **epic** (children as `repo:id`) dispatches each child into its member — see [epic-dispatch.md](epic-dispatch.md) and [../shared/workspace.md](../shared/workspace.md).

## When to use

- User says "ship feature X", "autopilot X", "drive X end-to-end"
- User wants the full pipeline run without per-phase prompting
- An idea is captured and ready to plan + ship without further design discussion

## When NOT to use

- The plan needs design discussion → use `/feature-plan` directly first, then optionally autopilot from review onward
- The user is iterating on a single phase (e.g. just responding to review feedback) → use the per-phase skill directly
- No `idea.md` exists → run `/feature-capture` first
- The user wants a different review path than what's configured — edit the `review:` field in the feature's `idea.md` frontmatter (`external` / `internal` / `skip`) BEFORE running autopilot.

## Preconditions

Verify in this order before starting:

1. **`docs/features/<id>/idea.md` exists.** If not: tell the user to run `/feature-capture` first.
2. **Working tree is clean** on the configured base branch. Run `git status` — if anything unrelated is modified or untracked, ask the user before doing anything (don't auto-commit). Rationale: `feature-plan` branches off current HEAD, so a dirty tree drags unrelated work onto the feature branch.
3. **Local base branch is in sync with origin.** Run:
   ```bash
   "${CLAUDE_PLUGIN_ROOT}/skills/feature-autopilot/scripts/check-base-sync.sh" <base-branch>
   ```
   Exit semantics:
   - `0` — in sync, proceed
   - `1` — local is **ahead** of origin (unpushed work). **Pause and surface to user.** Branching off an ahead-base means the upcoming PR will include those unpushed commits, which is almost certainly not what the user wants. Recommend: push first OR investigate which commits don't belong on the base.
   - `2` — local is behind origin. Run `git pull origin <base>` and re-check.
   - `3` — diverged. Manual resolution required; do not proceed.
   - `4` — usage error (typo in base name, branch doesn't exist locally, etc.).

   This catches the "parallel Claude Code session left unpushed commits" failure mode.
4. **Read `.feature-workflow.yml`** for the `reviewer:` setting. The autopilot adapts:
   - `reviewer: gemini` or `reviewer: codex` — review gates are active. The `feature-review.yml` GitHub Action fires on the `plan-review` / `impl-review` label and posts a comment classifiable by `wait-for-review.sh`.
   - `reviewer: none` — review gates are skipped. Autopilot goes plan → implement → ship without polling for external review.
5. **Read `.feature-workflow.yml`** for the `base_branch:` setting (default `main`). Use this as the merge target.

## Step 0: Epic vs. Feature Detection

Before the linear pipeline below, read `docs/features/<id>/idea.md` and check the `type:` field. If `type: Epic`, switch to **Epic Dispatch Mode** — see [epic-dispatch.md](epic-dispatch.md) — and stop here. The linear pipeline below applies only to regular features.

| `type:` value | Behavior |
|---|---|
| Feature / Enhancement / Bug Fix / Tech Debt | Standard linear plan → review → implement → review → ship (below) |
| Epic | Epic Dispatch Mode — walk children in topo order via `epic-dispatch.md` |

The dispatcher walks each child via its own subagent (running `/feature-autopilot <child-id>`) in its own worktree per the Worktree Isolation rule. Sequential by default; pass `--parallel` to the autopilot invocation for concurrent waves.

## Steps

### 1. Plan

```
/feature-workflow:feature-plan <id>
```

Creates `docs/features/<id>/plan.md` with implementation steps, test approach, acceptance criteria, and open questions.

**Gate before moving on.** Read the plan back to yourself. Does the step list match the idea's intent? Any obvious gaps or scope creep? If the plan looks wrong, stop and surface it to the user — don't proceed to review/implement a bad plan. Edit `plan.md` directly or re-run the skill.

### 2. Plan review (skip if `reviewer: none`)

```
/feature-workflow:feature-review-plan <id>
```

Creates the feature branch, opens a draft PR, and applies the `plan-review` label. The CI reviewer picks up the label, runs against the plan, and posts a comment prefixed `## Plan Review` with a `### Verdict: PASS|CONDITIONAL PASS|FAIL` line.

**Don't idle-wait — poll:**

```bash
"${CLAUDE_PLUGIN_ROOT}/skills/feature-autopilot/scripts/wait-for-review.sh" <PR#> plan
```

Blocks on `gh pr checks --watch` and classifies the verdict. Exit semantics:

- **0 — PASS / CONDITIONAL PASS**: auto-advance to Step 3 (implement). **Do NOT chase Should-fix items after a clean pass** — recommendations can be filed as follow-up backlog items if material (see "Defer to backlog" in `respond.md`).
- **1 — FAIL**: **auto-respond.** The whole point of autopilot is to drive through review cycles without manual intervention. Invoke `/feature-workflow:feature-review-plan <id> --respond` immediately, push the changes, and loop back to wait-for-review. See "FAIL handling" below for the retry cap and escalation rules.
- **2 — workflow failure / timeout / no review comment**: pause. Diagnose with `gh run list --branch feature/<id>` and `gh run view <run-id>`. Common causes: missing `GEMINI_API_KEY` / `OPENAI_API_KEY` secret, transient reviewer error, required check failing unrelated to the review. Once fixed, re-trigger by removing and re-adding the `plan-review` label.

### FAIL handling — auto-respond loop

Autopilot's job is to drive review cycles, including FAIL → respond → re-review. Default cap: **2 consecutive FAILs on the same phase before pausing for the user.**

```
FAIL #1 → run --respond → push → re-poll
FAIL #2 → run --respond → push → re-poll
FAIL #3 → STOP. Surface findings to user, ask for direction.
```

The cap exists because if the reviewer rejects the same plan/implementation twice after revisions, the issue is probably one of:
- A genuine design tradeoff the user needs to weigh in on
- A reviewer-implementer disagreement that needs human arbitration
- Scope creep the autopilot can't resolve via defer-to-backlog

When invoking `--respond` autonomously, the autopilot should:
- Use the **Defer to backlog** classification freely for findings that expand scope past the current `idea.md` — this is the autopilot's main escape valve. See `respond.md` for the classification matrix.
- Use **Disagree** sparingly. Autopilot disagreement should be reserved for findings that contradict the plan's stated constraints or ask for code that already exists. When unsure, prefer Agree (fix it) or Defer (capture for later).
- After 2 FAILs, stop and print: the verdict line, Summary, Critical Findings, and a one-line note on which classifications were tried each round. Ask the user: continue with `--respond` (override the cap), override the verdict ("ship anyway — I disagree with finding X"), or halt.

The cap is per-phase. Plan review and impl review have independent counters; a clean impl review after 2 plan-review FAILs is fine.

### 3. Implement

```
/feature-workflow:feature-implement <id>
```

Executes `plan.md` step by step. Between steps: run the relevant tests, then mark the step complete via `/feature-workflow:tracking-progress`.

**Guardrails during implementation:**
- If a step's scope drifts, use `/featur