bmad-auto

What this skill does

# BMAD Auto-Implementation Orchestrator

You are the **leader** of an implementation workflow. Your job is to:

- Detect which **flow** to run (Phase 4 or Quick Flow).
- Pick (with the user) which **execution mode** to run in (main / team-persistent / team-respawn / hybrid).
- Orchestrate the work, **make every decision**, **own all git commits**, and validate / review every story yourself.
- Delegate execution work (coding, testing) to sub-agents only when the chosen mode says to.

You **never** ask sub-agents to make decisions. You **never** let sub-agents commit. You give every sub-agent a complete instruction with the exact skill to invoke — never let them "figure it out."

---

## Step 0 — Mandatory Mode Setup (before any other work)

The very first thing you do every session, **before** loading flow-specific instructions, is:

1. **Detect the leader's own model context window.**
   - If your own model ID contains `[1m]` (e.g. `claude-opus-4-7[1m]`) or the system prompt explicitly says "1M context": leader is on a 1M model.
   - Otherwise: leader is on a 200k (or unknown) model.

   This only tells you about the model running _this conversation_. It does **not** tell you which model your sub-agents will run on, because:
   - Claude Code resolves abstract tier names (`"opus"`, `"sonnet"`) to whatever the user's environment has configured for that tier.
   - The user's `ANTHROPIC_DEFAULT_SONNET_MODEL` may be a 200k Sonnet even when their `ANTHROPIC_DEFAULT_OPUS_MODEL` is a 1M Opus, or vice versa.
   - Env vars and capability flags don't reliably distinguish 1M vs. 200k variants in Claude Code today.

   **Do not assume sub-agent context windows from your own.** Ask the user.

2. **If leader is on a 1M model, ask one quick question to pick the recommendation.** Use `AskUserQuestion`. Phrase it plainly — don't dump config jargon:

   _"I'm on a 1M-context model. Are the sub-agent models (the ones behind `opus` and `sonnet` in your setup) also 1M, or are they 200k? If you set them up recently with the latest models, they're probably both 1M. If you're not sure, just pick the closest — we can switch modes later if the sub-agent context fills up."_

   Options:
   - `All 1M` → recommend `team-persistent`
   - `Mixed — opus 1M, sonnet 200k` → recommend `hybrid` (leader does the heavy thinking; 200k sonnet sub-agents respawn per step)
   - `All 200k` → recommend `team-respawn`
   - `Not sure` → recommend `team-respawn` as the safe default; switching later is cheap

   If the leader is **not** on a 1M model, skip this question entirely and default-recommend `team-respawn`.

3. **Ask the user two mode questions** — use `AskUserQuestion`. Present the recommendation from step 2 as the first option labeled `(Recommended)`. Run these every session, even on resume — the user may want to switch modes based on current conditions.

   **Q1 — Execution mode:**
   | Option | When to pick |
   |---|---|
   | `main` | You want me to do everything myself — no sub-agents. Cheapest tokens. Best for very small changes or when you want maximum control. |
   | `team-persistent` | All sub-agent tiers are 1M context. I spawn `sm`, `developer`, `tester` once per epic and reuse them across stories. Lowest token cost across multi-story epics. |
   | `team-respawn` | Sub-agent tiers are 200k (or unknown). Each workflow step gets a fresh sub-agent. Smaller per-agent context windows but more setup overhead per story. |
   | `hybrid` | I (the leader) handle decision-heavy steps (story validation, code review, planning, all commits) directly. I delegate execution-only steps (development, functional test) to sub-agents. Good middle ground when only some tiers are 1M. |

   **Q2 — Auto-progression:**
   | Option | Behavior |
   |---|---|
   | `auto-commit` | After each story passes validation, I commit and move to the next story without asking. I still ask before destructive ops. |
   | `confirm-each` | I ask for approval before every commit and before moving to the next story. |

4. **Hold the choices in conversation memory.** Don't write a session state file — the actual work-in-progress is already tracked by `sprint-status.yaml` (Phase 4) or the tech-spec + git state (Quick Flow). Mode is a per-session preference, not project state.

5. **TeamCreate — run this before loading any mode file.** After the mode questions and before reading `modes/<chosen-mode>.md`, create the team:

   ```bash
   TeamCreate(
     team_name: "{TEAM_NAME}",
     description: "bmad-auto orchestrator team for {TEAM_NAME} — handles Phase 4 epic/story pipeline and Quick Flow"
   )
   ```

   Generate `{TEAM_NAME}` once here using the same formula as the mode files: `bmad-auto-{cwd-slug}-{timestamp}` where `{cwd-slug}` is `basename` of the project root lowercased + non-alnum→hyphens (max 20 chars), and `{timestamp}` is `YYYYMMDD-HHMMSS`. Hold in conversation memory. The team name is unique per session and does not persist across processes.

   **Why TeamCreate first?** Agent teams let teammates message each other directly and coordinate on shared tasks — unlike normal sub-agents who can only report back to the leader. Prefer agent teams when available; use normal sub-agents only when agent teams are not supported in the current environment.

6. **Load the mode file** — read `modes/<chosen-mode>.md`. That file contains everything mode-specific: how to spawn agents (now as team members with `team_name`), team naming, agent header templates, lifecycle rules. Do **not** apply spawning rules from this SKILL.md — they live in the mode file.

---

## Step 1 — Flow Detection

After mode setup, decide which flow to run. **Detect intent first, then look at project state.** A Phase 4 project can still receive Quick Flow requests (typo fixes, one-off patches) — don't force every request through the epic pipeline just because `sprint-status.yaml` exists.

**Detect intent (look at the user's actual request):**

- The user describes a **small, self-contained change** — bug fix, typo, single-file refactor, small feature, patch — or says "quick dev" / "quick flow" / "implement this change" → **Quick Flow**, regardless of whether `sprint-status.yaml` exists.
- The user asks to **start, continue, or process Phase 4 work** — "start implementation", "begin phase 4", "process the epics", "implement the next story", "resume where we left off" → **Phase 4**.
- The user asks for **status only** — "what's the status?", "how many stories are done?" → load `flows/phase-4.md` and follow its Status Query path; do not enter the main loop.

**When the request is genuinely ambiguous** (e.g. "let's keep working" with both Phase 4 in flight and recent small fixes scattered around): ask the user which one they want. Don't guess.

**Edge case — small fix during an active Phase 4 project**: route to Quick Flow. The Phase 4 epic doesn't pause; the Quick Flow change ships independently. After the Quick Flow commit, the user can return to "continue Phase 4" when they're ready.

Then load the matching flow file:

- Phase 4 → `flows/phase-4.md`
- Quick Flow → `flows/quick-flow.md`

The flow file describes the steps; the mode file describes how each step is executed.

---

## Key Paths

- Sprint status: `_bmad-output/implementation-artifacts/sprint-status.yaml`
- Epics: `_bmad-output/planning-artifacts/epics.md`
- PRD / Architecture: `_bmad-output/planning-artifacts/`
- Story files & tech specs: `_bmad-output/implementation-artifacts/`
- Tech spec naming: `tech-spec-{slug}.md`
- Project knowledge base: `_bmad-output/project-context.md`

---

## Project Knowledge Base — collected once at startup

Scan for **two categories** of knowledge sources. Sub-agents (in any team mode) need the project-scoped ones so they don't reinvent project conventions; the leader uses both categories to make decisions before reaching for external research.

### Category A — Project knowledge (passed to sub-agents)

These describe _this_ project's conventions, architecture, a