bmad-method 6.0.4 → 6.0.5-next.0

package/src/core/tasks/{help.md → bmad-help/workflow.md}

@@ -1,7 +1,3 @@
----
-name: help
-description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now'
----
 
 # Task: BMAD Help
 
@@ -21,6 +17,12 @@ description: 'Analyzes what is done and the users query and offers advice on wha
 When `command` field has a value:
 - Show the command prefixed with `/` (e.g., `/bmad-bmm-create-prd`)
 
+### Skill-Referenced Workflows
+When `workflow-file` starts with `skill:`:
+- The value is a skill reference (e.g., `skill:bmad-quick-dev-new-preview`), NOT a file path
+- Do NOT attempt to resolve or load it as a file path
+- Display using the `command` column value prefixed with `/` (same as command-based workflows)
+
 ### Agent-Based Workflows
 When `command` field is empty:
 - User loads agent first via `/agent-command`

package/src/core/tasks/bmad-review-adversarial-general/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-review-adversarial-general
+description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/src/core/tasks/bmad-review-adversarial-general/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/src/core/tasks/bmad-review-adversarial-general/workflow.md

@@ -0,0 +1,32 @@
+# Adversarial Review (General)
+
+**Goal:** Cynically review content and produce findings.
+
+**Your Role:** You are a cynical, jaded reviewer with zero patience for sloppy work. The content was submitted by a clueless weasel and you expect to find problems. Be skeptical of everything. Look for what's missing, not just what's wrong. Use a precise, professional tone — no profanity or personal attacks.
+
+**Inputs:**
+- **content** — Content to review: diff, spec, story, doc, or any artifact
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal adversarial analysis
+
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review from provided input or context
+- If content to review is empty, ask for clarification and abort
+- Identify content type (diff, branch, uncommitted changes, document, etc.)
+
+### Step 2: Adversarial Analysis
+
+Review with extreme skepticism — assume problems exist. Find at least ten issues to fix or improve in the provided content.
+
+### Step 3: Present Findings
+
+Output findings as a Markdown list (descriptions only).
+
+
+## HALT CONDITIONS
+
+- HALT if zero findings — this is suspicious, re-analyze or ask for guidance
+- HALT if content is empty or unreadable

package/src/core/tasks/bmad-review-edge-case-hunter/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-review-edge-case-hunter
+description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven.'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/src/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/src/core/tasks/bmad-review-edge-case-hunter/workflow.md

@@ -0,0 +1,62 @@
+# Edge Case Hunter Review
+
+**Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
+When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
+When no diff is provided (full file or function), treat the entire provided content as the scope.
+Ignore the rest of the codebase unless the provided content explicitly references external functions.
+
+**Inputs:**
+- **content** — Content to review: diff, full file, or function
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis
+
+**MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.**
+
+**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler — findings only.**
+
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review strictly from provided input
+- If content is empty, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+- Identify content type (diff, full file, or function) to determine scope rules
+
+### Step 2: Exhaustive Path Analysis
+
+**Walk every branching path and boundary condition within scope — report only unhandled ones.**
+
+- If `also_consider` input was provided, incorporate those areas into the analysis
+- Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- For each path: determine whether the content handles it
+- Collect only the unhandled paths as findings — discard handled ones silently
+
+### Step 3: Validate Completeness
+
+- Revisit every edge class from Step 2 — e.g., missing else/default, null/empty inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Add any newly found unhandled paths to findings; discard confirmed-handled ones
+
+### Step 4: Present Findings
+
+Output findings as a JSON array following the Output Format specification exactly.
+
+
+## OUTPUT FORMAT
+
+Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else:
+
+```json
+[{
+  "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)",
+  "trigger_condition": "one-line description (max 15 words)",
+  "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)",
+  "potential_consequence": "what could actually go wrong (max 15 words)"
+}]
+```
+
+No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when no unhandled paths are found.
+
+
+## HALT CONDITIONS
+
+- If content is empty or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop

package/src/core/tasks/bmad-skill-manifest.yaml

@@ -0,0 +1,19 @@
+editorial-review-prose.xml:
+  canonicalId: bmad-editorial-review-prose
+  type: task
+  description: "Clinical copy-editor that reviews text for communication issues"
+
+editorial-review-structure.xml:
+  canonicalId: bmad-editorial-review-structure
+  type: task
+  description: "Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension"
+
+index-docs.xml:
+  canonicalId: bmad-index-docs
+  type: task
+  description: "Generates or updates an index.md to reference all docs in the folder"
+
+shard-doc.xml:
+  canonicalId: bmad-shard-doc
+  type: task
+  description: "Splits large markdown documents into smaller, organized files based on sections"

