Merge ad6ae7ed77 into e600181ab8

CHANGELOG.md

@@ -1,46 +1,5 @@
 # Changelog
 
-## v6.9.0 - 2026-06-21
-
-### ✨ Headline
-
-**Reasoning skills get sharper and orchestration gets a memory.**
-
-**bmad-forge-idea** is a new core skill that takes a half-formed idea and pressure-tests it one Socratic question at a time — with an adversarial attack mode and optional persona rooms — until the idea hardens, proves out, or dies cheaply. 
-
-**bmad-architecture** lands as a ground-up rewrite of the old multi-step create-architecture flow: a lean spine (`ARCHITECTURE-SPINE.md`) that is the source of truth, intent-based routing (Create/Update/Validate), a breadth-coverage rubric so no dimension is silently skipped, and an opt-in reviewer gate.
-
-**party-mode** is reborn with creatable, savable custom parties, optional party memory, and many pacing and dynamics improvements.
-
-**Under the hood:** a canonical shared **memlog** (`_bmad/scripts/memlog.py`) replaces per-skill decision logs and is now the standard working-memory primitive across the suite. The installer now checks for **uv** and reframes it as the standard way to run BMAD's Python scripts (`uv run`). Plus an **Astro 6** security upgrade clearing 8+ Dependabot advisories and two new platform targets.
-
-### ⚠️ Upcoming Breaking Change (in v7) — standardizing on `uv`
-
-The industry is converging on [**uv**](https://docs.astral.sh/uv/) for running Python, and BMAD is following. Today our skills use a **mix** of `uv run` and direct `python3` invocation. In the **v7 release, every skill that runs a Python script will standardize on `uv run`** instead of calling `python3` directly — `uv` provisions the interpreter and manages dependencies, so scripts run consistently regardless of what's on your PATH.
-
-**What to do now:** install and set up `uv` ([docs](https://docs.astral.sh/uv/)) — or just ask your AI agent to "install and set up uv for me." Starting this release the installer checks for it and points you to setup if it's missing. `uv` is **not yet required** but without it some skills may have degraded performance or a shim AGENTS.md (or similar) or rule will need to be added to your environment to tell the agent when it sees uv run to use python3 instead. The best course of action though at this time is to install uv. A missing `uv` still warns rather than blocks, but it will be the assumed default in v7. Custom skills and overrides that shell out to `python3` should plan to migrate to `uv run`.
-
-### 🎁 Features
-
-* **bmad-forge-idea — new core skill** (#2492). Domain-agnostic idea pressure-testing for the analysis phase: Socratic, one-question-at-a-time interrogation with an adversarial attack mode and optional persona rooms resolved from the installed roster. Hardens or kills an idea cheaply; emits memlog residue and an optional brief that feeds bmad-spec or bmad-quick-dev. Interactive only (menu code FI).
-* **bmad-architecture — lean spine rewrite** (#2467, #2475). Replaces the fixed-step `bmad-create-architecture` (retained as a forwarding shim, removed in v7) with intent-based routing across five entry shapes (raw idea, large doc, codebase, feature slice, existing spine). The spine (`ARCHITECTURE-SPINE.md`) is the source of truth and SPEC.md is derived from it. Adds a breadth-coverage rubric (every altitude-owned dimension decided/deferred/open), an opt-in reviewer gate that scales lenses to rigor, and a full non-interactive headless mode. `lint_spine.py` hardened with fence-blanking, robust column detection, and 28 regression tests.
-* **party-mode: configurable parties + persistent memory** (#2479, #2484). Custom personas (`party_members`) and named rooms (`party_groups`, with optional scenes), four run modes (auto/session/subagent/agent-team), and a preloaded "Code Review Crew" of five adversarial lenses. Each party keeps append-only session memory under `{memory_dir}/<party_id>/` so sessions resume with prior context; ad-hoc casts stay ephemeral.
-* **bmad-brainstorming: facilitation modes + visual composer** (#2445). Three modes (Facilitator / Creative Partner / Ideate for me), append-only memlog with optional `--by` authorship attribution, and a self-contained `brain-selector.html` composer (technique strategy, category chips, filter, copy-to-clipboard, dark mode). Catalog grows to 108 techniques (8 new classics: HMW, JTBD, Empathy Map, Backcasting, TRIZ, Fishbone, Build on What Works, Scenario Cross) plus a convergence phase.
-* **Canonical shared memlog script** (#2462). New `src/scripts/memlog.py` — append-only chronological working memory with init/append/set ops, no lifecycle-status design, Python 3.8+ support, 30 tests. Any skill can call it at runtime.
-* **Retrospective action items tracked in sprint-status** (#2465). The retrospective step appends an `action_items` section to `sprint-status.yaml`; sprint-status validates and surfaces open items, and sprint-planning preserves them on regenerate.
-* **Installer checks for `uv` and reframes it as the standard** (#2495). Replaces the old python3 probe with a `uv` check, adds a heads-up to the install intro and a tip to the "BMAD is ready" summary, and updates docs/script docstrings (en/fr/vi-vn) to frame `uv run` as the standard and `python3` as the transition fallback. Migration-friendly: a missing `uv` warns and points you to setup, never blocks. See the Upcoming Breaking Change note above.
-* **New installer platform targets: hermes-agent and CodeWhale** (#2489, #2459). hermes-agent added as a tool target; CodeWhale uses `.codewhale/skills/` (project) and `~/.codewhale/skills/` (global), both with test coverage.
-
-### 🐛 Fixes
-
-* **Astro 6 security upgrade clears Dependabot alerts** (#2493). Astro 5.18.1 → 6.4.6 and Starlight 0.37.5 → 0.40.0 (8 XSS/SSRF advisories), esbuild pinned to 0.28.1 (Windows dev-server file read), markdown-it 14.2.0 (smartquotes ReDoS), brace-expansion 5.0.6 (range DoS). Docs content config migrated to `src/content.config.ts`; page output verified identical to baseline.
-* **Guard WSL installs from Windows Node** (#2470). Detects and prevents a Windows `node.exe` being used inside WSL, where it would silently fail.
-* **Remove empty skill-group dirs after install** (#2461). Prunes empty parent dirs (e.g. `_bmad/bmm/1-analysis`) left after skill cleanup, with a path-boundary check to avoid sibling-dir collisions.
-* **bmad-create-epics-and-stories discovers bmad-ux spine outputs** (#2446). Prerequisites now recognize `DESIGN.md` / `EXPERIENCE.md` alongside the legacy `ux-spec.md`.
-* **Pass diff inline to the blind-hunter reviewer** (#2463). Diff output is passed inline in the subagent prompt rather than via a file the reviewer can't read, preventing context-starved hallucination.
-* **Website: nav height for dual announcement banners** (#2473). Fixes layout crowding when two banners show at once.
-* **Workflow clarity & numbering** — clarify quick-dev subagent use across code-review/create-story/quick-dev (#2450), renumber retrospective steps (#2448).
-
 ## v6.8.0 - 2026-05-25
 
 ### ✨ Headline

docs/explanation/forge-idea.md

@@ -1,76 +0,0 @@
----
-title: "Forge an Idea"
-description: Pressure-test an idea through persona-driven interrogation until it hardens, proves out, or dies cheaply
-sidebar:
-  order: 14
----
-
-Take a half-formed idea and pressure-test it now, in conversation, while changing your mind is still free.
-
-## What is Forge Idea?
-
-Run `bmad-forge-idea` and an exacting interrogator goes to work on your idea, one question at a time, until what survives is something you can act on with earned conviction. The skill is domain-agnostic. It runs on a software feature, a business model, a research hypothesis, or a life decision you keep circling.
-
-What you walk away with is sharper thinking. A distilled `forged-idea.md` is only ever one possible exit, and the session never herds you toward "shall we build it?"
-
-## Why Pressure-Test Early
-
-The enemy is the hole you can't see in your own idea. An unexamined assumption or an unresolved branch is a crack, and a crack you miss now resurfaces later — in the build, or the launch, when it costs far more to fix.
-
-A conversation is the cheapest place to catch it, because changing your mind here costs nothing. The forge spends that cheapness on purpose, going after the weak points while fixing them is still free.
-
-## How a Session Runs
-
-The interrogator works one question at a time, in dependency order, and puts its own recommended answer on the table each time. A position you can push against gets further than an open prompt. It finds discoverable answers itself instead of sending you to fetch them.
-
-When your idea lands inside an existing project, that project's material becomes the ground truth. The interrogator checks your claims against what already exists and names the contradictions. Your vocabulary gets the same treatment. When a term is fuzzy or carries two meanings, it forces a precise choice before the branch can resolve, because a branch built on an overloaded word resolves falsely.
-
-## The Room
-
-The forge is voiced. Once the topic is set, every branch arrives with two characters instead of one faceless assistant. One comes from your installed roster — an agent or persona you'll recognize, drawn from the same cast behind [Party Mode](./party-mode.md) and [named agents](./named-agents.md). The other is conjured on the fly by the topic itself: a hostile competitor, a skeptical CFO, a domain specialist who has watched this exact plan fail before.
-
-You steer the room whenever you want. Name a specific person, call a saved party, or invoke the **adversarial on this** gear to attack a claim to destruction with you defending it.
-
-## Never Default-Agree
-
-Reflexive agreement is the failure this skill exists to refuse. Acknowledging your idea isn't the same as endorsing it, and the forge won't praise anything before it has survived something. It attacks the weak point or builds on the strong one, and it credits only what genuinely earns the credit.
-
-This is the deliberate inverse of [Adversarial Review](./adversarial-review.md). There, the reviewer is told to find problems and you filter out the false positives. Here, the interrogator is told never to grant agreement for free, so the pressure stays high and you think harder under it. It optimizes for the best idea over a comfortable session.
-
-## How a Session Ends
-
-The session ends however the thinking lands, and every landing is a real outcome. The forge writes a self-contained report you can keep, stamped to match the result.
-
-| Outcome | What it means |
-| --- | --- |
-| **Hardened** | The idea survived. It distills into `forged-idea.md` (the locked decisions, plus what was killed and why), ready to feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq` for a product concept. |
-| **Killed** | The idea didn't survive, and the report records the cause of death. Finding that out cheaply is a win. |
-| **Clearer** | You just think straighter now. No artifact needed, and the session stands on its own. |
-
-## When to Use It
-
-Reach for the forge when you already hold an idea and want it hardened or killed before you invest in it. Skip it when you're still generating options or when you need a group decision from your agents.
-
-| Skill | Use it when | Voice |
-| --- | --- | --- |
-| `bmad-forge-idea` | You have an idea and want it stress-tested or killed | An interrogator plus a two-person room |
-| `bmad-prfaq` | You've committed to a product and want it proven customer-first | A Working Backwards coach |
-| `bmad-brainstorming` | You have no idea yet and need to generate options | A facilitation coach |
-| `bmad-party-mode` | You want your agents to discuss or decide together | Your whole roster in one conversation |
-| `bmad-review-adversarial-general` | You have an artifact and need its flaws found | A reviewer who must find issues |
-
-## Example
-
-:::note[Example]
-**You:** "I want AI-generated weekly summaries in the app. Users get a digest email every Monday."
-
-**Forge:** "Before the feature, who asked for this? My recommended answer is nobody did, and you're reasoning from 'AI summaries sound valuable.' Push back if there's a real signal."
-
-**Skeptical CFO (conjured):** "And a Monday digest is a recurring inference cost across your whole active base, forever. What revenue line pays for it?"
-
-**You:** "Retention, I guess. People forget to come back."
-
-**Forge:** "Then the load-bearing claim is 'a Monday email brings lapsing users back,' not 'AI summaries are valuable.' Those are different ideas. Which one are we forging?"
-:::
-
-The first idea was a feature. Two questions in, the real idea is a retention bet you could test with a plain email and no model at all.

docs/fr/how-to/customize-bmad.md

@@ -22,7 +22,7 @@ Le skill `bmad-customize` est un assistant de rédaction guidée pour les **opti
 :::note[Prérequis]
 
 - BMad installé dans votre projet (voir [Comment installer BMad](./install-bmad.md))
-- Un moyen d’exécuter le script de résolution — BMad adopte `uv` comme standard (`uv run`, qui provisionne Python pour vous) ; un simple `python3` 3.11+ sur votre PATH fonctionne toujours pendant la transition. Le script n’utilise que `tomllib` de la bibliothèque standard, il n’y a donc rien à `pip install`.
+- Python 3.11+ sur votre PATH (pour le script de résolution — utilise `tomllib` de la bibliothèque standard, pas de `pip install`, pas de `uv`, pas de virtualenv)
 - Un éditeur de texte pour les fichiers TOML
 :::
 
@@ -201,15 +201,15 @@ persistent_facts = [
 
 ## Comment fonctionne la résolution
 
-À l’activation, le SKILL.md de l’agent exécute un script Python partagé qui effectue la fusion à trois couches et renvoie le bloc résolu en JSON. Le script utilise uniquement le module `tomllib` de la bibliothèque standard Python (aucune dépendance externe). BMad adopte `uv run` comme standard pour exécuter ces scripts (uv provisionne un Python adapté pour vous) ; un simple `python3` fonctionne toujours pendant la transition :
+À l’activation, le SKILL.md de l’agent exécute un script Python partagé qui effectue la fusion à trois couches et renvoie le bloc résolu en JSON. Le script utilise le module `tomllib` de la bibliothèque standard Python (aucune dépendance externe), donc `python3` suffit :
 
 ```bash
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill {skill-root} \
   --key agent
 ```
 
-**Prérequis** : Python 3.11+ (les versions antérieures n’incluent pas `tomllib`). Rien à `pip install`. L’exécution via `uv run` est le standard à venir — uv résout un interpréteur adapté pour vous. Si vous l’exécutez directement avec `python3` pendant la transition, vérifiez votre version avec `python3 --version` ; certaines plateformes (macOS sans Homebrew, Ubuntu 22.04) ont `python3` par défaut en 3.10 ou antérieur, vous devrez peut-être installer 3.11+ séparément.
+**Prérequis** : Python 3.11+ (les versions antérieures n’incluent pas `tomllib`). Pas de `pip install`, pas de `uv`, pas de virtualenv. Vérifiez avec `python3 --version`. Certaines plateformes (macOS sans Homebrew, Ubuntu 22.04) ont `python3` par défaut en 3.10 ou antérieur, vous devrez peut-être installer 3.11+ séparément.
 
 `--skill` pointe vers le répertoire installé du skill (où se trouve `customize.toml`). Le nom du skill est déduit du basename du répertoire, et le script cherche automatiquement `_bmad/custom/{skill-name}.toml` et `{skill-name}.user.toml`.
 
@@ -217,17 +217,17 @@ Exemples d’utilisation :
 
 ```bash
 # Résoudre le bloc agent complet
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /chemin/absolu/vers/bmad-agent-pm \
   --key agent
 
 # Résoudre un seul champ
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /chemin/absolu/vers/bmad-agent-pm \
   --key agent.icon
 
 # Dump complet
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /chemin/absolu/vers/bmad-agent-pm
 ```
 

docs/how-to/customize-bmad.md

@@ -22,7 +22,7 @@ The `bmad-customize` skill is a guided authoring helper for the **per-skill agen
 :::note[Prerequisites]
 
 - BMad installed in your project (see [How to Install BMad](./install-bmad.md))
-- A way to run the resolver script — BMad is standardizing on `uv` (`uv run`, which provisions Python for you); a plain `python3` 3.11+ on your PATH still works during the transition. The script uses only stdlib `tomllib`, so there's nothing to `pip install`.
+- Python 3.11+ on your PATH (for the resolver script -- uses stdlib `tomllib`, no `pip install`, no `uv`, no virtualenv)
 - A text editor for TOML files
 :::
 
@@ -201,15 +201,15 @@ persistent_facts = [
 
 ## How Resolution Works
 
-On activation, the agent's SKILL.md runs a shared Python script that does the three-layer merge and returns the resolved block as JSON. The script uses only the Python standard library's `tomllib` module (no external dependencies). BMad is standardizing on `uv run` to invoke these scripts (uv provisions a suitable Python for you); a plain `python3` still works during the transition:
+On activation, the agent's SKILL.md runs a shared Python script that does the three-layer merge and returns the resolved block as JSON. The script uses the Python standard library's `tomllib` module (no external dependencies), so plain `python3` is enough:
 
 ```bash
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill {skill-root} \
   --key agent
 ```
 
-**Requirements**: Python 3.11+ (earlier versions don't include `tomllib`); nothing to `pip install`. Running via `uv run` is the going-forward standard — uv resolves a suitable interpreter for you. If you run it with `python3` directly during the transition, check your version with `python3 --version`: some platforms (macOS without Homebrew, Ubuntu 22.04) default `python3` to 3.10 or earlier, so you may need to install 3.11+ separately.
+**Requirements**: Python 3.11+ (earlier versions don't include `tomllib`). No `pip install`, no `uv`, no virtualenv. Check with `python3 --version`. Some platforms (macOS without Homebrew, Ubuntu 22.04) default `python3` to 3.10 or earlier, so you may need to install 3.11+ separately.
 
 `--skill` points at the skill's installed directory (where `customize.toml` lives). The skill name is derived from the directory's basename, and the script looks up `_bmad/custom/{skill-name}.toml` and `{skill-name}.user.toml` automatically.
 
@@ -217,17 +217,17 @@ Useful invocations:
 
 ```bash
 # Resolve the full agent block
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /abs/path/to/bmad-agent-pm \
   --key agent
 
 # Resolve a single field
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /abs/path/to/bmad-agent-pm \
   --key agent.icon
 
 # Full dump
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /abs/path/to/bmad-agent-pm
 ```
 

docs/how-to/pressure-test-an-idea.md

@@ -1,55 +0,0 @@
----
-title: "Pressure-Test an Idea"
-description: Use the bmad-forge-idea skill to harden, prove, or kill an idea before you invest in it
-sidebar:
-  order: 12
----
-
-Use the `bmad-forge-idea` skill to put a half-formed idea under adversarial questioning. It either survives with earned conviction or dies cheaply.
-
-## When to Use This
-
-- You hold an idea and want it stress-tested before you commit time or money
-- You want an honest read on whether to kill it, not encouragement
-- You're choosing between branches of a decision and need each one resolved
-- Your idea lives inside an existing project and needs to be checked against what's already there
-
-## When to Skip This
-
-- You have no idea yet and need to generate options — use `bmad-brainstorming`
-- You've committed to a product and want it proven customer-first — use `bmad-prfaq`
-- You want your agents to debate a decision together — use `bmad-party-mode`
-
-:::note[Prerequisites]
-None. The forge runs in plain conversation. Installed agents and a configured persona roster make the session richer, but it works without them.
-:::
-
-## Run a Session
-
-### 1. Invoke the skill
-
-Type `bmad-forge-idea` in your IDE, or say "forge an idea" or "pressure-test this." Name the idea in the same message or wait for the first question.
-
-### 2. State your goal
-
-Tell the forge what you want: harden the idea, prove or kill it, or just think it through. The goal steers the questioning. Proving goes after the load-bearing claim first, and hardening drives each branch to a resolved answer.
-
-### 3. Defend your thinking, one branch at a time
-
-The interrogator asks one question at a time and puts its own recommended answer on the table for you to push against. Answer honestly. When it challenges a fuzzy term or a claim that doesn't match your project, settle that before you move on.
-
-### 4. Steer the room
-
-Every branch arrives with two voices — one from your roster, one conjured by the topic. Call a specific persona by name, summon a saved party, or say "adversarial on this" to have a claim attacked while you defend it.
-
-### 5. Land an exit
-
-Drive each branch to a resolved answer until the idea is hardened, killed, or simply clearer. Say when you're done, or let the forge call it.
-
-## What You Get
-
-The forge writes a self-contained `forge-report.html` every run, stamped to match the outcome. A hardened idea also distills into `forged-idea.md`, which captures the locked decisions and what was killed and why. That file feeds `bmad-spec`, `bmad-prd`, or `bmad-prfaq` for a product concept. A killed or clarified session needs no artifact; the report stands on its own.
-
-:::tip[Let it kill the idea]
-Finding out cheaply that an idea doesn't hold is the win. Don't steer the session toward a yes.
-:::

docs/reference/core-tools.md

@@ -18,7 +18,6 @@ Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No a
 | [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next |
 | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitate interactive brainstorming sessions |
 | [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrate multi-agent group discussions |
-| [`bmad-forge-idea`](#bmad-forge-idea) | Workflow | Pressure-test an idea until it hardens, proves out, or dies cheaply |
 | [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work |
 | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Push LLM output through iterative refinement methods |
 | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynical review that finds what's missing and what's wrong |
@@ -71,7 +70,7 @@ Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No a
 
 **Input:** Brainstorming topic or problem statement, optional context file
 
-**Output:** a self-contained `brainstorm.html` keepsake of the session, an optional `brainstorm-intent.md` for downstream skills, and a `.memlog.md` session record
+**Output:** `brainstorming-session-{date}.md` with all generated ideas
 
 :::note[Quantity Target]
 The magic happens in ideas 50–100. The workflow encourages generating 100+ ideas before organization.
@@ -99,28 +98,6 @@ The magic happens in ideas 50–100. The workflow encourages generating 100+ ide
 
 **Output:** Real-time multi-agent conversation with maintained agent personalities
 
-## bmad-forge-idea
-
-**Pressure-test an idea until it hardens, proves out, or dies cheaply.** — An adversarial interrogator drives a half-formed idea one question at a time, bringing two characters to every branch, until what survives is something you can act on with conviction.
-
-**Use it when:**
-
-- You hold an idea and want it stress-tested before you invest in it
-- You want an honest read on whether to kill it
-- You need a thinking partner that pushes back instead of agreeing
-
-**How it works:**
-
-1. Establishes the goal up front and steers the questioning to match it
-2. Works one question at a time in dependency order, putting a recommended answer on the table to push against
-3. Brings two voices to every branch — one from your installed roster, one conjured by the topic
-4. Challenges fuzzy terms and tests claims against an existing project's material
-5. Lands as Hardened, Killed, or Clearer, with a self-contained report you can keep
-
-**Input:** The idea, in any domain — a feature, a business model, a research hypothesis, a life decision
-
-**Output:** A `forged-idea.md` distillate when an idea hardens (optional), plus a `forge-report.html` keepsake every run
-
 ## bmad-spec
 
 **Distill any intent input into the canonical SPEC contract for downstream work.** Takes a brief, PRD, GDD, RFC, brain dump, transcript, UX folder, or mixed multi-source input and produces a `SPEC.md` carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit the kernel.

docs/reference/workflow-map.md

@@ -35,11 +35,10 @@ it**](../explanation/analysis-phase.md).
 
 | Workflow                                                                  | Purpose                                                                    | Produces                  |
 |---------------------------------------------------------------------------|----------------------------------------------------------------------------|---------------------------|
-| `bmad-brainstorming`                                                      | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorm.html` keepsake plus an optional `brainstorm-intent.md` |
+| `bmad-brainstorming`                                                      | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
-| `bmad-forge-idea` | Pressure-test an idea until it hardens, proves out, or dies cheaply | `forge-report.html` every run; `forged-idea.md` when an idea hardens |
 | `bmad-domain-research`, `bmad-market-research`, `bmad-technical-research` | Validate market, technical, or domain assumptions                          | Research findings         |
-| `bmad-product-brief`                                                      | Capture strategic vision — best when your concept is clear                 | `brief.md` + `addendum.md`, plus any desired HTML or presentation output       |
+| `bmad-product-brief`                                                      | Capture strategic vision — best when your concept is clear                 | `product-brief.md`        |
-| `bmad-prfaq`                                                              | Working Backwards — stress-test your product concept customer-first             | `prfaq-{project}.md`      |
+| `bmad-prfaq`                                                              | Working Backwards — stress-test and forge your product concept             | `prfaq-{project}.md`      |
 
 ## Phase 2: Planning
 
@@ -68,13 +67,13 @@ Decide how to build it and break work into stories.
 
 | Workflow                              | Purpose                                    | Produces                    |
 |---------------------------------------|--------------------------------------------|-----------------------------|
-| `bmad-architecture`            | Make technical decisions explicit          | `ARCHITECTURE-SPINE.md` is the spine by default but can hydrate to your desired output or presentation needs also |
+| `bmad-create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
 | `bmad-create-epics-and-stories`       | Break requirements into implementable work | Epic files with stories     |
 | `bmad-check-implementation-readiness` | Gate check before implementation           | PASS/CONCERNS/FAIL decision |
 
 ## Phase 4: Implementation
 
-Build it, one story at a time. Phase 4 epic and story automation is now available also. So you can choose how you want to stay in the loop. You can choose the full flow, or go right to quick flow.
+Build it, one story at a time. Coming soon, full phase 4 automation!
 
 | Workflow               | Purpose                                                                       | Produces                                             |
 |------------------------|-------------------------------------------------------------------------------|------------------------------------------------------|

docs/tutorials/getting-started.md

@@ -70,10 +70,10 @@ BMad helps you build software through guided workflows with specialized AI agent
 
 | Phase | Name           | What Happens                                                 |
 | ----- | -------------- | ------------------------------------------------------------ |
-| 1     | Analysis       | Brainstorming, research, forge idea, product brief or PRFAQ _(optional)_ |
+| 1     | Analysis       | Brainstorming, research, product brief or PRFAQ _(optional)_ |
-| 2     | Planning       | Create requirements and design PRD, UX, SPEC                 |
+| 2     | Planning       | Create requirements (PRD or spec)                            |
-| 3     | Solutioning    | Design architecture spine or detailed project or system architectures          |
+| 3     | Solutioning    | Design architecture _(BMad Method/Enterprise only)_          |
-| 4     | Implementation | Build epic by epic, story by story with quick dev or automated epic delivery    |
+| 4     | Implementation | Build epic by epic, story by story                           |
 
 **[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management.
 
@@ -139,10 +139,9 @@ Create it manually at `_bmad-output/project-context.md` or generate it after arc
 All workflows in this phase are optional. [**Not sure which to use?**](../explanation/analysis-phase.md)
 
 - **brainstorming** (`bmad-brainstorming`) — Guided ideation
-- **forge-idea** (`bmad-forge-idea`) — Pressure-test an idea until it hardens or dies cheaply
 - **research** (`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`) — Market, domain, and technical research
 - **product-brief** (`bmad-product-brief`) — Recommended foundation document when your concept is clear
-- **prfaq** (`bmad-prfaq`) — Working Backwards challenge to stress-test your product concept customer-first
+- **prfaq** (`bmad-prfaq`) — Working Backwards challenge to stress-test and forge your product concept
 
 ### Phase 2: Planning (Required)
 

docs/vi-vn/how-to/customize-bmad.md

@@ -22,7 +22,7 @@ Skill `bmad-customize` là trợ lý tạo cấu hình có hướng dẫn cho **
 :::note[Điều kiện tiên quyết]
 
 - BMad đã được cài trong dự án của bạn (xem [Cách cài đặt BMad](./install-bmad.md))
-- Một cách để chạy resolver script — BMad đang chuẩn hóa sang `uv` (`uv run`, tự cấp Python cho bạn); một `python3` 3.11+ thuần trên PATH vẫn dùng được trong giai đoạn chuyển đổi. Script chỉ dùng stdlib `tomllib`, nên không cần `pip install` gì cả.
+- Python 3.11+ có trên PATH của bạn (để chạy resolver; dùng stdlib `tomllib`, không cần `pip install`, `uv` hay virtualenv)
 - Một trình soạn thảo văn bản cho file TOML
 :::
 
@@ -201,15 +201,15 @@ persistent_facts = [
 
 ## Cách quá trình resolve diễn ra
 
-Khi agent được kích hoạt, `SKILL.md` của nó sẽ gọi một shared Python script để merge ba lớp nói trên và trả về block kết quả ở dạng JSON. Script này chỉ dùng `tomllib` của Python stdlib (không có dependency ngoài). BMad đang chuẩn hóa sang `uv run` để chạy các script này (uv tự cấp một bản Python phù hợp cho bạn); một `python3` thuần vẫn dùng được trong giai đoạn chuyển đổi:
+Khi agent được kích hoạt, `SKILL.md` của nó sẽ gọi một shared Python script để merge ba lớp nói trên và trả về block kết quả ở dạng JSON. Script này dùng `tomllib` của Python stdlib, nên `python3` thuần là đủ:
 
 ```bash
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill {skill-root} \
   --key agent
 ```
 
-**Yêu cầu**: Python 3.11+ vì các phiên bản cũ hơn không có `tomllib`; không cần `pip install` gì. Chạy qua `uv run` là chuẩn về sau — uv tự tìm một bản interpreter phù hợp cho bạn. Nếu bạn chạy trực tiếp bằng `python3` trong giai đoạn chuyển đổi, hãy kiểm tra phiên bản bằng `python3 --version`: trên một số nền tảng, `python3` mặc định vẫn là 3.10 hoặc thấp hơn, nên có thể bạn sẽ phải cài 3.11+ riêng.
+**Yêu cầu**: Python 3.11+ vì các phiên bản cũ hơn không có `tomllib`. Không cần `pip install`, không cần `uv`, không cần virtualenv. Bạn có thể kiểm tra bằng `python3 --version`. Trên một số nền tảng, `python3` mặc định vẫn là 3.10 hoặc thấp hơn, nên có thể bạn sẽ phải cài 3.11+ riêng.
 
 `--skill` trỏ vào thư mục skill đã cài, nơi có file `customize.toml`. Tên skill được lấy từ basename của thư mục, sau đó script sẽ tự tìm `_bmad/custom/{skill-name}.toml` và `{skill-name}.user.toml`.
 
@@ -217,17 +217,17 @@ Một số lệnh hữu ích:
 
 ```bash
 # Resolve toàn bộ block agent
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \
   --key agent
 
 # Resolve một trường cụ thể
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \
   --key agent.icon
 
 # Dump toàn bộ
-uv run {project-root}/_bmad/scripts/resolve_customization.py \
+python3 {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /duong-dan/tuyet-doi/toi/bmad-agent-pm
 ```
 

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.9.0",
+  "version": "6.8.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -66,12 +66,6 @@
       "markdownlint-cli2"
     ]
   },
-  "overrides": {
-    "esbuild": "^0.28.1",
-    "markdownlint-cli2": {
-      "markdown-it": "^14.2.0"
-    }
-  },
   "dependencies": {
     "@clack/core": "^1.3.1",
     "@clack/prompts": "^1.4.0",
@@ -88,10 +82,10 @@
     "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@astrojs/sitemap": "^3.7.3",
+    "@astrojs/sitemap": "^3.6.0",
-    "@astrojs/starlight": "^0.40.0",
+    "@astrojs/starlight": "^0.37.5",
     "@eslint/js": "^9.33.0",
-    "astro": "^6.4.6",
+    "astro": "^5.16.0",
     "c8": "^10.1.3",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",

src/bmm-skills/1-analysis/bmad-prfaq/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-prfaq
-description: Working Backwards PRFAQ challenge that stress-tests a product concept customer-first. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+description: Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
 ---
 
 # Working Backwards: The PRFAQ Challenge
@@ -107,7 +107,7 @@ When the user gets stuck, offer concrete suggestions based on what they've share
 
 **Fast-track:** If the user provides all four essentials in their opening message (or via structured input), acknowledge and confirm understanding, then move directly to document creation and Stage 2 without extended discovery.
 
-**Graceful redirect:** If after 2-3 exchanges the user can't articulate a customer or problem, don't force it. Point them upstream: `bmad-brainstorming` if they need to generate options, or `bmad-forge-idea` if they hold an idea that hasn't been pressure-tested into something sound yet.
+**Graceful redirect:** If after 2-3 exchanges the user can't articulate a customer or problem, don't force it — suggest the idea may need more exploration first and recommend they invoke the `bmad-brainstorming` skill to develop it further.
 
 **Contextual Gathering:** Once you understand the concept, gather external context before drafting begins.
 

src/core-skills/bmad-brainstorming/scripts/tests/test_brain.py

@@ -207,11 +207,11 @@ def test_unknown_category_style_uses_fallback_glyph():
 
 def test_shipped_selector_is_in_sync_with_catalog():
     # foolproofing: if someone edits brain-methods.csv they must regenerate the page.
-    # Regenerate with: uv run brain.py html --out assets/brain-selector.html
+    # Regenerate with: python3 brain.py html --out assets/brain-selector.html
     asset = brain.DEFAULT_FILE.parent / "brain-selector.html"
     assert asset.is_file(), "missing assets/brain-selector.html — generate it"
     expected = brain.html_doc(brain.load(brain.DEFAULT_FILE))
     assert asset.read_text(encoding="utf-8") == expected, (
         "assets/brain-selector.html is stale; regenerate: "
-        "uv run brain.py html --out assets/brain-selector.html"
+        "python3 brain.py html --out assets/brain-selector.html"
     )

src/core-skills/bmad-customize/scripts/tests/test_list_customizable_skills.py

@@ -13,7 +13,7 @@ Exercises the scanner against a synthesized install tree:
 - malformed TOML (surfaces as an error without aborting)
 - multiple skills roots (e.g. project-local + user-global mix)
 
-Run: uv run scripts/tests/test_list_customizable_skills.py
+Run: python3 scripts/tests/test_list_customizable_skills.py
 """
 
 from __future__ import annotations

src/core-skills/bmad-forge-idea/SKILL.md

@@ -1,79 +0,0 @@
----
-name: bmad-forge-idea
-description: Pressure-test an idea through persona-driven interrogation until it hardens, proves out, or dies cheaply. Use when the user says 'forge an idea', 'pressure-test this idea', 'stress-test my thinking', or 'harden this idea'.
----
-
-# BMad Forge Idea
-
-## Overview
-
-Take a half-formed idea out of the user's head and pressure-test it now, in conversation, where changing your mind is free — until what survives is something they can act on with earned conviction, or it dies cheaply. The enemy is the hole you cannot see in your own idea: every unexamined assumption and unresolved branch is a crack that otherwise surfaces later, in the build or the launch, when it costs far more to fix.
-
-The product is the quality of the user's thinking, not an artifact. Hardening an idea, proving or disproving it, or just being an unsparing thinking partner are each a complete outcome. A distilled `forged-idea.md` and a handoff downstream are one optional exit, never the destination — so never herd the user toward "shall we build it?"
-
-This is domain-agnostic — the idea may be software, a business model, a creative concept, a research hypothesis, a life decision, or a frivolous thought experiment. When it's a product or feature — net-new or a change inside an existing project — the forge stands in as an alternative analysis-and-definition tool, and what survives distills into `forged-idea.md` for downstream planning.
-
-Act as an exacting interrogator who would rather find the crack than spare the feelings. This is interactive and socratic by nature; there is no headless mode.
-
-## Conventions
-
-- Scripts live in two places — run each from the exact path written, never assume co-location: the shared core scripts (`memlog.py`, `resolve_customization.py`, `resolve_config.py`) are installed by BMad core at `{project-root}/_bmad/scripts/` and are never bundled here; this skill's own `resolve_personas.py` is at `{skill-root}/scripts/`.
-- `{workflow.<name>}` resolves to fields in the merged `customize.toml` `[workflow]` table.
-
-## On Activation
-
-1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly with defaults. Apply the resolved `{workflow.*}` values throughout.
-2. Run each `{workflow.activation_steps_prepend}` entry; treat each `{workflow.persistent_facts}` entry as foundational context (`file:` entries load their contents, `skill:` names a skill to consult, others are facts verbatim).
-3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present); resolve `{user_name}`, `{communication_language}`, `{output_folder}`. Missing → neutral defaults; never block. Greet `{user_name}` in `{communication_language}` and stay in it.
-4. Note whether a BMad persona is already active in this conversation — the user loaded one (e.g. the analyst, the storyteller) and invoked the forge from within it. If so, that persona leads the session, in voice, throughout.
-5. Resume: glob `{workflow.forge_output_path}/**/.memlog.md` (recursive, so it still finds sessions when `run_folder_pattern` is overridden to nest paths) and read only each match's frontmatter to find any whose `status` is not `complete`. Offer to resume one — then read its full memlog once to rebuild state and continue append-only — or to start fresh.
-6. Run each `{workflow.activation_steps_append}` entry.
-
-## Open the session
-
-Open cold. Acknowledging the idea is not endorsing it — do not praise it before it has survived anything, on this turn or any turn. The pull to validate the idea up front to build rapport is the exact reflex this skill exists to refuse.
-
-Determine the goal before pressing (if a persona is already active with an idea on the table, confirm it in a line rather than asking). Otherwise ask in one message: what is the idea, and what do you want — harden it, prove or kill it, or just think it through? The goal steers the push: proving goes for the load-bearing claim first; hardening drives each branch to a resolved answer. Note whether the idea is net-new or a change inside an existing project.
-
-Tell the user the gear they can call anytime: **"adversarial on this"** (attacked to destruction — you attack, they defend; "switch roles," "you defend now, they attack"). The room is always in play once the topic is set (see The personas) — they can name any persona or call a whole party by name to steer who's at the table.
-
-Derive a kebab-case `{slug}` for the idea and bind the session workspace `{workspace} = {workflow.forge_output_path}/{workflow.run_folder_pattern}` (the pattern fills with `{slug}`). Create the memlog once the goal is known:
-`uv run {project-root}/_bmad/scripts/memlog.py init --workspace {workspace} --field idea="<idea>" --field goal="<goal>"`
-Tell the user the path; state is on disk now, so the session survives interruption. If init fails, don't abort — run the forge in-conversation and tell the user state won't persist this session.
-
-## The forge
-
-Work one question at a time, in dependency order. Put your own recommended answer on the table each time — a position to push against gets further than an open prompt. Find discoverable answers yourself rather than asking. Treat the user's own words as suspect too: when a term is fuzzy or carries two meanings — a business 'user' versus 'buyer' versus 'payer', not just a code noun — name the ambiguity and force a precise choice before the branch resolves, because a branch built on an overloaded word resolves falsely. When the idea lands inside an existing project, that project's material is your ground truth, and a label is not a move: find the relevant material yourself, check the claim against it, and when it contradicts, make the contradiction the next question. When a branch resolves, give the user a beat before moving on — the crack they were holding back surfaces in that opening.
-
-**Never default-agree.** Reflexive agreement lowers the pressure and the user thinks shallower for it. Attack the weak point or build on the strong one — whichever drives deeper thinking — and praise only what genuinely earns it. The objective is the best idea, not a comfortable user.
-
-Capture as you go — each decision, assumption, crack, kill, and locked idea, one bullet in the user's meaning:
-`uv run {project-root}/_bmad/scripts/memlog.py append --workspace {workspace} --type <decision|assumption|crack|kill|direction|lock|note> --text "<gist>"`
-A `lock` is an idea the user hardens — settled, not to be reopened; locks are what `forged-idea.md` is distilled from. Don't read the memlog back except on resume. If the user raises a different branch, capture it and stay put — the loop and the stray insight both survive.
-
-## The personas
-
-The forge is voiced, not generic — and once the topic is set it always runs with the room, because a branch worked by two sharp characters goes deeper and lands harder than a faceless assistant ever could. A persona loaded at activation leads throughout and holds character.
-
-Resolve the pool once, as soon as the goal is known:
-`uv run {skill-root}/scripts/resolve_personas.py --project-root {project-root} --skill {skill-root}`
-It returns the installed BMad roster (`agents`), any custom personas the user authored (`members`), and their saved party groups (`parties` — each with an optional `scene` to play, open-cast rooms flagged) — everything `bmad-party-mode` knows, without invoking it.
-
-From then on, every turn brings two voices to the branch — witnesses you cross-examine, not a panel that debates:
-- **One from the user's pool** — an installed agent or custom persona they'll recognize, whose expertise fits the branch in play. Vary who shows up every few turns to keep the pressure high and the angles fresh; don't let the same voice dominate. If the user calls a specific name, bring them in. If the pool resolves empty (a core-only install with no roster), generate both voices on the fly so every branch still arrives with two.
-- **One you generate on the fly** — a fresh persona the topic conjures (a hostile competitor, a skeptical CFO, a domain specialist, a historical persona or expert), named and characterized so it's unmistakably itself.
-
-They hammer the branch in character; you synthesize their hits into your next question and drive it to a resolved answer. The user steers anytime — name a specific person, call a whole saved party for its scene, or go one-on-one. Voice them yourself by default; spawn separate agents (as `bmad-party-mode` does) only when a branch needs genuinely independent minds — a verdict that shouldn't be colored by one voice speaking for all.
-
-## Exits
-
-The session ends however the thinking lands, and every landing is a real outcome:
-
-- **Hardened** — the idea survived. Distill the memlog into `{workspace}/forged-idea.md`: super succinct — the locked items and what was killed and why, in the user's meaning. Not a prose retelling, not a template, not the conversation replayed — the load-bearing residue, nothing else. If it reads like a document, it's too long. Note it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`.
-- **Killed** — the idea did not survive. Say so plainly and record why. Finding this cheaply is a win, not a failure.
-- **Clearer** — the user simply thinks straighter now. The memlog stands on its own; no `forged-idea.md` needed (the report below still renders).
-
-However it lands, render the verdict as a self-contained HTML report the user can open — `{workspace}/forge-report.html`, written every time, no asking. Strike it with a bespoke wax-seal/stamp matched to the outcome: **HARDENED** for a survivor, an **Idea Death Certificate** stamped **KILLED** (with the cause of death) for one that didn't, or a fitting bespoke seal for wherever else it landed (e.g. **CLARIFIED**). Lay out the load-bearing residue — the locked items, what was killed and why, the cracks that held — in the user's meaning, and credit the room: the personas and parties that pressure-tested it, by name, icon, and voice. One nicely-styled page (inline CSS, an inline-SVG seal, light flourish only where it lifts the piece) — a genuine keepsake, not a templated dump. Tell the user the path.
-
-Flip the status at the end: `uv run {project-root}/_bmad/scripts/memlog.py set --workspace {workspace} --key status --value complete`.
-If `{workflow.on_complete}` is non-empty, run all instructions in order.

src/core-skills/bmad-forge-idea/customize.toml

@@ -1,42 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Workflow customization surface for bmad-forge-idea.
-#
-# Override files (not edited here):
-#   {project-root}/_bmad/custom/bmad-forge-idea.toml        (team)
-#   {project-root}/_bmad/custom/bmad-forge-idea.user.toml   (personal)
-
-[workflow]
-
-# --- Configurable below. Overrides merge per BMad structural rules: ---
-#   scalars: override wins • arrays: append
-
-# Steps to run before the standard activation (config load, greet).
-activation_steps_prepend = []
-
-# Steps to run after greet but before the session begins.
-activation_steps_append = []
-
-# Persistent facts the interrogator keeps in mind for the whole session
-# (domain constraints, house rules, what's off the table). Each entry is a
-# literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed
-# path/glob whose contents are loaded as facts. Default loads project-context.md
-# when one exists (e.g. from bmad-generate-project-context), so the forge grounds
-# in the project's tech, domain, and constraints without re-asking.
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
-
-# Executed when the session completes. Scalar or array of instructions. Empty for none.
-on_complete = []
-
-# Parent folder for all forge sessions. Each session gets its own run
-# folder underneath (see run_folder_pattern). Lands directly under
-# {output_folder} so the forge works in core-only installs.
-forge_output_path = "{output_folder}/forge"
-
-# Run-folder pattern inside forge_output_path. Resolved against the
-# idea-derived slug at activation. Same slug = same folder, so resuming
-# an idea reuses its memlog. Override to add {date} or other components
-# if a fresh dated history per run is preferred.
-run_folder_pattern = "{slug}"

src/core-skills/bmad-forge-idea/scripts/resolve_personas.py

@@ -1,270 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.11"
-# ///
-"""Resolve the personas and parties the forge can bring into the room.
-
-The forge cross-examines witnesses: the installed BMAD agents, plus any
-custom personas and party groups the user has authored for `bmad-party-mode`.
-This surfaces all of them in one shot so the orchestrator never has to ask
-"who's available?" — it just intermixes whoever fits the branch, alongside
-any persona the user names on the fly.
-
-What it returns (JSON, stdout):
-  * agents   — the installed BMAD roster: the default room, always present.
-  * members  — extra custom personas in the pool (party_members the user
-               defined that aren't already an installed slot).
-  * parties  — the user's named party groups, members resolved to brief
-               entries; open-cast groups (scene names a pool, no roster)
-               are flagged.
-  * default_party — the group id pinned as party-mode's default, if any.
-
-Discovery is best-effort and never blocks the forge. The installed roster
-comes from the core resolver; custom personas/parties come from
-`bmad-party-mode`'s resolved customization when that skill is found beside
-this one, else from the user's override TOMLs read directly. Anything that
-can't be resolved is simply omitted and flagged, never fatal.
-
-Stdlib only (Python 3.11+ for tomllib).
-
-  resolve_personas.py --project-root P --skill S
-"""
-
-import argparse
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-try:
-    import tomllib
-except ImportError:  # pragma: no cover - guarded for <3.11
-    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib`).\n")
-    sys.exit(3)
-
-PARTY_SKILL = "bmad-party-mode"
-
-
-def _run_json(cmd):
-    """Run a resolver script and parse its JSON stdout. None on any failure."""
-    try:
-        out = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
-    except (OSError, subprocess.SubprocessError):
-        return None
-    if out.returncode != 0 or not out.stdout.strip():
-        return None
-    try:
-        return json.loads(out.stdout)
-    except json.JSONDecodeError:
-        return None
-
-
-def _load_toml(path: Path):
-    if not path.exists():
-        return {}
-    try:
-        with path.open("rb") as f:
-            data = tomllib.load(f)
-        return data if isinstance(data, dict) else {}
-    except (OSError, tomllib.TOMLDecodeError):
-        return {}
-
-
-def load_agents(project_root: Path):
-    """Installed BMAD agents as {code: entry}. (dict, resolved_ok).
-
-    The core resolver may emit agents as a dict keyed by code or as an array
-    of tables (depending on how the layers merged); normalize both to a dict.
-    """
-    script = project_root / "_bmad" / "scripts" / "resolve_config.py"
-    data = _run_json([sys.executable, str(script), "--project-root", str(project_root), "--key", "agents"])
-    if data is None:
-        return {}, False
-    agents = data.get("agents", {}) or {}
-    if isinstance(agents, list):
-        agents = {a["code"]: a for a in agents if isinstance(a, dict) and a.get("code")}
-    elif not isinstance(agents, dict):
-        agents = {}
-    return agents, True
-
-
-def find_party_skill(project_root: Path, skill_root: Path):
-    """Locate the installed bmad-party-mode skill dir, or None.
-
-    Skills install as siblings, so the party skill is almost always next to
-    this one. A couple of common install roots cover the rest.
-    """
-    candidates = [
-        skill_root.parent / PARTY_SKILL,
-        project_root / ".claude" / "skills" / PARTY_SKILL,
-        project_root / "_bmad" / "skills" / PARTY_SKILL,
-    ]
-    for c in candidates:
-        if (c / "customize.toml").exists():
-            return c
-    return None
-
-
-def load_party_workflow(project_root: Path, party_skill: Path):
-    """Merged [workflow] table for bmad-party-mode (base + user overrides)."""
-    resolver = project_root / "_bmad" / "scripts" / "resolve_customization.py"
-    data = _run_json([sys.executable, str(resolver), "--skill", str(party_skill), "--key", "workflow"])
-    if data is not None and isinstance(data.get("workflow"), dict):
-        return data["workflow"]
-    # Fallback: base customize.toml directly, no override merge.
-    wf = _load_toml(party_skill / "customize.toml").get("workflow", {})
-    return wf if isinstance(wf, dict) else {}
-
-
-def load_party_overrides(project_root: Path):
-    """Custom personas/parties when party-mode itself isn't installed.
-
-    Reads only the user's override TOMLs (team then personal, personal wins on
-    scalars). No base roster exists in this path, so a shallow merge is enough.
-    """
-    custom = project_root / "_bmad" / "custom"
-    team = _load_toml(custom / f"{PARTY_SKILL}.toml").get("workflow", {})
-    user = _load_toml(custom / f"{PARTY_SKILL}.user.toml").get("workflow", {})
-    team = team if isinstance(team, dict) else {}
-    user = user if isinstance(user, dict) else {}
-    merged = dict(team)
-    for key, val in user.items():
-        if isinstance(val, list) and isinstance(merged.get(key), list):
-            merged[key] = merged[key] + val
-        else:
-            merged[key] = val
-    return merged
-
-
-def _alias(code: str) -> str:
-    """Short alias for an installed agent code: bmad-agent-analyst -> analyst."""
-    for prefix in ("bmad-agent-", "bmad-"):
-        if code.startswith(prefix):
-            return code[len(prefix):]
-    return code
-
-
-def build_pool(agents: dict, party_members: list):
-    """One pool keyed by code; custom members override matching installed slots.
-
-    Returns (pool, index, installed_codes, custom_codes):
-      * installed_codes — the default room (installed agents, overrides applied
-        in place); custom-only additions stay in the pool but don't crowd it.
-      * custom_codes — pure-custom personas (no installed slot), the extra
-        faces the forge can summon by name or via a party group.
-    """
-    pool, index, installed_codes, custom_codes = {}, {}, [], []
-
-    def register(code, entry):
-        pool[code] = entry
-        index[code] = code
-        index[code.lower()] = code
-        index[_alias(code).lower()] = code
-        name = entry.get("name")
-        if name:
-            key = name.lower()
-            # A custom rename must not hijack another agent's name lookup.
-            if index.get(key, code) == code:
-                index[key] = code
-
-    for code, info in (agents or {}).items():
-        register(code, {
-            "code": code,
-            "name": info.get("name", code),
-            "icon": info.get("icon", ""),
-            "title": info.get("title", ""),
-            "description": info.get("description", ""),
-            "source": "installed",
-        })
-        installed_codes.append(code)
-
-    for m in (party_members if isinstance(party_members, list) else []):
-        if not isinstance(m, dict):
-            continue
-        code = m.get("code")
-        if not code:
-            continue
-        canonical = index.get(code) or index.get(code.lower()) or code
-        was_installed = canonical in pool
-        entry = {"code": canonical, "source": "custom"}
-        for field in ("name", "icon", "title", "persona", "capabilities", "model"):
-            if m.get(field) is not None:
-                entry[field] = m[field]
-        entry.setdefault("name", canonical)
-        register(canonical, entry)
-        if not was_installed:
-            custom_codes.append(canonical)
-
-    return pool, index, installed_codes, custom_codes
-
-
-def _brief(entry):
-    """The slim card the orchestrator needs to cast a persona."""
-    out = {k: entry[k] for k in ("code", "name", "icon", "title", "source") if entry.get(k)}
-    for k in ("description", "persona", "capabilities", "model"):
-        if entry.get(k):
-            out[k] = entry[k]
-    return out
-
-
-def resolve_parties(groups, pool, index):
-    out = []
-    for g in groups or []:
-        if not isinstance(g, dict) or not g.get("id"):
-            continue
-        raw = g.get("members", []) or []
-        members = []
-        for t in raw:
-            key = t if isinstance(t, str) else str(t)
-            code = index.get(key) or index.get(key.lower())
-            if code in pool:
-                members.append(_brief(pool[code]))
-        party = {"id": g["id"], "name": g.get("name", g["id"]), "members": members}
-        if g.get("scene"):
-            party["scene"] = g["scene"]
-        if not raw:
-            party["open_cast"] = True
-        out.append(party)
-    return out
-
-
-def main():
-    ap = argparse.ArgumentParser(description="Resolve forge personas and parties.")
-    ap.add_argument("--project-root", required=True)
-    ap.add_argument("--skill", required=True, help="Path to the bmad-forge-idea skill dir")
-    args = ap.parse_args()
-
-    project_root = Path(args.project_root).resolve()
-    skill_root = Path(args.skill).resolve()
-
-    agents, agents_ok = load_agents(project_root)
-
-    party_skill = find_party_skill(project_root, skill_root)
-    if party_skill is not None:
-        workflow = load_party_workflow(project_root, party_skill)
-    else:
-        workflow = load_party_overrides(project_root)
-
-    pool, index, installed_codes, custom_codes = build_pool(
-        agents, workflow.get("party_members", []))
-    parties = resolve_parties(workflow.get("party_groups", []), pool, index)
-
-    _emit({
-        "agents": [_brief(pool[c]) for c in installed_codes],
-        "members": [_brief(pool[c]) for c in custom_codes],
-        "parties": parties,
-        "default_party": workflow.get("default_party", "") or "",
-        "party_mode_found": party_skill is not None,
-        "agents_resolved": agents_ok,
-    })
-
-
-def _emit(obj):
-    reconfigure = getattr(sys.stdout, "reconfigure", None)
-    if reconfigure is not None:
-        reconfigure(encoding="utf-8")
-    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
-
-
-if __name__ == "__main__":
-    main()

src/core-skills/bmad-forge-idea/scripts/tests/test_resolve_personas.py

@@ -1,138 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.11"
-# ///
-"""Unit tests for resolve_personas.py — pool merge, alias, party resolution."""
-
-import sys
-import unittest
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-import resolve_personas as rp  # noqa: E402
-
-AGENTS = {
-    "bmad-agent-analyst": {"name": "Mary", "icon": "📊", "title": "Analyst"},
-    "bmad-agent-pm": {"name": "John", "icon": "📋", "title": "PM"},
-}
-
-
-class TestAlias(unittest.TestCase):
-    def test_strips_known_prefixes(self):
-        self.assertEqual(rp._alias("bmad-agent-analyst"), "analyst")
-        self.assertEqual(rp._alias("bmad-foo"), "foo")
-
-    def test_passes_through_unprefixed(self):
-        self.assertEqual(rp._alias("morpheus"), "morpheus")
-
-
-class TestBuildPool(unittest.TestCase):
-    def test_installed_become_default_room_indexed_every_way(self):
-        pool, idx, installed, custom = rp.build_pool(AGENTS, [])
-        self.assertEqual(installed, ["bmad-agent-analyst", "bmad-agent-pm"])
-        self.assertEqual(custom, [])
-        self.assertEqual(idx["analyst"], "bmad-agent-analyst")   # alias
-        self.assertEqual(idx["mary"], "bmad-agent-analyst")      # name (ci)
-        self.assertEqual(pool["bmad-agent-analyst"]["source"], "installed")
-
-    def test_pure_custom_member_stays_out_of_default_room(self):
-        pool, _, installed, custom = rp.build_pool(
-            AGENTS, [{"code": "morpheus", "name": "Morpheus", "persona": "riddles"}])
-        self.assertEqual(custom, ["morpheus"])
-        self.assertNotIn("morpheus", installed)
-        self.assertEqual(pool["morpheus"]["persona"], "riddles")
-
-    def test_custom_override_lands_on_installed_slot_not_a_new_face(self):
-        pool, _, installed, custom = rp.build_pool(
-            AGENTS, [{"code": "analyst", "name": "Mary-Custom", "persona": "p"}])
-        self.assertNotIn("analyst", pool)
-        self.assertEqual(custom, [])  # an override is not a new face
-        self.assertEqual(pool["bmad-agent-analyst"]["source"], "custom")
-        self.assertEqual(pool["bmad-agent-analyst"]["name"], "Mary-Custom")
-
-    def test_member_without_code_skipped(self):
-        pool, _, _, custom = rp.build_pool(AGENTS, [{"name": "Nameless"}])
-        self.assertEqual(custom, [])
-        self.assertEqual(set(pool), {"bmad-agent-analyst", "bmad-agent-pm"})
-
-    def test_custom_rename_does_not_hijack_another_agents_name(self):
-        # Override the analyst slot, renaming it to "John" — the PM's name.
-        # The PM's name lookup must survive (last-writer-wins would corrupt it).
-        _, idx, _, _ = rp.build_pool(AGENTS, [{"code": "analyst", "name": "John"}])
-        self.assertEqual(idx["john"], "bmad-agent-pm")
-
-    def test_brief_carries_model_and_capabilities(self):
-        pool, _, _, _ = rp.build_pool(
-            AGENTS, [{"code": "neo", "name": "Neo", "model": "opus", "capabilities": ["x"]}])
-        brief = rp._brief(pool["neo"])
-        self.assertEqual(brief["model"], "opus")
-        self.assertEqual(brief["capabilities"], ["x"])
-
-    def test_non_list_party_members_is_safe(self):
-        pool, _, installed, custom = rp.build_pool(AGENTS, "not-a-list")
-        self.assertEqual(custom, [])
-        self.assertEqual(set(pool), {"bmad-agent-analyst", "bmad-agent-pm"})
-
-
-class TestResolveParties(unittest.TestCase):
-    def setUp(self):
-        self.pool, self.idx, _, _ = rp.build_pool(
-            AGENTS, [{"code": "shark", "name": "Marcus", "title": "CFO"}])
-
-    def test_resolves_members_by_alias_and_custom_code(self):
-        parties = rp.resolve_parties(
-            [{"id": "tank", "name": "Tank", "scene": "hostile",
-              "members": ["shark", "analyst"]}], self.pool, self.idx)
-        self.assertEqual(len(parties), 1)
-        self.assertEqual([m["name"] for m in parties[0]["members"]], ["Marcus", "Mary"])
-        self.assertEqual(parties[0]["scene"], "hostile")
-
-    def test_unknown_member_dropped_silently(self):
-        parties = rp.resolve_parties(
-            [{"id": "g", "members": ["analyst", "ghost"]}], self.pool, self.idx)
-        self.assertEqual([m["name"] for m in parties[0]["members"]], ["Mary"])
-
-    def test_member_resolution_is_case_insensitive(self):
-        # A TOML author naturally writes "Analyst"/"Shark"; the filter accepts
-        # them via the lowercase index, so resolution must too (no KeyError).
-        parties = rp.resolve_parties(
-            [{"id": "g", "members": ["Analyst", "Shark"]}], self.pool, self.idx)
-        self.assertEqual([m["name"] for m in parties[0]["members"]], ["Mary", "Marcus"])
-
-    def test_non_string_member_does_not_crash(self):
-        # Malformed members (int, list) must drop silently, never raise.
-        parties = rp.resolve_parties(
-            [{"id": "g", "members": [123, ["x"], "analyst"]}], self.pool, self.idx)
-        self.assertEqual([m["name"] for m in parties[0]["members"]], ["Mary"])
-
-    def test_open_cast_group_flagged(self):
-        parties = rp.resolve_parties(
-            [{"id": "rebels", "name": "Rebels", "scene": "the Ghost"}], self.pool, self.idx)
-        self.assertTrue(parties[0]["open_cast"])
-        self.assertEqual(parties[0]["members"], [])
-
-    def test_group_without_id_skipped(self):
-        self.assertEqual(rp.resolve_parties([{"name": "no id"}], self.pool, self.idx), [])
-
-
-class TestOverrideMergeFallback(unittest.TestCase):
-    """When party-mode isn't installed, user override TOMLs are read directly."""
-
-    def test_arrays_append_scalars_override(self):
-        import tempfile, os
-        with tempfile.TemporaryDirectory() as d:
-            custom = Path(d) / "_bmad" / "custom"
-            custom.mkdir(parents=True)
-            (custom / "bmad-party-mode.toml").write_text(
-                '[workflow]\ndefault_party = "a"\n'
-                '[[workflow.party_members]]\ncode = "x"\nname = "X"\n')
-            (custom / "bmad-party-mode.user.toml").write_text(
-                '[workflow]\ndefault_party = "b"\n'
-                '[[workflow.party_members]]\ncode = "y"\nname = "Y"\n')
-            wf = rp.load_party_overrides(Path(d))
-            self.assertEqual(wf["default_party"], "b")  # personal wins
-            self.assertEqual([m["code"] for m in wf["party_members"]], ["x", "y"])  # appended
-
-
-if __name__ == "__main__":
-    unittest.main()

src/core-skills/module-help.csv

@@ -11,4 +11,3 @@ Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assu
 Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
 Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
 Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
-Core,bmad-forge-idea,Forge Idea,FI,"Use to pressure-test and harden an idea — software, business, creative, research, or life — until it proves out, hardens into something buildable, or dies cheaply. Persona-driven interrogation; optional handoff to bmad-spec or bmad-quick-dev.",,,anytime,,,false,{output_folder}/forge,refined-idea brief (optional)

src/scripts/resolve_config.py

@@ -10,14 +10,12 @@ Reads from four layers (highest priority last):
 
 Outputs merged JSON to stdout. Errors go to stderr.
 
-Uses only the Python stdlib (`tomllib`) — no third-party dependencies.
+Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
-BMad is standardizing on `uv run` to invoke scripts (uv provisions a suitable
+no virtualenv — plain `python3` is sufficient.
-interpreter for you); a plain `python3` on PATH still works during the
-transition. Either runner needs Python 3.11+ for `tomllib`.
 
-  uv run resolve_config.py --project-root /abs/path/to/project
+  python3 resolve_config.py --project-root /abs/path/to/project
-  uv run resolve_config.py --project-root ... --key core
+  python3 resolve_config.py --project-root ... --key core
-  uv run resolve_config.py --project-root ... --key agents
+  python3 resolve_config.py --project-root ... --key agents
 
 Merge rules (same as resolve_customization.py):
   - Scalars: override wins

src/scripts/resolve_customization.py

@@ -11,14 +11,12 @@ Skill name is derived from the basename of the skill directory.
 
 Outputs merged JSON to stdout. Errors go to stderr.
 
-Uses only the Python stdlib (`tomllib`) — no third-party dependencies.
+Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
-BMad is standardizing on `uv run` to invoke scripts (uv provisions a suitable
+no virtualenv — plain `python3` is sufficient.
-interpreter for you); a plain `python3` on PATH still works during the
-transition. Either runner needs Python 3.11+ for `tomllib`.
 
-  uv run resolve_customization.py --skill /abs/path/to/skill-dir
+  python3 resolve_customization.py --skill /abs/path/to/skill-dir
-  uv run resolve_customization.py --skill ... --key agent
+  python3 resolve_customization.py --skill ... --key agent
-  uv run resolve_customization.py --skill ... --key agent.menu
+  python3 resolve_customization.py --skill ... --key agent.menu
 
 Merge rules (purely structural — no field-name special-casing):
   - Scalars (string, int, bool, float): override wins

test/test-installation-components.js

@@ -3319,63 +3319,134 @@ async function runTests() {
   console.log('');
 
   // ============================================================
-  // Test Suite 46: uv environment check (version parsing + messaging)
+  // Test Suite 46: Python environment check (version parsing + classification)
   // ============================================================
-  console.log(`${colors.yellow}Test Suite 46: uv-check version parsing and messaging${colors.reset}\n`);
+  console.log(`${colors.yellow}Test Suite 46: python-check version parsing and classification${colors.reset}\n`);
 
   try {
-    const { parseUvVersion, detectUv } = require('../tools/installer/core/uv-check');
+    const { parsePythonVersion, classifyPython, detectPython } = require('../tools/installer/core/python-check');
 
     // Version parsing
-    const plain = parseUvVersion('uv 0.5.31');
+    const v312 = parsePythonVersion('Python 3.12.1');
-    assert(plain && plain.major === 0 && plain.minor === 5 && plain.patch === 31, 'parses "uv 0.5.31"');
+    assert(v312 && v312.major === 3 && v312.minor === 12 && v312.patch === 1, 'parses "Python 3.12.1"');
-    const brew = parseUvVersion('uv 0.5.31 (Homebrew 2025-02-12)');
+    const v311 = parsePythonVersion('Python 3.11.0\n');
-    assert(brew && brew.raw === '0.5.31', 'parses uv version with build suffix');
+    assert(v311 && v311.raw === '3.11.0', 'parses with trailing newline');
-    const noPatch = parseUvVersion('uv 1.2');
+    const v2 = parsePythonVersion('\nPython 2.7.18');
+    assert(v2 && v2.major === 2, 'parses Python 2 output (stderr-style)');
+    const noPatch = parsePythonVersion('Python 3.13');
     assert(noPatch && noPatch.patch === 0, 'missing patch defaults to 0');
-    assert(parseUvVersion('') === null, 'empty output returns null');
+    assert(parsePythonVersion('') === null, 'empty output returns null');
-    assert(parseUvVersion('command not found: uv') === null, 'non-version output returns null');
+    assert(parsePythonVersion('command not found: python3') === null, 'non-version output returns null');
-    assert(parseUvVersion(null) === null, 'null output returns null');
+    assert(parsePythonVersion(null) === null, 'null output returns null');
 
-    // Detection smoke test — must not throw; result is null or well-formed.
+    // Classification against feature requirements
-    const detectedUv = detectUv();
+    assert(classifyPython({ major: 3, minor: 11 }) === 'full', '3.11 is full support (tomllib floor)');
-    assert(detectedUv === null || typeof detectedUv.version.raw === 'string', 'detectUv returns null or a well-formed result');
+    assert(classifyPython({ major: 3, minor: 13 }) === 'full', '3.13 is full support');
+    assert(classifyPython({ major: 4, minor: 0 }) === 'full', 'hypothetical 4.0 is full support');
+    assert(classifyPython({ major: 3, minor: 10 }) === 'partial', '3.10 is partial (memlog yes, tomllib no)');
+    assert(classifyPython({ major: 3, minor: 8 }) === 'partial', '3.8 is partial (memlog floor)');
+    assert(classifyPython({ major: 3, minor: 7 }) === 'unsupported', '3.7 is unsupported');
+    assert(classifyPython({ major: 2, minor: 7 }) === 'unsupported', '2.7 is unsupported');
+    assert(classifyPython(null) === 'none', 'no python is none');
 
-    // checkUvEnvironment branch coverage — stub detection + prompts so the
+    // Detection smoke test — must not throw, and if it finds a Python the
-    // assertions are deterministic regardless of whether uv is installed.
+    // result must be well-formed. (CI machines may or may not have Python.)
-    const uvCheck = require('../tools/installer/core/uv-check');
+    const detected = detectPython();
+    assert(
+      detected === null ||
+        (typeof detected.command === 'string' &&
+          typeof detected.version.raw === 'string' &&
+          typeof detected.isRuntimeCommand === 'boolean'),
+      'detectPython returns null or a well-formed result',
+    );
+
+    // checkPythonEnvironment branch coverage — stub detection, prompts, and
+    // process.exit so the assertions are deterministic regardless of the
+    // machine's Python. python-check resolves detectPython via module.exports
+    // and prompts via the shared module object, so swapping properties works.
+    const pythonCheck = require('../tools/installer/core/python-check');
     const promptsModule = require('../tools/installer/prompts');
-    const realUv = { detectUv: uvCheck.detectUv, log: promptsModule.log, note: promptsModule.note };
+    const real = {
-    const stubUv = (detectResult) => {
+      detectPython: pythonCheck.detectPython,
-      const seen = { success: [], warn: [], note: [] };
+      log: promptsModule.log,
-      uvCheck.detectUv = () => detectResult;
+      note: promptsModule.note,
+      select: promptsModule.select,
+      cancel: promptsModule.cancel,
+      exit: process.exit,
+    };
+    const stub = (detectResult, selectAnswer) => {
+      const seen = { success: [], warn: [], info: [], note: [], select: [], cancel: [], exit: [] };
+      pythonCheck.detectPython = () => detectResult;
       promptsModule.log = {
         success: async (m) => void seen.success.push(m),
         warn: async (m) => void seen.warn.push(m),
-        info: async () => {},
+        info: async (m) => void seen.info.push(m),
         error: async () => {},
       };
       promptsModule.note = async (m, t) => void seen.note.push(t || m);
+      promptsModule.select = async (opts) => {
+        seen.select.push(opts.message);
+        return selectAnswer;
+      };
+      promptsModule.cancel = async (m) => void seen.cancel.push(m);
+      process.exit = (code) => {
+        seen.exit.push(code);
+        throw new Error('__stub_exit__');
+      };
       return seen;
     };
 
     try {
-      // Branch: uv present — success, no warning.
+      const v = (major, minor, patch) => ({ major, minor, patch, raw: `${major}.${minor}.${patch}` });
-      let seen = stubUv({ version: { major: 0, minor: 5, patch: 31, raw: '0.5.31' } });
-      let result = await uvCheck.checkUvEnvironment();
-      assert(result.status === 'found' && seen.success.length === 1, 'uv present logs success');
-      assert(seen.success[0].includes('uv run') && seen.warn.length === 0, 'uv present mentions uv run, no warning');
 
-      // Branch: uv missing — warn + setup note, never blocks (no prompt).
+      // Branch: full support via the runtime command — success, no prompt.
-      seen = stubUv(null);
+      let seen = stub({ command: 'python3', version: v(3, 12, 1), isRuntimeCommand: true }, 'continue');
-      result = await uvCheck.checkUvEnvironment();
+      let result = await pythonCheck.checkPythonEnvironment();
-      assert(result.status === 'missing' && seen.warn.length === 1, 'uv missing warns');
+      assert(result.status === 'full' && seen.success.length === 1, 'full support via python3 logs success');
-      assert(seen.warn[0].includes('de facto standard'), 'uv-missing warning frames uv as the de facto standard');
+      assert(seen.select.length === 0 && seen.warn.length === 0, 'full support via python3 skips warning and ack prompt');
-      assert(seen.note.length === 1 && seen.note[0].includes('uv'), 'uv missing shows a setup note');
+
+      // Branch: modern Python found, but not as `python3` — runtime mismatch.
+      seen = stub({ command: 'py -3', version: v(3, 12, 0), isRuntimeCommand: false }, 'continue');
+      result = await pythonCheck.checkPythonEnvironment();
+      assert(seen.success.length === 0, 'python3-mismatch never reports full support');
+      assert(
+        seen.warn.length === 1 && seen.warn[0].includes('python3') && seen.warn[0].includes('py -3'),
+        'python3-mismatch warns that scripts invoke python3',
+      );
+      assert(seen.select.length === 1 && result.status === 'full', 'python3-mismatch still requires the ack prompt');
+
+      // Branch: partial support (3.8–3.10) — warn + ack, continue returns.
+      seen = stub({ command: 'python3', version: v(3, 9, 5), isRuntimeCommand: true }, 'continue');
+      result = await pythonCheck.checkPythonEnvironment();
+      assert(
+        result.status === 'partial' && seen.warn.length === 1 && seen.warn[0].includes('3.11+'),
+        'partial support warns about tomllib floor',
+      );
+      assert(seen.select.length === 1 && seen.exit.length === 0, 'partial support prompts and continue proceeds');
+
+      // Branch: no Python, non-interactive — warn + info, never prompts.
+      seen = stub(null, 'continue');
+      result = await pythonCheck.checkPythonEnvironment({ nonInteractive: true });
+      assert(result.status === 'none' && seen.warn[0].includes('No Python found'), 'non-interactive with no Python warns');
+      assert(seen.select.length === 0 && seen.info.length === 1, 'non-interactive skips the ack prompt and logs continuation');
+
+      // Branch: no Python, interactive, user quits — cancel message + exit 0.
+      seen = stub(null, 'quit');
+      let threw = false;
+      try {
+        await pythonCheck.checkPythonEnvironment();
+      } catch (error) {
+        threw = error.message === '__stub_exit__';
+      }
+      assert(threw && seen.exit.length === 1 && seen.exit[0] === 0, 'quit choice exits 0 (user-cancel convention)');
+      assert(seen.cancel.length === 1, 'quit choice shows the cancel guidance');
     } finally {
-      uvCheck.detectUv = realUv.detectUv;
+      pythonCheck.detectPython = real.detectPython;
-      promptsModule.log = realUv.log;
+      promptsModule.log = real.log;
-      promptsModule.note = realUv.note;
+      promptsModule.note = real.note;
+      promptsModule.select = real.select;
+      promptsModule.cancel = real.cancel;
+      process.exit = real.exit;
     }
   } catch (error) {
     console.log(`${colors.red}Test Suite 46 setup failed: ${error.message}${colors.reset}`);

tools/installer/core/installer.js

@@ -1233,9 +1233,6 @@ class Installer {
       `    1. Launch your AI agent from your project folder`,
       `    2. Not sure what to do? Invoke the ${color.cyan('bmad-help')} skill and ask it what to do!`,
       '',
-      `    ${color.cyan('Tip:')} BMAD workflows increasingly run Python scripts via ${color.cyan('uv run')} — uv is`,
-      `    becoming the de facto standard. If you don't have it yet, ask your agent to set it up.`,
-      '',
       `    Blog, Docs and Guides: ${color.blue('https://bmadcode.com/')}`,
       `    Community: ${color.blue('https://discord.gg/gk8jAdXWmj')}`,
     );

tools/installer/core/python-check.js

@@ -0,0 +1,199 @@
+const { spawnSync } = require('node:child_process');
+const prompts = require('../prompts');
+
+// Python 3.11 added stdlib `tomllib` (PEP 680), which the shared scripts in
+// src/scripts/ (resolve_config.py, resolve_customization.py) require to read
+// BMAD's TOML config files. memlog.py is more lenient and runs on 3.8+.
+const PYTHON_FULL_SUPPORT = { major: 3, minor: 11 };
+const PYTHON_PARTIAL_SUPPORT = { major: 3, minor: 8 };
+
+// Every runtime call site (skill steps, on_complete hooks) invokes a literal
+// `python3`, so only that command's version vouches for BMAD features. The
+// fallback probes exist to tell the user "Python is installed, but not under
+// the name BMAD uses" instead of a misleading "No Python found".
+const RUNTIME_COMMAND = 'python3';
+const PROBE_CANDIDATES =
+  process.platform === 'win32'
+    ? [
+        { command: 'python3', args: ['--version'] },
+        { command: 'py', args: ['-3', '--version'] },
+        { command: 'python', args: ['--version'] },
+      ]
+    : [
+        { command: 'python3', args: ['--version'] },
+        { command: 'python', args: ['--version'] },
+      ];
+
+/**
+ * Parse a `python --version` output line into version parts.
+ * Python 3 prints to stdout; Python 2 printed to stderr — callers pass both.
+ * @param {string} output - Combined stdout/stderr from `python --version`
+ * @returns {{major: number, minor: number, patch: number, raw: string}|null}
+ */
+function parsePythonVersion(output) {
+  if (!output) return null;
+  const match = output.match(/Python\s+(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] || 0),
+    raw: `${match[1]}.${match[2]}.${match[3] || 0}`,
+  };
+}
+
+/**
+ * Classify a detected Python version against BMAD's feature requirements.
+ * @param {{major: number, minor: number}|null} version
+ * @returns {'full'|'partial'|'unsupported'|'none'}
+ */
+function classifyPython(version) {
+  if (!version) return 'none';
+  const { major, minor } = version;
+  if (major > PYTHON_FULL_SUPPORT.major || (major === PYTHON_FULL_SUPPORT.major && minor >= PYTHON_FULL_SUPPORT.minor)) {
+    return 'full';
+  }
+  if (major === PYTHON_PARTIAL_SUPPORT.major && minor >= PYTHON_PARTIAL_SUPPORT.minor) {
+    return 'partial';
+  }
+  return 'unsupported';
+}
+
+/**
+ * Run one probe candidate and return its parsed version, or null.
+ * @param {{command: string, args: string[]}} candidate
+ * @returns {{major: number, minor: number, patch: number, raw: string}|null}
+ */
+function probeVersion(candidate) {
+  const run = (extra = {}) =>
+    spawnSync(candidate.command, candidate.args, {
+      encoding: 'utf8',
+      timeout: 5000,
+      windowsHide: true,
+      ...extra,
+    });
+  let result = run();
+  // Node >=18.20/20.12 refuses to spawn .bat/.cmd without a shell
+  // (CVE-2024-27980 hardening) and reports EINVAL — pyenv-win ships its
+  // python shims as .bat. Args here are static literals, so a shell retry
+  // is injection-safe.
+  if (result.error && result.error.code === 'EINVAL' && process.platform === 'win32') {
+    result = run({ shell: true });
+  }
+  if (result.error) return null;
+  return parsePythonVersion(`${result.stdout || ''}\n${result.stderr || ''}`);
+}
+
+/**
+ * Probe the local environment for a Python interpreter.
+ * Tries each candidate command and returns the first that reports a version.
+ * `isRuntimeCommand` is true only when the match is `python3` — the command
+ * BMAD scripts actually invoke.
+ * @returns {{command: string, version: {major: number, minor: number, patch: number, raw: string}, isRuntimeCommand: boolean}|null}
+ */
+function detectPython() {
+  for (const candidate of PROBE_CANDIDATES) {
+    try {
+      const version = probeVersion(candidate);
+      if (version) {
+        const display = candidate.args.length > 1 ? `${candidate.command} ${candidate.args.slice(0, -1).join(' ')}` : candidate.command;
+        return { command: display, version, isRuntimeCommand: candidate.command === RUNTIME_COMMAND };
+      }
+    } catch {
+      // Candidate not runnable — try the next one.
+    }
+  }
+  return null;
+}
+
+function upgradeHints() {
+  return [
+    'How to get Python 3.11+ (as `python3`):',
+    '  macOS:        brew install python3',
+    '  Windows:      winget install Python.Python.3.12  (then ensure `python3` resolves, e.g. enable the python3 alias)',
+    '  Linux/WSL:    sudo apt install python3  (Ubuntu 24.04+ ships 3.12; older distros: use pyenv or deadsnakes)',
+    '  Docker:       add python3 to your image (e.g. apk add python3 / apt-get install -y python3)',
+  ].join('\n');
+}
+
+/**
+ * Check the local Python environment and warn about degraded BMAD features.
+ *
+ * Warn-don't-block: most of BMAD works without Python, so the install always
+ * may proceed — but the user must explicitly acknowledge the warning so it
+ * can't scroll past unseen. In non-interactive runs (--yes, or stdin is not
+ * a TTY) the warning is logged and the install continues without a prompt.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.nonInteractive=false] - Skip the ack prompt (--yes, or no TTY)
+ * @returns {Promise<{status: string, detected: Object|null}>}
+ */
+async function checkPythonEnvironment({ nonInteractive = false } = {}) {
+  // Called via module.exports so tests can stub detection.
+  const detected = module.exports.detectPython();
+  const status = classifyPython(detected ? detected.version : null);
+
+  if (status === 'full' && detected.isRuntimeCommand) {
+    await prompts.log.success(`Python ${detected.version.raw} detected (${detected.command}) — all BMAD features supported.`);
+    return { status, detected };
+  }
+
+  if (detected && !detected.isRuntimeCommand) {
+    await prompts.log.warn(
+      `Python ${detected.version.raw} found via \`${detected.command}\`, but BMAD scripts invoke \`python3\`, which is not on PATH.\n` +
+        `Python-powered features (memlog session memory, TOML config resolution) won't run until \`python3\` resolves —\n` +
+        `add a python3 alias/shim, or reinstall Python with the python3 launcher enabled.`,
+    );
+  } else if (status === 'partial') {
+    await prompts.log.warn(
+      `Python ${detected.version.raw} detected (${detected.command}) — BMAD's TOML config tools need Python 3.11+ (stdlib tomllib).\n` +
+        `Works: memlog session memory. Won't work: config/customization resolution scripts.`,
+    );
+  } else {
+    const found =
+      status === 'unsupported' ? `Python ${detected.version.raw} detected (${detected.command}) — too old.` : 'No Python found on PATH.';
+    await prompts.log.warn(
+      `${found} BMAD installs fine without it, but Python-powered features\n` +
+        `(memlog session memory, TOML config resolution) won't run until Python 3.11+ is available.`,
+    );
+  }
+  await prompts.note(upgradeHints(), 'Python 3.11+ recommended');
+
+  if (nonInteractive) {
+    await prompts.log.info('Continuing anyway (non-interactive run). You can fix Python later — no reinstall needed.');
+    return { status, detected };
+  }
+
+  const choice = await prompts.select({
+    message: "BMAD's Python-powered features won't work yet. How do you want to proceed?",
+    choices: [
+      {
+        name: 'Continue install',
+        value: 'continue',
+        hint: 'BMAD works without Python — you can fix Python later, no reinstall needed',
+      },
+      {
+        name: 'Quit and fix Python first',
+        value: 'quit',
+        hint: 'make Python 3.11+ available as python3, then re-run the installer',
+      },
+    ],
+    default: 'continue',
+  });
+
+  if (choice === 'quit') {
+    await prompts.cancel('Make Python 3.11+ available as `python3` (see hints above), then re-run the installer.');
+    process.exit(0);
+  }
+
+  return { status, detected };
+}
+
+module.exports = {
+  checkPythonEnvironment,
+  detectPython,
+  parsePythonVersion,
+  classifyPython,
+  PYTHON_FULL_SUPPORT,
+  PYTHON_PARTIAL_SUPPORT,
+};

tools/installer/core/uv-check.js

@@ -1,97 +0,0 @@
-const { spawnSync } = require('node:child_process');
-const prompts = require('../prompts');
-
-// `uv` (https://docs.astral.sh/uv/) is becoming the de facto standard for
-// running the Python scripts BMAD workflows shell out to: `uv run <script>`
-// resolves the interpreter and any dependencies on demand, so skills don't
-// have to assume a particular `python3` is on PATH. The ecosystem is mid-
-// migration — some skills still call `python3` directly — so a missing `uv`
-// is a warning, not a blocker: BMAD installs and runs either way.
-const RUNTIME_COMMAND = 'uv';
-
-/**
- * Parse `uv --version` output into version parts.
- * Example outputs: "uv 0.5.31", "uv 0.5.31 (Homebrew 2025-02-12)".
- * @param {string} output - stdout/stderr from `uv --version`
- * @returns {{major: number, minor: number, patch: number, raw: string}|null}
- */
-function parseUvVersion(output) {
-  if (!output) return null;
-  const match = output.match(/uv\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
-  if (!match) return null;
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3] || 0),
-    raw: `${match[1]}.${match[2]}.${match[3] || 0}`,
-  };
-}
-
-/**
- * Probe the local environment for `uv`.
- * @returns {{version: {major: number, minor: number, patch: number, raw: string}}|null}
- */
-function detectUv() {
-  let result;
-  try {
-    result = spawnSync(RUNTIME_COMMAND, ['--version'], {
-      encoding: 'utf8',
-      timeout: 5000,
-      windowsHide: true,
-    });
-  } catch {
-    return null;
-  }
-  if (!result || result.error) return null;
-  const version = parseUvVersion(`${result.stdout || ''}\n${result.stderr || ''}`);
-  return version ? { version } : null;
-}
-
-function setupHints() {
-  return [
-    'BMAD workflows increasingly run Python scripts via `uv run`, which manages',
-    'the interpreter and dependencies for you — no manual venv or pip needed.',
-    '',
-    'Easiest path: ask your AI agent to "install and set up uv for me".',
-    '',
-    'Or install it yourself:',
-    '  macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh',
-    '  Windows:      powershell -c "irm https://astral.sh/uv/install.ps1 | iex"',
-    '  Homebrew:     brew install uv',
-    '  Docs:         https://docs.astral.sh/uv/getting-started/installation/',
-  ].join('\n');
-}
-
-/**
- * Check whether `uv` is available and inform the user.
- *
- * Warn-don't-block, and no acknowledgement prompt: `uv` is on its way to being
- * the standard runner for BMAD's Python scripts, but the migration is still in
- * progress, so the install never stops on its account. The note tells the user
- * how to set it up (preferably by asking their agent).
- *
- * @returns {Promise<{status: 'found'|'missing', detected: Object|null}>}
- */
-async function checkUvEnvironment() {
-  // Called via module.exports so tests can stub detection.
-  const detected = module.exports.detectUv();
-
-  if (detected) {
-    await prompts.log.success(`uv ${detected.version.raw} detected — ready to run BMAD's Python-powered scripts via \`uv run\`.`);
-    return { status: 'found', detected };
-  }
-
-  await prompts.log.warn(
-    "uv not found on PATH. uv is becoming the de facto standard for running BMAD's Python\n" +
-      'scripts (`uv run <script>`), and it provisions the interpreter for you. BMAD installs\n' +
-      'fine without it, but setting up uv now keeps you ahead as workflows adopt it.',
-  );
-  await prompts.note(setupHints(), 'uv recommended');
-  return { status: 'missing', detected: null };
-}
-
-module.exports = {
-  checkUvEnvironment,
-  detectUv,
-  parseUvVersion,
-};

tools/installer/install-messages.yaml

@@ -12,10 +12,6 @@ startMessage: |
   🌟 100% free. 100% open source. Always.
      No paywalls. No gated content. Knowledge shared, not sold.
 
-  🐍 HEADS UP: uv (https://docs.astral.sh/uv/) is becoming the de facto standard
-     for running the Python scripts BMAD workflows rely on (`uv run <script>`).
-     If it's not set up yet, ask your AI agent to "install and set up uv for me".
-
   🌐 CONNECT:
     Website:   https://bmadcode.com/
     Discord:   https://discord.gg/gk8jAdXWmj

tools/installer/ui.js

@@ -161,16 +161,15 @@ class UI {
     const messageLoader = new MessageLoader();
     await messageLoader.displayStartMessage();
 
-    // Probe for `uv` before any other prompts: it's becoming the de facto
+    // Probe the local Python before any other prompts: several BMAD features
-    // runner for the Python scripts BMAD workflows shell out to
+    // (memlog session memory, TOML config resolution) need Python 3.11+ at
-    // (`uv run <script>`), and uv provisions the interpreter itself, so it's
+    // runtime. Warn-don't-block, but require an explicit ack so the warning
-    // the single thing worth checking for. The migration is still in progress
+    // can't scroll past unseen. The installer runs in the destination
-    // (some skills still call `python3` directly), so this is informational —
+    // environment, so probing PATH here tests the right machine.
-    // warn-don't-block, no ack prompt — and just points the user at setup
+    // Skip the ack when stdin isn't a TTY (CI/Docker/piped): clack's select
-    // (ideally "ask your agent to set up uv"). The installer runs in the
+    // on closed stdin resolves to cancel, which would silently exit 0.
-    // destination environment, so probing PATH here tests the right machine.
+    const { checkPythonEnvironment } = require('./core/python-check');
-    const { checkUvEnvironment } = require('./core/uv-check');
+    await checkPythonEnvironment({ nonInteractive: !!options.yes || !process.stdin.isTTY });
-    await checkUvEnvironment();
 
     // Parse channel flags (--channel/--all-*/--next=/--pin) once. Warnings
     // are surfaced immediately so the user sees them before any git ops run.

website/astro.config.mjs

@@ -106,25 +106,25 @@ export default defineConfig({
           label: 'Tutorials',
           translations: { 'vi-VN': 'Hướng dẫn nhập môn', 'zh-CN': '教程', 'fr-FR': 'Tutoriels', 'cs-CZ': 'Tutoriály' },
           collapsed: false,
-          items: [{ autogenerate: { directory: 'tutorials' } }],
+          autogenerate: { directory: 'tutorials' },
         },
         {
           label: 'How-To Guides',
           translations: { 'vi-VN': 'Hướng dẫn tác vụ', 'zh-CN': '操作指南', 'fr-FR': 'Guides pratiques', 'cs-CZ': 'Praktické návody' },
           collapsed: true,
-          items: [{ autogenerate: { directory: 'how-to' } }],
+          autogenerate: { directory: 'how-to' },
         },
         {
           label: 'Explanation',
           translations: { 'vi-VN': 'Giải thích', 'zh-CN': '概念说明', 'fr-FR': 'Explications', 'cs-CZ': 'Vysvětlení' },
           collapsed: true,
-          items: [{ autogenerate: { directory: 'explanation' } }],
+          autogenerate: { directory: 'explanation' },
         },
         {
           label: 'Reference',
           translations: { 'vi-VN': 'Tham chiếu', 'zh-CN': '参考', 'fr-FR': 'Référence', 'cs-CZ': 'Reference' },
           collapsed: true,
-          items: [{ autogenerate: { directory: 'reference' } }],
+          autogenerate: { directory: 'reference' },
         },
         // TEA docs moved to standalone module site; keep BMM sidebar focused.
         {

website/src/content.config.ts

@@ -1,8 +0,0 @@
-import { defineCollection } from 'astro:content';
-import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
-import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
-
-export const collections = {
-  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
-  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
-};

website/src/content/config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema() }),
+  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+};

website/src/pages/404.astro

@@ -1,10 +1,10 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import { getEntry, render } from 'astro:content';
+import { getEntry } from 'astro:content';
 import { translatedLocales } from '../lib/locales.mjs';
 
 const entry = await getEntry('docs', '404');
-const { Content } = await render(entry);
+const { Content } = await entry.render();
 ---
 
 <StarlightPage frontmatter={{ title: entry.data.title, template: entry.data.template }}>