feat: issue 2243

package-lock.json

@@ -15,7 +15,6 @@
         "chalk": "^4.1.2",
         "commander": "^14.0.0",
         "csv-parse": "^6.1.0",
-        "fs-extra": "^11.3.0",
         "glob": "^11.0.3",
         "ignore": "^7.0.5",
         "js-yaml": "^4.1.0",
@@ -25,8 +24,8 @@
         "yaml": "^2.7.0"
       },
       "bin": {
-        "bmad": "tools/bmad-npx-wrapper.js",
+        "bmad": "tools/installer/bmad-cli.js",
-        "bmad-method": "tools/bmad-npx-wrapper.js"
+        "bmad-method": "tools/installer/bmad-cli.js"
       },
       "devDependencies": {
         "@astrojs/sitemap": "^3.6.0",
@@ -46,6 +45,7 @@
         "prettier": "^3.7.4",
         "prettier-plugin-packagejson": "^2.5.19",
         "sharp": "^0.33.5",
+        "unist-util-visit": "^5.1.0",
         "yaml-eslint-parser": "^1.2.3",
         "yaml-lint": "^1.7.0"
       },
@@ -6975,20 +6975,6 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/fs-extra": {
-      "version": "11.3.3",
-      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.3.tgz",
-      "integrity": "sha512-VWSRii4t0AFm6ixFFmLLx1t7wS1gh+ckoa84aOeapGum0h+EZd1EhEumSB+ZdDLnEPuucsVB9oB7cxJHap6Afg==",
-      "license": "MIT",
-      "dependencies": {
-        "graceful-fs": "^4.2.0",
-        "jsonfile": "^6.0.1",
-        "universalify": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=14.14"
-      }
-    },
     "node_modules/fs.realpath": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
@@ -7227,6 +7213,7 @@
       "version": "4.2.11",
       "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
       "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
+      "dev": true,
       "license": "ISC"
     },
     "node_modules/h3": {
@@ -9066,18 +9053,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/jsonfile": {
-      "version": "6.2.0",
-      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.0.tgz",
-      "integrity": "sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg==",
-      "license": "MIT",
-      "dependencies": {
-        "universalify": "^2.0.0"
-      },
-      "optionalDependencies": {
-        "graceful-fs": "^4.1.6"
-      }
-    },
     "node_modules/katex": {
       "version": "0.16.28",
       "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.28.tgz",
@@ -13607,15 +13582,6 @@
         "url": "https://opencollective.com/unified"
       }
     },
-    "node_modules/universalify": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
-      "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 10.0.0"
-      }
-    },
     "node_modules/unrs-resolver": {
       "version": "1.11.1",
       "resolved": "https://registry.npmjs.org/unrs-resolver/-/unrs-resolver-1.11.1.tgz",

src/bmm-skills/4-implementation/bmad-create-story/template.md

@@ -2,7 +2,7 @@
 
 Status: ready-for-dev
 
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. If TEA is installed, ATDD can run after validation and before dev-story. -->
 
 ## Story
 
@@ -32,6 +32,13 @@ so that {{benefit}}.
 - Alignment with unified project structure (paths, modules, naming)
 - Detected conflicts or variances (with rationale)
 
+### ATDD Artifacts (Optional)
+
+- Populate with `/bmad:tea:atdd` outputs when available
+- Checklist path
+- Generated API/E2E/component test paths
+- Activation guidance for scaffolded tests (for example, remove `test.skip()` per task)
+
 ### References
 
 - Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]

src/bmm-skills/4-implementation/bmad-create-story/workflow.md

@@ -369,9 +369,10 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
     **Next Steps:**
     1. Review the comprehensive story in {{story_file}}
-    2. Run dev agents `dev-story` for optimized implementation
+    2. Optional: If Test Architect module installed, run `/bmad:tea:atdd` after validation and before `dev-story` to generate red-phase acceptance test scaffolds and link them into Dev Notes
-    3. Run `code-review` when complete (auto-marks done)
+    3. Run dev agents `dev-story` for optimized implementation (it will consume ATDD artifacts from Dev Notes when present)
-    4. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `dev-story` to generate guardrail tests
+    4. Run `code-review` when complete (auto-marks done)
+    5. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `dev-story` to generate guardrail tests
 
     **The developer now has everything needed for flawless implementation!**
   </output>

src/bmm-skills/4-implementation/bmad-dev-story/checklist.md

@@ -11,9 +11,11 @@ optional-inputs:
   - 'Test results output'
   - 'CI logs'
   - 'Linting reports'
+  - 'TEA ATDD checklist and generated test artifact references from story Dev Notes'
 validation-rules:
   - 'Only permitted story sections modified: Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, Status'
   - 'All implementation requirements from story Dev Notes must be satisfied'
+  - 'When TEA ATDD artifacts are present, activate or extend them instead of duplicating the same acceptance coverage'
   - 'Definition of Done checklist must pass completely'
   - 'Enhanced story context must contain sufficient technical guidance'
 ---
@@ -43,6 +45,7 @@ validation-rules:
 - [ ] **Integration Tests:** Integration tests added/updated for component interactions when story requirements demand them
 - [ ] **End-to-End Tests:** End-to-end tests created for critical user flows when story requirements specify them
 - [ ] **Test Coverage:** Tests cover acceptance criteria and edge cases from story Dev Notes
