Merge e9cce0f848 into cd45d22eb6

* docs: chose your tea engagement

* docs: addressed PR comments

* docs: made refiements to the mermaid diagram

* docs: wired in test architect discoverability nudges

---------

Co-authored-by: Brian <bmadcode@gmail.com>

docs/modules/bmm-bmad-method/index.md

@@ -40,6 +40,8 @@ First know there is the full BMad Method Process and then there is a Quick Flow
   - Implementation in minutes, not days
   - Has a specialized single agent that does all of this: **[Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)**
 
+- **TEA engagement (optional)** - Choose TEA engagement: none, TEA-only (standalone), or integrated by track. See **[Test Architect Guide](./test-architecture.md)**.
+
 ## 🤖 Agents and Collaboration
 
 Complete guide to BMM's AI agent team:

docs/modules/bmm-bmad-method/quick-start.md

@@ -179,6 +179,16 @@ Once epics and stories are created:
 
 **Why run this?** It ensures all your planning assets align properly before you start building.
 
+#### Optional: TEA Engagement
+
+Testing is not mandated by BMad. Decide how you want to engage TEA:
+
+- **No TEA** - Use your existing team testing approach
+- **TEA-only (Standalone)** - Use TEA workflows with your own requirements and environment
+- **TEA-integrated** - Use TEA as part of the BMad Method or Enterprise flow
+
+See the [Test Architect Guide](./test-architecture.md) for the five TEA engagement models and recommended sequences.
+
 #### Context Management Tips
 
 - **Use 200k+ context models** for best results (Claude Sonnet 4.5, GPT-4, etc.)
@@ -211,7 +221,14 @@ Once planning and architecture are complete, you'll move to Phase 4. **Important
 3. Tell the agent: "Run dev-story"
 4. The DEV agent will implement the story and update the sprint status
 
-#### 3.4 Review the Code (Optional but Recommended)
+#### 3.4 Generate Guardrail Tests (Optional)
+
+1. **Start a new chat** with the **TEA agent**
+2. Wait for the menu
+3. Tell the agent: "Run automate"
+4. The TEA agent generates or expands tests to act as guardrails
+
+#### 3.5 Review the Code (Optional but Recommended)
 
 1. **Start a new chat** with the **DEV agent**
 2. Wait for the menu
@@ -224,7 +241,8 @@ For each subsequent story, repeat the cycle using **fresh chats** for each workf
 
 1. **New chat** → SM agent → "Run create-story"
 2. **New chat** → DEV agent → "Run dev-story"
-3. **New chat** → DEV agent → "Run code-review" (optional but recommended)
+3. **New chat** → TEA agent → "Run automate" (optional)
+4. **New chat** → DEV agent → "Run code-review" (optional but recommended)
 
 After completing all stories in an epic:
 

docs/modules/bmm-bmad-method/test-architecture.md