package/src/core/workflows/advanced-elicitation/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: bmad-advanced-elicitation
+type: workflow
+description: "Push the LLM to reconsider, refine, and improve its recent output using structured reasoning methods"

package/src/core/workflows/advanced-elicitation/workflow.md

@@ -0,0 +1,138 @@
+---
+name: advanced-elicitation
+description: 'Push the LLM to reconsider refine and improve its recent output. Use when the user asks for advanced elicitation.'
+methods: '{project-root}/_bmad/core/workflows/advanced-elicitation/methods.csv'
+agent_party: '{project-root}/_bmad/_config/agent-manifest.csv'
+---
+
+# Advanced Elicitation Workflow
+
+**Goal:** Push the LLM to reconsider, refine, and improve its recent output. Use when the user asks for advanced elicitation.
+
+---
+
+## CRITICAL LLM INSTRUCTIONS
+
+- **MANDATORY:** Execute ALL steps in the flow section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+- Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution
+- **YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the `communication_language`**
+
+---
+
+## INTEGRATION (When Called from Workflow)
+
+When called during template workflow processing:
+
+1. Receive or review the current section content that was just generated
+2. Apply elicitation methods iteratively to enhance that specific content
+3. Return the enhanced version back when user selects 'x' to proceed and return back
+4. The enhanced content replaces the original section content in the output document
+
+---
+
+## FLOW
+
+### Step 1: Method Registry Loading
+
+**Action:** Load and read `{methods}` and `{agent_party}`
+
+#### CSV Structure
+
+- **category:** Method grouping (core, structural, risk, etc.)
+- **method_name:** Display name for the method
+- **description:** Rich explanation of what the method does, when to use it, and why it's valuable
+- **output_pattern:** Flexible flow guide using arrows (e.g., "analysis -> insights -> action")
+
+#### Context Analysis
+
+- Use conversation history
+- Analyze: content type, complexity, stakeholder needs, risk level, and creative potential
+
+#### Smart Selection
+
+1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential
+2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV
+3. Select 5 methods: Choose methods that best match the context based on their descriptions
+4. Balance approach: Include mix of foundational and specialized techniques as appropriate
+
+---
+
+### Step 2: Present Options and Handle Responses
+
+#### Display Format
+
+```
+**Advanced Elicitation Options**
+_If party mode is active, agents will join in._
+Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed:
+
+1. [Method Name]
+2. [Method Name]
+3. [Method Name]
+4. [Method Name]
+5. [Method Name]
+r. Reshuffle the list with 5 new options
+a. List all methods with descriptions
+x. Proceed / No Further Actions
+```
+
+#### Response Handling
+
+**Case 1-5 (User selects a numbered method):**
+
+- Execute the selected method using its description from the CSV
+- Adapt the method's complexity and output format based on the current context
+- Apply the method creatively to the current section content being enhanced
+- Display the enhanced version showing what the method revealed or improved
+- **CRITICAL:** Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response.
+- **CRITICAL:** ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to follow the instructions given by the user.
+- **CRITICAL:** Re-present the same 1-5,r,x prompt to allow additional elicitations
+
+**Case r (Reshuffle):**
+
+- Select 5 random methods from methods.csv, present new list with same prompt format
+- When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being potentially the most useful for the document or section being discovered
+
+**Case x (Proceed):**
+
+- Complete elicitation and proceed
+- Return the fully enhanced content back to create-doc.md
+- The enhanced content becomes the final version for that section
+- Signal completion back to create-doc.md to continue with next section
+
+**Case a (List All):**
+
+- List all methods with their descriptions from the CSV in a compact table
+- Allow user to select any method by name or number from the full list
+- After selection, execute the method as described in the Case 1-5 above
+
+**Case: Direct Feedback:**
+
+- Apply changes to current section content and re-present choices
+
+**Case: Multiple Numbers:**
+
+- Execute methods in sequence on the content, then re-offer choices
+
+---
+
+### Step 3: Execution Guidelines
+
+- **Method execution:** Use the description from CSV to understand and apply each method
+- **Output pattern:** Use the pattern as a flexible guide (e.g., "paths -> evaluation -> selection")
+- **Dynamic adaptation:** Adjust complexity based on content needs (simple to sophisticated)
+- **Creative application:** Interpret methods flexibly based on context while maintaining pattern consistency
+- Focus on actionable insights
+- **Stay relevant:** Tie elicitation to specific content being analyzed (the current section from the document being created unless user indicates otherwise)
+- **Identify personas:** For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory already
+- **Critical loop behavior:** Always re-offer the 1-5,r,a,x choices after each method execution
+- Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session
+- Each method application builds upon previous enhancements
+- **Content preservation:** Track all enhancements made during elicitation
+- **Iterative enhancement:** Each selected method (1-5) should:
+  1. Apply to the current enhanced version of the content
+  2. Show the improvements made
+  3. Return to the prompt for additional elicitations or completion

