ma-agents 2.19.2 → 2.20.0

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

@@ -0,0 +1,370 @@
+---
+name: 'step-04c-aggregate'
+description: 'Aggregate subagent outputs and complete ATDD test infrastructure'
+outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+nextStepFile: './step-05-validate-and-complete.md'
+---
+
+# Step 4C: Aggregate ATDD Test Generation Results
+
+## STEP GOAL
+
+Read outputs from parallel subagents (API + E2E failing test generation), aggregate results, verify TDD red phase compliance, and create supporting infrastructure.
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Read subagent outputs from temp files
+- ✅ Verify all tests are marked with test.skip() (TDD red phase)
+- ✅ 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)
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, subagent outputs from temp files
+- Focus: aggregation and TDD validation
+- Limits: do not execute future steps
+- Dependencies: Step 4A and 4B subagent outputs
+
+---
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Read Subagent Outputs
+
+**Read API test subagent output:**
+
+```javascript
+const apiTestsPath = '/tmp/tea-atdd-api-tests-{{timestamp}}.json';
+const apiTestsOutput = JSON.parse(fs.readFileSync(apiTestsPath, 'utf8'));
+```
+
+**Read E2E test subagent output:**
+
+```javascript
+const e2eTestsPath = '/tmp/tea-atdd-e2e-tests-{{timestamp}}.json';
+const e2eTestsOutput = JSON.parse(fs.readFileSync(e2eTestsPath, 'utf8'));
+```
+
+**Verify both subagents succeeded:**
+
+- Check `apiTestsOutput.success === true`
+- Check `e2eTestsOutput.success === true`
+- If either failed, report error and stop (don't proceed)
+
+---
+
+### 2. Verify TDD Red Phase Compliance
+
+**CRITICAL TDD Validation:**
+
+**Check API tests:**
+
+```javascript
+apiTestsOutput.tests.forEach((test) => {
+  // Verify test.skip() is present
+  if (!test.content.includes('test.skip(')) {
+    throw new Error(`ATDD ERROR: ${test.file} missing test.skip() - tests MUST be skipped in red phase!`);
+  }
+
+  // Verify not placeholder assertions
+  if (test.content.includes('expect(true).toBe(true)')) {
+    throw new Error(`ATDD ERROR: ${test.file} has placeholder assertions - must assert EXPECTED behavior!`);
+  }
+
+  // Verify expected_to_fail flag
+  if (!test.expected_to_fail) {
+    throw new Error(`ATDD ERROR: ${test.file} not marked as expected_to_fail!`);
+  }
+});
+```
+
+**Check E2E tests:**
+
+```javascript
+e2eTestsOutput.tests.forEach((test) => {
+  // Same validation as API tests
+  if (!test.content.includes('test.skip(')) {
+    throw new Error(`ATDD ERROR: ${test.file} missing test.skip() - tests MUST be skipped in red phase!`);
+  }
+
+  if (test.content.includes('expect(true).toBe(true)')) {
+    throw new Error(`ATDD ERROR: ${test.file} has placeholder assertions!`);
+  }
+
+  if (!test.expected_to_fail) {
+    throw new Error(`ATDD ERROR: ${test.file} not marked as expected_to_fail!`);
+  }
+});
+```
+
+**If validation passes:**
+
+```
+✅ TDD Red Phase Validation: PASS
+- All tests use test.skip()
+- All tests assert expected behavior (not placeholders)
+- All tests marked as expected_to_fail
+```
+
+---
+
+### 3. Write All Test Files to Disk
+
+**Write API test files:**
+
+```javascript
+apiTestsOutput.tests.forEach((test) => {
+  fs.writeFileSync(test.file, test.content, 'utf8');
+  console.log(`✅ Created (RED): ${test.file}`);
+});
+```
+
+**Write E2E test files:**
+
+```javascript
+e2eTestsOutput.tests.forEach((test) => {
+  fs.writeFileSync(test.file, test.content, 'utf8');
+  console.log(`✅ Created (RED): ${test.file}`);
+});
+```
+
+---
+
+### 4. Aggregate Fixture Needs
+
+**Collect all fixture needs from both subagents:**
+
+```javascript
+const allFixtureNeeds = [...apiTestsOutput.fixture_needs, ...e2eTestsOutput.fixture_needs];
+
+// Remove duplicates
+const uniqueFixtures = [...new Set(allFixtureNeeds)];
+```
+
+---
+
+### 5. Generate Fixture Infrastructure
+
+**Create fixtures needed by ATDD tests:**
+(Similar to automate workflow, but may be simpler for ATDD since feature not implemented)
+
+**Minimal fixtures for TDD red phase:**
+
+```typescript
+// tests/fixtures/test-data.ts
+export const testUserData = {
+  email: 'test@example.com',
+  password: 'SecurePass123!',
+};
+```
+
+Note: More complete fixtures will be needed when moving to green phase.
+
+---
+
+### 6. Generate ATDD Checklist
+
+**Create ATDD checklist document:**
+
+```markdown
+# ATDD Checklist: [Story Name]
+
+## TDD Red Phase (Current)
+
+✅ Failing tests generated
+
+- API Tests: {api_test_count} tests (all skipped)
+- E2E Tests: {e2e_test_count} tests (all skipped)
+
+## Acceptance Criteria Coverage
+
+{list all acceptance criteria with test coverage}
+
+## Next Steps (TDD Green Phase)
+
+After implementing the feature:
+
+1. Remove `test.skip()` from all test files
+2. Run tests: `npm test`
+3. Verify tests PASS (green phase)
+4. If any tests fail:
+   - Either fix implementation (feature bug)
+   - Or fix test (test bug)
+5. Commit passing tests
+
+## Implementation Guidance
+
+Feature endpoints to implement:
+{list endpoints from API tests}
+
+UI components to implement:
+{list UI flows from E2E tests}
+```
+
+**Save checklist:**
+
+```javascript
+fs.writeFileSync(`{test_artifacts}/atdd-checklist-{story-id}.md`, checklistContent, 'utf8');
+```
+
+---
+
+### 7. Calculate Summary Statistics
+
+**Aggregate test counts:**
+
+```javascript
+const resolvedMode = subagentContext?.execution?.resolvedMode; // Provided by Step 4's orchestration context
+const subagentExecutionLabel =
+  resolvedMode === 'sequential'
+    ? 'SEQUENTIAL (API → E2E)'
+    : resolvedMode === 'agent-team'
+      ? 'AGENT-TEAM (API + E2E)'
+      : resolvedMode === 'subagent'
+        ? 'SUBAGENT (API + E2E)'
+        : 'PARALLEL (API + E2E)';
+const performanceGainLabel =
+  resolvedMode === 'sequential'
+    ? 'baseline (no parallel speedup)'
+    : resolvedMode === 'agent-team' || resolvedMode === 'subagent'
+      ? '~50% faster than sequential'
+      : 'mode-dependent';
+
+const summary = {
+  tdd_phase: 'RED',
+  total_tests: apiTestsOutput.test_count + e2eTestsOutput.test_count,
+  api_tests: apiTestsOutput.test_count,
+  e2e_tests: e2eTestsOutput.test_count,
+  all_tests_skipped: true,
+  expected_to_fail: true,
+  fixtures_created: uniqueFixtures.length,
+  acceptance_criteria_covered: [
+    ...apiTestsOutput.tests.flatMap((t) => t.acceptance_criteria_covered),
+    ...e2eTestsOutput.tests.flatMap((t) => t.acceptance_criteria_covered),
+  ],
+  knowledge_fragments_used: [...apiTestsOutput.knowledge_fragments_used, ...e2eTestsOutput.knowledge_fragments_used],
+  subagent_execution: subagentExecutionLabel,
+  performance_gain: performanceGainLabel,
+};
+```
+
+**Store summary for Step 5:**
+
+```javascript
+fs.writeFileSync('/tmp/tea-atdd-summary-{{timestamp}}.json', JSON.stringify(summary, null, 2), 'utf8');
+```
+
+---
+
+## OUTPUT SUMMARY
+
+Display to user:
+
+```
+✅ ATDD Test Generation Complete (TDD RED PHASE)
+
+🔴 TDD Red Phase: Failing Tests 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
+
+✅ Acceptance Criteria Coverage:
+{list all covered criteria}
+
+🚀 Performance: {performance_gain}
+
+📂 Generated Files:
+- 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
+
+📝 Next Steps:
+1. Implement the feature
+2. Remove test.skip() from tests
+3. Run tests → verify PASS (green phase)
+4. Commit passing tests
+
+✅ Ready for validation (Step 5 - verify tests fail as expected)
+```
+
+---
+
+## EXIT CONDITION
+
+Proceed to Step 5 when:
+
+- ✅ All test files written to disk (API + E2E)
+- ✅ All tests verified to have test.skip()
+- ✅ All fixtures created
+- ✅ ATDD checklist generated
+- ✅ Summary statistics calculated and saved
+- ✅ Output displayed to user
+
+---
+
+### 8. Save Progress
+
+**Save this step's accumulated work to `{outputFile}`.**
+
+- **If `{outputFile}` does not exist** (first save), create it with YAML frontmatter:
+
+  ```yaml
+  ---
+  stepsCompleted: ['step-04c-aggregate']
+  lastStep: 'step-04c-aggregate'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-04c-aggregate'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-04c-aggregate'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section.
+
+Load next step: `{nextStepFile}`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Both subagents succeeded
+- All tests have test.skip() (TDD red phase compliant)
+- All tests assert expected behavior (not placeholders)
+- All test files written to disk
+- ATDD checklist generated
+
+### ❌ SYSTEM FAILURE:
+
+- One or both subagents failed
+- Tests missing test.skip() (would break CI)
+- Tests have placeholder assertions
+- Test files not written to disk
+- ATDD checklist missing
+
+**Master Rule:** TDD RED PHASE requires ALL tests to use test.skip() and assert expected behavior.

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

@@ -0,0 +1,106 @@
+---
+name: 'step-05-validate-and-complete'
+description: 'Validate ATDD outputs and summarize'
+outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+---
+
+# Step 5: Validate & Complete
+
+## STEP GOAL
+
+Validate ATDD outputs and provide a completion summary.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Validate against the checklist
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, loaded artifacts, and knowledge fragments
+- Focus: this step's goal only
+- Limits: do not execute future steps
+- Dependencies: prior steps' outputs (if any)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+## 1. Validation
+
+Use `checklist.md` to validate:
+
+- Prerequisites satisfied
+- Test files created correctly
+- Checklist matches acceptance criteria
+- Tests are designed to fail before implementation
+- [ ] CLI sessions cleaned up (no orphaned browsers)
+- [ ] Temp artifacts stored in `{test_artifacts}/` not random locations
+
+Fix any gaps before completion.
+
+---
+
+## 2. Polish Output
+
+Before finalizing, review the complete output document for quality:
+
+1. **Remove duplication**: Progressive-append workflow may have created repeated sections — consolidate
+2. **Verify consistency**: Ensure terminology, risk scores, and references are consistent throughout
+3. **Check completeness**: All template sections should be populated or explicitly marked N/A
+4. **Format cleanup**: Ensure markdown formatting is clean (tables aligned, headers consistent, no orphaned references)
+
+---
+
+## 3. Completion Summary
+
+Report:
+
+- Test files created
+- Checklist output path
+- Key risks or assumptions
+- Next recommended workflow (e.g., implementation or `automate`)
+
+---
+
+## 4. Save Progress
+
+**Save this step's accumulated work to `{outputFile}`.**
+
+- **If `{outputFile}` does not exist** (first save), create it with YAML frontmatter:
+
+  ```yaml
+  ---
+  stepsCompleted: ['step-05-validate-and-complete']
+  lastStep: 'step-05-validate-and-complete'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-05-validate-and-complete'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-05-validate-and-complete'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Step completed in full with required outputs
+
+### ❌ SYSTEM FAILURE:
+
+- Skipped sequence steps or missing outputs
+  **Master Rule:** Skipping steps is FORBIDDEN.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/steps-e/step-01-assess.md

@@ -0,0 +1,65 @@
+---
+name: 'step-01-assess'
+description: 'Load an existing output for editing'
+nextStepFile: './step-02-apply-edit.md'
+---
+
+# Step 1: Assess Edit Target
+
+## STEP GOAL:
+
+Identify which output should be edited and load it.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the Master Test Architect
+
+### Step-Specific Rules:
+
+- 🎯 Ask the user which output file to edit
+- 🚫 Do not edit until target is confirmed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+
+## CONTEXT BOUNDARIES:
+
+- Available context: existing outputs
+- Focus: select edit target
+- Limits: no edits yet
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Identify Target
+
+Ask the user to provide the output file path or select from known outputs.
+
+### 2. Load Target
+
+Read the provided output file in full.
+
+### 3. Confirm
+
+Confirm the target and proceed to edit.
+
+Load next step: `{nextStepFile}`
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Target identified and loaded
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without a confirmed target

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/steps-e/step-02-apply-edit.md

@@ -0,0 +1,60 @@
+---
+name: 'step-02-apply-edit'
+description: 'Apply edits to the selected output'
+---
+
+# Step 2: Apply Edits
+
+## STEP GOAL:
+
+Apply the requested edits to the selected output and confirm changes.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the Master Test Architect
+
+### Step-Specific Rules:
+
+- 🎯 Only apply edits explicitly requested by the user
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+
+## CONTEXT BOUNDARIES:
+
+- Available context: selected output and user changes
+- Focus: apply edits only
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Confirm Requested Changes
+
+Restate what will be changed and confirm.
+
+### 2. Apply Changes
+
+Update the output file accordingly.
+
+### 3. Report
+
+Summarize the edits applied.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Changes applied and confirmed
+
+### ❌ SYSTEM FAILURE:
+
+- Unconfirmed edits or missing update

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/steps-v/step-01-validate.md

@@ -0,0 +1,67 @@
+---
+name: 'step-01-validate'
+description: 'Validate workflow outputs against checklist'
+outputFile: '{test_artifacts}/atdd-validation-report.md'
+validationChecklist: '../checklist.md'
+---
+
+# Step 1: Validate Outputs
+
+## STEP GOAL:
+
+Validate outputs using the workflow checklist and record findings.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the Master Test Architect
+
+### Step-Specific Rules:
+
+- 🎯 Validate against `{validationChecklist}`
+- 🚫 Do not skip checks
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Write findings to `{outputFile}`
+
+## CONTEXT BOUNDARIES:
+
+- Available context: workflow outputs and checklist
+- Focus: validation only
+- Limits: do not modify outputs in this step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Load Checklist
+
+Read `{validationChecklist}` and list all criteria.
+
+### 2. Validate Outputs
+
+Evaluate outputs against each checklist item.
+
+### 3. Write Report
+
+Write a validation report to `{outputFile}` with PASS/WARN/FAIL per section.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Validation report written
+- All checklist items evaluated
+
+### ❌ SYSTEM FAILURE:
+
+- Skipped checklist items
+- No report produced