@@ -6,6 +6,38 @@
 - **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project complexity and compliance demands.
 - **Use When:** BMad Method or Enterprise track projects, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required. (Quick Flow projects typically don't require TEA)
 
+## Choose Your TEA Engagement Model
+
+BMad does not mandate TEA. There are five valid ways to use it (or skip it). Pick one intentionally.
+
+1. **No TEA**
+   - Skip all TEA workflows. Use your existing team testing approach.
+
+2. **TEA-only (Standalone)**
+   - Use TEA on a non-BMad project. Bring your own requirements, acceptance criteria, and environments.
+   - Typical sequence: `*test-design` (system or epic) -> `*atdd` and/or `*automate` -> optional `*test-review` -> `*trace` for coverage and gate decisions.
+   - Run `*framework` or `*ci` only if you want TEA to scaffold the harness or pipeline.
+
+3. **Integrated: Greenfield - BMad Method (Simple/Standard Work)**
+   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
+   - Phase 4: per-epic `*test-design`, optional `*atdd`, then `*automate` and optional `*test-review`.
+   - Gate (Phase 2): `*trace`.
+
+4. **Integrated: Brownfield - BMad Method or Enterprise (Simple or Complex)**
+   - Phase 2: baseline `*trace`.
+   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
+   - Phase 4: per-epic `*test-design` focused on regression and integration risks.
+   - Gate (Phase 2): `*trace`; `*nfr-assess` (if not done earlier).
+   - For brownfield BMad Method, follow the same flow with `*nfr-assess` optional.
+
+5. **Integrated: Greenfield - Enterprise Method (Enterprise/Compliance Work)**
+   - Phase 2: `*nfr-assess`.
+   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
+   - Phase 4: per-epic `*test-design`, plus `*atdd`/`*automate`/`*test-review`.
+   - Gate (Phase 2): `*trace`; archive artifacts as needed.
+
+If you are unsure, default to the integrated path for your track and adjust later.
+
 ## TEA Workflow Lifecycle
 
 TEA integrates into the BMad development lifecycle during Solutioning (Phase 3) and Implementation (Phase 4):
@@ -16,6 +48,9 @@ graph TB
     subgraph Phase2["<b>Phase 2: PLANNING</b>"]
         PM["<b>PM: *prd (creates PRD with FRs/NFRs)</b>"]
         PlanNote["<b>Business requirements phase</b>"]
+        NFR2["<b>TEA: *nfr-assess (optional, enterprise)</b>"]
+        PM -.-> NFR2
+        NFR2 -.-> PlanNote
         PM -.-> PlanNote
     end
 
@@ -23,8 +58,8 @@ graph TB
         Architecture["<b>Architect: *architecture</b>"]
         EpicsStories["<b>PM/Architect: *create-epics-and-stories</b>"]
         TestDesignSys["<b>TEA: *test-design (system-level)</b>"]
-        Framework["<b>TEA: *framework</b>"]
+        Framework["<b>TEA: *framework (optional if needed)</b>"]
-        CI["<b>TEA: *ci</b>"]
+        CI["<b>TEA: *ci (optional if needed)</b>"]
         GateCheck["<b>Architect: *implementation-readiness</b>"]
         Architecture --> EpicsStories
         Architecture --> TestDesignSys
@@ -174,7 +209,7 @@ npm install -D @seontechnologies/playwright-utils
 
 **Enable during BMAD installation** by answering "Yes" when prompted.
 
-**Supported utilities (11 total):**
+**Supported utilities (10 total):**
 
 - api-request, network-recorder, auth-session, intercept-network-call, recurse
 - log, file-utils, burn-in, network-error-monitor
@@ -429,7 +464,7 @@ Provides fixture-based utilities that integrate into TEA's test generation and r
 
    Benefit: Faster CI feedback, HTTP error detection
 
-**Utilities available** (11 total): api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
+**Utilities available** (10 total): api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
 
 **Enable during BMAD installation** by answering "Yes" when prompted, or manually set `tea_use_playwright_utils: true` in `_bmad/bmm/config.yaml`.
 

docs/modules/bmm-bmad-method/workflows-implementation.md

@@ -98,8 +98,9 @@ Stories move through these states in the sprint status file:
 
 1. SM runs `create-story`
 2. DEV runs `dev-story`
-3. DEV runs `code-review`
+3. (Optional) TEA runs `*automate` to generate or expand guardrail tests
-4. If code review fails: DEV fixes issues in `dev-story`, then re-runs `code-review`
+4. DEV runs `code-review`
+5. If code review fails: DEV fixes issues in `dev-story`, then re-runs `code-review`
 
 **After Epic Complete:**
 

docs/modules/bmm-bmad-method/workflows-solutioning.md

@@ -434,7 +434,7 @@ Architecture documents are living. Update them as you learn during implementatio
 
 **Key Difference:** Enterprise adds optional extended workflows AFTER architecture but BEFORE create-epics-and-stories. Everything else is identical to BMad Method.
 
-**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](../../../../docs/modules/bmm-bmad-method/test-architecture.md) for TEA's full lifecycle integration.
+**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](./test-architecture.md) for TEA's full lifecycle integration.
 
 ---
 

src/modules/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -336,6 +336,7 @@
       1. Review the comprehensive story in {{story_file}}
       2. Run dev agents `dev-story` for optimized implementation
       3. Run `code-review` when complete (auto-marks done)
