---
name: bmad-autopilot
description: BMAD development driver that works through sprint backlog — creates stories, develops code, reviews, and QA automates each item. Uses Figma MCP for design context. GitHub API is read-only unless full-auto mode is active. Use when the user says "bmad autopilot", "bmad full autopilot", "drive the sprint", "run bmad", "sync sprint", or "manage the project".
---

# BMAD Autopilot

**The BMAD method is the governing framework for ALL work performed by this skill. Every action — story creation, development, review, QA, status tracking, and planning decisions — MUST be framed within and executed according to BMAD methodology. No work is performed outside this framework. Deviating from the method, skipping prescribed phases, or making ad-hoc changes that bypass BMAD artifacts and workflows is prohibited. When in doubt, consult the BMAD planning artifacts and follow the method.**

Active development driver for the BMAD methodology. Reads `sprint-status.yaml`, identifies the next actionable work item, and executes the appropriate workflow phase: create story, develop, review, or QA automate. Runs autonomously through the entire backlog until stopped.

**Autonomy model:** This skill is designed for long-running unattended operation. Proceed through stories continuously without waiting for approval between phases or stories. Only pause for:
- **Blocking ambiguity** — a requirement is contradictory or critically unclear and guessing wrong would waste significant work.
- **Unrecoverable errors** — build failures, test failures, or MCP errors that cannot be self-resolved after one retry.
- **Epic boundary** — briefly report epic completion before starting the next epic.

**Full-auto mode:** Activated when triggered by "bmad full autopilot". In this mode, the GitHub read-only restriction is relaxed for sprint-completion operations (Phase 8). The skill will create PRs, merge them, update issues, and manage branches autonomously at sprint boundaries. Standard autopilot ("bmad autopilot") retains the read-only GitHub constraint and skips Phase 8.

Do NOT pause for routine confirmations, phase transitions, or "Continue? [y/n]" prompts. Keep moving.