package/src/core/workflows/brainstorming/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: bmad-brainstorming
+type: workflow
+description: "Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods"

package/src/core/workflows/brainstorming/steps/step-03-technique-execution.md

@@ -1,7 +1,7 @@
 # Step 3: Interactive Technique Execution and Facilitation
 
 ---
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 ---
 
 ## MANDATORY EXECUTION RULES (READ FIRST):

package/src/core/workflows/brainstorming/workflow.md

@@ -49,7 +49,7 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
 
 All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern.
 - `context_file` = Optional context file path from workflow invocation for project-specific guidance
-- `advancedElicitationTask` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml`
+- `advancedElicitationTask` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md`
 
 ---
 

package/src/core/workflows/party-mode/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: bmad-party-mode
+type: workflow
+description: "Orchestrates group discussions between all installed BMAD agents"

package/src/utility/agent-components/activation-steps.txt

@@ -8,7 +8,7 @@
     <step n="3">Remember: user's name is {user_name}</step>
     {AGENT_SPECIFIC_STEPS}
     <step n="{MENU_STEP}">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
-    <step n="{HELP_STEP}">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help where should I start with an idea I have that does XYZ`</example></step>
+    <step n="{HELP_STEP}">Let {user_name} know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and that they can combine it with what they need help with <example>Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?"</example></step>
     <step n="{HALT_STEP}">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
     <step n="{INPUT_STEP}">On user input: Number → process menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
-    <step n="{EXECUTE_STEP}">When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+    <step n="{EXECUTE_STEP}">When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (exec, tmpl, data, action, multi) and follow the corresponding handler instructions</step>

package/src/utility/agent-components/handler-multi.txt

@@ -4,10 +4,9 @@
          2. Parse all nested handlers within the multi item
          3. For each nested handler:
             - Use the 'match' attribute for fuzzy matching user input (or Exact Match of character code in brackets [])
-            - Process based on handler attributes (exec, workflow, action)
+            - Process based on handler attributes (exec, action)
          4. When user input matches a handler's 'match' pattern:
             - For exec="path/to/file.md": follow the `handler type="exec"` instructions
-            - For workflow="path/to/workflow.yaml": follow the `handler type="workflow"` instructions
             - For action="...": Perform the specified action directly
          5. Support both exact matches and fuzzy matching based on the match attribute
          6. If no handler matches, prompt user to choose from available options

package/test/adversarial-review-tests/README.md

@@ -1,6 +1,6 @@
 # Adversarial Review Test Suite
 
-Tests for the `also_consider` optional input in `review-adversarial-general.xml`.
+Tests for the `also_consider` optional input in the `bmad-review-adversarial-general` skill.
 
 ## Purpose
 
@@ -19,12 +19,12 @@ All tests use `sample-content.md` - a deliberately imperfect User Authentication
 
 ## Running Tests
 
-For each test case in `test-cases.yaml`, invoke the adversarial review task.
+For each test case in `test-cases.yaml`, invoke the adversarial review skill.
 
 ### Manual Test Invocation
 
 ```
-Review this content using the adversarial review task:
+Review this content using the adversarial review skill:
 
 <content>
 [paste sample-content.md]

package/test/adversarial-review-tests/test-cases.yaml

@@ -1,9 +1,9 @@
-# Test Cases for review-adversarial-general.xml with also_consider input
+# Test Cases for bmad-review-adversarial-general skill with also_consider input
 #
 # Purpose: Evaluate how the optional also_consider input influences review findings
 # Content: All tests use sample-content.md (User Authentication API docs)
 #
-# To run: Manually invoke the task with each configuration and compare outputs
+# To run: Manually invoke the skill with each configuration and compare outputs
 
 test_cases:
   # BASELINE - No also_consider