+      4. Optional: Run TEA `*automate` after `dev-story` to generate guardrail tests
 
       **The developer now has everything needed for flawless implementation!**
     </output>

src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml

@@ -397,6 +397,7 @@
       - Verify all acceptance criteria are met
       - Ensure deployment readiness if applicable
       - Run `code-review` workflow for peer review
+      - Optional: Run TEA `*automate` to expand guardrail tests
     </action>
 
     <output>💡 **Tip:** For best results, run `code-review` using a **different** LLM than the one that implemented this story.</output>

tools/cli/commands/install-module.js

@@ -0,0 +1,193 @@
+const chalk = require('chalk');
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+const ora = require('ora');
+
+const { Installer } = require('../installers/lib/core/installer');
+const { ModuleManager } = require('../installers/lib/modules/manager');
+const { Manifest } = require('../installers/lib/core/manifest');
+const { ManifestGenerator } = require('../installers/lib/core/manifest-generator');
+
+module.exports = {
+  command: 'install-module <path>',
+  description: 'Install a custom BMAD module from local path',
+  options: [['-f, --force', 'Force reinstall if module already exists']],
+  action: async (modulePath, options) => {
+    const spinner = ora();
+
+    try {
+      // Step 1: Validate module path exists
+      const absolutePath = path.resolve(modulePath);
+      if (!(await fs.pathExists(absolutePath))) {
+        console.error(chalk.red(`Error: Path does not exist: ${absolutePath}`));
+        process.exit(1);
+      }
+
+      const moduleYamlPath = path.join(absolutePath, 'module.yaml');
+      if (!(await fs.pathExists(moduleYamlPath))) {
+        console.error(chalk.red(`Error: Invalid module - module.yaml not found at ${absolutePath}`));
+        process.exit(1);
+      }
+
+      // Read module.yaml to get module code
+      const moduleYamlContent = await fs.readFile(moduleYamlPath, 'utf8');
+      const moduleConfig = yaml.parse(moduleYamlContent);
+      const moduleCode = moduleConfig.code;
+
+      if (!moduleCode) {
+        console.error(chalk.red('Error: module.yaml must have a "code" field'));
+        process.exit(1);
+      }
+
+      console.log(chalk.cyan(`\n📦 Installing module: ${moduleConfig.name || moduleCode}`));
+      if (moduleConfig.version) {
+        console.log(chalk.dim(`   Version: ${moduleConfig.version}`));
+      }
+
+      // Step 2: Find BMAD installation
+      const installer = new Installer();
+      const { bmadDir } = await installer.findBmadDir(process.cwd());
+
+      // Check if manifest exists (confirms BMAD is actually installed)
+      const manifest = new Manifest();
+      const manifestData = await manifest.read(bmadDir);
+
+      if (!manifestData) {
+        console.error(chalk.red('\nError: No BMAD installation found.'));
+        console.log(chalk.yellow('Run `npx bmad-method install` first to set up BMAD.'));
+        process.exit(1);
+      }
+
+      console.log(chalk.green(`✓ Found BMAD installation at ${bmadDir}`));
+
+      // Step 3: Check if already installed
+      if (manifestData.modules && manifestData.modules.includes(moduleCode) && !options.force) {
+        console.error(chalk.red(`\nError: Module '${moduleCode}' is already installed.`));
+        console.log(chalk.yellow('Use --force to reinstall.'));
+        process.exit(1);
+      }
+
+      // Step 4: Install module using ModuleManager
+      spinner.start('Installing module files...');
+
+      const moduleManager = new ModuleManager();
+      moduleManager.setCustomModulePaths(new Map([[moduleCode, absolutePath]]));
+      moduleManager.setBmadFolderName(path.basename(bmadDir));
+
+      await moduleManager.install(moduleCode, bmadDir, null, {
+        skipModuleInstaller: false,
+        moduleConfig: moduleConfig,
+      });
+
+      spinner.succeed('Module files installed');
+
+      // Step 5: Regenerate manifests
+      spinner.start('Regenerating manifests...');
+
+      const manifestGen = new ManifestGenerator();
+      // Get all modules including the new one
+      const allModules = [...(manifestData.modules || [])];
+      if (!allModules.includes(moduleCode)) {
+        allModules.push(moduleCode);
+      }
+
+      await manifestGen.generateManifests(bmadDir, allModules, [], {
+        ides: manifestData.ides || [],
+      });
+
+      spinner.succeed('Manifests regenerated');
+
+      // Step 6: Regenerate IDE commands
+      const projectDir = path.dirname(bmadDir);
+      const installedIDEs = manifestData.ides || [];
+
+      if (installedIDEs.includes('claude-code')) {
+        spinner.start('Generating Claude Code commands...');
+
+        const { WorkflowCommandGenerator } = require('../installers/lib/ide/shared/workflow-command-generator');
+        const { AgentCommandGenerator } = require('../installers/lib/ide/shared/agent-command-generator');
+        const { TaskToolCommandGenerator } = require('../installers/lib/ide/shared/task-tool-command-generator');
+
+        const bmadFolderName = path.basename(bmadDir);
+        const bmadCommandsDir = path.join(projectDir, '.claude', 'commands', 'bmad');
+
+        // Generate agent launchers
+        const agentGen = new AgentCommandGenerator(bmadFolderName);
+        const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, allModules);
+
+        // Create module directories
+        await fs.ensureDir(path.join(bmadCommandsDir, moduleCode, 'agents'));
+        await fs.ensureDir(path.join(bmadCommandsDir, moduleCode, 'workflows'));
+
+        // Write agent launchers
+        await agentGen.writeAgentLaunchers(bmadCommandsDir, agentArtifacts);
+
+        // Generate workflow commands
+        const wfGen = new WorkflowCommandGenerator(bmadFolderName);
+        const { artifacts: workflowArtifacts } = await wfGen.collectWorkflowArtifacts(bmadDir);
+
+        // Write workflow commands
+        for (const artifact of workflowArtifacts) {
+          if (artifact.type === 'workflow-command') {
+            const moduleWorkflowsDir = path.join(bmadCommandsDir, artifact.module, 'workflows');
+            await fs.ensureDir(moduleWorkflowsDir);
+            const commandPath = path.join(moduleWorkflowsDir, path.basename(artifact.relativePath));
+            await fs.writeFile(commandPath, artifact.content);
+          }
+        }
+
+        // Generate task/tool commands
+        const taskGen = new TaskToolCommandGenerator();
+        await taskGen.generateTaskToolCommands(projectDir, bmadDir);
+
+        spinner.succeed('Claude Code commands generated');
+      }
+
+      // Step 7: Update manifest
+      await manifest.addModule(bmadDir, moduleCode);
+
+      // Success message
+      console.log(chalk.green(`\n✨ Module '${moduleCode}' installed successfully!`));
+
+      // Show available commands
+      const commandsDir = path.join(projectDir, '.claude', 'commands', 'bmad', moduleCode);
+      if (await fs.pathExists(commandsDir)) {
+        console.log(chalk.cyan('\nAvailable commands:'));
+
+        const agentsDir = path.join(commandsDir, 'agents');
+        const workflowsDir = path.join(commandsDir, 'workflows');
+
+        if (await fs.pathExists(agentsDir)) {
+          const agents = await fs.readdir(agentsDir);
+          for (const agent of agents.filter((f) => f.endsWith('.md') && f !== 'README.md')) {
+            console.log(chalk.dim(`  /${moduleCode}:${path.basename(agent, '.md')}`));
+          }
+        }
+
+        if (await fs.pathExists(workflowsDir)) {
+          const workflows = await fs.readdir(workflowsDir);
+          for (const wf of workflows.filter((f) => f.endsWith('.md') && f !== 'README.md')) {
+            console.log(chalk.dim(`  /${moduleCode}:${path.basename(wf, '.md')}`));
+          }
+        }
+      }
+
+      process.exit(0);
+    } catch (error) {
+      spinner.fail('Installation failed');
+
+      if (error.fullMessage) {
+        console.error(error.fullMessage);
+      } else {
+        console.error(chalk.red('Error:'), error.message);
+      }
+
+      if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+        console.error(chalk.dim(error.stack));
+      }
+
+      process.exit(1);
+    }
+  },
+};