bmad-auto

# 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, and rules. Pass them in every Delegation Packet's _Knowledge sources_ slot. 1. **BMAD project context**: `_bmad-output/project-context.md` (or `**/project-context.md`) 2. **Custom project rules**: `.knowledge-base/`, `.knowledge/`, `.standards/`, `.conventions/`, `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `AGENTS.md`, `GEMINI.md` Collect found paths into `{KNOWLEDGE_PATHS}`. ### Category B — Leader's own memory / second-brain (leader uses for decisions) These describe the _user's_ preferences, prior decisions, and accumulated lessons across projects. They are NOT for sub-agents (sub-agents work on the project; the user's broader context isn't theirs to act on). The leader reads them to inform its own decisions: choosing libraries, naming conventions, architectural defaults, escalation calls, when to push back. Look for any of these the host environment provides: - **Auto-loaded into the leader's context already**: identity blocks, soul/personality blocks, MEMORY index, daily logs, decision logs, SOUL.md, IDENTITY.md, vault trees. If you can already see them in your context, they count. - **Vault / memory directories**: a memory-dir env var (e.g. `$MEMORY_DIR` or a host-provided cache path), `~/.claude/memory/`, `~/.codex/memory/`, `~/.cursor/memory/`, project-relative `memory/`, `second-brain/`, `vault/`. - **Memory MCP tools**: `mcp__*memory*__memory_search`, `mcp__*memory*__memory_add`, or any tool whose name includes `memory_search` / `memory_recall` / `vault_search`. Use these for semantic lookup before falling back to research. - **Memory skills**: any memory/knowledge-base skill the host exposes (e.g. `superpowers:using-superpowers`, which exposes a memory index), or any skill whose description mentions a personal knowledge base. Collect found sources into `{MEMORY_SOURCES}`. If empty, that's fine — `{MEMORY_SOURCES}` simply doesn't apply this session. ### Memory-first decision rule When the leader needs to make a research-style decision — _which library, which pattern, which default, has the user solved this before_ — the order is: 1. **Check `{MEMORY_SOURCES}` first.** Search the vault, query the memory MCP, scan the auto-loaded MEMORY index. If the user has a prior decision on this exact topic, use it. Cite it briefly when you act ("Per `decisions/db-runtime-choices`, using SQLite + WAL" beats "I picked SQLite"). 2. **Check `{KNOWLEDGE_PATHS}` next.** The project rules may already mandate a choice. 3. **Only if neither has the answer, escalate to research.** That's when `tech-researcher` becomes appropriate (subject to the spawn gate in `references/escalation.md`). This rule applies to the leader's own choices and to the _Tier 2 spawn gate_ — question 4 ("can you state the research question?") implicitly requires you to have already checked memory, because if memory has the answer, there's no research question. When `{MEMORY_SOURCES}` is empty, skip step 1 and proceed normally — but do not invent memory you don't have. ### What to pass to sub-agents Pass `{KNOWLEDGE_PATHS}` (Category A only). Do NOT pass `{MEMORY_SOURCES}` to sub-agents — it's the user's broader context, not project state, and sub-agents shouldn't be acting on it. --- ## Model Selection (for sub-agent spawns) If your chosen mode does not spawn sub-agents (`main`), skip this section. At startup, run detection once: **Claude Code (any provider):** if `ANTHROPIC_DEFAULT_OPUS_MODEL` is set, you're on CC. Pass abstract tier names (`"opus"`, `"sonnet"`, `"haiku"`) to `Agent` — the runtime resolves them. Never hard-code IDs like `claude-opus-4-7`. **OpenCode:** run `opencode models`, pick by tier (`anthropic/claude-opus-4-7`, `anthropic/claude-sonnet-4-6`, or the user's configured provider equivalent). **Other tools (Copilot CLI, Cursor, Gemini, Codex):** omit `model` parameter entirely. **Effort support:** if `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` contains `effort`, set `{EFFORT_SUPPORTED}=true`. Otherwise omit effort everywhere. **Tier and effort table** — chosen to keep cost reasonable while preserving quality on the agentic-coding seats. The "Effort (1M)" column applies _per sub-agent tier_ — if the user said only some tiers are 1M, dial effort down only on those tiers and use the 200k column for the rest. (Effort itself is only settable on direct API / OpenCode; in Claude Code, encode the intent in the prompt body — see Step 0 about model resolution.) | Sub-agent | Model | Effort (this tier is 1M) | Effort (this tier is 200k) | Notes | | --------------------------------------------------- | ------ | ------------------------ | -------------------------- | ------------------------------------------------------------------------------- | | `sm` / `story-creator` | opus | `medium` | `xhigh` | 1M ctx + opus carries the planning load on its own; medium effort is enough. | | `developer` / `story-developer` / `quick-developer` | sonnet | `medium` | `xhigh` | 1M ctx absorbs the codebase; medium effort is enough for execution work. | | `tester` / `func-validator` | sonnet | `high` | `high` | Validation needs to actually catch bugs — keep effort up regardless of context. | | `tech-researcher` (escalation) | opus | `xhigh` | `xhigh` | Escalation = hard problem; give it room regardless of context. | **Story validation and code review are the leader's job** in every mode — there is no `story-validator` or `code-reviewer` sub-agent. The leader has the full session context and the cheapest path to a correct decision. --- ## Working Directory and Document-First Handoffs Two non-negotiable rules that apply to every sub-agent in every mode: ### 1. Always spawn at the project root Every `Agent` call must be issued from the project root — the directory the user invoked `bmad-auto` from (the same directory that contains `_bmad-output/`). Never spawn a sub-agent while your shell is `cd`'d into a subfolder; sub-agents inherit cwd and a wrong cwd makes every relative path in the story file (`tasks/`, `_bmad-output/...`, `src/...`) resolve incorrectly. In the spawn prompt's _Project Context_ section, **state the project root explicitly**: ``` ## Working directory You are operating at the project root: <absolute path, e.g. /Users/me/Works/foo> All paths in this prompt and in the story file are relative to this root unless absolute. Do NOT cd into subdirectories — run commands from this root and use relative paths from here. ``` If the leader needs to run a command itself (build, test, git), do it from project root too. The only legitimate `cd` is into a temporary scratch dir for one-off operations the sub-agents won't touch. ### 2. Document-first handoffs (heavy context lives in files, not messages) Sub-agents do their thinking in **files**, not in `SendMessage` payloads. The pattern: - **Developer finishes a story** → writes the full implementation summary, decisions made, files touched, test results, deferrals, and any noteworthy reasoning into the **story file's Dev Notes / Dev Agent Record section** (the slot the BMAD `bmad-create-story` workflow generated). Then sends a _short_ message back: `"Done. Story file: <path>. Status: <review|blocked>. Headline: <one line>."` - **Tester finishes validation** → appends results to a **QA Results / Validation Results section** in the same story file, with PASS/PARTIAL/FAIL, command output snippets, and any warnings. Sends a short message: `"Validation: <PASS|PARTIAL|FAIL>. See QA Results in <path>."` - **SM finishes story creation** → the workflow already produces the story file; SM just reports `"Story file: <path>. Ready for leader validation."` - **Leader finishes code review** → writes review findings into a **Review Notes section** of the story file before sending a fix-request to the developer. The fix-request packet then says _"see Review Notes in <story_file>"_ instead of pasting 200 lines of findings into the message.