+- [ ] **ATDD Artifact Consumption:** If story Dev Notes reference TEA ATDD outputs, relevant scaffold tests were activated or extended for the implemented tasks
 - [ ] **Regression Prevention:** ALL existing tests pass (no regressions introduced)
 - [ ] **Code Quality:** Linting and static checks pass when configured in project
 - [ ] **Test Framework Compliance:** Tests use project's testing frameworks and patterns from Dev Notes

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

@@ -161,6 +161,11 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
     <action>Load comprehensive context from story file's Dev Notes section</action>
     <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Initialize {{atdd_artifacts}} = empty</action>
+    <action>Check Dev Notes for optional "ATDD Artifacts" subsection and any TEA checklist/test references under References</action>
+    <action>If ATDD artifacts are referenced, capture checklist path, generated API/E2E/component test paths, and activation guidance as {{atdd_artifacts}}</action>
+    <action if="ATDD checklist path exists and file is accessible">Load the referenced ATDD checklist and extract generated test inventory, story metadata, and implementation guidance relevant to the current tasks</action>
+    <action if="ATDD artifacts are referenced but linked files are missing">Record the missing ATDD artifact paths in Dev Agent Record → Completion Notes and continue with standard test-first implementation</action>
     <action>Use enhanced story context to inform implementation decisions and approaches</action>
 
     <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
@@ -179,6 +184,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
     <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
     <action>Load comprehensive context from story file's Dev Notes section</action>
     <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Use any loaded TEA ATDD checklist or artifact references to understand pre-generated acceptance coverage before implementation begins</action>
     <action>Use enhanced story context to inform implementation decisions and approaches</action>
     <output>✅ **Context Loaded**
       Story and project context available for implementation
@@ -267,8 +273,16 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
     <action>Plan implementation following red-green-refactor cycle</action>
 
     <!-- RED PHASE -->
-    <action>Write FAILING tests first for the task/subtask functionality</action>
+    <check if="{{atdd_artifacts}} contains relevant tests for the current task or acceptance criteria">
-    <action>Confirm tests fail before implementation - this validates test correctness</action>
+      <action>Identify the pre-generated ATDD scaffold test files covering the current task/subtask</action>
+      <action>Activate only the relevant scaffold tests by removing `test.skip()` for the current task; preserve unrelated scaffolds as skipped</action>
+      <action>Run the activated tests and confirm they fail before implementation - this validates the pre-generated acceptance coverage</action>
+      <action>Author additional failing tests only if ATDD coverage is missing for the current task/subtask</action>
+    </check>
+    <check if="{{atdd_artifacts}} is empty OR no relevant ATDD tests exist for the current task or acceptance criteria">
+      <action>Write FAILING tests first for the task/subtask functionality</action>
+      <action>Confirm tests fail before implementation - this validates test correctness</action>
+    </check>
 
     <!-- GREEN PHASE -->
     <action>Implement MINIMAL code to make tests pass</action>
@@ -295,6 +309,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
     <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
     <action>Add integration tests for component interactions specified in story requirements</action>
     <action>Include end-to-end tests for critical user flows when story requirements demand them</action>
+    <action>If TEA ATDD artifacts exist, preserve and extend those tests instead of duplicating the same acceptance coverage in new files</action>
     <action>Cover edge cases and error handling scenarios identified in story Dev Notes</action>
   </step>
 
@@ -335,7 +350,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
     <!-- ONLY MARK COMPLETE IF ALL VALIDATION PASS -->
     <check if="ALL validation gates pass AND tests ACTUALLY exist and pass">
       <action>ONLY THEN mark the task (and subtasks) checkbox with [x]</action>
-      <action>Update File List section with ALL new, modified, or deleted files (paths relative to repo root)</action>
+      <action>Update File List section with ALL new, modified, or deleted files (paths relative to repo root), including any activated or extended ATDD test files</action>
       <action>Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested</action>
     </check>
 
@@ -437,7 +452,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       - Verify all acceptance criteria are met
       - Ensure deployment readiness if applicable
       - Run `code-review` workflow for peer review
-      - Optional: If Test Architect module installed, run `/bmad:tea:automate` to expand guardrail tests
+      - Optional: If Test Architect module installed and `atdd` was not used earlier, use `/bmad:tea:atdd` before future `dev-story` runs; use `/bmad:tea:automate` after implementation 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>

src/bmm-skills/module-help.csv

@@ -25,8 +25,8 @@ BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,I
 BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,4-implementation,,,true,implementation_artifacts,sprint status
 BMad Method,bmad-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,4-implementation,bmad-sprint-planning,,false,,
 BMad Method,bmad-create-story,Create Story,CS,"Story cycle start: Prepare first found story in the sprint plan that is next or a specific epic/story designation.",create,,4-implementation,bmad-sprint-planning,bmad-create-story:validate,true,implementation_artifacts,story
-BMad Method,bmad-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins.,validate,,4-implementation,bmad-create-story:create,bmad-dev-story,false,implementation_artifacts,story validation report
+BMad Method,bmad-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins. If Test Architect is installed, ATDD can optionally run after validation and before development.,validate,,4-implementation,bmad-create-story:create,bmad-dev-story,false,implementation_artifacts,story validation report
-BMad Method,bmad-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed.,,4-implementation,bmad-create-story:validate,,true,,
+BMad Method,bmad-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests, consuming optional ATDD artifacts from Dev Notes when present, then CR then back to DS if fixes needed.,,4-implementation,bmad-create-story:validate,,true,,
 BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if approved then next CS or ER if epic complete.,,4-implementation,bmad-dev-story,,false,,
 BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,4-implementation,,,false,,
 BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,4-implementation,bmad-dev-story,,false,implementation_artifacts,test suite