package/test/fixtures/agent-schema/valid/menu/multiple-menu-items.agent.yaml

@@ -22,7 +22,7 @@ agent:
       action: display_help
     - trigger: start-workflow
       description: Start a workflow
-      workflow: path/to/workflow
+      exec: path/to/workflow
     - trigger: execute
       description: Execute command
       exec: npm test

package/test/fixtures/agent-schema/valid/menu-commands/all-command-types.agent.yaml

@@ -19,7 +19,7 @@ agent:
   menu:
     - trigger: workflow-test
       description: Test workflow command
-      workflow: path/to/workflow
+      exec: path/to/workflow
     - trigger: validate-test
       description: Test validate-workflow command
       validate-workflow: path/to/validation

package/test/fixtures/agent-schema/valid/menu-commands/multiple-commands.agent.yaml

@@ -19,6 +19,5 @@ agent:
   menu:
     - trigger: multi-command
       description: Menu item with multiple command targets
-      workflow: path/to/workflow
-      exec: npm test
+      exec: path/to/workflow
       action: perform_action

package/test/fixtures/file-refs-csv/valid/bmm-style.csv

@@ -1,3 +1,3 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
-bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.yaml,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze project",project-knowledge,*,
+bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.md,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze project",project-knowledge,*,
 bmm,1-analysis,Brainstorm Project,BP,10,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,data=template.md,"Brainstorming",planning_artifacts,"session",

package/test/test-file-refs-csv.js

