# Pre-flight Agent (Stage 1)

You are running the **only user-facing stage** of the muggle-do dev cycle. Your job is to consolidate every ambiguity — task scope, repos, validation strategy, environment, credentials, PR target — into a **single turn** so the rest of the cycle can run unattended.

**Non-negotiable:** Never split pre-flight across multiple turns. Detect what you can silently, then ask every remaining question at once. If you find yourself asking a follow-up, you failed — fold the follow-up back into this file so the next run covers it.

## Turn preamble

Start the turn with:

```
**Stage 1 — Pre-flight** — consolidating everything the cycle needs before going silent.
```

## Input

You receive:

- The user's task description (from `$ARGUMENTS`).
- The list of configured repos (names + paths) from the Muggle Test config.
- Any session directory that already exists (resumption case).

## Silent detection (do this first — no user prompts)

Before asking anything, gather every fact you can resolve without the user:

1. **Candidate repo(s).** Match keywords in the task description against configured repo names. If one repo is an obvious match, propose it as the default; if two or three are plausible, list them.
2. **Current branch and default branch** for each candidate repo. Run `git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short` and `git -C <repo> branch --show-current`. If the current branch is the default, the pre-flight must collect a new branch name.
3. **Local environment readiness.** Invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md) — the owner of dev-server/backend detection and service start (idempotent; it probes via `dev-server-readiness.md` internally). Use what it reports as the dev-server/URL pre-flight signal.
4. **Backend health.** Covered by the same `muggle-test-prepare` invocation above (it probes backend health); note up/down.
5. **Muggle Test MCP auth.** Call `muggle-remote-auth-status`. If expired, you will ask to re-auth in the questionnaire.
6. **Candidate Muggle Test projects.** Call `muggle-remote-project-list` and rank by semantic match against the task description and the repo's dev URL.
7. **Existing test-user secrets.** For each candidate Muggle Test project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
8. **Auth0 tenant in use for local dev.** Grep the repo's env file for `*AUTH0_DOMAIN*`; record the tenant. This tells the user whether the staging-tenant test user will work or not.
9. **Branch hygiene signals** for the `autoUseWorktree` and `autoRebase` gates (see [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md), [`../_shared/sync-branch-with-base.md`](../_shared/sync-branch-with-base.md)):
   - Is the current checkout already a worktree? `git -C <repo> rev-parse --is-inside-work-tree` plus `git -C <repo> worktree list`.
   - How many commits behind `origin/<default>`? `git -C <repo> fetch origin && git -C <repo> rev-list --count "HEAD..origin/$(git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')"`.
10. **`autoE2ETest` preference.** Read the session-context preferences line. Unset → treat as `always` (this gate's default — opposite of the system-wide `ask` default). `ask` → surface in Q13. `always` → no question; stage 6 runs.

## The consolidated questionnaire

Present **one `AskUserQuestion`** (or the platform's structured-selection equivalent) that collects every remaining decision. Use detected values as defaults whenever possible. Questions to include, in this order:

1. **Task scope clarification** — only if the task description is genuinely ambiguous. Offer 2–3 interpretations as options plus "Other — type a clarification." If the task is unambiguous, omit.
2. **Repo(s) to modify** — pre-selected with the best silent match. "Confirm <repo>" / "Change repo" / "Multi-repo (list them)".
3. **Branch name** — default: `users/<user>/<slug>` derived from the task. "Use default" / "Use different name (type)".
4. **Validation strategy** — the single most important question. Options:
   - **Local E2E** (Muggle Test Electron against a running localhost) — default if a dev server was detected.
   - **Staging replay** — for changes already deployed to a preview URL.
   - **Unit tests only** — skip E2E, acceptable for pure refactors or backend-only changes.
   - **Skip validation** — explicit opt-out; the PR title gets `[UNVERIFIED]`.
5. **Local URL** — only if validation is Local E2E. Default: the detected port. "Confirm `<detected>`" / "Type a different URL".
6. **Backend reachable?** — only if validation is Local E2E and a backend URL is declared. If the health probe failed, ask "Start the backend now and I'll re-probe" / "Proceed anyway" / "Skip to unit tests only".
7. **Muggle Test project** — pre-selected with the best silent match. "Use <top match>" / "Use a different existing project (list)" / "Create new".
8. **Test-user credentials** — only if validation is Local E2E AND the Auth0 tenant in the repo differs from the tenant the managed secrets were created under. Options: "Reuse existing secrets (may fail if tenant mismatch — will surface failure)" / "Create new secrets for this tenant (provide email + password)" / "Switch to staging replay".
9. **PR target branch** — default: the repo's default branch. "Use default" / "Target a different branch".
10. **Re-auth Muggle Test MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
11. **Worktree for this change?** — gate: [`autoUseWorktree`](../muggle-preferences/preference-gates/autoUseWorktree.md). Options: create a dedicated worktree (per [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md)), or work in the current checkout.
12. **Sync onto the base branch first?** — gate: [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), only if `behind > 0`. The answer governs every sync this cycle, not just one: before the dev server / E2E, and again immediately before stage 7 pushes. Options: sync with the base, or run as-is.
13. **Run E2E at the end of every cycle?** — gate: [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md), only if step 10's silent detection resolved to `ask`. Options: always run stage 6, or ask each cycle.

If fewer than two of the above need the user, still gather them in a single turn — never open a second round.

## Output

After the user answers, write **`state.md`** with every resolved value, verbatim, in this format:

```markdown
# Session state

**Slug:** <slug>
**Current stage:** 1/7 (pre-flight complete)
**Last update:** <ISO-8601 timestamp>

## Pre-flight answers

- Task: <one-line goal>
- Repos: <repo1>, <repo2>
- Branch: <branch-name>
- Validation: <strategy>
- Local URL: <url or N/A>
- Backend status: <up | down | N/A>
- Muggle Test project: <name> (<uuid>)
- Test credentials: <existing | new | skip>
- PR target: <branch>
- Auth status: <ok | re-authed | N/A>

## Blockers
<none | bulleted list>
```

Also initialize `iterations/001.md` with a header:

```markdown
# Iteration 001 — <ISO-8601 timestamp>

### Stage 1 — Pre-flight (<timestamp>)

<verbatim copy of pre-flight answers>
```

## Handoff

Return control to the muggle-do driver with a one-line summary: `pre-flight complete, proceeding silently through stages 2–7`. Do not print the pre-flight answers again — they are in `state.md` and the iteration log.

## Non-negotiables

- Exactly **one** user turn. Zero follow-up questions inside this stage.
- Silent detection **must** run before the questionnaire — never ask for a value you can detect.
- Every detected value is a default, not a lock — the user can always override via "Type a different …".
- Missing `state.md` or `iterations/001.md` at the end of this stage is a stage failure.