Merge 93ff8d458f into 6ac4c26b69

Replace the standalone python3 environment check with a uv check, since
uv is becoming the de facto standard for running BMad's Python scripts
(`uv run <script>`) and uv provisions the interpreter itself.

Installer:
- Remove tools/installer/core/python-check.js and its wiring in ui.js
- Add tools/installer/core/uv-check.js: warn-don't-block, no ack prompt
  (the migration is in progress, so a missing uv never blocks install).
  Missing uv warns and points the user at setup, preferring "ask your
  agent to set up uv"
- Add a uv heads-up to the install intro (install-messages.yaml) and a
  uv tip line to the final "BMAD is ready" summary box
- Swap test Suite 46 from python-check to uv-check coverage

Docs and script comments (no functional skill invocations changed):
- resolve_config.py / resolve_customization.py docstrings: drop the
  "No uv ... plain python3 is sufficient" claims; frame uv run as the
  standard, python3 as the transition fallback; examples use uv run
- customize-bmad.md (en/fr/vi-vn): same reframing; example commands use
  uv run
- Update uv run hints in brain.py / list_customizable test comments

CHANGELOG.md

@@ -1,5 +1,46 @@
 # 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

@@ -0,0 +1,76 @@
+---
+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))
-- 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 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`.
 - 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 le module `tomllib` de la bibliothèque standard Python (aucune dépendance externe), donc `python3` suffit :
+À 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 :
 
 ```bash
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {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`). 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.
+**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.
 
 `--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
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /chemin/absolu/vers/bmad-agent-pm \
   --key agent
 
 # Résoudre un seul champ
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /chemin/absolu/vers/bmad-agent-pm \
   --key agent.icon
 
 # Dump complet
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {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))
-- Python 3.11+ on your PATH (for the resolver script -- uses stdlib `tomllib`, no `pip install`, no `uv`, no virtualenv)
+- 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`.
 - 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 the Python standard library's `tomllib` module (no external dependencies), so plain `python3` is enough:
+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:
 
 ```bash
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {project-root}/_bmad/scripts/resolve_customization.py \
   --skill {skill-root} \
   --key agent
 ```
 
-**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.
+**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.
 
 `--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
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /abs/path/to/bmad-agent-pm \
   --key agent
 
 # Resolve a single field
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /abs/path/to/bmad-agent-pm \
   --key agent.icon
 
 # Full dump
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /abs/path/to/bmad-agent-pm
 ```
 

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

@@ -0,0 +1,55 @@
+---
+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,6 +18,7 @@ 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 |
@@ -70,7 +71,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:** `brainstorming-session-{date}.md` with all generated ideas
+**Output:** a self-contained `brainstorm.html` keepsake of the session, an optional `brainstorm-intent.md` for downstream skills, and a `.memlog.md` session record
 
 :::note[Quantity Target]
 The magic happens in ideas 50–100. The workflow encourages generating 100+ ideas before organization.
@@ -98,6 +99,28 @@ 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,10 +35,11 @@ it**](../explanation/analysis-phase.md).
 
 | Workflow                                                                  | Purpose                                                                    | Produces                  |
 |---------------------------------------------------------------------------|----------------------------------------------------------------------------|---------------------------|
-| `bmad-brainstorming`                                                      | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
+| `bmad-brainstorming`                                                      | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorm.html` keepsake plus an optional `brainstorm-intent.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                 | `product-brief.md`        |
+| `bmad-product-brief`                                                      | Capture strategic vision — best when your concept is clear                 | `brief.md` + `addendum.md`, plus any desired HTML or presentation output       |
-| `bmad-prfaq`                                                              | Working Backwards — stress-test and forge your product concept             | `prfaq-{project}.md`      |
+| `bmad-prfaq`                                                              | Working Backwards — stress-test your product concept customer-first             | `prfaq-{project}.md`      |
 
 ## Phase 2: Planning
 
@@ -67,13 +68,13 @@ Decide how to build it and break work into stories.
 
 | Workflow                              | Purpose                                    | Produces                    |
 |---------------------------------------|--------------------------------------------|-----------------------------|
-| `bmad-create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
+| `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-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. Coming soon, full phase 4 automation!
+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.
 
 | 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, product brief or PRFAQ _(optional)_ |
+| 1     | Analysis       | Brainstorming, research, forge idea, product brief or PRFAQ _(optional)_ |
-| 2     | Planning       | Create requirements (PRD or spec)                            |
+| 2     | Planning       | Create requirements and design PRD, UX, SPEC                 |
-| 3     | Solutioning    | Design architecture _(BMad Method/Enterprise only)_          |
+| 3     | Solutioning    | Design architecture spine or detailed project or system architectures          |
-| 4     | Implementation | Build epic by epic, story by story                           |
+| 4     | Implementation | Build epic by epic, story by story with quick dev or automated epic delivery    |
 
 **[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management.
 
@@ -139,9 +139,10 @@ 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 and forge your product concept
+- **prfaq** (`bmad-prfaq`) — Working Backwards challenge to stress-test your product concept customer-first
 
 ### 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))
-- 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 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ả.
 - 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 dùng `tomllib` của Python stdlib, nên `python3` thuần là đủ:
+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:
 
 ```bash
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {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`, 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.
+**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.
 
 `--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
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {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ể
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {project-root}/_bmad/scripts/resolve_customization.py \
   --skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \
   --key agent.icon
 
 # Dump toàn bộ
-python3 {project-root}/_bmad/scripts/resolve_customization.py \
+uv run {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.8.0",
+  "version": "6.9.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -40,12 +40,13 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run test:renderer && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:renderer && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
+    "test:renderer": "node test/test-quick-dev-renderer.js",
     "test:urls": "node test/test-parse-source-urls.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",
     "validate:skills": "node tools/validate-skills.js --strict"
@@ -66,6 +67,12 @@
       "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",
@@ -82,10 +89,10 @@
     "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@astrojs/sitemap": "^3.6.0",
+    "@astrojs/sitemap": "^3.7.3",
-    "@astrojs/starlight": "^0.37.5",
+    "@astrojs/starlight": "^0.40.0",
     "@eslint/js": "^9.33.0",
-    "astro": "^5.16.0",
+    "astro": "^6.4.6",
     "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 to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+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'.
 ---
 
 # 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 — suggest the idea may need more exploration first and recommend they invoke the `bmad-brainstorming` skill to develop it further.
+**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.
 
 **Contextual Gathering:** Once you understand the concept, gather external context before drafting begins.
 

src/bmm-skills/4-implementation/bmad-quick-dev/SKILL.md

@@ -3,112 +3,12 @@ name: bmad-quick-dev
 description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
 ---
 
-# Quick Dev New Preview Workflow
+Run this, substituting `{skill-root}` with the absolute path to this skill's base directory, without changing the cwd:
 
-**Goal:** Turn user intent into a hardened, reviewable artifact.
+```bash
+python3 {skill-root}/render.py
+```
 
-**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
+- **On success:** follow the instruction it prints to stdout; ignore stderr.
-
+- **If `python3` is missing or lacks `tomllib`:** recover and retry.
-Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps.
+- **Any other failure:** report what it printed and HALT.
-If you need an explicit user instruction to run them, ask once now for the whole workflow run.
-
-## READY FOR DEVELOPMENT STANDARD
-
-A specification is "Ready for Development" when:
-
-- **Actionable**: Every task has a file path and specific action.
-- **Logical**: Tasks ordered by dependency.
-- **Testable**: All ACs use Given/When/Then.
-- **Complete**: No placeholders or TBDs.
-
-## SCOPE STANDARD
-
-A specification should target a **single user-facing goal** within **900–1600 tokens**:
-
-- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
-  - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
-  - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
-- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
-- **Neither limit is a gate.** Both are proposals with user override.
-
-## Conventions
-
-- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root.
-- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
-- `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
-
-## On Activation
-
-### Step 1: Resolve the Workflow Block
-
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
-
-**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
-
-1. `{skill-root}/customize.toml` — defaults
-2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
-3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
-
-Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
-
-### Step 2: Execute Prepend Steps
-
-Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
-
-### Step 3: Load Persistent Facts
-
-Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim.
-
-### Step 4: Load Config
-
-Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
-
-- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
-- `communication_language`, `document_output_language`, `user_skill_level`
-- `date` as system-generated current datetime
-- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
-- `project_context` = `**/project-context.md` (load if exists)
-- CLAUDE.md / memory files (load if exist)
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- Language MUST be tailored to `{user_skill_level}`
-- Generate all documents in `{document_output_language}`
-
-### Step 5: Greet the User
-
-Greet `{user_name}`, speaking in `{communication_language}`.
-
-### Step 6: Execute Append Steps
-
-Execute each entry in `{workflow.activation_steps_append}` in order.
-
-Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
-
-## WORKFLOW ARCHITECTURE
-
-This uses **step-file architecture** for disciplined execution:
-
-- **Micro-file Design**: Each step is self-contained and followed exactly
-- **Just-In-Time Loading**: Only load the current step file
-- **Sequential Enforcement**: Complete steps in order, no skipping
-- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
-- **Append-Only Building**: Build artifacts incrementally
-
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Read the entire step file before acting
-2. **FOLLOW SEQUENCE**: Execute sections in order
-3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
-4. **LOAD NEXT**: When directed, read fully and follow the next step file
-
-### Critical Rules (NO EXCEPTIONS)
-
-- **NEVER** load multiple step files simultaneously
-- **ALWAYS** read entire step file before execution
-- **NEVER** skip steps or optimize the sequence
-- **ALWAYS** follow the exact instructions in the step file
-- **ALWAYS** halt at checkpoints and wait for human input
-
-## FIRST STEP
-
-Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.

src/bmm-skills/4-implementation/bmad-quick-dev/render.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""render.py — bmad-quick-dev template renderer.
+
+Resolves compile-time {{.variable}} placeholders from BMad's central config,
+bakes absolute paths for {project-root} into derived values, resolves and
+inlines the skill's [workflow] customization block, and writes rendered .md
+files to {project-root}/_bmad/render/bmad-quick-dev/.
+
+Config: four-layer merge of _bmad/config.toml + config.user.toml +
+custom/config.toml + custom/config.user.toml (post-#2285 installs).
+Keys surface from [core] and [modules.bmm]. Missing or unparseable
+config.toml → HALT.
+
+Customization: three-layer merge of {skill}/customize.toml +
+_bmad/custom/bmad-quick-dev.toml + .user.toml (same structural rules as
+resolve_customization.py). The resolved [workflow] values fill {workflow.*}
+placeholders, so this skill needs no runtime resolve_customization.py call.
+Other single-curly placeholders ({project-root}, {spec_file}, {skill-root},
+...) pass through untouched for the LLM to resolve during workflow execution.
+
+Every invocation rebuilds from scratch — no hash, no cache.
+Python 3.11+ stdlib only. UTF-8 I/O.
+"""
+
+import os
+import posixpath
+import re
+import sys
+import tomllib
+
+
+def find_project_root():
+    """Walk up from cwd until a _bmad/ directory is found. On failure, print a
+    HALT instruction to stdout and exit non-zero."""
+    current = os.path.abspath(os.getcwd())
+    while True:
+        candidate = os.path.join(current, "_bmad")
+        if os.path.isdir(candidate):
+            return current
+        parent = os.path.dirname(current)
+        if parent == current:
+            print(
+                f"HALT and report to the user: no _bmad/ directory found walking up from {os.getcwd()}"
+            )
+            sys.exit(1)
+        current = parent
+
+
+def load_toml(path, required=False):
+    """Load a TOML file. For required files, HALT (stdout) on missing/parse
+    error so the LLM-driven workflow stops — stdout is how this script signals
+    workflow halts to its LLM caller. For optional files, write a stderr
+    warning and return {}."""
+    if not os.path.isfile(path):
+        if required:
+            print(
+                f"HALT and report to the user: required config file not found: {path} — "
+                "ensure this is a post-#2285 BMAD install"
+            )
+            sys.exit(1)
+        return {}
+    try:
+        with open(path, "rb") as fh:
+            parsed = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as error:
+        if required:
+            print(f"HALT and report to the user: failed to parse {path}: {error}")
+            sys.exit(1)
+        print(f"render.py: warning: failed to parse {path}: {error}", file=sys.stderr)
+        return {}
+    except OSError as error:
+        if required:
+            print(f"HALT and report to the user: failed to read {path}: {error}")
+            sys.exit(1)
+        print(f"render.py: warning: failed to read {path}: {error}", file=sys.stderr)
+        return {}
+    if not isinstance(parsed, dict):
+        return {}
+    return parsed
+
+
+def _deep_merge(base, override):
+    """Dict-aware deep merge. Lists and scalars: override wins (we don't need
+    the full keyed-merge semantics of resolve_config.py — quick-dev only reads
+    flat scalars out of [core] and [modules.bmm])."""
+    if isinstance(base, dict) and isinstance(override, dict):
+        result = dict(base)
+        for key, value in override.items():
+            result[key] = _deep_merge(result[key], value) if key in result else value
+        return result
+    return override
+
+
+def _detect_keyed_merge_field(items):
+    """Return 'code' or 'id' if every table item carries that same field.
+    Mixed or partial arrays return None and fall through to append."""
+    if not items or not all(isinstance(item, dict) for item in items):
+        return None
+    for candidate in ("code", "id"):
+        if all(item.get(candidate) is not None for item in items):
+            return candidate
+    return None
+
+
+def _merge_by_key(base, override, key_name):
+    result = []
+    index_by_key = {}
+    for item in base:
+        if not isinstance(item, dict):
+            continue
+        if item.get(key_name) is not None:
+            index_by_key[item[key_name]] = len(result)
+        result.append(dict(item))
+    for item in override:
+        if not isinstance(item, dict):
+            result.append(item)
+            continue
+        key = item.get(key_name)
+        if key is not None and key in index_by_key:
+            result[index_by_key[key]] = dict(item)
+        else:
+            if key is not None:
+                index_by_key[key] = len(result)
+            result.append(dict(item))
+    return result
+
+
+def _merge_arrays(base, override):
+    """Shape-aware array merge: keyed merge if every item has code/id, else append."""
+    base_arr = base if isinstance(base, list) else []
+    override_arr = override if isinstance(override, list) else []
+    keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
+    if keyed_field:
+        return _merge_by_key(base_arr, override_arr, keyed_field)
+    return base_arr + override_arr
+
+
+def _structural_merge(base, override):
+    """Faithful port of resolve_customization.py's deep_merge: tables deep-merge,
+    arrays-of-tables keyed by code/id replace-then-append (other arrays append),
+    scalars override. Used only for the [workflow] customization layers — the
+    central-config path keeps its own simpler _deep_merge. Duplicated rather than
+    imported to keep this skill self-contained."""
+    if isinstance(base, dict) and isinstance(override, dict):
+        result = dict(base)
+        for key, over_val in override.items():
+            result[key] = (
+                _structural_merge(result[key], over_val) if key in result else over_val
+            )
+        return result
+    if isinstance(base, list) and isinstance(override, list):
+        return _merge_arrays(base, override)
+    return override
+
+
+def resolve_workflow(root, skill_dir, skill_name):
+    """Resolve the [workflow] customization block via the three-layer merge
+    (skill defaults -> team -> user), highest priority last. Same structural
+    rules as resolve_customization.py. All three layers are optional: a missing
+    or unparseable file warns (via load_toml) and is skipped."""
+    defaults = load_toml(posixpath.join(skill_dir, "customize.toml"))
+    custom_dir = posixpath.join(root, "_bmad", "custom")
+    team = load_toml(posixpath.join(custom_dir, f"{skill_name}.toml"))
+    user = load_toml(posixpath.join(custom_dir, f"{skill_name}.user.toml"))
+    merged = _structural_merge(defaults, team)
+    merged = _structural_merge(merged, user)
+    workflow = merged.get("workflow")
+    return workflow if isinstance(workflow, dict) else {}
+
+
+def load_central_config(root):
+    """Four-layer merge of _bmad/config.toml and its peers (highest priority
+    last). HALTs if the base _bmad/config.toml is missing or unparseable."""
+    bmad_dir = posixpath.join(root, "_bmad")
+    base_team = load_toml(posixpath.join(bmad_dir, "config.toml"), required=True)
+    base_user = load_toml(posixpath.join(bmad_dir, "config.user.toml"))
+    custom_team = load_toml(posixpath.join(bmad_dir, "custom", "config.toml"))
+    custom_user = load_toml(posixpath.join(bmad_dir, "custom", "config.user.toml"))
+
+    merged = _deep_merge(base_team, base_user)
+    merged = _deep_merge(merged, custom_team)
+    merged = _deep_merge(merged, custom_user)
+    return merged
+
+
+def flatten_central_config(merged):
+    """Lift scalar keys from [core] and [modules.bmm] into a single namespace.
+    Module keys take precedence on collision (installer strips core keys from
+    module buckets, so collisions shouldn't happen in practice)."""
+    flat = {}
+    for section in (merged.get("core"), merged.get("modules", {}).get("bmm")):
+        if not isinstance(section, dict):
+            continue
+        for key, value in section.items():
+            if isinstance(value, bool):
+                flat[key] = "true" if value else "false"
+            elif isinstance(value, (str, int, float)):
+                flat[key] = str(value)
+    return flat
+
+
+def render_template(content, vars_):
+    """Resolve {{.var}} substitutions. Unresolved references emit an empty string
+    (Go's missingkey=zero semantics)."""
+    return re.sub(r"\{\{\.(\w+)\}\}", lambda m: vars_.get(m.group(1), ""), content)
+
+
+def _scalar_str(value):
+    """Stringify a scalar for inline rendering: booleans lowercase (matching
+    BMad config conventions), None as empty, everything else via str()."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _render_workflow_value(value):
+    """Format a resolved [workflow] value for inline substitution. Lists render
+    as markdown bullets (empty -> '_None._'); scalars render verbatim. Each list
+    item uses the same scalar formatting so booleans stay consistent. Entries are
+    emitted as-is so runtime placeholders like {project-root} survive for the LLM
+    to resolve."""
+    if isinstance(value, list):
+        if not value:
+            return "_None._"
+        return "\n".join(f"- {_scalar_str(item)}" for item in value)
+    return _scalar_str(value)
+
+
+def render_workflow(content, workflow):
+    """Resolve {workflow.<key>} placeholders from the resolved [workflow] block.
+    Unknown keys emit an empty string (missingkey=zero, matching render_template).
+    Distinct regex from render_template so single-curly runtime placeholders
+    elsewhere are untouched."""
+    return re.sub(
+        r"\{workflow\.(\w+)\}",
+        lambda m: _render_workflow_value(workflow.get(m.group(1))),
+        content,
+    )
+
+
+def main():
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    skill_name = os.path.basename(script_dir)
+    root = find_project_root()
+    root = root.replace(os.sep, "/")
+    bmad_dir = posixpath.join(root, "_bmad")
+
+    vars_ = flatten_central_config(load_central_config(root))
+
+    for key in list(vars_.keys()):
+        vars_[key] = vars_[key].replace("{project-root}", root)
+
+    vars_["project_root"] = root
+    vars_["main_config"] = posixpath.join(bmad_dir, "config.toml")
+    vars_["sprint_status"] = posixpath.join(
+        vars_["implementation_artifacts"], "sprint-status.yaml"
+    )
+    vars_["deferred_work_file"] = posixpath.join(
+        vars_["implementation_artifacts"], "deferred-work.md"
+    )
+
+    workflow = resolve_workflow(root, script_dir.replace(os.sep, "/"), skill_name)
+
+    out_dir = posixpath.join(root, "_bmad", "render", skill_name)
+    os.makedirs(out_dir, exist_ok=True)
+
+    for fname in os.listdir(out_dir):
+        if fname.endswith(".md"):
+            os.remove(posixpath.join(out_dir, fname))
+
+    for fname in sorted(os.listdir(script_dir)):
+        if not fname.endswith(".md") or fname == "SKILL.md":
+            continue
+        src = posixpath.join(script_dir, fname)
+        dst = posixpath.join(out_dir, fname)
+        with open(src, "r", encoding="utf-8", newline="") as fh:
+            content = fh.read()
+        with open(dst, "w", encoding="utf-8", newline="") as fh:
+            fh.write(render_workflow(render_template(content, vars_), workflow))
+
+    workflow_md = posixpath.join(out_dir, "workflow.md")
+    print(f"read and follow {workflow_md}")
+
+
+if __name__ == "__main__":
+    main()

src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

@@ -1,5 +1,4 @@
 ---
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 spec_file: '' # set at runtime for both routes before leaving this step
 story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds
 ---
@@ -8,7 +7,7 @@ story_key: '' # set at runtime to the current story's full sprint-status key (e.
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - The prompt that triggered this workflow IS the intent — not a hint.
 - Do NOT assume you start from zero.
 - The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
@@ -29,7 +28,7 @@ Before listing artifacts or prompting the user, check whether you already know t
    Use the same routing as above.
 
 3. Otherwise — scan artifacts and ask
-   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{{.implementation_artifacts}}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
      - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
      - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-03-implement.md`
      - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-04-review.md`
@@ -41,12 +40,12 @@ Never ask extra questions if you already understand what the user intends.
 
 This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `{epic_num}` and `{story_num}`. If the spec is not an epic story, skip silently and leave `{story_key}` unset.
 
-If the spec is an epic story and `{sprint_status}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple).
+If the spec is an epic story and `{{.sprint_status}}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple).
 
 ## INSTRUCTIONS
 
 1. Load context.
-   - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
+   - List files in `{{.planning_artifacts}}` and `{{.implementation_artifacts}}`.
    - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
    - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
 
@@ -54,17 +53,17 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
 
      1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B.
 
-     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
+     2. **Check for a valid cached epic context.** Look for `{{.implementation_artifacts}}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{{.planning_artifacts}}` is newer.
         - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
         - **If missing, empty, or invalid:** continue to step 3.
 
-     3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
+     3. **Compile epic context.** Produce `{{.implementation_artifacts}}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
-        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
+        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{{.planning_artifacts}}` directory, and the output path `{{.implementation_artifacts}}/epic-<N>-context.md`.
         - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
 
      4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
 
-     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{{.implementation_artifacts}}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
 
      6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now.
 
@@ -82,11 +81,11 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
    - Present detected distinct goals as a bullet list.
    - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
    - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
-   - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **S**: Append deferred goals to `{{.deferred_work_file}}`. Narrow scope to the first-mentioned goal. Continue routing.
    - On **K**: Proceed as-is.
 5. Route — choose exactly one:
 
-   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
+   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.
 
    **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
 

src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md

@@ -1,12 +1,8 @@
----
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
 # Step 2: Plan
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - No intermediate approvals.
 
 ## INSTRUCTIONS
@@ -19,7 +15,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
    - Show user the token count.
    - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
-   - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
+   - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{{.deferred_work_file}}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
    - On **K**: Continue to checkpoint with full spec.
 
 ### CHECKPOINT 1

src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md

@@ -5,7 +5,7 @@
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - No push. No remote ops.
 - Sequential execution only.
 - Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.

src/bmm-skills/4-implementation/bmad-quick-dev/step-04-review.md

@@ -1,5 +1,4 @@
 ---
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 specLoopIteration: 1
 ---
 
@@ -7,7 +6,7 @@ specLoopIteration: 1
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - Review subagents get NO conversation context.
 - All review subagents must run at the same model capability as the current session.
 
@@ -23,7 +22,7 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{{.implementation_artifacts}}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
 
 - **Blind hunter** — receives inline `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
 - **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
@@ -42,7 +41,7 @@ Launch three subagents without conversation context. If no sub-agents are availa
    - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
    - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
    - **patch** — Auto-fix. These are the only findings that survive loopbacks.
-   - **defer** — Append to `{deferred_work_file}`.
+   - **defer** — Append to `{{.deferred_work_file}}`.
    - **reject** — Drop silently.
 
 ## NEXT

src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md

@@ -5,7 +5,7 @@
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - NEVER auto-push.
 
 ## INSTRUCTIONS
@@ -73,6 +73,6 @@ Workflow complete.
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+If anything appears below, follow it as the final terminal instruction before exiting; otherwise exit normally.
 
-If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.
+{workflow.on_complete}

src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

@@ -1,12 +1,8 @@
----
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
 # Step One-Shot: Implement, Review, Present
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - NEVER auto-push.
 
 ## INSTRUCTIONS
@@ -19,14 +15,14 @@ Implement the clarified intent directly.
 
 ### Review
 
-Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
+Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{{.implementation_artifacts}}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
 
 ### Classify
 
 Deduplicate all review findings. Three categories only:
 
 - **patch** — trivially fixable. Auto-fix immediately.
-- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`.
+- **defer** — pre-existing issue not caused by this change. Append to `{{.deferred_work_file}}`.
 - **reject** — noise. Drop silently.
 
 If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
@@ -66,6 +62,6 @@ Workflow complete.
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+If anything appears below, follow it as the final terminal instruction before exiting; otherwise exit normally.
 
-If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.
+{workflow.on_complete}

src/bmm-skills/4-implementation/bmad-quick-dev/sync-sprint-status.md

@@ -6,11 +6,11 @@ Shared sub-step for updating `sprint-status.yaml` during quick-dev. Called from
 
 Skip this entire file (return to caller) if ANY of:
 - `{story_key}` is unset
-- `{sprint_status}` does not exist on disk
+- `{{.sprint_status}}` does not exist on disk
 
 ## Instructions
 
-1. Load the FULL `{sprint_status}` file.
+1. Load the FULL `{{.sprint_status}}` file.
 2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller.
 3. **Idempotency check.** If `development_status[{story_key}]` is already at `{target_status}` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status.
 4. Set `development_status[{story_key}]` to `{target_status}`.

src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md

@@ -0,0 +1,101 @@
+# Quick Dev New Preview Workflow
+
+**Goal:** Turn user intent into a hardened, reviewable artifact.
+
+**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
+
+Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps.
+If you need an explicit user instruction to run them, ask once now for the whole workflow run.
+
+## READY FOR DEVELOPMENT STANDARD
+
+A specification is "Ready for Development" when:
+
+- **Actionable**: Every task has a file path and specific action.
+- **Logical**: Tasks ordered by dependency.
+- **Testable**: All ACs use Given/When/Then.
+- **Complete**: No placeholders or TBDs.
+
+## SCOPE STANDARD
+
+A specification should target a **single user-facing goal** within **900–1600 tokens**:
+
+- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
+  - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
+  - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
+- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
+- **Neither limit is a gate.** Both are proposals with user override.
+
+## Conventions
+
+- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Execute Prepend Steps
+
+Execute each of these steps in order before proceeding (`_None._` means skip):
+
+{workflow.activation_steps_prepend}
+
+### Step 2: Load Persistent Facts
+
+Treat every entry below as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim (`_None._` means none):
+
+{workflow.persistent_facts}
+
+### Step 3: Load Config
+
+Load config from `{{.main_config}}` and resolve:
+
+- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+- `sprint_status` = `{{.sprint_status}}`
+- `project_context` = `**/project-context.md` (load if exists)
+- CLAUDE.md / memory files (load if exist)
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
+- Language MUST be tailored to `{{.user_skill_level}}`
+- Generate all documents in `{{.document_output_language}}`
+
+### Step 4: Greet the User
+
+Greet `{{.user_name}}`, speaking in `{{.communication_language}}`.
+
+### Step 5: Execute Append Steps
+
+Execute each of these steps in order (`_None._` means skip):
+
+{workflow.activation_steps_append}
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly
+- **Just-In-Time Loading**: Only load the current step file
+- **Sequential Enforcement**: Complete steps in order, no skipping
+- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
+- **Append-Only Building**: Build artifacts incrementally
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting
+2. **FOLLOW SEQUENCE**: Execute sections in order
+3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
+4. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at checkpoints and wait for human input
+
+## FIRST STEP
+
+Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.

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: python3 brain.py html --out assets/brain-selector.html
+    # Regenerate with: uv run 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: "
-        "python3 brain.py html --out assets/brain-selector.html"
+        "uv run 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: python3 scripts/tests/test_list_customizable_skills.py
+Run: uv run scripts/tests/test_list_customizable_skills.py
 """
 
 from __future__ import annotations

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

@@ -0,0 +1,79 @@
+---
+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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,270 @@
+#!/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

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

src/scripts/resolve_customization.py

@@ -11,12 +11,14 @@ Skill name is derived from the basename of the skill directory.
 
 Outputs merged JSON to stdout. Errors go to stderr.
 
-Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
+Uses only the Python stdlib (`tomllib`) — no third-party dependencies.
-no virtualenv — plain `python3` is sufficient.
+BMad is standardizing on `uv run` to invoke scripts (uv provisions a suitable
+interpreter for you); a plain `python3` on PATH still works during the
+transition. Either runner needs Python 3.11+ for `tomllib`.
 
-  python3 resolve_customization.py --skill /abs/path/to/skill-dir
+  uv run resolve_customization.py --skill /abs/path/to/skill-dir
-  python3 resolve_customization.py --skill ... --key agent
+  uv run resolve_customization.py --skill ... --key agent
-  python3 resolve_customization.py --skill ... --key agent.menu
+  uv run 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,134 +3319,63 @@ async function runTests() {
   console.log('');
 
   // ============================================================
-  // Test Suite 46: Python environment check (version parsing + classification)
+  // Test Suite 46: uv environment check (version parsing + messaging)
   // ============================================================
-  console.log(`${colors.yellow}Test Suite 46: python-check version parsing and classification${colors.reset}\n`);
+  console.log(`${colors.yellow}Test Suite 46: uv-check version parsing and messaging${colors.reset}\n`);
 
   try {
-    const { parsePythonVersion, classifyPython, detectPython } = require('../tools/installer/core/python-check');
+    const { parseUvVersion, detectUv } = require('../tools/installer/core/uv-check');
 
     // Version parsing
-    const v312 = parsePythonVersion('Python 3.12.1');
+    const plain = parseUvVersion('uv 0.5.31');
-    assert(v312 && v312.major === 3 && v312.minor === 12 && v312.patch === 1, 'parses "Python 3.12.1"');
+    assert(plain && plain.major === 0 && plain.minor === 5 && plain.patch === 31, 'parses "uv 0.5.31"');
-    const v311 = parsePythonVersion('Python 3.11.0\n');
+    const brew = parseUvVersion('uv 0.5.31 (Homebrew 2025-02-12)');
-    assert(v311 && v311.raw === '3.11.0', 'parses with trailing newline');
+    assert(brew && brew.raw === '0.5.31', 'parses uv version with build suffix');
-    const v2 = parsePythonVersion('\nPython 2.7.18');
+    const noPatch = parseUvVersion('uv 1.2');
-    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(parsePythonVersion('') === null, 'empty output returns null');
+    assert(parseUvVersion('') === null, 'empty output returns null');
-    assert(parsePythonVersion('command not found: python3') === null, 'non-version output returns null');
+    assert(parseUvVersion('command not found: uv') === null, 'non-version output returns null');
-    assert(parsePythonVersion(null) === null, 'null output returns null');
+    assert(parseUvVersion(null) === null, 'null output returns null');
 
-    // Classification against feature requirements
+    // Detection smoke test — must not throw; result is null or well-formed.
-    assert(classifyPython({ major: 3, minor: 11 }) === 'full', '3.11 is full support (tomllib floor)');
+    const detectedUv = detectUv();
-    assert(classifyPython({ major: 3, minor: 13 }) === 'full', '3.13 is full support');
+    assert(detectedUv === null || typeof detectedUv.version.raw === 'string', 'detectUv returns null or a well-formed result');
-    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');
 
-    // Detection smoke test — must not throw, and if it finds a Python the
+    // checkUvEnvironment branch coverage — stub detection + prompts so the
-    // result must be well-formed. (CI machines may or may not have Python.)
+    // assertions are deterministic regardless of whether uv is installed.
-    const detected = detectPython();
+    const uvCheck = require('../tools/installer/core/uv-check');
-    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 real = {
+    const realUv = { detectUv: uvCheck.detectUv, log: promptsModule.log, note: promptsModule.note };
-      detectPython: pythonCheck.detectPython,
+    const stubUv = (detectResult) => {
-      log: promptsModule.log,
+      const seen = { success: [], warn: [], note: [] };
-      note: promptsModule.note,
+      uvCheck.detectUv = () => detectResult;
-      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 (m) => void seen.info.push(m),
+        info: async () => {},
         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 {
-      const v = (major, minor, patch) => ({ major, minor, patch, raw: `${major}.${minor}.${patch}` });
+      // Branch: uv present — success, no warning.
+      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: full support via the runtime command — success, no prompt.
+      // Branch: uv missing — warn + setup note, never blocks (no prompt).
-      let seen = stub({ command: 'python3', version: v(3, 12, 1), isRuntimeCommand: true }, 'continue');
+      seen = stubUv(null);
-      let result = await pythonCheck.checkPythonEnvironment();
+      result = await uvCheck.checkUvEnvironment();
-      assert(result.status === 'full' && seen.success.length === 1, 'full support via python3 logs success');
+      assert(result.status === 'missing' && seen.warn.length === 1, 'uv missing warns');
-      assert(seen.select.length === 0 && seen.warn.length === 0, 'full support via python3 skips warning and ack prompt');
+      assert(seen.warn[0].includes('de facto standard'), 'uv-missing warning frames uv as the de facto standard');
-
+      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 {
-      pythonCheck.detectPython = real.detectPython;
+      uvCheck.detectUv = realUv.detectUv;
-      promptsModule.log = real.log;
+      promptsModule.log = realUv.log;
-      promptsModule.note = real.note;
+      promptsModule.note = realUv.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}`);

test/test-quick-dev-renderer.js

@@ -0,0 +1,232 @@
+/**
+ * Smoke test for bmad-quick-dev render.py
+ *
+ * Sets up a temp project with base + override config layers and a
+ * _bmad/custom/bmad-quick-dev.user.toml [workflow] override, runs render.py,
+ * and asserts:
+ *   1. The central-config override wins (workflow.md contains "Japanese").
+ *   2. sprint_status is an absolute path rooted at the temp project dir.
+ *   3. [workflow] customization is self-resolved and inlined: prepend bullet,
+ *      persistent_facts append (base kept), empty list -> _None._, on_complete
+ *      scalar baked into step-05/step-oneshot.
+ *   4. No {workflow.*} placeholder or resolve_customization.py call survives
+ *      in any rendered file.
+ *
+ * Usage: node test/test-quick-dev-renderer.js
+ * Exit codes: 0 = all tests pass, 1 = test failures
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// ANSI color codes (same as other test files)
+const colors = {
+  reset: '\u001B[0m',
+  green: '\u001B[32m',
+  red: '\u001B[31m',
+  cyan: '\u001B[36m',
+};
+
+let totalTests = 0;
+let passedTests = 0;
+const failures = [];
+
+function test(name, fn) {
+  totalTests++;
+  try {
+    fn();
+    passedTests++;
+    console.log(`  ${colors.green}\u2713${colors.reset} ${name}`);
+  } catch (error) {
+    console.log(`  ${colors.red}\u2717${colors.reset} ${name} ${colors.red}${error.message}${colors.reset}`);
+    failures.push({ name, message: error.message });
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const SKILL_SRC = path.join(__dirname, '..', 'src', 'bmm-skills', '4-implementation', 'bmad-quick-dev');
+
+/**
+ * Recursively copy a directory (stdlib only, no fs.cp to stay >=20 compat).
+ */
+function copyDirSync(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, dstPath);
+    } else {
+      fs.copyFileSync(srcPath, dstPath);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test fixture setup
+// ---------------------------------------------------------------------------
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bmad-renderer-test-'));
+
+try {
+  // _bmad/config.toml — base layer
+  fs.mkdirSync(path.join(tmpDir, '_bmad'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, '_bmad', 'config.toml'),
+    [
+      '[core]',
+      'communication_language = "French"',
+      '',
+      '[modules.bmm]',
+      'planning_artifacts = "{project-root}/plan"',
+      'implementation_artifacts = "{project-root}/impl"',
+    ].join('\n'),
+    'utf-8',
+  );
+
+  // _bmad/custom/config.user.toml — override layer (should win)
+  fs.mkdirSync(path.join(tmpDir, '_bmad', 'custom'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, '_bmad', 'custom', 'config.user.toml'),
+    ['[core]', 'communication_language = "Japanese"'].join('\n'),
+    'utf-8',
+  );
+
+  // _bmad/custom/bmad-quick-dev.user.toml — [workflow] customization override.
+  // Exercises render.py's self-resolution: array append (persistent_facts),
+  // list inlining (activation_steps_prepend), and scalar override (on_complete),
+  // all baked into the rendered output with no runtime resolve_customization.py.
+  fs.writeFileSync(
+    path.join(tmpDir, '_bmad', 'custom', 'bmad-quick-dev.user.toml'),
+    [
+      '[workflow]',
+      'activation_steps_prepend = ["TEST_PREPEND_STEP"]',
+      'persistent_facts = ["TEST_EXTRA_FACT"]',
+      'on_complete = "TEST_ON_COMPLETE_INSTRUCTION"',
+    ].join('\n'),
+    'utf-8',
+  );
+
+  // Copy skill dir into <tmpDir>/bmad-quick-dev/ so find_project_root() walks
+  // up and finds <tmpDir>/_bmad/, and os.path.basename(script_dir) resolves
+  // to the real skill name so the render output lands at
+  // _bmad/render/bmad-quick-dev/workflow.md.
+  const skillDst = path.join(tmpDir, 'bmad-quick-dev');
+  copyDirSync(SKILL_SRC, skillDst);
+
+  // ---------------------------------------------------------------------------
+  // Run render.py
+  // ---------------------------------------------------------------------------
+
+  console.log(`\n${colors.cyan}Quick-dev renderer smoke tests${colors.reset}\n`);
+
+  const result = spawnSync('python3', [path.join(skillDst, 'render.py')], {
+    cwd: skillDst,
+    encoding: 'utf-8',
+  });
+
+  const renderDir = path.join(tmpDir, '_bmad', 'render', 'bmad-quick-dev');
+  const readRendered = (name) => fs.readFileSync(path.join(renderDir, name), 'utf-8');
+  const renderedMdFiles = () => fs.readdirSync(renderDir).filter((f) => f.endsWith('.md'));
+
+  // ---------------------------------------------------------------------------
+  // Tests
+  // ---------------------------------------------------------------------------
+
+  test('render.py exits with code 0', () => {
+    assert(result.status === 0, `exit code ${result.status}\nstdout: ${result.stdout}\nstderr: ${result.stderr}`);
+  });
+
+  test('workflow.md exists in render output', () => {
+    const rendered = path.join(tmpDir, '_bmad', 'render', 'bmad-quick-dev', 'workflow.md');
+    assert(fs.existsSync(rendered), `workflow.md not found at ${rendered}`);
+  });
+
+  test('custom override wins — workflow.md contains "Japanese"', () => {
+    const rendered = path.join(tmpDir, '_bmad', 'render', 'bmad-quick-dev', 'workflow.md');
+    const content = fs.readFileSync(rendered, 'utf-8');
+    assert(content.includes('Japanese'), `"Japanese" not found in workflow.md (communication_language override did not win)`);
+  });
+
+  test('sprint_status is an absolute path rooted at temp project dir', () => {
+    const rendered = path.join(tmpDir, '_bmad', 'render', 'bmad-quick-dev', 'workflow.md');
+    const content = fs.readFileSync(rendered, 'utf-8');
+    // Normalize to forward slashes for cross-platform matching
+    const normalizedTmp = tmpDir.replaceAll('\\', '/');
+    // sprint_status should appear as <tmpDir>/impl/sprint-status.yaml
+    const expected = `${normalizedTmp}/impl/sprint-status.yaml`;
+    assert(
+      content.includes(expected),
+      `sprint_status path not found.\nExpected substring: ${expected}\n` +
+        `workflow.md excerpt (first 2000 chars):\n${content.slice(0, 2000)}`,
+    );
+  });
+
+  test('workflow override — prepend step inlined as a bullet', () => {
+    const content = readRendered('workflow.md');
+    assert(content.includes('- TEST_PREPEND_STEP'), 'activation_steps_prepend not inlined as a bullet');
+  });
+
+  test('workflow override — persistent_facts append (base kept, override added)', () => {
+    const content = readRendered('workflow.md');
+    assert(content.includes('- TEST_EXTRA_FACT'), 'override persistent_fact not inlined');
+    assert(content.includes('project-context.md'), 'base persistent_fact dropped — append semantics broken');
+  });
+
+  test('empty activation_steps_append renders the _None._ sentinel', () => {
+    const content = readRendered('workflow.md');
+    assert(content.includes('_None._'), '_None._ sentinel missing for empty list');
+  });
+
+  test('on_complete scalar inlined into step-05 and step-oneshot', () => {
+    for (const file of ['step-05-present.md', 'step-oneshot.md']) {
+      assert(readRendered(file).includes('TEST_ON_COMPLETE_INSTRUCTION'), `on_complete not inlined into ${file}`);
+    }
+  });
+
+  test('no {workflow.*} placeholder survives in any rendered file', () => {
+    const leaks = renderedMdFiles().filter((f) => readRendered(f).includes('{workflow.'));
+    assert(leaks.length === 0, `{workflow.*} leaked in: ${leaks.join(', ')}`);
+  });
+
+  test('no resolve_customization.py reference survives in any rendered file', () => {
+    const leaks = renderedMdFiles().filter((f) => readRendered(f).includes('resolve_customization.py'));
+    assert(leaks.length === 0, `resolve_customization.py still referenced in: ${leaks.join(', ')}`);
+  });
+} finally {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log(`\n${colors.cyan}${'═'.repeat(55)}${colors.reset}`);
+console.log(`${colors.cyan}Test Results:${colors.reset}`);
+console.log(`  Total:  ${totalTests}`);
+console.log(`  Passed: ${colors.green}${passedTests}${colors.reset}`);
+console.log(`  Failed: ${passedTests === totalTests ? colors.green : colors.red}${totalTests - passedTests}${colors.reset}`);
+console.log(`${colors.cyan}${'═'.repeat(55)}${colors.reset}\n`);
+
+if (failures.length > 0) {
+  console.log(`${colors.red}FAILED TESTS:${colors.reset}\n`);
+  for (const failure of failures) {
+    console.log(`${colors.red}\u2717${colors.reset} ${failure.name}`);
+    console.log(`  ${failure.message}\n`);
+  }
+  process.exit(1);
+}
+
+console.log(`${colors.green}All tests passed!${colors.reset}\n`);
+process.exit(0);

tools/installer/core/installer.js

@@ -1233,6 +1233,9 @@ 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

@@ -1,199 +0,0 @@
-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

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

tools/skill-validator.md

@@ -10,7 +10,7 @@ Before running inference-based validation, run the deterministic validator:
 node tools/validate-skills.js --json path/to/skill-dir
 ```
 
-This checks 12 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
+This checks 13 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02, TPL-01.
 
 Review its JSON output. For any rule that produced **zero findings** in the first pass, **skip it** during inference-based validation below — it has already been verified. If a rule produced any findings, the inference validator should still review that rule (some rules like SKILL-04 and SKILL-06 have sub-checks that benefit from judgment). Focus your inference effort on the remaining rules that require judgment (PATH-01, PATH-03, PATH-04, PATH-05, WF-03, STEP-02, STEP-03, STEP-04, STEP-05, SEQ-01, REF-01, REF-02, REF-03).
 
@@ -253,6 +253,16 @@ If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
+### TPL-01 — Template Files Must Not Contain Compile-Time Substitutions
+
+- **Severity:** HIGH
+- **Applies to:** `.md` files whose name contains `template` (case-insensitive)
+- **Rule:** Template files seed durable, version-controlled artifacts (e.g. spec files) that execute on other machines. A `{{.var}}` compile-time substitution would be baked at render time and freeze a machine-local value into every artifact produced from the template.
+- **Detection:** Regex `\{\{\.\w+\}\}` match anywhere in a file whose basename matches `/template/i`.
+- **Fix:** Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated artifact.
+
+---
+
 ### REF-01 — Variable References Must Be Defined
 
 - **Severity:** HIGH

tools/validate-file-refs.js

@@ -80,7 +80,7 @@ function escapeTableCell(str) {
 }
 
 // Path prefixes/patterns that only exist in installed structure, not in source
-const INSTALL_ONLY_PATHS = ['_config/', 'custom/'];
+const INSTALL_ONLY_PATHS = ['_config/', 'custom/', 'render/bmad-quick-dev/'];
 
 // Files that are generated at install time and don't exist in the source tree
 const INSTALL_GENERATED_FILES = ['config.yaml', 'config.user.yaml'];

tools/validate-skills.js

@@ -17,6 +17,7 @@
  * - STEP-06: step frontmatter has no name/description
  * - STEP-07: step count 2-10
  * - SEQ-02: no time estimates
+ * - TPL-01: template files must not contain compile-time {{.var}} substitutions
  *
  * Usage:
  *   node tools/validate-skills.js                    # All skills, human-readable
@@ -43,6 +44,8 @@ const positionalArgs = args.filter((a) => !a.startsWith('--'));
 const NAME_REGEX = /^bmad-[a-z0-9]+(-[a-z0-9]+)*$/;
 const STEP_FILENAME_REGEX = /^step-\d{2}[a-z]?-[a-z0-9-]+\.md$/;
 const TIME_ESTIMATE_PATTERNS = [/takes?\s+\d+\s*min/i, /~\s*\d+\s*min/i, /estimated\s+time/i, /\bETA\b/];
+const TEMPLATE_FILENAME_REGEX = /template/i;
+const COMPILE_TIME_SUB_REGEX = /\{\{\.\w+\}\}/;
 
 const SEVERITY_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
 
@@ -530,6 +533,36 @@ function validateSkill(skillDir) {
     }
   }
 
+  // --- TPL-01: template files must not contain compile-time {{.var}} substitutions ---
+  // Template files seed durable, version-controlled artifacts (spec files) that
+  // execute on other machines. Baking a {{.var}} at render time would freeze a
+  // machine-local value into every downstream artifact.
+  for (const filePath of allFiles) {
+    if (path.extname(filePath) !== '.md') continue;
+    const base = path.basename(filePath);
+    if (!TEMPLATE_FILENAME_REGEX.test(base)) continue;
+
+    const relFile = path.relative(skillDir, filePath);
+    const content = safeReadFile(filePath, findings, relFile);
+    if (content === null) continue;
+
+    const lines = content.split('\n');
+    for (const [i, line] of lines.entries()) {
+      const match = line.match(COMPILE_TIME_SUB_REGEX);
+      if (match) {
+        findings.push({
+          rule: 'TPL-01',
+          title: 'Template files must not contain compile-time substitutions',
+          severity: 'HIGH',
+          file: relFile,
+          line: i + 1,
+          detail: `Template file contains compile-time substitution \`${match[0]}\` — this would be baked at render time and leak a machine-local value into every spec produced from the template.`,
+          fix: 'Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated spec.',
+        });
+      }
+    }
+  }
+
   return findings;
 }
 

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,
-          autogenerate: { directory: 'tutorials' },
+          items: [{ 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,
-          autogenerate: { directory: 'how-to' },
+          items: [{ autogenerate: { directory: 'how-to' } }],
         },
         {
           label: 'Explanation',
           translations: { 'vi-VN': 'Giải thích', 'zh-CN': '概念说明', 'fr-FR': 'Explications', 'cs-CZ': 'Vysvětlení' },
           collapsed: true,
-          autogenerate: { directory: 'explanation' },
+          items: [{ autogenerate: { directory: 'explanation' } }],
         },
         {
           label: 'Reference',
           translations: { 'vi-VN': 'Tham chiếu', 'zh-CN': '参考', 'fr-FR': 'Référence', 'cs-CZ': 'Reference' },
           collapsed: true,
-          autogenerate: { directory: 'reference' },
+          items: [{ autogenerate: { directory: 'reference' } }],
         },
         // TEA docs moved to standalone module site; keep BMM sidebar focused.
         {

website/src/content.config.ts

@@ -0,0 +1,8 @@
+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

@@ -1,7 +0,0 @@
-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 } from 'astro:content';
+import { getEntry, render } from 'astro:content';
 import { translatedLocales } from '../lib/locales.mjs';
 
 const entry = await getEntry('docs', '404');
-const { Content } = await entry.render();
+const { Content } = await render(entry);
 ---
 
 <StarlightPage frontmatter={{ title: entry.data.title, template: entry.data.template }}>