**Subagent execution model (MANDATORY — STRICTLY ENFORCED):** Every BMAD workflow phase — story creation (Phase 3), development (Phase 4), code review (Phase 5), and QA automation (Phase 6) — MUST be dispatched to a **separate, fresh subagent** via the `Task` tool. This is non-negotiable and the single most important structural rule of this skill. Each subagent starts with fresh context, eliminating stale state, token budget exhaustion, and cross-story contamination. The orchestrator (this skill's top-level agent) handles only initialization (Phase 1), sprint assessment (Phase 2), loop control (Phase 7), and error triage. It does NOT perform implementation, review, or test-writing directly.

Subagent dispatch rules:
- **One subagent per phase per story — NO EXCEPTIONS.** Story `2-3` gets four separate subagents: one for create (Phase 3), one for develop (Phase 4), one for review (Phase 5), and one for QA (Phase 6). **Never combine two or more phases in a single subagent call.** A subagent that finishes Phase 3 does NOT continue into Phase 4. The orchestrator receives the Phase 3 result, then dispatches a brand-new subagent for Phase 4. This applies even when phases feel trivially small — the boundary is mandatory.
- **Provide full context in the prompt.** Each subagent has no memory of prior subagents. The dispatch prompt MUST include: the story slug, the phase instructions (from this skill), paths to all relevant BMAD artifacts, the current `sprint-status.yaml` state for this story, owner/repo, and any phase-specific data (e.g., Figma node IDs, relevant skill paths, GH issue number).
- **Wait for completion.** The orchestrator must wait for each subagent to finish and read its result before dispatching the next phase or story.
- **Subagent type:** Use `subagent_type="generalPurpose"` for all BMAD phase work.
- **Never inline phase work.** If you catch yourself reading story files, writing code, running tests, or editing `sprint-status.yaml` outside a subagent dispatch, STOP. You are violating this rule. Dispatch a subagent instead.
- **Never batch phases.** If you catch yourself dispatching a subagent prompt that includes instructions for more than one phase (e.g., "develop and then review"), STOP. You are violating this rule. Split into separate dispatches.

**Constraints:**
- **GitHub API is read-only (standard mode).** Read issues, labels, comments, sub-issues. Never create, update, close, comment on, or reorganize anything — whether via MCP or CLI. **Exception:** In full-auto mode, GitHub write operations are permitted during Phase 8 (Sprint Completion) only — PR creation, PR merging, issue assignment, issue closing, and epic management.
- **MCP-first, CLI-fallback.** Use MCP servers (`user-github`, Figma) as the primary interface. If an MCP server is unavailable or broken, fall back to the equivalent CLI tool (e.g., `gh` for GitHub). Document which method is in use at session start.
- **Git commit and push is allowed.** Commit and push code, story files, test files, and sprint-status.yaml updates to the current branch.
- **All quality gates must pass before every commit.** Run these three checks before committing any code or test changes. If any fail, fix the failures before committing. Never commit code that breaks existing tests, introduces static analysis errors, or violates coding style.
  1. `ddev exec php bin/phpunit --bootstrap vendor/autoload.php src/Acme/` (unit tests)
  2. `ddev exec php vendor/phpstan/phpstan/phpstan analyse --no-progress` (static analysis)
  3. `ddev exec bash -c "PHP_CS_FIXER_IGNORE_ENV=1 php vendor/friendsofphp/php-cs-fixer/php-cs-fixer fix --dry-run --diff src/Acme/"` (coding style)
- **Use ddev for all application interaction.** The local environment runs via ddev (PHP 8.4, PostgreSQL 17, Elasticsearch). Use `ddev exec` to run PHP commands, `ddev ssh` for interactive shells, and `ddev start`/`ddev stop` to manage the environment. Never run PHP commands directly on the host — the host PHP version is incompatible.
- **No retrospectives.** Skip `epic-N-retrospective` entries entirely.

## Phase 1: Initialize

### 1a. Discover MCP Tools and CLI Fallbacks

**Prefer MCP servers for all external service interactions.** Fall back to CLI tools (e.g., `gh`) only when an MCP server is unavailable or its tools fail after retry.

**GitHub — `user-github` MCP server:**

Introspect available tools before any MCP call:
1. List files under the MCP descriptor path for `user-github` (check `tools/` subdirectory).
2. If no tool descriptors exist on disk, make a test call to confirm tool names and parameter shapes.
3. If the MCP server is not available or discovery fails, fall back to `gh` CLI for read-only operations (e.g., `gh issue list`, `gh issue view`).
4. Cache the verified tool names/schemas (or the CLI fallback decision) for the session.

Read-only tools (expected names — **verify at runtime**):

| Operation | MCP Tool | CLI Fallback |
|-----------|----------|--------------|
| Get current user | `get_me` | `gh api user` |
| List issues | `list_issues` | `gh issue list` |
| Search issues | `search_issues` | `gh issue list --search` |
| Get issue details | `issue_read` | `gh issue view` |
| List labels | `list_label` | `gh label list` |

**READ-ONLY constraint** applies in standard mode regardless of method: Do not create, update, close, comment on, or reorganize GitHub issues/labels via MCP or CLI. In full-auto mode, write operations are permitted only during Phase 8 (Sprint Completion).

**Figma — `project-0-tkg-acme-oro-figma` MCP server:**

Check for availability. If present, it provides `get_design_context`, `get_screenshot`, and `get_metadata` for pulling Figma design specs. Follow the project's `figma-mcp` cursor rule for translation conventions (Twig + SCSS + Layout YAML, not React/Tailwind). No CLI fallback exists for Figma — if the MCP server is unavailable, skip Figma context and proceed with local artifacts only.

Also check for the `project-0-tkg-acme-oro-figma` MCP server. If available, it provides `get_design_context`, `get_screenshot`, and `get_metadata` for pulling Figma design specs. Follow the project's `figma-mcp` cursor rule for translation conventions (Twig + SCSS + Layout YAML, not React/Tailwind).

### 1b. Resolve owner/repo

Derive `owner` and `repo` from the git remote URL. Cache for the session.

### 1c. Validate Sprint Branch

1. Get the current branch name: `git branch --show-current`.
2. Verify it matches the pattern `feat/bmad-sprint-<N>` (e.g., `feat/bmad-sprint-5`). If it does not, **stop and report the error**. Do not proceed.
3. Verify the branch was created from `develop`:
   - `git merge-base --is-ancestor develop HEAD` must succeed (develop is an ancestor of HEAD).
   - `git log develop..HEAD --oneline` should show only commits from the current sprint (no unrelated divergence).
4. If the branch is not properly based on `develop` or is not named correctly, **stop and report**. The user must fix the branch before autopilot can proceed.
5. Extract the sprint number `N` from the branch name and cache it for the session (used in Phase 8 for PR titles and next-branch naming).

### 1d. Read Sprint Status

1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml`.
2. Parse the `generated:` field.
3. If `generated` date is more than 2 days old, **warn the user** and suggest running `/bmad-bmm-sprint-status` to refresh. Offer to proceed on stale data if they choose.

### 1e. Load Planning Context

Read these once and cache for the session — they inform story creation and development:

- `_bmad-output/planning-artifacts/epics.md` — full epic/story breakdown with acceptance criteria
- `_bmad-output/planning-artifacts/architecture.md` — system architecture and integration patterns
- `_bmad-output/planning-artifacts/prd.md` — functional requirements (reference by FR-ID)
- `_bmad-output/planning-artifacts/ux-design-specification.md` — UX patterns and flows
- `_bmad-output/project-context.md` — tech stack, bundle structure, coding conventions

### 1f. Load Deferred Work Manifest

Read `_bmad-output/implementation-artifacts/deferred-work.md` if it exists. This tracks blocked, deferred, and tech-debt items from prior sprints. During story creation (Phase 3), check whether the new story resolves any deferred items. During review (Phase 5), append any newly deferred items.

## Phase 2: Assess Sprint State

### 2a. Parse Development Status

Extract all entries under `development_status:` from the YAML. Categorize:

- **Epics**: keys matching `epic-N` (status: `backlog`, `in-progress`, `done`)
- **Stories**: keys matching `N-N-slug` (status: `backlog`, `ready-for-dev`, `in-progress`, `review`, `done`)
- **Retros**: keys matching `epic-N-retrospective` — **skip entirely**

### 2b. Map to GitHub Issues

For each non-backlog story, search GitHub by `story:N-N` label, falling back to title search. This is for context only (reading issue descriptions, comments, linked resources).

### 2c. Present Status and Propose Next Action

Determine the next actionable work item by priority order (lowest story number in the earliest incomplete epic). Do NOT present a status table or wait for user confirmation. Proceed immediately to the appropriate phase for the next story.

## Phase 3: Create Story

For the next `backlog` story in the current or next epic:

### 3a. Gather Requirements

1. Find the story in `epics.md` — extract the user story, acceptance criteria, tasks, dev notes, and source FR references.
2. Cross-reference the FR-IDs against `prd.md` for full requirement text.
3. Check `architecture.md` for relevant integration patterns, data flows, or constraints.
4. Check `ux-design-specification.md` for any UX flows or wireframe references.
5. If the story involves UI/storefront work and Figma MCP is available, call `get_design_context` and `get_screenshot` for the relevant Figma nodes referenced in the UX spec.
6. Cross-reference the story requirements against the **OroCommerce Platform Evolution** section of this skill. If a native 6.1.x feature covers part or all of the requirement, note it in the story's Dev Notes and adjust tasks to leverage the platform capability.

### 3b. Check Deferred Work Manifest

If `deferred-work.md` exists, check whether the new story resolves or unblocks any deferred items. If so, note them in the story's Dev Notes under a `### Deferred Items Resolved` section so the review phase (5d) can remove them from the manifest when the story is marked `done`.

### 3c. Check for Existing GH Issue Context

If the story has a matching GitHub issue, read its description and comments for any additional context, decisions, or clarifications from the team.

### 3d. Write the Story File

Create `_bmad-output/implementation-artifacts/{slug}.md` following the established format:

```markdown
# Story N.M: Title

Status: ready-for-dev

## Story
As a [role], I want [capability], So that [benefit].

## Acceptance Criteria
1. **Given** ... **When** ... **Then** ...

## Tasks / Subtasks
- [ ] Task 1: Description (AC: #N)
  - [ ] 1.1 Subtask detail

## Dev Notes
### Critical Context
[Architecture constraints, integration points, Oro-specific patterns]

### Figma References
[Design context if applicable]
```

### 3e. Update Sprint Status

Update the story's status from `backlog` to `ready-for-dev` in `sprint-status.yaml`. If this is the first story created in an epic, update the epic status from `backlog` to `in-progress`.

### 3f. Commit

Commit the story file and updated sprint-status.yaml. Push.

## Phase 4: Develop Story

For the next `ready-for-dev` or `in-progress` story:

### 4a. Load Story Spec

Read the story file from `_bmad-output/implementation-artifacts/{slug}.md`. This is the source of truth for what to build.

### 4b. Load Relevant Skills

Based on the story's domain, read the appropriate Oro skill files:

| Domain | Skill |
|--------|-------|
| Backend (entities, bundles, controllers, datagrids) | `oro-backend-dev` |
| Frontend (themes, layouts, SCSS, JS) | `oro-frontend-dev` |
| API (REST endpoints, processors) | `oro-api-dev` |
| Database (migrations, schema) | `oro-dba` |
| DevOps (Docker, deployment, config) | `oro-devops` |
| Architecture decisions | `oro-architect` |

### 4c. Figma Design Context

If the story involves storefront UI and Figma MCP is available:
1. Call `get_design_context` for the relevant node(s).
2. Call `get_screenshot` for visual reference.
3. Follow `figma-mcp` cursor rule: translate to Twig + SCSS + Layout YAML. Never emit React/Tailwind.

### 4d. Implement

Work through the story's tasks sequentially. Follow `project-context.md` conventions:
- Bundle namespace: `Acme\Bundle\{Domain}Bundle`
- Table prefix: `acme_`
- Register via `Resources/config/oro/bundles.yml`
- Use existing Oro extension points before custom solutions
- Check the **OroCommerce Platform Evolution** section for native features that may replace or simplify planned custom work (especially SSO/OIDC, recurring orders, inventory validation, and Quote API)

Check off tasks in the story file as they're completed.

### 4e. Update Status

Update the story status to `in-progress` in `sprint-status.yaml` when starting, and to `review` when all tasks are complete.

### 4f. Run Quality Gates and Commit

Run all three quality gates and verify they pass. Fix any failures before proceeding.

1. `ddev exec php bin/phpunit --bootstrap vendor/autoload.php src/Acme/`
2. `ddev exec php vendor/phpstan/phpstan/phpstan analyse --no-progress`
3. `ddev exec php vendor/friendsofphp/php-cs-fixer/php-cs-fixer fix --dry-run --diff src/Acme/`

Then commit implementation code, updated story file, and sprint-status.yaml. Push.

## Phase 5: Code Review

For stories in `review` status:

### 5a. Review Scope

1. Identify all files changed for this story (use git log/diff against the story's commits or inspect the implementation against the story spec).
2. Read each changed file.

### 5b. Review Criteria

- **Correctness**: Does the implementation satisfy every acceptance criterion?
- **Oro conventions**: Bundle structure, naming, extension patterns per `project-context.md`.
- **Security**: No hardcoded secrets, proper ACL/permission checks, input validation.
- **Performance**: No N+1 queries, proper use of Oro cache patterns, index coverage.
- **Completeness**: All tasks checked off in the story file. No TODO/FIXME left behind.

### 5c. Report

Present findings as a checklist. If issues are found, fix them (this is self-review of autopilot-generated code). If the code passes, update status to `done`.

### 5d. Update Deferred Work Manifest

After review, check for any items that were deferred, blocked, stubbed, or flagged as needing future work. If any exist, append them to `_bmad-output/implementation-artifacts/deferred-work.md` under the appropriate category:

- **Blocked on platform upgrade** — work that requires a newer Oro version or third-party dependency not yet available.
- **Infrastructure / environment setup** — config, tooling, or environment changes needed before the feature is fully operational.
- **Security configuration** — firewall, authenticator, or ACL wiring that needs runtime verification or manual setup.
- **Runtime verification** — behavior that cannot be confirmed without a running instance (event names, listener ordering, cross-bundle interactions).
- **Technical debt** — stubs, placeholders, hardcoded values, or patterns identified during review that should be addressed later.

Each entry must include: the originating story slug, the specific task/subtask, and a description of what remains. If `deferred-work.md` does not exist, create it with the header template from the first entry.

This step is mandatory even when zero items are deferred — the subagent must explicitly confirm "no deferred items" in its output.

### 5e. Update Status

Update the story status to `done` in `sprint-status.yaml`. If all stories in the epic are now `done`, update the epic to `done`.

### 5f. Run Quality Gates and Commit

Run all three quality gates and verify they pass. Fix any failures before proceeding.

1. `ddev exec php bin/phpunit --bootstrap vendor/autoload.php src/Acme/`
2. `ddev exec php vendor/phpstan/phpstan/phpstan analyse --no-progress`
3. `ddev exec php vendor/friendsofphp/php-cs-fixer/php-cs-fixer fix --dry-run --diff src/Acme/`

Then commit any review fixes, updated story file, deferred-work.md (if changed), and sprint-status.yaml. Push.

## Phase 6: QA Automate

For stories recently moved to `done` that lack test coverage:

### 6a. Determine Test Type

| Story Domain | Test Type | Location |
|-------------|-----------|----------|
| Backend logic / services | PHPUnit unit tests | `tests/Unit/` |
| API endpoints | PHPUnit functional tests | `tests/Functional/` |
| Entity/database | PHPUnit integration tests | `tests/Integration/` |
| Frontend UI | Behat scenarios | `tests/Behat/Features/` |
| Workflow/process | PHPUnit + Behat | Both |

### 6b. Write Tests

Write tests that validate each acceptance criterion from the story. Follow Oro's test conventions:
- Extend `Oro\Bundle\TestFrameworkBundle\Test\WebTestCase` for functional tests.
- Use Oro's test fixtures and container access patterns.
- Behat contexts extend Oro's base contexts.

### 6c. Run Tests

Execute the test suite for the new tests. Fix failures.

### 6d. Run Quality Gates and Commit

Run all three quality gates and verify they pass (including the newly written tests). Fix any failures before proceeding.

1. `ddev exec php bin/phpunit --bootstrap vendor/autoload.php src/Acme/`
2. `ddev exec php vendor/phpstan/phpstan/phpstan analyse --no-progress`
3. `ddev exec php vendor/friendsofphp/php-cs-fixer/php-cs-fixer fix --dry-run --diff src/Acme/`

Then commit test files. Push.

## Phase 7: Loop

After completing a workflow phase for one story, immediately proceed to the next phase or next story. Do not wait for confirmation. Continue until:
- The user interrupts.
- All stories in the current epic are `done` and QA-automated (pause briefly at epic boundary to report, then continue to next epic).
- There are no more actionable items in the sprint.

**Phase sequencing enforcement:** For each story, drive it through all applicable phases in sequence: create (Phase 3) -> develop (Phase 4) -> review (Phase 5) -> QA (Phase 6). Each phase is a **separate subagent dispatch**. The orchestrator dispatches Phase 3, waits for the result, dispatches Phase 4 as a new subagent, waits for the result, dispatches Phase 5 as a new subagent, waits for the result, dispatches Phase 6 as a new subagent, waits for the result. Four phases = four subagents minimum. If a story is already partway through (e.g., `in-progress`), pick up at the next applicable phase — but each remaining phase still gets its own subagent.

Between stories, emit a one-line progress marker (not a prompt):

```
[autopilot] 2-1 done (created -> developed -> reviewed -> QA). Starting 2-2.
```

**Sprint completion:** When all stories in the sprint are `done` and QA-automated, and **full-auto mode is active**, proceed to Phase 8 (Sprint Completion). In standard mode, report sprint completion and stop.

## Phase 8: Sprint Completion (Full-Auto Mode Only)

This phase executes only in full-auto mode. It handles the PR lifecycle, GitHub issue housekeeping, and branch setup for the next sprint.

### 8a. Create Pull Request

1. Determine the current sprint branch name (e.g., `feat/bmad-sprint-4`) and the target branch (`develop`).
2. Push any remaining commits on the sprint branch.
3. Create a PR to merge the sprint branch into `develop` using `gh pr create --base develop --head <sprint-branch> --title "Merge sprint N into develop" --body "<sprint summary>"`. The body should list completed epics/stories and any deferred items.

### 8b. Wait for CI Checks

1. Poll PR check status: `gh pr checks <pr-number> --watch` or poll with `gh pr checks <pr-number>` at intervals.
2. If all checks pass, proceed to 8c.
3. If checks fail:
   - Read the failure logs (`gh run view <run-id> --log-failed`).
   - Diagnose and fix the failures locally on the sprint branch.
   - Run local quality gates to verify the fix.
   - Commit and push the fix.
   - Return to step 1 (re-poll checks). Retry up to 3 times. If still failing after 3 fix attempts, stop and report.

### 8c. Merge PR

1. Merge the PR using admin override: `gh pr merge <pr-number> --admin --merge`.
2. Confirm the merge succeeded.
3. Delete the remote sprint branch: `gh pr merge` with `--delete-branch`, or `git push origin --delete <sprint-branch>`.

### 8e. Move Deferred Tasks

1. Read `_bmad-output/implementation-artifacts/deferred-work.md`.
2. For each deferred item, find or create an issue in the **Deferred Work** epic (or equivalent tracking epic). Include in the issue body:
   - The originating story slug and sprint number.
   - The deferred item description from the manifest.
   - The category (blocked on platform, infra, security, runtime verification, tech debt).
3. Use `gh issue create` with appropriate labels indicating origin sprint and category.

### 8f. Prepare Next Sprint Branch

1. Switch to `develop` and pull latest: `git checkout develop && git pull origin develop`.
2. Determine the next sprint number (current + 1).
3. Create and push the new sprint branch: `git checkout -b feat/bmad-sprint-<N+1> && git push -u origin feat/bmad-sprint-<N+1>`.
4. Report: `[autopilot] Sprint N complete. PR merged to develop. Branch feat/bmad-sprint-<N+1> ready.`

### 8g. Continue to Next Sprint

If there are remaining items in the sprint backlog (next sprint's stories), loop back to Phase 2 and continue. Otherwise, report that all planned sprints are complete and stop.

## Error Handling

### MCP Call Failures

- On auth/permission errors: stop and report. Do not retry.
- On rate limits (HTTP 429): wait 5 seconds, retry once. If still failing, stop and report.
- On network errors: retry once. If still failing, stop and report.

### Build/Test Failures

- If implementation causes build errors, fix them before committing.
- If tests fail, diagnose and fix. Retry up to 3 times with different approaches. If still failing after 3 attempts, log the issue in the story file as a `## Known Issues` section, mark the story `done` with a caveat, and move on. Only pause if the failure cascades into other stories.

### Ambiguous GH Matches

- If a story title matches multiple GH issues, flag as `AMBIGUOUS` and skip the GH context. Proceed with local artifacts only.

### Malformed YAML

- If `sprint-status.yaml` cannot be parsed or is missing `development_status:`, stop and report.

## OroCommerce Platform Evolution

This project targets OroCommerce 6.1 LTS (support through March 2028, extendable to 6 years). Oro shifted to continual feature releases throughout the year — everything below landed in 6.1.x patch releases and is consolidated in the 7.0 LTS. A new backporting policy (2025+) means select 7.0 features will also be made available to 6.1 users.

**When implementing stories, prefer native platform capabilities over custom solutions.** Cross-reference story requirements against this section during Phase 3 (story creation) and Phase 4 (development).

### OroCommerce 7.0

- **RC available now.** LTS expected late March / early April 2026.
- **Symfony 7 support** — performance improvements + 450 new framework features.
- 7.0 is the first LTS containing all features listed below. No new features exclusive to 7.0 beyond the Symfony upgrade — everything was delivered in 6.1.x patches.
- **Field Sales PWA** and **SmartOrder/SmartAgent** require Oro support team to enable in the environment (open a support ticket).

### Security, Identity & SSO (High Relevance)

| Version | Feature | Ref |
|---------|---------|-----|
| 6.1.2 | **SSO-Only Logins** — restrict non-SSO login for specified email domains (Google, Microsoft 365) | BB-24881 |
| 6.1.5 | **Disable Username/Password Login** — force SSO-only auth, fully delegating to IdP | BAP-23058 |
| 6.1.5 | **Subresource Integrity (SRI)** — toggle for JS/CSS asset integrity checks | BAP-22926 |
| 6.1.7 | **OIDC Identity Providers for Storefront Users** — admin UI to manage OpenID Connect IdPs for customer/buyer SSO | BB-26553 |
| 6.1.7 | **Okta SCIM** — automated user provisioning/deprovisioning synced with Okta or Microsoft Entra ID | BB-26380 |
| 6.1.x | **Security hardening** — enhanced SVG content sanitization, HTTP proxy support for Google reCAPTCHA in secured environments | — |

**Guidance:** If any story involves authentication, SSO, or user provisioning, check whether native OIDC storefront support (6.1.7) or SCIM provisioning covers the requirement before building custom solutions. These are first-party platform features.

### Buyer Experience & Storefront Flexibility

| Version | Feature | Ref |
|---------|---------|-----|
| 6.1.7 | **Recurring Orders** — customers convert past orders to recurring; custom frequency (weekly/monthly/yearly), pause/resume/cancel from portal | BB-26218 |
| 6.1.7 | **Selective Guest Access** — keep specific system/CMS pages public while storefront is private; no custom code required | BB-26729 |
| 6.1.7 | **Inventory Validation Prior To Checkout** — real-time stock levels visible across product listings, search results, shopping lists, and checkout | BB-25199 |
| 6.1.7 | **Save for Later** — customers set aside unavailable items on shopping lists to avoid checkout validation errors | BB-25199 |
| 6.1.6 | **Order PDF** — customers download styled PDF orders from storefront or receive as email attachments | BB-25202 |
| 6.1.5 | **Assets Preloading** — frontend devs preload critical assets (fonts, images, CSS) for faster page load and SEO | BB-24797 |

### Financial Operations & Native Payments

| Version | Feature | Ref |
|---------|---------|-----|
| 6.1.x | **OroPay** — native B2B payment solution (Global Payments); L2/L3 credit card + ACH; PCI DSS, SOC 1 & 2. N. America only. | — |
| 6.1.x | **Customer Invoicing Portal** — buyers view, track, and pay invoices online via OroPay or Stripe Elements | — |
| 6.1.x | **Back-Office Invoice Management** — full invoicing lifecycle with API support for ERP sync | — |
| 6.1.1 | **Multi-Currency Price Rules** — use system exchange rates in price calculation formulas; automatic price list updates on rate change | BB-25195 |

### Smarter Sales & Quoting

| Version | Feature | Ref |
|---------|---------|-----|
| 6.1.2 | **Back-Office Quote API** — external systems create and manage quotes (field sales tools, CRMs) | BB-25204 |
| 6.1.2 | **Linked RFQs and Quotes** — storefront navigation between related RFQs and finalized Quotes | BB-25200 |
| 6.1.4 | **Customer-Facing Attachments** — spec sheets, contracts, documents shared within quotes/orders; accessible via storefront and API | BB-25201 |
| 6.1.4 | **Project Name in Quotes and RFQs** — tracks initiatives; auto-copied from RFQ to Quote | BB-25203 |

### Data Management & Operations

| Version | Feature | Ref |
|---------|---------|-----|
| 6.1.x | **External Order Import (JSON)** — import historical/ERP orders; buyers get unified view; legacy data read-only | BB-25196 |
| 6.1.7 | **Advanced Product Import** — category matching by ID, full path, or title for complex catalogs | BB-18280 |
| 6.1.6 | **Organization Selector Upgrade** — lazy-loading, auto-complete for large multi-org environments | BB-26033 |
| 6.1.2 | **Dashboard Scorecards** — buyer widget for Total Orders, Open RFQs, Shopping Lists | BB-25440 |
| 6.1.2 | **Data Audit for JSON Fields** — accurate change logs for Doctrine/PostgreSQL JSON fields | BB-25559 |
| 6.1.1 | **Seller Info Configuration** — company name, address, tax ID in system config (global/org/website) | BB-25449 |
| 6.1.5 | **Advanced Search in Back-Office API** — `searchQuery` filter for granular conditions per entity field | BAP-23040 |

### AI: Smart Order & MCP

| Version | Feature | Ref |
|---------|---------|-----|
| 6.1.7 | **Oro MCP Server** — unified integration layer for back-office and storefront, connecting external AI tools and services | — |
| 6.1.7 | **Smart Order enhancements** — improved line item recognition in uploaded PO files | AI-639 |
| 6.1.7 | **Langfuse Integration** — central management and versioning of AI prompts with local fallback for resilience | AI-651, AI-708 |
| — | **Field Sales PWA** / **SmartAgent** — requires Oro support to enable in environment | — |

## Important Notes

- **BMAD method is mandatory.** All work — every story, commit, review, test, and status update — must be performed within the BMAD framework. BMAD planning artifacts (`epics.md`, `prd.md`, `architecture.md`, `ux-design-specification.md`, `project-context.md`, `sprint-status.yaml`) are the authoritative source of truth. No work is valid outside this structure.
- **GitHub API is read-only (standard mode).** Read issues for context via MCP or `gh` CLI. Never mutate via either method. **In full-auto mode**, GitHub write operations are permitted exclusively in Phase 8 for PR lifecycle, issue management, and branch operations.
- **Full-auto mode** is activated by "bmad full autopilot". It enables Phase 8 (Sprint Completion) which creates PRs, merges with admin override, closes/assigns issues, manages deferred work issues, and creates the next sprint branch. Standard autopilot skips Phase 8 entirely.
- **MCP-first, CLI-fallback.** Always prefer MCP servers for external services. Use CLI equivalents (e.g., `gh`) only when the MCP server is unavailable or non-functional.
- **Git commit and push is allowed.** Commit early, commit often — but only after all quality gates pass.
- **Three quality gates before every commit:** PHPUnit (unit tests), PHPStan (static analysis), and PHP CS Fixer (coding style). Never push code that breaks any gate.
- **No retrospectives.** Skip all `epic-N-retrospective` entries.
- **Figma MCP is optional.** Use it when available and the story involves UI. Follow the `figma-mcp` cursor rule for translation.
- **Skills are reference material.** Load the appropriate `oro-*` skill before implementing domain-specific code.
- **Autonomous by default.** After initial direction is confirmed, do not pause between phases or stories. Only stop for blocking ambiguity, unrecoverable errors, or epic boundaries.
- **Fresh subagent per phase (MANDATORY — ZERO TOLERANCE).** Every story phase (Phase 3: create, Phase 4: develop, Phase 5: review, Phase 6: QA) runs in its own **separate** subagent via the `Task` tool with full context in the prompt. The orchestrator never performs phase work directly. **Combined cycles are prohibited** — a single subagent must never execute more than one phase. Four phases = four subagent dispatches. This ensures clean context windows and prevents cross-story contamination.
- **Deferred work is tracked.** `_bmad-output/implementation-artifacts/deferred-work.md` is the single source of truth for blocked, stubbed, and deferred items. Phase 5 (review) appends new items; Phase 3 (story creation) checks for items the new story resolves. The manifest is committed alongside sprint-status.yaml.
- **When undecided on next steps**, `/bmad-help` reliably surfaces the best available BMAD workflows for the current project state.
