ma-agents 3.5.3 → 3.5.5

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-04c-aggregate.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-04c-aggregate'
 description: 'Aggregate subagent outputs and complete ATDD test infrastructure'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 nextStepFile: './step-05-validate-and-complete.md'
 ---
 
@@ -9,7 +9,7 @@ nextStepFile: './step-05-validate-and-complete.md'
 
 ## STEP GOAL
 
-Read outputs from parallel subagents (API + E2E failing test generation), aggregate results, verify TDD red phase compliance, and create supporting infrastructure.
+Read outputs from parallel subagents (API + E2E red-phase test generation), aggregate results, verify TDD red phase compliance, and create supporting infrastructure.
 
 ---
 
@@ -22,7 +22,7 @@ Read outputs from parallel subagents (API + E2E failing test generation), aggreg
 - ✅ Generate shared fixtures based on fixture needs
 - ✅ Write all generated test files to disk
 - ❌ Do NOT remove test.skip() (that's done after feature implementation)
-- ❌ Do NOT run tests yet (that's step 5 - verify they fail)
+- ❌ Do NOT run tests yet (that's step 5 - verify scaffolds and optional RED activation)
 
 ---
 
@@ -187,7 +187,7 @@ Note: More complete fixtures will be needed when moving to green phase.
 
 ## TDD Red Phase (Current)
 
-✅ Failing tests generated
+✅ Red-phase test scaffolds generated
 
 - API Tests: {api_test_count} tests (all skipped)
 - E2E Tests: {e2e_test_count} tests (all skipped)
@@ -196,14 +196,14 @@ Note: More complete fixtures will be needed when moving to green phase.
 
 {list all acceptance criteria with test coverage}
 
-## Next Steps (TDD Green Phase)
+## Next Steps (Task-by-Task Activation)
 
-After implementing the feature:
+During implementation of each task:
 
-1. Remove `test.skip()` from all test files
+1. Remove `test.skip()` from the current test file or scenario
 2. Run tests: `npm test`
-3. Verify tests PASS (green phase)
-4. If any tests fail:
+3. Verify the activated test fails first, then passes after implementation (green phase)
+4. If any activated tests still fail unexpectedly:
    - Either fix implementation (feature bug)
    - Or fix test (test bug)
 5. Commit passing tests
@@ -220,9 +220,21 @@ UI components to implement:
 **Save checklist:**
 
 ```javascript
-fs.writeFileSync(`{test_artifacts}/atdd-checklist-{story-id}.md`, checklistContent, 'utf8');
+fs.writeFileSync(`{test_artifacts}/atdd-checklist-{story_key}.md`, checklistContent, 'utf8');
 ```
 
+**If `{story_file}` exists and is writable, attempt to link artifacts back into the story:**
+
+- Add or update a `### ATDD Artifacts` subsection under `## Dev Notes`
+- Record:
+  - `Checklist: {test_artifacts}/atdd-checklist-{story_key}.md`
+  - `API tests: {api_test_file_path}` when present
+  - `E2E tests: {e2e_test_file_path}` when present
+  - `Component tests: {component_test_file_path}` when present
+- Preserve all other story content verbatim
+- The checklist template already contains the manual handoff instructions if story linking is not possible
+- If the story file cannot be updated safely, continue without failing the workflow and keep the checklist's manual handoff instructions intact
+
 ---
 
 ### 7. Calculate Summary Statistics
@@ -279,14 +291,14 @@ Display to user:
 ```
 ✅ ATDD Test Generation Complete (TDD RED PHASE)
 
-🔴 TDD Red Phase: Failing Tests Generated
+🔴 TDD Red Phase: Test Scaffolds Generated
 
 📊 Summary:
 - Total Tests: {total_tests} (all with test.skip())
   - API Tests: {api_tests} (RED)
   - E2E Tests: {e2e_tests} (RED)
 - Fixtures Created: {fixtures_created}
-- All tests will FAIL until feature implemented
+- Activated tests will FAIL until feature is implemented
 
 ✅ Acceptance Criteria Coverage:
 {list all covered criteria}
@@ -297,15 +309,16 @@ Display to user:
 - tests/api/[feature].spec.ts (with test.skip())
 - tests/e2e/[feature].spec.ts (with test.skip())
 - tests/fixtures/test-data.ts
-- {test_artifacts}/atdd-checklist-{story-id}.md
+- {test_artifacts}/atdd-checklist-{story_key}.md
 
 📝 Next Steps:
-1. Implement the feature
-2. Remove test.skip() from tests
-3. Run tests → verify PASS (green phase)
-4. Commit passing tests
+1. Link ATDD artifacts into the story file if available
+2. Implement the feature
+3. Remove test.skip() from the tests for the current task
+4. Run activated tests → verify they FAIL before implementation, then PASS after implementation
+5. Commit passing tests
 
-✅ Ready for validation (Step 5 - verify tests fail as expected)
+✅ Ready for validation (Step 5 - verify red-phase scaffolds and handoff metadata)
 ```
 
 ---
@@ -334,6 +347,11 @@ Proceed to Step 5 when:
   stepsCompleted: ['step-04c-aggregate']
   lastStep: 'step-04c-aggregate'
   lastSaved: '{date}'
+  storyId: '{story_id}'
+  storyKey: '{story_key}'
+  storyFile: '{story_file}'
+  atddChecklistPath: '{outputFile}'
+  generatedTestFiles: []
   ---
   ```
 
@@ -343,6 +361,11 @@ Proceed to Step 5 when:
   - Add `'step-04c-aggregate'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-04c-aggregate'`
   - Set `lastSaved: '{date}'`
+  - Set `storyId` to `{story_id}`
+  - Set `storyKey` to `{story_key}`
+  - Set `storyFile` to `{story_file}`
+  - Set `atddChecklistPath` to `{outputFile}`
+  - Set `generatedTestFiles` deterministically to the list of present test paths in this order: API, E2E, Component (omit blanks / N/A values)
   - Append this step's output to the appropriate section.
 
 Load next step: `{nextStepFile}`
@@ -358,6 +381,7 @@ Load next step: `{nextStepFile}`
 - All tests assert expected behavior (not placeholders)
 - All test files written to disk
 - ATDD checklist generated
+- Story metadata and handoff paths captured in checklist frontmatter
 
 ### ❌ SYSTEM FAILURE:
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-05-validate-and-complete.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-05-validate-and-complete'
 description: 'Validate ATDD outputs and summarize'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 ---
 
 # Step 5: Validate & Complete
@@ -42,7 +42,8 @@ Use `checklist.md` to validate:
 - Prerequisites satisfied
 - Test files created correctly
 - Checklist matches acceptance criteria
-- Tests are designed to fail before implementation
+- Tests are generated as red-phase scaffolds and marked with `test.skip()`
+- Story metadata and handoff paths are captured for downstream workflows
 - [ ] CLI sessions cleaned up (no orphaned browsers)
 - [ ] Temp artifacts stored in `{test_artifacts}/` not random locations
 
@@ -67,8 +68,9 @@ Report:
 
 - Test files created
 - Checklist output path
+- Story key / story file handoff path
 - Key risks or assumptions
-- Next recommended workflow (e.g., implementation or `automate`)
+- Next recommended workflow (usually `dev-story`; `automate` comes after implementation)
 
 ---
 
@@ -83,6 +85,11 @@ Report:
   stepsCompleted: ['step-05-validate-and-complete']
   lastStep: 'step-05-validate-and-complete'
   lastSaved: '{date}'
+  storyId: '{story_id}'
+  storyKey: '{story_key}'
+  storyFile: '{story_file}'
+  atddChecklistPath: '{outputFile}'
+  generatedTestFiles: []
   ---
   ```
 
@@ -92,6 +99,8 @@ Report:
   - Add `'step-05-validate-and-complete'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-05-validate-and-complete'`
   - Set `lastSaved: '{date}'`
+  - Ensure `storyId`, `storyKey`, `storyFile`, and `atddChecklistPath` are present and populated
+  - Ensure `generatedTestFiles` remains populated with the deterministic list of present generated test paths
   - Append this step's output to the appropriate section.
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS:

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/workflow-plan.md

@@ -16,6 +16,6 @@
   - step-02-apply-edit.md
 
   ## Outputs
-  - {test_artifacts}/atdd-checklist-{story_id}.md
+  - {test_artifacts}/atdd-checklist-{story_key}.md
 
-- Failing acceptance tests under {project-root}/tests
+- Red-phase acceptance test scaffolds under {project-root}/tests

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/workflow.md

@@ -1,12 +1,12 @@
 ---
 name: bmad-testarch-atdd
-description: Generate failing acceptance tests using TDD cycle. Use when user says 'lets write acceptance tests' or 'I want to do ATDD'
+description: Generate red-phase acceptance test scaffolds using TDD cycle. Use when user says 'lets write acceptance tests' or 'I want to do ATDD'
 web_bundle: true
 ---
 
 # Acceptance Test-Driven Development (ATDD)
 
-**Goal:** Generate failing acceptance tests before implementation using TDD red-green-refactor cycle
+**Goal:** Generate red-phase acceptance test scaffolds before implementation using TDD red-green-refactor cycle
 
 **Role:** You are the Master Test Architect.
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/workflow.yaml

@@ -1,7 +1,7 @@
 # Test Architect workflow: bmad-testarch-atdd
 name: bmad-testarch-atdd
 # prettier-ignore
-description: 'Generate failing acceptance tests using TDD cycle. Use when the user says "lets write acceptance tests" or "I want to do ATDD"'
+description: 'Generate red-phase acceptance test scaffolds using TDD cycle. Use when the user says "lets write acceptance tests" or "I want to do ATDD"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/tea/config.yaml"
@@ -23,7 +23,7 @@ variables:
   test_dir: "{project-root}/tests" # Root test directory
 
 # Output configuration
-default_output_file: "{test_artifacts}/atdd-checklist-{story_id}.md"
+default_output_file: "{test_artifacts}/atdd-checklist-{story_key}.md"
 
 # Required tools
 required_tools:

package/lib/bmad.js

@@ -4,6 +4,27 @@ const os = require('os');
 const { execSync } = require('child_process');
 const chalk = require('chalk');
 const yaml = require('yaml');
+const { withExperimentalWarningSuppressed } = require('./warning-filter');
+
+/**
+ * Build the env object passed to the bmad-method child spawn.
+ * Extends parent env with GIT_TERMINAL_PROMPT=0 and a NODE_OPTIONS
+ * value that silences the ExperimentalWarning about CJS require() of
+ * an ES Module (Bug A). Callers that need a different NODE_OPTIONS
+ * can merge after this call.
+ *
+ * @param {NodeJS.ProcessEnv} [parentEnv=process.env]
+ * @returns {NodeJS.ProcessEnv}
+ */
+function buildChildSpawnEnv(parentEnv = process.env) {
+    return {
+        ...parentEnv,
+        GIT_TERMINAL_PROMPT: '0',
+        // Bug A — keep the bmad-method child as quiet about CJS-require-ESM
+        // as the parent. Preserves any NODE_OPTIONS the user already set.
+        NODE_OPTIONS: withExperimentalWarningSuppressed(parentEnv.NODE_OPTIONS),
+    };
+}
 
 const BMAD_DIR = '_bmad';
 const CONFIG_DIR = path.join(BMAD_DIR, '_config', 'agents');
@@ -122,7 +143,7 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
         await deployMethodology(projectRoot, force);
         return true;
     } catch (error) {
@@ -157,7 +178,7 @@ async function runMigration(modules, tools, projectRoot, force, { userName, comm
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
     } catch (error) {
         // Rollback on failure
         console.error(chalk.red(`  BMAD update failed: ${error.message}`));
@@ -284,7 +305,7 @@ async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = pr
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
         await deployMethodology(projectRoot, force);
         return true;
     } catch (error) {
@@ -361,7 +382,7 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
     } catch (error) {
         console.error(chalk.red(`  BMAD recompile failed: ${error.message}`));
     }

package/lib/installer.js

@@ -5,7 +5,7 @@ const prompts = require('prompts');
 const { getAgent, getAllAgents } = require('./agents');
 
 const MANIFEST_FILE = '.ma-agents.json';
-const MANIFEST_VERSION = '1.1.0';
+const MANIFEST_VERSION = '1.2.0';
 const MA_AGENTS_SOURCE = 'ma-agents';
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'project-context.template.md');
 
@@ -1053,6 +1053,7 @@ module.exports = {
   uninstallSkill,
   getStatus,
   readManifest,
+  ensureManifest,
   getInstalledSkillInfo,
   getManifestAgents,
   compareSemver,

package/lib/methodology/version.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "BMAD-METHOD AI Development Training Presentation",
   "files": [
     "BMAD_AI_Development_Training.pptx"

package/lib/profile.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * Story 21.1 — Install-time profile persistence and resolution.
+ *
+ * Public API (exactly three functions):
+ *   getProfile(projectRoot)                  -> "on-prem" | "standard" | undefined
+ *   setProfile(projectRoot, value)           -> void (persists to .ma-agents.json)
+ *   resolveProfile({ persisted, yesMode })   -> resolved value | null (pure, no I/O)
+ *
+ * NFR44: setProfile is the ONLY mutator of the "profile" field.
+ * Back-compat: manifests at 1.1.0 without "profile" are read without error;
+ *              getProfile returns undefined for missing field.
+ *              setProfile migrates 1.1.0 → 1.2.0 on write (profile field is
+ *              1.2.0-only; writing it onto a 1.1.0 manifest would be schema drift).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_FILE = '.ma-agents.json';
+const VALID_PROFILES = ['on-prem', 'standard'];
+
+/**
+ * Reads the persisted profile from .ma-agents.json at the given project root.
+ * Returns undefined if the file does not exist, is malformed, or the "profile"
+ * field is absent. Does NOT throw on missing file.
+ */
+function getProfile(projectRoot) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) {
+    return undefined;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+  if (!manifest || typeof manifest !== 'object') return undefined;
+  if (!Object.prototype.hasOwnProperty.call(manifest, 'profile')) return undefined;
+  return manifest.profile;
+}
+
+/**
+ * Persists the profile value into .ma-agents.json, preserving all other fields.
+ * Creates the file via the standard ensureManifest bootstrap path if absent.
+ * Throws an Error naming the bad value if `value` is not "on-prem" or "standard".
+ *
+ * Migration: If the loaded manifest is at manifestVersion 1.1.0 (or missing the
+ * version field entirely), setProfile bumps it to 1.2.0 before writing, because
+ * the "profile" field is 1.2.0-only. A one-time log line is emitted to stdout
+ * describing the migration. Manifests already at 1.2.0 or higher are left alone.
+ */
+function setProfile(projectRoot, value) {
+  if (!VALID_PROFILES.includes(value)) {
+    throw new Error(
+      `Invalid profile value: ${JSON.stringify(value)}. Expected one of: ${VALID_PROFILES.join(', ')}`
+    );
+  }
+
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+
+  let manifest;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = null;
+    }
+  }
+
+  if (!manifest || typeof manifest !== 'object') {
+    // Bootstrap via the standard schema (mirrors lib/installer.js ensureManifest shape).
+    // Require lazily to avoid potential circular-import pitfalls at module load.
+    const { ensureManifest } = require('./installer');
+    manifest = ensureManifest(projectRoot, null, 'project');
+  }
+
+  // Migrate 1.1.0 (or missing version) → 1.2.0, since the "profile" field is 1.2.0-only.
+  // Writing it onto a 1.1.0 manifest would be schema drift. Do not downgrade manifests
+  // that are already at 1.2.0 or higher.
+  const currentVersion = manifest.manifestVersion;
+  if (currentVersion === '1.1.0') {
+    manifest.manifestVersion = '1.2.0';
+    console.log('Migrated .ma-agents.json manifestVersion 1.1.0 → 1.2.0');
+  } else if (!currentVersion) {
+    manifest.manifestVersion = '1.2.0';
+    console.log('Migrated .ma-agents.json manifestVersion (none) → 1.2.0');
+  }
+
+  manifest.profile = value;
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Pure resolver — performs NO I/O.
+ * Precedence: persisted > (yesMode ? 'standard' : null).
+ * Returns null when nothing is set and yesMode is false (caller must prompt).
+ */
+function resolveProfile({ persisted, yesMode } = {}) {
+  if (persisted) return persisted;
+  if (yesMode === true) return 'standard';
+  return null;
+}
+
+module.exports = { getProfile, setProfile, resolveProfile };