@@ -58,7 +58,7 @@ test('bmm-style.csv: extracts workflow-file refs with trailing commas', () => {
   const { fullPath, content } = loadFixture('valid/bmm-style.csv');
   const refs = extractCsvRefs(fullPath, content);
   assert(refs.length === 2, `Expected 2 refs, got ${refs.length}`);
-  assert(refs[0].raw === '_bmad/bmm/workflows/document-project/workflow.yaml', `Wrong raw[0]: ${refs[0].raw}`);
+  assert(refs[0].raw === '_bmad/bmm/workflows/document-project/workflow.md', `Wrong raw[0]: ${refs[0].raw}`);
   assert(refs[1].raw === '_bmad/core/workflows/brainstorming/workflow.md', `Wrong raw[1]: ${refs[1].raw}`);
   assert(refs[0].type === 'project-root', `Wrong type: ${refs[0].type}`);
   assert(refs[0].line === 2, `Wrong line for row 0: ${refs[0].line}`);

package/test/test-install-to-bmad.js

@@ -0,0 +1,154 @@
+/**
+ * install_to_bmad Flag — Design Contract Tests
+ *
+ * Unit tests against the functions that implement the install_to_bmad flag.
+ * These nail down the 4 core design decisions:
+ *
+ * 1. true/omitted → skill stays in _bmad/ (default behavior)
+ * 2. false → skill removed from _bmad/ after IDE install
+ * 3. No platform → no cleanup runs (cleanup lives in installVerbatimSkills)
+ * 4. Mixed flags → each skill evaluated independently
+ *
+ * Usage: node test/test-install-to-bmad.js
+ */
+
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('fs-extra');
+const { loadSkillManifest, getInstallToBmad } = require('../tools/cli/installers/lib/ide/shared/skill-manifest');
+
+// ANSI colors
+const colors = {
+  reset: '\u001B[0m',
+  green: '\u001B[32m',
+  red: '\u001B[31m',
+  yellow: '\u001B[33m',
+  cyan: '\u001B[36m',
+  dim: '\u001B[2m',
+};
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, testName, errorMessage = '') {
+  if (condition) {
+    console.log(`${colors.green}✓${colors.reset} ${testName}`);
+    passed++;
+  } else {
+    console.log(`${colors.red}✗${colors.reset} ${testName}`);
+    if (errorMessage) {
+      console.log(`  ${colors.dim}${errorMessage}${colors.reset}`);
+    }
+    failed++;
+  }
+}
+
+async function runTests() {
+  console.log(`${colors.cyan}========================================`);
+  console.log('install_to_bmad — Design Contract Tests');
+  console.log(`========================================${colors.reset}\n`);
+
+  // ============================================================
+  // 1. true/omitted → getInstallToBmad returns true (keep in _bmad/)
+  // ============================================================
+  console.log(`${colors.yellow}Design decision 1: true or omitted → skill stays in _bmad/${colors.reset}\n`);
+
+  // Null manifest (no bmad-skill-manifest.yaml) → true
+  assert(getInstallToBmad(null, 'workflow.md') === true, 'null manifest defaults to true');
+
+  // Single-entry, flag omitted → true
+  assert(
+    getInstallToBmad({ __single: { type: 'skill' } }, 'workflow.md') === true,
+    'single-entry manifest with flag omitted defaults to true',
+  );
+
+  // Single-entry, explicit true → true
+  assert(
+    getInstallToBmad({ __single: { type: 'skill', install_to_bmad: true } }, 'workflow.md') === true,
+    'single-entry manifest with explicit true returns true',
+  );
+
+  console.log('');
+
+  // ============================================================
+  // 2. false → getInstallToBmad returns false (remove from _bmad/)
+  // ============================================================
+  console.log(`${colors.yellow}Design decision 2: false → skill removed from _bmad/${colors.reset}\n`);
+
+  // Single-entry, explicit false → false
+  assert(
+    getInstallToBmad({ __single: { type: 'skill', install_to_bmad: false } }, 'workflow.md') === false,
+    'single-entry manifest with explicit false returns false',
+  );
+
+  // loadSkillManifest round-trip: YAML with false is preserved through load
+  {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-itb-'));
+    await fs.writeFile(path.join(tmpDir, 'bmad-skill-manifest.yaml'), 'type: skill\ninstall_to_bmad: false\n');
+    const loaded = await loadSkillManifest(tmpDir);
+    assert(getInstallToBmad(loaded, 'workflow.md') === false, 'loadSkillManifest preserves install_to_bmad: false through round-trip');
+    await fs.remove(tmpDir);
+  }
+
+  console.log('');
+
+  // ============================================================
+  // 3. No platform → cleanup only runs inside installVerbatimSkills
+  //    (This is a design invariant: getInstallToBmad is only consulted
+  //     during IDE install. Without a platform, the flag has no effect.)
+  // ============================================================
+  console.log(`${colors.yellow}Design decision 3: flag is a per-skill property, not a pipeline gate${colors.reset}\n`);
+
+  // The flag value is stored but doesn't trigger any side effects by itself.
+  // Cleanup is driven by reading the CSV column inside installVerbatimSkills.
+  // We verify the flag is just data — getInstallToBmad doesn't touch the filesystem.
+  {
+    const manifest = { __single: { type: 'skill', install_to_bmad: false } };
+    const result = getInstallToBmad(manifest, 'workflow.md');
+    assert(typeof result === 'boolean', 'getInstallToBmad returns a boolean (pure data, no side effects)');
+    assert(result === false, 'false value is faithfully returned for consumer to act on');
+  }
+
+  console.log('');
+
+  // ============================================================
+  // 4. Mixed flags → each skill evaluated independently
+  // ============================================================
+  console.log(`${colors.yellow}Design decision 4: mixed flags — each skill independent${colors.reset}\n`);
+
+  // Multi-entry manifest: different files can have different flags
+  {
+    const manifest = {
+      'workflow.md': { type: 'skill', install_to_bmad: false },
+      'other.md': { type: 'skill', install_to_bmad: true },
+    };
+    assert(getInstallToBmad(manifest, 'workflow.md') === false, 'multi-entry: workflow.md with false returns false');
+    assert(getInstallToBmad(manifest, 'other.md') === true, 'multi-entry: other.md with true returns true');
+    assert(getInstallToBmad(manifest, 'unknown.md') === true, 'multi-entry: unknown file defaults to true');
+  }
+
+  console.log('');
+
+  // ============================================================
+  // Summary
+  // ============================================================
+  console.log(`${colors.cyan}========================================`);
+  console.log('Results:');
+  console.log(`  Passed: ${colors.green}${passed}${colors.reset}`);
+  console.log(`  Failed: ${colors.red}${failed}${colors.reset}`);
+  console.log(`========================================${colors.reset}\n`);
+
+  if (failed === 0) {
+    console.log(`${colors.green}All install_to_bmad contract tests passed!${colors.reset}\n`);
+    process.exit(0);
+  } else {
+    console.log(`${colors.red}Some install_to_bmad contract tests failed${colors.reset}\n`);
+    process.exit(1);
+  }
+}
+
+runTests().catch((error) => {
+  console.error(`${colors.red}Test runner failed:${colors.reset}`, error.message);
+  console.error(error.stack);
+  process.exit(1);
+});