From aa003890273cf2296fab30a0b2abbb652f99152f Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 20 Jun 2026 01:23:28 -0500 Subject: [PATCH] bmm: invoke scripts with 'uv run' instead of python3/bare uv Bare 'uv {path}.py' does not execute (uv treats the path as a subcommand and errors); only 'uv run {path}' runs the script. Fixes the broken bare-uv memlog form shipped earlier in this branch and converts python3 script calls to 'uv run' across the 6 touched skills (memlog.py, resolve_customization.py, brain.py, lint_spine.py). Inline 'python3 -c' one-liners and .py shebangs are left as-is. --- .../1-analysis/bmad-product-brief/SKILL.md | 6 +++--- src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md | 6 +++--- .../2-plan-workflows/bmad-prd/references/headless.md | 2 +- src/bmm-skills/2-plan-workflows/bmad-ux/SKILL.md | 6 +++--- .../2-plan-workflows/bmad-ux/references/headless.md | 2 +- .../3-solutioning/bmad-architecture/SKILL.md | 6 +++--- .../bmad-architecture/references/reviewer-gate.md | 2 +- src/core-skills/bmad-brainstorming/SKILL.md | 12 ++++++------ .../bmad-brainstorming/references/converge.md | 2 +- .../bmad-brainstorming/references/finalize.md | 2 +- .../bmad-brainstorming/references/headless.md | 4 ++-- .../references/in-chat-techniques.md | 2 +- .../bmad-brainstorming/references/mode-autonomous.md | 2 +- src/core-skills/bmad-spec/SKILL.md | 6 +++--- 14 files changed, 30 insertions(+), 30 deletions(-) diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md index dbd6353b1..baa85f9f8 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md @@ -15,7 +15,7 @@ At the opening greeting, let the user know they can invoke `bmad-party-mode` for ## On Activation -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. +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 and use defaults. 2. Execute each entry in `{workflow.activation_steps_prepend}` in order. 3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim. 4. `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers in `## Discovery`, org tools preferred when their directive matches. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant. @@ -28,7 +28,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen ## Intent Operating Modes -**Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume: instead converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely - create sections for specialized domains or concerns also as needed. The brief serves the product's story, not the template's shape. Bind `{doc_workspace}` to a fresh folder at `{workflow.brief_output_path}/{workflow.run_folder_pattern}/`, write `brief.md` there with YAML frontmatter (title, status, created, updated), and seed the memlog: `uv {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic=""`. For Update and Validate, `{doc_workspace}` is the existing folder of the brief being targeted. +**Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume: instead converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely - create sections for specialized domains or concerns also as needed. The brief serves the product's story, not the template's shape. Bind `{doc_workspace}` to a fresh folder at `{workflow.brief_output_path}/{workflow.run_folder_pattern}/`, write `brief.md` there with YAML frontmatter (title, status, created, updated), and seed the memlog: `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic=""`. For Update and Validate, `{doc_workspace}` is the existing folder of the brief being targeted. **Update.** Reconcile an existing brief with a change signal. Before proposing changes, read the brief, addendum, `.memlog.md`, and original inputs — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal via `memlog.py append --type override`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. @@ -77,7 +77,7 @@ The workspace persists; stop and resume freely. The opener's philosophy (not in - **Right-size to purpose.** A passion project does not need investor-grade rigor. A VC pitch input does. Read the room. - **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `brief.md` skeleton with `status: draft`, `.memlog.md` seeded via `memlog.py init`) exists on disk and the user knows the path. -- **File roles.** `.memlog.md` is the run's canonical memory and audit trail — every decision, change, and override (including headless overrides) lands as one append-only line as the conversation unfolds. All writes go through the shared script, never by hand: `uv {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text ""` (atomic; read it back only to resume or audit). The brief is distilled toward it; whatever isn't logged is lost on resume. `addendum.md` preserves user-contributed depth that belongs in a downstream document (PRD, architecture, solution design) or earned a place but does not fit the brief (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, in-depth personas, sizing data). Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum. +- **File roles.** `.memlog.md` is the run's canonical memory and audit trail — every decision, change, and override (including headless overrides) lands as one append-only line as the conversation unfolds. All writes go through the shared script, never by hand: `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text ""` (atomic; read it back only to resume or audit). The brief is distilled toward it; whatever isn't logged is lost on resume. `addendum.md` preserves user-contributed depth that belongs in a downstream document (PRD, architecture, solution design) or earned a place but does not fit the brief (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, in-depth personas, sizing data). Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum. - **Continuity across sessions.** If a prior in-progress draft for this project exists, the user is offered to resume. - **Extract, don't ingest.** Source artifacts (provided by the user or discovered during the run — transcripts, brainstorms, research reports, code, web results, prior briefs) enter the parent conversation as relevance-filtered extracts, not loaded wholesale. Subagents do the extraction against the user's stated focus; the parent context stays lean. - **Length and coherence.** Aim for 1-2 pages — if it is longer, the detail belongs in the addendum. Structure in service of the product; downstream consumers (PRD workflow, etc.) read this, so coherent shape matters. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index 1d940b230..4ba158911 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -11,11 +11,11 @@ You are a master facilitator and coach helping the user create, edit, or validat - Bare paths resolve from skill root; `{skill-root}` is this skill's install dir; `{project-root}` is the project working dir. - `{workflow.}` resolves to fields in `customize.toml`'s `[workflow]` table (overrides win per BMad merge rules). - `{doc_workspace}` is the bound run folder. -- **File roles.** `.memlog.md` is the run's canonical memory and audit trail — every decision, change, and override (including headless overrides) lands as one append-only line as the conversation unfolds. All writes go through the shared script, never by hand: `uv {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text ""` (atomic; read it back only to resume or audit). The PRD is distilled toward it; whatever isn't logged is lost on resume. `addendum.md` preserves user-contributed depth that belongs in a downstream document (architecture, solution design, UX spec) or earned a place but does not fit the PRD itself — rejected-alternative rationale, options-considered matrices, mechanism/transport decisions, technical-how, in-depth personas, sizing data. Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum. +- **File roles.** `.memlog.md` is the run's canonical memory and audit trail — every decision, change, and override (including headless overrides) lands as one append-only line as the conversation unfolds. All writes go through the shared script, never by hand: `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text ""` (atomic; read it back only to resume or audit). The PRD is distilled toward it; whatever isn't logged is lost on resume. `addendum.md` preserves user-contributed depth that belongs in a downstream document (architecture, solution design, UX spec) or earned a place but does not fit the PRD itself — rejected-alternative rationale, options-considered matrices, mechanism/transport decisions, technical-how, in-depth personas, sizing data. Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum. ## On Activation -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. +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 and use defaults. 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**. 3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block. 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-quick-dev`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing. @@ -27,7 +27,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen ## Intent Modes -**Create.** Bind `{doc_workspace}` to `{workflow.prd_output_path}/{workflow.run_folder_pattern}/`. Write `prd.md` with YAML frontmatter (title, status, created, updated — initial `status: draft`), and seed the memlog with `uv {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic=""` so subsequent decisions land in a known file. Tell the user the path. Run `## Discovery`, then `## Finalize`. +**Create.** Bind `{doc_workspace}` to `{workflow.prd_output_path}/{workflow.run_folder_pattern}/`. Write `prd.md` with YAML frontmatter (title, status, created, updated — initial `status: draft`), and seed the memlog with `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic=""` so subsequent decisions land in a known file. Tell the user the path. Run `## Discovery`, then `## Finalize`. **Update.** Reconcile the PRD with a change signal. Source-extract against PRD, addendum, `.memlog.md`, and original inputs (extract, don't ingest). If `.memlog.md` is missing, `memlog.py init` it, then spawn a one-time bootstrap subagent to reverse-engineer a thin log from the PRD (one `memlog.py append` per recovered decision) before continuing. Surface conflicts with prior decisions before applying. Then `## Finalize`. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md index ba752037a..2f5a168a0 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md @@ -34,6 +34,6 @@ End with the JSON response (full schemas with examples in `assets/headless-schem ## Mode-specific overrides -**Update.** Apply the change, log it via `uv {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type change --text ""`, and surface any conflict-with-prior-decision in `conflicts_with_prior_decisions[]` in the JSON status. Halt `blocked` if intent is ambiguous. +**Update.** Apply the change, log it via `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type change --text ""`, and surface any conflict-with-prior-decision in `conflicts_with_prior_decisions[]` in the JSON status. Halt `blocked` if intent is ambiguous. **Validate.** Always write both `validation-report.html` and `validation-report.md` to `{doc_workspace}` regardless of finding count. Always include `"offer_to_update": true` in the JSON status. Skip the browser-open step in `references/validate.md` — write the artifacts and return. diff --git a/src/bmm-skills/2-plan-workflows/bmad-ux/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-ux/SKILL.md index 1831d4f49..131a6c9ea 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-ux/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-ux/SKILL.md @@ -30,7 +30,7 @@ UX may lead, follow, or stand alone. Inherit `sources:` by reference; the spines ## On Activation -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. +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 and use defaults. 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools; consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. 3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block. 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn. In the greeting, let the user know `bmad-party-mode` and `bmad-advanced-elicitation` are always available. Then scan for misroute on the first message: PRD → `bmad-prd`; architecture → `bmad-architecture`; game UX → BMad GDS; agent/skill → `bmad-workflow-builder`; brief → `bmad-product-brief`. @@ -42,7 +42,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen ## Modes -**Create.** Bind `{doc_workspace}` to `{workflow.ux_output_path}/{workflow.run_folder_pattern}/`. Create `.working/` and `imports/`; seed the memlog with `uv {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic=""`; create `DESIGN.md` (frontmatter only) and `EXPERIENCE.md` (frontmatter only). Run Discovery → Finalize. +**Create.** Bind `{doc_workspace}` to `{workflow.ux_output_path}/{workflow.run_folder_pattern}/`. Create `.working/` and `imports/`; seed the memlog with `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic=""`; create `DESIGN.md` (frontmatter only) and `EXPERIENCE.md` (frontmatter only). Run Discovery → Finalize. **Update.** Read spines + memlog + sources. `memlog.py init` the memlog if missing — this update is entry one. Surface conflicts with prior decisions. Run Finalize. @@ -50,7 +50,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen ## Discovery -**Capture; do not author.** The spines are distilled at Finalize toward the memlog. Decisions → `.memlog.md` (canonical), each appended via `uv {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text "…"` — never hand-edited; a resume reloads it. Creative-tool artifacts → `.working/`. User-supplied visuals (Figma, sketches, brand decks, image folders) → `imports/`, one `memlog.py append` per item. Spines win on conflict. +**Capture; do not author.** The spines are distilled at Finalize toward the memlog. Decisions → `.memlog.md` (canonical), each appended via `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text "…"` — never hand-edited; a resume reloads it. Creative-tool artifacts → `.working/`. User-supplied visuals (Figma, sketches, brand decks, image folders) → `imports/`, one `memlog.py append` per item. Spines win on conflict. **Source scan.** Glob `{planning_artifacts}/` for candidate input paths; surface paths only — never read content in the parent. User confirms which apply or adds others; subagent-extracts on confirm. diff --git a/src/bmm-skills/2-plan-workflows/bmad-ux/references/headless.md b/src/bmm-skills/2-plan-workflows/bmad-ux/references/headless.md index bbb615cef..7f1f8588c 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-ux/references/headless.md +++ b/src/bmm-skills/2-plan-workflows/bmad-ux/references/headless.md @@ -32,6 +32,6 @@ End with JSON matching `assets/headless-schemas.md`. `intent` reflects detected ## Mode-specific overrides -**Update.** Apply the change. Log it via `uv {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type change --text ""`. Surface conflicts in `conflicts_with_prior_decisions[]`. +**Update.** Apply the change. Log it via `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type change --text ""`. Surface conflicts in `conflicts_with_prior_decisions[]`. **Validate.** Always write both `validation-report.html` and `validation-report.md` regardless of finding count. Always include `"offer_to_update": true`. Skip the browser-open step. diff --git a/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md b/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md index fb978571d..bd89fa94c 100644 --- a/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md +++ b/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md @@ -36,8 +36,8 @@ The **memlog** (`.memlog.md`) is the run's working memory: every decision, const Writes go through the shared script (don't read the file back except on resume): -- `uv {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field scope="…" --field purpose="…" --field altitude="…"` -- `uv {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text "…"` +- `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field scope="…" --field purpose="…" --field altitude="…"` +- `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text "…"` ## Resolution rules @@ -50,7 +50,7 @@ Writes go through the shared script (don't read the file back except on resume): **Forwarded activation:** if a caller (e.g. the `bmad-create-architecture` shim) invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`. -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand. +1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand. 2. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml`) for `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`; missing keys take neutral defaults, never block. 3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default), **update** an existing spine, or **validate** one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `bmad-prd`, `bmad-ux`, `bmad-spec`, `bmad-create-epics-and-stories`, or `bmad-workflow-builder` (if the BMad Builder module is installed) skill instead. 4. If a run folder for this target already exists under `{workflow.spine_output_path}`, offer to resume from its memlog rather than restart. diff --git a/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md b/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md index 175676413..159548a95 100644 --- a/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md +++ b/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md @@ -2,7 +2,7 @@ The spine's pre-handoff review. Runs at Finalize (after distill + reconcile) and *is* the Validate intent. The difference is the ending: at Finalize you apply the clear fixes yourself; under Validate you report and don't change the spine. -Cheap deterministic pass first: `python3 {skill-root}/scripts/lint_spine.py --workspace {doc_workspace}` settles the mechanical misses (placeholders, duplicate `AD` IDs, missing Binds/Prevents/Rule, unpinned Stack versions), so reviewers spend judgment on the semantic half. +Cheap deterministic pass first: `uv run {skill-root}/scripts/lint_spine.py --workspace {doc_workspace}` settles the mechanical misses (placeholders, duplicate `AD` IDs, missing Binds/Prevents/Rule, unpinned Stack versions), so reviewers spend judgment on the semantic half. Assemble the menu: a **rubric walker** that judges the spine against the good-spine checklist below, **+ every entry in `{workflow.finalize_reviewers}`**, + ad-hoc lenses you invent or offer as the spine's rigor, altitude, and criticality warrant — a security/compliance lens for regulated stakes, a seam reviewer cross-team, a data-integrity lens for a heavy data model. Scale *whether and how heavily the gate runs* to the stakes: a throwaway prototype may run it quietly or skip the gate entirely; a high-criticality or platform-altitude spine earns more lenses and the explicit all / subset / skip menu. But once the gate runs, the `{workflow.finalize_reviewers}` always run — they are the configured floor, never cherry-picked out; only the ad-hoc lenses are optional. (Headless never skips the gate.) diff --git a/src/core-skills/bmad-brainstorming/SKILL.md b/src/core-skills/bmad-brainstorming/SKILL.md index b06a031c3..f3878f6fe 100644 --- a/src/core-skills/bmad-brainstorming/SKILL.md +++ b/src/core-skills/bmad-brainstorming/SKILL.md @@ -18,7 +18,7 @@ The session runs in one of three stances, chosen by the user — set explicitly ## On Activation -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, use a subagent to read `{skill-root}/customize.toml` directly with defaults. +1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, use a subagent to read `{skill-root}/customize.toml` directly with defaults. 2. Run each `{workflow.activation_steps_prepend}` entry. Treat each `{workflow.persistent_facts}` entry as foundational context (`file:`-prefixed entries are paths/globs under `{project-root}` — load their contents; others are facts verbatim). 3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present); resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{output_folder}`, `{project_name}`, `{date}`. Missing → neutral defaults; never block. 4. **If launched headless** (a machine signal, not a human asking for output — `references/headless.md` lists them): load `references/headless.md` and follow it for the whole run. It is the *only* context where you generate ideas yourself; never load it otherwise. @@ -36,9 +36,9 @@ These fight your defaults, in every mode; hold them deliberately. The stance you **The memlog** is the session's memory: the single source every output builds from, and the file a resume reloads. Whatever isn't in it is gone. Log every idea, decision, question, and bit of user direction — anything you'd regret losing if the window closed — one line each, the gist in the user's meaning, in time order; never edit or reorder. Skip your prompts and small talk. All writes to memlog are atomic and use the script `memlog.py` invoked as follows: -- `uv {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="" --field goal="" --field mode=""` — create it once topic, goal, and stance are known. -- `uv {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text ""` — log one entry. `--type` ∈ `idea`/`insight`/`question`/`decision`/`direction`/`technique` (a switch: `--text "started "`); omit for a plain note. Add `--by user`/`--by coach` to mark authorship — **required in Creative Partner mode** (renders `(idea by user)`); skip it otherwise. -- `uv {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete` — flip status at wrap-up. +- `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="" --field goal="" --field mode=""` — create it once topic, goal, and stance are known. +- `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type --text ""` — log one entry. `--type` ∈ `idea`/`insight`/`question`/`decision`/`direction`/`technique` (a switch: `--text "started "`); omit for a plain note. Add `--by user`/`--by coach` to mark authorship — **required in Creative Partner mode** (renders `(idea by user)`); skip it otherwise. +- `uv run {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete` — flip status at wrap-up. ## Run a Session @@ -46,7 +46,7 @@ Open with one compound question what are we brainstorming, and what's the goal o Now set the **stance** and the **technique batch** in one step — the composer page does both, so make it the default. -**The composer page (primary).** The file is `{skill-root}/assets/brain-selector.html`. With a customized catalog (overridden `{workflow.brain_methods}` or any `{workflow.additional_techniques}`), regenerate it first: `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} [--extra {doc_workspace}/extra-techniques.json] html --out {doc_workspace}/brain-selector.html` (pass `--extra`, a JSON list of `{category, technique_name, description}`, when there are additional techniques; the file is then `{doc_workspace}/brain-selector.html`). Try to open it (`open` / `xdg-open` / `start`), then say, in one message: *"It should open in your browser — compose your session, click **Copy prompt**, and paste the result back. If it didn't open, open `` yourself, or say 'let's do it in chat'."* You can't see their browser, so never claim it opened. +**The composer page (primary).** The file is `{skill-root}/assets/brain-selector.html`. With a customized catalog (overridden `{workflow.brain_methods}` or any `{workflow.additional_techniques}`), regenerate it first: `uv run {skill-root}/scripts/brain.py --file {workflow.brain_methods} [--extra {doc_workspace}/extra-techniques.json] html --out {doc_workspace}/brain-selector.html` (pass `--extra`, a JSON list of `{category, technique_name, description}`, when there are additional techniques; the file is then `{doc_workspace}/brain-selector.html`). Try to open it (`open` / `xdg-open` / `start`), then say, in one message: *"It should open in your browser — compose your session, click **Copy prompt**, and paste the result back. If it didn't open, open `` yourself, or say 'let's do it in chat'."* You can't see their browser, so never claim it opened. Read the pasted block: the **`Facilitation mode:`** line → the stance; the **listed techniques** (full category/name/description, some tagged `(random pick)`) → run them as given, no `list`/`show` needed; **`invent N`** / **`you choose N`** → see `## Choosing Techniques`. @@ -61,7 +61,7 @@ For **Facilitator** and **Creative Partner**. (In **Ideate for me** you pick and Most sessions arrive with a batch already composed on the page — run it as given (each technique's full text is in the paste; no `list`/`show` needed). Two parts of a paste delegate back to you: - **`invent N`** (Inventive Flow) — invent N brand-new techniques on the fly. A line may scope an invention (`invent 1 new technique in the spirit of `, from the page's per-category invent card) — when it does, honor that category's spirit. Announce the order, log each one's name + description, and offer to save a keeper to `{workflow.additional_techniques}` at wrap-up. -- **`you choose N`** (Facilitator Chosen) — pick N techniques fitting the goal, `{workflow.favorite_techniques}` first; confirm exact names with a scoped `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} list --category `. Never pull the library whole into context. +- **`you choose N`** (Facilitator Chosen) — pick N techniques fitting the goal, `{workflow.favorite_techniques}` first; confirm exact names with a scoped `uv run {skill-root}/scripts/brain.py --file {workflow.brain_methods} list --category `. Never pull the library whole into context. If they didn't use the page, load `references/in-chat-techniques.md` and pick the batch in chat (**3–4 is the sweet spot**). diff --git a/src/core-skills/bmad-brainstorming/references/converge.md b/src/core-skills/bmad-brainstorming/references/converge.md index 5758870cb..a24231fcc 100644 --- a/src/core-skills/bmad-brainstorming/references/converge.md +++ b/src/core-skills/bmad-brainstorming/references/converge.md @@ -17,7 +17,7 @@ Pick by what the decision needs: - **PMI (Plus / Minus / Interesting)** — when one strong candidate needs pressure-testing before commitment: list its pluses, minuses, and the merely-interesting, then judge. - **MoSCoW** — when scoping a build: sort into Must / Should / Could / Won't-this-time. -Log the surviving directions and the reasoning with `uv {project-root}/_bmad/scripts/memlog.py append --type decision --text ""` (use `--by` in Creative Partner mode). Two or three convergence moves chained is fine (e.g. cluster → score the clusters); more than that is usually over-processing. +Log the surviving directions and the reasoning with `uv run {project-root}/_bmad/scripts/memlog.py append --type decision --text ""` (use `--by` in Creative Partner mode). Two or three convergence moves chained is fine (e.g. cluster → score the clusters); more than that is usually over-processing. ## Then finalize diff --git a/src/core-skills/bmad-brainstorming/references/finalize.md b/src/core-skills/bmad-brainstorming/references/finalize.md index fa046ee3a..c7a888472 100644 --- a/src/core-skills/bmad-brainstorming/references/finalize.md +++ b/src/core-skills/bmad-brainstorming/references/finalize.md @@ -9,7 +9,7 @@ In Facilitator mode this is the one place your own creative contribution is welc 1. **Hand them the mirror first.** Reflect a vivid sampling of *their* ideas back — deliberately include the odd, random, or buried ones from earlier, not just the recent obvious ones (in Creative Partner mode the `(... by user)` tags tell you which were theirs). Ask what they see now: conclusions, synergies, themes, the few that actually matter. Let them connect first; their own pattern-recognition is the point. 2. **Then add the connections they would miss.** Lean in creatively — not new raw ideas, but the non-obvious links: this idea from technique one quietly solves that tension from technique four; these three are one idea wearing three hats; this wildcard is the real breakthrough. -Record the insights and chosen directions with `memlog.py append --type insight`. **Then run `uv {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete`** — the session is done and must stop being offered for resume. Do this even if the user declines every artifact below. +Record the insights and chosen directions with `memlog.py append --type insight`. **Then run `uv run {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete`** — the session is done and must stop being offered for resume. Do this even if the user declines every artifact below. ## Artifacts diff --git a/src/core-skills/bmad-brainstorming/references/headless.md b/src/core-skills/bmad-brainstorming/references/headless.md index 74b741521..1e687dfdf 100644 --- a/src/core-skills/bmad-brainstorming/references/headless.md +++ b/src/core-skills/bmad-brainstorming/references/headless.md @@ -14,7 +14,7 @@ When in doubt, you are interactive — a present human asking you to "brainstorm ## The inversion -There is no user to draw ideas out of, so you become the brainstormer. Run a real divergent session against the supplied topic: discover techniques with `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} list --all` (the whole catalog is fine here — you are generating, not pacing a user; add `show ""` for a technique's full method on demand), plus any `{workflow.additional_techniques}`, preferring `{workflow.favorite_techniques}` where they fit; work them, and **shift the creative domain every ~10 ideas** exactly as the interactive Stance demands — technical, then experiential, then business, then failure modes, then wildcards. Push past the obvious; the same quantity ambition (aim past 100) and anti-clustering discipline apply. The only thing that changes is that the ideas are now yours to generate. This relaxation is scoped entirely to this file — it never applies to interactive sessions. +There is no user to draw ideas out of, so you become the brainstormer. Run a real divergent session against the supplied topic: discover techniques with `uv run {skill-root}/scripts/brain.py --file {workflow.brain_methods} list --all` (the whole catalog is fine here — you are generating, not pacing a user; add `show ""` for a technique's full method on demand), plus any `{workflow.additional_techniques}`, preferring `{workflow.favorite_techniques}` where they fit; work them, and **shift the creative domain every ~10 ideas** exactly as the interactive Stance demands — technical, then experiential, then business, then failure modes, then wildcards. Push past the obvious; the same quantity ambition (aim past 100) and anti-clustering discipline apply. The only thing that changes is that the ideas are now yours to generate. This relaxation is scoped entirely to this file — it never applies to interactive sessions. ## Inputs the caller is expected to provide @@ -29,7 +29,7 @@ Free-form structured payload in the first message; provide what applies: ## Run -1. Bind `{doc_workspace}` and create the memlog with `uv {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="" [--field goal=""]`. It remains the canonical source every artifact derives from. +1. Bind `{doc_workspace}` and create the memlog with `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="" [--field goal=""]`. It remains the canonical source every artifact derives from. 2. Run the divergent session per **The inversion**, capturing each idea with `memlog.py append --workspace {doc_workspace} --type idea --text ""` as it lands, and marking each technique switch with `memlog.py append --type technique --text "started "`. 3. Synthesize: surface the conclusions, connections, and the few directions that matter; record them with `memlog.py append --type insight`, then run `memlog.py set --workspace {doc_workspace} --key status --value complete`. 4. Produce the requested artifacts from the log — `brainstorm.html` (the imaginative, self-contained, no-template report) and/or the succinct `brainstorm-intent.md` — the same artifacts `references/finalize.md` describes, delegating each to a subagent that reads the log as its sole source. (Headless produces the `artifacts` payload directly; it does not ask, unlike the interactive opt-in.) diff --git a/src/core-skills/bmad-brainstorming/references/in-chat-techniques.md b/src/core-skills/bmad-brainstorming/references/in-chat-techniques.md index f041d4cfa..4e0e02a7b 100644 --- a/src/core-skills/bmad-brainstorming/references/in-chat-techniques.md +++ b/src/core-skills/bmad-brainstorming/references/in-chat-techniques.md @@ -7,7 +7,7 @@ Loaded only when the user won't use the composer page (no browser, headless, or - **Category** — the user names 1–n categories; `random --category` draws the batch from them. No listing needed. - **Inventive Flow** — invent at least 3 techniques, announce the order before the first, touch no script. Log each one's name + description so you can offer to save a keeper to `{workflow.additional_techniques}` (via `bmad-customize`) at wrap-up. -The library is large — never pull it whole into context. The only way in is the helper, always passing `--file {workflow.brain_methods}`. Subcommands of `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods}`: +The library is large — never pull it whole into context. The only way in is the helper, always passing `--file {workflow.brain_methods}`. Subcommands of `uv run {skill-root}/scripts/brain.py --file {workflow.brain_methods}`: - `categories` — names + counts; the cheap survey map. - `list --category X [--category Y]` — the index (name + gist) for those categories. Bare `list` is refused by the script. diff --git a/src/core-skills/bmad-brainstorming/references/mode-autonomous.md b/src/core-skills/bmad-brainstorming/references/mode-autonomous.md index d26dce289..646ef616e 100644 --- a/src/core-skills/bmad-brainstorming/references/mode-autonomous.md +++ b/src/core-skills/bmad-brainstorming/references/mode-autonomous.md @@ -5,6 +5,6 @@ The user handed you the topic and wants to see what you come up with on your own - **Run a real divergent session yourself.** Pick and run techniques on your own (use `brain.py` as in `## Choosing Techniques`, but *you* choose — no menu for the user), capturing each idea to the memlog with `--type idea --by coach`, marking each technique switch with a `technique` entry, shifting the creative domain every ~10 ideas, aiming past 100. Push past the obvious. - **Don't pepper the user with questions** — this is your run. One quick confirm of topic and goal up front is plenty. - **When it's mined out, synthesize and produce the keepsake.** Go to `## Wrap-Up` (`references/finalize.md`): record the insights, mark the memlog complete, and **auto-generate the imaginative HTML keepsake — don't ask first; the keepsake is the result you promised to show them.** Offer the other artifacts (intent doc, etc.) after. -- **Then, because a human is here, offer to keep going together.** They may want to push an idea further or react to what you found — if so, switch into **Facilitator** or **Creative Partner** (load that frame), **record the switch in the memlog** so a resume restores the new stance — `uv {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key mode --value ` — and continue from the same memlog. +- **Then, because a human is here, offer to keep going together.** They may want to push an idea further or react to what you found — if so, switch into **Facilitator** or **Creative Partner** (load that frame), **record the switch in the memlog** so a resume restores the new stance — `uv run {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key mode --value ` — and continue from the same memlog. This is the interactive sibling of headless mode (`references/headless.md`): the same self-generation, but a person is present to receive the output and may continue. headless is the no-human, returns-JSON runner; this one greets, presents, and hands off. diff --git a/src/core-skills/bmad-spec/SKILL.md b/src/core-skills/bmad-spec/SKILL.md index b02dfa35d..aa1fb8fdc 100644 --- a/src/core-skills/bmad-spec/SKILL.md +++ b/src/core-skills/bmad-spec/SKILL.md @@ -18,7 +18,7 @@ Multiple skills may call to update the same spec over time. ## On Activation -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly. +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. 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded). 3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. 4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field. @@ -57,8 +57,8 @@ Deriving the contract from a living log instead of editing the contract in place Writes go through the shared script — `{project-root}/_bmad/scripts/memlog.py`, the same location as `resolve_customization.py` (atomic; never read it back except to resume): -- `uv {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic=""` — once, at create. -- `uv {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type --text ""` — as each lands. +- `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic=""` — once, at create. +- `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type --text ""` — as each lands. - Terminal moments (a validation verdict, "spec finalized") are `--type event` entries; the memlog carries no status field. ## The Operation